Synchronization Actions

When an object has been assigned a situation, the synchronization process takes the configured action on that object. If no action is configured, the default action for that situation applies.

The following actions can be taken:

CREATE

Create and link a target object.

UPDATE

Link and update a target object.

DELETE

Delete and unlink the target object.

LINK

Link the correlated target object.

UNLINK

Unlink the linked target object.

EXCEPTION

Flag the link situation as an exception.

Do not use this action for liveSync mappings.

In the context of liveSync, the EXCEPTION action triggers the liveSync failure handler, and the operation is retried in accordance with the configured retry policy. This is not useful because the operation will never succeed. If the configured number of retries is high, these pointless retries can continue for a long period of time.

If the maximum number of retries is exceeded, the liveSync operation terminates and does not continue processing the entry that follows the failed (EXCEPTION) entry. LiveSync is only resumed at the next liveSync polling interval.

This behavior differs from reconciliation, where a failure to synchronize a single source-target association does not fail the entire reconciliation.

IGNORE

Do not change the link or target object state.

REPORT

Do not perform any action but report what would happen if the default action were performed.

NOREPORT

Do not perform any action or generate any report.

ASYNC

An asynchronous process has been started, so do not perform any action or generate any report.

Launching a Script As an Action

In addition to the static synchronization actions described in "Synchronization Actions", you can provide a script that is run in specific synchronization situations. The script can be either JavaScript or Groovy. You can specify the script inline (with the "source" property), or reference it from a file, (with the "file" property).

The following excerpt of a sample mapping specifies that an inline script should be invoked when a synchronization operation assesses an entry as ABSENT in the target system. The script checks whether the employeeType property of the corresponding source entry is contractor. If so, the source entry is ignored. Otherwise, the entry is created on the target system:

{
    "situation" : "ABSENT",
    "action" : {
        "type" : "text/javascript",
        "globals" : { },
        "source" : "if (source.employeeType === 'contractor') {action='IGNORE'}
                   else {action='CREATE'};action;"
    },
}

Note that the CREATE action updates the target data set automatically. For other actions, you must call openidm.update explicitly, in the script. For example, if you simply want to update the value of the description attribute on the target object, and then ignore the object, your script might look as follows:

"var action = 'IGNORE';
target.description='This entry has been deleted';
openidm.update('system/ldap/account/' + target._id, null, target);
action"

The following variables are available to a script that is called as an action:

source

target

linkQualifier

recon (where recon.actionParam contains information about the current reconciliation operation).

For more information about the variables available to scripts, see Script Variables.

The result obtained from evaluating this script must be a string whose value is one of the synchronization actions listed in "Synchronization Actions". This resulting action is shown in the reconciliation log.

To launch a script as a synchronization action in the Admin UI:

Select Configure > Mappings.
Select the mapping that you want to change.
On the Behaviors tab, click the pencil icon next to the situation whose action you want to change.
On the Perform this Action tab, click Script, then enter the script that corresponds to the action.

Launching a Workflow As an Action

The triggerWorkflowFromSync.js script launches a predefined workflow when a synchronization operation assesses a particular situation. The mechanism for triggering this script is the same as for any other script. The script is provided in the openidm/bin/defaults/script/workflow directory. If you customize the script, copy it to the script directory of your project to ensure that your customizations are preserved during an upgrade.

The parameters for the workflow are passed as properties of the action parameter.

The following extract of a sample mapping specifies that, when a synchronization operation assesses an entry as ABSENT, the workflow named managedUserApproval is invoked:

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

To launch a workflow as a synchronization action in the Admin UI:

Select Configure > Mappings.
Select the mapping that you want to change.
On the Behaviors tab, click the pencil icon next to the situation whose action you want to change.
On the Perform this Action tab, click Workflow, then enter the details of the workflow you want to launch.