Collections¶

Vidispine collections are groupings of items. It uses the VSCollection object from VidiRest as well as VSItem and VSACL objects.

An example of getting a collection with the ID ‘VX-1’ would be:

from portal.vidispine.icollection import CollectionHelper
from portal.vidispine.igeneral import performVSAPICall

ch = CollectionHelper(runas=runas_user)
response = performVSAPICall(func=ch.getCollection, \
                            args={'collection_id':'VX-1'}, \
                            vsapierror_templateorcode='template.html')

If the performVSAPICall was a success, the response will contain an attribute “success”, and the response will contain the Collection object:

_collection = res['response']

An example of creating a new collection, using the settings of the currently browsing user:

from portal.vidispine.icollection import CollectionHelper
from portal.vidispine.iuser import UserHelper
from portal.vidispine.igeneral import performVSAPICall

ch = CollectionHelper(runas=self.request.user)
uh = UserHelper(runas=self.request.user)
settingsprofile_id = uh.getUserSettingsProfile()
res = performVSAPICall(func=ch.createCollection, \
                       args={'collection_name':'new collection',\
                             'settingsprofile_id':settingsprofile_id},\
                       vsapierror_templateorcode=500)
collection = res['response']

The above uses a collection helper and a user helper which gets the current users settings profile, then makes a call to create a collection with the name ‘new collection’.

Collection Interface¶

Interface for Collection¶

This API is for working with collections in Vidispine.

class portal.vidispine.icollection.CollectionHelper(user=None, runas=None, *args, **kwargs)¶

This is an interface to the helper classes provided by VidiREST

addCollectionToCollection(collection_id, add_collection_id)¶

Add a collection to another collection

Args:

collection_id: Id of the collection to add to (parent)
add_collection_id: Id of the collection to be added (new child)

Returns:

Add collection to collection return value

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”addCollectionToCollection”, collection_id=add_collection_id
Post modify:
sender=self.__class__, instance=collection_id, method=”addCollectionToCollection”, collection_id=add_collection_id

addEntryToCollectionACL(collection_id, entry_document)¶

Add an ACL entry to a collection

Args:

collection_id: Id of the collection.

Returns:

Newly created entry id

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”addEntryToCollectionACL”, entry_document=entry_document
Post modify:
sender=self.__class__, instance=collection_id, method=”addEntryToCollectionACL”

addEntryToCollectionACLBulk(collection_id, entry_document)¶

Adds ACL entries to a collection

Args:

collection_id: Id of the collection.

Returns:

Newly created entry id

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”addEntryToCollectionACL”, entry_document=entry_document
Post modify:
sender=self.__class__, instance=collection_id, method=”addEntryToCollectionACL”

addItemToCollection(collection_id, item_id)¶

Add item to a collection

Args:

collection_id: Id of the collection.
item_id: Id of the item to be added

Returns:

Add item to collection return value

Signals raised:

Pre modify: sender=self.__class__, instance=collection_id, method=”addItemToCollection”, item_id=item_id
Post modify: sender=self.__class__, instance=collection_id, method=”addItemToCollection”

addItemsToCollection(collection_id: str, item_ids: Iterable[str]) → None¶

Add items to a collection.

Args:

collection_id: Id of the collection.
item_ids: Ids of the items to be added.

Returns:

None

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”addItemsToCollection”, item_ids=item_ids
Post modify:
sender=self.__class__, instance=collection_id, method=”addItemsToCollection”, item_ids=item_ids

addLibraryToCollection(collection_id, library_id, addItems=True)¶

Add library to a collection

Args:

collection_id: Id of the collection.
library_id: Id of the library
addItems: Should we add the items instead of the dynamic library? Default: True

Returns:

Add library to collection return value

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”addLibraryToCollection”, library_id=library_id
Post modify:
sender=self.__class__, instance=collection_id, method=”addLibraryToCollection”

createCollection(collection_name, settingsprofile_id=None)¶

Creates a collection in Vidispine

