b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder<?xml version="1.0" encoding="UTF-8"?>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder<chapter xml:id='chap-sample'

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder xmlns='http://docbook.org/ns/docbook'

2c81e2bd9f9dee247c74a642c03620a2f799d0a4Razvan Pascanu version='5.0' xml:lang='en'

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

bf4226899034bddcfe81c870cbedf28c2890370eChristian Maeder xmlns:xlink='http://www.w3.org/1999/xlink'

55c5e901b5c3466300009135585bc70bd576dcb6Christian Maeder xmlns:xinclude='http://www.w3.org/2001/XInclude'>

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder

55c5e901b5c3466300009135585bc70bd576dcb6Christian Maeder<title>OpenIDM Sample</title>

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder

55c5e901b5c3466300009135585bc70bd576dcb6Christian Maeder <para>In the current distribution of OpenIDM the sample

54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder in <filename>openidm/samples/sample1</filename> is configured and enabled by

55c5e901b5c3466300009135585bc70bd576dcb6Christian Maeder default. This chapter provides an overview of the sample and how it is

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder configured. To see a listing and an overview of the rest of the samples

c208973c890b8f993297720fd0247bc7481d4304Christian Maeder provided see the README found in <filename>openidm/samples</filename> and in

55c5e901b5c3466300009135585bc70bd576dcb6Christian Maeder the chapter <link xlink:href="install-guide#chap-samples"

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder xlink:role="http://docbook.org/xlink/role/olink"><citetitle>More OpenIDM

54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder Samples</citetitle></link>.</para>

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder <section xml:id="before-you-begin-sample">

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder <title>Before You Begin</title>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <para>Install OpenIDM as described in the chapter on <link

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder xlink:href="install-guide#chap-install"

697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Installing

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder OpenIDM Services</citetitle></link>.</para>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <para>OpenIDM comes with an internal noSQL database, OrientDB for use as

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder the internal repository out of the box. This makes it easy to get started

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder with OpenIDM. OrientDB is not yet supported for production use, however,

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder so use a supported JDBC database when moving to production.</para>

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder

c4df2219ea6f47a5e510503e475c38362e8464ebChristian Maeder <para>If you want to query the internal noSQL database, download and unzip

c4df2219ea6f47a5e510503e475c38362e8464ebChristian Maeder <link xlink:href="http://code.google.com/p/orient/wiki/Download"

e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder xlink:show="new">OrientDB 1.0</link>. Once you have downloaded and unzipped

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder OrientDB, you can find the shell console in the <filename>bin</filename>

333780eae2be9f20fe46dedbf5eb46ffa0cbfd02Christian Maeder directory. Start OrientDB console using either <command>console.sh</command>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder or <command>console.bat</command>, and then connect to the running OpenIDM

e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder with the <command>connect</command> command.</para>

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder <screen>$ /path/to/orientdb-1.0rc6/bin/console.sh

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder&gt;

edd35c6c970fa1707dc6ad7a3ba26119e0046223Cui Jian&gt; connect remote:localhost/openidm admin admin

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder

6948b7295a0521212803f15cf919395d2073e2c9Christian MaederConnecting to database [remote:localhost/openidm] with user 'admin'...OK

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder&gt;</screen>

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder

2c81e2bd9f9dee247c74a642c03620a2f799d0a4Razvan Pascanu <variablelist>

2c81e2bd9f9dee247c74a642c03620a2f799d0a4Razvan Pascanu <para>Once connected to the database, you might find the following

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder commands useful.</para>

2c81e2bd9f9dee247c74a642c03620a2f799d0a4Razvan Pascanu <varlistentry>

e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder <term><command>info</command></term>

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <listitem><para>Shows classes and records</para></listitem>

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder </varlistentry>

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder <varlistentry>

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder <term><command>select * from managed_user</command></term>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <listitem><para>Shows all users in the OpenIDM repository</para></listitem>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder </varlistentry>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <varlistentry>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <term><command>select * from audit_activity</command></term>

e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder <listitem><para>Shows all activity audit records</para></listitem>

04d04d19fdd5320953c78ad5b6d2d11f85bc4bcfChristian Maeder </varlistentry>

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder <varlistentry>

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder <term><command>select * from audit_recon</command></term>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <listitem><para>Shows all reconciliation audit records</para></listitem>

