Object-Mapping Objects

An object-mapping object specifies the configuration for a mapping of source objects to target objects. The name, source, and target properties are mandatory. Other properties are optional or implicit (that is, they have a default value if not set).

{
  "correlationQuery"                 : script object,
  "correlationScript"                : script object,
  "displayName"                      : string,
  "enableSync"                       : boolean,
  "linkQualifiers"                   : [ list of strings ] or script object,
  "links"                            : string,
  "name"                             : string,
  "onCreate"                         : script object,
  "onDelete"                         : script object,
  "onLink"                           : script object,
  "onUnlink"                         : script object,
  "onUpdate"                         : script object,
  "policies"                         : [ policy object, ... ],
  "properties"                       : [ property object, ... ],
  "queuedSync"                       : { property object },
  "reconAssociation"                 : { property object },
  "reconProgressStateUpdateInterval" : integer,
  "reconSourceQueryPageSize"         : integer,
  "reconSourceQueryPaging"           : boolean,
  "result"                           : script object,
  "runTargetPhase"                   : boolean,
  "source"                           : string,
  "sourceCondition"                  : script object or queryFilter string,
  "sourceIdsCaseSensitive"           : boolean,
  "sourceQueryFullEntry"             : boolean,
  "syncAfter"                        : [ list of strings ],
  "target"                           : string,
  "targetIdsCaseSensitive"           : boolean,
  "targetQueryFullEntry"             : boolean,
  "taskThreads"                      : integer,
  "triggerSyncProperties"            : [ list of JSON pointers ],
  "validSource"                      : script object,
  "validTarget"                      : script object
}

Mapping Object Properties

correlationQuery

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. For examples of correlation queries, see "Writing Correlation Queries". The source object is provided in the source property in the script scope.

correlationScript

script object, optional

A script that goes beyond a correlationQuery of a target system. Used when you need another method to determine which records in the target system relate to the given source record. The syntax depends on the target of the correlation. For information about defining correlation scripts, see "Writing Correlation Scripts".

displayName

string, optional

The mapping name displayed in the UI.

enableSync

boolean, true or false

Specifies whether automatic synchronization (liveSync and implicit synchronization) should be enabled for a specific mapping. For more information, see "Disable Automatic Synchronization Operations".

Default : true

linkQualifiers

list of strings or script object, optional

Enables mapping of a single source object to multiple target objects.

Example: "linkQualifiers" : [ "employee", "customer" ] or

"linkQualifiers" : {
        "type" : "text/javascript",
        "globals" : { },
        "source" : "if (returnAll) {
                      ['contractor', 'employee', 'customer', 'manager']
                    } else {
                      if(object.type === 'employee') {
                        ['employee', 'customer', 'manager']
                      } else {
                        ['contractor', 'customer']
                      }
                    }"
      }

If a script object, the script must return a list of strings.

links

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".

name

string, required

Uniquely names the object mapping. Used in the link object identifier.

onCreate

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, the projected target object in the target property, and the link situation that led to the create operation in the situation property. Properties on the target object can be modified by the script. If a property value is not set by the script, IDM falls back on the default property mapping configuration. If the script throws an exception, the target object creation is aborted.

onDelete

script object, optional

A script to execute when a target object is to be deleted, after property mappings have been applied. In the root scope, the source object is provided in the source property, the target object in the target property, and the link situation that led to the delete operation in the situation property. If the script throws an exception, the target object deletion is aborted.

onLink

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, and the projected target object in the target property.

Note that, although an onLink script has access to a copy of the target object, changes made to that copy will not be saved to the target system automatically. If you want to persist changes made to target objects by an onLink script, you must explicitly include a call to the action that should be taken on the target object (for example openidm.create, openidm.update or openidm.delete) within the script.

In the following example, when an LDAP target object is linked, the "description" attribute of that object is updated with the value "Active Account". A call to openidm.update is made within the onLink script, to set the value.

"onLink" : {
    "type" : "text/javascript",
    "source" : "target.description = 'Active Account';
                openidm.update('system/ldap/account/' + target._id, null, target);"
}

If the script throws an exception, target object linking is aborted.

onUnlink

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, and the target object in the target property.

Note that, although an onUnlink script has access to a copy of the target object, changes made to that copy will not be saved to the target system automatically. If you want to persist changes made to target objects by an onUnlink script, you must explicitly include a call to the action that should be taken on the target object (for example openidm.create, openidm.update or openidm.delete) within the script.

In the following example, when an LDAP target object is unlinked, the description attribute of that object is updated with the value Inactive Account. A call to openidm.update is made within the onUnlink script, to set the value.

"onUnlink" : {
    "type" : "text/javascript",
    "source" : "target.description = 'Inactive Account';
                openidm.update('system/ldap/account/' + target._id, null, target);"
}

