Understanding Rules and Rule Libraries

This section provides the following information:

• What is a Rule?

• Why Use Rules?

• What is a Rule Library?

What is a Rule?

A rule is an object in the Waveset repository that contains a function written in the XPRESS, XML Object, or JavaScript languages. Within Waveset, rules provide a mechanism for storing and executing frequently used programming logic or static variables for reuse. Rules are semantically similar to a programming subroutine or function. A rule can take input parameters, execute some logic, and return a value to a caller.

You can pass arguments to a rule to control its behavior, and a rule can reference and modify variables maintained by a form or workflow.

Rules are primarily referenced within forms and workflows, but you can also reference rules in other user-data related areas, such as

• Roles: Use a role-assignment rule to dynamically assign owners and approvers to a role.

• Active Sync: Use Process or Correction rules to control what happens when an Active Sync-enabled adapter detects changes to a resource account.

• Reconciliation: Use special rule subtypes (such as confirmation and correlation rules) during reconciliation. These subtypes are described later in this chapter.

Because the XPRESS and XML Object languages are both written in XML, the XPRESS and XML Object code examples used in this chapter are similar.

For information about writing rules in JavaScript, see Writing Rules in JavaScript.

The following example shows how to use the <Rule> element to define a basic rule expression, in which the rule definition name is getApprover, the rule argument name is department, the argument’s default value is Tampa, and the rule body returns the Sales Manager or HR Manager string values.

Example 4–1 Example XML Rule

<Rule name=’getApprover’>
   <Comments> This rule determines the appropriate approver for a 
              particular department.</Comment> 
   <RuleArgument name=’department’/> 
   <RuleArgument name=’location’ value=’Tampa’/>
   <cond> 
      <eq><ref>department</ref><String>sales</String></eq>   
      <cond> 
         <eq><ref>location</ref><String>Tampa</String></eq> 
         <String>Tampa Sales Manager</String> 
         <String>Sales Manager</String> 
      </cond> 
      <String>HR Manager</String> 
   </cond> 
   <MemberObjectGroups> ObjectRef type=’ObjectGroup’ name=ExampleChoc’/> 
   </MemberObjectGroups> 
</Rule>

When defining a rule, use the <Rule> element with an uppercase R as in <Rule name=’rulename’>. When calling a rule, use the XPRESS <rule> element with lowercase r, as in <rule name=’rulename’>.

Why Use Rules?

You can call a rule wherever XPRESS is allowed— most notably in forms, Java code, and workflows. Rules allow you to encapsulate data, such as a fragment of logic or a static value, that can then be reused in many locations.

The benefits of organizing XPRESS logic or static values for reuse include:

• Easy maintenance. You can modify a rule by changing a single object instead of changing each form or workflow that references the rule. You can also more effectively manage

  • Frequently used and shared expressions

  • Frequently changing lists and business logic

  Distributed development. Users can develop rules that focus on rule requirements without having to be aware of all forms, Java code, roles, or workflows that reference that rule.

• Hiding complexity. More advanced developers can write rules with more complex logic while other users see only the interface without the underlying complexity.

You can secure rules to protect sensitive data, such as user credentials or personal information from being accessed by unauthorized administrators. For more information, see Securing Rules.

Using Rules in Forms

You typically call a rule in forms to calculate the value of a field or to control field visibility within a <Disable> expression. Within forms, rules could be the most efficient mechanism for storing and reusing:

• A list of corporate departments

• Default values

• A list of office buildings

When calling rules from forms, it is particularly important that you properly secure those rules. Imagine a rule used in a critical form, but the implementation of the rule could be modified by anyWaveset user! For information about securing rules, see Securing Rules.

The following example rule returns a list of job titles.

Example 4–2 Returning a Job Titles List

<Rule name=’Job Titles’> 
   <List> 
      <String>Sales</String> 
      <String>Accounting Manager</String> 
      <String>Customer Service Representative</String> 
   </List> 
</Rule>

Rules such as this are often used in Waveset forms to calculate lists of names for selection. To add or change a new job title, you only have to modify this rule instead of modifying each form that references the rule.

In the next example, the global.jobTitle field calls the Job Titles rule defined in Using Rules in Forms to use the job titles list in a select box:

This example uses a lowercase r in the rule element because you are calling a rule, not defining a rule.

Example 4–3 Using a Job Titles List in a Select Box

