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