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