Asynchronous Reconciliation Using a Workflow

This sample demonstrates asynchronous reconciliation using workflows.

The data for this sample is in the file samples/sync-asynchronous/data/csvConnectorData.csv. That file contains two users, as follows:

"description", "uid", "username", "firstname", "lastname", "email", "mobile..."
"Created ...", "bjensen", "bjensen@example.com", "Barbara", "Jensen", "bjensen@example.com", 1234..."
"Created ...", "scarter", "scarter@example.com", "Steven", "Carter", "scarter@example.com", 1234..."

During the sample, you will reconcile the users in the CSV file with the managed user repository. Instead of creating each user immediately, the reconciliation operation generates an approval request for each ABSENT user (users who are not found in the repository). The configuration for this action is defined in the conf/sync.json file, which specifies that an ABSENT condition should launch the managedUserApproval workflow:

...
    {
        "situation" : "ABSENT",
        "action" : {
            "workflowName" : "managedUserApproval",
            "type" : "text/javascript",
            "file" : "workflow/triggerWorkflowFromSync.js"
        }
    },
 ...

When each request is approved by an administrator, an asynchronous reconciliation operation is launched, that ultimately creates the users in the repository.

Run the Sample

Before you start, prepare IDM as described in "Prepare IDM".

Important

Workflows are not supported with a DS repository. Before you test this sample, install a JDBC repository.

Edit the /path/to/openidm/samples/sync-asynchronous/conf/datasource.jdbc-default.json file with the details of your JDBC repository. For more information, see Select a Repository.

Start IDM with the configuration for this sample:

/path/to/openidm/startup.sh -p samples/sync-asynchronous

The sample is configured to assign new workflow tasks to an admin account named async.admin. Create this account before you begin:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
 "userName": "async.admin",
 "givenName": "async",
 "sn" : "admin",
 "password" : "Passw0rd",
 "displayName" : "async admin",
 "mail" : "async.admin@example.com",
 "authzRoles": [
     { "_ref": "internal/role/openidm-admin" },
     { "_ref": "internal/role/openidm-authorized" }
 ],
 "_id" : "asyncadmin"
 }' \
"http://localhost:8080/openidm/managed/user?_action=create"
{
  "_id":"asyncadmin",
  "_rev":"00000000e8f502db",
  "userName":"async.admin",
  "givenName":"async",
  "sn":"admin",
  "displayName":"async admin",
  "mail":"async.admin@example.com",
  "accountStatus":"active",
  "effectiveRoles":[],
  "effectiveAssignments":[]
}

Run reconciliation over the REST interface:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/recon?_action=recon&mapping=systemCsvfileAccounts_managedUser"
{
  "_id": "98d7f3c5-684e-4ef0-b4f9-f2e816a339cf-32",
  "state": "ACTIVE"
}

The reconciliation operation returns a reconciliation run ID, and the status of the operation.

This reconciliation launches a workflow that generates an approval process for each ABSENT user. The approval processes must be approved by an administrator before the workflow can continue.

Review the approval tasks launched by the reconciliation.
- To review the tasks in the Admin UI, log in to the Admin UI at https://localhost:8443/admin/ using an administrator account (either openidm-admin or async.admin will work) and select Manage > Tasks.
  You should see two task instances launched by the Managed User Approval Workflow.
- To view the approval tasks over REST run the following command:
```
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/workflow/taskinstance?_queryFilter=true&_fields=_id,processDefinitionId"
```
  The request returns two task instances, each with a process ID (_id) and a process definition ID.
```
{
  "result": [
    {
      "_id": "38",
      "processDefinitionId": "managedUserApproval:1:5"
    },
    {
      "_id": "39",
      "processDefinitionId": "managedUserApproval:1:5"
    }
  ],
  ...
}
```
Complete each approval task.
- To complete the approval tasks using the UI, log in to the End User UI at https://localhost:8443/#/login as user async.admin with password Passw0rd.
  You should see two Evaluate request tasks under My Tasks on the Dashboard.
  For each task, select Edit and then select Approve to add the noted users.
- To approve the requests over REST, set requestApproved to true for each task instance, and use the complete action. Specify the _id of each task in the URL.
  For example, to approve the first request:
```
curl \
--header "X-OpenIDM-Username: async.admin" \
--header "X-OpenIDM-Password: Passw0rd" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{"requestApproved": "true"}' \
"http://localhost:8080/openidm/workflow/taskinstance/38?_action=complete"
{
  "Task action performed": "complete"
}
```
  Repeat this command for each task ID.

When the requests have been approved, select Manage > User in the Admin UI to see the new users in the repository, or query the managed users over REST as follows:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/user?_queryFilter=true&_fields=_id"
{
  "result": [
    {
       "_id": "asyncadmin",
       "_rev": "00000000e8f502db"
    }, {
       "_id": "scarter",
       "_rev": "000000007e120780"
    }, {
       "_id": "bjensen",
       "_rev": "00000000d9390751"
    }
  ],
 ...
}