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”