Triggers

A trigger is the event that will cause the notification to be sent. Different triggers exist for different resources. The trigger used determines what output that can be expected. Note that all keys will not necessarily be set and some keys may have more than one value.

Item triggers

Item create

Resource /item
Parameters -  
Output itemId The id of the created item
action The string “CREATE”

Notifies when an item has been created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <item>
            <create/>
        </item>
    </trigger>
</NotificationDocument>

Item delete

Resource /item
Parameters -  
Output itemId The id of the deleted item
action The string “DELETE”

Notifies when an item has been deleted.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <item>
            <delete/>
        </item>
    </trigger>
</NotificationDocument>

Item modify

Resource /item
Parameters field Specifies which fields to trigger on.
interval Specifies which intervals to trigger on.
language Specifies which languages to trigger on.
track Specifies which tracks to trigger on.
Output itemId The id of the modified item.
changeSetId The id of the metadata change set that was created.
(field-name) The value of the field with the name (field-name).

Notifies when the metadata of an item has been modified. For the syntax of the parameters, please refer to Retrieve metadata.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <metadata>
            <modify>
                <field>field_a, field_b</field>
                <language>en_*</language>
            </modify>
        </metadata>
    </trigger>
</NotificationDocument>

Item create access

Resource /item
Parameters -  
Output notificationType The string “access”.
notificationTrigger The string “CREATE”.
itemId The id of the item that were assigned the access control.
accessId The id of the access control.
permission The level of permission granted by the access control.
user If the access control grants access to a particular user, this value is set.
group If the access control grants access to a particular group, this value is set.

Sends a notification when an access control is created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <access>
            <create/>
        </access>
    </trigger>
</NotificationDocument>

Item delete access

Resource /item
Parameters -  
Output notificationType The string “access”.
notificationTrigger The string “DELETE”.
itemId The id of the item that were assigned the access control.
accessId The id of the access control.
permission The level of permission granted by the access control.
user If the access control grants access to a particular user, this value is set.
group If the access control grants access to a particular group, this value is set.

Sends a notification an access control is deleted.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <access>
            <delete/>
        </access>
    </trigger>
</NotificationDocument>

Item change access

Resource /item
Parameters -  
Output notificationType The string “access”.
notificationTrigger The string “CHANGE”.
itemId The id of the item that were assigned the access control.
accessId The id of the access control.
permission The level of permission granted by the access control.
user If the access control grants access to a particular user, this value is set.
group If the access control grants access to a particular group, this value is set.

Sends a notification when an access control is changed.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <access>
            <change/>
        </access>
    </trigger>
</NotificationDocument>

Item create shape

Resource /item
Parameters -  
Output notificationType The string “shape”.
notificationTrigger The string “CREATE”.
itemId The id of the item that the shape belongs to.
shapeId The id of the shape.

Sends a notification when a shape is created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <shape>
            <create/>
        </shape>
    </trigger>
</NotificationDocument>

Item modify shape

Resource /item
Parameters -  
Output notificationType The string “shape”.
notificationTrigger The string “MODIFY”.
itemId The id of the item that the shape belongs to.
shapeId The id of the shape.

Sends a notification when a shape is modified.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <shape>
            <modify/>
        </shape>
    </trigger>
</NotificationDocument>

Item delete shape

Resource /item
Parameters -  
Output notificationType The string “shape”.
notificationTrigger The string “DELETE”.
itemId The id of the item that the shape belongs to.
shapeId The id of the shape.

Sends a notification when a shape is deleted.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <shape>
            <delete/>
        </shape>
    </trigger>
</NotificationDocument>

Collection triggers

Collection create

Resource /collection
Parameters -  
Output collectionId The id of the created collection
action The string “CREATE”

Notifies when a collection has been created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <collection>
            <create/>
        </collection>
    </trigger>
</NotificationDocument>

Collection delete

Resource /collection
Parameters -  
Output collectionId The id of the deleted collection
action The string “DELETE”

Notifies when a collection has been deleted.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <collection>
            <delete/>
        </collection>
    </trigger>
</NotificationDocument>

Collection metadata

Resource /collection
Parameters field Specifies which fields to trigger on.
interval Specifies which intervals to trigger on.
language Specifies which languages to trigger on.
track Specifies which tracks to trigger on.
Output collectionId The id of the modified collection.
changeSetId The id of the metadata change set that was created.
(field-name) | The value of the field with the name (field-name).

Notifies when the metadata of a collection has been modified. For the syntax of the parameters, please refer to Retrieve metadata.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
      <collection>
        <metadata>
            <modify>
                <field>field_a, field_b</field>
                <language>en_*</language>
            </modify>
        </metadata>
      </collection>
    </trigger>
</NotificationDocument>

Collection modify