6948b7295a0521212803f15cf919395d2073e2c9Christian Maeder </varlistentry>

afddef51d985ac2ea76a6bd846f04cbbc4311305Razvan Pascanu </variablelist>

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian </section>

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian <section xml:id="about-the-sample">

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian <title>About the Sample</title>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <para>OpenIDM connects identity data objects held in different data resources

afe76697dd6888856a066934a1112a38809b27faChristian Maeder by mapping one object to another. To connect to different data resources,

3fe83d4c932a8266edcf0304a97814c59821d91fChristian Maeder OpenIDM uses <link xlink:href="http://openicf.forgerock.org">OpenICF</link>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder connectors configured for use with the data resources.</para>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <para>When objects in one data resource change, OpenIDM determines how the

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder changes affect other objects, and can make the changes as necessary. This

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder sample demonstrates how OpenIDM does this by using

64325303fc09fc4d88ced49be11ff2d29966422aCui Jian <firstterm>reconciliation</firstterm> and

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <firstterm>synchronization</firstterm>. OpenIDM reconciliation compares

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder objects in one object set to mapped objects in another object set.

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder Reconciliation can work in write mode, where OpenIDM writes changes to

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder affected objects, or in report mode, where OpenIDM reports on what changes

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder would be written without making the changes. OpenIDM synchronization reflects

da955132262baab309a50fdffe228c9efe68251dCui Jian changes in objects to any mapped objects, making changes as necessary to

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian create or remove mapped objects and links to associate them.</para>

3fe83d4c932a8266edcf0304a97814c59821d91fChristian Maeder

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian <para>This sample connects to an XML file holding sample user data. The XML

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian file is configured as the authoritative source. In this sample, users are

afe76697dd6888856a066934a1112a38809b27faChristian Maeder created in the local repository to show you how you can manage local users

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder through the REST APIs. You can also use OpenIDM without storing managed

afe76697dd6888856a066934a1112a38809b27faChristian Maeder objects for users in the local repository, instead reconciling and

afe76697dd6888856a066934a1112a38809b27faChristian Maeder synchronizing objects directly through connectors to external data

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder resources.</para>

5ff3af2a00b2663a7aaeffa820338a895dc38b82Cui Jian

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <para>Furthermore, this sample involves only one data resource. In practice,

da955132262baab309a50fdffe228c9efe68251dCui Jian you can connect as many resources as needed for your deployment.</para>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <variablelist xml:id="about-the-sample-configuration">

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <title>Sample Configuration Files</title>

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <para>You can find configuration files for the sample under the

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <filename>openidm/samples/sample1/conf</filename> directory. As you review

3fe83d4c932a8266edcf0304a97814c59821d91fChristian Maeder the samples, keep the following in mind.</para>

4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder <orderedlist>

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <listitem>

da955132262baab309a50fdffe228c9efe68251dCui Jian <para>OpenIDM regularly scans for any scheduler configuration files in the

3fe83d4c932a8266edcf0304a97814c59821d91fChristian Maeder <filename>conf</filename> directory.</para>

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian </listitem>

3fe83d4c932a8266edcf0304a97814c59821d91fChristian Maeder <listitem>

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <para>OpenIDM's reconciliation service reads the mappings and actions for

9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder the source and target users from <filename>conf/sync.json</filename>.</para>

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder </listitem>

0a5165c161ce13d434b5c0488b533a8de98aafaaChristian Maeder <listitem>

9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder <para>Reconciliation runs, querying all users in the source, and then

afe76697dd6888856a066934a1112a38809b27faChristian Maeder creating, deleting, or modifying users in the local OpenIDM repository

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder according to the synchronization mappings.</para>

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder </listitem>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <listitem>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <para>OpenIDM writes all operations to the audit logs in both the internal

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder database and also the flat files in the <filename>openidm/audit</filename>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder directory.</para>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder </listitem>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder </orderedlist>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <varlistentry>

