5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose<?xml version="1.0" encoding="UTF-8"?>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose<chapter xml:id='chap-sample'

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xmlns='http://docbook.org/ns/docbook'

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose version='5.0' xml:lang='en'

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xmlns:xlink='http://www.w3.org/1999/xlink'

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xmlns:xinclude='http://www.w3.org/2001/XInclude'>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose<title>OpenIDM Sample</title>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher <para>In the current distribution of OpenIDM the sample

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher in <filename>openidm/samples/sample1</filename> is configured and enabled by

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher default. This chapter provides an overview of the sample and how it is

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher configured. To see a listing and an overview of the rest of the samples

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher provided see the README found in <filename>openidm/samples</filename>.

fb0df854f9be51892173ba299cab88bf628d2b30Stephen Gallagher </para>

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher <section xml:id="before-you-begin-sample">

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher <title>Before You Begin</title>

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher <para>Install OpenIDM as described in the chapter on <link

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher xlink:href="install-guide#chap-install"

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Installing

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher OpenIDM Services</citetitle></link>.</para>

48a038d077ed2de18a5211e010c18ab680107293Stephen Gallagher <para>If you want to query the internal noSQL database (OrientDB), download

7bfc287b693d3696bd5b3c60bdb7e543eb230f9bStephen Gallagher and unzip <link xlink:href='http://code.google.com/p/orient/wiki/Download'

7bfc287b693d3696bd5b3c60bdb7e543eb230f9bStephen Gallagher xlink:show="new">OrientDB 1.0</link>. Once you have downloaded and unzipped

63fb0857378c450d9806b1a3c6bb5657f00a8ba1Jakub Hrozek OrientDB, you can find the shell console in the <filename>bin</filename>

63fb0857378c450d9806b1a3c6bb5657f00a8ba1Jakub Hrozek directory. Start OrientDB console using either <command>console.sh</command>

01248645166911f3b3c19723f44a84c5a0599e34Stephen Gallagher or <command>console.bat</command>, and then connect to the running OpenIDM

01248645166911f3b3c19723f44a84c5a0599e34Stephen Gallagher with the <command>connect</command> command.</para>

3662413d65e9ba2a899e8ce98ec9c3a549be20c8Jan Zeleny <screen>$ /path/to/orientdb-1.0rc6/bin/console.sh

01248645166911f3b3c19723f44a84c5a0599e34Stephen Gallagher&gt;

3662413d65e9ba2a899e8ce98ec9c3a549be20c8Jan Zeleny&gt; connect remote:localhost/openidm admin admin

3662413d65e9ba2a899e8ce98ec9c3a549be20c8Jan Zeleny

7bfc287b693d3696bd5b3c60bdb7e543eb230f9bStephen GallagherConnecting to database [remote:localhost/openidm] with user 'admin'...OK

3662413d65e9ba2a899e8ce98ec9c3a549be20c8Jan Zeleny

7bfc287b693d3696bd5b3c60bdb7e543eb230f9bStephen Gallagher&gt;</screen>

7bfc287b693d3696bd5b3c60bdb7e543eb230f9bStephen Gallagher

7bfc287b693d3696bd5b3c60bdb7e543eb230f9bStephen Gallagher <variablelist>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>Once connected to the database, you might find the following

7bfc287b693d3696bd5b3c60bdb7e543eb230f9bStephen Gallagher commands useful.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <term><command>info</command></term>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem><para>Shows classes and records</para></listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <term><command>select * from managed_user</command></term>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem><para>Shows all users in the OpenIDM repository</para></listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <term><command>select * from audit_activity</command></term>

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <listitem><para>Shows all activity audit records</para></listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </varlistentry>

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <term><command>select * from audit_recon</command></term>

b9303e06737e6a024239e9c9a6f05fb9ed0a977eStephen Gallagher <listitem><para>Shows all reconciliation audit records</para></listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </variablelist>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </section>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <section xml:id="about-the-sample">

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <title>About the Sample</title>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>OpenIDM connects identity data objects held in different data resources

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose by mapping one object to another. To connect to different data resources,

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose OpenIDM uses <link xlink:href="http://openicf.forgerock.org">OpenICF</link>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose connectors configured for use with the data resources.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>When objects in one data resource change, OpenIDM determines how the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose changes affect other objects, and can make the changes as necessary. This

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov sample demonstrates how OpenIDM does this by using

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <firstterm>reconciliation</firstterm> and