Resource /collection
Parameters -  
Output notificationType The string “collection”.
notificationTrigger The string “MODIFY”.
collectionId The id of the collection that has changed.

Sends a notification when the content of a collection has been modified.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <collection>
            <modify/>
        </collection>
    </trigger>
</NotificationDocument>

Document triggers

Document create

Resource /document
Parameters -  
Output document The name of the created document
action The string “CREATE”

Notifies when a document has been created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <document>
            <create/>
        </document>
    </trigger>
</NotificationDocument>

Document delete

Resource /document
Parameters -  
Output document The name of the deleted document
action The string “DELETE”

Notifies when a document has been deleted.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <document>
            <delete/>
        </document>
    </trigger>
</NotificationDocument>

Document update

Resource /document
Parameters field Specifies which fields to trigger on.
interval Specifies which intervals to trigger on.
language Specifies which languages to trigger on.
track Specifies which tracks to trigger on.
Output document The name of the modified document.
changeSetId The id of the metadata change set that was created.
(field-name) The value of the field with the name (field-name).

Notifies when the document metadata has been modified. For the syntax of the parameters, please refer to Retrieve metadata.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
      <document>
        <modify>
          <field>field_a, field_b</field>
          <language>en_*</language>
        </modify>
      </document>
    </trigger>
</NotificationDocument>

Group triggers

Group create

Resource /group
Parameters -  
Output group The name of the created group.
action The string “CREATE”
username The name of the user that created the group.

Sends a notification when a group is created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <group>
            <create/>
        </group>
    </trigger>
</NotificationDocument>

Group delete

Resource /group
Parameters -  
Output group The name of the deleted group.
action The string “DELETE”
username The name of the user that deleted the group.

Notifies when a group has been deleted.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <group>
            <delete/>
        </group>
    </trigger>
</NotificationDocument>

Group modify

Resource /group
Parameters -  
Output group The name of the modified group.
action The string “MODIFY”
username The name of the user that modified the group.
mode Either has the value “ADD” or “REMOVE” depending on the action taken on the group.
affectedGroup Contains the name of any affected group.
affectedUser Contains the name of any affected user.

Notifies when the contents of a group has been modified.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <group>
            <modify/>
        </group>
    </trigger>
</NotificationDocument>

Job triggers

Normal job notifications

POST /job/notification
Content-Type: application/xml

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
         ...
   </action>
   <trigger>
      <job>
         <stop/>
      </job>
   </trigger>
</NotificationDocument>

This notification will be triggered when any job stops.

Placeholder job notifications

One way job notifications differ from other notifications is that they can be created in advanced and then later be specified when starting a job. Note that a single job notification can be used for several jobs.

Creating a placeholder notification, that triggers when jobs stop:

POST /job/notification
Content-Type: application/xml

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
         ...
   </action>
   <trigger>
      <job>
         <stop/>
         <placeholder>true</placeholder>
      </job>
   </trigger>
</NotificationDocument>
VX-16

Using that notification when creating a new import job:

POST /import/?URL=http://example.com/video.avi&notification=VX-16
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <timespan start="-INF" end="+INF">
      <field>
         <name>title</name>
         <value>My notification item!</value>
      </field>
   </timespan>
</MetadataDocument>

Job create

Resource /job
Parameters -  
Output jobId The id of the created job.
action The string “CREATE”.
status The status of the job.
type The type of the job.

Notifies when a job is created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <job>
            <create/>
        </job>
    </trigger>
</NotificationDocument>

Job stop

Resource /job
Parameters -  
Output jobId The id of the stopped job.
action The string “STOP”.
status The status of the job.
type The type of the job.
currentStepNumber The current step number.
currentStepStatus The status of the current step.

Notifies when a job has stopped running, either successfully or unsuccessfully. Note that the output may also contain additional job specific data such as itemId, in the case of an import job.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <job>
            <stop/>
        </job>
    </trigger>
</NotificationDocument>

Job update

Resource /job
Parameters -  
Output jobId The id of the stopped job.
action The string “UPDATE”.
status The status of the job.
type The type of the job.
currentStepNumber The current step number.
currentStepStatus The status of the current step.

Notifies when the status of a job changes. Note that the output may also contain additional job specific data such as itemId, in the case of an import job.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <job>
            <update/>
        </job>
    </trigger>
</NotificationDocument>

Job filtering

Job types

Filter criteria can be added to job notifications in order to filter the jobs they trigger on.

Name Description
type The type of the job
step The step that the job is currently on
jobdata A particular value in the job metadata. Job metadata consists of key value pairs and can be matched either by string comparison or regular expressions.

Example

POST /job/notification
Content-Type: application/xml

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
         ...
   </action>
   <trigger>
      <job>
         <stop/>
         <filter>
           <type>PLACEHOLDER_IMPORT</type>
         </filter>
      </job>
   </trigger>
