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. (New in 4.0.) | |
(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 Get 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¶
New in version 4.0.
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. (New in 4.0``.) | |
(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 Get 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>
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¬ification=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¶
New in version 4.0.
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 EJB 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¶
New in version 4.1.
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>