a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov <firstterm>synchronization</firstterm>. OpenIDM reconciliation compares

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose objects in one object set to mapped objects in another object set.

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose Reconciliation can work in write mode, where OpenIDM writes changes to

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose affected objects, or in report mode, where OpenIDM reports on what changes

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose would be written without making the changes. OpenIDM synchronization reflects

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose changes in objects to any mapped objects, making changes as necessary to

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov create or remove mapped objects and links to associate them.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>This sample connects to an XML file holding sample user data. The XML

b36dfa237c0d9ad3a1c9d59790d6aab3b1e2e82dJakub Hrozek file is configured as the authoritative source. In this sample, users are

99dd40a885ed3d42af4bbbde7ee2fc98830544d0Pavel Březina created in the local repository to show you how you can manage local users

b36dfa237c0d9ad3a1c9d59790d6aab3b1e2e82dJakub Hrozek through the REST APIs. You can also use OpenIDM without storing managed

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov objects for users in the local repository, instead reconciling and

a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov synchronizing objects directly through connectors to external data

b36dfa237c0d9ad3a1c9d59790d6aab3b1e2e82dJakub Hrozek resources.</para>

b36dfa237c0d9ad3a1c9d59790d6aab3b1e2e82dJakub Hrozek

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>Furthermore, this sample involves only one data resource. In practice,

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose you can connect as many resources as needed for your deployment.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <variablelist xml:id="about-the-sample-configuration">

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <title>Sample Configuration Files</title>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>You can find configuration files for the sample under the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <filename>openidm/samples/sample1/conf</filename> directory. As you review

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose the samples, keep the following in mind.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <orderedlist>

6480abbd1bba71efa8a834fada6505d1767fabfcJakub Hrozek <listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>OpenIDM regularly scans for any scheduler configuration files in the

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <filename>conf</filename> directory.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>OpenIDM's reconciliation service reads the mappings and actions for

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose the source and target users from <filename>conf/sync.json</filename>.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>Reconciliation runs, querying all users in the source, and then

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose creating, deleting, or modifying users in the local OpenIDM repository

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose according to the synchronization mappings.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>OpenIDM writes all operations to the audit logs in both the internal

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose database and also the flat files in the <filename>openidm/audit</filename>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose directory.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </orderedlist>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <term><filename>conf/provisioner.openicf-xml.json</filename></term>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>This connector configuration file serves for the XML file resource.

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose In this sample, this connector instance acts as the authoritative source

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose for users. In the configuration file you can see that the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <literal>xmlFilePath</literal> is set to

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <filename>samples/sample1/data/xmlConnectorData.xml</filename>, which

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose contains users in XML format.</para>

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <para>For details on the OpenICF connector configuration files see the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <link xlink:href="reference#chap-provisioning"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xlink:role="http://docbook.org/xlink/role/olink"

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov ><citetitle>Provisioning</citetitle></link> chapter in the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <citetitle>Reference</citetitle>.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <term><filename>conf/repo.orientdb.json</filename></term>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>This local repository configuration file maps the data and queries

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov for use with OrientDB.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <term><filename>conf/scheduler-reconcile_systemXmlAccounts_managedUser.json</filename></term>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>The sample scheduler configuration file defines a reconciliation

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose job that, if enabled by setting <literal>"enabled" : true</literal>,

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose starts a reconciliation each minute for the mapping named

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <literal>systemXmlAccounts_managedUser</literal>. The mapping is defined

6480abbd1bba71efa8a834fada6505d1767fabfcJakub Hrozek in the configuration file, <filename>conf/sync.json</filename>.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <programlisting language="javascript">{

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "enabled" : false,

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "type": "cron",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "schedule": "0 0/1 * * * ?",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "invokeService": "org.forgerock.openidm.sync",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "invokeContext": {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "action": "reconcile",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "mapping": "systemXmlfileAccounts_managedUser"

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov }

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov}</programlisting>

