FAQ

ForgeRock Identity Platform

Does not apply to Identity Cloud

FAQ: Scripts in IDM

Last updated Jan 12, 2023

The purpose of this FAQ is to provide answers to commonly asked questions regarding scripts in IDM.

1 reader recommends this article

Frequently asked questions

Q. What variables can be used in scripts?
Q. How can I use the identityServer variable in scripts?
Q. When do onUpdate scripts run?
Q. How can I use a postAction script?
Q. How can I troubleshoot scripts?
Q. How do I invoke reconciliation (or any other http operation) via REST using a script?
Q. Why does my external JavaScript script fail to process sample data in the Admin UI?
Q. Why are changes to my JavaScript files being ignored?
Q. Can I use custom Java packages in scripts?
Q. How do I load external JavaScript functions into other scripts in IDM?
Q. How do I call a Groovy script from another Groovy script?

Q. What variables can be used in scripts?

A. The variables that can be used in scripts depend on the triggers that launch the script. The available variables are detailed in the Script variables.

Q. How can I use the identityServer variable in scripts?

A. The identityServer variable is a context variable, which can be used for the following locations in scripts:

InstallLocation
ProjectLocation
WorkingLocation

For example:

identityServer.getInstallLocation()

It can also be used to return values of specific properties using getProperty, as used in the crypto.js and policyFilter.js files (located in the /path/to/idm/bin/defaults/script directory).

See Script variables for further information on the identityServer variable

Q. When do onUpdate scripts run?

A. onUpdate scripts run before the liveSync update completes and run regardless of whether the source object has changed or not. The onUpdate script must always execute because it is possible for the onUpdate action to modify the source object itself based on some business logic.

See Managed Object Configuration for further information on when scripts run.

Q. How can I use a postAction script?

A. postAction scripts are used in the sync.json file, where you can associate them with a specific situation and action for a policy. The postAction script is invoked when the corresponding action for the specific policy situation has completed, thereby allowing you to automatically trigger an action upon completion of a related action.

Note

The postAction script is not triggered if the action is set to either IGNORE or ASYNC.

For example, you could use a postAction script on the CREATE action to trigger an update to the LDAP object that you just created. The relevant section in the sync.json file would look similar to this:

{ "situation" : "ABSENT", "action" : "CREATE", "postAction" : { "type" : "text/javascript", "file" : "script/postcreate-update.js" } }

See Synchronization Situations and Actions and Policy Objects for further information.

Q. How can I troubleshoot scripts?

A. You can add logging to scripts to troubleshoot them as detailed in How do I add logging to JavaScript files in IDM (All versions)? and How do I add logging to Groovy scripts in IDM (All versions)?

You can also debug your Groovy scripts as detailed in How do I debug server-side Groovy code in IDM (All versions)?

Q. How do I invoke reconciliation (or any other http operation) via REST using a script?

A. You can use the following in JavaScript® to invoke http operations via REST:

openidm.action()

For example, an external REST call via a script would look similar to this:

openidm.action("external/rest", "call", params);

Where the call parameter specifies the action name to be used for invoking the http operation.

See Access External REST Services for further information.

Q. Why does my external JavaScript script fail to process sample data in the Admin UI?

A. There are known issues in IDM with evaluating external transformation and conditional scripts against sample data in the Admin UI.

External transformation and conditional scripts do not work when you view sample data, but do work if you process the data by performing a reconciliation. As a workaround for viewing sample data, you can include the script inline rather than as an external script.

Q. Why are changes to my JavaScript files being ignored?

A. Changes to JavaScript files are loaded according to the interval set in the following property in the script.json file (located in the /path/to/idm/conf directory):

"javascript.recompile.minimumInterval" : "60000",

This defaults to 60000 (60 seconds), which means any changes made to scripts are not picked up for up to 60 seconds.

If you are developing scripts, you can reduce this interval to see your changes quicker. See Script Configuration for further information.

Q. Can I use custom Java packages in scripts?

A. Yes, you can use custom Java® packages, but you must prefix the package name with "Packages." in JavaScript. For example:

If your package name is: custom.package.name
You must refer to it as follows in JavaScript files: Packages.custom.package.name

JavaScript only recognizes packages beginning with org, com or java, whereas Groovy recognizes all package names.