Oracle Waveset 8.1.1 Deployment Reference

Chapter 4 Working with Rules

Waveset rules and rule libraries are repository objects that are used to encapsulate frequently used programming logic and static variables for reuse in many locations throughout your deployment. Rules and rule libraries enable you to manage data more efficiently.

This chapter explains how to work with Waveset rules and rule libraries and describes how to customize the default rules and rule libraries supplied with Waveset. This information is organized into the following sections:


Note –

You can use the Identity Manager IDE to create, edit, and test rules for your deployment.

Instructions for installing and configuring the Identity Manager IDE are provided on https://identitymanageride.dev.java.net.


Before You Begin

Review the information in these sections before working with Waveset rules and rule libraries:

Intended Audience

This chapter is intended for individuals who create, edit, and test rules for an Waveset deployment. Before working with Waveset rules and rule libraries, you must

Related Documentation and Web Sites

In addition to the information provided in this chapter, consult the publications and web sites listed in this section for information related to working with Waveset rules and rule libraries.

Recommended Reading

See the following chapters iDeployment Referencen for information related to Waveset rules.

Useful Web Sites

The following table describes some web sites you might find useful when trying to work with Waveset rules and rule libraries.

Table 4–1 Useful Web Sites

Web Site URL  

Description  

https://identitymanageride.dev.java.net

Open source Oracle Waveset Integrated Development Environment) project. Includes instructions for installing and configuring Identity Manager IDE. 

http://sunsolve.sun.com/

Sun web site containing diagnostic tools, forums, features and articles, security information, and patch contents. 

Note: The information on this site is partitioned into three areas,

  • Internal: Sun employees only

  • Contract: Available only to customers with contract access

  • Public: Available to everyone

http://forums.sun.com/

Sun Developer Network (SDN) web site where you can browse forums and post questions. 

https://sharespace.sun.com/gm/folder-1.11.60181?

Waveset link on Sun’s Share Space. 

Note: You must sign up for a Share Space ID to access information provided on this site.

http://sharespace.sun.com/gm/document-1.26.2296

Waveset FAQ on Sun’s Share Space. 

Note: You must sign up for a Share Space ID to access this FAQ.

Understanding Rules and Rule Libraries

This section provides the following information:

What is a Rule?

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

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

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


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.

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


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


Example 4–1 Example XML Rule


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

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

Why Use Rules?

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

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

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

Using Rules in Forms

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

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

The following example rule returns a list of job titles.


Example 4–2 Returning a Job Titles List


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

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

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


Note –

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



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


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

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


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


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

Using Rules in Roles

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

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

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


Note –

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


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


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


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

Using Rules in Workflows

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

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

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

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


Example 4–6 Calculating a Rule Name Dynamically


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

What is a Rule Library?

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

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


Note –

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


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


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


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


Note –

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


Developing New Rules and Rule Libraries

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


Note –

Best Practice:

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

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


Understanding Rule Syntax

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

This section covers the following topics:

Using the <Rule> Element

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


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


<Rule name=’getApprover’> 
   <cond>
      <eq>
         <ref>department></ref>
         <s>sales</s>
      </eq> 
      <s>Sales Manager</s> 
      <s>HR Manager</s> 
   </cond> 
</Rule>

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

Returning Static Values

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


Example 4–9 Returning a List of Strings


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

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

Referencing Variables

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

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


Example 4–10 Calculating an Email Address


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

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


Example 4–11 Testing a Transition


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

Declaring a Rule with Arguments

Best Practice:

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

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

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


Example 4–12 Setting a Default Value


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

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


Example 4–13 Overriding a Default Value Declared in RuleArgument


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

For more information about calling rules, see Referencing Rules.

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


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


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

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

Rules with Side Effects

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

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


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


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

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

Writing Rules in JavaScript

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

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


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


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

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

Referencing Rules

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

Basic Rule Call Syntax

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

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


<rule name=’Build Email’/>

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

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


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

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


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

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


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

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

Invoking Rules in a Library

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

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

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

Resolving Rule Arguments

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

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

This section provides the following information:

Calling Scope or Explicit Arguments in Forms

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

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


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

This rule references two variables:

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


Example 4–17 Calling the Rule in a Field


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

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

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

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


Example 4–18 Rule Referencing firstname and lastname Variables


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

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


Example 4–19 Calling the Rule with Explicit Arguments


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

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

Using the LocalScope Option in Workflows

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


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


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

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

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


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


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

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

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

Using Rule Argument Declarations

Best Practice:

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

Using argument declarations offers the following advantages:

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


Example 4–22 Rewriting the generateEmail Rule


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

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

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

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


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


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

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


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


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

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


Example 4–25 Producing john.smith@ String


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

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

Using Locked Arguments

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

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

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


Example 4–26 Locking an Argument


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

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

Securing Rules

If a rule contains sensitive information, such as credentials or calls to a Java utility that might have dangerous side effects, you must secure the rule to prevent anyone from using that rule in an unintended way.

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 who is capable of creating a session through the API or a SOAP request.

This section provides the following information:

Put Rules in an Appropriate Organization

As a convenience, most administrators put simple rules, such as those that perform calculations but have no side effects, in the All organization so that everyone granted rights to view rules can access those rules.

However, if you want to provide more security for a rule

Use Authorization Types to Secure Rules

You can use authorization types (AuthType) to further scope or restrict access to a subset of objects for a given Waveset objectType, such as a rule. For example, you might not want your users to have access to all rules within their scope of control when populating rules to select in a user form.

For information about using authorization types, see “Using Authorization Types to Secure Objects“ inBusiness Administrator's Guide.

Control Access to Rules that Reference More Secure Rules

Users can call, view, and modify the content of a secure rule if they have been given access to a rule that references that secure rule.

Waveset runs an authorization check in which a wrapper calls all of the users who have a right to edit that rule. Authorized users can use that rule to call other rules without further authorization checking, which can give them indirect access to secure rules.

When you create a rule that references a secure rule and give users access rights to the less secure rule, be careful that you are not inadvertently giving them inappropriate access to the secure rule.


Note –

To create a rule that references a more secure rule, you must control both organizations containing those rules. You also must have rights to run the first rule and call the secure rule.


Customizing Default Rules and Rule Libraries

This section describes the default rules and rule libraries supplied with Waveset. The information is organized as follows:


Note –

You can use the Identity Manager IDE to customize these rules and rule libraries.


Waveset Rules

You can use the following rules and rule libraries to customize Waveset.

AccessEnforcerLibrary

The AccessEnforcerLibrary is a default library of rules that enable you to manage certain types of objects because the Access Enforcer resource adapter does not provide a way for you to fetch these objects.

Inputs: See Table 4–2.

You must specify the following for a custom AccessEnforcerLibrary rule:

Argument 

Description 

AuthType 

Library 

SubType 

listRules

Returns 

See Table 4–2

Predefined Rules 

Not specified 

The following table describes the example AccessEnforcerLibrary rules.

Table 4–2 Example AccessEnforcerLibrary Rules

Rule Name 

Input Variables 

Description 

getApplications 

  • resName (Resource name)

  • Specify Access Enforcer object names by manually entering the names as strings.

Returns a list of applications that are available in SAP GRC Access Enforcer. If resName was specified, fetches the applications from Access Enforcer. Otherwise, returns the list specified statically.

getRoles 

resName (Resource name)

Returns a list of roles that are available in SAP GRC Access Enforcer that are the same as the roles available in the back-end system. 

These values are manually created and must be in sync with the corresponding values in SAP GRC Access Enforcer. 

getRequestTypes 

None 

Returns a list of Request types that are available in SAP GRC Access Enforcer. 

These values are manually created and must be in sync with the corresponding values in SAP GRC Access Enforcer. 

getPriorities 

None 

Returns a list of Priority values that are available in SAP GRC Access Enforcer 

