Collections [VC 5.6 INT]

Collections are generic storage containers and can for example be used as:

A sort of folder structure, where files are mapped as items and sub folders are mapped as sub collections in the hierarchy.
A simple container for a number of items and collections.
A representation of a Non Linear Editor (NLE) “bin”.
A representation of an entity in your domain.

Creating collections

Create a collection using POST /collection. Once created you can add items, libraries or other collections to it, add metadata or grant access to other users by adding access controls.

CODE

POST /collection?name=Pending%20review

<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <loc>http://localhost:8080/API/collection/VX-16</loc>
  <id>VX-16</id>
  <name>Pending review</name>
</CollectionDocument>

Searching for collections

You can search for collections in the same way as you can search for items.

CODE

PUT /collection
Content-Type: application/xml

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <text>Pending</text>
</ItemSearchDocument>

<CollectionListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <hits>1</hits>
  <collection>
    <id>VX-16</id>
    <name>Pending review</name>
  </collection>
</CollectionListDocument>

Searching for collections with specific items

Use an item query to find collections that contain specific items. For example, to find collections with a title containing ‘Peach’ or collections with items with similar titles:

CODE

<ItemSearchDocument version="2" xmlns="http://xml.vidispine.com/schema/vidispine">
  <operator operation="OR">
    <field>
      <name>title</name>
      <value>Peach</value>
    </field>
    <item>
      <field>
        <name>title</name>
        <value>Peach</value>
      </field>
    </item>
  </operator>
</ItemSearchDocument>

See Joins on collection search.

Searching in a collection

You can also search for items in a collections using PUT /collection/(collection-id)/item. An alternative way of finding only items that exist in a collection is to query on the __collection transient metadata field. This is also more flexible as it allows you to find items in multiple collections, or using it as part of a more complex query.

CODE

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <name>__collection</name>
    <value>VX-16</value>
  </field>
  <operator operation="NOT">
    <field>
      <name>__collection</name>
      <value>VX-1</value>
    </field>
  </operator>
</ItemSearchDocument>

The difference between searching for items in a collection using PUT /collection/(collection-id)/item and PUT /item with a query on __collection is the default ordering, which is by collection order and by creation date, respectively.

There is also the __ancestor_collection transient metadata field that allows you to find items that exist in a collection or in a sub collection of that collection.

Listing collections that contain an item

If you want to see which collections contain an item, you can either look at the item metadata and look at the ” __collection ” field. There will be one entry for each collection that includes the item. This, however, does not take into account which collections a user has read access to. In order to see which collections contain an item with read permissions honored you can use GET /item/(item-id)/collection

Ordering collections

The entities in the collection are ordered, and new entities will be added at the end of the list. Use POST /collection/(collection-id)/order to change the order. The order will be enforced in requests to GET /collection/(collection-id) and GET /collection/(collection-id)/item for example.

To get the same ordering as in GET /item you will have to explicitly sort on the creation date, the created field, which is the default.

Update collection content

Items, libraries and collections can be added, removed and reordered in a collection in a single call. Use GET /collection/(collection-id) to get the content of the collection. Then rearrange, add and/or remove content and use PUT /collection/(collection-id) to update the collection.

Partial update collection content

If you only want to specify each change (add, move or remove entity) in a collection you can use PUT /collection/(collection-id) and specifying a mode in each content element.

CODE

PUT /collection/VX-2000
Content-Type: application/xml

<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <loc>http://localhost:8080/API/collection/VX-2000/</loc>
    <id>VX-2000</id>

    <!-- Set the name to "New name" -->
    <name>New name</name>

    <!-- Move item VX-3 after VX-2 -->
    <content mode="move" after="VX-2">
        <id>VX-3</id>
        <uri>http://localhost:8080/API/item/VX-3</uri>
        <type>item</type>
        <metadata/>
    </content>

    <!-- Add the items from library VX*40 to after item VX-2 -->
    <content mode="add" addItems="true" after="VX-2">
        <id>VX*40</id>
        <uri>http://localhost:8080/API/library/VX*40</uri>
        <type>library</type>
        <metadata/>
    </content>

    <!-- Add the library VX*44 before VX*33 -->
    <content mode="add" before="VX*33">
        <id>VX*44</id>
        <uri>http://localhost:8080/API/library/VX*44</uri>
        <type>library</type>
        <metadata/>
    </content>

    <!-- Remove the collection VX-500 -->
    <content mode="remove">
        <id>VX-500</id>
        <uri>http://localhost:8080/API/collection/VX-500</uri>
        <type>collection</type>
        <metadata/>
    </content>
</CollectionDocument>

Multiple relations between same entities

New in version 5.5.

In version 5.5, multiple relations between the same pair of collection and item, sub-collection or library are allowed. Each relation has a unique id (UUID), which can be used to reference relations instead of the entity id shown above.

In addition, a new mode is added: “update”, which only updates a relation, and not move it.

An example. Assume the following collection:

CODE