<Field name=’global.jobTitle’> 
   <Display class=’Select’> 
      <Property name=’title’ value=’Job Title’/> 
      <Property name=’allowedValues’> 
         <rule name=’Job Titles’/> 
      </Property> 
   </Display> 
</Field>

Waveset forms also support rules that dynamically calculate the name of another rule to call. The following example shows how a form field calls a rule that calculates a department code:

Example 4–4 Calling a Rule that Calculates a Department Code

<Field name=’DepartmentCode’> 
   <Display class=’Text’> 
      <Property name=’title’ value=’DepartmentCode’/> 
   </Display> 
   <Expansion> 
      <rule> 
         <cond> 
            <eq> 
               <ref>var1</ref> 
               <s>Admin</s> 
            </eq> 
            <s>AdminRule</s> <s>DefaultRule</s> 
         </cond> 
      </rule> 
   </Expansion> 
</Field>

Using Rules in Roles

In Waveset, a role is an object that allows you to efficiently group and assign resources to users. Roles have designated owners and approvers, where:

• Only role owners can authorize changes to the parameters that define the role.

• Only role approvers can authorize the assignment of end-users to the role.

You can directly assign role owners and approvers to a role or use a role-assignment rule to dynamically assign them to a role.

You can use a rule to set the value of any resource attribute in a role definition. When Waveset evaluates the rule, it can reference any attribute of the user view.

For more information about roles, see the Business Administrator's Guide.

The following example shows how to use a rule to set an attribute value for a particular resource. When you create a user and associate this rule with that user’s role, the rule automatically sets the description value.

Example 4–5 Setting the Value for a User’s Resource Description

<Rule name=’account description’> 
   <concat> 
      <string>Account for </string> 
      <ref>global.firstname</ref> 
      <string>.</string> 
      <ref>global.lastname</ref> 
   </concat> 
</Rule>

Using Rules in Workflows

In general terms, an Waveset workflow is a logical, repeatable process during which documents, information, or tasks are passed from one participant to another for action, according to a defined set of procedural rules. A participant is a person, machine, or both.

In workflow, you can use a rule anywhere you can use an expression. You can use rules in a workflow to:

• Calculate an approver

• Calculate the name of another rule

• Add a condition to a transition

• Implement an action

• Calculate an approval escalation timeout

For example, you can use a manual action to send an approval request to an administrator, specify a timeout value for this action. If the administrator does not respond within the specified time, you can terminate the action, and escalate the workflow approval to a different administrator.

Workflow activities can also contain subprocesses containing a rule that dynamically calculates a subprocess name. For example.

Example 4–6 Calculating a Rule Name Dynamically

<Activity id=’0’ name=’activity1’> 
   <Variable name=’ValueSetByRule’> 
      <rule> 
         <cond> 
            <eq>
               <ref>var2</ref>
               <s>specialCase</s>
            </eq> 
            <s>Rule2</s> 
            <s>Rule1</s> 
         </cond> 
         <argument name=’arg1’> <ref>variable</ref> </argument> 
      </rule> 
   </Variable> 
</Activity>

What is a Rule Library?

A rule library is an XML configuration object that is stored in the Waveset repository. The configuration object contains a library object, which in turn contains one or more rule objects.

Creating rule libraries is a convenient way to organize closely related rules into a single object. Add rules to a rule library when you want to provide a grouping of related functionality. Using libraries simplifies rule maintenance by reducing the number of objects in the Repository. Using libraries also makes it easier to identify and call useful rules when you are designing forms and workflows.

Instructions for invoking rules in a rule library are provided in Invoking Rules in a Library.

The following example shows a library containing two different account ID generation rules:

Example 4–7 Using a Rule Library with Two Account ID Generation Rules

<Configuration name=’Account ID Rules’> 
   <Extension> 
      <Library> 
         <Rule name=’First Initial Last’> 
            <expression> 
               <concat> 
                  <substr> 
                     <ref>firstname</ref> 
                     <i>0</i> 
                   <i>1</i> 
                  </substr> 
                     <ref>lastname</ref> 
               </concat> 
            </expression> 
         </Rule> 
         <Rule name=’First Dot Last’> 
            <expression> 
               <concat> 
                  <ref>firstname</ref> 
                  <s>.</s> 
                  <ref>lastname</ref> 
               </concat> 
            </expression> 
         </Rule> 
      </Library> 
   </Extension> 
</Configuration>

You can use the open source Identity Manager IDEto view and edit the default rule libraries or to add new rules to an existing library object. See https://identitymanageride.dev.java.netfor more information.