Relationships

Contendo Server supports non-hierarchical linking of objects using Relationship Objects. Objects of any type can be linked together, including documents, folders, items or even other relationships.

Relationships are directional, where the source object points to the target object. A single object may serve as the source in one relationship and the target in another. Multiple relationships can exist between the same pair of source and target objects.

Relationship objects don't have content and can't be stored in folders. If extended, they can have additional properties to describe the relationship.

Relationships are non-invasive - A source object and a target object are linked through the relationship, but the objects themselves remain unaffected by the relationship. Their content or properties aren't changed in any way.

The base Relationship type has no semantic meaning - just that the source object is related to the target object.

By extending the Relationship type, the meaning can be explicitly added. E.g. the custom type “Likes” could be used to state that the source “Dog” object likes a target “Treat” object.

There are no limitations on which the types of objects that can be in a relationship. Objects of any type can be linked together, including documents, folders, items or even other relationships. Objects of the same type can be in a relationship and an object can be in a relationship with itself.

The base Relationship type has no limitations on which object types may be linked. By extending the Relationship limitations may be added by setting allowedSourceTypes and allowedSourceTypes type attributes.
E.g. the custom relationship type “Likes” could have:
"allowedSourceTypes" : ["Dog"],
"allowedSourceTypes" : ["Treat"]
See Type Attributes

Creating Relationships

Relationships are created with the Create Object operation by setting the objectTypeId property to a relationship type (cmis:relationship or a descendant type). The cmis:sourceId and cmis:targetId properties must be set to define the source and target object respectively. See Relationship Specific Properties

Example:

{
  "cmis:objectTypeId": "cmis:relationship",
  "cmis:sourceId": "{Source Object Id}",
  "cmis:targetId": "{Target Object Id}"
}

Retrieving Relationships

Get Relationships

The relationsip operation can be used to retrieve relationships in which an object is part of, be it as a source, target or both.

Operation: relationships
HTTP Method: POST
Content-Type: application/json, multipart/form-data
Target Object: The object for which relationships should be retrieved. See Specifying the Target Object.

Parameters

Name	Required	Description	Link
`typeId`	No	If specified, only the relationships of the specified type are returned. Otherwise, all relationships involving the target object are returned.
`includeSubRelationshipTypes`	No	If `true`, returns relationships of all subtypes of the specified `typeId`. If `false` (default) only the relationships of the specified `typeId` are returned. No effect if `typeId` isn't set.
`relationshipDirection`	No	Filters relationships based on direction. Values: `source`, `target`, or `both` (default).
`filter`	No	Comma-separated list of properties to include in the response.	Filter
`maxItems`	No	Limits the number of relationships returned. If omitted, all relationships are retrieved.
`skipCount`	No	Specifies how many relationships to skip before returning results. Used for pagination.
`succinct`	No	If `true`, the response will use a compact format.	Succinct Format

Example:

curl -X 'POST' \
  '{REPOSITORY_URL}/Animals/Dogs/Rex' \
  -H 'Content-Type: application/json' \
  -d '{
    "operation": "relationships",
    "direction": "both",
    "maxItems": 10,
    "succinct": true
  }'

Response Format

Content-Type: application/json
Response Body: A JSON representation of the relationships.

Field Name	Condition	Description	Link
`objects[]`	Always present	Array of relationship objects containing the properties of the relationship.
└ `properties` / `succinctProperties`	Always present	The properties of the relationship object.	Properties
`hasMoreItems`	Always present	`true` if more relationships exist beyond `maxItems`.
`numItems`	Always present	The total number of relationships returned.

Example Response (omitted some properties for clarity)

{
  "objects": [
    {
      "succinctProperties": {
        "cmis:objectId": "2f14b215-32ce-497d-bbea-e8e58c1971bc",
        "cmis:sourceId": "1ba4f646-25c7-495e-afd2-7566d9514d2c",
        "cmis:targetId": "d4e65f23-8c27-4e5a-94b8-fb1a6dfc2b0e",
        "cmis:objectTypeId": "Likes"
      }
    }
  ],
  "hasMoreItems": false,
  "numItems": 1
}

Including ACL when retrieving objects

Additionally, query and most retrieving objects operations have the option to include relationships in their response via the includeRelationships parameter.

Example: getting an object with includeRelationships set to true (omitted some properties for clarity):

{
  "succinctProperties": {
    "cmis:name": "Rex",
    "cmis:objectId": "1ba4f646-25c7-495e-afd2-7566d9514d2c"
  },
  "relationships": [
    {
      "succinctProperties": {
        "cmis:baseTypeId": "Likes",
        "cmis:sourceId": "1ba4f646-25c7-495e-afd2-7566d9514d2c",
        "cmis:targetId": "1667d760-f86c-42e1-8184-2832c4098a46"
      }
    },
    {
      "succinctProperties": {
        "cmis:baseTypeId": "Likes",
        "cmis:sourceId": "1ba4f646-25c7-495e-afd2-7566d9514d2c",
        "cmis:targetId": "1ba4f646-25c7-495e-afd2-7566d9514d2c"
      }
    }
  ]
}

Updating Relationships

The Update Properties operation can be used to update the properties of a Relationship. Note that Source ID and Target ID properties can't be changed as they are oncreate properties. Other readwrite properties can be changed, most notably custom ones added to a custom relationship type.

A relationship is defined as a link between two objects. If one (or both?) of the objects needs to change, then we actually need a new relationship.

Deleting Relationships

The Delete Object operation can be used to delete a relationship.