--- title: Configure relationship change notification description: 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. component: pingoneaic page_id: pingoneaic:idm-objects:relationships-notification canonical_url: https://docs.pingidentity.com/pingoneaic/idm-objects/relationships-notification.html keywords: ["Data Object Model", "Relationships", "Roles", "Change Notification", "REST API"] section_ids: origin_and_referenced_objects: Origin and referenced objects notification_properties: Notification properties relationship_change_notifications: Relationship change notifications --- # 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](roles-change-notification.html). ## 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](relationships-between-objects.html). In an example in the [Create a relationship between two objects](relationships-between-objects.html) 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 " \ --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:///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](_images/relationship-objects.png)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's*`notifyRelationships` 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: ```json { "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: ```json { "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`: ```json { "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: ```json { "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](reverse-relationships.html) (`"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 console; you must update the managed object schema directly. |