--- title: Configure relationship change notification description: A relationship exists between two managed objects. By default, when a relationship changes (when it is created, updated, or deleted), 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 in the case where many objects are affected by a single relationship change. component: pingidm version: 8.1 page_id: pingidm:objects-guide:relationships-notification canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/relationships-notification.html keywords: ["Data Object Model", "Relationships", "Roles", "Change Notification"] --- # Configure relationship change notification A relationship exists between two managed objects. By default, when a relationship changes (when it is created, updated, or deleted), 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 in the case where many objects are affected by a single relationship change. For `roles`, a special kind of relationship, change notification *is* configured by default. The purpose of this default configuration is to notify managed users when any of the relationships that link users, roles, and assignments are manipulated. Learn more about relationship change notification in managed roles in [Roles and relationship change notification](roles-change-notification.html). To change the default configuration, or to set up notification for other relationship changes, use the `notify*` properties in the relationship definition, as described in this section. 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/user/psmith`) and which object is referenced by the relationship (`_ref*`) properties. Learn more about relationship properties in [relationship properties](relationships.html#relationship-properties). In the previous example, a PUT on `managed/user/psmith` with `"manager" : {_ref : "managed/user/bjensen"}`, causes `managed/user/psmith` to be the origin object, and `managed/user/bjensen` to be the referenced object for that relationship, as shown in the following illustration: ![Illustration shows the origin and referenced objects in a relationship](_images/relationship-objects.svg)Figure 1. Relationship Objects Note that for the reverse relationship (a PUT on `managed/user/bjensen` with `"reports" : [{_ref = "managed/user/psmith"}]`) `managed/user/bjensen` would be the origin object, and `managed/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 PUT on `managed/user/psmith` with `"manager" : {_ref : "managed/user/bjensen"}`, neither psmith's object nor bjensen's object is notified. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Auditing is not tied to relationship change notification and is always triggered when a *relationship* changes. Therefore, relationship changes are audited, regardless of the `notify` and `notifySelf` properties. | To configure relationship change notification, set the `notify` and `notifySelf` properties in your managed object schema. These 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. For example, for a 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/user`, and that this object specifies `"notify" : true`. If the relationship changes through a CREATE, UPDATE, or DELETE on the URL `psmith/manager`, then the reference object (`managed/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, look at the `attributes` property in the default `managed/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. Because the `role` managed object has `"notifyRelationships" : ["members"]` defined on its `assignments` field, the notification that originated from the change to the assignment attribute is propagated to the connected `roles`, and then out to the `members` of those roles. So, the `role` is notified through its `assignments` field because an `attribute` in the assignment changed. This notification is propagated out of the `members` field because the role definition has `"notifyRelationships" : ["members"]` on its `assignments` field. 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 will be notified of the change. For example, if there is a CREATE on `managed/user/psmith/roles` which specifies a set of references to existing roles, user `psmith` will be notified of the change. Similarly, the `role` object 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/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/user` objects) that are identified as `members` of that role must be notified of the change. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * To notify an object at the end of a relationship 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 has been created, the user object calculates its base state, and the state of its `roles` field, before and after the new role was created. This *before* and *after* state is then reconciled. An object that is referenced by a forward (unidirectional) relationship does not have a field that references 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. |