Synchronization | Memority Documentation

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-tasks/`	List all the `SynchronizationTaskDefinition` resources	Create a new `SynchronizationTaskDefinition`	N/A	N/A
`/{tenant}/api/sync/conf/sync-tasks/<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 `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 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 `taskInstanceId`parameter 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` Default pagination: Page size: 20 instances per page Maximum page size: 500 instances per page Sort order: Sorted by `createdAt` in descending order	N/A	Return the list of executions of a synchronization task by providing the identifier of a `SynchronizationTaskDefinition` task configuration with the `taskDefinitionId`parameter.	Success HTTP code 200. Body: JSON list of task progress information
Get an history of all the synchronization task executions of all `SynchronizationTaskDefinition`s	`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.
Get an history of all the synchronization task executions of all `synchronization TaskDefinitions`	`GET /{tenant}/api/sync/sync-tasks/~instances` Parameters `filter`: taskId Options: `expandErrorDetails:` true/false `kind` `taskVisibility:`PRIVATE/PUBLIC `actor` `taskStatus` `simulate:` true/false Default pagination: Page size: 20 instances per page Maximum page size: 500 instances per page Sort order: Sorted by `createdAt` in descending order Example of request with parameter and filter : `GET /{tenant}/api/sync/sync-tasks/~instances?filter=myImport-synctask&option=taskStatus:ERROR`	N/A	Get all synchronization task	Success HTTP code 200. Body: JSON task information of task instances.

Here is an example of a task progress information returned by a monitoring request:

{
  "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 `taskInstanceId`parameter 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)
Get an history of all the executions of the given `ProvisioningTaskDefinition`	`GET /{tenant}/api/sync/prov-tasks/{taskDefinitionId}/~instances` Default pagination: Page size: 20 instances per page Maximum page size: 500 instances per page Sort order: Sorted by `createdAt` in descending order		Return the list of executions of a provsioning task by providing the identifier of a `ProvisioningTaskDefinition` task configuration with the `taskDefinitionId`parameter.	Success HTTP code 200. Body: JSON list of task progress information
Get an history of all the provisioning task executions of all `ProvisioningTaskDefinitions`	`GET /{tenant}/api/sync/prov-tasks/~instances` Parameters `filter`: taskId Options: `expandErrorDetails:` true/false `actor` `taskStatus` `simulate:` true/false Default pagination: Page size: 20 instances per page Maximum page size: 500 instances per page Sort order: Sorted by `createdAt` in descending order Example of request with parameter and filter : `GET /{tenant}/api/sync/prov-tasks/~instances?filter=allIdentities-provtask&option=taskStatus:ERROR`	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 `taskDefinitionId`parameter.	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 `taskDefinitionId`parameter.	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 `taskDefinitionId`parameter.	Success HTTP code 200. Response body: properties indicating the Job scheduling status. Errors HTTP code 404 is the task configuration id is not found.

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 `taskDefinitionId`parameter.	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 `taskDefinitionId`parameter.	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 `taskDefinitionId`parameter.	Success HTTP code 200. Response body: properties indicating the Job scheduling status. Errors HTTP code 404 is the task configuration id is not found.

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.

Overview

Inbound Synchronization

Outbound Synchronization

REST API

Configuring Synchronization Tasks

REST CRUD Configuration

XML Import/Export of Configuration

Launching/Monitoring/Interrupting Synchronization Tasks

Launching/Monitoring/Interrupting Provisioning Tasks

Pausing/Resuming Scheduled Synchronization Task Jobs

Pausing/Resuming Scheduled Provisioning Task Jobs

Read Next