Configure relationship change notification

A relationship exists between two managed objects. By default, when a relationship changes for any create, update, or delete operation, the managed objects on either side of the relationship are not notified of that change. This means that the state of each object with respect to that relationship field is not recalculated until the object is read. This default behavior improves performance, especially cases where many objects are affected by a single relationship change.

For roles, change notification is set to TRUE by default. This default configuration lets managed users receive notifications when any relationships that link users, roles, and assignments are manipulated. For more information about relationship change notification, refer to Roles and relationship change notification.

Origin and referenced objects

A relationship exists between an origin object and a referenced object. These terms reflect which managed object is specified in the URL (for example managed/realm-name_user/psmith), and which object is referenced by the relationship (_ref*) properties. For more information about the relationship properties, refer to Create a relationship between two objects.

In an example in the Create a relationship between two objects section, a POST on managed/realm-name_user/psmith (UUID is 51257f1e-6562-4b67-a80b-47b84f693f1b) with "manager":{_ref:"managed/realm-name_user/bjensen"} (UUID is 1dff18dc-ac57-4388-8127-dff309f80002) causes managed/realm-name_user/psmith to be the origin object, and managed/realm-name_user/bjensen to be the referenced object for that relationship.

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": [],
  ...
}

This relationship is illustrated as follows:

Illustration shows the origin and referenced objects in a relationship

Figure 1. Relationship Objects

Note that for the reverse relationship (a POST on managed/realm-name_user/bjensen with "reports":[{_ref = "managed/realm-name_user/psmith"}]) managed/realm-name_user/bjensen would be the origin object, and managed/realm-name_user/psmith would be the referenced object.

By default, when a relationship changes, neither the origin object nor the referenced object is notified of the change. So, with the POST on managed/realm-name_user/psmith with "manager":{_ref:"managed/realm-name_user/bjensen"}, neither psmith's object nor bjensen's object is notified. This means that the objects are not updated to reflect the latest change.

Notification properties

To configure relationship change notifications, set the notify and notifySelf properties in your managed object schema.

Auditing is not tied to relationship change notification and is always triggered when a relationship changes; therefore, relationship changes are audited, regardless of the notifySelf, notify, and notifyRelationships properties.

The following properties specify whether objects that reference relationships are notified of a relationship change:

notifySelf

Notifies the origin object of the relationship change.

In our example, if the manager definition includes "notifySelf":true and if the relationship is changed through a URL that references psmith, then psmith's object would be notified of the change. Thus, for any CREATE, UPDATE or DELETE request on the psmith/manager, psmith would be notified, but the managed object referenced by this relationship (bjensen) would not be notified.

If the relationship were manipulated through a request to bjensen/reports, then bjensen would only be notified if the reports relationship specified "notifySelf":true.

notify

Notifies the referenced object of the relationship change. Set this property on the resourceCollection of the relationship property.

In our example, assume that the manager definition has a resourceCollection with a path of managed/realm-name_user and that this object specifies "notify":true. If the relationship changes through any CREATE, UPDATE, or DELETE operation on the URL psmith/manager, then the reference object (managed/realm-name_user/bjensen) would be notified of the change to the relationship.

notifyRelationships

This property controls the propagation of notifications out of a managed object when one of its properties changes through an update or patch or when that object receives a notification through one of these fields.

The notifyRelationships property takes an array of relationships as a value; for example, "notifyRelationships":["relationship1", "relationship2"]. The relationships specified here are fields defined on the managed object type, which might itself be a relationship.

Notifications are propagated according to the recipient’snotifyRelationships configuration. If a managed object type is notified of a change through one if its relationship fields, the notification is done according to the configuration of the recipient object.

To illustrate, review the attributes property in the default managed/realm-name_assignment object:

{
  "name" : "assignment",
    "schema" : {
      ...
      "properties" : {
        ...
        "attributes" : {
          "description" : "The attributes operated on by this assignment.",
          "title" : "Assignment Attributes",
          ...
          "notifyRelationships" : ["roles"]
        },
        ...

This configuration means that if an assignment is updated or patched and the assignment’s attributes change in some way, all the roles connected to that assignment are notified.

Note that the role managed object has "notifyRelationships":["members"] defined on its assignments field as follows:

{
  "name" : "role",
    "schema" : {
      ...
      "properties" : {
        ...
        "assignments" : {
          ...
          "notifyRelationships" : ["members"]
        }
    ...
}

When a role is notified of the creation of a new relationship to an assignment, the notification is propagated through the assignments property. Because "notifyRelationships":["members"] is set on the assignments property, the notification is propagated across the role to all of its members.

Relationship change notifications

By default, roles, assignments, and members use relationship change notification to ensure that relationship changes are accurately provisioned.

For example, the default user object includes a roles property with notifySelf set to true:

{
  "name" : "user",
  ...
  "schema" : {
    ...
    "properties" : {
      ...
      "roles" : {
        "description" : "Provisioning Roles",
        ...
        "items" : {
          "type" : "relationship",
          ...
          "reverseRelationship" : true,
          "reversePropertyName" : "members",
          "notifySelf" : true,
          ...
        }
        ...

In this case, notifySelf indicates the origin or user object. If any changes are made to a relationship referencing a role through a URL that includes a user, the user is notified of the change. For example, if there is a CREATE on managed/realm-name_user/psmith/roles specifying a set of references to existing roles, user psmith is notified of the change.

Similarly, the role object also includes a members property. That property includes the following schema definition:

{
  "name" : "role",
  ...
  "schema" : {
    ...
    "properties" : {
      ...
      "members" : {
        ...
        "items" : {
          "type" : "relationship",
          ...
          "properties" : {
            ...
            "resourceCollection" : [
              {
                "notify" : true,
                "path" : "managed/realm-name_user",
                "label" : "User",
                ...
              }
           ]
          }
          ...

Notice the "notify":true setting on the resourceCollection. This setting indicates that if the relationship is created, updated, or deleted through a URL that references that role, all objects in that resource collection (in this case, managed/realm-name_user objects), which are identified as members of that role, are notified of the change.

To notify an object that the relationship has changed (using the notify property), the relationship must be bidirectional ("reverseRelationship":true).

When an object is notified of a relationship state change (create, delete, or update), part of that notification process involves calculating the changed object state with respect to the changed relationship field. For example, if a managed user is notified that a role was created, the user object calculates its base state and the state of its roles field, before and after the new role is created. This before and after state is then reconciled.

An object referenced by a forward (unidirectional) relationship does not have a field referencing that relationship; the object is "pointed-to" but does not "point-back". Because this object cannot calculate its before and after state with respect to the relationship field, it cannot be notified.

Similarly, relationships that are notified of changes to the objects that reference them must be bidirectional relationships.

If you configure relationship change notification on a unidirectional relationship, IDM throws an exception.
You cannot configure relationship change notification in the IDM admin UI; you must update the managed object schema directly.

PingOne Advanced Identity Cloud

Configure relationship change notification

Origin and referenced objects

Notification properties

Relationship change notifications