</NotificationDocument>

this notification is triggered only when a PLACEHOLDER_IMPORT job stops.

Note

If you find notification filtering not working, please verify that there is no normal job notification existing.

Job metadata

Either by string comparison or regular expressions:

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
         ...
   </action>
   <trigger>
      <job>
         <stop/>
         <filter>
           <type>PLACEHOLDER_IMPORT</type>
           <jobdata>
                <key>key</key>
                <value>value</value>
           </jobdata>
         </filter>
      </job>
   </trigger>
</NotificationDocument>
<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
         ...
   </action>
   <trigger>
      <job>
         <stop/>
         <filter>
           <type>PLACEHOLDER_IMPORT</type>
           <jobdata>
                <key-regex>regex</key-regex>
                <value-regex>regex</value-regex>
           </jobdata>
         </filter>
      </job>
   </trigger>
</NotificationDocument>

Content Filter

Content filter criteria can be added to job notifications in order to reduce the size of jobDocument returned by Vidispine.

Example:

POST /job/notification
Content-Type: application/xml

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <action>
         ...
   </action>
  <trigger>
    <job>
      <stop/>
      <contentFilters>
        <contentFilter>jobId</contentFilter>
        <contentFilter>jobState</contentFilter>
      </contentFilters>
    </job>
  </trigger>
</NotificationDocument>

Legal content filters are:

<contentFilters>
  <contentFilter>jobId</contentFilter>
  <contentFilter>jobState</contentFilter>
  <contentFilter>user</contentFilter>
  <contentFilter>startTime</contentFilter>
  <contentFilter>jobType</contentFilter>
  <contentFilter>jobData</contentFilter>
  <contentFilter>errorMessage</contentFilter>
  <contentFilter>itemId</contentFilter>
  <contentFilter>totalSteps</contentFilter>
  <contentFilter>currentStep</contentFilter>
</contentFilters>

Storage triggers

Create storage

Resource /storage
Parameters -  
Output storageId The id of the created storage.
action The string “CREATE”.

Notifies when a storage is created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <storage>
            <create/>
        </storage>
    </trigger>
</NotificationDocument>

Delete storage

Resource /storage
Parameters -  
Output storageId The id of the deleted storage.
action The string “DELETE”.

Notifies when a storage is being deleted.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <storage>
            <delete/>
        </storage>
    </trigger>
</NotificationDocument>

Generate filename

Resource /storage
Parameters -  
Output storageId The id of the storage.
action The string “FILENAME”.
itemId The id of the item the file belongs to.
shapeId The id of the shape the file belongs to.
componentId The id of the component the file belongs to.
fileId The id of the file.
username The name of the user that causes the file to be created.
metadata The metadata of the item.
shapeTag A list of shape tags that belong to the shape.

Notifies when a file is being created on a storage. The message returned by the HTTP or Java action will be used as a filename. If multiple notifications exist for a storage, then either one that returns a valid filename will be used. A valid filename follows the following format: [A-Za-z0-9\_-]+. It is recommended to use fileId in some way to guarantee the uniqueness of the filename.

Note that only the storageId, action and fileId output values are guaranteed to be included.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <storage>
            <filename/>
        </storage>
    </trigger>
</NotificationDocument>

Note

It is recommended to use the filename generation script function instead, see Naming files on storage.

File triggers

Only generic file notifications are available, that is, there is no way to apply a notification to an individual file.

Creating file notifications

Creating a placeholder notification, that triggers when file is created:

POST /storage/file/notification
Content-Type: application/xml

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
         ...
   </action>
   <trigger>
      <file>
         <new/>
      </file>
   </trigger>
</NotificationDocument>
VX-16

New file

Resource /storage/file
Parameters -  
Output fileId The id of the new file.
action The string “NEW”.
storageId The id of the storage the file is located on.
shapeId The shapeId of the file, if available.
itemId The id of the item the file is associated with if available.

Notifies when a file is created, or has been discovered.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <file>
            <new/>
        </file>
    </trigger>
</NotificationDocument>

File has changed

Resource /storage/file
Parameters -  
Output fileId The id of the changed file.
action The string “CHANGE”.
storageId The id of the storage the file is located on.
shapeId The shapeId of the file, if available.
itemId The id of the item the file is associated with if available.

Notifies when a file has changed.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <file>
            <change/>
        </file>
    </trigger>
</NotificationDocument>

File has closed

Resource /storage/file
Parameters -  
Output fileId The id of the changed file.
action The string “CLOSE”.
storageId The id of the storage the file is located on.
shapeId The shapeId of the file, if available.
itemId The id of the item the file is associated with if available.

Notifies when a file has been marked as closed in Vidispine.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <file>
            <close/>
        </file>
    </trigger>
</NotificationDocument>

File was deleted

