How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I monitor LiveSync activity using REST in IDM (All versions)?

Last updated Mar 15, 2021

The purpose of this article is to provide information on monitoring LiveSync activity in IDM using the REST API. You can use this information to help you troubleshoot failed synchronization jobs.


Monitoring LiveSync activity

The following example demonstrates returning details for the last two LiveSync schedules and then following up on a specific schedule that failed. You will need to adjust these queries to fit your environment, but they should help you to monitor and resolve your own LiveSync schedule issues.

Note

Please be aware of the following:

  • Using the syncToken endpoint is not a reliable indicator of the health of a job because a failed LiveSync will not update the syncToken. 
  • File-based audit event handlers (such as CSV or JSON) do not support paging, which means you cannot use the _pageSize parameter. If you want paging, you should use the JDBC audit event handler. See Integrator's Guide › Specifying the Audit Query Handler for further information on the different audit event handlers.

Example

Return details of the last two schedule syncs using the following query, where you will need to update userId to match the LiveSync schedule:

  • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" "http://localhost:8080/openidm/audit/access?_queryFilter=userId+sw+\"Scheduled\"&_fields=timestamp,transactionId,userId,response,request&_sortKeys=-timestamp" Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" "http://localhost:8080/openidm/audit/access?_queryFilter=userId+sw+\"Scheduled\"&_fields=timestamp,transactionId,userId,response,request&_sortKeys=-timestamp"

Example response (where both LiveSync schedules failed):

{     "remainingPagedResults": -1,   "pagedResultsCookie": null,   "resultCount": 2,   "result": [     {       "_id": "d33e369d-7b82-4f4f-9a70-30d196aacddd-24438",       "timestamp": "2017-11-14T00:15:45.500Z",       "transactionId": "d33e369d-7b82-4f4f-9a70-30d196aacddd-24420",       "userId": "Scheduled d4528b10-cb4f-4b2f-8c13-8deff9677d1b-Fri Nov 10 15:24:30 CDT 2017",       "response": {         "status": "FAILED",         "statusCode": null,         "elapsedTime": "75475",         "elapsedTimeUnits": "MILLISECONDS"       },       "request": {         "protocol": "CREST",         "operation": "ScheduledTask",         "detail": {           "taskName": "scheduler-service-group.d4528b10-cb4f-4b2f-8c13-8deff9677d1b"         }       }     },     {       "_id": "d33e369d-7b82-4f4f-9a70-30d196aacddd-24382",       "timestamp": "2017-11-14T00:15:21.500Z",       "transactionId": "d33e369d-7b82-4f4f-9a70-30d196aacddd-24379",       "userId": "Scheduled d4528b10-cb4f-4b2f-8c13-8deff9677d1b-Fri Nov 10 15:19:00 CDT 2017",       "response": {         "status": "FAILED",         "statusCode": null,         "elapsedTime": "75517",         "elapsedTimeUnits": "MILLISECONDS"       },       "request": {         "protocol": "CREST",         "operation": "ScheduledTask",         "detail": {           "taskName": "scheduler-service-group.d4528b10-cb4f-4b2f-8c13-8deff9677d1b"         }       }     }   ] }

You can then find out more about a failed sync in the audit log using the details returned from the above call. For example, you could use one of the following calls with the corresponding transactionId, depending on what type of events you are interested in:

  • Access events:
    • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" "http://localhost:8080/openidm/audit/access/d33e369d-7b82-4f4f-9a70-30d196aacddd-24420"
    • Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" "http://localhost:8080/openidm/audit/access/d33e369d-7b82-4f4f-9a70-30d196aacddd-24420" This call will indicate the status of the job (either a SUCCESS or FAILED) and report the latest timestamp.
  • Activity events:
    • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" "http://localhost:8080/openidm/audit/activity?_queryFilter=userId+sw+\"Scheduled\"&_status+eq+\"FAILED\"&_transactionId+eq+\"d33e369d-7b82-4f4f-9a70-30d196aacddd-24420\"&_sortKeys=-timestamp"
    • ​​​​​​​Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" "http://localhost:8080/openidm/audit/activity?_queryFilter=userId+sw+\"Scheduled\"&_status+eq+\"FAILED\"&_transactionId+eq+\"d33e369d-7b82-4f4f-9a70-30d196aacddd-24420\"&_sortKeys=-timestamp" This call will query the activity logs to see if any failures were reported there.

See Also

How do I read and set the LiveSync syncToken using REST in IDM (All versions)?

How do I query individual reconciliation synchronization failures using REST in IDM (All versions)?

Synchronization Guide › Managing LiveSync Over REST

Audit Guide › Query Audit Logs Over REST

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.