test

Oracle Waveset 8.1.1 Deployment Reference

Developing New Rules and Rule Libraries

This section describes how to develop rules for your deployment, and provides the following information:

Note –

Best Practice:

When designing a rule, try to maximize the ease with which a less-experienced user could further customize the rule using the Identity Manager IDE.

A complex rule, with well chosen rule arguments, can be extensively customized by changing default values, without ever having to expose XPRESS or JavaScript to the user.

Understanding Rule Syntax

Waveset rules are typically written in XML and encapsulated in the <Rule> element.

This section covers the following topics:

Using the <Rule> Element

Using the <Rule> Element shows the use of the <Rule> element to define a basic rule expression. The name property identifies the name of the rule. The rule is written in XPRESS.

Example 4–8 Using the <Rule> Element to Define a Basic Rule Expression


<Rule name=’getApprover’> 
   <cond>
      <eq>
         <ref>department></ref>
         <s>sales</s>
      </eq> 
      <s>Sales Manager</s> 
      <s>HR Manager</s> 
   </cond> 
</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’>.

Returning Static Values

If the rule returns a static value, you can write it using XML Object syntax. The following example returns a list of strings.

Example 4–9 Returning a List of Strings


<Rule name=’UnixHostList’> 
   <List> 
      <String>aas</String> 
      <String>ablox</String> 
      <String>aboupdt</String> 
   </List> 
</Rule>

For more information about XML Object syntax, see the “XML Object Language” chapter in Deployment Reference.

Referencing Variables

You can use <ref> expressions in a rule to reference the values of external variables. The context in which the rule is used determines the names of the available variables.

In the following example, the form uses a rule to calculate an email address. The form defines the global.firstname and global.lastname fields, and the rule references those fields. The email address is calculated by concatenating the first letter of global.firstname with global.lastname and the @example.com string.

Example 4–10 Calculating an Email Address


<Rule name=’Build Email’> 
   <concat> 
      <substr> 
         <ref>global.firstname</ref> 
         <i>0</i> 
         <i>1</i> 
      </substr> 
      <ref>global.lastname</ref> 
      <s>@example.com</s> 
   </concat> 
</Rule>

The next example shows how a workflow uses a rule to test whether a transition to a particular activity should be taken. This workflow defines a user variable that contains the User view. The rule returns true if any simulated resources are assigned to this user or returns null if no simulated resources are assigned. The workflow engine interprets null as false and would consequently not take the transition.

Example 4–11 Testing a Transition


<Rule name=’Has Simulated Resources’> 
   <notnull> 
      <ref>user.accountInfo.types[simulated].accounts</ref> 
   </notnull> 
</Rule>

Declaring a Rule with Arguments

Best Practice:

You are not required to declare arguments for a rule, but it is considered a best practice to do so. If a rule uses a variable that is “in scope” at the time of the rule’s execution, then the rule becomes less reusable.

Declaring arguments in a rule provides documentation to rule users, allows reference validation in the Identity Manager IDE, and allows the rule to be used in forms and workflows that might not use the same naming convention.

You can use the <RuleArgument> element to declare rule arguments, and set a default value for the argument by specifying a value after the argument name. For example, the following rule specifies “Austin” as the default value for the location RuleArgument.

Example 4–12 Setting a Default Value


<Rule name=’description’> 
   <RuleArgument name=’UserId’/> 
   <RuleArgument name=’location’ value=’Austin’/> 
   <concat> 
      <ref>UserId</ref> 
      <s>@</s> 
      <ref>location</ref> 
   </concat> 
</Rule>

You can use this rule in user forms, but UserId and location are not attributes of the User view. You must use the <argument> element in the rule call to pass the expected arguments into the rule. Note that passing an argument whose name is location overrides the default value declared in the RuleArgument element in the rule definition.

Example 4–13 Overriding a Default Value Declared in RuleArgument


<rule name=’description’> 
   <argument name=’UserId’ value=’$(waveset.accountId)’/> 
   <argument name=’location’ value=’global.location’/> 
</rule>

For more information about calling rules, see Referencing Rules.

There is no formal way to declare an argument type, but you can specify type in a comment field. Use the <Comment> element to include comments in your rule:

Example 4–14 Using <Comment> to Include Comments in a Rule


<Comments> Description rule is expecting 2 arguments. 
A string value UserId, which is the e employees’ ID number, and a 
string value location that describes the building 
location for the employee </Comments>

If you are using the Identity Manager IDE to edit rules, you might find it helpful to formally define a list of rule arguments. This list would consist of the names of variables that are expected to be available to the rule. You can use them afterwards to perform validation in the Identity Manager IDE.

Rules with Side Effects

Rules typically return a single value, but in some cases you may want a rule to return several values or to take an action other than returning a value. You can use the following XPRESS expressions in a rule to assign values to external variables:

The following example shows how the rule tests the value of external variable named department and assigns values to two other variables.

Example 4–15 Testing the department Variable and Assigning Other Variables


<Rule name=’Check Department’> 
   <switch> 
      <ref>global.department</ref> 
      <case> 
         <s>Engineering</s> 
         <block> 
            <setvar name=’global.location’> 
               <s>Building 1</s> 
            </setvar> 
            <setvar name=’global.mailServer’> 
               <s>mailserver.somecompany.com</s> 
            </setvar> 
         </block> 
      </case> 
      <case> 
         <s>Marketing</s> 
         <block> 
            <setvar name=’global.location’> 
               <s>Building 2</s> 
            </setvar> 
            <setvar name=’global.mailServer’> 
               <s>mailserver2.somecompany.com</s> 
            </setvar> 
         </block> 
      </case> 
   </switch> 
</Rule>

In the preceding example, the variables global.location and global.mailServer are both set according to the value of the variable department. In this case, the return value of the rule is ignored, and the rule is called only for its side effects.

Writing Rules in JavaScript

When rules become complex, you might find it more convenient to write those rules in JavaScript rather than XPRESS, and then wrap the JavaScript in an XPRESS <script> element.

The following example references the values of form and workflow variables, calls the env.get function, and passes the variable name. The example uses the env.put function to assign variable names, and the value of the last statement in the script becomes the value of the rule. The rule returns the value in the email variable.

Example 4–16 Wrapping JavaScript in a <script> Element


<Rule name=’Build Email’> 
   <script> var firstname = env.get(’firstname’); var lastname = env.get(’lastname’); 
var email = firstname.substring(0, 1) + lastname + "@example.com"; email; </script> 
</Rule>

You can call other rules with the env.call function.