These values are manually created and must be in sync with the corresponding values in SAP GRC Access Enforcer. 

getEmployeeTypes 

None 

Returns a list of Employee types that are available in SAP GRC Access Enforcer. 

These values are manually created and must be in sync with the corresponding values in SAP GRC Access Enforcer. 

getSLAs 

None 

Returns a list of Service Levels that are available in SAP GRC Access Enforcer. 

These values are manually created and must be in sync with the corresponding values in SAP GRC Access Enforcer. 

getSupporttedVersions 

resName (Resource name)

Returns a list of SAP GRC Access Enforcer versions that are supported by Waveset. These values must be the same as values that the adapter facet understands. 

ActiveSync Rules

When the Flat File Active Sync adapter detects a change to an account on a resource, it either maps the incoming attributes to an Waveset user, or it creates an Waveset user account. The adapter uses process, correlation, and delete rules to determine what to do with the user.


Note –

Active Sync rules must use context, not display.session. Correlation and Delete rules do not get a session, but Confirmation rules do. For more information, see Correlation Rule and Confirmation Rule.


Inputs: These rulesaAccept resource account attributes in the activeSync namespace. For example, activeSync.firstname.

You must specify the following for a custom ActiveSync rule:

Argument 

Description 

AuthType 

Not specified 

SubType 

Not specified 

Namespace 

Provide resource account attributes in the activeSync namespace. For example,

activeSync.firstname

Predefined Rules 

ActiveSyncRules’ predefined rules include: 

  • ActiveSync has isDeleted set: Used by migration from resources when you set the Process deletes as updates parameter to false.


    Note –

    Do not change this rule name. If you want to use a different rule name, duplicate the rule content and rename the new rule.


  • No Correlation Rule: Use this default rule if you do not want correlation.

  • No Confirmation Rule: Use this default rule if you do not want confirmation.

ADRules Library

The default library of ADRules enables you to create a list of the servers

Inputs: None

You must specify the following for a custom ADRules rule:

AuthType 

Not specified 

SubType 

Not specified 

Called 

 

Returns 

A list of zero or more string values. 

Predefined Rules 

None 

Table 4–3 Example ADRules Rules

Rule Name  

Description 

Exchange Servers 

Returns a list of the Exchange servers in your environment. 

You can update this list to include the Exchange servers in your environment. 

Home Directory Servers 

Returns a list of the Home Directory Servers in your environment. 

You can update this list to include the systems that serve home directory drives in your environment. 

AD Login Scripts 

Returns a list of the user login scripts being used in your environment. 

You can update this list to include the login batch scripts in your environment. 

Home Directory Drive Letter 

Returns a list of the home directory mapped drive letters in your environment. 

You can update this list to include the common home directory map drive letters in your environment. 

Home Directory Volumes 

Returns a list of the home directory volume names in your environment. 

You can update this list to include the common home directory volume names in your environment. Waveset uses this value with the Home Directory Server to create a user’s home directory. This volume must exist and be shared on the selected home directory server. 

AlphaNumeric Rules Library

The AlphaNumeric Rules Library is a default library of rules that enable you to control how numbers and letters are ordered and displayed in Waveset forms and workflows.


Note –

This library is displayed as the Alpha Numeric Rules library object in the Identity Manager IDE.


Inputs: See Table 4–4

You must specify the following for a custom rule:

AuthType 

EndUserRule

SubType 

Not specified 

Returns 

A list of zero or more strings. 

The following table describes rules in the AlphaNumeric Rules library.

Table 4–4 Example Alphanumeric Rules

Rule Name  

Input Variable  

Description  

AlphaCapital 

None 

Returns a list of English capital alpha characters 

AlphaLower 

None 

Returns a list of English lowercase alpha characters 

Numeric 

None 

Returns a list of numeric characters 

WhiteSpace 

None 

Returns a list of white space characters 

SpecialCharacters 

None 

Returns a list of common special characters 

legalEmailCharacters 

None 

Returns a list of legal special characters for email 

stringToChars 

testStr

Converts the given string to a list composed of the string’s individual characters 

isNumeric 

testStr

Tests to see if testStr contains all numeric characters

isAlpha 

testStr

Tests to see if testStr contains only alpha characters

hasSpecialChar 

testStr

Tests to see if testStr contains any special characters

hasWhiteSpace 

testStr

Tests to see if testStr contains any white space characters

isLegalEmail 

testStr

Tests to see if testStr consists of only legal email address characters

StripNonAlphaNumeric 

testStr

Removes any non-alpha or non-numeric characters from testStr

Approval Transaction Message

The Approval Transaction Message rule is a default rule used to format approval transaction text. You can customize this rule to provide more information for a user to sign.

Inputs: Accepts the following arguments:

You must specify the following for a custom Approval Transaction Message rule:

AuthType 

Not specified 

SubType 

Not specified 

Returns 

Formatted transaction text for the list of workitems in workItemList

Predefined Rules 

None 

Approval Transaction Message Helper

The Approval Transaction Message Helper rule returns the formatted transaction text for the approval of a single workitem.

Inputs: Accepts the following arguments:

You must specify the following for a custom Approval Transaction Message Helper rule:

AuthType 

Not specified 

SubType 

Not specified 

Returns 

Formatted transaction text for the approval of a single workitem

Predefined Rules 

None 

Attestation Remediation Transaction Message

The Attestation Remediation Transaction Message rule is a default rule used to format attestation remediation transaction text. You can customize this rule to provide more information for the user to sign.

Inputs: Accepts the following arguments:

You must specify the following for a custom Attestation Remediation Transaction Message rule:

AuthType 

EndUserAuditorRule

SubType 

Not specified 

Returns 

Formatted attestation remediation transaction text 

Predefined Rules 

None 

Attestation Remediation Transaction Message Helper

The Attestation Remediation Transaction Message Helper rule returns the formatted transaction text for the attestation remediation of a single workitem.

Inputs: Accepts the following arguments:

You must specify the following for a custom Attestation Remediation Transaction Message Helper rule:

AuthType 

EndUserAuditorRule

SubType 

Not specified 

Returns 

Formatted transaction text for the attestation remediation of a single workitem.

Predefined Rules 

None 

Attestation Transaction Message

The Attestation Transaction Message rule a default rule used to format attestation transaction text. You can customize this rule to provide more information for the user to sign.

Inputs: Accepts the following arguments:

You must specify the following for a custom Attestation Transaction Message rule:

AuthType 

EndUserAuditorRule

SubType 

Not specified 

Returns 

Formatted attestation transaction text. 

Predefined Rules 

None 

Attestation Transaction Message Helper

The Attestation Transaction Message Helper rule returns the formatted transaction text for the a single attestation.

Inputs:

Accepts the following arguments:

You must specify the following for a custom Attestation Transaction Message Helper rule:

AuthType 

EndUserAuditorRule

SubType 

Not specified 

Returns 

Formatted transaction text for a single attestation 

Predefined Rules 

None 

CheckDictionaryWord

Use the CheckDictionaryWord rule to run a JDBC query against a dictionary to check if a password exists in the dictionary.

Inputs:

Accepts the following arguments:

You must specify the following for a custom CheckDictionaryWord rule:

AuthType 

Not specified 

SubType 

Not specified 

Returns 

A list of zero or more strings 

Predefined Rules 

None 

DateLibrary

The DateLibrary is a default library of rules that control how dates and times are displayed in a deployment.


Note –

This library is displayed as the Date Library library object in the Identity Manager IDE.


Inputs:

See Table 4–5.

You must specify the following for a custom DateLibrary rule:

AuthType 

Rule

SubType 

Not specified 

Returns 

Boolean values of true or false. See Table 4–5.

The following table describes the example DateLibrary rules.

Table 4–5 Example DateLibrary Rules

Rule 

Input Variables 

Description 

Date Validation

