Virtual Properties

Properties can be derived from other properties within an object. This lets computed and composite values be created in the object. Such derived properties are named virtual properties. The value of a virtual property can be calculated in two ways:

  • Using a script called by the onRetrieve script hook. This script then calculates the current value of the virtual property based on the related properties.

  • Using a query to identify the relationship fields to traverse to reach the managed objects whose state is included in the virtual property, and the fields in these managed objects to include in the value of the virtual property.

    These properties are called relationship-derived virtual properties.

Virtual Properties Using onRetrieve Scripts

The onRetrieve script hook lets you run a script when the object is retrieved. In the case of virtual properties, this script gets the data from related properties and uses it to calculate a value for the virtual property. For more information about running scripts on managed objects, see "Run Scripts on Managed Objects".

Prior to IDM version 7.0, using onRetrieve scripts was the primary method for calculating virtual properties. This method will continue to work, but is not as performant as using queryConfig. There may be some cases involving custom logic where a scripted solution is still the preferred answer. For more information about customizing scripts for role calculation, see Grant a Role By Using Custom Scripts.

Relationship-Derived Virtual Properties

Virtual properties can be calculated by IDM based on relationships and relationship notifications. This means that, rather than calculating the current state when retrieved, the managed object that contains the virtual property is notified of changes in a related object, and the virtual property is recalculated when this notification is received. To configure virtual properties to use relationship notifications, there are two areas that need to be configured:

  • The related managed objects must be configured to use relationship notifications. This lets IDM know where to send notifications of changes in related objects.

  • To calculate the value of a virtual property, you must configure which relationships to check, and in what order, a notification of a change in a related object is received. You configure this using the queryConfig property.

The queryConfig property tells IDM the sequence of relationship fields it should traverse in order to calculate (or recalculate) a virtual property, and what fields it should return from that related object. This is done using two fields:

  • referencedRelationshipFields is an array listing a sequence of relationship fields connecting the current object with the related objects you want to calculate the value of the virtual property from. The first field in the array is a relationship field belonging to the same managed object as the virtual property, the second field is a relationship in the managed object referenced by the first field, and so on.

    For example, the referencedRelationshipFields for effectiveAssignments is ["roles","assignments"]. The first field refers to the roles relationship field in managed/user, which references the managed/role object. It then refers to the assignments relationship in managed/role, which references the managed/assignment object. Changes to either related object (managed/role or managed/assignment) will cause the virtual property value to be recalculated, due to the notify, notifySelf, and notifyRelationships configurations on managed user, role, and assignment. These configurations ensure that any changes in the relationships between a user and their roles, or their roles, and their assignments, as well as any relevant changes to the roles or assignments themselves, such as the modification of temporal constraints on roles, or attributes on assignments, will be propagated to connected users, so their effectiveRoles and effectiveAssignments can be recalculated and potentially synced.

  • referencedObjectFields is an array of object fields that should be returned as part of the virtual property. If this property is not included, the returned properties will be a reference for the related object. To return the entire related object, use *.

Using queryConfig, the virtual property is recalculated when it receives a notice that changes occurred in the related objects. This can be significantly more efficient than recalculating whenever an object is retrieved, while still ensuring the state of the virtual property is correct.

Note

When making changes to what object fields to return using referencedObjectFields, the changes will not be reflected until there is a change in the related object that would trigger the virtual property to be recalculated (as specified by the notify, notifySelf, and notifyRelationships configurations). The calculated state of the virtual property is still correct, but since a change is necessary for the state to be updated, the returned fields will still be based on the previous configuration.

Read a different version of :