Item-to-item relations [VC 21.3.1 GEN]

This section describes relations between items. The relation can be used to find ancestors, derived items, or simply loosely related items.

Type of relations

Relations

can be directional or undirectional. In a directional relation, one item is the source and another item is the target. In an undirectional relation, the two items are treated equally
are manually built using the API or created automatically. An example of automatically built relations is the timeline conform method, which automatically creates directed relations
have metadata as key-value pairs. One key-value pair which is always present is the type key, which describes the reason of the relationship.

Automatically generated relations

Item-to-item relations are automatically generated by timeline conform actions. These relations are directional from source item(s) to target item. The relations have the following tags:

key=conform
conform-job= { conform-job }

Managing item relations

List all item relations

GET /item/(id)/relation

Returns a list of relations that matches the search criteria. Item id can be an Identifiers, that is libraries can be used.

Query Parameters:	direction (string) – `U` - Only return undirectional relations where `id` is part of. `S` - Only return directional relations where `id` is the source item. `T` - Only return directional relations where `id` is the target item. `D` - Only return directional relations where `id` is the source or target item. `A` (default) - Return all relations that `id` is a part of.
Status Codes:	400 – An invalid direction has been specified. 404 – Could not find the item identified by `id`.
Produces:	application/xml, application/json – ItemRelationListDocument. text/plain – CR LF -delimited list of Tabbed tuples of relation id, relation URI, direction type (`U`, `D`), relation type, and source id, target id.
Role:	_relation_read

In addition, extra query parameters of the form key=value can be added, to only return relations that matches the key-value pair(s).

Create an item relation

POST /item/(id1)/relation/(id2)

Generates a new relation between the two items with the given ids, id1 and id2, with the given parameters.

Query Parameters:	direction (string) – Required. `U` - Set the direction of the relation as undirectional. `S` - Set the direction as `id1` being the source and `id2` being the target. `T` - Set the direction as `id2` being the source and `id1` being the target. allowDuplicate (boolean) – `true` (default) - Allow duplicate relations. `false` - Avoid adding duplicate relations.
Status Codes:	400 Bad request – Both `id1` and `id2` identifies the same item, or the direction is invalid. 404 Not found – Could not find the item identified by `id1` or `id2`.
Produces:	application/xml, application/json – ItemRelationDocument
Role:	_relation_write

In addition, extra query parameters of the form key=value can be added, to set metadata of the item-to-item relation.

Create multiple item relations

New in version 4.16.

POST /relation

Generates multiple relations at once. Each relation has a source and a target, and the direction can take the value U, if not set it generates a directional relation from source to target.

Query Parameters:	allowDuplicate (boolean) – `true` (default) - Allow duplicate relations. `false` - Avoid adding duplicate relations.
Status Codes:	400 Bad request – Both `source` and `target` identifies the same item, or the direction is invalid. 404 Not found – Could not find the item identified by `source` or `target`.
Accepts:	application/xml, application/json – ItemRelationListDocument
Produces:	application/xml, application/json – ItemRelationListDocument
Role:	_relation_write

For example:

HTML/XML

<?xml version="1.0"?>
<ItemRelationListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <relation>
    <direction>
      <source>VX-1</source>
      <target>VX-2</target>
    </direction>
  </relation>
  <relation>
    <direction>
      <source>VX-1</source>
      <target>VX-3</target>
    </direction>
  </relation>
  <relation>
      <direction type="U">
        <source>VX-4</source>
        <target>VX-5</target>
      </direction>
   </relation>
</ItemRelationListDocument>

Retrieve an item relation

GET /relation/(relation-id)

Retrieves the relation with the id relation-id.

Status Codes:	404 Not found – Could not find the relation identified by `relation-id`.
Produces:	application/xml, application/json – ItemRelationDocument.
Role:	_relation_read

Update an item relation

PUT /relation/(relation-id)

Updates the relation metadata for a relation with the id relation-id.

Query Parameters:	direction (string) – `U` - Set the direction of the relation as undirectional. `S` - Set the direction as `id1` being the source and `id2` being the target. `T` - Set the direction as `id2` being the source and `id1` being the target.
Status Codes:	404 Not found – Could not find the relation identified by `relation-id`.
Produces:	application/xml, application/json – The updated item described as an ItemRelationDocument.
Role:	_relation_write

Query parameters of the form key=value are used to modify the metadata of the relation.

Delete an item relation

DELETE /relation/(relation-id)

Deletes the relation with the id relation-id.

Status Codes:	200 OK – The item relation is deleted. 404 Not found – Could not find the relation identified by `relation-id`.
Role:	_relation_write

Delete all item relations

DELETE /item/(id)/relation

Deletes the relations with the specified direction or all relations.

Query Parameters:	direction (string) – `A` - This is the default value. Deletes all relations `id1` is involved in. `U` - Deletes only the relations with the direction as undirectional. `S` - Deletes only the relations where `id1` is the source and `id2` is the target. `T` - Deletes only the relations where `id2` is the source and `id1` is the target.
Status Codes:	200 OK – The item relation is deleted.
Role:	_relation_write

Delete all relations between two items

DELETE /item/(id1)/relation/(id2)

Deletes the relations with the specified direction or all relations between id1 and id2.

Query Parameters:	direction (string) – `A` - This is the default value. Deletes all relations between `id1` and `id2`. `U` - Deletes only the relations with the direction as undirectional. `S` - Deletes only the relations where `id1` is the source and `id2` is the target. `T` - Deletes only the relations where `id2` is the source and `id1` is the target.
Status Codes:	200 OK – The item relation is deleted.
Role:	_relation_write