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