Policies

One of the unique features of THCNET is the ability to define and set policies. A policy is a way of evaluating a complex set of conditions, and set variables accordingly.

An example of a policy is to set a template if a certain browser type is detected. You can go a step further and only set the template if a user is trying to use a particular template, and a browser was detected, such as if they were trying to use a template that was known not to display correctly in Internet Explorer, you could set the template to an IE friendly version.

Of course you are not limited to browser detection. In fact you can check and set any number of variables, in sets of rules with multiple match and set statements. Because of this, policies can be quite powerful, but if used incorrectly, can be rather dangerous. Policies don't limit you from doing something like setting everyone's access level to 255 or 0.

You have the ability to set the system_policy_map configuration variable which is applied just before the template determination takes place. Because all other policies you apply take place after this step, if you want to define a policy to change the template set to be displayed, you need to define that here.

Note that since setting the system_policy_map can potentially be system disabling, in the event of a poorly written policy, you can override this if you have sysop level access. Just append ?policy=disable or &policy=disable to the URL.

How Policies Operate

Policies are a series of rules, with various match and set conditions for each rule.

Rules are processed in numeric order. First the match conditions are evaluated for the rule. If all the match statements are true, then the rule passes, and the set statements are applied.

If one or more of the match statements are false, the rule fails, and the next rule is evaluated. The exception to this is if you have the deny option set, a failed match counts as as a pass. Rules with the deny option do not process set statements, even though you are allowed to define them.

If the continue option is set, it will continue to the next rule.

A rule with no match statements will default to pass.

Set statements are not required.

If the log option is set, the policy, rule number, and result will be logged. Comments are just comments. Make as many as you like.

Policies end with an implicit fail rule in which no action is taken.

Policies will return a true or false depending on how they exit. This lets you policies to give you even greater control over how template macros are displayed.

For those of you familiar with Cisco route-maps, this will seem strangely familiar. The only difference is I'm giving you a spiffy web interface to build it.

Policy Definition

Policies are defined using the Policy Definition tab under the Admin section.

   ___ = hidden field
  [___] = text field
  [_]v] = drop box
  [x]   = check box
  (*)   = radio button
  [   ] = submit button
  {   } = dynamic field, error messages, notes, etc...
   ---  = link


  [_policy_name_______________]             { save needed }          -x-

  [_10___]                                                           -x-

    comment     [_comment_________________________________________]  -x-
    match       [_$variable1____] [ ==  ]v] [_value_______________]  -x-
    match       [_$variable2____] [ !=  ]v] [_value b_____________]  -x-
    set         [_$variable3____]           [_value b_____________]  -x-
    log                                                              -x-
    [ type  ]v]

  [_20___]                                                           -x-

    match       [_$variable1____] [ ==  ]v] [_value_______________]  -x-
    set         [_$variable3____]           [_value b_____________]  -x-
    set         [_$variable4____]           [_value c_____________]  -x-
    [ type  ]v]

  [ add rule ]
  [  update  ][  revert  ][ duplicate ]

  ---------------------------------------------------------------------
  [ new policy ]

To define a policy, click on "new policy". This will create a new blank policy in the policy workspace.

Set the policy name. Policy names are case sensitive and may only contain alpha-numeric characters, underscores, and dashes. No spaces or other punctuation is allowed in the policy name.

Click on "add rule". While you can use any rule number, the system will automatically increment rule numbers by ten to make it easy to insert rules if needed.

Select the item type you want to add to the rule. Items may be comments, match statements, set statements, or options.

Using Policies

Policies can be used in three different ways. A policy is only used if it is applied somewhere. So you can work on a copy of a policy without worrying about affecting your system should you make a mistake while editing.

System Policy Map

The first place a policy can be defined is the system_policy_map configuration variable. This is located under the Access section on the Admin tab of the Admin page.

Note that since setting the system_policy_map can potentially be system disabling, in the event of a poorly written policy, you can override this if you have sysop level access. Just append ?policy=disable or &policy=disable to the URL.

Policy Macro

You can apply a policy using the policy macro. The policy macro does not display anything, but is there as a method of simple way of applying a policy when your template files are displayed. The syntax of the policy macro is as follows:

  %%policy,"policy_name"%%

Policy Macro Switch

You can also use a policy as a macro switch to be used in evaluating if a macro or block of text should be displayed or not. If a all the match statements for a policy rule pass, the policy will return a true. If none of the rules pass, or a rule with a deny statement passes, then the policy returns false.

A policy macro switch can be specified using the following syntax:

%%macro,ppolicy_name%%

Of course this can be combined with other macro switches, prefixed with the NOT "!" and OR "|" conditions, as you can with all other macro switches.

Note that even though other macro switches may fail and cause an item not to be displayed, the policy is evaluated and set statements are applied as normal with policies.

A Final Note On Policy Use

When setting things in policies, be sure to keep in mind the potential issues which could arise by incorrectly setting variables, which are best not adjusted. For example variables in the user object have the potential to get saved, if the policy is say defined when the userinfo is displayed.

Another thing to note is that policies are often processed multiple times when being displayed in templates. This is due to the way block macros are evaluated. Because of this you should be especially careful when using set statements within policies which are called from template files.