|
| |
| Sun Java System Identity Manager 6.0 Deployment Tools 2005Q4M3 | |
2
Working with Rules
This chapter introduces Identity Manager rules and rules libraries and describes how to use the Business Process Editor (BPE) to create, edit, and validate rules. Examples are provided that illustrate how to implement rules and rule libraries in forms, roles, and workflows.
This chapter is organized into the following sections:
Related Documentation
The Introduction to the Business Process Editor chapter in the Identity Manager Technical Deployment Overview introduces the Business Process Editor (BPE) and describes how to start the tool, set editor options, and save the edited processes.
Understanding Identity Manager RulesThis section covers the following introductory topics:
What is a Rule?
A rule is an object in the Identity Manager repository that contains a function written in the XPRESS, XML Object, or JavaScript languages. Within Identity Manager, rules provide a mechanism for storing frequently used logic or static variables for reuse within forms, workflows, and roles.
Arguments can be passed to a rule to control its behavior, and a rule can reference and modify variables maintained by the form or workflow.
Because simple rules are most commonly written in XML, the examples in this chapter will use the XPRESS or XML Object languages. For information about writing rules in JavaScript, see Rules Written in JavaScript.
Example Rule
In the following simple XML rule, the rule name is first defined in the <Rule> element by the name attribute, and it returns the string value john or mary. The rule body is an XPRESS expression within the <Rule> element.
<Rule name='getApprover'>
<cond><eq><ref>department></ref><s>sales</s></eq>
<s>john</s>
<s>mary</s>
</cond>
</Rule>
This discussion of rules assumes a knowledge of the XPRESS language. For information about XPRESS, see Sun Java™ System Identity Manager Workflows, Forms, and Views.
Why Use Rules?
You can call a rule wherever XPRESS is allowed, most notably in workflow and forms. Rules allow you to encapsulate a fragment of logic or a static value that can then be reused in many locations.
Saving XPRESS logic or static values for reuse provides these benefits:
- Ease of maintenance. Modifying a rule requires changing one object rather than all the forms or workflows that reference the rule.
- Distributed development. Rules can be developed by users that focus on rule requirements without needing to be aware of all the forms or workflows that may reference the rule.
- Hiding complexity. Less technical users can modify simple rules using interfaces that do not require knowledge of XML, workflows, or forms.
Using Rules in Forms
In forms, you would typically call a rule to calculate the allowedValues display property or within a <Disable> expression to control field visibility. Within forms, rules could be the most efficient mechanism for storage and reuse of:
It is particularly important that rules that are called from forms be properly secured. For information about how to secure rules, see Securing Rules.
Sample Scenario: Forms
The following rule returns a list of job titles. Rules such as this are often used in Identity Manager forms to calculate lists of names for selection. When a new Job Title is added or changed, you only need to modify this rule, not all of the forms that reference the rule.
<Rule name='Job Titles'>
<list>
<s>Sales</s>
<s>Accounting Manager</s>
<s>Customer Service Representative</s>
</list>
</Rule>
The following field calls the rule that is defined above to use the list of job titles 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>
Note The rule name element in the preceding code uses a lowercase r because it is used to call the rule, not define it.
Using Rules in Workflow
In workflow, you can use a rule to:
Sample Scenario: Workflow
The following manual action is used to send an approval request to an administrator. The action can have a timeout value. If the administrator does not respond within the specified time, the action terminates, and the workflow can escalate the approval to a different administrator.
In the following rule, the timeout is specified with a fixed value of 86,400 seconds or 24 hours.
<Rule name='Approval Timeout'>
<i>86400</i>
</Rule>
The following manual action calls the timeout rule:
<ManualAction>
<Owner name='$(approver)'/>
<Timeout>
<rule name='Approval Timeout'/>
</Timeout>
<FormRule>
<ref>approvalForm</ref>
</FormRule>
</ManualAction>
Using Rules in Roles
You can use rules to set the value of any resource attribute in a role definition. When the rule is evaluated, it can reference any attribute of the user view.
Sample Scenario: Roles
The following rule sets a value for the user's description for a resource, such as NT. When a user is created with a role that has this rule associated with it, the description value will automatically be set according to the rule.
<Rule name='account description'>
<concat>
<s>Account for </s>
<ref>global.firstname</ref>
<ref>global.lastname</ref>
<s>.</s>
</concat>
</Rule>
Dynamically Calculating the Name of the Rule
Identity Manager forms and workflow support rules that can dynamically calculate the name of another rule to call. The following example shows a form field that calls 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>
Workflow activities can also contain subprocesses that contain a rule that dynamically calculates the subprocess name:
<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>
Understanding How Rules WorkThis section describes:
For information about applying a rule to a role, see Identity Manager Administration for the roles discussion.
For information about adding a rule to an existing rule library, see Rule Libraries.
Design Tip: When designing a rule, try to maximize the ease with which a less experienced user could further customize the rule using the Business Process Editor. A complex rule with well chosen <RuleArgument>s can be extensively customized by changing default values without ever having to expose XPRESS or JavaScript to the user.
Understanding Rule Syntax
Rules are typically written in XML and encapsulated in the <Rule> element.
This section covers the following topics:
Using the <Rule> Element
The following example 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.
<Rule name='getApprover'>
<cond><eq><ref>department></ref><s>sales</s></eq>
<s>Sales Manager</s>
<s>HR Manager</s>
</cond>
</Rule>
Returning Fixed Values
If the rule returns a fixed value, you can write it using XML Object syntax.
This example returns a list of strings.
<Rule name='UnixHostList'>
<List>
<String>aas</String>
<String>ablox</String>
<String>aboupdt</String>
</List>
</Rule>
Note For more information about XML Object syntax, see the XML Object Language chapter in Sun Java™ System Identity Manager Workflows, Forms, and Views.
Referencing Variables
Rules are allowed to reference the value of external variables with a <ref> expression. The names of the available variables are determined by the context in which the rule is used. When used within forms, any form field, view attribute, or variable defined with <defvar> can be referenced. When used within workflow, any variable defined within the workflow process can be referenced.
In the following example, a form uses a rule to calculate an email address. The form defines the fields global.firstname and global.lastname, and the rule references them. The email address is calculated by concatenating the first letter of global.firstname with global.lastname and the string @waveset.com.
<Rule name='Build Email'>
<concat>
<substr> <ref>global.firstname</ref> <i>0</i> <i>1</i> </substr>
<ref>global.lastname</ref>
<s>@waveset.com</s>
</concat>
</Rule>
In the next example, a workflow uses a rule to test whether a transition to a particular activity should be taken. The workflow defines a variable named user that contains the User View. The rule returns true if this user has any NT resources assigned to them or null if no NT resources are assigned. The workflow engine interprets null as false and would consequently not take the transition.
<Rule name='Has NT Resources'>
<notnull>
<ref>user.accountInfo.types[NT].accounts</ref>
</notnull>
</Rule>
Declaring a Rule with Arguments
Though rules are not required to declare arguments, it is considered good practice to do so. Declaring arguments provides documentation to the rule author, allows reference validation in the Business Process Editor, and allows the rule to be used in forms and workflows that may not use the same naming convention.
To declare rule arguments, use the <RuleArgument> element. The argument can have a default value set by specifying a value after the argument name as shown in the following location argument.
<Rule name='description'>
<RuleArgument name='UserId'/>
<RuleArgument name='location' value='Austin'/>
<concat>
<ref>UserId</ref>
<s>@</s>
<ref>location</ref>
</concat>
</Rule>
Note When defining a rule, use the <Rule> element that has an uppercase R as in <Rule name='rulename'>. When calling a rule, the XPRESS <rule> element has a lowercase r, as in <rulename='rulename'>.
You can use this rule in a user form, but UserId and location are not attributes of the user view. To pass the expected arguments into the rule the <argument> element is used in the rule call. Note that passing an argument whose name is location will override the default value declared in the RuleArgument element.
<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 argument type, but you can specify type in a comment field. Use the <Comment> element to include comments in your rule:
<Comments>
Description rule is expecting 2 arguments. A string value
UserId, which is the employees’ ID number, and a string
value location that describes the building location for
the employee
</Comments>
Tip If you are using the Business Process Editor 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 Business Process Editor.
Rules with Side Effects
Rules typically return a single value, but in some cases you may want a rule to return several values. While a rule expression can return only a single value, a rule can assign values to external variables with the XPRESS <set> expression. In the following example, the rule tests the value of the external variable named department and assigns values to two other variables.
<Rule name='Check Department'>
<switch>
<ref>global.department</ref>
<case>
<s>Engineering</s>
<block>
<set name='global.location'>
<s>Building 1</s>
</set>
<set name='global.mailServer'>
<s>mailserver.somecompany.com</s>
</set>
</block>
</case>
<case>
<s>Marketing</s>
<block>
<set name='global.location'>
<s>Building 2</s>
</set>
<set name='global.mailServer'>
<s>mailserver2.somecompany.com</s>
</set>
</block>
</case>
</switch>
</Rule>
In the previous 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.
Rules Written in JavaScript
When rules become complex, you may find it more convenient to write rules in JavaScript rather than XPRESS. This can be accomplished by wrapping the JavaScript in a <script> element.
Example
<Rule name='Build Email'>
<script>
var firstname = env.get('firstname');
var lastname = env.get('lastname');
var email = firstname.substring(0, 1) + lastname + "@waveset.com";
email;
</script>
</Rule>
You reference the values of form and workflow variables by calling the env.get function and passing the name of the variable. You can assign variable names with the env.put function. The value of the last statement in the script becomes the value of the rule. In the preceding example, the value in the email variable will be returned by the rule.
You can call other rules with the env.call function.
Default Rules
Using the BPE, you can edit the default Identity Manager rules to follow a custom set of steps. Identity Manager ships with a library of default rules, which includes the following rules libraries and rules:
Naming Rules Library
Identity Manager ships a default library of naming rules, displayed in the BPE as the library object named NamingRules. This default library includes rules that you can use to control how names are displayed after rule processing.
AlphaNumeric Rules
Identity Manager ships a default library of alphanumeric rules, displayed in the BPE as the library object named Alpha Numeric Rules. This default library includes rules that you can use to control how numbers and letters are ordered and displayed in Identity Manager forms and workflows.
RegionalConstants Library
Identity Manager ships a default library of regional constants rules, displayed in the BPE as the library object named RegionalConstants Rules. This default library includes rules that you can use to control how the names of months, states, and provinces are displayed.
The Date Library rule library contains the Date Validation rule, which returns true if the passed-in string is a valid date. This rule takes one RuleArgument in the form mm/dd/yy. If the month or the day are passed in with single digits, it accounts for it approximately.
Active Sync Rules
When an Active Sync adapter detects a change to an account on a resource, it either maps the incoming attributes to an Identity Manager user, or it creates an Identity Manager user account.
Note Active Sync rules must use context, not display.session.
The following Active Sync rules are predefined.
Excluded Resource Accounts Rule Subtype
The ExcludedAccountRule subtype supports the exclusion of resource accounts from resource operations.
The rule has the following parameters:
The accountID parameter can be compared to one or more resource accounts that should be excluded from Identity Manager. In addition, the operation parameter can be used by the rule to have finer control of which resource accounts will be exempt from the actions specified by the operation parameter.
The operation argument can contain the following values:
If the operation parameter is not used within the rule, all accounts identified by the rule will be excluded from all the listed operations.
Sample Rules
The following rule exemplifies subtype use. It excludes specified resource accounts for UNIX adapters.
<Rule name='Excluded Resource Accounts' authType='ExcludedAccountsRule'>
<RuleArgument name='accountID'/>
<defvar name 'excludedList'>
<List>
<String>root</String>
<String>daemon</String>
<String>bin</String>
<String>sys</String>
<String>adm</String>
<String>uucp</String>
<String>nuucp</String>
<String>listen</String>
<String>lp</String>
</List>
</defvar>
<cond>
<eq>
<contains>
<ref>excludedList</ref>
<ref>accountID</ref>
</contains>
<i>1</i>
</eq>
<Boolean>true</Boolean>
<Boolean>false</Boolean>
</cond>
</Rule>
The following example rule illustrates the use of the operation parameter. It allows to the “Test User” resource account to be manipulated without any impact on Identity Manager if Active Sync is running against the resource.
<Rule name='Example Excluded Resource Accounts' authType='ExcludedAccountsRule'>
<!--
Exclude all operations on 'Administrator' account
Exclude activeSync events on 'Test User' account
-->
<RuleArgument name='accountID'/>
<RuleArgument name='operation'/>
<!-- List of IAPI Operations -->
<defvar name='iapiOperations'>
<List>
<String>iapi_create</String>
<String>iapi_update</String>
<String>iapi_delete</String>
</List>
</defvar>
<or>
<!-- Always ignore the administrator account. -->
<cond>
<eq>
<s>Administrator</s>
<ref>accountID</ref>
</eq>
<Boolean>true</Boolean>
<Boolean>false</Boolean>
</cond>
<!-- Ignore IAPI events for the 'Test User' account -->
<and>
<cond>
<eq>
<contains>
<ref>iapiOperations</ref>
<ref>operation</ref>
</contains>
<i>1</i>
</eq>
<Boolean>true</Boolean>
<Boolean>false</Boolean>
</cond>
<cond>
<eq>
<ref>accountID</ref>
<s>Test User</s>
</eq>
<Boolean>true</Boolean>
<Boolean>false</Boolean>
</cond>
</and>
</or>
</Rule>
Using the BPE to Create and Edit RulesThe Business Process Editor (BPE) application is a standalone, Swing-based Java application that provides a graphical and forms-based view of Identity Manager workflows, forms, rules, generic and configuration objects, and views. The BPE also enables you to display view attributes for reference while you customize rules.
Specifically you can use the BPE to
This section provides information and instructions for using the BPE to create and edit rules. The information is organized as follows:
Note Instructions for starting the BPE application are provided in Starting and Configuring the BPE.
Getting Around the BPE
Before you start customizing rules, you must understand the basics of navigating and using the BPE interface. When you are working with rules, the initial BPE interface consists of display panes, a menu bar, Action menus, and Rule dialogs.
Note The BPE interface changes based on the object type or process selection.
This section describes the interface related to creating and editing rules. The information is organized as follows:
BPE Display Panes
When you are working with rules, the BPE interface provides the following display panes:
Tree View
The tree view (in the left interface pane) lists selected rules as standalone icons.
Figure 1. Rule Display in Tree View
Typically, the tree view shows a hierarchical view of tasks, forms, or views — listing each element in order with sub-elements nested under their parent.
However, rules do not reside in hierarchies within Identity Manager (unless already incorporated into a rule library object, workflow, or form), so there are no hierarchical relationships among rules to display in tree view. Instead, rules that are not incorporated into a library, workflow, or form appear in tree view as single icons.
Rule Source
The Rule source pane (in the upper right interface pane) provides the source information of a rule.
Figure 2. Rule Source Pane
From this pane, you can right-click to access a cascading menu that enables you to perform any of the following tasks:
You can also use the buttons located above this pane to perform any of the following actions:
Input Tab
The Input tab pane (in the lower right corner) displays by default.
Figure 3. Input Tab Pane
You can use this tab to control the arguments that are passed to the rule for testing. This tab is basically the same as the BPE's GenericObject Editor (see Generic Objects).
From this pane, you can:
- Double-click the argument name, the Arguments dialog displays so you can Validate the argument.
- Right-click an argument name to access a cascading menu that enables you to import test data from a view or a file. Specifically, you can perform any of the following tasks:
- Click New to create new arguments by specifying a name, type, and value.
- Click Delete to delete a selected argument.
Result Tab
Select the Result tab and click Run (above the Rule source pane) to execute the selected rule. The rule’s return value displays in the Result tab pane in XML format.
Figure 4. Result Tab Pane
Trace Tab
Select the Trace tab to capture XPRESS tracing during execution of the rule.
Figure 5. Trace Tab Pane
Menu Selections
You can use the menu bar or the action (right-click) menu to work in the interface.
Select an item in the tree or diagram view, and then right-click to display the action menu selections that are available for that item.
Rule Dialogs
Each rule and rule element has an associated dialog that you can use to define the element type and its characteristics.
To access these dialogs, double-click the rule name in the tree view. The rule dialog for the selected rule displays, with the Main tab in front by default. For example, see the following figure:
Figure 6. Rule Dialog (Main tab view)
You use the options on this dialog to define a rule, as follows:
- Name — Automatically displays the selected rule name, which is the name displayed in the Identity Manager interface.
- Description (optional) — Specify text describing the purpose of the rule.
- Comments — Specify text inserted into the rule body with a <Comment> element.
- Arguments — Specify any required arguments.
Editing Rule Elements (Changing Field Value Type)
Some dialog fields behave differently depending on the field value type you selected.
Figure 7. Rule Argument Dialog
You can use one of the following methods to change a value type:
Changing Display Type
To change the way information displays in diagram view
- Right-click to display the action menu.
- Select Display > <view_type>.
The view types include:
- XML – Displays XPRESS or JavaScript source. You may prefer this display type if you are comfortable with XML.
Figure 8. XML Display
- Graphical – Displays a tree of expression nodes. This display type provides a structural overview.
To conserve space, the following graphic captures only part of the selected rule.
Figure 9. Graphical Display
- Property Sheet – Displays a list of properties. Some of these can be edited directly. Other properties may require launching another dialog. For efficiency, use this display type when creating new expressions. (You can enter expression arguments more rapidly in this view than in the graphical view.)
Figure 10. Property Sheet
- Configuration – Displays argument information listed in a property-sheet style. (See the following figure.) Also lists any comments that the rule creator used to describe the rule in the database.
Figure 11. Configuration Display
Browsing Rules
Use one of the following methods to browse and select the rules that you can access through Identity Manager:
- Select File > New Repository Object from the main menu bar. When the Select objects to edit dialog displays, expand the Rules node to display the available rules.
- Right-click in the Rule source pane and select New > Browse Rules from the actions menu.
When the Select Rule dialog opens (see the following figure), expand the Rules node to display the available rules.
Figure 12. Select Rule Dialog
Reviewing Rule Summary Details
Double-click a rule name in the tree pane to view, at a glance, rule elements. Tabs that display in the Rule dialog are:
Main Tab
Select this tab to access argument properties for this element (including each argument’s name and value). It also lets you re-order arguments for better visual organization. (Reordering in this list does not change interpretation of the rule.)
This tab displays the same information about the rule as the Main view of the Rule dialog (see the following figure).
Figure 13. Main Tab Display
Repository Tab
Note Rules that are not included in a Rule library have a Repository tab.
Select the Repository tab to view the following information about the selected rule.
Figure 14. Repository Tab Display
This tab primarily contains read-only information, but you can change the following values:
- Subtype: Select a new subtype assignment from the menu.
Rules have no subtype by default. Consequently; when you create a rule, the Subtype value defaults to None.
However, to display this rule in the Reconciliation interface, you must set this value to Account Correlation or Account Confirmation, depending upon which selection list in the Reconciliation graphical user interface you would like this rule to appear.
- Organization: Enter a new organization assignment into the text field.
- Authorization Type: Enter a new authorization type into the text field.
Note For an example rule subtype, see Excluded Resource Accounts Rule Subtype
XML Tab
Select the XML tab to view and edit raw XML for the selected rule. You can then click Validate to validate your changes before clicking OK to save. The XML parser validates the rule XML against the waveset.dtd.
Figure 15. XML Tab Display
Creating a New Rule
Use the following steps to create a new rule:
- Select File > New > Rule.
The Rule: New Rule dialog displays, with the Main tab in front by default.
Figure 16. New Rule Dialog
- Specify the following parameters for the new rule:
- Click New to add arguments to the new rule.
- When the Argument: Null dialog displays, enter text into the Name, Value, and Comments fields, and then click OK.
This text displays in the Arguments table and will be inserted into the rule as a <RuleArgument> element.
- When you are finished click OK to save your changes.
Notes:
Defining Rule Elements
The XML elements that comprise rules can be functions, XPRESS statements, one of several data types. You can use the following BPE Rule Element dialogs to create or edit rule elements:
- Argument dialog — Use to view or define argument characteristics.
- Element dialog — Use to view or define selected elements.
- Object Access dialog — Use to manipulate objects or call Java methods that manipulate objects.
- Diagnostics dialog — Use to debug or examine JavaScript, trace, print, and breakpoints.
Additional information about these dialogs is provided in the following sections.
Note For more information about rule structure, see Understanding Rule Syntax.
Argument Dialogs
You use an Argument dialog to access and define rule arguments.
Figure 17. Argument Dialog
Use one of the following methods to open an Argument dialog:
- From the Tree view pane, double-click a rule name to open the Rule dialog, and then double-click the argument name on the Main tab.
- From the Rule source pane (in Graphical View only), right-click and select
New > Rule > argument.- From the Rule source pane (in Graphical view only), double-click an argument node.
Figure 18. Double-Click an Argument Node
The Argument dialog provides the following basic options:
Note In addition to these options, the Argument dialog may also display other fields depending upon the type of element you are viewing/editing.
For example, if you are viewing a method element, an Argument dialog similar to the one displayed for the Query method dialog opens:
Figure 19. Argument Popup Dialog (Method)
You can change the argument’s data type by clicking the Change Type button, which displays the Select Type dialog.
Figure 20. Select Type Dialog
Valid argument types are listed in the following table.
Element Dialogs
The Element dialog displays the name and value of an argument.
Figure 21. Element Popup for the address Variable
Use one of the following methods to display an Element dialog from the Rule source pane (in Graphical view only):
You can define an element to be one of the several types as listed in the table in Creating a New Element. To change the data type of the element, click the Change Type button. The Select Type popup opens, displaying a list of the data types you can assign to the selected rule element.
To create a new element, right-click in the Graphical view and select
New > <element_type> from the menu. The element types listed on this menu represent categories of XPRESS functions. (See the following table for a description of these element types.)
Note For more information about these functions, see Sun Java™ System Identity Manager Workflows, Forms, and Views.
You can also access the element types most recently created in a BPE session through the Recent options of the actions menu.
The following figure shows the window that displays when you select New > Strings > concat.
Figure 22. concat Dialog
Object Access Dialogs
Right-click in the graphical display, and select New > Other > Object Access > option.
Note See Object Access Dialogs for a discussion of the object access options.
Use to manipulate objects or call Java methods that manipulate objects. Right-click to access the action menu, and select New > Other > Object Access > option, where option can be one of the options described in the following table:
To create an object, right-click to access the action menu, and select New > Other > Object Access > new.
Figure 23. new Dialog
Editing Element Details
From the Argument dialog, you can define values for the variable. Use the Value field to enter a simple string value as the initial variable value. Alternatively, you can select a value type (such as Expression or Rule), and then click Edit to enter values.
The following graphic shows the variable window for a ref statement.
Figure 24. ref Dialog
To identifying argument types (simple or complex), select Simple when you can enter the argument value in a text field (for example, string, Boolean, or integer). If you are working with a List, XML Object, or other expressions that requires an additional popup, select Calculated.
Diagnostics Dialogs
You can use Diagnostics dialogs to debug or examine the following:
You access the Diagnostics dialog by selecting New > Other > Diagnostics > trace from the actions menu in the right pane.
Editing a RuleIf you customize a rule, you must save and validate your changes to ensure that the rule completes correctly and as expected. After saving, import the modified rule for use in Identity Manager.
Loading a Rule
Use the following steps to load a rule in the BPE:
- Select File > Open Repository Object from the menu bar.
- If prompted, enter the Identity Manager Configurator name and password in the displayed login dialog, and then click Login.
The following items display:
- Expand the Rule node to view all existing rules.
- Select the rule you want to load, and then click OK.
Note If you are loading a rule for the first time, the rule components displayed in the right pane may not display correctly. Right-click in the right pane, and then select Layout to re-display the diagram.
Saving Changes
To save changes to a rule and check it into the repository, select File > Save in Repository from the menu bar.
Note You can also use File > Save As File to save the rule as an XML text file. Save the file in the form Filename.xml.
Validating Changes
You can validate changes to rules at different stages of the customization process:
- From the Rule source pane, click the Validate button to validate the rule with the current set of arguments.
- If you are working with XML display values, when adding or customizing arguments, click Validate to validate each change to the rule.
- After making changes, select the rule in the tree view, and then select Tools > Validate to test it.
The BPE displays validation messages that indicate the status of the rule:
Rule LibrariesA rule library serves as a convenient way to organize closely related rules into a single object in the Identity Manager repository. Using libraries can ease rule maintenance by reducing the number of objects in the repository and making it easier for form and workflow designers to identify and call useful rules.
A rule library is defined as an XML Configuration object. The Configuration object contains a Library object, which in turn contains one or more Rule objects. The following example shows a library containing two different 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 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.
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'/>
Selecting a Library to View or Customize
Perform the following steps to select a rule library to view or edit:
You can now edit the rule library XML.
Adding a Rule to an Existing Library Object
Once a rule library has been checked out, you can add a new rule by inserting the <Rule> element somewhere within the <Library> element. The position of the Rule within the library is not significant.
Referencing RulesThis section covers:
Basic Rule Call Syntax
Rules can be called from anywhere XPRESS is allowed, which includes forms, workflows, or even another rule. To call a rule, use the XPRESS <rule> expression as exemplified below:
<rule name='Build Email'/>
When the XPRESS interpreter evaluates this expression, it assumes the value of the name attribute is the name of a Rule object in the repository. The rule is automatically loaded from the repository and evaluated. 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 shows an argument passed to the rule using the argument element.
<rule name='getEmployeeId'>
<argument name='accountId' value='jsmith'/>
</rule>
In the previous example, the value of the argument is specified as a static string jsmith. You can also calculate the value of an argument using an expression.
<rule name='getEmployeeId'>
<argument name='accountId'>
<ref>user.waveset.accountId</ref>
</argument>
</rule>
In the previous example, the argument value is calculated by evaluating a simple ref expression that returns the value of the view attribute user.waveset.accountId.
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>
The previous examples have the same behavior. They both pass the value of the view attribute user.waveset.account as the value of the argument.
Rule Argument ResolutionMost rules contain XPRESS <ref> expressions or JavaScript env.get calls to retrieve the value of a variable. Several options are available for controlling how the values of these variables are obtained.
In the simplest case, the application calling the rule will attempt to resolve all references. For rules called from workflows, the workflow processor will assume all references are to workflow variables. For rules called from forms, the form processor will assume all references are to attributes in a view. Rules can also call another rule by dynamically resolving the called rule’s name.
You can also use the optional <RuleArgument> element, which is described in Declaring a Rule with Arguments at the beginning of this chapter.
This section provides the following information:
Example
<Rule name='generateEmail'>
<concat>
<ref>global.firstname</ref>
<s>.</s>
<ref>global.lastname</ref>
<s>@sun.com</s>
</concat>
</Rule>This rule references two variables: global.firstname and global.lastname. You could use a rule such as this one in a form that is used with the User view because these are names of attributes in the view. The rule could be called in a Field such as:
<Field name='global.email'>
<Expansion>
<rule name='generateEmail'/>
</Expansion>
</Field>
This can be a convenient way to write simple rules that are used only in user forms, it is 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. It cannot be called from most workflows because workflows usually do not define variables named global.firstname and global.lastname.
These problems can be addressed by passing rule arguments explicitly, and by writing the rule to use names that are not dependent on any particular view. Here is a modified version of the rule that references the variables firstname and lastname.
<Rule name='generateEmail'>
<concat> \
<ref>firstname</ref>
<s>.</s>
<ref>lastname</ref>
<s>@sun.com</s>
</concat>
</Rule>
This rule is simpler and more general because it does not assume that it will be called from a user form. But the rule must then be called with explicit arguments like this:
<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. This keeps the rule isolated from the naming conventions used by the calling application, and makes the rule usable in other contexts.
Local Scope Option
Even when arguments are passed explicitly to a rule, the system by default allows references to other variables not passed as explicit arguments. The following example shows a workflow action calling the rule but only passing one argument:
<Action>
<expression>
<set name='email'>
<rule name='generateEmail'>
<argument name='firstname' value='$(employeeFirstname)'/>
</rule>
</set>
</expression>
</Action>
When the rule is evaluated, the workflow processor will be 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, it is recommended that rules be defined with the local scope option. This option is enabled by setting the localScope attribute to true in the Rule element:
<Rule name='generateEmail' localScope='true'>
<concat>
<ref>firstname</ref>
<s>.</s>
<ref>lastname</ref>
<s>@sun.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 should always use the local scope option.
Rule Argument Declarations
Though not required, it is considered good practice to include within the rule definition explicit declarations for all arguments that can be referenced by the rule. Argument declarations offer advantages, and can:
You could rewrite the generateEmail rule as follows:
<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='waveset.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.
The rule has been modified to define another argument named domain, which is given a default value of waveset.com. The default value is used by the rule unless the caller passes an explicit argument named domain.
The following call produces the string john.smith@sun.com:
<rule name='generateEmail'>
<argument name='firstname' value='john'/>
<argument name='lastname' value='smith'/>
</rule>
The following call produces the string john.smith@yourcompany.com:
<rule name='generateEmail'>
<argument name='firstname' value='john'/>
<argument name='lastname' value='smith'/>
<argument name='domain' value='yourcompany.com'/>
</rule>
The following call produces the string john.smith@:
<rule name='generateEmail'>
<argument name='firstname' value='john'/>
<argument name='lastname' value='smith'/>
<argument name='domain'/>
</rule>
Note 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.
Locked Arguments
Declaring arguments with default values can be a useful technique for making the development and customization of rules easier. If you have a constant value in a rule that may occasionally change, it is easier to locate and change if the value is defined in an argument rather than embedded deep within the rule expression.
The Business Process Editor provides a simplified GUI for configuring rules by changing the default values of arguments which is much easier than editing the entire rule expression.
But once an argument is declared, it is possible for the caller of the rule to override the default value by passing an explicit argument. You may not wish the caller to have any control over the value of the argument. This can be prevented by locking the argument. Arguments are locked by including the attribute locked with a value of true in the RuleArgument element. For example:
<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='waveset.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>
In the previous example, the argument domain is locked, which means its value will always be waveset.com, even if the caller tries to pass an value for the argument. If this rule is to be used at a site whose domain name is not waveset.com, all the administrator needs to do is edit the rule and change the value of the argument. There is no need to understand or modify the rule expression.
Securing RulesSecure a rule so that it cannot be used in an unintended way when it
This is especially important for rules called from forms. Because form rules run above the session, any rule that you expose is available to anyone capable of creating a session, either through the API or a SOAP request.
This section provides the following information:
How to Secure a Rule
- Place the rule in an appropriate organization. Rules are often put in the organization named All so that everyone can access them. This is convenient for simple rules that perform calculations but have no side effects.
- Do not put sensitive rules in All. Instead, consider placing them in Top or another suitably high level organization so that only high level administrators can execute them directly.
Creating a Rule that References a More Secure Rule
When you call a rule, you are first authorized for that rule. If authorized, that rule can then call other rules without further checking authorization. This allows users to be given indirect access to secure rules. The user cannot view or modify the contents of the secure rule. They can call it only through a rule to which they have been given access.
To create a rule that references a more secure rule, the user creating the rule must control both of the organizations that contain the rules. Typically, the secure rule is in a high level organization such as Top. The insecure rules are then placed in a lower level organization to which more users have access.
:
