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