|
| |
| Sun Java[TM] System Identity Manager 7.1 Deployment Tools | |
Chapter 2
Working with RulesThis chapter explains how to work with Identity Manager rules and rule libraries.
The information is organized into the following sections:This chapter is organized into the following sections:
Note
You can use the Sun Identity Manager Integrated Development Environment (Identity Manager IDE) to create, edit, and test rules for your deployment. See Chapter 1, "Using the Identity Manager IDE" for detailed instructions.
You can also use the Identity Manager Business Process Editor (BPE) application to create, edit, and validate rules. See Appendix A, "Using the Business Process Editor."
Understanding Rules and Rule LibrariesThis section provides the following information:
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.
You can pass arguments to a rule to control its behavior, and a rule can reference and modify variables maintained by the form or workflow.
Note
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.
This chapter assumes you are familiar with the XPRESS language. For detailed information about using XPRESS, see Sun Java™ System Identity Manager Workflows, Forms, and Views.
For information about writing rules in JavaScript, see Writing Rules in JavaScript.
Code Example 2-1 contains a simple XML rule. The rule name is defined by the name attribute in the <Rule> element, and it returns the string value john or mary. The rule body is an XPRESS expression within the <Rule> element.
Code Example 2-1 Example XML Rule
<Rule name='getApprover'>
<cond><eq><ref>department></ref><s>sales</s></eq>
<s>john</s>
<s>mary</s>
</cond>
</Rule>
Why Use Rules?
You can call a rule wherever XPRESS is allowed — most notably in workflows and forms. Rules allow you to encapsulate a fragment of logic or a static value that can then be reused in many locations.
The benefits of saving XPRESS logic or static values for reuse include:
- Easy maintenance. You can modify a rule by changing a single object instead of changing all of the forms or workflows that reference the rule.
- Distributed development. Users can develop rules that focus on rule requirements without having to be aware of all the forms or workflows that reference that 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
You typically call a rule in forms to calculate the allowedValues display property or to control field visibility within a <Disable> expression. Within forms, rules could be the most efficient mechanism for storing and reusing:
When calling rules from forms, it is particularly important that you properly secure those forms. For information about securing rules, see Securing Rules.
The rule in Code Example 2-2 returns a list of job titles. Rules such as this are often used in Identity Manager forms to calculate lists of names for selection. To add or change a new job title, you only need to modify this rule instead of having to modify all of the forms that reference the rule.
Code Example 2-2 Returning a Job Titles List
<Rule name='Job Titles'>
<list>
<s>Sales</s>
<s>Accounting Manager</s>
<s>Customer Service Representative</s>
</list>
</Rule>
The field in Code Example 2-3 calls the rule defined in the preceding example to use the job titles list in a select box:
Note
In this example, the rule name element uses a lowercase r because you use it to call the rule, not define it.
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.
The rule in Code Example 2-4 sets a value for the user's description of 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.
Code Example 2-4 Setting the Value for a User’s Resource Description
<Rule name='account description'>
<concat>
<s>Account for </s>
<ref>global.firstname</ref>
<ref>global.lastname</ref>
<s>.</s>
</concat>
</Rule>
Identity Manager forms and workflows support rules that can dynamically calculate the name of another rule to call. Code Example 2-5 shows a form field that calls a rule that calculates a department code:
Code Example 2-5 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>
Workflow activities can also contain subprocesses that contain a rule that dynamically calculates the subprocess name:
Code Example 2-6 Calculating a Subprocess 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>
Using Rules in Workflows
In workflow, you can use a rule to:
Code Example 2-7 is a manual action used to send an approval request to an administrator. You can specify a timeout value for this action, and if the administrator does not respond within the specified time, the action terminates, and the workflow escalates the approval to a different administrator.
In this example, the timeout is specified with a fixed value of 86,400 seconds or 24 hours.
Code Example 2-7 Specifying a Timeout with a Fixed Value
<Rule name='Approval Timeout'>
<i>86400</i>
</Rule>
Code Example 2-8 is a manual action that calls the timeout rule:
Code Example 2-8 Calling the timeout Rule
<ManualAction>
<Owner name='$(approver)'/>
<Timeout>
<rule name='Approval Timeout'/>
</Timeout>
<FormRule>
<ref>approvalForm</ref>
</FormRule>
</ManualAction>
What is a Rule Library?
A rule library is an XML configuration object that is stored in the Identity Manager 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. Using libraries can simplify rule maintenance by reducing the number of objects in the repository and makes it easier for form and workflow designers to identify and call useful rules.
For example, Code Example 2-9 shows a library containing two different account ID generation rules:
Code Example 2-9 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 Identity Manager IDE to view and edit the default rule libraries or to add new rules to an existing library object. For detailed instructions, see Working with Repository Objects.
Customizing Default Rules and Rule LibrariesYou can use the Identity Manager IDE to edit the default Identity Manager rules to follow a custom set of steps. Identity Manager ships with a library of default rules and rule libraries, including:
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.
Table 2-1 lists the predefined Active Sync rules.
Table 2-1 Predefined Active Sync Rules
Rule Name
Description
ActiveSync has isDeleted set
Used by migration from resources with “Process deletes as updates” set to false.
No Correlation Rule
Default rule to use when no correlation is desired.
No Confirmation Rule
Default rule to use when no confirmation is desired.
AlphaNumeric Rules Library
A default library of alphanumeric rules enables you to control how numbers and letters are ordered and displayed in Identity Manager forms and workflows. In the Identity Manager IDE, this library is displayed as the Alpha Numeric Rules library object.
Table 2-2 lists the rules in this library.
Table 2-2 Default Alphanumeric Rules
Rule Name
Description
AlphaCapital
List of English uppercase alphabetic characters
AlphaLower
List of English lowercase alphabetic characters
Numeric
List of numeric characters
WhiteSpace
List of white space characters
SpecialCharacters
List of common special characters
IllegalNTCharacters
List of illegal NT characters
legalEmailCharacters
Tests to see if str is all numeric characters.
isNumeric
Tests to see if str is only numeric
isAlpha
Tests to see if str is only alpha
hasSpecialChar
Tests to see if str has any special characters
hasWhiteSpace
Tests to see if str has any white space characters
isLegalEmail
Tests to see is str contains legal characters for an email address
hasIllegalNTChar
Tests to see is str is all numeric characters
stringToChars
Converts the supplied string (passed as a testStr argument) to a list of its component characters.
StripNonAlphaNumeric
Removes any nonalphanumeric characters from testStr
Auditor Rules
To achieve a high level of configurability with minimal complexity, Identity Auditor makes judicious use of rules in audit policy and access scan object configuration.
Table 2-3 provides an overview of the rules you can use to customize how audit policy remediation works and how access scans operate.
Table 2-3 Auditor Rule Types Quick Reference
Rule Type
Example Rules
subTypes and authTypes
Purpose
Attestor
Default Attestor
SubType: ATTESTORS_RULE
AuthType: AccessScanRule
Automates the attestation process by specifying a default attestor for manual entitlements.
Attestor Escalation
Default EscalationAttestor
SubType:
AttestorEscalationRuleAuthType: AccessScanRule
Automates the attestation process by specifying a default escalation user for manual attestation.
Audit Policy
Compare Accounts to Roles
SubType: SUBTYPE_AUDIT_POLICY_RULE
SubType: SUBTYPE_AUDIT_POLICY_SOD_RULE
AuthType: AuditPolicyRule
Compares user accounts to accounts specified by current Roles.
Compare Roles to Actual Resource Values
SubType: SUBTYPE_AUDIT_POLICY_RULE
SubType: SUBTYPE_AUDIT_POLICY_SOD_RULE
AuthType: AuditPolicyRule
Compares current resource attributes with those specified by current Roles.
Remediation User Form
SubType: USER_FORM_RULE
AuthType: Not specified
Automates the attestation process by allowing audit policy authors to constrain which part of a user view is visible when responding to a particular policy violation.
Remediator
Default Remediator
SubType: REMEDIATORS_RULE
AuthType: AccessScanRule
Automates the remediation process by specifying a remediator for any entitlements created in remediating state.
Review Determination
Reject Changed User
SubType:
REVIEW_REQUIRED_RULEAuthType: AccessScanRule
Automates the attestation process by automatically rejecting user entitlement records.
Review Changed Users
SubType:
REVIEW_REQUIRED_RULEAuthType: AccessScanRule
Automates the attestation process by automatically approving user entitlement records.
Review Everyone
SubType:
REVIEW_REQUIRED_RULEAuthType: AccessScanRule
Automates the attestation process by requiring manual attestation for some user entitlement records.
User Scope
All Administrators
SubType: USER_SCOPE_RULE
AuthType: AccessScanRule
Provides flexibility in selecting a list of users to be scanned by an access scan.
All Non-Administrators
SubType: USER_SCOPE_RULE
AuthType: AccessScanRule
Provides flexibility in selecting a list of users to be scanned by an access scan.
Users Without a Manager
SubType: USER_SCOPE_RULE
AuthType: AccessScanRule
Provides flexibility in selecting a list of users to be scanned by an access scan.
ViolationPriority
ViolationPriority
SubType: Not specified
AuthType:
EndUserAuditorRuleCustomization — allows the deployment to specify what are valid violation priorities and the corresponding display strings.
ViolationSeverity
ViolationSeverity
SubType: Not specified
AuthType:
EndUserAuditorRuleCustomization — allows the deployment to specify what are valid violation severities and the corresponding display strings.
The following sections provide information about these Identity Auditor rules, how you might customize them, and why:
Attestor Rule
Every user entitlement that is created in a pending state must be attested by someone. During an access review, Identity Auditor passes each user view to the Attestor rule to determine who gets the initial attestation requests.
The idmManager attribute on the WSUser object contains the Identity Manager account name and ID of the user’s manager.
You can use alternate implementations to designate both IdmManager and any Resource owners as attestors (for Resources included in the view). This rule takes the current user view and a LighthouseContext object as inputs, so you can use any data known to Identity Manager.
Inputs: Accepts the following input variables:
You must specify the following for a custom Attestor rule:
Called: During access scan; after evaluating all audit policies, but before dispatching the user entitlement
Returns: A list of zero or more Identity Manager attestor names (users responsible for attesting a particular user entitlement) or NamedValue pairs.
- If the result is a string, it must resolve to an Identity Manager account ID. If delegation is enabled for the access scan, the access scan will use the delegation settings of the Identity Manager user returned by the code.
- If the result is a NamedValue, it assumed to be a bound delegation pair [Delegator, Delegatee], and the access scan will not resolve any further.
Note
No checking is performed on NamedValue pairs.
If the rule returns NamedValue pair elements, they are passed on without validation.
- If the result is not a valid Identity Manager user name, the rule appends errors to the scan task results, but the scan thread continues.
- If the result is a zero-length list, the attestation request remains in pending state because nobody will process the request.
- If the result is neither a string or a NamedValue, an exception results and the scan thread aborts.
Predefined Rule: Default Attestor
Location: Compliance > Manage Policies > Access Scan > Attestor Rule
Attestor Escalation Rule
A workflow calls the Attestor Escalation rule when an attestation times out because the attestor did not take action within a specified period of time. This rule returns the next person in the escalation chain based on the cycle count.
Inputs: Accepts the following input variables:
You must specify the following for a custom Attestor Escalation rule:
SubType: AttestorEscalationRule
Called: During an attestation workflow when a workitem times out.
(Default timeout is 0 — never times out).Returns: A single attestor name or a list of attestor names, which must be valid Identity Manager account names.
Predefined Rule: Default EscalationAttestor
Location: Compliance > Manage Policies > Access Scan > Attestor Escalation Rule
Audit Policy Rule
An audit policy contains a set of rules that it applies to data representing an object being audited. Each rule can return a boolean value (plus some optional information).
To determine whether a policy has been violated, the audit policy evaluates a logical operation on the results of each rule. If the audit policy has been violated, a compliance violation object might result, with (typically) one compliance violation object per policy, rule, or whatever was being audited. For example, an audit policy with five rules might result in five violations.
None
You must specify the following for a custom Audit Policy rule:
Note
When you use the Audit Policy Wizard to create an Audit Policy rule, the wizard uses the AuditPolicyRule authType by default.
If you use the Identity Manager IDE or the Identity Manager Business Process Editor (BPE) to create an Audit Policy rule, be sure to specify the AuditPolicyRule authType.
Called: During an Audit Policy Evaluation
Returns: An audit policy rule must return an integer value, but the value can be expressed as one of the following:
If the audit policy returns a map, other elements can affect the resulting compliance violation. These elements include:
- resources element: Causes the compliance violation to refer to two resources, resource one and resource two. These values must be real resource names because the compliance violation contains actual object references (so the names are resolved to IDs). (Default is no resource.)
- severity element: Causes the compliance violation to have the specified severity. (Default is 1.)
- priority element: Causes the compliance violation to have the specified priority. (Default is 1.)
- violation element: Prevents the audit scanner from creating a rule violation — even if the audit policy evaluates to true.
- Compare Accounts to Roles: Compares user accounts to accounts specified by roles. Any account not referenced by a role is considered an error.
- Compare Roles to Actual Resource Values: Compares current resource attributes with those specified by current Roles. Any differences are considered errors, and any resources or resource attributes not specified by a role are ignored.
Remediation User Form Rule
The Remediation User Form rule allows audit policy authors to constrain which part of a user view is visible when they are responding to a particular policy violation.
When a remediator edits a user during entitlement remediation processing, a JSP (approval/remModifyUser.jsp) calls the Remediation User Form rule. This rule allows the access scan to specify an appropriate form for editing a user. If the remediator has already specified a user form, then the access scan uses that form instead.
Inputs: Accepts the item variable (Remediation WorkItem)
You must specify the following for a custom Remediation User Form rule:
Called: During JSP form processing after the remediator clicks Edit User on the remediation form.
Returns: The name of a User Form or a null.
Remediator Rule
During an access review, every user view is passed to the Remediator rule to determine who should get the initial remediation requests. This rule is analogous to the Attestors rule, except the Remediator rule is called when a workitem is created in the remediating state.
Inputs: Accepts the following input variables:
You must specify the following for a custom Remediator rule:
Called: During access scan, after evaluating all audit policies and before dispatching the user entitlement
Returns: A list of zero or more Identity Manager remediator names or NamedValue pairs.
- If the result is a string, it is resolved to a Identity Manager user, and if delegation is enabled for the access scan, the user's delegation data is used.
- If the result is a NamedValue, it is assumed to be a bound delegation pair [Delegator, Delegatee].
- If the result is one or more invalid Identity Manager user names, errors indicating a problem are appended to the scan task results, but the scan thread continues.
- If the result is not a string or NamedValue, an exception occurs and the scan thread aborts.
- If the results are a zero-length list, the remediation request remains in a pending state because nobody will process it.
Predefined Rule: Default Remediator
Location: Compliance > Manage Policies > Access Scan > Remediator Rule
Review Determination Rule
During an access review, every user view is passed to the Review Determination rule to determine whether the corresponding user entitlement record can be automatically approved or rejected, automatically placed into remediation state, or if it must be manually attested.
You can use the Review Determination rule to significantly increase the efficiency of an access review.
If you can encapsulate any institutional knowledge that would allow a user to be automatically approved or rejected, and express that knowledge in this rule, you reduce the number of manual attestations needed and improve overall review performance.
As a further improvement, this rule can return information that will be visible to the attestors as a “hint.” For example, if the rule noticed that the user has privilege access to a resource, see attestorHint in Example 1 on (more...) .
In addition, the Review Determination rule can access the user view (including any Compliance Violations) and compare the user’s previous UserEntitlements, which allows the rule to approve or reject all UserEntitlements that are the same as (or different from) a previously approved UserEntitlement.
Inputs: Accepts the following input variables:
You must specify the following for a custom Review Determination rule:
Called: During access scan, after evaluating all audit policies and before dispatching the user entitlement
Example 1: Manually attests the UserEntitlement. The rule provides a hint to the manual attestor.
<map>
<result>
<i>1</i>
<s>reason</s>
<s><reason that the attestation was auto-approved/rejected></s>
<s>attestorHint</s>
<s><hint to attestor></s>
</map>
Example 2: Automatically rejects the UserEntitlement. The rejection comment indicates that group membership is disallowed.
<map>
<s>result</s>
<i>0</i>
<s>reason</s>
<s>User belongs to NT group Domain Administrators</s>
</map>
- Reject Changed Users: Automatically rejects user entitlements that have changed since the last approval state, and automatically approves user entitlements that are unchanged. All unknown UserViews are forwarded for manual attestation. Only the accounts section of the User view is compared.
- Review Changed Users: Automatically approves any users whose account data has not changed since their last approved entitlement. Users with changed account data or no approved data are manually attested. Only the accounts section of the User view is compared.
- Review Everyone: Forwards all user entitlement records for manual attestation.
Location: Compliance > Manage Access Scans > Access Scan > Review Determination Rule
User Scope Rules
If an access scan has users scoped by a rule, the User Scope rule is evaluated to determine a list of users to scan.
Inputs: Accepts the lhcontext variable (LighthouseContext)
You must specify the following for a custom User Scope rule:
Called: At the beginning of an access scan
Returns: An Identity Manager user name or a list of Identity Manager user names. Each name must be a valid Identity Manager user name.
- If the results contain any names that cannot be resolved to valid Identity Manager user names, the rule returns an error.
- If the results contain any duplicate user names, the rule returns an error.
Note
- An access scan that scans the same user multiple times might fail to create the attestation workflow for a subsequent instance of the same user. Therefore, a customized implementation of the User Scope rule should provide checks to avoid duplicate users in the output.
- This rule can return accounts that are not available to the administrator running the scan. In this case, the scan will attempt to get the account’s user view and fail; resulting in an error in the scan task.
Location: Compliance > Manage Access Scans > Access Scan > User Scope Rule
ViolationPriority Rule
Use the ViolationPriority rule to allow a deployment to specify what the valid violation priorities are, and what the corresponding display strings will be.
You must specify the following for a custom ViolationPriority rule:
Called: When displaying the violation list and when changing violation priority.
Returns: A list of key/value pairs indicating priority integer value and a corresponding string. The integer values must be contiguous because the rule returns a list, not a map.
Note
You can customize this rule to change the display value for any priority setting.
When a ComplianceViolation is created, you can change priority values in the Remediation WorkItem list viewer. Select one or more Remediation WorkItems, and then select Prioritize, which enables you to change priority values.
To see these values in the Remediation WorkItem list view, you must change the approval/remediate.jsp page by setting the includeCV option to true (default is false). However, enabling the more detailed view affects performance, which may be unacceptable for deployments with lots of Remediations.
The custom value expects the ViolationPriority rule to be an array rather than a map. So, if you use 100 as the integer value, the rule must have 200 elements (alternate int/string). The list provides both string mapping for the integer and populates the selection in the form where you changed it.
Predefined Rule: ViolationPriority
Location: Called from the Remediation List Form
ViolationSeverity Rule
Use the ViolationSeverity rule to allow a deployment to specify what the valid violation severities are, and what the corresponding display strings will be.
You must specify the following for a custom ViolationSeverity rule:
Called: When displaying the violation list and when changing violation severity.
Returns: A list of key/value pairs indicating severity integer value and a corresponding string. The integer values must be contiguous because the rule returns a list, not a map.
Note
You can customize this rule to change the display value for any priority setting.
When a ComplianceViolation is created, you can change severity values in the Remediation WorkItem list viewer. Select one or more Remediation WorkItems, and then select Priority, which enables you to change severity values.
To see these values in the Remediation WorkItem list view, you must change the approval/remediate.jsp page by setting the includeCV option to true (default is false). However, enabling the more detailed view affects performance, which may be unacceptable for deployments with lots of Remediations.
The custom value expects the ViolationSeverity rule to be an array rather than a map. So, if you use 100 as the integer value, the rule must have 200 elements (alternate int/string). The list provides both string mapping for the integer and populates the selection in the form where you changed it.
Predefined Rule: ViolationSeverity
Location: Called from the Remediation List Form
Sample Auditor Rule Multiple Account Types
You can use the Sample Auditor Rule Multiple Account Types rule to dynamically test multiple user accounts per resource. For example,
- Set up a resource with multiple account types (see Code Example 2-10).
Code Example 2-10 Sample Auditor Rule Multiple Account Types Rule
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Waveset PUBLIC 'waveset.dtd' 'waveset.dtd'>
<Waveset>
<Rule subtype='IdentityRule' name='Administrator Identity'>
<concat>
<s>adm</s>
<ref>attributes.accountId</ref>
</concat>
</Rule>
</Waveset>
- Add a user with two accounts on the resource and set up a user form so that the new resource attributes are directly assigned separately:
account[Simulated Resource].department
account[Simulated Resource|admin].department
- Assign different values for each account and test the policy rule.
sample/rules/SampleAuditorRuleMultipleAccountTypes.xml
Compliance Violation Rules
ComplianceViolations support numeric severity and priority attributes that enable you to distinguish between violations by severity or priority. You can assign these attributes to the violation, based on Audit rule output.
For example, if the Audit rule provides the following output, the resulting ComplianceViolation will have a severity of 3 and a priority of 4.
The following rules map between a ComplianceViolation’s numeric value and its display string value:
Identity Auditor allows you to customize these rules by changing the display value for any severity or priority setting.
After a ComplianceViolation is created, you can view and change severity and priority values in the Remediation WorkItem list viewer by selecting one or more Remediation WorkItems, and then clicking Prioritize.
Note
To view severity and priority values in the Remediation WorkItem list viewer, you must change the approval/remediate.jsp page to set the includeCV option to true (default is false).
However, be aware that enabling the more-detailed view affects performance, which may be unacceptable for deployments with lots of Remediations.
DateLibrary
The DateLibrary a default library of rules that control how dates and times are displayed in a deployment. In the Identity Manager IDE, this library is displayed as the Date Library library object.
Use these rules to customize how dates and times are displayed:
Excluded Resource Accounts Rule SubType
The ExcludedAccountRule subType supports the exclusion of resource accounts from resource operations.
Inputs: Accepts the following input variables:
The rule can use the operation parameter to have finer control over which resource accounts are exempt from the actions specified by the operation parameter. If an operation parameter is not used within the rule, all accounts identified by the rule will be excluded from all the listed operations.
The operation parameter can contain the following values:
authType: ExcludedAccountsRule
Code Example 2-11 exemplifies subType use, and it excludes specified resource accounts for UNIX adapters.
Code Example 2-11 Exemplifying Subtype Use
<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>
Code Example 2-12 illustrates the use of the operation parameter.
This parameter allows the “Test User” resource account to be manipulated — without impacting Identity Manager — if Active Sync is running against the resource.
Code Example 2-12 Using the operation Parameter
<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>
Naming Rules Library
The Naming Rules Library is a default library of naming rules that enable you to control how names are displayed after rule processing. In the Identity Manager IDE, this library is displayed as the NamingRules library object.
Table 2-4 lists the default naming rules.
Table 2-4 Default Naming Rules
Rule Name
Description/Output
AccountName — First dot Last
Marcus.Aurelius
AccountName — First initial Last
MAurelius
AccountName — First underscore Last
Marcus_Aurelius
marcus.aurelius@example.com
Fullname — First space Last
Marcus Aurelius
Fullname — First space MI space Last
Marcus A Aurelius
Fullname — Last comma First
Aurelius, Marcus
RegionalConstants Library
The RegionalConstants Library is a default library of regional constants rules that enable you to control how states, days, months, countries, and provinces are displayed. In the Identity Manager IDE, this library is displayed as the RegionalConstants Rules library object.
Table 2-5 lists the default regional constants rules.
Table 2-5 Default Regional Constants Rules
Rule Name
Description
US States
List of the full names of the US states
US State Abbreviations
List of the standard US state abbreviations.
Days of the Week
List of the full names of the seven days of the week.
Work Days
List of the five work days of the week (U.S.)
Months of the Year
List of the full names of the months of the year.
Month Abbreviations
List of the standard abbreviation for the selected month.
Numeric Months of the Year
Returns a list of 12 months.
Days of the Month
Returns a list of 31 days.
Smart Days of the Month
Returns a list based on a numeric month and four-digit year.
Countries
Lists the names, in English, of the countries of the world.
Canadian Provinces
Lists the names, in English, of the Canadian provinces.
Developing New Rules and Rule LibrariesThis section describes how to develop rules for your deployment, and provides the following information:
Note
- For information about applying rules to a roles, see Using Rules in Roles and Sun Java™ System Identity Manager Administration.
- For information about adding rules to an existing rule library, see Customizing Default Rules and Rule Libraries.
- For information about using XPRESS to write an expression, see the XPRESS Language chapter in Sun Java™ System Identity Manager Workflows, Forms, and Views.
Tip
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
Rules are typically written in XML and encapsulated in the <Rule> element.
This section covers the following topics:
Using the <Rule> Element
Code Example 2-13 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.
Code Example 2-13 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>
Returning Fixed Values
If the rule returns a fixed value, you can write it using XML Object syntax.
Code Example 2-14 returns a list of strings.
Code Example 2-14 Returning 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 Code Example 2-15, a 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.
Code Example 2-15 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>
In Code Example 2-16, 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.
Code Example 2-16 Testing a 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 Identity Manager IDE, 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.
Code Example 2-17 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>
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.
Code Example 2-18 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 argument type, but you can specify type in a comment field. Use the <Comment> element to include comments in your rule:
Code Example 2-19 Using <Comment> to Include Comments in a 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 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. While a rule expression can return only a single value, a rule can assign values to external variables with the following XPRESS expressions:
In Code Example 2-20, the rule tests the value of the external variable named department and assigns values to two other variables.
Code Example 2-20 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 may find it more convenient to write those rules in JavaScript rather than XPRESS. You can wrap the JavaScript in a <script> element. For example,
Code Example 2-21 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>
To reference the values of form and workflow variables, call the env.get function and pass the variable name. You can use the env.put function to assign variable names. The value of the last statement in the script becomes the value of the rule. In the preceding example, the rule will return the value in the email variable.
You can call other rules with the env.call function.
Referencing RulesYou 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, all rule names 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'/>
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, 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.
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.
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 Resolution
Most 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.
This section provides the following information:
Calling Scope or Explicit Arguments
This section provides examples to illustrate rule argument resolution.
Code Example 2-22 illustrates adding a rule to a form that can be used with the User view because there are attributes names in the view:
Code Example 2-22 Adding a Rule to a Form
<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:
You can call this rule in a Field, as shown in Code Example 2-23:
Code Example 2-23 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.
Code Example 2-24 shows a modified version of the rule that references the variables firstname and lastname:
Code Example 2-24 Rule Referencing firstname and lastname Variables
<Rule name='generateEmail'>
<concat> \
<ref>firstname</ref>
<s>.</s>
<ref>lastname</ref>
<s>@example.com</s>
</concat>
</Rule>
The rule shown in Code Example 2-25 is simpler and more general because it does not assume that the rule will be called from a user form. But the rule must then be called with explicit arguments such as:
Code Example 2-25 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. 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. Code Example 2-26 shows a workflow action calling the rule but only passing one argument:
Code Example 2-26 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 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, rules should be defined with the localScope option.
You enable this option by setting the localScope attribute to true in the Rule element:
Code Example 2-27 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 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 shown in Code Example 2-28:
Code Example 2-28 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.
The rule has been modified to define another argument named domain, which is given a default value of example.com. The default value is used by the rule unless the caller passes an explicit argument named domain.
The call in Code Example 2-29 produces the string john.smith@example.com:
Code Example 2-29 Producing john.smith@example.com String
<rule name='generateEmail'>
<argument name='firstname' value='john'/>
<argument name='lastname' value='smith'/>
</rule>
The call in Code Example 2-30 produces the string john.smith@yourcompany.com:
Code Example 2-30 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>
The call in Code Example 2-31 produces the string john.smith@:
Code Example 2-31 Producing john.smith@ String
<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 Identity Manager IDE 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 (see Code Example 2-32):
Code Example 2-32 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>
In the preceding example, the argument domain is locked, which means its value will always be example.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 example.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 RulesYou should secure a rule so it cannot be used in an unintended way if that rule contains sensitive information such as credentials or it calls out to a Java utility that can have dangerous side effects.
Securing rules is especially important if the rules are called from forms. Form rules run above the session, so exposed rules are available to anyone capable of creating a session — either through the API or a SOAP request.
This section provides the following information:
Securing a Rule
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 Rules that Reference More Secure Rules
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.