mm/dd/yy yy

Determines valid date strings. If month or day values are provided in with single digits, the rule accounts for them appropriately. 

  • true if the string provided contains valid date components.

  • false if the string provided contains invalid date components.

Validate Day Month Year

  • month

  • day

  • year

Determines valid day, month, and year strings. If the month or the day values are provided in with single digits, the rule accounts for them appropriately. 

  • true if the string provided is a valid date.

  • false if the string provided is a invalid date.

Validate Time

HH:mm:ss

Determines valid time strings. If the time string is not in this format, or the components are out of bounds (for example, if the hour is less than zero or greater than 23), the rule returns a false.

  • true if the string provided is a valid time.

  • false if the string provided is a invalid time.

End User Controlled Organizations

The End User Controlled Organizations rule determines the set of organizations that are controlled by a user logging into the End User interface. These organizations, together with the End User organization, define the scope of control over which a user is granted the permissions specified in the EndUser capability (AdminGroup). Because this is a rule, it allows the scope of control to vary depending on which user is logging into the End User interface.

Inputs:

User view of the authenticating end user

You must specify the following for a custom End User Controlled Organizations rule:

AuthType 

EndUserControlledOrganizationsRule

SubType 

Not specified 

Returns 

A single controlled organization (string) or a list of controlled organizations. Each value can be an organization name or ID. If an organization name is returned, it must be fully qualified up to Top (for example, Top:Marketing:South)

Predefined Rules 

Defaults to returning the organization of which the user is a member (for example, waveset.organization)

EndUserRuleLibrary

The EndUserRuleLibrary is a default library of rules that Waveset uses to determine or to verify end-user account information.


Note –

By default, Waveset’s End User Anonymous Enrollment processing generates values for accountId and emailAddress by using user-supplied first names (firstName), last names (lastName) and employee IDs (employeeID). Anonymous enrollment can cause non-ASCII characters to display in email addresses and account IDs.

To ensure that Waveset maintains ASCII accountIds and email addresses during anonymous enrollment processing, international users must perform these steps:


ProcedureTo Use EndUserRuleLibrary in Localized Environments

  1. Modify the following EndUserRuleLibrary rules:

    • getAccountId: Remove firstName, lastName, and letter substr. Use employeeId only.

      • getEmailAddress: Remove firstName, lastName, and "." Use employeeId only.

      • verifyFirstname: Change length check from 2 to 1 to allow single character Asian first names.

  2. Edit the End User Anon Enrollment Completion form to remove the firstName and lastName arguments from calls to the getAccountId and getEmailAddress rules.


    Note –

    This library is displayed as the EndUserRuleLibrary library object in the Identity Manager IDE.


    Inputs:

    See EndUserRuleLibrary and EndUserRuleLibrary.

    You must specify the following for a custom EndUserLibrary rule:

    AuthType 

    EndUserLibrary

    SubType 

    Not specified 

    The following table describes the example EndUserRuleLibrary rules.

    Rule 

    Input Variable 

    Description  

    getCallerSession

    None 

    Returns the internal session context (Lighthouse context) for the user executing a form. 

    getUserView

    • resourceTargets list

    • accountId string

    • includeAvailableRoleInfos boolean

    Returns the User view of the specified accountId, including a list of resource targets, and whether or not to include Role information. 

    getView

    • nameOrId string

    • type string

    • options map

    Returns a view of an object specified by the name or GUID, type of object, and a map of options. 

    getUnassignedResources

    • roles list

    • currentResources list

    • groups list

    Determines which resources are currently unassigned. 

    getDirectReports

    • manager string

    • options map

    Returns a list of direct reports for a specified manager. For example, a list of users whose idmManager attribute is specified by the manager input variable.

    getIndirectReports

    • manager string

    • options map

    Returns a list of indirect reports for a specified manager. For example, a list of users who are in the reporting structure of the user specified by the manager input variable, excluding direct reports.

    getResourceObjectParentId

    • resourceName string

    • resObjectName string

    • objType string

    • objAttr string

    Returns a GenericObject of the parent of a resource specified by the name, object type, and object attribute. 

    getObjectsByType

    • type string

    • attributeVal string

    • attributeName string

    Returns a list of GenericObjects specified by type and that match the attributeName=attributeVal condition.

    getRealName

    • accountId string

    • addAccountId boolean

    Determines a user’s “real name,” such as FirstName <space> LastName, when an accountId has been provided.

    • If the addAccountId argument is true, Waveset returns the FirstName LastName (accountId) string.

    • If the FirstName or LastName attributes cannot be determined, the rule returns just the accountId.

    NOTES:

    • You can easily modify this rule if you want the real name to display as LastName, FirstName.

    • The user must have the appropriate permissions to be able to search for other users.

    The next table describes the example EndUserRuleLibrary rules used for anonymous enrollment.

    getAccountId

    • firstName string

    • lastName string

    • employeeId string

    Generates an account ID from the first name, last name, and employee ID. First initial + last intial + employee ID

    Note: International users must modify this rule to ensure that Waveset maintains ASCII accountIds and email addresses during anonymous enrollment processing.

    getEmailAddress

    • firstName string

    • lastName string

    • emailDomain string

    Generates an email address from the first name, last name, and email domain provided. firstname.lastname@emailDomain

    Note: International users must modify this rule to ensure that Waveset maintains ASCII accountIds and email addresses during anonymous enrollment processing.

    getIdmManager

    employeeId string

    Returns the account ID of the Waveset manager associated with an employee ID for a user being created. You must customize this rule for your deployment environment. (Default is configurator.)

    getOrganization

    None 

    Returns the name of the organization to which a user will be assigned. You must customize this rule for your deployment environment. (Default is Top.)

    runValidation

    None 

    Invokes verifyFirstname, verifyLastname, verifyEmployeeId, and verifyEligibility rules.

    verifyFirstname

    firstName string

    Validates the first name provided by a user for the End User Anonymous Enrollment process. This sample rule verifies a first name is not null. You must customize this rule for your deployment environment. 

    Note: International users must modify this rule to ensure that Waveset maintains ASCII accountIds and email addresses during anonymous enrollment processing.

    verifyLastname

    lastName string

    Validates the last name provided by a user for the End User Anonymous Enrollment process. This sample rule verifies a last name is not null. You must customize this rule for your deployment environment. 

    verifyEmployeeId

    employeeId string

    Validates the employee ID provided by a user for the End User Anonymous Enrollment process. This sample rule verifies that an employee ID is valid. You must customize this rule for your deployment environment. 

    verifyEligibility

    • firstName string

    • lastName string

    • employeeId string

    Can be used to validate the employee ID provided by a user for the End User Anonymous Enrollment process. This rule must be customized for deployment. 

ExcludedAccountsRule

The ExcludedAccountsRule supports the exclusion of resource accounts from resource operations.

Inputs:

Accepts the following arguments:

You must specify the following for a custom ExcludedAccountsRule rule:

AuthType 

ExcludedAccountsRule

SubType 

Not specified 

Returns 

A list of zero or more strings 

Predefined Rules 

  • Microsoft SQL Server Excluded Resource Accounts

  • Sun Access Manager Excluded Resource Accounts

  • Unix Excluded Resource Accounts

  • Windows Excluded Resource Accounts

The following example exemplifies subType use and excludes specified resource accounts for UNIX adapters.


Example 4–27 Exemplifying authType Use

<Rule name=’ExcludedResourceAccounts’ 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> 
   </defvar>
</Rule>

The next example shows how to use the operation parameter. This parameter allows you to manipulate the “Test User” resource account— without impacting Waveset— if Active Sync is running against the resource.


Example 4–28 Example Using 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>

This example shows an ExcludedAccountsRule for RACF.


Example 4–29 ExcludedAccountsRule for RACF


