9.1 The Purpose and Use of Rule Libraries

The Purpose and Use of Rule Libraries

Objective 4.1 asks you to understand the purpose and use of rule libraries. First, the basics of rules.

Rules and Scripts

IdentityIQ lets integrators add custom business logic at defined points using BeanShell, a Java-based scripting language that can use any Java class available to IdentityIQ, including custom code. The documentation separates two forms:

• Rules are standalone objects (Rule) that other objects refer to. For example, an application references a Correlation rule, and a certification references an Exclusion rule.
• Scripts are BeanShell embedded inside the object that uses them, such as a workflow step, a policy, or a form field.

Most rules have a type, such as Correlation, BuildMap, CertificationExclusion, or PolicyOwner. The type decides which drop-down lists offer the rule and which inputs and outputs it gets (section 9.2). For example, the Policy Owner selector on the Edit Policy page shows only rules of type PolicyOwner.

Creating Rules

• Rule Editor: click [...] beside a rule field. You can copy an existing rule, name it, and see its type-specific Arguments and Returns (read-only). Warning: the editor does not validate the code. A syntactically broken rule saves anyway and fails later at run time. Access to the Rule Editor can be restricted.
• Import rule XML: use Global Settings > Import from File or the console import command. One file may contain several rules. This is how rules move between environments (section 3.1).
• Samples: WEB-INF/config/examplerules.xml has an example of each rule type. Rapid Setup samples are in WEB-INF/config/rapidsetup/rsexamplerules.xml.

What a Rule Library Is

A rule library is a Rule object that contains a collection of related but unconnected methods, not one piece of logic that runs top to bottom. Other rules and workflow scripts call those methods. SailPoint keeps these methods in Rule objects, rather than compiled Java, so each installation can easily modify them. The product ships several, including Workflow Library, Approval Library, and LCM Workflow Library. You can view them in the Debug pages or the console.

Referencing a Library from a Rule

<Rule name="Correlation - HR" type="Correlation">
  <ReferencedRules>
    <Reference class="sailpoint.object.Rule" name="ACME Common Library"/>
  </ReferencedRules>
  <Source>
    return buildCorrelationMap(account);   // method defined in the library
  </Source>
</Rule>

Referencing a Library from a Workflow

<RuleLibraries>
  <Reference class="sailpoint.object.Rule" name="Workflow Library"/>
  <Reference class="sailpoint.object.Rule" name="Approval Library"/>
  <Reference class="sailpoint.object.Rule" name="LCM Workflow Library"/>
</RuleLibraries>

Each Reference names one library. Include only the libraries whose methods the workflow needs. Custom libraries use the same syntax.

A typical custom library looks like this:

// Rule "ACME Common Library" (no type needed for a pure library)
import sailpoint.object.Identity;
import java.util.HashMap;
import java.util.Map;

public Map buildCorrelationMap(Object account) {
    Map result = new HashMap();
    String empId = (String) account.getAttribute("EMPLOYEE_ID");
    if (empId != null) {
        result.put("identityAttributeName", "employeeId");
        result.put("identityAttributeValue", empId.trim());
    }
    return result;
}

public boolean isContractor(Identity id) {
    return id != null && "Contractor".equals(id.getAttribute("type"));
}

Rule Libraries vs. Workflow Libraries vs. Step Libraries

Three "library" ideas appear in IdentityIQ, and the exam likes to mix them up:

If a workflow has no libraries attribute, it can use the Identity, Role, PolicyViolation, and LCM workflow libraries by default. If you list libraries, you must include every one you need, because the list replaces the default. There is one more wrinkle: methods from a Java workflow library called inside a script must be imported in that script. The documentation's example imports sailpoint.workflow.IdentityRequestLibrary before calling it.

Why and When to Use Rule Libraries

• Don't repeat yourself. Put name-formatting, correlation-key, and lookup logic in one place and call it from Correlation, IdentityCreation, and FieldValue rules.
• Keep specialized rules small. The typed rule becomes a thin wrapper that calls library methods, which makes review and testing easier.
• Change without redeploying Java. Libraries are XML objects, so an import updates behavior without a restart.
• Remember the reuse warning. The documentation notes that one rule can be reused in many places, such as two applications sharing a BuildMap rule. A change affects every place it is used. If behavior must differ, create separate rules.
• Watch performance. Library methods called by aggregation-time rules run for every record. Expensive lookups multiply quickly.