Sun Identity Manager Deployment Reference

Referencing Rules

This section provides information about referencing rules. The information is organized as follows:

Basic Rule Call Syntax

Rules can be called from anywhere XPRESS is allowed, which includes forms, workflows, or even another rule.

Use the XPRESS <rule> expression to call a rule. For example:

<rule name=’Build Email’/>

When the XPRESS interpreter evaluates this expression, the interpreter assumes the value of the name attribute is the name of a rule object in the repository. The interpreter automatically loads the rule from the repository and evaluates that rule. The value returned by the rule becomes the result of the <rule> expression.

In the previous example, no arguments are passed explicitly to the rule. The next example uses an argument element to pass an accountId argument to the rule. In addition, the argument value is passed as a static string, jsmith.

<rule name=’getEmployeeId’>
    <argument name=’accountId’ value=’jsmith’/>
 </rule>

You can also use an expression to calculate the value of an argument, as follows. In this example, the argument value is calculated by evaluating a simple <ref> expression that returns the value of the view attribute user.waveset.accountId.

<rule name=’getEmployeeId’>
    <argument name=’accountId’>
       <ref>user.waveset.accountId</ref>
    </argument>
</rule>

Because calculating argument values by referencing attributes is so common, an alternate syntax is also provided.

<rule name=’getEmployeeId’>
    <argument name=’accountId’ value=’$(user.waveset.accountId)’/>
 </rule>

Both of the previous examples pass the value of the user.waveset.account view attribute as the value of the argument.

Invoking Rules in a Library

You reference rules in a library using an XPRESS <rule> expression. The value of the name attribute is formed by combining the name of the configuration object containing the library, followed by a colon, followed by the name of a rule within the library. Therefore, each rule name in a library must be unique.

For example, the following expression calls the rule named First Dot Last contained in a library named Account ID Rules:

<rule name=’Account ID Rules:First Dot Last’/>

Resolving Rule Arguments

Most rules contain XPRESS <ref> expressions or JavaScript env.get calls to retrieve variable values. Several options are available for controlling how the values of these variables are obtained.

In the simplest case, the application calling the rule attempts to resolve all references.

For rules called from forms, the form processor assumes all references are to attributes in a view.
For rules called from workflows, the workflow processor assumes all references are to workflow variables.
Rules can call other rules by dynamically resolving the called rule’s name. You can use the optional <RuleArgument> element, which is described in Declaring a Rule with Arguments.

This section provides the following information:

Calling Scope or Explicit Arguments in Forms

This section provides examples that illustrate how rule arguments are resolved in forms.

The following example shows how to add a rule to a form. You can use this form with the User view because there are attribute names in the view.

<Rule name=’generateEmail’>
   <concat>
      <ref>global.firstname</ref>
      <s>.</s>
      <ref>global.lastname</ref>
      <s>@example.com</s>
   </concat>
</Rule>

This rule references two variables:

global.firstname
global.lastname

You can call this rule in a Field, as shown in the following example:

Example 4–17 Calling the Rule in a Field

<Field name=’global.email’> 
   <Expansion> 
      <rule name=’generateEmail’/> 
   </Expansion> 
</Field>

This method can be a convenient way to write simple rules that are used in user forms only— similar to the concept of global variables in a programming language. But there are two problems with this style of rule design. First, it is unclear to the form designer which variables the rule will be referencing. Second, the rule can be called only from user forms because it references attributes of the User view. The rule cannot be called from most workflows because workflows usually do not define variables named global.firstname and global.lastname.

You can address these problems by passing rule arguments explicitly, and by writing the rule to use names that are not dependent on any particular view.

The following example shows a modified version of the rule that references the variables firstname and lastname:

Example 4–18 Rule Referencing firstname and lastname Variables

<Rule name=’generateEmail’> 
   <RuleArgument name=’firstname’/> 
   <RuleArgument name=’lastname’/> 
   <concat> 
      <ref>firstname</ref> 
      <s>.</s> 
      <ref>lastname</ref> 
      <s>@example.com</s> 
   </concat> 
</Rule>

The following examples shows a rule that is simpler and more general. The example does not assume that the rule will be called from a user form, but that the rule must be called with explicit arguments.

Example 4–19 Calling the Rule with Explicit Arguments

<Field name=’global.email’> 
   <Expansion> 
      <rule name=’generateEmail’> 
         <argument name=’firstname’ value=’$(global.firstname)’/> 
         <argument name=’lastname’ value=’$(global.lastname)’/> 
      </rule> 
   </Expansion> 
</Field>

The name attribute of the argument elements correspond to the variables referenced in the rule. The values for these arguments are assigned to values of global attributes in the User view, which keeps the rule isolated from the naming conventions used by the calling application and makes the rule usable in other contexts.

Using the LocalScope Option in Workflows

Even when arguments are passed explicitly to a rule, the system by default allows references to other variables that are not passed as explicit arguments. The following example shows a workflow action calling the rule but passing only one argument:

Example 4–20 Workflow Action Calling the Rule and Passing a Single Argument