a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov <para>You can also start reconciliation through the REST interface. The

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose call to the REST interface is an HTTP POST such as the following.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <screen width="100">$ curl

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose --user admin:admin

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose --request POST

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "http://localhost:8080/openidm/sync?_action=recon&amp;mapping=systemXmlfileAccounts_managedUser"</screen>

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <para>For details on the scheduler configuration please refer to the <link

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xlink:href="reference#chap-scheduling"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xlink:role="http://docbook.org/xlink/role/olink"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose ><citetitle>Scheduling</citetitle></link> chapter in the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <citetitle>Reference</citetitle>.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <term><filename>conf/sync.json</filename></term>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>This sample configuration file defines the configuration for

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose reconciliation and synchronization. The

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <literal>systemXmlAccounts_managedUser</literal> is the mapping for

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose the reconciliation in the scheduler configuration. This entry in

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <filename>conf/sync.json</filename> defines the synchronization mappings

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov between the XML file connector (source) and the local repository

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov (target).</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <programlisting language="javascript">{

a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov "mappings" : [ {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "name" : "systemXmlfileAccounts_managedUser",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "source" : "system/xmlfile/account",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "target" : "managed/user",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "properties" : [ {

6480abbd1bba71efa8a834fada6505d1767fabfcJakub Hrozek "source" : "description",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "target" : "description"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "source" : "firstname",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "target" : "firstname"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "source" : "email",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "target" : "email"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "source" : "lastname",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "target" : "lastname"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov "source" : "name",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "target" : "name"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose } ],

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "policies" : [ {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "situation" : "CONFIRMED",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "action" : "UPDATE"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "situation" : "FOUND",

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov "action" : "IGNORE"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "situation" : "ABSENT",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "action" : "CREATE"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "situation" : "AMBIGUOUS",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "action" : "IGNORE"

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "situation" : "MISSING",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "action" : "IGNORE"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "situation" : "UNQUALIFIED",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "action" : "IGNORE"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose }, {

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "situation" : "UNASSIGNED",

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose "action" : "IGNORE"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose } ]

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose } ]

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose}</programlisting>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>Source and target paths starting with <literal>managed</literal>,

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose such as <literal>managed/user</literal>, always refer to objects in the

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov local OpenIDM repository, whereas paths starting with

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <literal>system</literal>, such as <literal>system/xml/account</literal>,

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose refer to connector objects, in this case the XML file connector.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>To filter objects from the resource for a particular target, you can

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose use the <literal>validTarget</literal> script in the mapping to ensure

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose only users matching specified criteria are considered part of the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose reconciliation. You can use an <literal>onCreate</literal> script in a

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose mapping to set default values for a user created in the target resource.

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose For details on scripting see the <link

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xlink:href="reference#chap-scripting"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xlink:role="http://docbook.org/xlink/role/olink"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose ><citetitle>Scripting</citetitle></link> chapter in the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <citetitle>Reference</citetitle>.</para>

6480abbd1bba71efa8a834fada6505d1767fabfcJakub Hrozek <para>For details on synchronization, reconciliation, and

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <filename>sync.json</filename>, see the <link

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xlink:href="reference#chap-synchronization"

6480abbd1bba71efa8a834fada6505d1767fabfcJakub Hrozek xlink:role="http://docbook.org/xlink/role/olink"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose ><citetitle>Synchronization</citetitle></link> chapter in the

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <citetitle>Reference</citetitle>.</para>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </listitem>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </varlistentry>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </variablelist>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose </section>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <section xml:id="sample-running-reconciliation">

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <title>Running Reconciliation</title>

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <para>If OpenIDM is not running, start it as described in the procedure

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose <link xlink:href="install-guide#run-openidm"

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Start OpenIDM

5b680ac8ef46fc1714f2ab59a07f68ac386ad89bSumit Bose Services</citetitle></link>.</para>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <para>Reconcile the objects in the resources either by editing

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <filename>conf/sync.json</filename> to set <literal>"enabled" : true</literal>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose and then waiting until the scheduled reconciliation happens, or by using the

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose REST interface.</para>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <screen width="100">$ curl

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose --user admin:admin

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose --request POST

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose "http://localhost:8080/openidm/sync?_action=recon&amp;mapping=systemXmlfileAccounts_managedUser"

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose{"reconId":"cc0c849b-1ed3-4822-aa47-f44a9fa24489"}</screen>

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <para>OpenIDM responds with the reconciliation identifier.</para>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <para>By default, logging is turned on, so debug messages are displayed on

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose the console.</para>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose </section>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov <section xml:id="sample-viewing-users-logs">

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <title>Viewing Users &amp; Logs</title>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <para>After reconciliation runs, you can use the REST interface to display

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose all users in the local repository, by performing an HTTP GET on the following

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose link: <link xlink:show="new"

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose xlink:href="http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids"

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose >http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids</link>.</para>

795315c21d865a3060fc50bea79a758a7de7a956Lukas Slebodnik