<Rule name="RACF EAR" authType="ExcludedAccountsRule"> 
   <RuleArgument name="accountID"/> 
   <block> 
      <defvar name="excludedList"> 
         <List> 
            <String>irrcerta</String> 
            <String>irrmulti</String> 
            <String>irrsitec</String> 
            <String>IBMUSER</String> 
         </List> 
      </defvar> 
      <cond> 
         <eq> 
            <containsAny> 
               <ref>excludedList</ref> 
               <list> 
                  <upcase> 
                     <ref>accountID</ref> 
                  </upcase> 
                  <ref>accountID</ref> 
               </list> 
            </containsAny> 
            <i>1</i> 
         </eq> 
      <Boolean>true</Boolean> 
      <Boolean>false</Boolean> 
      </cond> 
   </block> 
</Rule>

This final example shows an ExcludedAccountsRule for RACF LDAP.


Example 4–30 Excluded Accounts Rule for RACF LDAP


<Rule name="Test RACF_LDAP Case Insensitive Excluded Resource Accounts" 
authType="ExcludedAccountsRule"> 
   <RuleArgument name="accountID"/> 
   <block> 
      <defvar name="excludedList"> 
         <List> 
            <String>irrcerta</String> 
            <String>irrmulti</String> 
            <String>irrsitec</String> 
            <String>IBMUSER</String> 
         </List> 
      </defvar> 
      <defvar name="convertedId"> 
         <get> 
            <split> 
               <get> 
                  <split> 
                     <ref>accountID</ref> 
                     <s>,</s> 
                  </split> 
                  <i>0</i> 
               </get> 
               <s>=</s> 
            </split> 
            <i>1</i> 
         </get> 
      </defvar> 
      <cond> 
         <eq> 
            <containsAny> 
               <ref>excludedList</ref> 
               <list> 
                  <upcase> 
                     <ref>convertedId</ref> 
                  </upcase> 
               <ref>convertedId</ref>

getAvailableServerOptions

The getAvailableServerOptions rule determines the list of available server configuration options for the specified synchronization mechanism. Using the settings in Waveset.properties applies only for ActiveSync, and is a backwards-compatibility option.

Inputs:

Accepts the targetObjectType argument


Note –

If IDMXUser, then viaWavesetProperties is not returned in the list.


You must specify the following for a custom getAvailableServerOptions rule:

AuthType 

Not specified 

SubType 

Not specified 

Predefined Rules 

None 

InsertDictionaryWord

Use the InsertDictionaryWord rule to run a JDBC command against the Waveset dictionary to load new words into the database.

Inputs:

Accepts the following arguments:

You must specify the following for a custom InsertDictionaryWord rule:

AuthType 

Not specified 

SubType 

Not specified 

Returns 

A list of zero or more strings 

Predefined Rules 

None 

IS_DELETE

The IS_DELETE rule is a sample rule, written for the PeopleSoft Active Sync adapter, that determines whether the Active Sync event should delete a user.

Inputs:

None

You must specify the following for a custom IS_DELETE rule:

AuthType 

Not specified 

SubType 

Not specified 

Predefined Rules 

None 

Is Manager

The Is Manager rule tests specified accountIds to see whether they are managers for any other users in the system.

Inputs:

Accepts the managerId argument (<RuleArgument name=’managerId’/>)

You must specify the following for a custom Is Manager rule:

AuthType 

RoleConditionRule

SubType 

Not specified 

Returns 

True if managerId is declared as the idmManager for any user in the system, otherwise returns false.

This rule issues a query in the repository using the caller’s display.session session, meaning this rule can only be called from a Form. The check only matches users that are within organizations controlled by the caller, so the rule might return false if the managerId is the manager of users outside of the callers scope of control.

Predefined Rules 

None 

LoginCorrelationRules

The LoginCorrelationRules map user login information to an Waveset user. You specify logic in LoginCorrelationRules that enables the rule to search for an Waveset user and return a list of one or more AttributeConditions.

Inputs:

None

You must specify the following for a custom LoginCorrelationRules rule:

AuthType 

LoginCorrelationRule

SubType 

Not specified 

Called 

By a LoginModule to map login information to the Waveset user 

Returns 

A list of zero or more AttributeConditions

Predefined Rules 

  • Correlate via X509 Certificate SubjectDN

  • Correlate via LDAP Uid

My Direct Reports

The My Direct Reports rule returns the names of all Waveset users that are direct reports of the caller. Management is typically a hierarchical structure, however this rule only returns the names of users that have the caller specified as their manager. The management hierarchy is not traversed by this rule.

Inputs:

None

You must specify the following for a custom My Direct Reports rule:

AuthType 

AccessScanRule

SubType 

USER_SCOPE_RULE

Returns 

A list of Waveset user names that have the caller specified as their manager. 

Predefined Rules 

None 

NamingRules Library

The NamingRules Library is a default library of rules that enable you to control how names are displayed after rule processing.


Note –

This library is displayed as the NamingRules library object in the Identity Manager IDE.


Inputs:

None

You must specify the following for a custom NamingRulesLibrary rule:

AuthType 

Not specified 

SubType 

Not specified 

Predefined Rules 

None 

The following table lists the example NamingRules.

Table 4–6 Example NamingRules

Rule Name  

Description/Output  

AccountName— First dot Last 

Marcus.Aurelius 

AccountName— First initial Last 

MAurelius 

AccountName— First underscore Last 

Marcus_Aurelius 

Email 

marcus.aurelius@example.com  


Note –

You must append an AccountName rule to the mail domain.


Fullname— First space Last 

Marcus Aurelius 

Fullname— First space MI space Last 

Marcus A Aurelius 

Fullname— Last comma First 

Aurelius, Marcus 

NewUsernameRules

The NewUsernameRule is a standard repository initialization file that you can use to extract the value of a user distinguished name’s (DN) left most relative distinguished name (RDN).

Inputs:

None

You must specify the following for a custom NewUsernameRules rule:

AuthType 

NewUserNameRule

SubType 

Not specified 

Returns 

A proposed user name for new users upon registration. For example, Use SubjectDN Common Name extracts the jsmith from cn=jsmith,ou=engineering,dc=acme,dc=com.

Predefined Rules 

Use SubjectDN Common Name 

Object Approvers As Attestors

The Object Approvers As Attestors rule returns the provided objectapprovers parameter value if it is not null. If the objectapprovers list is not provided, this rule creates a new list and includes the Configurator user.

Inputs:

Accepts the following arguments:

You must specify the following for a custom Object Approvers As Attestors rule:

AuthType 

AccessScanRule

SubType 

ATTESTORS_RULE

Called 

By running Access Review 

Returns 

 

Predefined Rules 

None 

Object Owners As Attestors

The Object Approvers As Attestors rule returns the objectowners parameter if it is not null. If the objectowners list is not provided, the rule creates a new list and includes the Configurator user.

Inputs:

Accepts the following arguments:

You must specify the following for a custom Object Approvers As Attestors rule:

AuthType 

AccessScanRule

SubType 

ATTESTORS_RULE

Called 

By running Access Review 

Returns 

A list of Waveset user names 

Predefined Rules 

None 

Organization Names

The Organization Names rule returns a List of Display Names for all organizations within the current context.

Inputs:

None

You must specify the following for a custom Organization Names rule:

AuthType 

Not specified 

SubType 

Not specified 

Returns 

 

Predefined Rules 

None 

OS400UserFormRules

Use the OS400UserFormRules to manage the default User Form values for an OS400 resource.

Inputs:

None

You must specify the following for a custom OS400UserFormRules rule:

AuthType 

EndUserLibrary

SubType 

Not specified 

Called 

 

Returns 

See Table 4–7

Predefined Rules 

OS400 User Form Default Values 

The following table lists the example OS400UserFormRules.

Table 4–7 Example OS400UserFormRules

Rule Name 

Description 

Default Password Expiration Interval 

