Skip to content

Rules and Scripts in IdentityIQ

Rules in IdentityIQ allow the addition of custom business logic at specific points within the execution flow of the product. To enable this, IdentityIQ allows system integrators to write rules in the BeanShell scripting language. The BeanShell language is based on Java and can use all Java classes that are available to IdentityIQ, including custom code.troubleshooting process.

Types of Rules and Scripts

Rules and scripts are used in many places within IdentityIQ, including but not limited to:

  • Modifying IdentityIQ behavior

  • Validating and customizing aggregated data

  • Filtering and modifying data during provisioning

  • Advanced correlation of application accounts to Identity Cubes

In addition to these standard purposes, rules can implement automated tasks and perform advanced actions not contained in the standard features of IdentityIQ.

Scripts are similar to rules; the main difference between them is where they are stored. Scripts are embedded in the objects that use them, such as policy objects and workflows, whereas rules are separate objects that are referred to by the objects that use them.

How Rules Are Created

Rules are created within IdentityIQ in one of two ways: through the UI-based Rule Editor, and by importing rule XML objects.

See Using the Rule Editor and Importing Rule XML for details.

Type Attributes in Rules

Specialized rules must have a type attribute so that they can be selected from dropdown menus throughout the application. Each specialized type also has its own set of input and output variables and, optionally, a return value.

In each area where you can select a rule, you are limited to choosing (or creating) rules of the type that is appropriate to the feature. For example, in the Edit Policy page, the Policy Owner rule dropdown only lets you choose rules of the type "PolicyOwner."

The rule type is shown in both the Rule Editor, and in the rule's signature in the Debug pages.

Using the Rule Editor

Rules are associated with system activities on a variety of pages (such as the Schedule Certification, Edit Application, and Edit Policy pages), and throughout the IdentityIQ user interface. At these points, an existing rule can be selected to attach to the activity. Most, but not all, of these UIs also provide an entry point to the Rule Editor, for writing new rules or editing existing rules. Some UIs, such as the Rapid Setup Configuration pages, allow you to select rules but do not provide a direct link to the Rule Editor.

To edit an existing rule, first select the rule, then click the [...] button to open the Rule Editor.

To create a new rule, click the [...] button without selecting an existing rule, and a blank Rule Editor window is opened where you can create a new rule.

Rule Editor Fields

The Rule Editor uses these fields to define the rule and its business logic:

Copy From Existing Rule

If you want to reuse existing code in your new rule, select an existing rule to copy.

Rule Name

Enter a unique name for the new rule, that clearly describes the purpose. It is useful to include the type of rule in the name, such as "Customization – My App," or "Exclusion – Inactive Users."

Description

Enter text that describes the purpose of the rule and what it does.

Arguments and Returns

These sections list the input variables (Arguments) that can be used in the script, and the return information (Returns). Click on any of the arguments or returns to show more detailed information. These fields cannot be changed in the Rule Editor.

Rule Type

The rule type determines the purpose of the rule and where it can appear in dropdown lists in the IdentityIQ UI. In most cases, the Rule Editor does not allow you to change the Rule Type.

Rule Editor

In the main editor of this UI, enter the BeanShell code for the rule. The rule cannot be saved until some code is entered. Note that no validation is performed; even if the rule is syntactically incorrect, it is accepted and saved. Incorrect rules may result in tasks, workflows or certifications failing to execute, and in errors and large stack traces in the log files.

Rule Re-Use

A single rule can be reused in many places throughout IdentityIQ; for example, two applications could share the same Build Map Rule. Changes made to the rule in one location will affect the functionality in all locations where it is used, so if the functionality varies between usages, separate rules should be created for each functional need.

Restricting Access to the Rule Editor

The ability to edit inline scripts in Identity IQ requires either the SystemAdministrator capability or the EditScripts SPRight. The EditScripts SPRight is not included in any standard capabilities by default. If you want to give script editing abilities to users other than System Administrators, you must either create a new capability for these users that includes the EditScripts SPRight, or add the EditScripts SPRight to an existing capability that can be assigned to those users.

Because the ability to write scripts is a potential security risk, it is recommended that the EditScripts SPRight is given out in a controlled manner to trusted users only.

For more information on assigning capabilities to users, see the User Rights Tab.

For more information on rights and capabilities in IdentityIQ, see IdentityIQ Rights and Capabilities - Definitions.

Importing Rule XML

Rules can be written as standalone XML objects and imported into IdentityIQ through the gear > Global Settings > Import from File option, or through the IdentityIQ console, using the iiq console import command. A single rule XML file can contain one or more rules.

For more information on importing files, see Import From File and Commonly Used Commands in the IdentityIQ Console Guide.

Sample Rule Files

IdentityIQ provides a set of sample rules that you can use as a model for creating your own. The sample rules are in the examplerules.xml file, which is located in your IdentityIQ installation directory under <identityiq_home>\WEB-INF\config\

In addition, a set of sample rules specifically for Rapid Setup is included with the Rapid Setup feature. Sample Rapid Setup rules are in the rsexamplerules.xml file, which is located in your IdentityIQ installation directory under <identityiq_home>\WEB-INF\config\rapidsetup.

Rule Libraries

Rule libraries are collections of methods that have been grouped together and stored in IdentityIQ as a Rule object. They contain sets of related but unconnected methods that can be invoked directly by workflow steps or other rules. These are stored as Rule objects, rather than in the compiled Java classes, so that their functionality can be easily modified to suit the needs of each installation.

IdentityIQ includes some rule libraries that are used by the default workflows. Examples of rule libraries are Workflow Library, Approval Library, and LCM Workflow Library, any of which can be viewed through the Debug pages or the iiq console.

You can create your own custom libraries to provide additional functionality as needed. To reference a rule library from another rule, include a <ReferencedRules> element in the rule XML, naming the rule library in the <Reference> element.

The methods within the library can then be invoked from within the rule's Source element.

<Rule...>
   <ReferencedRules>
       <Reference class='Rule' name='My Library'/>
   </ReferencedRules>
   <Source>
       doSomething();  
   </Source>
</Rule>

API Reference for Rules

The IdentityIQ API is documented as Java documentation (javadocs). The documentation is included in every installation of IdentityIQ under <identityiq_home>\doc\javadoc\

Testing Rules

In many cases, rules need input. That is, the rules need instances of objects, meaning that live data is the best test environment. However, taking instances of objects is not always possible and could cause problems with the actual data. For example, if a mistake is made in a correlation rule, application accounts could be correlated to the wrong identities or remain uncorrelated.

SailPoint recommends separating development, testing, and production environments. Creating a "sandbox" with its own sample data is a recommended practice that allows for testing rules under realistic conditions with minimal risk to live data.

For debugging purposes, it can be useful to insert println statements in your rules' BeanShell code. Be sure to comment out or delete any println statements before making the rule live in a production environment.