Args:

collection_name: Name of the collection to be created.
settingsprofile_id: Optional settings profile

Returns:

VSCollection object.

Signals raised:

Pre create:
sender=self.__class__, instance=collection_name, method=”createCollection”, settingsprofile_id=settingsprofile_id

Post create:
sender=self.__class__, instance=collection_name, method=”createCollection, collection_id=new_collection_id”

export(collection_id, uri=None, tag_name=None, metadataprojection=None, jobmetadata=None, query=None, *args)¶

Exports a collection

Args:

collection_id: Id of the collection.
uri: uri to the export place
tag_name: Optional tag name to export
metadataprojection: metadataprojection if metadata is being included
jobmetadata: Optional metadata to be sent to the job
query: Optional query to be sent to the export function

Returns:

Export result

Signals raised:

Pre export:
sender=self.__class__, instance=collection_id, method=”export”, tag_name=tag_name, uri=uri, metadataprojection=metadataprojection
Post export:
sender=self.__class__, instance=collection_id, method=”export”

getAllCollections(includeItemThumbnails=False, savedSearchesOnly=False, ignoreDeprecatedSavedSearches=True, filterByName=None, matrix=None, *args) → list[VidiRest.objects.collection.VSCollection]¶

Gets all collection from Vidispine.

Args: * includeItemThumbnails: Include representative thumbnails for each collection. * savedSearchesOnly: Return saved searches only. The returned VSCollection objects will include the metadata

value for field “criteria_document”, which is the Cantemo search document.

ignoreDeprecatedSavedSearches: If true, ignore saved searches created pre 2.4
filterByName: Return collections matching this name only, cannot be used together with
savedSearchesOnly=True
matrix: matrix information default values in vidispine: {‘first’ 1, ‘number’: 100}

Returns: * A list of VSCollection objects.

getAllCollectionsAsDict(includeItemThumbnails=False, savedSearchesOnly=False, ignoreDeprecatedSavedSearches=True, filterByName=None, matrix=None, *args)¶

Gets all collection from Vidispine.

The difference between this function and getAllCollections is that it has the possiblity to return more data such as total number of hits.

Args: * includeItemThumbnails: Include representative thumbnails for each collection. * savedSearchesOnly: Return saved searches only. The returned VSCollection objects will include the metadata

value for field “criteria_document”, which is the Cantemo search document.

filterByName: Return collections matching this name only, cannot be used together with
savedSearchesOnly=True
matrix: matrix information default values in vidispine: {‘first’ 1, ‘number’: 100}
ignoreDeprecatedSavedSearches: If true, ignore saved searches created pre 2.4

Returns: * A dict containing a list of VSCollection objects and total number of hits.

getAllNotifications()¶: Returns a list of collection notifications

getChildCollectionsOfCollectionRecursively(collection_id, collection_ids=None, exclude_list=None)¶

Given a list of collection ids, return all children.

Parameters

collection_id – list of parent_ids: [‘VX-1’]
collection_ids – set of collection ids to return, this should be an empty initially.
exclude_list – List of collection ids to exclude: [‘VX-1’]

Returns

list of collections ids [‘VX-2’, ‘VX-3’]

getCollection(collection_id, query=None, *args)¶

Gets a collection from Vidispine.

Note: By default the resulting VSCollection does not include metadata. This can be included by passing query=’content=metadata’ to this function.

Args:

collection_id: The collection id to get.
query: Additional query to be sent through the API call

Returns:

VSCollection object.

getCollectionACL(collection_id, *args)¶

Gets the collection ACL from Vidispine.

Args:

collection_id: Id of the collection.

Returns:

Object VSACL representing the ACL

getCollectionACLEntry(collection_id, access_id, *args)¶

Gets the collection ACL from Vidispine.

Args:

collection_id: Id of the collection.
access_id: Id of the acl entry.

Returns:

Object VSACL representing the ACL

getCollectionACLMerged(collection_id, username, type='GENERIC', permission='NONE')¶

