README.md revision c1bed58d59da76132e7b960e74825f038c282555
4169N/A/**
1178N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
1178N/A *
1178N/A * Copyright (c) 2014 ForgeRock AS. All rights reserved.
1178N/A *
1178N/A * The contents of this file are subject to the terms
1178N/A * of the Common Development and Distribution License
1178N/A * (the License). You may not use this file except in
1178N/A * compliance with the License.
1178N/A *
1178N/A * You can obtain a copy of the License at
1178N/A * http://forgerock.org/license/CDDLv1.0.html
1178N/A * See the License for the specific language governing
1178N/A * permission and limitations under the License.
1178N/A *
1178N/A * When distributing Covered Code, include this CDDL
1178N/A * Header Notice in each file and include the License file
2362N/A * at http://forgerock.org/license/CDDLv1.0.html
2362N/A * If applicable, add the following below the CDDL Header,
2362N/A * with the fields enclosed by brackets [] replaced by
1178N/A * your own identifying information:
4935N/A * "Portions Copyrighted [year] [name of copyright owner]"
1178N/A */
1178N/A
4033N/A# Sample 1 - One-Way XML -> Internal Repository
4935N/A
1178N/AThe documentation at http://openidm.forgerock.org/doc/install-guide/index.html#chap-sample
1178N/Adescribes how to get started with this sample.
4935N/A
1178N/AThe sample demonstrates reconciliation between an external XML file and the
4033N/AOpenIDM internal repository, with data flowing from the XML file into the
1178N/Ainternal repository.
1178N/A
1178N/AThe configuration files used in this sample are as follows:
1178N/A
4169N/A* samples/sample1/conf/provisioner.openicf-xml.json shows the XML connector
1178N/A configuration.
1178N/A* samples/sample1/conf/schedule-reconcile_systemXmlAccounts_managedUser.json
1178N/A includes a schedule configuration you can use to run reconciliation
1178N/A periodically.
1178N/A* samples/sample1/conf/sync.json describes how identities in the XML file
4033N/A source map to identities in the internal repository target.
0N/A
0N/AData for this sample is stored in samples/sample1/data/xmlConnectorData.xml.
4935N/AThe initial XML file contains two identities.
4169N/A
4169N/A## Starting the sample
4169N/ATo run the sample, start OpenIDM with the configuration for sample 1:
4169N/A
4935N/A $ cd /path/to/openidm
4169N/A $ ./startup.sh -p samples/sample1
4169N/A
4935N/A## Reconciling the sample data
4169N/AInitiate a reconciliation operation over the REST interface, as follows:
4169N/A
4169N/A $ curl -k -H "Content-type: application/json" -u \
4169N/A "openidm-admin:openidm-admin" -X \
4169N/A POST "https://localhost:8443/openidm/recon?_action=recon&mapping=systemXmlfileAccounts_managedUser"
1178N/A
0N/AAlternatively, edit
0N/A
1178N/A samples/sample1/conf/schedule-reconcile_systemXmlAccounts_managedUser.json
0N/A
1178N/Ato enable scheduled reconciliation:
0N/A
1178N/A "enabled" : true,
0N/A
1178N/A## Retrieving sample data from the Internal Repository
0N/AThe following curl command requests all identifiers in OpenIDM's internal
1178N/Arepository. Use it to see the results after reconciliation for example.
1178N/A
1178N/A
1178N/A $ curl -k -u "openidm-admin:openidm-admin" "https://localhost:8443/openidm/managed/user?_queryId=query-all&fields=*&_prettyPrint=true"
1178N/A
0N/A {
1178N/A "result" : [ {
1178N/A "mail" : "bjensen@example.com",
1178N/A "sn" : "Jensen",
1178N/A "passwordAttempts" : "0",
1178N/A "lastPasswordAttempt" : "Thu Oct 16 2014 21:06:21 GMT-0500 (CDT)",
1178N/A "address2" : "",
1178N/A "givenName" : "Barbara",
1178N/A "effectiveRoles" : [ ],
1178N/A "country" : "",
1178N/A "city" : "",
1178N/A "lastPasswordSet" : "",
0N/A "postalCode" : "",
1178N/A "_id" : "bjensen",
1178N/A "_rev" : "6",
1178N/A "description" : "Created By XML1",
1178N/A "accountStatus" : "active",
1178N/A "telephoneNumber" : "1234567",
1178N/A "roles" : [ "openidm-authorized" ],
1178N/A "postalAddress" : "",
1178N/A "stateProvince" : "",
1178N/A "userName" : "bjensen@example.com",
0N/A "effectiveAssignments" : null
1178N/A }, {
1178N/A "mail" : "scarter@example.com",
0N/A "sn" : "Carter",
1178N/A "passwordAttempts" : "0",
0N/A "lastPasswordAttempt" : "Thu Oct 16 2014 21:06:21 GMT-0500 (CDT)",
1178N/A "address2" : "",
4935N/A "givenName" : "Steven",
1178N/A "effectiveRoles" : [ ],
1178N/A "country" : "",
0N/A "city" : "",
1178N/A "lastPasswordSet" : "",
4169N/A "postalCode" : "",
1178N/A "_id" : "scarter",
0N/A "_rev" : "6",
1178N/A "description" : "Created By XML1",
4169N/A "accountStatus" : "active",
1178N/A "telephoneNumber" : "1234567",
4169N/A "roles" : [ "openidm-admin", "openidm-authorized" ],
1178N/A "postalAddress" : "",
4169N/A "stateProvince" : "",
1178N/A "userName" : "scarter@example.com",
4169N/A "effectiveAssignments" : null
1178N/A } ],
4169N/A "resultCount" : 2,
1178N/A "pagedResultsCookie" : null,
0N/A "remainingPagedResults" : -1
1178N/A }
1178N/A
0N/A# Sample 1 through the Administration UI
1178N/A
0N/ABy using the Admin UI you can go through the same exact steps depicted above, but through a point and click experience.
1178N/AWhile the command line examples above are very useful to Developers, the visual experience provided by the Admin UI
4935N/Ais very powerful and easily understood by the Business Users of the system.
0N/A
0N/A## Starting the sample
0N/AThe initial steps are identical...
0N/ATo run the sample, start OpenIDM with the configuration for sample 1:
4169N/A
0N/A $ cd /path/to/openidm
0N/A $ ./startup.sh -p samples/sample1
0N/A
4169N/ANow, though once OpenIDM has started, point your web browser to :
0N/A https://localhost:8443/admin
4169N/A
0N/AIn order to login you will need to provide the "default" credentials :
4169N/A
0N/A username : openidm-admin
0N/A password : openidm-admin
0N/A
4169N/AAfter successfully logging in you will be asked to change your password for security reasons (as the default password
0N/Ais insecure). Note that you will be asked initially to accept the self-signed certificate created during OpenIDM's
4169N/Ainitial startup.
0N/A
4169N/AThe Resources tab shows the XML Connector in the Active state. By clicking on the little pencil you can take a look
0N/Aat the connector details (the XML file path, etc.). Click "Cancel".
4169N/A
4169N/ANext go to the Mappings tab. Click on the mapping representing the mapping definition between the XML file connector
4169N/Aand the Internal Repository (Managed Users). The details of the Mapping will be displayed and you can see the attribute
0N/Amapping as defined in the sync.json included with the sample.
0N/A
0N/A## Reconciling the sample data
4169N/AIn the Mappings tab, click on the "Sync Now" button. You should briefly see a progress bar showing the reconciliation
0N/Ataking place. Once done, you can click on the "Last Synced...." link to see the result of the reconciliation.
4169N/A
0N/AIn order to see the User Association results click on the Correlation sub-menu in the Mappings tab. This table shows
4169N/Athe outcome of the reconciliation by grouping entries in different situation categories and the matching entries which
0N/Ahave been linked, based on the association query that was defined -- in this case you can see the inline script that
4169N/Awas defined as part of the sample :
0N/A
4169N/A var query = {'_queryId' : 'for-userName', 'uid' : source.name};query;
0N/A
4169N/AThis association rule can be changed to use the Expression Builder by specifying the following expression :
0N/A
4169N/A (select) All of the below fields ==> (add) userName
0N/A
4169N/Awhich will translate to the following in the sync.json :
0N/A
4169N/A "correlationQuery" : {
0N/A "type" : "text/javascript",
4169N/A "expressionTree" : {
0N/A "all" : [
4169N/A "userName"
0N/A ]
4169N/A },
0N/A "mapping" : "systemXmlfileAccounts_managedUser",
4169N/A "file" : "ui/correlateTreeToQueryFilter.js"
0N/A },
4169N/A
0N/A## Retrieving sample data from the Internal Repository
4169N/AIn order to see the data which was extracted from the XML file and pushed into the Internal Repository, just click on
0N/Athe User View link at the top right of the Admin UI. Your web browser should now be showing the User
4169N/AManagement screen and by clicking on the Users tab you should see the 2 users from the XML file (bjensen and
4169N/Ascarter).