<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <id>VX-937</id>
    <name>coll</name>
    <content>
        <id>VX-718</id>
        <type>item</type>
        <reference>bbd5adbb-4826-49cc-8f26-b87a266f09db</reference>
        <metadata>
            <field>
                <key>myfield</key>
                <value>somedata</value>
            </field>
        </metadata>
    </content>
    <content>
        <id>VX-721</id>
        <type>item</type>
        <reference>9cf0a1ac-7c7b-49a7-acf9-33fce948e1aa</reference>
        <metadata/>
    </content>
    <content>
        <id>VX-718</id>
        <type>item</type>
        <reference>80eaad68-bcb7-4811-ada0-2fa1c366547c</reference>
        <metadata/>
    </content>
</CollectionDocument>

The following update:

Move the last VX-718 to the top.
Removes the first VX-718.
Adds two new VX-719 (at the end of the list).
Sets metadata on VX-721.

CODE

<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <content mode="move" before="bbd5adbb-4826-49cc-8f26-b87a266f09db"/>
        <reference>80eaad68-bcb7-4811-ada0-2fa1c366547c</reference>
    </content>
    <content mode="remove">
        <reference>bbd5adbb-4826-49cc-8f26-b87a266f09db</reference>
    </content>
    <content mode="add">
        <id>VX-719</id>
        <type>item</type>
    </content>
    <content mode="add">
        <id>VX-719</id>
        <type>item</type>
    </content>
    <content mode="update">
        <reference>9cf0a1ac-7c7b-49a7-acf9-33fce948e1aa</reference>
        <metadata>
            <field>
                <key>myfield</key>
                <value>newdata</value>
            </field>
        </metadata>
    </content>
</CollectionDocument>

Metadata on collection to entity relations

Each collection to entity relation can contain metadata which is stored in fields with a key and a value and can be modified when updating the collection.

CODE

GET /collection/VX-3866

<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <loc>http://localhost:8080/API/collection/VX-3866/</loc>
  <id>VX-3866</id>
  <content>
    <id>VX-5480</id>
    <uri>http://localhost:8080/API/item/VX-5480</uri>
    <type>item</type>
    <metadata/>
  </content>
  <content>
    <id>VX*1810</id>
    <uri>http://localhost:8080/API/library/VX*1810</uri>
    <type>library</type>
    <metadata/>
  </content>
</CollectionDocument>

PUT /collection/VX-3866
Content-Type: application/xml

<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <loc>http://localhost:8080/API/collection/VX-3866/</loc>
  <id>VX-3866</id>
  <content>
    <id>VX-5480</id>
    <uri>http://localhost:8080/API/item/VX-5480</uri>
    <type>item</type>
    <metadata>
      <field>
        <key>AddedBy</key>
        <value>Jane Doe</value>
      </field>
    </metadata>
  </content>
  <content>
    <id>VX*1810</id>
    <uri>http://localhost:8080/API/library/VX*1810</uri>
    <type>library</type>
    <metadata>
      <field>
        <key>AddedBy</key>
        <value>John Doe</value>
      </field>
    </metadata>
  </content>
</CollectionDocument>

Collections as folders

As mentioned in the introduction, collections could be used to represent folders, as a way for your users to organize their items.

This could be an entirely logical grouping, or correspond to the actual directory structure of the items files on the file system. To achieve the later, you can mark the collections as folder mapped collections. See Folder mapped collections in the API reference on how to set this up.

Representative thumbnails

A new metadata field has been added to the collection metadata: representativeItems. This field can contain a list of items that will represent this collection. Vidispine will automatically get the representative thumbnails of each item and add a transient metadata field on the collection metadata.

For example:

CODE

<field>
  <name>representativeItems</name>
  <value>VX-653</value>
  <value>VX-657</value>
  <value>VX-658</value>
  <value>VX-659</value>
</field>

will add those values to the metadata:

CODE

<field>
    <name>__representativeThumbnails</name>
    <value>/API/thumbnail/VX-2/VX-653;version=0/2100@NTSC30</value>
    <value>/API/thumbnail/VX-2/VX-657;version=0/0@24000</value>
    <value>/API/thumbnail/VX-2/VX-658;version=0/3300297@30000</value>
    <value>/API/thumbnail/VX-2/VX-659;version=0/500@PAL</value>
</field>
<field>
    <name>__representativeThumbnailsNoAuth</name>
    <value>/APInoauth/thumbnail/VX-2/VX-653;version=0/2100@NTSC30?hash=9dfb29f8159532b1d3a119462e64c03f</value>
    <value>/APInoauth/thumbnail/VX-2/VX-657;version=0/0@24000?hash=bb75e99dd2f1f961810c85fab99cd75f</value>
    <value>/APInoauth/thumbnail/VX-2/VX-658;version=0/3300297@30000?hash=696fa412368ccc0ac11fc30018ea8062</value>
    <value>/APInoauth/thumbnail/VX-2/VX-659;version=0/500@PAL?hash=0737888e52cb4e66041ba7d1e58b22be</value>
</field>

In combination with Stitching images, this can be used to easily create and cache a collection thumbnail without having to track the item update notifications.