The synchronization engine is one of the core services of OpenIDM. You
configure the synchronization service through a mappings
property that specifies mappings between objects that are managed by the
synchronization engine.
{
"mappings": [ object-mapping object, ... ]
}An object-mapping object specifies the configuration for a mapping of source objects to target objects.
{
"name" : string,
"source" : string,
"target" : string,
"links" : string,
"validSource" : script object,
"validTarget" : script object,
"correlationQuery": script object,
"properties" : [ property object, ... ],
"policies" : [ policy object, ... ],
"onCreate" : script object,
"onUpdate" : script object,
"onLink" : script object,
"onUnlink" : script object
}string, required
Uniquely names the object mapping. Used in the link object identifier.
string, required
Specifies the path of the source object set. Example:
"managed/user".
string, required
Specifies the path of the target object set. Example:
"system/ldap/account".
string, optional
Enables reuse of the links created in another mapping.
Example: "systemLdapAccounts_managedUser" reuses the
links created by a previous mapping whose name is
"systemLdapAccounts_managedUser".
script object, optional
A script that determines if a source object is valid to be
mapped. The script yields a boolean value: true
indicates the source object is valid; false can be
used to defer mapping until some condition is met. In the root scope,
the source object is provided in the "source"
property. If the script is not specified, then all source objects are
considered valid.
script object, optional
A script used during the target phase of reconciliation that
determines if a target object is valid to be mapped. The script yields
a boolean value: true indicates that the target object
is valid; false indicates that the target object should
not be included in reconciliation. In the root scope, the target object is
provided in the "target" property. If the script is
not specified, then all target objects are considered valid for
mapping.
script object, optional
A script that yields a query object to query the target object
set when a source object has no linked target. The syntax for writing
the query depends on the target system of the correlation. See the
section on
Correlation Queries for examples of some
common targets. The source object is provided in the
"source" property in the script scope.
array of property-mapping objects, optional
Specifies mappings between source object properties and target object properties, with optional transformation scripts.
array of policy objects, optional
Specifies a set of link conditions and associated actions to take in response.
script object, optional
A script to execute when a target object is to be created,
after property mappings have been applied. In the root scope, the
source object is provided in the "source" property,
projected target object in the "target" property and
the link situation that led to the create operation in
"situation". The _id property in
the target object can be modified, allowing the mapping to select an
identifier; if not set then the identifier is expected to be set by
the target object set. If the script throws an exception, then
target object creation is aborted.
script object, optional
A script to execute when a target object is to be updated,
after property mappings have been applied. In the root scope, the
source object is provided in the "source" property,
projected target object in the "target" property,
link situation that led to the update operation in
"situation". If the script throws an exception,
then target object update is aborted.
script object, optional
A script to execute when a source object is to be linked to a target object,
after property mappings have been applied. In the root scope, the
source object is provided in the "source" property,
projected target object in the "target" property. If the script throws an exception,
then target object linking is aborted.
script object, optional
A script to execute when a source and a target object are to be
unlinked, after property mappings have been applied. In the root scope,
the source object is provided in the "source" property,
projected target object in the "target" property. If
the script throws an exception, then target object unlinking is aborted.
script object, optional
A script to execute on each mapping event, independent of the nature
of the operation. In the root scope, the source object is provided in the
"source" property, projected target object in the
"target" property. If the script throws an exception,
then target object unlinking is aborted.
The "result" script is executed only during reconciliation operations!
A property object specifies how the value of a target property is determined.
{
"target" : string,
"source" : string,
"transform" : script object,
"condition" : script object,
"default": value
}string, required
Specifies the path of the property in the target object to map to.
string, optional
Specifies the path of the property in the source object to map from. If not specified, then the target property value is derived from the script or default value.
script object, optional
A script to determine the target property value. The root
scope contains the value of the source in the
"source" property, if specified. If the
"source" property has a value of
"", then the entire source object of the mapping is
contained in the root scope. The resulting value yielded by the script
is stored in the target property.
script object, optional
A script to determine whether the mapping should be executed or
not. The condition has an "object" property available
in root scope, which (if specified) contains the full source object. For
example "source": "(object.email != null)". The
script is considered to return a boolean value.
any value, optional
Specifies the value to assign to the target property if a
non-null value is not established by "source" or
"transform". If not specified, the default value is
null.
A policy object specifies a link condition and the associated actions to take in response.
{
"situation" : string,
"action" : string or script object
"postAction" : optional, script object
}string, required
Specifies the situation for which an associated action is to be defined.
string or script object, required
Specifies the action to perform. If a script is specified, the script is executed and is expected to yield a string containing the action to perform.
script object, optional
Specifies the action to perform after the previously specified action has completed.
Script objects take the following form.
{
"type" : "text/javascript",
"source": string
}string, required
Specifies the type of script to be executed. Currently, OpenIDM
supports only "text/javascript".
string, required
Specifies the source code of the script to be executed.
To maintain links between source and target objects in mappings, OpenIDM stores an object set in the repository. The object set identifier follows this scheme.
links/mappingHere, mapping represents the name of the
mapping for which links are managed.
Link entries have the following structure.
{
"_id":string,
"_rev":string,
"linkType":string,
"firstId":string
"secondId":string,
}string
The identifier of the link object.
string, required
The value of link object's revision.
string, required
The type of the link. Usually then name of the mapping which created the link.
string, required
The identifier of the first of the two linked objects.
string
The identifier of the second of the two linked objects.
OpenIDM performs the following queries on a link object set.
Find link(s) for a given firstId object identifier.
SELECT * FROM links WHERE linkType
= value AND firstId = valueAlthough a single result makes sense, this query is intended to allow multiple results so that this scenario can be handled as an exception.
Select link(s) for a given second object identifier.
SELECT * FROM links WHERE linkType
= value AND secondId = valueAlthough a single result makes sense, this query is intended to allow multiple results so that this scenario can be handled as an exception.
OpenIDM performs reconciliation on a per-mapping basis. The process of reconciliation for a given mapping includes these stages.
Iterate through all objects for the object set specified as
"source". For each source object, carry out the
following steps.
Look for a link to a target object in the link object set, and perform a correlation query (if defined).
Determine the link condition, as well as whether a target object can be found.
Determine the action to perform based on the policy defined for the condition.
Perform the action.
Keep track of the target objects for which a condition and action has already been determined.
Write the results.
Iterate through all object identifiers for the object set specified
as "target". For each identifier, carry out the
following steps.
Find the target in the link object set.
Determine if the target object was handled in the first phase.
Determine the action to perform based on the policy defined for the condition.
Perform the action.
Write the results.
Iterate through all link objects, carrying out the following steps.
If the reconId is "my", then
skip the object.
If the reconId is not recognized, then the
source or the target is missing.
Determine the action to perform based on the policy.
Perform the action.
Store the reconId identifer in the mapping to
indicate that it was processed in this run.
To optimize a reconciliation operation, the reconciliation process does not attempt to correlate source objects to target objects if the set of target objects is empty when the correlation is started. For information on changing this default behaviour, see Reconciliation Optimization.
External synchronized objects expose an API to request immediate synchronization. This API includes the following requests and responses.
Example:
POST /openidm/system/xml/account/jsmith?action=sync HTTP/1.1
Example:
HTTP/1.1 204 No Content ...
Example:
HTTP/1.1 409 Conflict ... [JSON representation of error]