Deletion lock [VC 21.3 GEN]

New in version 4.15.

Deletion lock is a mechanism to prevent entities from been moved or deleted. Entities that support deletion lock are collections, items and files.

New in version 4.17.2.

Locked files can be moved by running an explicit move job. Thus, overriding the lock for that file.

Adding locks

Deletion locks can be added to collections, items and files. All locks must have an expiration time, and can have user defined key-value metadata that can be used to filter locks and to for example explain why a lock exists.

HTML/XML

<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
  <metadata>
    <field>
      <key>reason</key>
      <value>Locked for playout</value>
    </field>
  </metadata>
</DeletionLockDocument>

Deletion locks can also be used in searches, and support notifications so that you can easily take action once a lock has expired.

Lock expiration

All deletion locks must have an expiration time.

Expired locks are treated as if they weren’t present at all.
Expired deletion locks on collections and items can be automatically removed if autoRemoveExpiredDeletionLocks is set to true.
Expired file deletion locks need to be removed manually.

The isExpired attribute highlights locks that have expired:

HTML/XML

<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine" isExpired="true">
  <id>VX-1574</id>
  <user>admin</user>
  <expiryTime>2018-09-09T18:49:41.650+02:00</expiryTime>
  <modified>2018-10-12T14:27:03.175+02:00</modified>
  <entityType>Item</entityType>
  <entityId>VX-32140</entityId>>
</DeletionLockDocument>

Working with multiple locks

An entity can have multiple deletion locks, but only zero or one effective deletion lock.

An effective lock is a lock that hasn’t expired, and has the maximum expiration time among all the explicit locks and inherited locks.
An entity with an effective deletion lock can be copied, but not moved or deleted; either by any explicit API request, or Vidispine internally (storage-rule for example).

In the examples below, you will see that effective locks are shown as isEffective="true.

Lock inheritance

Deletion locks will be automatically inherited from parent to child entities, i.e., from collection to sub-collections to items and then to files, with one exception:

If there is any explicit lock set on a file, the file will not inherit any parent locks.

One use case of this behavior is that if the original asset needs to be kept for a longer period of time, but its copy can be removed earlier.

Transient metadata

An entity’s effective lock id and expiration time are added to the entity’s metadata as transient fields:

__deletion_lock_id - The id of the effective lock on the entity (string-exact).
__deletion_lock_expiry - The expiration time of the effective lock (date).

For example, an item with a deletion lock will have metadata:

NONE

GET /item/VX-132340/metadata

HTML/XML

<MetadataListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-132340">
  <metadata>
    <revision>VX-706676,VX-706677,VX-706678,VX-706671,VX-706672</revision>
    <timespan start="-INF" end="+INF">
      ...
      <field>
        <name>__deletion_lock_id</name>
        <value>VX-1559</value>
      </field>
      <field>
        <name>__deletion_lock_expiry</name>
        <value>2018-10-13T07:49:46.637Z</value>
      </field>
    </timespan>
  </metadata>
  </item>
</MetadataListDocument>

The same applies for files:

NONE

GET /storage/file/VX-10725401/metadata

HTML/XML

<SimpleMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <key>__deletion_lock_expiry</key>
    <value>2019-10-09T16:49:41.65Z</value>
  </field>
  <field>
    <key>__deletion_lock_id</key>
    <value>VX-1561</value>
  </field>
</SimpleMetadataDocument>

Examples

Collection lock inheritance

Assuming one collection and one item:

The item belongs to the collection.
The collection has an explicit lock set.

NONE

POST /collection/VX-9129/deletion-lock

HTML/XML

<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
</DeletionLockDocument>

Both the collection and the item will get the deletion lock.

NONE

GET /collection/VX-9129/deletion-lock

HTML/XML

<DeletionLockListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <lock isEffective="true">
  <id>VX-1410</id>
  <user>admin</user>
  <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
  <modified>2018-10-11T15:04:24.125+02:00</modified>
  <entityType>Collection</entityType>
  <entityId>VX-9129</entityId>
  <metadata/>
  </lock>
</DeletionLockListDocument>

NONE

GET /item/VX-132271/deletion-lock

HTML/XML

<DeletionLockListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <lock isEffective="true" isInherited="true">
  <id>VX-1410</id>
  <user>admin</user>
  <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
  <modified>2018-10-11T15:04:24.125+02:00</modified>
  <entityType>Collection</entityType>
  <entityId>VX-9129</entityId>
  <metadata/>
  </lock>
</DeletionLockListDocument>

Effective locks

Assuming one collection and one item:

Each of them have one explicit lock set.

NONE

POST /collection/VX-9129/deletion-lock

HTML/XML

<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
</DeletionLockDocument>

NONE

POST /item/VX-132271/deletion-lock

HTML/XML

<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <expiryTime>2019-09-09T18:49:41.650+02:00</expiryTime>
</DeletionLockDocument>

The item will inherit the lock from the collection. The effective lock of the item is the inherited one, since it has longer expiration time.

NONE

GET /item/VX-132271/deletion-lock

HTML/XML

<DeletionLockListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <lock>
    <id>VX-1411</id>
    <user>admin</user>
    <expiryTime>2019-09-09T18:49:41.650+02:00</expiryTime>
    <modified>2018-10-11T15:16:42.802+02:00</modified>
    <entityType>Item</entityType>
    <entityId>VX-132271</entityId>
    <metadata/>
    </lock>
  <lock isEffective="true" isInherited="true">
    <id>VX-1410</id>
    <user>admin</user>
    <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
    <modified>2018-10-11T15:04:24.125+02:00</modified>
    <entityType>Collection</entityType>
    <entityId>VX-9129</entityId>
    <metadata/>
  </lock>
</DeletionLockListDocument>

Explicit file locks

Assuming one item with one file in it:

Both the item and the file have explicit locks set.

NONE

POST /item/VX-132164/deletion-lock

HTML/XML

<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
</DeletionLockDocument>

NONE

POST /file/VX-10725401/deletion-lock

HTML/XML

<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <expiryTime>2017-09-09T18:49:41.650+02:00</expiryTime>
</DeletionLockDocument>

The file will not inherit any lock from the item, since it has an explicit lock. In this case, the file lock has expired, so the file can be removed.

NONE

GET /item/VX-132164/deletion-lock

HTML/XML

<DeletionLockListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <lock isEffective="true">
    <id>VX-1412</id>
    <user>admin</user>
    <expiryTime>2019-09-09T18:49:41.650+02:00</expiryTime>
    <modified>2018-10-11T15:39:30.402+02:00</modified>
    <entityType>Item</entityType>
    <entityId>VX-132164</entityId>
    <metadata/>
  </lock>
</DeletionLockListDocument>

NONE

GET /storage/file/VX-10725401/deletion-lock

HTML/XML

<DeletionLockListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <lock isExpired="true">
    <id>VX-1413</id>
    <user>admin</user>
    <expiryTime>2017-09-09T18:49:41.650+02:00</expiryTime>
    <modified>2018-10-11T15:40:30.483+02:00</modified>
    <entityType>File</entityType>
    <entityId>VX-10725401</entityId>
    <metadata/>
  </lock>
</DeletionLockListDocument>

Search using deletion locks

The deletion lock transient metadata fields can be used in collection, item and file searches. For example, to find items that will expire in the coming week:

NONE

PUT /search

HTML/XML

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine" version="1">
  <field>
    <name>__deletion_lock_expiry</name>
    <range>
      <value>NOW</value>
      <value>NOW+7DAYS</value>
    </range>
  </field>
</ItemSearchDocument>