Returns the default value for the password expiration interval. The returned value is 90. 

Default Initial Program Call 

Returns the default initial program called for a user. The returned value is *LIB/CCTC00CLP.

Max Storage List Choices 

Returns a list of Max Storage Defaults. The values are in Kilobytes and equate to: No maximum, 10MB, 50MB, 100MB. 

Initial Menu Default 

Returns the initial menu default value. The returned value is *SIGNOFF.

Language ID Default 

Returns the default language ID value. The returned value is *SYSVAL.

Country ID Default 

Returns the default country ID value. The returned value is *SYSVAL.

Character Set Default 

Returns a list of the default character set values. The returned value is *SYSVAL.

UID Default 

Returns the UID default value. The returned value is *GEN.

Home Directory Prepend 

Path to prepend to user ID to form home directory. 

RACFUserFormRules

Use the RACFUserFormRules to specify default settings for your RACF resource account.

Inputs:

None

You must specify the following for a custom RACFUserFormRules rule:

AuthType 

EndUserLibrary

SubType 

Not specified 

Called 

From RACF User Form 

Returns 

A list of zero or more string values 

Predefined Rules 

RACF User Form Default Values 

The following table lists the example RACFUserFormRules.

Table 4–8 Example RACFUserFormRules

Rule Name 

Description 

Prepend RACF Home Dir Path 

Path prepended to accountId to form home directory.

RACF OMVS Program 

Specify a default OMVS program value. 

RACF TSO Command 

Specify a default OMVS TSO value. 

RACF Master Catalog 

Specify a default OMVS program value. 

RACF User Catalog 

Specify a default OMVS program value. 

RACF Delete TSO Segment 

Specify a default Delete TSO Segment value. 

Reconciliation Rules

The following table provides information about the common Waveset processes or tasks related to the reconciliation rules category:

Correlation Rule

Waveset invokes the Correlation rule during reconciliation to associate a resource account with one or more Waveset users.

Inputs:

Accepts a WSUser representing a resource account as returned by ResourceAdapter#getUser(WSUser)

You must specify the following for a custom Correlation rule:

AuthType 

Not specified 

SubType 

SUBTYPE_ACCOUNT_CORRELATION_RULE

Namespace 

All attribute values for the resource account defined in the schema are provided in the following format: 

account. LHS Attr Name

Called 

During reconciliation 

Returns 

Criteria you can use to select existing users that might own the specified account. A correlation rule can return criteria in any of the following forms:

  • A string that is interpreted as a WSUser NAME

  • A list of string elements that are each interpreted as a WSUser NAME

  • A list of com.waveset.object.WSAttribute elements

  • A list of com.waveset.object.AttributeCondition elements

    Waveset uses any set of criteria returned by a correlation rule to query the repository for matching users.

Predefined Rules 

Default Correlation 

Confirmation Rule

Waveset invokes the Confirmation rule during reconciliation to compare a resource account with one or more Waveset users.

Inputs:

Accepts the following arguments:

You must specify the following for a custom Confirmation rule:

AuthType 

None 

SubType 

SUBTYPE_ACCOUNT_CONFIRMATION_RULE

Namespace 

All attribute values for the resource account and all attributes in the User view are provided in the following format:

  • account.LHS Attr Name

  • user.accounts[*].*

  • user.waveset.*

  • user.accountInfo.*

Called 

During reconciliation 

Returns 

Logical true or false (1 or 0) depending on whether there is a match.

Predefined Rules 

Default Confirmation 

RegionalConstants Library

The RegionalConstants Library is a default library of rules that enable you to control how states, days, months, countries, and provinces are displayed.


Note –

This library is displayed as the RegionalConstants Rules library object in the Identity Manager IDE.


Inputs:

See Table 4–9.

You must specify the following for a custom RegionalConstants Library rule:

AuthType 

EndUserRule

SubType 

Not specified 

Returns 

A list of strings 

Predefined Rules 

Regional Constants 

The following table lists the example RegionalConstants rules.

Table 4–9 Example Regional Constants Rules

Rule Name 

Input Variable 

Description  

US States 

None 

Returns a list of the US state names. 

US State Abbreviations 

None 

Returns a list of the standard US state abbreviations. 

Days of the Week 

None 

Returns a list of the full names of the seven days of the week. 

Work Days 

None 

Returns a list of the five work days of the week (U.S.). 

Months of the Year 

None 

Returns a list of the full names of the months of the year. 

Month Abbreviations 

None 

Returns a list of the standard abbreviation for the selected month. 

Numeric Months of the Year 

None 

Returns a list of 12 months. 

Days of the Month 

None 

Returns a list of 31 days. 

Smart Days of the Month 

  • month: Month whose dates are to be calculated.

  • year: Year for the month whose dates are to be calculated.

Returns a list based on a numeric month and four-digit year. 

Countries 

None 

Lists the names, in English, of the countries of the world. 

Canadian Provinces 

None 

Lists the names, in English, of the Canadian provinces. 

Remediation Transaction Message

The Remediation Transaction Message rule is a default rule that is used to format the remediation or mitigation transaction text. You can customize this rule to provide more information for the user to sign.

Inputs:

Accepts the following arguments:

You must specify the following for a custom Remediation Transaction Message rule:

AuthType 

EndUserAuditorRule

SubType 

Not specified 

Returns 

Formatted remediation or mitigation transaction text 

Predefined Rules 

None 

Remediation Transaction Message Helper

The Remediation Transaction Message Helper rule returns the formatted transaction text for the remediation or mitigation of a single workitem.

Inputs:

Accepts the following arguments:

You must specify the following for a custom Remediation Transaction Message Helper rule:

AuthType 

EndUserAuditorRule

SubType 

Not specified 

Returns 

Formatted remediation or mitigation transaction text 

Predefined Rules 

None 

ResourceFormRules

The ResourceFormRules library is a default library of rules that enable you to customize values and choices used in several of the UserForms, which in turn are frequently used to select user attributes for resources.

Inputs:

See Table 4–10.

You must specify the following for a custom ResourceFormRules rule:

AuthType 

EndUserLibrary

SubType 

Not specified 

Called 

By UserForms, specifically

  • sample\forms\AccessEnforcerUserForm.xml

  • sample\forms\ADUserForm.xml

  • sample\forms\AIXUserForm.xml

  • sample\forms\HP-UXUserForm.xml

  • sample\forms\NDSUserForm.xml

  • sample\forms\RedHatLinuxUserForm.xml

  • sample\forms\SolarisUserForm.xml

  • sample\forms\SUSELinuxUserForm.xml

Returns 

A list of strings 

Predefined Rule: 

ResourceFormRuleLibrary 

Predefined Rules 

None 

The following table describes the example ResourceFormRules.

Table 4–10 Example ResourceFormRules

Rule Name 

Input Variable 

Description 

ListObjects 

  • resourceType

  • resourceName

  • resourceInstance

Returns a list of resource objects, such as groups, that can be used by multiple forms.

ListGroups 

  • resourceName

  • resourceInstance

Returns a list of groups that can be used by multiple forms. NOTE: This rule is provided for backward compatibility.

getDefaultShell 

resourceType

Returns a the default shell for a particular resourceType that can be used by multiple forms. Ensure that each resourceType has the same default shell as specified in the ResourceAdapter. 

Exchange Servers 

None 

Returns a list of Exchange servers. 

You can update this list to include the Exchange servers in your environment. 

Home Directory Servers 

None 

Returns a list of systems serving user home directories. 

You can update this list to include the systems that serve home directory drives in your environment. 

AD Login Scripts 

None 

Returns a list of user login scripts. 

You can update this list to include the login batch scripts in your environment. 

Home Directory Drive Letters 

None 

Returns a list of home directory mapped drive letters. 

You can update this list to include the common home directory map drive letters in your environment. 

Home Directory Volumes 

