Item-to-item relations [VC 21.3 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 }

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:

<?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