appendix-scripting.xml revision 21321a22cb4d65f132f22f73df6b0fd8a62dac32
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! CCPL HEADER START
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! This work is licensed under the Creative Commons
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! To view a copy of this license, visit
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! http://creativecommons.org/licenses/by-nc-nd/3.0/
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! or send a letter to Creative Commons, 444 Castro Street,
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! Suite 900, Mountain View, California, 94041, USA.
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! You can also obtain a copy of the license at
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! See the License for the specific language governing permissions
e6c3a72a023407f5d1fface64356e1cc81f1af31Phill Cunnington ! and limitations under the License.
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! If applicable, add the following below this CCPL HEADER, with the fields
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! enclosed by brackets "[]" replaced with your own identifying information:
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! Portions Copyright [yyyy] [name of copyright owner]
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! CCPL HEADER END
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! Copyright 2011-2012 ForgeRock AS
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest version="5.0"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest xmlns:xinclude="http://www.w3.org/2001/XInclude">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>Scripting lets you customize how OpenIDM works in various ways, such
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest as providing custom logic between source and target mappings, defining
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest correlation rules, filters, and triggers.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>You define scripts using script objects, which can either include the
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest code directly in the configuration, or call an external file containing the
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest script.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "file" : <replaceable>file location</replaceable>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>Specifies the type of script to be executed. Currently, OpenIDM
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest supports only <literal>"text/javascript"</literal>.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string, required if file is not specified</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>Specifies the source code of the script to be executed.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string, required if source is not specified</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>Specifies the file containing the source code of the script to
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest execute.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The following example returns <literal>true</literal> if the
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <literal>employeeType</literal> is equal to <literal>external</literal>,
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest otherwise returns <literal>false</literal>. This script can be useful during
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reconciliation to establish whether the source object should be a part of
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest the reconciliation, or ignored.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <programlisting language="javascript">"validTarget": {
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "source": "object.employeeType == 'external'"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The following example sets the <literal>__PASSWORD__</literal>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest attribute to <literal>defaultpwd</literal> when OpenIDM creates a target
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <programlisting language="javascript">"onCreate" : {
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "source": "target.__PASSWORD__ = 'defaultpwd'"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This example shows how to define a trigger to create Solaris home
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest directories using a script. The script is located in a file,
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <filename>/path/to/openidm/script/createUnixHomeDir.js</filename>.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "filters" : [ {
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "methods" : [ "create" ],
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "onResponse" : {
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>Functions (access to managed objects, system objects, configuration
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest objects) within OpenIDM are accessible to scripts via the
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <literal>openidm</literal> object, which is included in the top-level scope
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest provided to each script.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function creates a new resource object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to be created.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The value of the object to be created.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>A <literal>null</literal> value if successful.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the object could not be created for any
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function reads and returns an OpenIDM resource object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to be read.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The read OpenIDM resource object, or <literal>null</literal> if not
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest found.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.update(id, rev, value)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function updates a resource object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the resource object to be updated.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The revision of the object to be updated, or <literal>null</literal>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest if the object is not subject to revision control.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The value of the object to be updated.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>A <literal>null</literal> value if successful.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the object could not be updated for any
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function deletes a resource object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to be deleted.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The revision of the object to be deleted, or <literal>null</literal>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest if the object is not subject to revision control.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>A <literal>null</literal> value if successful.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the object could not be deleted for any
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function performs a query on the specified OpenIDM resource
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to perform the query on.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An object containing the parameters to pass to the query.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the given query could not be processed for
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest any reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.action(id, params, value)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function performs an action on the specified OpenIDM resource
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to perform the action on.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An object containing the parameters to pass to the action.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>A value that can be provided to the action for processing.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The result of the action. May be <literal>null</literal> if no result
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest is provided.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the given action could not be executed
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest for any reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.encrypt(value, cipher, alias)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The cipher with which to encrypt the value, using the form
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "algorithm/mode/padding" or just "algorithm". Example:
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <literal>AES/ECB/PKCS5Padding</literal>.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The key alias in the key store with which to encrypt the node.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The value, encrypted with the specified cipher and key.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the object could not be encrypted for any
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
from the <link xlink:href="http://www.eclipse.org/downloads/" xlink:show="new">Eclipse download page</link>.</para>
<para>Add <link xlink:href="http://wiki.eclipse.org/JSDT" xlink:show="new">JavaScript Development Tools</link> to your existing Eclipse
#openidm.script.javascript.debug=transport=socket,suspend=y,address=9888,trace=true</programlisting>