None 

Returns a list of home directory volume names. 

You can update this list to include the common home directory volume names in your environment. Waveset uses this value with the Home Directory server to create a user’s home directory. The volume must exist and it must be shared on the selected home directory server. 

NDS Home Directory Servers 

None 

Returns a list of systems serving user home directories. 

You can update this list to include the systems that serve home directory drives in your environment. 

NDS Home Directory Types 

None 

Returns a list of home directory mapped drive letters. 

You can update this list to include the common home directory map drive letters in your environment. 

NDS Home Directory Volumes 

None 

Returns a list of home directory volume names. 

You can update this list to include the common home directory volume names in your environment. Waveset uses this value with the Home Directory server to create a user’s home directory. The volume must exist and it must be shared on the selected home directory server. 

NDS Template 

  • resourceName

  • ndsTemplate

  • attrList

Returns an NDS Template object. 

Is Mail User 

objectClasses 

Returns 1 if the objectClasses list contains all the following classes, otherwise returns 0:

  • inetuser

  • ipuser

  • inetmailuser

  • inetlocalmailrecipient

  • userpresenceprofile

getResourceAttribute 

  • resName

  • attrNam

Returns the value of the requested resource attribute. 

Resource Names

The Resource Name rule returns a list of Resources within the current context.

Inputs:

None

You must specify the following for a custom Resource Names rule:

AuthType 

Not specified 

SubType 

Not specified 

Returns 

A list of resources 

Predefined Rules 

None 

Role Approvers

The Role Approvers rule provides a list of users who are approvers for a specified role.

Inputs:

Accepts the roleName argument

You must specify the following for a custom Role Approvers rule:

AuthType 

RoleUserRule

SubType 

Not specified 

Returns 

A list of the statically defined approvers for a given role 

Predefined Rules 

None 

Role Notifications

The Role Notifications rule provides a list of users who are designated to be notified when a role is assigned to a user.

Inputs:

Accepts the roleName argument

You must specify the following for a custom Role Notifications rule:

AuthType 

RoleUserRule

SubType 

Not specified 

Returns 

A list of the statically defined approvers for a given role 

Predefined Rules 

None 

Role Owners

The Role Owners rule provides a list of users who are the owners of a specified role.

Inputs:

Accepts the roleName argument

You must specify the following for a custom Role Owners rule:

AuthType 

RoleUserRule

SubType 

Not specified 

Returns 

A list of the statically defined approvers for a given role 

Predefined Rules 

None 

Sample On Local Network

The Sample On Local Network rule is an example of a LoginConstraintRule evaluated during login to determine if the login module group will be applied to the user login.

Inputs:

None

You must specify the following for a custom Sample On Local Network rule:

AuthType 

LoginConstraintRule

SubType 

Not specified 

Called 

During login processing by the login module group 

Returns 

  • Returns 1 (true) if the user IP address matches a specific subnet so the login module group should be applied.

  • Returns 0 (false) if the user IP address does not match a specific subnet.

Predefined Rules 

None 

SAP Portal User Form Default Values

The SAP Portal User Form Default Values library is a default library of rules that provide default values for the SAP Portal User Form.

Inputs:

None

You must specify the following for a custom SAP Portal User Form Default Values rule:

AuthType 

Library

SubType 

Not specified 

Called 

During login processing by the login module group 

Returns 

See Table 4–11.

Predefined Rules 

None 

The following table describes the example SAP Portal User Form Default Values.

Table 4–11 Example SAP Portal User Form Default Values Rules

Rule Name 

Input Variable 

Description 

Countries-ISO3166 Map 

None 

Returns a map of ISO3166 country codes. 

Currency Code Map 

None 

Returns a map of country codes. 

Locale Map 

None 

Returns a map of locales. 

TimeZones 

None 

Returns a list of timezone IDs. 

ShellRules

The ShellRules library consists of one rule, called getDefaultShell. Multiple forms use the getDefaultShell rule to return the default shell for a particular Unix resourceType.

Inputs:

Accepts the resourceType argument.

The only valid resourceTypes are Solaris, AIX, HP-UX, and Red Hat Linux


Note –

Each resourceType must have the same default shell as specified in the ResourceAdapter.


You must specify the following for a custom ShellRules rule:

AuthType 

Not specified 

SubType 

Not specified 

Returns 

A string that contains the default shell for the specified resourceType.

Predefined Rules 

None 

SIEBEL_NAV_RULE

The SIEBEL_NAV_RULE is a sample navigation rule that could be specified as the AdvancedNavRule, as discussed in the “Advanced Navigation” section of the Siebel CRM documentation.

Inputs:

None

You must specify the following for a custom SiebelNavigationRule:

AuthType 

Not specified 

SubType 

Not specified 

Predefined Rules 

None 

TestDictionary

Use the TestDictionary rule to run a JDBC query against the Waveset dictionary to test the connection.

Inputs:

Accepts the following arguments:

You must specify the following for a custom TestDictionary rule:

AuthType 

Not specified 

SubType 

Not specified 

Predefined Rules 

None 

TopSecretUserFormRules

Use the TopSecretUserFormRules to specify default settings for your TopSecret resource account.

Inputs:

None

You must specify the following for a custom TopSecretUserFormRules rule:

AuthType 

EndUserLibrary

SubType 

Not specified 

Called 

From TopSecret User Form 

Returns 

See Table 4–12.

Predefined Rules 

None 

The following table describes the example TopSecretUserFormRules.

Table 4–12 Example TopSecretUserFormRules

Rule Name 

Description  

TopSecret Default OMVS 

Determines the default OMVS shell. 

TopSecret Default TSO 

Determines the default TSO Process. 

TopSecret Home Prepend Path 

Path to prepend to accountId to create home directory.

TopSecret Attribute List 

Returns a list of attributes that can be assigned to a user. 

User Members Rule

The User Members Rule enables you to dynamically control a single organization’s user membership, based on who is logged in. For example, if you assign the User Members Rule to the My Employees organization, the rule dynamically controls the organization’s user membership as follows:

Inputs:

You must specify the following for a custom User Members Rule rule:

AuthType 

UserMembersRule

SubType 

Not specified 

Called 

 

Returns 

  • A list of resource accountIds

    You can return resource accountIds by invoking the FormUtil.getResourceObjects call to, for example, return all user entries in a specified directory OU.

    Returned resource accountIds must be in one of the following formats:

    • resourceId:accountId

    • resourceId@accountId


     <list>
        <s>res1:stevel</s>
        <s>res1:joem</s>
        <s>res1:sallyp</s>
      </list>
  • A list of Waveset AttributeConditions used to query the Waveset repository for users matching the specified condition.


    <list>
        <new class=’com.waveset.object.AttributeCondition>
          <s>idmManager</s>
          <s>equals</s>
          <ref>waveset.accountId</s>
        </new>
    </list>

Predefined Rules 

None 

USER_EMAIL_MATCHES_ACCOUNT_EMAIL_CONF

The USER_EMAIL_MATCHES_ACCOUNT_EMAIL_CONF rule is a confirmation rule that compares an Waveset user to an account.

Inputs:

None

You must specify the following for a custom USER_EMAIL_MATCHES_ACCOUNT_EMAIL_CONF rule:

AuthType 

Not specified 

SubType 

SUBTYPE_ACCOUNT_CONFIRMATION_RULE

Returns 

True if the email attribute values match

Predefined Rules 

None 

USER_EMAIL_MATCHES_ACCOUNT_EMAIL_CORR

The USER_EMAIL_MATCHES_ACCOUNT_EMAIL_CORR rule is a correlation rule that searches for a Waveset user with an email attribute value that matches the email attribute value in the specified account.

Inputs:

None

You must specify the following for a custom USER_EMAIL_MATCHES_ACCOUNT_EMAIL_CORR rule:

AuthType 

Not specified 

SubType 

SUBTYPE_ACCOUNT_CORRELATION_RULE

Returns 

A list of attribute conditions 

Predefined Rules 

None 

USER_FIRST_AND_LAST_NAMES_MATCH_ACCOUNT

The USER_FIRST_AND_LAST_NAMES_MATCH_ACCOUNT rule is a confirmation rule that compares an Waveset user to an account by looking for a fullname attribute.

Inputs:

None

You must specify the following for a custom USER_FIRST_AND_LAST_NAMES_MATCH_ACCOUNT rule:

AuthType 

Not specified 

SubType 

SUBTYPE_ACCOUNT_CONFIRMATION_RULE

Return 

True if first name and last name values match, otherwise returns false

Predefined Rules 

None 

USER_NAME_MATCHES_ACCOUNT_ID

The USER_NAME_MATCHES_ACCOUNT_ID rule is a correlation rule that searches for an Waveset user with the same name as the user in the specified account.

Inputs:

None

You must specify the following for a custom USER_NAME_MATCHES_ACCOUNT_ID rule:

AuthType 

Not specified 

SubType 

SUBTYPE_ACCOUNT_CORRELATION_RULE

Return 

Returns a string value 

Predefined Rules 

None 

USER_OWNS_MATCHING_ACCOUNT_ID

The USER_OWNS_MATCHING_ACCOUNT_ID rule is a correlation rule that searches for any Waveset user that owns an accountId matching the name of the specified account.

Inputs:

None

You must specify the following for a custom USER_OWNS_MATCHING_ACCOUNT_ID rule:

AuthType 

Not specified 

SubType 

SUBTYPE_ACCOUNT_CORRELATION_RULE

Return 

A list of attribute conditions 

Predefined Rules 

None 

Users Without a Manager

The Users Without a Manager rule determines which Waveset users are administrators.

Inputs:

None


Note –

This rule uses the lhcontext variable from the calling scope.


You must specify the following for a custom Users Without a Manager rule:

AuthType 

AccessScanRule

SubType 

USER_SCOPE_RULE

Returns 

A list of user names that do not have a manager defined. 

Predefined Rules 

None 

Use SubjectDN Common Name

The Use SubjectDN Common Name rule to return a subject’s common name from the subject’s DN.

Inputs:

None

You must specify the following for a custom Use SubjectDN Common Name rule:

AuthType 

NewUserNameRule

SubType 

Not specified 

Returns 

A common name 

Predefined Rules 

None 

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 4–13 provides an overview of the rules you can use to customize how audit policy remediation works and how access scans operate.

Table 4–13 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: AttestorEscalationRule

AuthType: 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_RULE

AuthType: AccessScanRule

Automates the attestation process by automatically rejecting user entitlement records. 

 

Review Changed Users 

SubType: REVIEW_REQUIRED_RULE

AuthType: AccessScanRule

Automates the attestation process by automatically approving user entitlement records. 

 

Review Everyone 

SubType: REVIEW_REQUIRED_RULE

AuthType: 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: EndUserAuditorRule

Customization— allows the deployment to specify what are valid violation priorities and the corresponding display strings. 

ViolationSeverity 

ViolationSeverity 

SubType: Not specified

AuthType: EndUserAuditorRule

Customization— 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 Waveset 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 Waveset.

Inputs:

Accepts the following arguments:

You must specify the following for a custom Attestor rule:

AuthType 

AccessScanRule

SubType 

ATTESTORS_RULE

Called 

During access scan; after evaluating all audit policies, but before dispatching the user entitlement 

Returns 

A list of zero or more Waveset attestor names (users responsible for attesting a particular user entitlement) or NamedValue pairs.

  • If the result is a string, it must resolve to an Waveset account ID. If delegation is enabled for the access scan, the access scan will use the delegation settings of the Waveset 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 –

    If the rule returns NamedValue pair elements, they are passed on without validation.


  • If the result is not a valid Waveset 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 Rules 

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 arguments:

You must specify the following for a custom Attestor Escalation rule:

AuthType 

AccessScanRule

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 Waveset account names.

  • If the attestor does not have a manager, the Attestor Escalation rule returns Configurator.

  • If the result is an invalid account name or null, the attestation workitem is not escalated.

Predefined Rules 

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.

Inputs:

None

You must specify the following for a custom Audit Policy rule:

AuthType 

AuditPolicyRule


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 to create an Audit Policy rule, be sure to specify the AuditPolicyRule authType.


SubType 

  • SUBTYPE_AUDIT_POLICY_RULE (for an audit policy rule)

  • SUBTYPE_AUDIT_POLICY_SOD_RULE (for an audit policy SOD rule)

    SOD (separation of duties or segregation of duties) rules differ from regular rules in that they are expected to produce a list element in the rule output. A list element is not required; but if one is not present, it causes any corresponding violations to be ignored in SOD reporting.

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: 

  • A pure integer:


    <i>1</i>
  • An integer within a map of additional data:


    <map>
      <s>result</s>
      <i>1</i>
      ...
    </map>

    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.)


      <s>resources</s>
      <list>
          <s>resource one</s>
          <s>resource two</s>
      </list>
    • severity element: Causes the compliance violation to have the specified severity. (Default is 1.)


      <s>severity</s>
      <i>3</i>
    • priority element: Causes the compliance violation to have the specified priority. (Default is 1.)


      <s>priority</s>
      <i>2</i>
    • violation element: Prevents the audit scanner from creating a rule violation— even if the audit policy evaluates to true.

      By default, if the audit policy evaluates to true, it creates compliance violations for each rule that returns a non-zero. Setting this element to zero allows the rule to return true, but does not create a violation for the rule.


      <s>violation</s>
      <i>0</i>

Note –

The Audit Policy Wizard only creates rules that reference a single resource and return an integer value (not a map).

To use any of the preceding map-related features, you must write the rule yourself. Some very sophisticated audit policy rule examples are provided in sample/auditordemo.xml.


Predefined Rules 

  • 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.


Note –

The RULE_EVAL_COUNT value equals the number of rules that were evaluated during a policy scan. Waveset calculates this value as follows:

RULE_EVAL_COUNT = # of users scanned x (# of rules in policy + 1)

The +1 is included in the calculation because Waveset also counts the policy rule, which is the rule that actually decides if a policy is violated. The policy rule inspects the audit rule results, and performs the boolean logic to come up with a policy result.

For example, if you have Policy A with three rules and Policy B with two rules, and you scanned ten users, the RULE_EVAL_COUNT value equals 70 because

10 users x (3 + 1 + 2 + 1 rules)

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 argument (Remediation WorkItem)

You must specify the following for a custom Remediation User Form rule:

AuthType 

Not specified 

SubType 

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. 

Predefined Rules 

None 

Location 

  • Compliance > Manage Policies > Access Scan > Remediation User Form Rule

  • Compliance > Manage Policies > Audit Policy > Remediation User Form Rule

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 arguments:

You must specify the following for a custom Remediator rule:

AuthType 

AccessScanRule

SubType 

REMEDIATORS_RULE

Called 

During access scan, after evaluating all audit policies and before dispatching the user entitlement 

Returns 

A list of zero or more Waveset remediator names or NamedValue pairs.

  • If the result is a string, it is resolved to a Waveset 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 Waveset 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.


Note –

If the rule returns NamedValue pair elements, they are passed on without validation.


Predefined Rules 

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 the record must be manually attested. A user entitlement is a complete User view (in which some resources might be omitted) and some tracking data.

You can use the Review Determination rule to significantly increase the efficiency of an access review by


<map>
   <result>
   <i>1</i>
   <s>reason</s>
   <s><reason the attestation was auto-approved/rejected></s>
   <s>attestorHint</s>
   <s><hint to attestor></s>
</map>