Resource /storage/file
Parameters -  
Output fileId The id of the deleted file.
action The string “DELETE”.
storageId The id of the storage the file is located on.
shapeId The shapeId of the file, if available.
itemId The id of the item the file is associated with if available.

Notifies when a file has been deleted.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <file>
            <delete/>
        </file>
    </trigger>
</NotificationDocument>

File hash has been computed

Resource /storage/file
Parameters -  
Output fileId The id of the hashed file.
action The string “HASH”.
storageId The id of the storage the file is located on.
shapeId The shapeId of the file, if available.
itemId The id of the item the file is associated with if available.

Notifies when a file has been hashed.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <file>
            <hash/>
        </file>
    </trigger>
</NotificationDocument>

Quota triggers

Quota triggers can be set to send a notification when a quota has been exceeded, when a quota is added, and when a quota is deleted.

Create quota notifications

Creating a placeholder notification, that triggers when a quota is exceeded:

POST /quota/notification
Content-Type: application/xml

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
         ...
   </action>
   <trigger>
      <quota>
         <warning/>
      </quota>
   </trigger>
</NotificationDocument>
VX-16

Quota warning

Resource /quota
Parameters -  
Output ruleId The id of the quota rule
notificationTrigger The string “WARNING”.
itemLimit The item limit set in the triggering rule.
storageLimit The storage limit set in the triggering rule.
itemUsage The current usage in items
storageUsage The current usage on storages.

Notifies when a quota has been exceeded.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <quota>
            <warning/>
        </quota>
    </trigger>
</NotificationDocument>

Quota create

Resource /quota
Parameters -  
Output ruleId The id of the quota rule
notificationTrigger The string “CREATE”.
itemLimit The item limit set in the triggering rule.
storageLimit The storage limit set in the triggering rule.
itemUsage The current usage in items
storageUsage The current usage on storages.

Notifies when a quota has been created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <quota>
            <created/>
        </quota>
    </trigger>
</NotificationDocument>

Quota delete

Resource /quota
Parameters -  
Output ruleId The id of the quota rule
notificationTrigger The string “DELETE”.
itemLimit The item limit set in the triggering rule.
storageLimit The storage limit set in the triggering rule.
itemUsage The current usage in items
storageUsage The current usage on storages.

Notifies when a quota has been exceeded.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <quota>
            <delete/>
        </quota>
    </trigger>
</NotificationDocument>

Deletion lock triggers

New in version 4.15.

Changed in version 5.1.

The deletion-lock triggers now contains the entityType and entityId that the lock applies to.

Lock create

Resource .../deletion-lock
Parameters -  
Output newLockId The id of the newly created lock.
newExpiry The expiration time of the lock.
entityType The type of the entity that the created lock applies to.
entityId The entity id that the created lock applies to.

Triggered when a new deletion lock is created.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
         ...
   </action>
   <trigger>
      <deletionLock>
         <create/>
      </deletionLock>
   </trigger>
</NotificationDocument>

Lock modify

Triggered when a deletion lock has been modified.

Resource .../deletion-lock
Parameters -  
Output oldLockId The id of the lock that was modified.
oldExpiry The old expiration time of the lock.
newLockId The id of the lock that was modified.
newExpiry The new expiration time of the lock.
entityType The type of the entity that the modified lock applies to.
entityId The entity id that the modified lock applies to.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
      <deletionLock>
         <modify/>
      </deletionLock>
    </trigger>
</NotificationDocument>

Lock delete

Resource .../deletion-lock
Parameters -  
Output oldLockId The id of the lock that was deleted.
oldExpiry The expiration time of that lock.
entityType The type of the entity that the deleted lock applied to.
entityId The entity id that the deleted lock applied to.

Triggered when a deletion lock has been deleted, and the change has propagated to all the sub entities.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <deletionLock>
            <delete/>
        </deletionLock>
    </trigger>
</NotificationDocument>

Lock expired

Resource .../deletion-lock
Parameters -  
Output oldLockId The id of the lock that expired.
oldExpiry The expiration time of that lock.
entityType The type of the entity that the expired lock applied to.
entityId The entity id that the expired lock applied to.

Triggered when a lock has expired.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <deletionLock>
            <expire/>
        </deletionLock>
    </trigger>
</NotificationDocument>

Effective lock change

Resource .../deletion-lock
Parameters -  
Output oldLockId The id of the previous effective lock.
oldExpiry The old expiration time of the old lock.
newLockId The id of the new effective lock.
newExpiry The expiration time of the new lock.
entityType The type of the entity that the effective lock applies to.
entityId The entity id that the effective lock applies to.

Triggered when an effective lock on the entity has changed.

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        ...
    </action>
    <trigger>
        <deletionLock>
            <effective/>
        </deletionLock>
    </trigger>
</NotificationDocument>