Overview
Synchronization service synchronizes IM objects with external accounts hosted on remote applications, such as an LDAP directory, or even a CSV file (CSV files are indeed also considered as "remote applications", just like an LDAP directory). The synchronization is bidirectional, which means:
IDM objects may be imported or updated from one or more external application repositories acting as "sources" (typically CSV files); this is the inbound synchronization
IDM objects may be provisioned on one or more external applications, thus creating/updating external accounts; this is the outbound provisioning
Inbound Synchronization
Synchronization service runs synchronization tasks. The term "synchronization" is a general-purpose word that designates one of the following tasks:
reconciliation: compare the content of a remote application's repository with the IM repository. The reconciliation task starts by scanning all the application's objects (accounts, organizations...), detecting changes regarding the IM state; new applicative accounts added, accounts that no longer exist (i.e. removed by the application's administrator), accounts modified. Reconciliation is usually executed as a scheduled task
import : very similar to the reconciliation, except that accounts deleted locally on the remote application are ignored. In fact, the import task considers that all application's account should be added to the IM, overwriting IM objects that already exist. The import pretends thus that all accounts on the application were just created
Thus, when configuring a synchronization task, via a Synchronization Task Definition, the task type must be chosen, among reconciliation or import.
Outbound Synchronization
provisioning : scan the content of the IDM repository and ensure that all remote accounts that should theoretically be assigned to IM objects (according to the configured settings) really exist and are up-to-date. This may result in creation, deletion or modification of remote accounts, and modification of account group membership.
REST API
Configuring Synchronization Tasks
Very much like Memority, the Synchronization service configuration can be achieved either by REST CRUD operations targeting individual resources, or by importing a whole XML configuration bundle.
REST CRUD Configuration
The usual REST methods enable to configure individual resources:
REST CRUD Configuration
Resource | GET | POST | PUT | DELETE |
|---|
/{tenant}/api/sync/conf/connector-definitions/
| List all the ConnectorDefinition resources | Create a new ConnectorDefinition | N/A | N/A |
/{tenant}/api/sync/conf/connector-definitions/<id>
| Get the ConnectorDefinition identified by <id> | N/A | Update the given ConnectorDefinition | Delete the given ConnectorDefinition |
/{tenant}/api/sync/conf/applications/
| List all the Application resources | Create a new Application | N/A | N/A |
/{tenant}/api/sync/conf/applications/<id>
| Get the Application identified by <id> | N/A | Update the given Application | Delete the given Application |
/{tenant}/api/sync/conf/sync-task-definitions/
| List all the SynchronizationTaskDefinition resources | Create a new SynchronizationTaskDefinition | N/A | N/A |
/{tenant}/api/sync/conf/sync-task-definitions/<id>
| Get the SynchronizationTaskDefinition identified by <id> | N/A | Update the given SynchronizationTaskDefinition | Delete the given SynchronizationTaskDefinition |
/{tenant}/api/sync/conf/sync-task-post-processing-definitions/
| List all the SynchronizationTaskPostProcessingDefinition resources | Create a new SynchronizationTaskPostProcessingDefinition | N/A | N/A |
/{tenant}/api/sync/conf/sync-task-post-processing-definitions/<id>
| Get the SynchronizationTaskPostProcessingDefinition identified by <id> | N/A | Update the given SynchronizationTaskPostProcessingDefinition | Delete the given SynchronizationTaskPostProcessingDefinition |
/{tenant}/api/sync/conf/application-profiles/
| List all the ApplicationProfile resources | Create a new ApplicationProfile | N/A | N/A |
/{tenant}/api/sync/conf/application-profiles/<id>
| Get the ApplicationProfile identified by <id> | N/A | Update the given ApplicationProfile | Delete the given ApplicationProfile |
/{tenant}/api/sync/conf/prov-task-definitions/
| List all the ProvisioningTaskDefinition resources | Create a new ProvisoningTaskDefinition | N/A | N/A |
/{tenant}/api/sync/conf/prov-task-definitions/<id>
| Get the ProvisioningTaskDefinition identified by <id> | N/A | Update the given ProvisioningTaskDefinition | Delete the given ProvisioningTaskDefinition |
/{tenant}/api/sync/conf/prov-task-post-processing-definitions/
| List all the ProvisioningTaskPostProcessingDefinition resources | Create a new ProvisioningTaskPostProcessingDefinition | N/A | N/A |
/{tenant}/api/sync/conf/prov-task-post-processing-definitions/<id>
| Get the ProvisioningTaskPostProcessingDefinition identified by <id> | N/A | Update the given ProvisioningTaskPostProcessingDefinition | Delete the given ProvisioningTaskPostProcessingDefinition |
XML Import/Export of Configuration
Whole XML configuration bundles may be imported/exported, this pertains to both the synchronization (inbound) and provisioning (outbound) cases:
Resource | Description |
|---|
POST /{tenant}/api/sync/conf/dataset/import
| Import an XML configuration bundle (inbound and/or outbound). |
GET /{tenant}/api/sync/conf/dataset/export
| Export an XML configuration bundle (inbound and/or outbound). |
A sample XML configuration bundle is available in Appendix: XML Configuration Samples.
Launching/Monitoring/Interrupting Synchronization Tasks
The execution of synchronization tasks is managed through the REST API.
Synchronization Execution tasks
Action | Resource | Example of Request Body | Description | Return value |
|---|
Launch a synchronization task | POST /{tenant}/api/sync/sync-tasks/<taskDefinitionId>/instances
| N/A | Launch a synchronization task by providing the identifier of a SynchronizationTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 200. Body: a task instance id as a simple string (not JSON): an identifier enabling to monitor the task progress, or interrupt the running task (see below). Errors HTTP code 404 if the task configuration id is not found. HTTP code 409 (conflict) if the same task is already running. It is indeed forbidden to launch concurrent executions of the same task. |
Monitor the execution of a synchronization task | GET /{tenant}/api/sync/sync-tasks/{taskDefinitionId}/instances/{taskInstanceId}?option=expandErrorDetails:true/false
| N/A | Monitor the execution of a synchronization task (if the task is still running) or get its execution outcome (if the task is not running anymore). The taskInstanceIdparameter is the task instance id that was immediately returned when the task was launched (see above). option=expandErrorDetails:true/false is an optional boolean parameter (true or false) enabling to include or not the errorDetails key in the JSON response. It is false by default.
| Success HTTP code 200. Body: JSON task progress information of a given task instance (see example below) Errors HTTP code 404 if the task instance id is not found. |
Get an history of all the executions of the given SynchronizationTaskDefinition | GET /{tenant}/api/sync/sync-tasks/{taskDefinitionId}/instances
| N/A | Return the list of executions of a synchronization task by providing the identifier of a SynchronizationTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 200. Body: JSON list of task progress information Errors HTTP code 404 if the task configuration id is not found. |
Get an history of all the synchronization task executions of all SynchronizationTaskDefinitions | GET /{tenant}/api/sync/sync-tasks/~instances?option=expandErrorDetails:true/false
| N/A | | Success HTTP code 200. Body: a JSON list of task progress informations (see above) |
Interrupt a running synchronization task | POST /{tenant}/api/sync/sync-tasks/{taskDefinitionId}/instances/{taskInstanceId}/~cancel
| N/A | Cancel a running task. | Success HTTP code 200 Body: empty. Errors HTTP code 404 if the task instance id is not found. HTTP code 409 ("conflict") if the task cannot be canceled because it is in a terminal state. |
Here is an example of a task progress information returned by a monitoring request:
CODE
{
"id": "synchronizationTaskProgressId",
"synchronizationTaskId": "synchronizationTaskId",
"progressStatus": "RUNNING",
"outcomeStatus": "ABORTED",
"startDate": "2018-08-08T06:29:53.928Z",
"processingTimeMillis": 5000,
"numberOfEntriesToProcess": 1200,
"numberOfProcessedEntries": 120,
"numberOfErrors": 3,
"progressPercentage": 10,
"errorDetails": [
{
"@class": "com.memority.toolkit.core.error.SimpleErrorRepresentation",
"errorId": "KIT-C0000001",
"label": "INTERNAL_ERROR",
"description": "An internal error occurred",
"properties": {
"prop": "value",
"cause": "Illegal argument : "
},
"fix": "Check the server logs",
"appId": "environment-app-name-v0",
"timestamp": "2018-08-08T06:29:54.827Z",
"logTrackingId": "00aa3d2c-57f8-45a2-bf4c-6dc8512cef32"
}
],
"jobId": "jobId"
}
Launching/Monitoring/Interrupting Provisioning Tasks
The execution of provisioning tasks is managed through the REST API.
Provisioning Execution tasks
Action | Resource | Example of Request Body | Description | Return value |
|---|
Launch a provisioning task | POST /{tenant}/api/sync/prov-tasks/{taskDefinitionId}/instances
| N/A | Launch a provisioning task by providing the identifier of a ProvisioningTaskDefinition task configuration with the taskDefinitionId parameter. | Success HTTP code 200. Body: a task instance id as a simple string (not JSON): an identifier enabling to monitor the task progress, or interrupt the running task (see below). Errors HTTP code 404 if the task configuration id is not found. HTTP code 409 (conflict) if the same task is already running. It is indeed forbidden to launch concurrent executions of the same task. |
Monitor the execution of a provisioning task | GET /{tenant}/api/sync/prov-tasks/{taskDefinitionId}/instances/{taskInstanceId}?option=expandErrorDetails:true/false
| N/A | Monitor the execution of a provisioning task (if the task is still running) or get its execution outcome (if the task is not running anymore). The taskInstanceIdparameter is the task instance id that was immediately returned when the task was launched (see above). option=expandErrorDetails:true/false is an optional boolean parameter (true or false) enabling to include or not the errorDetails key in the JSON response. It is false by default.
| Success HTTP code 200. Body: JSON Task progress information of a given task instance (see example below) Errors HTTP code 404 if the task instance id is not found. |
Get an history of all the executions of the given ProvisioningTaskDefinition | GET /{tenant}/api/sync/prov-tasks/{taskDefinitionId}/instances
| | Return the list of executions of a provsioning task by providing the identifier of a ProvisioningTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 200. Body: JSON list of task progress information Errors HTTP code 404 if the task configuration id is not found. |
Get an history of all the provisioning task executions of all ProvisioningTaskDefinitions | GET /{tenant}/api/sync/prov-tasks/~instances?option=expandErrorDetails:true/false
| N/A | | Success HTTP code 200. Body: a JSON list of task progress informations (see above) |
Interrupt a running provisioning task | POST /{tenant}/api/sync/prov-tasks/{taskDefinitionId}/instances/{taskInstanceId}/~cancel
| N/A | This method is idempotent. It may be launched consecutively several times without error, even if the task is not currently running. | Success HTTP code 200 Body: empty. Errors HTTP code 404 if the task instance id is not found. |
Pausing/Resuming Scheduled Synchronization Task Jobs
Scheduled synchronization task Jobs can be paused/resumed through the REST API.
Actions on Scheduled synchronization task Jobs
Action | Resource | Description | Return value |
|---|
Pause a scheduled synchronization task Job | POST /{tenant}/api/sync/sync-tasks/{taskDefinitionId}/job/~pause
| Pause a scheduled synchronization task Job by providing the identifier of a SynchronizationTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 204 (no content). Errors HTTP code 404 if the task configuration id is not found. |
Resume a paused synchronization task Job | POST /{tenant}/api/sync/sync-tasks/{taskDefinitionId}/job/~resume
| Resume a paused synchronization task Job by providing the identifier of a SynchronizationTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 204 (no content). Errors HTTP code 404 if the task configuration id is not found. |
Report the scheduling state of a synchronization task Job | GET /{tenant}/api/sync/sync-tasks/{taskDefinitionId}/job/~scheduling
| Get the scheduling status of a synchronization task Job by providing the identifier of a SynchronizationTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 200. Response body: properties indicating the Job scheduling status. Errors HTTP code 404 is the task configuration id is not found. |
Pausing/Resuming Scheduled Provisioning Task Jobs
Scheduled provisioning task Jobs can be paused/resumed through the REST API.
Actions on Scheduled provisioning task Jobs
Action | Resource | Description | Return value |
|---|
Pause a scheduled provisioning task Job | POST /{tenant}/api/sync/prov-tasks/{taskDefinitionId}/job/~pause
| Pause a scheduled provisioning task Job by providing the identifier of a ProvisioningTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 204 (no content). Errors HTTP code 404 if the task configuration id is not found. |
Resume a paused provisioning task Job | POST /{tenant}/api/sync/prov-tasks/{taskDefinitionId}/job/~resume
| Resume a paused provisioning task Job by providing the identifier of a ProvisioningTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 204 (no content). Errors HTTP code 404 if the task configuration id is not found. |
Report the scheduling state of a provisioning task Job | GET /{tenant}/api/sync/sync-tasks/{taskDefinitionId}/job/~scheduling
| Get the scheduling status of a provisioning task Job by providing the identifier of a SynchronizationTaskDefinition task configuration with the taskDefinitionIdparameter. | Success HTTP code 200. Response body: properties indicating the Job scheduling status. Errors HTTP code 404 is the task configuration id is not found. |
Read Next
.png)