Gets the merged collection ACL from Vidispine.

Args:

collection_id: Id of the collection.
username: Merged ACL for this user
type: Filter on this type and above. Default: ‘GENERIC’
permission: Filter on this permission and above. Default: ‘NONE’

Returns:

A VSACLMerged object representing the collection ACL

getCollectionCollectionsAndAncestorCollectionsIds(collection_id)¶: Given an collection_id, retrieves a set with ids of all the parent collections and ancestor collections the collection is in, based on the __ancestor_collection and __collection metadata fields

getCollectionItems(collection_id, query=None, *args)¶

Gets items from a specified collection from Vidispine, and includes more information about all items (set in query).

Args:

collection_id: The collection id to get.
query: Additional query to be sent through the API call

Returns:

List of VSItems.

Example 1: If you would like to see items in collection VX-1

getCollectionItems(‘VX-1’)

Example 2: If you would like to see metadata on items in collection VX-1

getCollectionItems(‘VX-1’, query={‘content’: ‘metadata’})

getCollectionMetadata(collection_id, fields=None)¶

Gets the collection metadata from Vidispine.

Args:

collection_id: Id of the collection.
fields: List of fields to get

Returns:

Collection metadata

getCollectionMetadataByLabel(collection_id, label_name)¶

Gets collection metadata from Vidispine for a specific metadata label.

Args:

collection_id: Id of the collection.
label_name: The label to fetch metadata for

Returns:

Collection metadata

getCollectionMetadataFieldGroups(collection_id)¶

Get the item metadata group

Args:

collection_id: Id of the collection.

Returns:

Collection metadata

getCollections(collection_ids, content=None, *args)¶

Gets a list of collections from Vidispine.

By default the resulting collections include metadata, thumbnail, poster, uri and shape information.

Args:

collection_ids: List of collection ids
content: Optional content dictionary to define what element of the collection to include.

Returns:

A VSItem object representing the collection

getItemsFromCollection(collection, results_per_page, page)¶

Get all the items, gets all the items within a library and gets all the items from within a collection and return them as a list

Args:

collection: An actual collection
results_per_page: Integer of results per page
page: The current page number

Returns:

item_ids: list of item IDs
collections

getRepresentativeThumbnails(collection_id, num_of_thumbs=4)¶

Get representative thumbnails for the collection

Args:

collection_id: Id of the collection.
num_of_thumbs: number of thumbnails per collection. Default value: 4

Returns:

VSCollection object.

getRepresentativeThumbnailsForCollections(collections)¶

Get a list of thumbnails which can be shown in the UI to represent this collection

Args:

Collections - list of collection objects

Returns:

List of URI to thumbnails

getRepresentativeThumbs(collection_id, num_of_thums=4)¶

Get representative thumbnails for the collection

Args:

collection_id: Id of the collection.
num_of_thumbs: number of thumbnails per collection. Default value: 4

Returns:

A list of VSItems

removeCollection(collection_id)¶

Remove the collection

Args:

collection_id: Id of the collection to be removed.

Returns:

None

Signals raised:

Pre delete: sender=self.__class__, instance=collection_id, method=”removeCollection”
Post delete: sender=self.__class__, instance=collection_id, method=”removeCollection”

removeCollectionACLEntry(collection_id, access_id)¶

Removes an ACL entry from a collection

Args:

collection_id: Id of the collection.
access_id: ACL entry id

Returns:

None

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”removeCollectionACLEntry”, access_id=access_id
Post modify:
sender=self.__class__, instance=collection_id, method=”removeCollectionACLEntry”

removeCollectionACLEntryBulk(collection_id, entry_document)¶

Removes ACL entries from a collection

Args:

collection_id: Id of the collection.
entry_document: AccessControlListDocument

Returns:

None

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”removeCollectionACLEntry”, entry_document=entry_document
Post modify:
sender=self.__class__, instance=collection_id, method=”removeCollectionACLEntry”