<Action> 
   <expression> 
      <setvar name=’email’> 
         <rule name=’generateEmail’> 
            <argument name=’firstname’ value=’$(employeeFirstname)’/> 
         </rule> 
      </setvar> 
   </expression> 
</Action>

When the rule is evaluated, the workflow processor is asked to supply a value for the variable lastname. Even if there is a workflow variable with this name, it may not have been intended to be used with this rule. To prevent unintended variable references, rules should be defined with the localScope option.

You enable this option by setting the localScope attribute to true in the Rule element:

Example 4–21 Setting localScope Attribute to true in a Rule Element

<Rule name=’generateEmail’ localScope=’true’> 
   <concat> 
      <ref>firstname</ref> 
      <s>.</s> 
      <ref>lastname</ref> 
      <s>@example.com</s> 
   </concat> 
</Rule>

By setting this option, the rule is only allowed to reference values that were passed explicitly as arguments in the call. When called from the previous workflow action example, the reference to the lastname variable would return null.

Rules intended for general use in a variety of contexts must use the localScope option.

Using Rule Argument Declarations

Best Practice:

You are not required to include explicit declarations for all arguments that can be referenced by a rule within the rule definition, but it is considered a best practice to do so.

Using argument declarations offers the following advantages:

Declarations can serve as documentation for the caller of the rule
Declarations can define default values
Declarations can enable the Identity Manager IDE to check for misspelled references within the rule
Declarations can enable the Identity Manager IDE to simplify the configuration of a rule call

For example, you could rewrite the generateEmail rule as follows:

Example 4–22 Rewriting the generateEmail Rule

<Rule name=’generateEmail’ localScope=’true’> 
   <RuleArgument name=’firstname’> 
      <Comments>The first name of a user</Comments> 
   </RuleArgument> 
   <RuleArgument name=’lastname’> 
      <Comments>The last name of a user</Comments> 
   </RuleArgument> 
   <RuleArgument name=’domain’ value=’example.com’> 
      <Comments>The corporate domain name</Comments> 
   </RuleArgument> 
   <concat> 
      <ref>firstname</ref> 
      <s>.</s> 
      <ref>lastname</ref> 
      <s>@</s> 
      <ref>domain</ref> 
   </concat> 
</Rule>

The Comments element can contain any amount of text that might be useful to someone examining the rule.

In this example, the rule was modified to define another argument named domain, which was given a default value of example.com. This rule uses the default value unless the caller passes an explicit argument named domain.

The next example shows a call that produces the john.smith@example.com string:

Example 4–23 Producing john.smith@example.com String

<rule name=’generateEmail’> 
   <argument name=’firstname’ value=’john’/> 
   <argument name=’lastname’ value=’smith’/> 
</rule>

The next example shows a call that produces the john.smith@yourcompany.com string:

Example 4–24 Producing john.smith@yourcompany.com String

<rule name=’generateEmail’> 
   <argument name=’firstname’ value=’john’/> 
   <argument name=’lastname’ value=’smith’/> 
   <argument name=’domain’ value=’yourcompany.com’/> 
</rule>

This example shows a call that produces the john.smith@ string:

Example 4–25 Producing john.smith@ String

<rule name=’generateEmail’> 
   <argument name=’firstname’ value=’john’/> 
   <argument name=’lastname’ value=’smith’/> 
   <argument name=’domain’/> 
</rule>

In the previous example, a null value is passed for the domain argument, but the default value is not used. If you specify an explicit argument in the call, that value is used even if it is null.

Using Locked Arguments

Declaring arguments with default values can be a useful technique for simplifying the development and customization of rules. If you have a constant value in a rule that might occasionally change, it is easier to locate and change that value if it is defined in an argument rather than embedded deep within a rule expression.

The Identity Manager IDE provides a simplified user interface for configuring rules. You can change the default values of arguments in the Identity Manager IDE, which is much easier than editing the entire rule expression.

After an argument is declared, it is possible for the caller of the rule to override the default value by passing an explicit argument. However, if you do not want the caller to have any control over the argument value, include a locked attribute with a value of true in the RuleArgument element to lock the argument. For example,

Example 4–26 Locking an Argument

<Rule name=’generateEmail’ localScope=’true’> 
   <RuleArgument name=’firstname’> 
      <Comments>The first name of a user</Comments> 
   </RuleArgument> 
   <RuleArgument name=’lastname’> 
      <Comments>The last name of a user</Comments> 
   </RuleArgument> 
   <RuleArgument name=’domain’ value=’example.com’ locked=’true’> 
      <Comments>The corporate domain name</Comments> 
   </RuleArgument> 
   <concat> 
      <ref>firstname</ref> 
      <s>.</s> 
      <ref>lastname</ref> 
      <s>@</s> 
      <ref>domain</ref> 
   </concat> 
</Rule>

The domain argument is locked in this example, which means the argument value will always be example.com— even if the caller tries passing a value for the argument. If you are going to use this rule at a site where the domain name is not example.com, the administrator only has to edit the rule to change the argument value. The administrator does not have to understand or modify the rule expression.