appendix-scripting.xml revision 21321a22cb4d65f132f22f73df6b0fd8a62dac32
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest<?xml version="1.0" encoding="UTF-8"?>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest<!--
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! CCPL HEADER START
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest !
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 !
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! You can also obtain a copy of the license at
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! legal/CC-BY-NC-ND.txt.
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! See the License for the specific language governing permissions
e6c3a72a023407f5d1fface64356e1cc81f1af31Phill Cunnington ! and limitations under the License.
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest !
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 !
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! CCPL HEADER END
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest !
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest ! Copyright 2011-2012 ForgeRock AS
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest !
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest-->
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest<appendix xml:id="appendix-scripting"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest version="5.0"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest xml:lang="en"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest xmlns="http://docbook.org/ns/docbook"
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:xlink="http://www.w3.org/1999/xlink"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest xmlns:xinclude="http://www.w3.org/2001/XInclude">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Scripting</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
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
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="scripting-configuration">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Configuration</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
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
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <programlisting language="javascript">{
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "type" : "text/javascript",
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "source": <replaceable>string</replaceable>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>or</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <programlisting language="javascript">{
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "type" : "text/javascript",
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "file" : <replaceable>file location</replaceable>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>type</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string, required</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>Specifies the type of script to be executed. Currently, OpenIDM
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest supports only <literal>"text/javascript"</literal>.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>source</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
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 </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>file</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
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 </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="scripting-example">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Examples</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
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
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <programlisting language="javascript">"validTarget": {
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "type" : "text/javascript",
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "source": "object.employeeType == 'external'"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
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
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <programlisting language="javascript">"onCreate" : {
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "type" : "text/javascript",
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "source": "target.__PASSWORD__ = 'defaultpwd'"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
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
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <programlisting language="javascript">{
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "filters" : [ {
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "pattern" : "^system/solaris/account$",
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "methods" : [ "create" ],
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "onResponse" : {
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "type" : "text/javascript",
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest "file" : "script/createUnixHomeDir.js"
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest }
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest } ]
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest}</programlisting>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-ref">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Function Reference</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
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
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-create">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.create(id, value)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function creates a new resource object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Parameters</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>id</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to be created.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>value</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>object</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The value of the object to be created.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Returns</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>A <literal>null</literal> value if successful.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Throws</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the object could not be created for any
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-read">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.read(id)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function reads and returns an OpenIDM resource object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Parameters</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>id</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to be read.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Returns</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The read OpenIDM resource object, or <literal>null</literal> if not
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest found.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-update">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.update(id, rev, value)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function updates a resource object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Parameters</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>id</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the resource object to be updated.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>rev</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
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 </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>value</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>object</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The value of the object to be updated.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Returns</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>A <literal>null</literal> value if successful.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Throws</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the object could not be updated for any
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-delete">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.delete(id, rev)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function deletes a resource object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Parameters</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>id</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to be deleted.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>rev</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
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 </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Returns</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>A <literal>null</literal> value if successful.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Throws</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the object could not be deleted for any
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-query">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.query(id, params)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function performs a query on the specified OpenIDM resource
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Parameters</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>id</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to perform the query on.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>params</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>object</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An object containing the parameters to pass to the query.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Returns</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The result of the query.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Throws</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the given query could not be processed for
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest any reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-action">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.action(id, params, value)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function performs an action on the specified OpenIDM resource
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest object.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Parameters</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>id</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The identifier of the object to perform the action on.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>params</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>object</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An object containing the parameters to pass to the action.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>value</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>object</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>A value that can be provided to the action for processing.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Returns</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The result of the action. May be <literal>null</literal> if no result
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest is provided.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Throws</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the given action could not be executed
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest for any reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-encrypt">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.encrypt(value, cipher, alias)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function encrypts a value.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Parameters</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>value</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>any</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The value to be encrypted.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>cipher</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
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 </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>alias</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>string</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The key alias in the key store with which to encrypt the node.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Returns</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The value, encrypted with the specified cipher and key.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Throws</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>An exception is thrown if the object could not be encrypted for any
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest reason.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </itemizedlist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </section>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <section xml:id="function-decrypt">
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>openidm.decrypt(value)</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>This function decrypts a value.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <variablelist>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <title>Parameters</title>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <term>value</term>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>any</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest <para>The value to be decrypted.</para>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </listitem>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </varlistentry>
ea65b6bac936db133a660beef9d75f044dd7ce84Andrew Forrest </variablelist>
<itemizedlist>
<title>Returns</title>
<listitem>
<para>A deep copy of the value, with any encrypted value decrypted.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Throws</title>
<listitem>
<para>An exception is thrown if the object could not be decrypted for any
reason.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="debugging-scripts">
<title>Debugging OpenIDM Scripts</title>
<para>OpenIDM includes Eclipse JSDT libraries so you can use Eclipse to debug
you OpenIDM scripts during development.</para>
<procedure xml:id="enable-debugging">
<title>To Enable Debugging</title>
<para>Follow these steps to enable debugging using Eclipse.</para>
<step>
<para>Install the environment to support JavaScript development in either
of the following ways.</para>
<stepalternatives>
<step>
<para>Download and install Eclipse IDE for JavaScript Web Developers
from the <link xlink:href="http://www.eclipse.org/downloads/" xlink:show="new">Eclipse download page</link>.</para>
</step>
<step>
<para>Add <link xlink:href="http://wiki.eclipse.org/JSDT" xlink:show="new">JavaScript Development Tools</link> to your existing Eclipse
installation.</para>
</step>
</stepalternatives>
</step>
<step>
<para>Create an empty JavaScript project called <literal>External JavaScript
Source</literal> in Eclipse.</para>
<para>Eclipse then uses the <filename>External JavaScript Source</filename>
directory in the default workspace location to store sources that it
downloads from OpenIDM.</para>
</step>
<step>
<para>Stop OpenIDM.</para>
</step>
<step>
<para>Edit <filename>openidm/conf/boot/boot.properties</filename> to
enable debugging.</para>
<substeps>
<step>
<para>Uncomment and edit the following line.</para>
<programlisting language="none" width="84">
#openidm.script.javascript.debug=transport=socket,suspend=y,address=9888,trace=true</programlisting>
<para>Here <literal>suspend=y</literal> prevents OpenIDM from starting
until the remote JavaScript debugger has connected. You might therefore
choose to set this to <literal>suspend=n</literal>.</para>
</step>
<step>
<para>Uncomment and edit the following line.</para>
<programlisting language="none" width="81">
#openidm.script.javascript.sources=/Eclipse/workspace/External JavaScript Source/</programlisting>
<para> Adjust <literal>/Eclipse/workspace/External JavaScript
Source/</literal> to match the absolute path to this folder including the
trailing <literal>/</literal> character. On Windows, also use forward
slashes, such as <literal>C:/Eclipse/workspace/External JavaScript
Source/</literal>.</para>
<para>Each time OpenIDM loads a new script, it then creates or overwrites
the file in the <filename>External JavaScript Source</filename> directory.
Before toggling breakpoints, be sure to refresh the source manually in
Eclipse so you have the latest version.</para>
</step>
</substeps>
</step>
<step>
<para>Start OpenIDM, and connect the debugger.</para>
</step>
</procedure>
</section>
</appendix>