If the script throws an exception, target object unlinking is aborted.

onUpdate

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, the projected target object in the target property, and the link situation that led to the update operation in the situation property. Any changes that the script makes to the target object will be persisted when the object is finally saved to the target resource. If the script throws an exception, the target object update is aborted.

policies

array of policy objects, optional

Specifies a set of link conditions and associated actions to take in response.

properties

array of property-mapping objects, optional

Specifies mappings between source object properties and target object properties, with optional transformation scripts. See Property Object Properties.

queuedSync

list of properties, optional

Specifies the queued synchronization configuration.

reconAssociation

list of properties, optional

Specifies the recon association configuration.

reconProgressStateUpdateInterval

integer, optional

Overrides the number of reconciliation operations required before the reconciliation progress state statistics are persisted to the repository. A value of 50 will write statistics to the repository every 50 operations.

Default : 1024, minimum : 1.

reconSourceQueryPageSize

integer

Sets the page size for reconciliation source queries, if paging is configured.

Default : 0 (no paging)

reconSourceQueryPaging

boolean, true or false

Specifies whether paging should be used for reconciliation source queries.

Default : false

result

script object, optional

A script for each mapping event, executed only after a successful reconciliation.

The variables available to a result script are as follows:

source - provides statistics about the source phase of the reconciliation
target - provides statistics about the target phase of the reconciliation
global - provides statistics about the entire reconciliation operation

runTargetPhase

boolean, true or false

Specifies whether reconciliation operations should run both the source and target phase. To avoid queries on the target resource, set to false.

Default : true

source

string, required

Specifies the path of the source object set. Example: "managed/user".

sourceCondition

script object or queryFilter string, optional

A script or query filter that determines if a source object should be included in the mapping. If no sourceCondition element (or validSource script) is specified, all source objects are included in the mapping.

sourceIdsCaseSensitive

boolean, true or false

Consider case sensitivity when linking source IDs. Only effective if this mapping defines links, ignored if the mapping re-uses another mapping's links.

Default : true

sourceQueryFullEntry

boolean, true or false, optional

Specifies whether the defined source query returns full object data (true) or IDs only (false).

No default. If not set in the configuration, IDM will attempt to auto-detect the setting, based on the query results.

syncAfter

list of strings, optional

The specified mapping must be synchronized after all mappings in this list.

target

string, required

Specifies the path of the target object set. Example: "system/ldap/account".

targetIdsCaseSensitive

boolean, true or false

Consider case sensitivity when linking target IDs. Only effective if this mapping defines links, ignored if the mapping re-uses another mapping's links.

Default : true

targetQueryFullEntry

Boolean true or false, optional

Specifies whether the defined target query returns full object data (true) or IDs only (false).

No default. If not set in the configuration, IDM will attempt to auto-detect the setting, based on the query results.

taskThreads

integer, optional

Sets the number of threads dedicated to the same reconciliation run.

Default : 10

triggerSyncProperties

list, optional

A list of JsonPointers to fields in the source object whose changes should trigger a synchronization operation.

validSource

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.

validTarget

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.

Property Objects

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
}

Property Object Properties

target

string, required

Specifies the path of the property in the target object to map to.

source

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.

transform

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 "", 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.

condition

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.

default

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.

Policy Objects

A policy object specifies a link condition and the associated actions to take in response.

{
  "condition"  : optional, script object,
  "situation"  : string,
  "action"     : string or script object
  "postAction" : optional, script object
}

Policy Object Properties

condition

script object or queryFilter condition, optional

Applies a policy, based on the link type, for example "condition" : "/linkQualifier eq \"user\"".

A queryFilter condition can be expressed in two ways—as a string ("condition" : "/linkQualifier eq \"user\"") or a map, for example:

"condition" : {
    "type" : "queryFilter",
    "filter" : "/linkQualifier eq \"user\""
}

It is generally preferable to express a queryFilter condition as a map.

A condition script has the following variables available in its scope: object, and linkQualifier.

situation

string, required

Specifies the situation for which an associated action is to be defined.

action

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.

The action script has the following variables available in its scope: source, target, sourceAction, linkQualifier, and recon.

postAction

script object, optional

Specifies the action to perform after the previously specified action has completed.

The postAction script has the following variables available in its scope: source, target, action, sourceAction, linkQualifier, and reconID. sourceAction is true if the action was performed during the source reconciliation phase, and false if the action was performed during the target reconciliation phase. For more information, see "How Synchronization Situations Are Assessed".

Note

No postAction script is triggered if the action is either IGNORE or ASYNC.

Script Object

Script objects take the following form.

{
  "type"  : "text/javascript",
  "source": string
}

type

string, required

Specifies the type of script to be executed. Supported types include "text/javascript" and "groovy".

source

string, required

Specifies the source code of the script to be executed.