9.2 Rule Input and Output Arguments

Rule Input and Output Arguments

Objective 4.2 asks you to understand and leverage rule input and output arguments. Writing correct logic in the wrong shape, such as returning a String where a Map is expected, is the most common rule bug. It is also a favorite exam distractor.

The Signature

A rule's XML can declare a <Signature> listing its inputs and outputs:

<Rule name="Correlation - HR" type="Correlation">
  <Signature returnType="Map">
    <Inputs>
      <Argument name="environment"/>
      <Argument name="application"/>
      <Argument name="account"/>
      <Argument name="link"/>
    </Inputs>
    <Returns>
      <Argument name="identityAttributeName"/>
      <Argument name="identityAttributeValue"/>
    </Returns>
  </Signature>
  <Source>...</Source>
</Rule>

The Rule Editor shows these as Arguments and Returns, and you cannot change them there. Inputs arrive as named BeanShell variables, so you use account, not a parameter list. The signature documents the contract, and the rule type decides what IdentityIQ actually passes.

Variables Every Rule Gets

• context – the SailPointContext, your gateway to the database and API (section 9.3).
• log – a logger for debug and error output (section 14.1).

Contracts for the Most-Tested Rule Types

Correlation Example: Returning the Right Shape

import java.util.HashMap;
import java.util.Map;
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;   // empty map = no match; the account stays uncorrelated

IdentityCreation Example: Modify, Do Not Replace

String first = (String) account.getAttribute("FIRST_NAME");
String last  = (String) account.getAttribute("LAST_NAME");
identity.setFirstname(first);
identity.setLastname(last);
identity.setAttribute("type", "Employee");
// no return value: IdentityIQ saves the identity object it passed in

A rule that builds a brand-new Identity and returns it breaks the contract. IdentityIQ keeps using the object it passed in.

BuildMap Example: Shaping One Row

A delimited HR file has a single FULL_NAME column, but IdentityIQ needs first and last names. The BuildMap rule receives the column list (cols) and one row (record) and returns the attribute map for that account:

import java.util.HashMap;
import java.util.Map;
Map map = new HashMap();
for (int i = 0; i < cols.size(); i++) {
    map.put(cols.get(i), record.get(i));
}
String full = (String) map.get("FULL_NAME");
if (full != null && full.contains(" ")) {
    map.put("FIRST_NAME", full.substring(0, full.indexOf(" ")));
    map.put("LAST_NAME", full.substring(full.lastIndexOf(" ") + 1));
}
return map;

The returned keys must match the account schema attribute names. Otherwise the values are ignored when the ResourceObject is built.

Workflow Rules and Scripts

Rules of type Workflow, and scripts inside steps, transitions, and initializers, receive:

• wfcontext – the WorkflowContext, holding variables, step arguments, the current step, the workflow, and the WorkflowCase.
• Every workflow variable by name, plus any step arguments declared before the current one.

The return value can be captured in the step's resultVariable, used as a transition condition (it must be Boolean), or used as an argument or initializer value.

Calling a Rule From Code

You can run a rule and pass it inputs from another rule or script:

import sailpoint.object.Rule;
import java.util.HashMap;
import java.util.Map;
Rule r = context.getObjectByName(Rule.class, "ACME - Compute Username");
Map args = new HashMap();
args.put("firstname", "Ana");
args.put("lastname", "Silva");
Object username = context.runRule(r, args);   // map keys become variables

Common Mistakes

• Returning a String identity name from a Correlation rule instead of a Map.
• Returning a new Identity from an IdentityCreation rule instead of changing identity.
• Returning null from a Customization rule when you meant to keep the object. Always return the object you changed.
• Transition scripts that return a non-Boolean value.
• Relying on a variable that is not in that rule type's inputs. Check the Arguments list in the Rule Editor or the sample in examplerules.xml.