<set name=’viewCompare’>
<!-- compare the entire view (3rd argument can specify sub-path) -->
   <invoke name=’compareUserViews’ class=’com.sun.idm.auditor.ui.FormUtil’>
      <ref>userView</ref>
      <ref>lastUserView</ref>
      <s>accounts</s>
   </invoke>
</set>

This argument compares User views and allows the caller to specify a subpath of the complete User view using GenericObject path expressions. If you just want to compare particular account data, the subpath can specify that data. If you compare just the accounts subpath of the User view, you are less likely to encounter differences that are not reflected on a real resource.

Differences found in the User view comparison are returned in the reason element of the output map. The audit log captures this difference data if the rule returns 0 (reject attestation) or 2 (approve attestation), just as the predefined Reject Changed Users rule does.

You can use the Reject Changed Users rule to verify exactly what Waveset thinks is different and you can look at the auditable attributes in the resulting audit log records.

Inputs:

Accepts the following arguments:

You must specify the following for a custom Review Determination rule:

AuthType 

AccessScanRule

SubType 

REVIEW_REQUIRED_RULE

Called 

During access scan, after evaluating all audit policies and before dispatching the user entitlement 

Returns 

An integer or a map 

  • If the rule returns an integer, its value is interpreted as follows:

    • -1: No attestation required

    • 0: Automatically reject attestation

    • 1: Manual attestation

    • 2: Automatically approve attestation

    • 3: Automatically remediate attestation

      When the attestation is set to auto-remediating mode, Waveset creates an AccessReviewRemediation work item and routes the work item through the Remediator rule associated with the access scan.

  • If the rule returns a map, the output must be similar to one of the following examples:

    Example 1: Manually attests the user entitlement, and 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>

    Note –

    The attestorHint value in the output map must be a string or a list of strings.


    Example 2: Automatically rejects the user entitlement. The rejection comment indicates that group membership is disallowed.


    <map>
      <s>result</s>
      <i>0</i>
      <s>reason</s>
      <s>User belongs to group Domain Administrators</s>
    </map>

    Note –

    The value of attestorHint is shown to the attestor through the user interface. The value of reason is recorded in the attestation history.


Predefined Rules 

  • Reject Changed Users: Automatically rejects user entitlements that have changed since the last approval state, and automatically approves user entitlements that are unchanged. The rule only compares the accounts section of the User view.

    Each unknown User view is forwarded for manual attestation.

  • Review Changed Users: Automatically approves any users whose account data has not changed since their last approved entitlement. The rule only compares the accounts section of the User view.

    Users with changed account data or no approved data must be manually attested.

  • 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 argument

You must specify the following for a custom User Scope rule:

AuthType 

AccessScanRule

SubType 

USER_SCOPE_RULE

Called 

At the beginning of an access scan 

Returns 

An Waveset user name or a list of Waveset user names. Each name must be a valid Waveset user name.

  • If the results contain any names that cannot be resolved to valid Waveset 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.


Predefined Rules 

  • All Administrators: Returns all users with administrative capabilities assigned.

  • All Non-Administrators: Returns all users with no administrative capabilities assigned.

  • Users Without Manager: Returns all user accounts with no manager (idmManager) assigned.

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.

Inputs:

None

You must specify the following for a custom ViolationPriority rule:

AuthType 

EndUserAuditorRule

SubType 

Not specified 

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 Rules 

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.

Inputs:

None

You must specify the following for a custom ViolationSeverity rule:

AuthType 

EndUserAuditorRule

SubType 

Not specified 

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 Rules 

ViolationSeverity 

Location 

Called from the Remediation List Form 

Sample Auditor Rule Multiple Account Types

The following example demonstrates how to use the Sample Auditor Rule Multiple Account Types rule. The location of the rule is


sample/rules/SampleAuditorRuleMultipleAccountTypes.xml

ProcedureTo Dynamically Test Multiple User Accounts per Resource

  1. Set up a resource with multiple account types.


    <?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>
  2. 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
  3. Assign different values for each account and test the policy rule.

    Location:


    sample/rules/SampleAuditorRuleMultipleAccountTypes.xml

Audit Policy 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.


<map>
  <s>result</s>
  <i>1</i>
  <s>severity</s>
  <i>3</i>
  <s>priority</s>
  <i>4</i>
</map>

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 creating a ComplianceViolation, you can view and change the 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 a more-detailed view affects performance, which may be unacceptable for deployments with lots of Remediations.


Service Provider Rules

This section describes the following example Service Provider rules:

Service Provider Confirmation Rules

The example Service Provider confirmation rules have access to the list of candidate accountIds under the candidates path and to the Service Provider User view under the view path.

Inputs:

None

You must specify the following for a custom Service Provider confirmation rule:

AuthType 

SPERule

SubType 

SUBTYPE_SPE_LINK_CONFIRMATION_RULE

Returns 

A null or a string representing the confirmed accountId 

Predefined Rules 

None 

The following table describes the example confirmation rules you can use to customize Service Provider.

Table 4–14 Example Service Provider Confirmation Rules

Rule Name  

Description  

Service Provider Example Confirmation Rule Rejecting All Candidates 

Rejects all candidates from a link correlation rule.Returns a null. 

Service Provider Example Confirmation Rule Returning First Candidate 

Returns the first accountId from the candidate list. 

Service Provider Example Confirmation Rule Selecting Candidates Using AccountId 

Returns the candidate that matches the accountId in the view. If the rule cannot find the accountId from the view in the candidate list, then the rule returns a null.

Service Provider Correlation Rules

The example Service Provider correlation rules have access to the Service Provider User view.

Inputs:

None

You must specify the following for a custom Service Provider correlation rule:

AuthType 

SPERule

SubType 

SUBTYPE_SPE_LINK_CORRELATION_RULE

Return 

A single accountId, a list of accountIds, or an option map

  • If the rule returns a list of accountIds, then you must set a confirmation rule to determine the selected accountId.

  • If the rule returns an option map, then the view handler first retrieves a list of identities from the resource adapter by invoking the listResourceObjects context call with the provided option map.

Predefined Rules 

None 

The following table describes the example correlation rules you can use to customize Service Provider.

Table 4–15 Example Service Provider Correlation Rules

Rule Name  

Description  

Service Provider Example Correlation Rule for LDAP Returning Option Map 

Returns an option map with a search filter to be used with an LDAP adapter. The LDAP Resource Adapter allows a filter to be passed to scope the search operation. The filter is expected to be an LDAP search filter. 

Service Provider Example Correlation Rule for Simulated Returning Option Map 

Returns an option map with a search filter to be used with a Simulated Resource Adapter. The Simulated Resource Adapter allows a filter to be passed to scope the search operation. This adapter expects the search filter to be an AttributeExpression.

Service Provider Example Correlation Rule Returning List of Identities 

Returns a list of accountIds in LDAP DN format that are composed from the accountId in the view. 

Service Provider Example Correlation Rule Returning Single Identity 

Returns a single accountId in LDAP DN format composed from the account Id in the view. 

Service Provider Account Locking Rules

The example Service Provider account locking rules have access to the Service Provider User view and they lock or unlock accounts in a Sun Directory Server.

Inputs:

See Table 4–16.

You must specify the following for a custom Service Provider account locking rule:

AuthType 

SPERule

SubType 

Not specified 

Returns 

Nothing 

Predefined Rules 

None 

The following table describes the example account locking rules you can use to customize Service Provider.

Table 4–16 Example Service Provider Account Locking Rules

Rule Name 

Input Variable 

Description  

Service Provider Example Lock Account Rule 

lockExpirationDate: A possibly null java.util.Date at which the lock should expire.

Locks an account in a Sun Directory Server. This rule modifies top-level attributes in the Service Provider user view. 

Service Provider Example Unlock Account Rule 

None 

Unlocks an account in a Sun Directory Server. This rule modifies top-level attributes in the Service Provider user view.