Item-to-item relations

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/jsonItemRelationListDocument.
  • text/plainCR 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:
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:
Produces:
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:
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:
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