a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov <para>OpenIDM returns a JSON file. Depending on your browser, it can display

a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov the JSON or download it as a file. Alternatively, you can use the following

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <link xlink:href="http://curl.haxx.se/"><command>curl</command></link>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose command to get the JSON file.</para>

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose <screen>$ curl

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose --user admin:admin

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose --request GET

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose{

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose "query-time-ms":1,

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose "result":[

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose {

83bf46f4066e3d5e838a32357c201de9bd6ecdfdNikolai Kondrashov "_id":"joe",

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose "_rev":"0"

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose },{

0eb8bf8c05a5535ed44c71342f4bed5b821cfa06Sumit Bose "_id":"DDOE1",

"_rev":"0"

}],

"conversion-time-ms":0

}

</screen>

<para>If you created user <literal>joe</literal> as described previously in

this guide, you see IDs for two users, the second user

<literal>DDOE1</literal> created during reconcililation. Now try a RESTful

GET of user <literal>DDOE1</literal> by appending the user ID to the managed

user URL, <link xlink:href="http://localhost:8080/openidm/managed/user/"

xlink:show="new">http://localhost:8080/openidm/managed/user/</link>.</para>

<screen>$ curl --user admin:admin http://localhost:8080/openidm/managed/user/DDOE1

{

"lastname":"Doe1",

"firstname":"Darth1",

"_id":"DDOE1",

"_rev":"0",

"email":["mail1@example.com"],

"description":"Created By XML1",

"name":"DDOE1"

}</screen>

<para>In the OrientDB console, connect to the database, and then query the

users and audit logs.</para>

<screen>&gt; connect remote:localhost/openidm admin admin

Connecting to database [remote:localhost/openidm] with user 'admin'...OK

&gt; select * from managed_user

---+---------+...+--------------------+...

#| RID |...|_openidm_id |...

---+---------+...+--------------------+...

0| #8:0|...|joe |...

1| #8:1|...|DDOE1 |...

---+---------+...+--------------------+...

2 item(s) found. Query executed in 0.011 sec(s).

&gt; select * from audit_activity

---+---------+--------------------+--------------------+--------------------+...

#| RID |rev |status |timestamp |...

---+---------+--------------------+--------------------+--------------------+...

0| #11:0|0 |SUCCESS |2011-12-02T07:34:19 |...

1| #11:1|0 |SUCCESS |2011-12-02T07:34:46 |...

---+---------+--------------------+--------------------+--------------------+...

2 item(s) found. Query executed in 0.013 sec(s).

&gt; select * from audit_recon

---+---------+--------------------+--------------------+--------------------+...

#| RID |timestamp |sourceObjectId |_openidm_id |...

---+---------+--------------------+--------------------+--------------------+...

0| #12:0|2011-12-02T07:34:46 |system/xmlfile/account/1|02f5c8fd-0cc4-4a5...

1| #12:1|2011-12-02T07:34:46 |null |4707745d-6b10-4c75-9b...

---+---------+--------------------+--------------------+--------------------+...

2 item(s) found. Query executed in 0.01 sec(s).</screen>

<para>Also notice the audit logs in the <filename>openidm/audit</filename>

directory, which are in CSV format.</para>

<screen>$ ls /path/to/openidm/audit/

activity.csv recon.csv</screen>

</section>

<section xml:id="sample-adding-users-resource">

<title>Adding Users in a Resource</title>

<para>Add a user to the source connector XML data file to see reconciliation

in action. During the next reconciliation, OpenIDM finds the new user in the

source connector, and creates the user in the local repository. To add the

user, copy the following XML into

<filename>openidm/samples/sample1/data/xmlConnectorData.xml</filename>.</para>

<programlisting language="xml">&lt;ri:__ACCOUNT__&gt;

&lt;icf:__UID__&gt;12345&lt;/icf:__UID__&gt;

&lt;icf:__NAME__&gt;Daffy Duck&lt;/icf:__NAME__&gt;

&lt;icf:__PASSWORD__&gt;123456789&lt;/icf:__PASSWORD__&gt;

&lt;ri:email&gt;daffy.duck@forgerock.com&lt;/ri:email&gt;

&lt;ri:lastname&gt;Duck&lt;/ri:lastname&gt;

&lt;ri:firstname&gt;Daffy&lt;/ri:firstname&gt;

&lt;/ri:__ACCOUNT__&gt;</programlisting>

<para>Run reconciliation as described in the section on <link

linkend="sample-running-reconciliation"><citetitle>Running

