PingDirectory

Working with correlated REST resources

You can link resource types based on a common attribute value. When two or more resources are linked this way, they are known as correlated resources.

Correlated REST resources

When you retrieve a resource configured with correlated resources, any correlated resource with matching attribute values is included with the resource.

You can view, update, and delete a resource’s correlated resources. You can also link them to and unlink them from a resource.

Configuration

The following example shows how to create a correlated resource by linking a documents resource type to a users resource type. When a user resource is retrieved, any document resources with the user’s entryUUID in their documentPublisher attribute are included.

dsconfig create-delegated-admin-correlated-rest-resource \
    --type-name users  \
    --resource-name Documents  \
    --set display-name:Documents  \
    --set correlated-rest-resource:Documents  \
    --set primary-rest-resource-correlation-attribute:entryUUID  \
    --set secondary-rest-resource-correlation-attribute:documentPublisher

Linking and unlinking

You can link resources to correlated resources by taking an attribute value from either the primary resource or the correlated resource and assigning it to the other. To control the direction that the linking value is assigned, use the use-secondary-value-for-linking property. If use-secondary-value-for-linking is false or isn’t set, the primary correlation attribute’s value is assigned to the secondary correlation attribute to create the link. If use-secondary-value-for-linking is true, the secondary correlation attribute’s value is assigned to the primary correlation attribute.

The following is an example of a users resource type linked to a documents resource type by assigning the document’s entryUUID value to the user’s description attribute. The secondary correlation attribute’s value is assigned to the primary correlation attribute, so use-secondary-value-for-linking is true.

dsconfig create-delegated-admin-correlated-rest-resource \
    --type-name users  \
    --resource-name ownedDocuments  \
    --set display-name:Owned Documents  \
    --set correlated-rest-resource:Documents  \
    --set primary-rest-resource-correlation-attribute:description  \
    --set secondary-rest-resource-correlation-attribute:entryUUID  \
    --set use-secondary-value-for-linking:true

If you inspected a user’s description attribute with this setup, you see a list of all of the documents owned by the user.

The next example links the attributes in the other direction. Here, the user’s entryUUID value is assigned to the documentAuthor attribute on the document.

dsconfig create-delegated-admin-correlated-rest-resource \
    --type-name users  \
    --resource-name authoredDocuments  \
    --set display-name:Authored Documents  \
    --set correlated-rest-resource:Documents  \
    --set primary-rest-resource-correlation-attribute:entryUUID  \
    --set secondary-rest-resource-correlation-attribute:documentAuthor  \
    --set use-secondary-value-for-linking:false

If you inspect a document’s documentAuthor attribute with this setup, you see a list of all of the users who authored the document.

You can also unlink correlated resources from the primary resource. Resources are unlinked by removing the common attribute value using the logic based on the use-secondary-value-for-linking property described above.

Unlinking correlated resources differs from deleting correlated resources. When correlated resources are unlinked, the common attribute value is removed, but the correlated resource still exists in the directory. When a correlated resource is deleted, it is removed from the directory.

The attribute that the linking value is assigned to must be a writable attribute because the value must be updated to link and unlink correlated resources. The attributes should also have the same syntax so that the value of one can be assigned to the other successfully.

When use-secondary-value-for-linking is enabled and a linked object is deleted, the linking value is not removed from the primary correlation attribute. This means that if a secondary object is recreated with the same value in the secondary correlation attribute, the secondary object is automatically linked to the primary object.

Permissions

The following table describes the permissions required to perform the specified actions.

Action Permissions required

View

The read permission on the secondary resource type.

Update

The update or update-profile permission on the secondary resource type.

Delete

The delete permission on the secondary resource type.

Link or unlink

The update or update-profile permission.

The required permission is dependent on the use-secondary-value-for-linking setting. If use-secondary-value-for-linking is set to false, the permission is required on the correlated resource type. If use-secondary-value-for-linking is set to true, the permission is required on the primary resource type.