Collections¶
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.
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.
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¶
New in version 4.2.4.
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:
<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>
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.
<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¶
New in version 4.7.
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¶
New in version 4.7.
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.
PUT /collection
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>
Metadata on collection to entity relations¶
New in version 4.7.
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.
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¶
New in version 4.0.
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:
<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:
<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.