Developing and Testing Rule Logic

Key Takeaways

  • Use the documented rule element type and only the inputs supplied to that hook.

  • Handle null and unexpected types before reading or converting values.

  • Match each return case to the selected hook’s contract and expected destination type.

  • Validate the artifact, run local logic tests and verify actual sandbox execution after the appropriate installation path.

Last updated: November 2026

Read the signature before writing code

SailPoint's Java-like BeanShell rule syntax operates within a provided runtime. Start from the official template for the exact hook. For a cloud Identity Attribute rule, the documented inputs include the identity being calculated, the previous value as an object, the supported rule utility, and the logger. The return is the computed attribute value. Choose a return type appropriate to the mapped attribute. A Before Provisioning rule instead changes the supplied plan within its supported contract and has no returned output. Connector hooks have distinct signatures and may use an entirely different runtime, such as PowerShell invoked by the supported IQService path.

The cloud rule example below illustrates syntax using an already available identity attribute named routeTagInput. The destination is a single text field. In this scenario, retain a prior text value if the input is missing, blank or the wrong type. Use unmapped if there is no prior text value. This is a teaching sample for a non-security-critical label. Holding a previous value during upstream failures would be a separate policy decision for attributes used in entitlement or lifecycle rules.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Rule PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<Rule name="Compute route label" type="IdentityAttribute">
  <Description>Returns a trimmed routing label for this identity.</Description>
  <Source><![CDATA[
    Object raw = null;
    if (identity != null) {
      raw = identity.getAttribute("routeTagInput");
    }
    if (raw instanceof String) {
      String label = ((String) raw).trim();
      if (label.length() > 0) {
        return label;
      }
    }
    if (oldValue instanceof String) {
      return oldValue;
    }
    return "unmapped";
  ]]></Source>
</Rule>

The rule type tells the platform which contract applies. The description records the intent for review. The rule name identifies the installed object that the mapping uses. Renaming an artifact or changing how it is attached calls for checking the relevant mapping in the target tenant. The code lives in its Source element with a CDATA section, allowing characters in the script to be stored as text rather than interpreted as XML markup. In the body, identity != null guards the method call. The instanceof check is false for null and verifies the type before the cast. Trimming and checking the resulting length separates whitespace-only text from a usable value. Each branch either returns the computed string, returns the previous text by policy, or uses the fallback. No data model object is saved inside the rule.

Inputs to the sampleExpected expression resultReason
An identity with " North " and an old value of "West""North"Trimmed non-empty string wins
An identity with three spaces and an old value of "West""West"Trimmed input is empty and prior text is available
A null identity with a null prior value"unmapped"Neither usable input nor prior text is available
A numeric raw value and a prior value of "West""West"Type check prevents using non-text as a label

Test behavior at the correct layer

Begin with similar input/output samples for the real business logic. The Rule Development Kit shows evaluating rule source with BeanShell and mocked platform objects, then asserting results. Verify the expected text or documented no-value result for each path. Test a missing return input, malformed data, multiple candidate matches where applicable, and repeat execution. A mock demonstrates logic under that mock's assumptions. Choose accurate contracts for provided objects and test the map or mutation instead of asserting a scalar in a hook with a different output.

Run the appropriate validator to identify forbidden constructs or unsupported operations and review the artifact. For cloud rules, follow the documented review and installation process before testing in the sandbox tenant. Select the installed Identity Attribute rule through the identity profile's Complex Data Source option and check resulting values in that environment. A vendor rule integrity review does not demonstrate the customer's business result. Avoid arbitrary outbound connections, background threads, sensitive logging or writes to platform objects. Use sparse diagnostic logs and account for who can access them. Check the affected identity or source result at runtime before a wider promotion.

See SailPoint’s Identity Attribute inputs, output and template, rule guidelines, Before Provisioning signatures, and Rule Development Kit.

Test Your Knowledge

In the shown routing label rule, routeTagInput is two spaces and oldValue is the string "East". What does the rule return?

A

Two spaces.

B

The empty string.

C

"unmapped".

D

"East".

Test Your Knowledge

Why should a test of a Before Provisioning rule inspect the plan after the rule runs?

A

The hook’s documented result is a modification of the supplied plan. It has no returned output to assert.

B

The hook always returns a new identity object.

C

It must return the target account password.

D

The hook persists the identity directly instead of modifying its instructions.

Sections you finish are checked off in the contents.