d24317c8197e565e60c8f41309de246249c1e57eChristian Maeder <term><filename>conf/provisioner.openicf-xml.json</filename></term>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <listitem>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <para>This connector configuration file serves for the XML file resource.

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder In this sample, this connector instance acts as the authoritative source

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder for users. In the configuration file you can see that the

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <literal>xmlFilePath</literal> is set to

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <filename>samples/sample1/data/xmlConnectorData.xml</filename>, which

afe76697dd6888856a066934a1112a38809b27faChristian Maeder contains users in XML format.</para>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder <para>For details on the OpenICF connector configuration files see the

49d8e1a419ee5658d23762335af121179a68669fCui Jian <link xlink:href="integrators-guide#chap-resource-conf"

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

afe76697dd6888856a066934a1112a38809b27faChristian Maeder ><citetitle>Connecting to External Resources</citetitle></link> chapter in

afe76697dd6888856a066934a1112a38809b27faChristian Maeder the <citetitle>Integrator's Guide</citetitle>.</para>

afe76697dd6888856a066934a1112a38809b27faChristian Maeder </listitem>

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder </varlistentry>

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <varlistentry>

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder <term><filename>conf/scheduler-reconcile_systemXmlAccounts_managedUser.json</filename></term>

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder <listitem>

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder <para>The sample scheduler configuration file defines a reconciliation

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder job that, if enabled by setting <literal>"enabled" : true</literal>,

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder starts a reconciliation each minute for the mapping named

e04726af1ef4af2f172f6ce2a075a4f004ea98f1Cui Jian <literal>systemXmlAccounts_managedUser</literal>. The mapping is defined

b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder in the configuration file, <filename>conf/sync.json</filename>.</para>

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <programlisting language="javascript">{

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder "enabled" : false,

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "type": "cron",

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "schedule": "0 0/1 * * * ?",

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "invokeService": "org.forgerock.openidm.sync",

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "invokeContext": {

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "action": "reconcile",

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "mapping": "systemXmlfileAccounts_managedUser"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder }

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder}</programlisting>

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <para>You can also start reconciliation through the REST interface. The

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder call to the REST interface is an HTTP POST such as the following.</para>

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <screen width="100">$ curl

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian --header "X-OpenIDM-Username: openidm-admin"

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian --header "X-OpenIDM-Password: openidm-admin"

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian --request POST

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

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian <para>For details on the scheduler configuration see the <link

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian xlink:href="integrators-guide#chap-scheduler-conf"

37e30366abd83c00a5d5447b45694627fd783de8Cui Jian xlink:role="http://docbook.org/xlink/role/olink"

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder ><citetitle>Scheduling Synchronization</citetitle></link> chapter in the

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder <citetitle>Integrator's Guide</citetitle>.</para>

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder </listitem>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder </varlistentry>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <varlistentry>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <term><filename>conf/sync.json</filename></term>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <listitem>

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <para>This sample configuration file defines the configuration for

b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder reconciliation and synchronization. The

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <literal>systemXmlAccounts_managedUser</literal> is the mapping for

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder the reconciliation in the scheduler configuration. This entry in

54a0a1e10bd93721cf52dbd9b816c8f108997ec0Christian Maeder <filename>conf/sync.json</filename> defines the synchronization mappings

b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder between the XML file connector (source) and the local repository

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder (target).</para>

