Next-generation scripts
The next-generation scripting engine offers the following benefits:
- Stability
-
-
A stable set of enhanced bindings that reduces the need to allowlist Java classes to access common functionality.
-
- Ease of use
-
-
Simplifying your scripts with fewer imports and more intuitive return types that require less code.
-
Easier debugging through clear log messages and a simple logging interface based on SLF4J.
-
Making requests to other APIs from within scripts is easier 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 next-generation script.
-
Access identity management information seamlessly through the
openidm
binding.
-
Availability
The following script types use the next-generation scripting engine:
These are the only script types that can use library scripts and next-generation bindings.
Migrate to next-generation scripts
To use next-generation bindings, you must migrate eligible legacy scripts.
The next-generation engine can’t use legacy scripts. 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 script 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 to be included as a supported script binding in a future release.
-
Update your bindings according to the API documentation for the specific script type.
The following table provides links to examples of how to migrate common bindings to next-generation scripts.
Binding Next-generation change Uses native JavaScript objects, similar to the Fetch API.
Logger is now based on
org.slf4j.Logger
, instead ofcom.sun.identity.shared.debug.Debug
.Use this binding to access the
openidm
scripting functions supported in IDM.Reference secrets and credentials from scripts.
Use this utility binding to base64 encode/decode strings and to generate random UUIDs.
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
var fr = JavaImporter(
org.forgerock.openam.auth.node.api.Action);
var requestURL =
"https://example.com/authenticate";
var request = new
org.forgerock.http.protocol.Request();
request.setUri(requestURL); 2
request.setMethod("POST");
request.getHeaders().add("Content-Type", 3
"application/json;");
request.getHeaders().add("Authorization",
"Bearer abcd-1234"); 4
request.setEntity(JSON.stringify(
{"username": "demo"}));
var response =
httpClient.send(request).get(); 5
var responseCode =
response.getStatus().getCode(); 6
if (responseCode === 200) {
action = fr.Action.goTo("true").build();
} else {
action = fr.Action.goTo("false").build();
}
// import an external library to get token
var authLib = require('authLib'); 1
var bearerToken =
authLib.generateBearer(nodeState);
var options = { 2
method: "POST",
headers: {
"Content-Type": "application/json" 3
},
token: bearerToken, 4
body: {
username: "demo"
}
}
var requestURL =
"https://example.com/authenticate";
var response = httpClient.send(
requestURL, options).get(); 5
if (response.status === 200) { 6
action.goTo("true");
} else {
action.goTo("false");
}
1 The example assumes you’ve created a custom library script (authLib
) that handles authentication.
2 Set the request options as a native JavaScript object, instead of setting parameters on a Request object.
3 To send a form request, you don’t need to set Content-Type
to url-encode parameters. Use the form
attribute instead. For details, refer to Access HTTP services.
4 Use Library scripts to reuse common pieces of code; for example, to get an authentication token.
5 Call httpClient.send
with the request URL and options as separate arguments, instead of a Request object.
6 Access response data directly using the methods and properties of the returned response
object.
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
var messageEnabled = logger.messageEnabled();
logger.message("Message with arg {}", arg);
var warnEnabled = logger.warningEnabled();
logger.warning("Warn with arg {}", arg);
var errorEnabled = logger.errorEnabled();
logger.error("Error with arg {}", arg);
var traceEnabled = logger.isTraceEnabled();
logger.trace("Trace with arg {}", arg);
var debugEnabled = logger.isDebugEnabled();
logger.debug("Debug with arg {}", arg);
var infoEnabled = logger.isInfoEnabled();
logger.info("Info with arg {}", arg);
var warnEnabled = logger.isWarnEnabled();
logger.warn("Warn with arg {}", arg);
var errorEnabled = logger.isErrorEnabled();
logger.error("Error with arg {}", arg);
openidm
The openidm
binding lets you manage an IDM resource by calling
scripting functions directly from a next-generation 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
function lookupUser (email) {
try {
var idmUserEndpoint =
+ '/openidm/managed/alpha_user?
_queryFilter=userName+eq+%22'
+ email + '%22';
var request = new
org.forgerock.http.protocol.Request();
var accessToken =
transientState.get("idmAccessToken"); 1
request.setMethod('GET');
request.setUri(idmUserEndpoint); 1
request.getHeaders().add('Authorization',
'Bearer ' + accessToken);
request.getHeaders().add('Content-Type',
'application/json');
request.getHeaders().add('Accept-API-Version',
'resource=1.0');
var httpResponse =
httpClient.send(request).get(); 1
var responseCode =
httpResponse.getStatus().getCode();
if (responseCode === 200) {
var response = JSON.parse(
httpResponse.getEntity().getString());
if (response && response.result &&
response.result.length > 0) {
// User found
return {
success: true,
user: response.result[0]};
} else {
// User NOT found
return { success: true, user: null };
}
} else {
return {
success: false,
error: 'Error looking up user: ' + responseCode
};
}
} catch (e) {
return {
success: false,
error: 'Error querying user: ' + e.toString()
};
}
}
openidm.query("managed/user", { 1
"_queryFilter":`/userName eq '${email}'`
}
);
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.
secrets
The secrets
binding is available to all next-generation scripts.
Learn more about the secrets
binding in Access secrets and credentials.
Legacy | Next-generation |
---|---|
|
|
1 Access the secret from the Advanced Identity Cloud secret store in the same way as the legacy binding.
2 To encode sensitive information, the utils
binding replaces the need
to allowlist the java.util.Base64
and java.util.Base64$Encoder
Java classes.
Exception handling when using next-generation script bindings
You must handle exceptions differently depending on whether the exception occurs within a JavaScript Promise
or not.
Both types of exception handling can require that the Java exception class is allowlisted or marked as supported for you to access particular details about the exception. Otherwise, the script can throw an error.
The next-generation scripting engine doesn’t support a configurable allowlist. Learn more in Access Java classes. |
General exception handling
When you call a method on a script binding that throws an exception, the scripting engine wraps the exception object in a JavaScript error. You can use this to access the error message in the following way:
try {
myBinding.myMethod();
} catch (e) {
// works without requiring support or allowlisting of the exception class
logger.error(e.message);
}
If the exception class is allowlisted or the class and method are annotated as @Supported
,
you can access the underlying Java exception as follows:
try {
myBinding.myMethod();
} catch (e) {
// throws an exception if getMyObject() isn't supported or the exception class isn't allowlisted
myObject = e.javaException.getMyObject();
}
Exception handling within a Promise
When you handle an exception in a thenCatch
block of a Promise
, the exception object isn’t
wrapped, so it still references the Java exception instead of a JavaScript error.
You can only access the exception object if the exception class is allowlisted
or if the fields and methods you want to use are annotated with the @Supported
annotation.
For example:
var val = myBinding.methodReturningPromise()
.then(() => {
// function to handle the result of the promise
})
.thenCatch((e) => {
// throws a new exception unless the "message" field is supported
message = e.message;
// throws an exception unless "getMyObject()" is supported or the exception class is allowlisted
myObject = e.getMyObject();
return false;
}).get();
As an example, the HttpClientScriptException has a supported message field for logging purposes.
|