Managing LiveSync Over REST

Because you can trigger liveSync operations over REST (or by using the resource API) you can use an external scheduler to trigger liveSync operations, rather than using the IDM scheduling mechanism.

There are two ways to trigger liveSync over REST:

Use the _action=liveSync parameter directly on the resource. This is the recommended method. The following example calls liveSync on the user accounts in an external LDAP system:

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/system/ldap/account?_action=liveSync"

Target the system endpoint and supply a source parameter to identify the object that should be synchronized. This method matches the scheduler configuration and can therefore be used to test schedules before they are implemented.
The following example calls the same liveSync operation as the previous example:
```
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/system?_action=liveSync&source=system/ldap/account"
```

A successful liveSync operation returns the following response:

{
     "_rev": "000000001ade755f",
     "_id": "SYSTEMLDAPACCOUNT",
     "connectorData": {
         "nativeType": "integer",
         "syncToken": 1
     }
}

Do not run two identical liveSync operations simultaneously. Rather, ensure that the first operation has completed before a second similar operation is launched.

Troubleshooting LiveSync Failures

To troubleshoot a liveSync operation that has not succeeded, include the detailedFailure parameter to return additional information. For example:

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/system/ldap/account?_action=liveSync&detailedFailure=true"

The first time liveSync is called, it does not have a synchronization token in the database to establish which changes have already been processed. The default liveSync behavior is to locate the last existing entry in the change log, and to store that entry in the database as the current starting position from which changes should be applied. This behavior prevents liveSync from processing changes that might already have been processed during an initial data load. Subsequent liveSync operations will pick up and process any new changes.

Typically, in setting up liveSync on a new system, you would load the data initially (by using reconciliation, for example) and then enable liveSync, starting from that base point.

In the case of DS, the change log (cn=changelog) can be read only by uid=admin by default. If you are configuring liveSync with DS, the principal that is defined in the LDAP connector configuration must have access to the change log. For information about allowing a regular user to read the change log, see Allow a User or Application to Read the Change Log in the DS Configuration Guide.

If you see the following error message, you might have forgotten to set changelog-read access for a regular user:

Unable to locate the DS replication change log suffix. Please make
sure it's enabled, and changelog-read access is granted.

Triggering LiveSync Through the UI

LiveSync operations are specific to a system object type (such as system/ldap/account). Apart from scheduling liveSync, as described in "Scheduling LiveSync Through the UI", you can launch a liveSync operation on demand for a particular system object type as follows:

Select Configure > Connectors > connector-name and select the Object Types tab.
Select the Edit icon () next to the object type that you want to synchronize.
Select the Sync tab and select Sync Now.
The Sync Token field displays the current synchronization token for that object type.