removeCollectionMetadataFieldGroup(collection_id, metadatagroup_name)¶

Remove a metadata group association with a collection and clear out all metadata fields related to the group.

Args:

collection_id: Id of the collection.
metadatagroup_name: Name of the metadata group

Returns:

Nothing

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”removeCollectionMetadataFieldGroup”, metadatagroup_name=metadatagroup_name
Post modify:
sender=self.__class__, instance=collection_id, method=”removeCollectionMetadataFieldGroup”

removeFromCollection(collection_id, object_id, type=None)¶

Remove the object from collection

Args:

collection_id: Id of the collection.
object_id: Id of the object to be removed, can be item id, collection id, or library id

Returns:

None

Signals raised:

Pre delete:
sender=self.__class__, instance=collection_id, method=”removeFromCollection”, object_id=object_id
Post delete:
sender=self.__class__, instance=collection_id, method=”removeFromCollection”

renameCollection(collection_id, new_name)¶

Rename a collection

Args:

collection_id: Id of the collection.
new_name: The new name of the collection

Returns:

None

Signals raised:

Pre modify: sender=self.__class__, instance=collection_id, method=”renameCollection”, new_name=new_name
Post modify: sender=self.__class__, instance=collection_id, method=”renameCollection”

reorderCollection(collection_id, src_object_id, src_object_type, move_to_object_id, before=True)¶

Move a certain object in a collection to before or after another given object

Args:

collection_id: Id of the collection.
src_object_id: Id of the source object to be moved
src_object_type: Type of the source object. Options: ‘item’, ‘library’, or ‘collections’
move_to_object_id: Id of the target object where the source object should be moved to
before: If set to true, the source object will be moved to before the target object. Else after. Default: True

Returns:

A VSCollection object of the new reordered collection

Signals raised:

Pre modify: sender=self.__class__, instance=collection_id, method=”reorderCollection”, collection_id=collection_id, src_object_id=src_object_id, src_object_type=src_object_type, move_to_object_id=move_to_object_id, before=before
Post modify: sender=self.__class__, instance=collection_id, method=”reorderCollection”

setCollectionMetadata(collection_id, metadata_document, skipForbidden=True, enable_cascading=True, only_return_changes=True)¶

Sets the collection metadata.

Args:

collection_id: Id of the collection.
metadata_document: A pyxb metadata document
skipForbidden: Variable that tells the backend to ignore forbidden fields - no error is thrown if they are included in the update
enable_cascading: When set to False, changes will not cascade down to child items. Used for special cases where cascading is not wanted.
only_return_changes: If True, only return the changed entries
else return the whole global metadata after the update

Returns:

Collection metadata

Signals raised:

Pre modify: sender=self.__class__, instance=collection_id, method=”setCollectionMetadata”, metadata_document=metadata_document, enable_cascading=enable_cascading
Post modify: sender=self.__class__, instance=collection_id, method=”setCollectionMetadata”, metadata_document=metadata_document, enable_cascading=enable_cascading

setCollectionMetadataFieldGroup(collection_id, metadatagroup_name)¶

Associates a metadata group to a collection

Args:

collection_id: Id of the collection.
metadatagroup_name: Metadata group name to be associated with the collection

Returns:

None

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”setCollectionMetadata”, metadata_document=metadata_document
Post modify:
sender=self.__class__, instance=collection_id, method=”setCollectionMetadata”

setCollectionMetadataFieldValue(collection_id, field_name, field_val)¶

Quick and easy function to a set a value to a specific field in a collection

Args:

collection_id: A collection ID.
field_name: The field name.
field_val: The value of the field to be set.

Returns:

None

Signals raised:

Pre modify:
sender=self.__class__, instance=collection_id, method=”setCollectionMetadata”, metadata_document=metadata_document
Post modify:
sender=self.__class__, instance=collection_id, method=”setCollectionMetadata”

Collections¶

Collection Interface¶

Interface for Collection¶

Table of Contents

Previous topic

Next topic