Next-generation scripts
The next-generation scripting engine offers the following benefits:
- Stability
-
-
A stable set of enhanced bindings, available to JavaScript decision node scripts, that reduces the need to allowlist Java classes to access common functionality.
-
- Ease of use
-
-
Simplify your scripts with fewer imports and more intuitive return types that require less code.
-
Debug more easily with clear log messages and a simple logging interface based on SLF4J.
-
Make requests to other APIs from within scripts more easily with a more intuitive HTTP client.
-
- Reduced complexity
-
-
Simplify and modularize your scripts with library scripts by reusing commonly used code snippets as CommonJS modules.
Reference library scripts from a decision node script.
-
Access identity management information seamlessly through the
openidm
binding.
-
Migrate to next-generation scripts
Different bindings are available to the decision node script depending on the scripting engine version; legacy or next-generation.
The next-generation engine can’t use legacy scripts or scripts written in Groovy. If your Scripted Decision node uses legacy scripts, you must convert them to use updated bindings to take advantage of the benefits of the next-generation scripting engine. Where possible, you should migrate legacy scripts to take advantage of next-generation stability. |
You can’t change the script engine version after you have created a script.
To migrate existing scripts, create a new script and convert your legacy code:
-
Create a decision node script (type:
Decision node script for authentication trees
) and select Next Generation on the Choose Script Engine page. -
Copy and paste the legacy version of your script into the JavaScript field.
-
Review any Java classes that you needed to allowlist to use in your legacy script.
You can’t add Java classes to the next-generation allowlist.
Instead, check if any next-generation bindings provide similar functionality, or reimplement the class as a library script. Library scripts let you add third-party code as reusable JavaScript modules that can be referenced from other scripts.
If this isn’t possible, you can request the functionality be included as a supported script binding in a future release.
-
Review the changes in the following table and update the bindings according to the examples in the links provided.
Binding Next-generation change Example action
New.
Use static method
goTo()
to set the script outcome.To send callbacks, instead of calling
Action.send()
, use the newcallbacksBuilder
functionality.callbacksBuilder
New.
Instead of creating a
Callback
object and invokingAction.send()
, add callbacks using static methods on thecallbacksBuilder
object; for examplenameCallback
andpasswordCallback
. These callbacks are automatically sent when the script completes.httpClient
Uses native JavaScript objects, similar to the Fetch API.
idRepository
Class changed from
ScriptIdentityRepository
toScriptedIdentityRepository
.Use
getIdentity()
method in addition to methods to get or set attributes.You must now explicitly call
store()
to persist changes to attribute values.jwtAssertion
New.
Generate JWT assertions in scripts.
jwtValidator
New.
Validate JWT assertions in scripts.
logger
Logger is now based on
org.slf4j.Logger
, instead ofcom.sun.identity.shared.debug.Debug
.nodeState
The
sharedState
andtransientState
bindings are no longer supported.openidm
New.
Use this binding to access the
openidm
scripting functions supported in IDM.utils
Use this utility binding to base64 encode/decode strings and to generate random UUIDs.
action
Legacy | Next-generation |
---|---|
|
|
1 No need to import the Action
class to access the goTo
method.
Instead, call the goTo
method directly on the action
binding.
callbacksBuilder
Use the callbacksBuilder
object instead of importing Callback
classes.
Learn more about using callbacks in Callbacks.
Legacy | Next-generation |
---|---|
|
|
1 Use callbacksBuilder
to request callbacks, and the callbacks
object to retrieve returned values.
2 No need to explicitly call send()
. The script sends every callback added to the callbacksBuilder
when it completes.
3 Use nodeState.putShared()
instead of sharedState.put()
and nodeState.putTransient()
instead of transientState.put()
.
4 No need to set the outcome, because action.goTo()
was invoked.
httpClient
Call HTTP services with the httpClient.send
method. HTTP client requests are asynchronous,
unless the get()
method is invoked on the returned object.
For more information, refer to Access HTTP services.
Legacy | Next-generation |
---|---|
|
|
1 Set the request options as a native JavaScript object, instead of setting parameters on a Request object.
2 Use Library scripts to reuse common pieces of code; for example, to get an authentication token.
3 Call httpClient.send
with the request URL and options as separate arguments, instead of a Request object.
4 Access response data directly using the methods and properties of the returned response
object.
idRepository
Legacy | Next-generation |
---|---|
|
|
1 The idRepository
object is no longer used to get attribute values. Instead, use the getIdentity()
method of the new org.forgerock.openam.scripting.api.identity.ScriptIdentityRepository
interface to get the identity object.
2 Use the identity
object, instead of idRepository
, to get or set attribute values.
3 Setting or adding attributes on the identity
object does not persist data.
4 You must explicitly persist changes by calling the store
method.
logger
The com.sun.identity.shared.debug.Debug
logger class is deprecated and replaced by org.forgerock.openam.scripting.logging.ScriptedLoggerWrapper
.
ScriptedLoggerWrapper
provides a subset of the methods offered by SLF4J.
For more information, refer to Log script messages.
Legacy | Next-generation |
---|---|
|
|
nodeState
Legacy | Next-generation |
---|---|
|
|
1 Deprecated sharedState
and transientState
bindings are no longer available. Use nodeState.get()
instead. To store state values, use nodeState.putShared()
or nodeState.putTransient()
instead of sharedState.put()
and transientState.put()
.
2 No need to call methods such as asString()
or asMap()
.
3 New getObject()
method to retrieve a map with values stored across different states. The map is immutable.
For more information about the nodeState
binding, refer to Access shared state data.
openidm
The new openidm
binding lets you manage an IDM resource by calling
scripting functions directly from a decision node script.
The following CRUDPAQ functions are supported:
-
create
-
read
-
update
-
delete
-
patch
-
action
-
query
The following example shows the extensive code required in a legacy script
to query the existence of a user by their email address in IDM,
compared to the ease of using the openidm
binding.
For further examples of how to use the openidm
binding in your next-generation scripts,
refer to Access IDM scripting functions.
For details of other supported functions, refer to Scripting functions.
The |
Legacy | Next-generation |
---|---|
|
|
1 Replace code that gets an idmAccessToken
and uses the HTTP client
object to invoke a request on an /openidm/*
endpoint,
with the direct use of the openidm
binding.