Deletion lock

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.

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.

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

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

GET /item/VX-132340/metadata
<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:

GET /storage/file/VX-10725401/metadata
<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.
POST /collection/VX-9129/deletion-lock
<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.

GET /collection/VX-9129/deletion-lock
<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>
GET /item/VX-132271/deletion-lock
<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.
POST /collection/VX-9129/deletion-lock
<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
</DeletionLockDocument>
POST /item/VX-132271/deletion-lock
<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.

GET /item/VX-132271/deletion-lock
<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.
POST /item/VX-132164/deletion-lock
<DeletionLockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <expiryTime>2019-10-09T18:49:41.650+02:00</expiryTime>
</DeletionLockDocument>
POST /file/VX-10725401/deletion-lock
<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.

GET /item/VX-132164/deletion-lock
<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>
GET /storage/file/VX-10725401/deletion-lock
<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:

PUT /search
<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>