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 Advanced Identity Cloud 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.

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

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/sync/mappings?_queryFilter=true"

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

Each mapping result includes the read-only, server-computed status fields sourceRouteReady and targetRouteReady. These fields show whether the router service can route requests to the mapping’s source and target resources, for example, managed/realm-name_user or system/csvfile/account. A true value means the connector or repository backing that resource is loaded and enabled. A false value typically means the source or target connector is disabled or not loaded.

These fields report route registration only. They don’t test live connectivity to the backend, so a resource can report true and still be unreachable. Advanced Identity Cloud verifies route readiness before synchronization: reconciliation and queued synchronization operations wait until both routes are ready before they proceed.

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 Advanced Identity Cloud repository, you would define the following two mappings:

LDAP Server > Advanced Identity Cloud Repository
Advanced Identity Cloud 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, see Reuse Links Between Mappings.

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

Paging synchronization mapping results

With many synchronization mappings, use paging to retrieve the results in manageable chunks to avoid overwhelming the client. The openidm/sync/mappings endpoint supports paging with the _pageSize parameter and either cookies (_pagedResultsCookie) or offsets (_pagedResultsOffset).

Example: Cookie-based paging

In the following example, the source source1 returns 3 results without a query filter (mapping1, mapping4, and mapping7).

To get the first page of results, with a page size of 2, send a request like this:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://<tenant-env-fqdn>/openidm/sync/mappings?_queryFilter=/source+eq+'source1'&_pageSize=2"

The response includes a pagedResultsCookie containing the ID of the next available result (mapping7) that you can use to retrieve the next page:

{
  "result": [
    {
      "_id": "mapping1",
      "source": "source1",
      "target": "target1",
      "name": "mapping1",
      "sourceRouteReady": true,
      "targetRouteReady": true
    },
    {
      "_id": "mapping4",
      "source": "source1",
      "target": "target0",
      "name": "mapping4",
      "sourceRouteReady": true,
      "targetRouteReady": true
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": "mapping7",
  "totalPagedResultsPolicy": "EXACT",
  "totalPagedResults": 2,
  "remainingPagedResults": -1
}

To get the next page of results, use the _pagedResultsCookie query parameter with the ID (mapping7) from the previous response:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://<tenant-env-fqdn>/openidm/sync/mappings?_queryFilter=/source+eq+'source1'&_pageSize=2&_pagedResultsCookie=mapping7"
{
  "result": [
    {
      "_id": "mapping7",
      "source": "source1",
      "target": "target3",
      "name": "mapping7",
      "sourceRouteReady": true,
      "targetRouteReady": true
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,         (1)
  "totalPagedResultsPolicy": "EXACT",
  "totalPagedResults": 1,
  "remainingPagedResults": -1
}

1	The `pagedResultsCookie` has a `null` value, indicating no further results are available.

Example: Offset-based paging

To get the first page of results, with a page size of 2 and an offset of 0:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://<tenant-env-fqdn>/openidm/sync/mappings?_queryFilter=/source+eq+'source1'&_pageSize=2&_pagedResultsOffset=0"
{
  "result": [
    {
      "_id": "mapping1",
      "source": "source1",
      "target": "target1",
      "name": "mapping1",
      "sourceRouteReady": true,
      "targetRouteReady": true
    },
    {
      "_id": "mapping4",
      "source": "source1",
      "target": "target0",
      "name": "mapping4",
      "sourceRouteReady": true,
      "targetRouteReady": true
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": "mapping7",
  "totalPagedResultsPolicy": "EXACT",
  "totalPagedResults": 2,
  "remainingPagedResults": -1
}

To get the second page of results, set the _pagedResultsOffset to the number of results already retrieved (in this case, 2):

curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://<tenant-env-fqdn>/openidm/sync/mappings?_queryFilter=/source+eq+'source1'&_pageSize=2&_pagedResultsOffset=2"
{
  "result": [
    {
      "_id": "mapping7",
      "source": "source1",
      "target": "target3",
      "name": "mapping7",
      "sourceRouteReady": true,
      "targetRouteReady": true
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "EXACT",
  "totalPagedResults": 1,
  "remainingPagedResults": -1
}

PingOne Advanced Identity Cloud

Resource mapping

Paging synchronization mapping results