PingIDM

Resource mapping

A synchronization mapping specifies a relationship between objects and their attributes in two data stores. The following example shows a typical attribute mapping, between objects in an external LDAP directory and an IDM managed user data store:

"source": "lastName",
"target": "sn"

In this case, the lastName source attribute is mapped to the sn (surname) attribute in the target LDAP directory.

The core synchronization configuration is defined in the mapping configuration.

You can define a single file with all your mappings (conf/sync.json), or a separate file per mapping. Individual mapping files are named mapping-mappingName.json; for example, mapping-managedUser_systemCsvfileAccounts.json. Individual mapping files can be useful if your deployment includes many mappings that are difficult to manage in a single file. You can also use a combination of individual mapping files and a monolithic sync.json file, particularly if you are adding mappings to an existing deployment.

If you use a single sync.json file, mappings are processed in the order in which they appear within that file. If you use multiple mapping files, mappings are processed according to the syncAfter property in the mapping. The following example indicates that this particular mapping must be processed after the managedUser_systemCsvfileAccount mapping:

  "source" : "managed/user",
  "target" : "system/csvfile/account",
  "syncAfter" : [ "managedUser_systemCsvfileAccount" ],

If you use a combination of sync.json and individual mapping files, the synchronization engine processes the mappings in sync.json first (in order), and then any mappings specified in the individual mapping files, according to the syncAfter property in each mapping.

For a list of all mappings, use the following request:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/sync/mappings?_queryFilter=true"

This call returns the mappings in the order in which they will be processed.

The admin UI only shows the mappings configured in the sync.json file. Don’t use the admin UI to add or change mappings in individual mapping files.

Mappings are always defined from a source resource to a target resource. To configure bidirectional synchronization, you must define two mappings. For example, to configure bidirectional synchronization between an LDAP server and an IDM repository, you would define the following two mappings:

  • LDAP Server > IDM Repository

  • IDM Repository > LDAP Server

Bidirectional mappings can include a links property that lets you reuse the links established between objects, for both mappings. For more information, refer to Reuse Links Between Mappings.

You can update a mapping while the server is running. To avoid inconsistencies between data stores, don’t update a mapping while a reconciliation is in progress for that mapping.

Specifying default fields

The defaultSourceFields and defaultTargetFields optional fields allow more control over which attributes are fetched during read operations during synchronization and reconciliation.

When to specify

  1. During synchronization reads: If IDM needs to read a source or target object while executing a synchronization operation because the object isn’t already loaded in memory for that specific task, it will include the attributes listed in defaultSourceFields or defaultTargetFields in the read request.

    This is an efficiency feature. If an object was already loaded into memory earlier in the same overall transaction (for instance, during reconciliation) before the sync operation needs it, IDM won’t automatically reread the object to add the attributes specified in these default fields. The fields are primarily used when a new read is initiated during the sync process itself.

  2. During reconciliation queries: If you don’t specify an explicit list of attributes in the sourceQuery or targetQuery configuration, IDM will fall back to using defaultSourceFields or defaultTargetFields respectively. This can be more helpful than the older behavior, where some default queries might only retrieve the object’s _id.

If you define a list of attributes within the sourceQuery or targetQuery settings, that specific list always takes precedence. The defaultSourceFields and defaultTargetFields only act as defaults when no specific list is provided in those contexts.

When not to specify

There are a couple of situations where these fields won’t dictate the attributes loaded for a source object during a synchronization operation:

  • Implicit synchronization: In implicit sync scenarios, the source object that triggered the event is usually already loaded, so IDM doesn’t perform a new read using defaultSourceFields.

  • Object already loaded using explicit query: If the source or target object was already fully loaded during reconciliation because specific attributes were requested using the higher-priority sourceQuery or targetQuery settings, then defaultSourceFields or defaultTargetFields won’t cause another read.