README revision 3f86d4e2ad2128cae27b60d8584d6befb05505d8
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * Copyright (c) 2014 ForgeRock AS. All rights reserved.
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * The contents of this file are subject to the terms
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * of the Common Development and Distribution License
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * (the License). You may not use this file except in
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * compliance with the License.
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * You can obtain a copy of the License at
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * See the License for the specific language governing
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * permission and limitations under the License.
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * When distributing Covered Code, include this CDDL
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * Header Notice in each file and include the License file
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * at http://forgerock.org/license/CDDLv1.0.html
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * If applicable, add the following below the CDDL Header,
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * with the fields enclosed by brackets [] replaced by
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * your own identifying information:
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter * "Portions Copyrighted [year] [name of copyright owner]"
b138eb36479de1170a91322a845ad9e977c3af56ludovicpSample 5b - "All-or-Nothing" Synchronization of Two Resources
ea170de3e0f20cf18e737b399609e9f0d977d0a6ludo-------------------------------------------------------------
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suterThis sample demonstrates flowing data between external resources just as
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suterin the regular sample 5 on which it is based. It simulates two directory
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suterresources using XML files. It extends sample 5 in that it configures a
62713b44520556f3136c67f8716f905d9a90c463matthew_swiftcompensation script that attempts to ensure either all the synchronization
049c170ba12b61f3ce9dade61e61ec7fc030a5fdlutoffor none of the synchronization is performed after making a change to a
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suterWhenever a change is made to a managed/user resource, OpenIDM implicitly
cddd676de138668ef547099bba407d8b302a1507kenneth_suterattempts to synchronize external resources according to the object mapping
d043ed7798f5f8759dee3ecfe8cccdf25fcdd2d9jvergarain sync.json where managed/user is the source. Typically, if the
d043ed7798f5f8759dee3ecfe8cccdf25fcdd2d9jvergarasynchronization fails--owing to a policy validation for the target,
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_sutermissing required properties for the target, or simply that the target
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suteris unavailable--the synchronization stops, leaving the managed/user
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suterresource, and any targets that were synchronized before the failure,
36bb690a409d9e6e3defd678f47acbbf02bd9167kenneth_suterupdated. The target that failed, and any targets specified
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suterin mappings subsequent to the one that failed are not updated.
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suterThis situation would usually result in a set of systems that are out of
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_sutersync. The only way to re-synchronize them would be a reconciliation operation.
049c170ba12b61f3ce9dade61e61ec7fc030a5fdlutoffReconciliations can be expensive with large data sets.
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suterOpenIDM 3.0 enhances synchronization to multiple targets by providing
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_sutersynchronization details to an "onSync" script, after successfully synchronizing
62713b44520556f3136c67f8716f905d9a90c463matthew_swiftall targets or failing one target. This script hook can be used to "revert"
f167a375fb0a2b0b9c7acdf57667337e10e4b3f1kenneth_suterthe partial change to managed/user and the corresponding external resources
36bb690a409d9e6e3defd678f47acbbf02bd9167kenneth_suterSample 5b includes a script that demonstrates compensating for a synchronization
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suterFor documentation pertaining to this example see:
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suterhttp://openidm.forgerock.org/doc/install-guide/index.html#more-sample5b
36bb690a409d9e6e3defd678f47acbbf02bd9167kenneth_suter Steps 1 and 2 are optional, and only necessary if you'd like to receive emailed
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter recon summaries.
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter 1. Copy the samples/misc/external.email.json file into samples/sample5b/conf
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter $ cp samples/misc/external.email.json samples/sample5b/conf
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter Edit this file to have your email server SMTP details.
23aeaed7a139cd74c6ac0b106a5dd6b9c070e891kenneth_suter See http://openidm.forgerock.org/doc/integrators-guide/index.html#chap-mail
192f9f2d79df74f198031f059df7487978d102a7kenneth_suter for more information.
192f9f2d79df74f198031f059df7487978d102a7kenneth_suter 2. Edit samples/sample5b/script/reconStats.js and change these values to your
192f9f2d79df74f198031f059df7487978d102a7kenneth_suter own email addresses:
62713b44520556f3136c67f8716f905d9a90c463matthew_swift var params = {
192f9f2d79df74f198031f059df7487978d102a7kenneth_suter //UPDATE THESE VALUES
62713b44520556f3136c67f8716f905d9a90c463matthew_swift from : "openidm@example.com",
62713b44520556f3136c67f8716f905d9a90c463matthew_swift to : "idmadmin1@example.com",
62713b44520556f3136c67f8716f905d9a90c463matthew_swift cc : "idmadmin2@example.com,idmadmin3@example.com",
62713b44520556f3136c67f8716f905d9a90c463matthew_swift subject : "Recon stats for " + global.reconName,
62713b44520556f3136c67f8716f905d9a90c463matthew_swift 3. Start OpenIDM with the configuration for sample 5b.
27f8adec83293fb8bd3bfa37175322b0ee3bb933jvergara $ ./startup.sh -p samples/sample5b
27f8adec83293fb8bd3bfa37175322b0ee3bb933jvergara When you start OpenIDM, it creates data in the new external resource file
d818d56321460d97bc2ab94ba725170ca81a604ckenneth_suter that represents an AD directory, samples/sample5b/data/xml_AD_Data.xml.
d818d56321460d97bc2ab94ba725170ca81a604ckenneth_suter The new file is empty until you run reconciliation.
d818d56321460d97bc2ab94ba725170ca81a604ckenneth_suter 4. Run reconciliation.
62ecec3a82a8b838ee76c1f6610902d8fd7015cbmatthew_swift $ curl -k -H "Content-type: application/json" -u "openidm-admin:openidm-admin" -X POST "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser"
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter {"reconId":"b149f0e3-4bb9-4790-9266-fab2e5c80ec6"}
62713b44520556f3136c67f8716f905d9a90c463matthew_swift $ cat /path/to/openidm/samples/sample5b/data/xml_AD_Data.xml
27f8adec83293fb8bd3bfa37175322b0ee3bb933jvergara <?xml version="1.0" encoding="UTF-8"?>
62ecec3a82a8b838ee76c1f6610902d8fd7015cbmatthew_swift <icf:OpenICFContainer xmlns:icf="http://openidm.forgerock.com/xml/ns/public/resource/openicf/resource-schema-1.xsd"
27f8adec83293fb8bd3bfa37175322b0ee3bb933jvergara xmlns:ri="http://openidm.forgerock.com/xml/ns/public/resource/instances/resource-schema-extension"
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
baf2ea03dd87a1fc57296e9552951757984bdd6eludo xsi:schemaLocation="http://openidm.forgerock.com/xml/ns/public/resource/instances/resource-schema-extension samples/sample5b/data/resource-schema-extension.xsd http://openidm.forgerock.com/xml/ns/public/resource/openicf/resource-schema-1.xsd samples/sample5b/data/resource-schema-1.xsd">
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff <ri:__ACCOUNT__>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <ri:firstname>Darth</ri:firstname>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <icf:__DESCRIPTION__/>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <icf:__GROUPS__/>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <icf:__UID__>68077c05-32ae-4438-b250-d23be784ea07</icf:__UID__>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <icf:__NAME__>DDOE1</icf:__NAME__>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <ri:email>mail1@example.com</ri:email>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <icf:__PASSWORD__>initial_Passw0rd</icf:__PASSWORD__>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <icf:__ENABLE__/>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter <ri:lastname>Doe</ri:lastname>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter </ri:__ACCOUNT__>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter </icf:OpenICFContainer>
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter 6. Create a new user in the source external resource file,
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter samples/sample5b/data/xml_LDAP_Data.xml, and run reconciliation again
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter to see the result show up in samples/sample5b/data/xml_AD_Data.xml.
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter 7. Login to the UI at https://localhost:8443/openidmui. You can use
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter openidm-admin/openidm-admin for admin access or DDOE1/TestPassw0rd2 for
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter non-admin access. Updates to DDOE1 will be synced backed to both XML files.
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter 8. Now make the LDAP xml file unavailable by renaming it so it is unreadable.
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter You may need to have root or sudo access to do this:
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter $ mv /path/to/openidm/samples/sample5b/data/xml_LDAP_Data.xml /path/to/openidm/samples/sample5b/data/xml_LDAP_Data.xml.bak
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov 9. Perform an update to the DDOE1 user. It will be updated in managed/user,
cddd676de138668ef547099bba407d8b302a1507kenneth_suter the synchronization to AD will be successful, but the synchronization to
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov LDAP should fail. The compensate.js script will be invoked and will
cddd676de138668ef547099bba407d8b302a1507kenneth_suter attempt to revert the change by performing another update to DDOE1 in
192f9f2d79df74f198031f059df7487978d102a7kenneth_suter managed/user, which will, in turn, perform the sync to AD and LDAP.
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov On the second time through, the sync will again fail to LDAP, which will
cddd676de138668ef547099bba407d8b302a1507kenneth_suter trigger the compensate.js again. The script this time will recognize
cddd676de138668ef547099bba407d8b302a1507kenneth_suter that the change was originally called from compensation and will abort.
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov The original sync error on the first update will be thrown from the
c05ab3910a6e2abef2a2212120f30b9c15ebc5aakenneth_suter script and the UI should display an error.
049c170ba12b61f3ce9dade61e61ec7fc030a5fdlutoff Note that if you are making these updates from the UI, the UI screen does
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov not refresh after the failure. It will still show the "pending update"
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov that has not taken effect. Go back to the Users tab and start over and
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov you will see the old managed/user data has been restored. View the
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov xml_AD_Data.xml file and you will see that DDOE1 has also been reverted
049c170ba12b61f3ce9dade61e61ec7fc030a5fdlutoff to its condition prior to update.
049c170ba12b61f3ce9dade61e61ec7fc030a5fdlutoff 10. If you have configured the recon email summary in steps 1 and 2, you
c8d962c30776d1b772e3f4d0c72760bd05f68647abobrov should have received an email that lists the details for the reconciliation.