f4ae50539e67874b6162f8334f6782a0d66acefaCui Jian <programlisting language="javascript">

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder{

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder "mappings": [

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder {

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "name": "systemXmlfileAccounts_managedUser",

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder "source": "system/xmlfile/account",

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "target": "managed/user",

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "correlationQuery": {

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "type": "text/javascript",

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "source": "var query = {'_query-id' : 'for-userName',

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder 'userName' : source.name};query;"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder },

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "properties": [

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder {

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "source": "description",

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "target": "description"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder },

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder {

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "source": "firstname",

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "target": "givenName"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder },

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder {

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "source": "email",

e220b2051a2342a9291721e6c7f408860bed01b7Jorina Freya Gerken "target": "email"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder },

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder {

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "source": "lastname",

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "target": "familyName"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder },

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder {

5efed683fd173e9d53bd5f1929ba5b0c8a228710Christian Maeder "source": "name",

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "target": "userName"

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder },

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder {

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "source": "name",

5efed683fd173e9d53bd5f1929ba5b0c8a228710Christian Maeder "target": "_id"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder }

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder ],

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder "policies": [

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder {

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder "situation": "CONFIRMED",

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder "action": "UPDATE"

da955132262baab309a50fdffe228c9efe68251dCui Jian },

da955132262baab309a50fdffe228c9efe68251dCui Jian {

d11391a2447a2005329a95b5d770f24e62bf5b63Christian Maeder "situation": "FOUND",

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder "action": "IGNORE"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder },

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder {

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder "situation": "ABSENT",

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder "action": "CREATE"

90a0050cf7979b2ca1fde7991462851abcbcf3a3Christian Maeder },

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder {

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "situation": "AMBIGUOUS",

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "action": "IGNORE"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder },

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder {

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "situation": "MISSING",

b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder "action": "IGNORE"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder },

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder {

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "situation": "SOURCE_MISSING",

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "action": "IGNORE"

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder },

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder {

e44a4fd691fbfb3a1ac9f3f31aae7d5245055760Christian Maeder "situation": "UNQUALIFIED",

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "action": "IGNORE"

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder },

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder {

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder "situation": "UNASSIGNED",

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder "action": "IGNORE"

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder }

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder ]

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder }

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder ]

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder}</programlisting>

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder <para>Source and target paths starting with <literal>managed</literal>,

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder such as <literal>managed/user</literal>, always refer to objects in the

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder local OpenIDM repository, whereas paths starting with

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <literal>system</literal>, such as <literal>system/xmlfile/account</literal>,

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder refer to connector objects, in this case the XML file connector.</para>

3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <para>To filter objects from the resource for a particular target, you can

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder use the <literal>validTarget</literal> script in the mapping to ensure

e953bea49e7f0e1a43bccf2a66c5e2a2b50848e0Christian Maeder only users matching specified criteria are considered part of the

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder reconciliation. You can use an <literal>onCreate</literal> script in a

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder mapping to set default values for a user created in the target resource.

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder For details on scripting see the <link

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder xlink:href="integrators-guide#appendix-scripting"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder xlink:role="http://docbook.org/xlink/role/olink"

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder ><citetitle>Scripting</citetitle></link> appendix in the

120eec9ff1748e1ae786e2ab073234198bc0f701Christian Maeder <citetitle>Integrator's Guide</citetitle>.</para>

bf4226899034bddcfe81c870cbedf28c2890370eChristian Maeder <para>For details on synchronization, reconciliation, and

4cb77926a2d85ce3bb32ac0938f0100c8c528dc2Till Mossakowski <filename>sync.json</filename>, see the <link

e220b2051a2342a9291721e6c7f408860bed01b7Jorina Freya Gerken xlink:href="integrators-guide#chap-synchronization"

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

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

<citetitle>Integrator's Guide</citetitle>.</para>

</listitem>

</varlistentry>

</variablelist>

</section>

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

<title>Running Reconciliation</title>

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

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

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

Services</citetitle></link>.</para>

<para>Reconcile the objects in the resources either by editing

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

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

REST interface.</para>

<screen width="100"><?dbfo pgwide="1"?>$ curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-admin"

--request POST

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

<para>To see what happened, review the CSV format logs in the

<filename>openidm/audit/</filename> directory.</para>

</section>

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

<title>Viewing Users &amp; Logs</title>

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

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

URL:

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

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

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

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

command to get the JSON file.</para>

<screen>$ curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-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"

}],

"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,

<literal>http://localhost:8080/openidm/managed/user/</literal>.</para>

<screen>$ curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-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. The following shows edited excerpts from a console

session querying OrientDB.</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>Again, this information is also available in the CSV format audit logs

located in the <filename>openidm/audit</filename> directory.</para>

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

access.csv 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

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

<screen>$ curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-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"><?dbfo pgwide="1"?>

"_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="integrators-guide#chap-synchronization"

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

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

<citetitle>Integrator's Guide</citetitle>.</para>

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

xlink:href="integrators-guide#chap-auditing"

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

><citetitle>Audit Logging</citetitle></link> chapter in the

<citetitle>Integrator's Guide</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

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-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

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-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>