RapidIdentity Product Guide

ECMAScript Implementation File

The expressions entered as the values for the return actions in the XML Action Definitions File are actually calls to ECMAScript functions that are defined in the ECMAScript Implementation File. A template for the ECMAScript Implementation File can be generated by executing the maven target xml:transform, which will (among other things) generate a template file target/templates/dss-example-actions.template.js. The template can then be used as a skeleton for implementing adapter actions by replacing the TODO comments with the implementation code. In the example adapter, the ECMAScript Implementation File can be found at:  src/main/resources/net/idauto/exodus/dss/adapter/example/example-adapter-actions.js

Implementation Notes

  • ECMAScript is the standards-based name for what is more commonly known as JavaScript. The ECMAScript is interpreted by Mozilla Rhino.

    The Rhino interpreter implements most of the 5th Edition of the ECMAScript standard, as well as many of the additions from ECMAScript 2015+. It does not implement any of the objects specific to usage in web browsers. It does provide mechanisms for scripting Java objects as if they were native ECMAScript objects.

    The basic ECMAScript objects have no real way to interact with anything outside of the script, but what makes the Rhino engine useful is it's ability to be used to script Java objects and use them as more-or-less as if they were native ECMAScript objects, which an adapter that does anything useful will almost certainly need to do.

  • Most of the actions available in RapidIdentity Connect for building Action Sets are available to an adapter implementation as ECMAScript global functions. The primary exceptions to this are setVariable() and all of the actions in the Core|Logic category. This includes actions provided by other adapters with the caveat that those actions are only available at runtime if the adapter has a valid license installed. Since a Record object is the predominant data structure used by RapidIdentity Connect, many of the actions from Core|Data|Records category will usually need to be used.

  • Rhino supports the ECMAScript for XML (E4X) specification, which makes working with XML much simpler and more straightforward than using Java DOM APIs. Conversion between DOM and E4X is also supported which makes it possible to use E4X even when dealing with Java libraries that require DOM.

  • ECMAScript is unusual in that it has a notion of both null and undefined and they are different. An adapter should treat both null and undefined as if they were the same when passed in as an input property.

  • An action can emit trace, warning, and error messages by calls to $builtin.core.trace(), c, and $builtin.core.error(). Each of these functions takes a variable number (1 or more) of arguments, which it converts to strings and joins into one string. They can intelligently display objects, Records, Arrays, Exceptions, and XML.

  • Catch all exceptions unless some condition is detected that should abort the Action Set that is currently being run. When an exception is caught that indicates some sort of failure of the action, it is usually a good idea to emit an error or warning to the trace and return a value from the action that is indicative of an error.

  • The maven build file automatically checks the syntax of the ECMAScript implementation file during the validate phase, so it won't let you build the adapter .jar file if there are syntax errors.

  • There are also syntax-aware JavaScript/ECMAScript editors that will validate the syntax and format the code.

  • RapidIdentity Connect supports ECMAScript debugging using the Rhino debugger. To use the debugger:

    • The servlet container (usually Tomcat) hosting RapidIdentity Connect must be running in a context that has access to the GUI. On Linux, this usually means that it was started from within an X session, possibly via ssh -Y which allows tunneling of X from a remote server.

    • Create an Action Set that calls the action(s) to be debugged.

    • Run the Action Set.

    • After the Action Set process has completed, edit the URL in the browser and change “run?” to “ecmaDebug?” and resubmit. If everything is set up correctly, the GUI window of the Rhino debugger should pop up in the GUI.

    • You will be able to debug through the ECMAScript that was generated from the Action Set including stepping into the action implementation.

  • If the adapter needs to maintain some sort of state, e.g. a connection to a server, you may need to create and return custom objects to maintain that state. If that state includes resources that need to be released/closed/freed, then the custom object SHOULD implement a close() function and the object SHOULD be registered for automatic cleanup by calling $builtin.core.registerCleanup(object) so that the resources will be freed if the Action Set process terminates abnormally or the Action Set otherwise fails to explicitly close the resource. The object MAY be unregistered by calling $builtin.core.unregisterCleanup(object) when the resource is explicitly closed, but the close() method MUST NOT throw an exception even if the resource has already been released/closed/freed or for some reason cannot be released/closed/freed.

In this section: