The Rule Runner plugin is an in-browser IDE, allowing ad-hoc Beanshell code execution. It is similar to the Debug pages' "Run Rule" feature, but includes live syntax checking, simple auto-completion, execution history, background execution for long-running rules, many safety features.
Simply type your code into the source code box and click Run. The rule’s output, whether success or failure, will be displayed in the Execution results section. Output can be scalar, object, or XML format, or an error message, each of which render slightly differently.
If your code runs for longer than 3 seconds, execution will be shifted to a background thread, which will be polled for completion, logs, and other statistics every few seconds. You can attempt to terminate a background rule by clicking the "Stop" button.
Most output will render as a String, usually the toString() of the object. Certain object types, such as List and Map, will render as a JSON tree, with each section individually collapsible (visible in the overview screenshot above).
SailPointObjects, such as Identity or Link, will be displayed as their XML equivalent.
If an exception occurs, the exception message and stack trace will be displayed in place of the output.
Beanshell (specifically, BSF) tends to swallow errors and wrap them in a less-than-useful BSFException. It may be useful to catch and return (not throw) an exception from your rule, rather than letting Beanshell do the work for you. The Rule Runner will interpret a Throwable return value as an actual error and will display it as such.
try {
somethingThatThrowsAnError();
} catch(Exception e) {
return e;
}
If the error is a Beanshell parse (syntax) error, its message will be helpfully extracted and displayed above the main exception trace.
You may use Rule Library code by selecting them from the dropdown box below the source code entry area. More than one rule library can be selected.
By default, the Run asynchronously feature is enabled. With this feature enabled, each execution will create two background threads: (1) an execution thread to run your Rule and (2) a monitor thread.
The monitor thread is responsible for tracking the progress of the execution thread. It will attempt to terminate long-running executions after the allocated timeout period has elapsed (default: 10 minutes).
You may also terminate asynchronous execution using the Stop button.
Any messages logged within you Beanshell script will be updated in the browser, updated every couple seconds.
The Rule Runner injects three Beanshell variables referencing the same Log object: log, _log, and __log (with one and two underscores). This is because some Rule Libraries define their own variable called log, which overwrites our injected variable. You can set it back at the start of your script, like:
import org.apache.common.logging.Log;
Log log = __log;You may also log progress messages and progress percentages using the injected monitor object, which implements a superset of sailpoint.task.Monitor. These will be reported in the user interface as a status message and a progress bar, respectively.
If the plugin option createTaskResult is enabled, the TaskResult corresponding to your rule execution will be updated with the same progress values.
The following checkbox options are available:
-
Include web context variables: If checked, the servlet variables httpRequest and httpResponse, and the IIQ web service context webService are injected to your script. This can be used to debug web session issues. Since this can only run in the context of a web service call, this option is not compatible with asynchronous execution.
-
Include workflow library variables (lint only): If you are writing a workflow library, the parser will assume launcher and wfcontext variables exist. This option provides those variables so that those lines don’t cause syntax errors.
-
Ignore type errors that Beanshell allows (lint only): Beanshell provides a superset of Java, allowing some dynamic typing. The Java parser will reject these structures as errors or warnings. This option suppresses those errors.
The plugin will periodically pass your script (and any included rule libraries) to a parser based on the Eclipse ECJ compiler. Errors returned by the compiler will be displayed with appropriate highlights on your screen.
Note that the presence of error messages does not prevent you from running your script. Beanshell can be a strange environment, and it’s possible that the compiler can’t make sense of a script that will run flawlessly. It’s up to you, as the developer, to decide whether an error is "real" or not.
You can use the Variables button to open the variable initialization screen. Any variables defined on this screen will be injected into your Beanshell script, allowing you to test the same Beanshell code with various inputs.
The syntax parser will assume that your variables exist with the appropriate type, so you can use them without syntax errors.
Click Create New and define your variable, then click Save. Once finished defining variables, click Done.
You must specify the fully qualified Java type of each variable, such as java.lang.String and not just String.
Variables can be strings, lists, dates, or any loadable SailPointObject, such as an Identity. Variables can be initialized in various ways by selecting an "Initialization type" from the dropdown. The "Object Lookup" initialization type will become available if you enter a sailpoint.object class name.
You can load, edit, and save existing Rule objects, including their source code and rule libraries.
The plugin uses the localForage Javascript library to save the source code you are currently editing (and its metadata, such as rule libraries) to your browser’s local storage. The localForage library uses IndexedDB if it’s available, but falls back to localStorage if not.
When you execute a rule, the Rule Runner will register an IIQ audit event with the full contents of your source code and other metadata. It will also store a copy in your browser history. (If you run the same rule twice, the browser copy will be de-duplicated.)