Create a relationship between two objects

In the default IDM schema, several user properties are defined as relationships, for example, the manager relationship.

Relationships let you reference one managed object from another using the _ref* relationship properties. Three properties make up a relationship reference:

_refResourceCollection specifies the container of the referenced object, for example, managed/realm-name_user.
_refResourceId specifies the ID of the referenced object. This is generally a system-generated UUID, such as 9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb.
_ref is a derived path that is a combination of _refResourceCollection and a URL-encoded _refResourceId.

For example, imagine that you are creating a new user, psmith, and that psmith's manager is bjensen. You would add psmith's user entry, and reference bjensen's entry with the _ref property.

First, retrieve bjensen's UUID, displayed in the _id property value.

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22bjensen%22"
{
  "result": [
    {
      "_id": "1dff18dc-ac57-4388-8127-dff309f80002",
      "_rev": "f4816053-aa01-4a7b-8380-8f3646787fd0-23348",
      "country": null,
      ...
    }
  ]
  ...
}

Next, add the new user psmith and specify bjensen as the manager using the _ref property. Make sure to use bjensen's UUID, for example, 1dff18dc-ac57-4388-8127-dff309f80002.

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "sn":"Smith",
  "userName":"psmith",
  "givenName":"Patricia",
  "displayName":"Patti Smith",
  "description" : "psmith - new user",
  "mail" : "psmith@example.com",
  "telephoneNumber" : "0831245986",
  "password" : "Passw0rd",
  "manager" : {"_ref" : "managed/realm-name_user/1dff18dc-ac57-4388-8127-dff309f80002"}
}' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_action=create"
{
  "_id": "51257f1e-6562-4b67-a80b-47b84f693f1b",
  "_rev": "6aad0f3b-eb20-4ae4-8c72-7e904b1062e5-34787",
  "country": null,
  "frUnindexedString1": null,
  "mail": "psmith@example.com",
  "memberOfOrgIDs": [],
  ...
}

Note that relationship information is not returned by default. To show the relationship in psmith's entry, you must explicitly request their manager entry, as follows:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22psmith%22&_fields=manager"
{
  "result": [
    {
      "_id": "51257f1e-6562-4b67-a80b-47b84f693f1b",
      "_rev": "6aad0f3b-eb20-4ae4-8c72-7e904b1062e5-34787",
      "manager": {
        "_ref": "managed/alpha_user/1dff18dc-ac57-4388-8127-dff309f80002",
        "_refResourceCollection": "managed/alpha_user",
        "_refResourceId": "1dff18dc-ac57-4388-8127-dff309f80002",
        "_refProperties": {
          "_id": "3dd2c42d-598e-4b78-bf59-0aab43113be7",
          "_rev": "6aad0f3b-eb20-4ae4-8c72-7e904b1062e5-34784"
        }
      }
    }
  ],
  ...
}

If a relationship changes, you can query the updated relationship state when any referenced managed objects are queried. So, after creating user psmith with manager bjensen, run a query on bjensen's user entry. The query shows a reference to psmith's entry in their reports property, which is configured as the reversePropertyName of the manager property.

The following query shows bjensen's direct reports including the new user entry, psmith:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22bjensen%22&_fields=reports"
{
  "result": [
    {
      "_id": "1dff18dc-ac57-4388-8127-dff309f80002",
      "_rev": "f4816053-aa01-4a7b-8380-8f3646787fd0-23348",
      "reports": [
        ...
        {
          "_ref": "managed/alpha_user/51257f1e-6562-4b67-a80b-47b84f693f1b",
          "_refResourceCollection": "managed/alpha_user",
          "_refResourceId": "51257f1e-6562-4b67-a80b-47b84f693f1b",
          "_refProperties": {
            "_id": "3dd2c42d-598e-4b78-bf59-0aab43113be7",
            "_rev": "6aad0f3b-eb20-4ae4-8c72-7e904b1062e5-34784"
          }
        }
      ]
    }
  ],
  ...
}

IDM maintains referential integrity by deleting the relationship reference if the object referred to by that relationship is deleted. In our example, if bjensen's user entry is deleted, the corresponding reference in psmith's manager property is removed.

PingOne Advanced Identity Cloud

Create a relationship between two objects