Reconciliation</citetitle></link>. After reconciliation has run, query the

local repository to see the new user appear in the list of all users under

<link xlink:show="new"

xlink:href="http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids"

>http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids</link>.</para>

<screen>$ curl

--user admin:admin

--request GET

http://localhost:8080/openidm/managed/user/?_query-id=query-all-ids

{

"query-time-ms":1,

"result":[{

"_id":"joe",

"_rev":"0"

},{

"_id":"DDOE1",

"_rev":"0"

},{

"_id":"Daffy Duck",

"_rev":"0"

}],

"conversion-time-ms":0

}</screen>

<para>Also look at the reconciliation audit log,

<filename>openidm/audit/recon.csv</filename> to see what took place during

reconciliation. This formatted excerpt from the log covers two

reconciliation runs.</para>

<programlisting width="110">

"_id", "action",...,"reconId","situation","sourceObjectId",..., "targetObjectId","timestamp";

"02...","CREATE",...,"cc0...", "ABSENT", "system/xmlfile/account/1",..., "managed/user/DDOE1",...;

"47...","IGNORE",...,"cc0...", "UNQUALIFIED","" ,..., "managed/user/joe",...;

"79...","UPDATE",...,"d15...", "CONFIRMED","system/xmlfile/account/1",..., "managed/user/DDOE1",...;

"af...","CREATE",...,"d15...", "ABSENT", "system/xmlfile/account/12345",...,"managed/user/Daffy Duck",...;

"23...","IGNORE",...,"d15...", "UNQUALIFIED","",..., "managed/user/joe",...;

</programlisting>

<para>The important fields in the audit log are the action, the situation,

the source <literal>sourceObjectId</literal>, and the target

<literal>targetObjectId</literal>. For each object in the source,

reconciliation results in a situation that leads to an action on the

target.</para>

<para>In the first reconciliation run (the abbreviated

<literal>reconID</literal> is shown as <literal>cc0...</literal>), the source

object does not exist in the target, resulting in an ABSENT situation and an

action to CREATE the object in the target. The object created earlier in the

target does not exist in the source, and so is IGNORED.</para>

<para>In the second reconciliation run (the abbreviated

<literal>reconID</literal> is shown as <literal>d15...</literal>) after you

added a user to the source XML, OpenIDM performs an UPDATE on the user object

<literal>DDOE1</literal> that already exists in the target, in this case

changing the internal ID. OpenIDM performs a CREATE on the target for the

new user.</para>

<para>You configure the action that OpenIDM takes based on an object's

situation in the configuration file, <filename>conf/sync.json</filename>.

For the list of all possible situations and actions, see the <link

xlink:href="reference#chap-synchronization"

xlink:role="http://docbook.org/xlink/role/olink"

><citetitle>Synchronization</citetitle></link> chapter in the

<citetitle>Reference</citetitle>.</para>

<para>For details on auditing, see the <link

xlink:href="reference#chap-auditing"

xlink:role="http://docbook.org/xlink/role/olink"

><citetitle>Auditing</citetitle></link> chapter in the

<citetitle>Reference</citetitle>.</para>

</section>

<section xml:id="sample-adding-users-rest">

<title>Adding Users Through REST</title>

<para>You can also add users directly to the local repository through the

REST interface. The following example adds a user named James Berg.</para>

<para>On UNIX, Linux, and Mac OS X</para>

<screen>$ curl

--user admin:admin

--request PUT

--data '{

"name":"james",

"lastname":"Berg",

"firstname":"James",

"email":"james2@examplerock.com",

"fullname":"hallo2",

"description":"Created by OpenIDM REST.",

"userPassword":"asdfkj23"

}'

http://localhost:8080/openidm/managed/user/james

{"_rev":"0","_id":"james"}</screen>

<para>On Windows</para>

<screen>C:\&gt;curl

--user admin:admin

--request PUT

--data {

\"name\":\"james\",

\"lastname\":\"Berg\",

\"firstname\":\"James\",

\"email\":\"james2@examplerock.com\",

\"fullname\":\"hallo2\",

\"description\":\"Created by OpenIDM REST.\",

\"userPassword\":\"asdfkj23\"

}

http://localhost:8080/openidm/managed/user/james

{"_rev":"0","_id":"james"}</screen>

<para>OpenIDM creates the new user in the repository. If you configure a

mapping to apply changes from the local repository to the XML file connector

as a target, OpenAM next updates the XML file to add the new user.</para>

</section>

</chapter>