Notifications¶
Most URLs that acts as resources in the RESTful API are used as resources in the notification framework as well.
In the following reference, {notification-entity}
is one of the following:
/item
/collection
/job
/storage
/storage/file
/quota
/group
/document
/deletion-lock
In the following reference, {notification-resource}
is one of the following:
{notification-entity}/notification
/notification
Where the single notification endpoint is the placeholder-entity. To read and write these placeholder notifications the releveant role must be used, in this case the placeholder read/write roles.
In the following reference, {notification-entity-read-role}
is one of the following:
_{notification-entity}_notification_read
_placeholder_notification_read
In the following reference, {notification-entity-write-role}
is one of the following:
_{notification-entity}_notification_write
_placeholder_notification_write
- Applying notifications to entire resources
- Applying notifications to specific entities
- Retrieve all notifications that exists for a particular entity
- Create a new notification that is applied to a particular entity
- Deletes all notifications that exists within an entire resource
- Retrieve a particular notification
- Remove a particular notification
- Change a particular notification on a whole entity
- Change a particular notification on a specific entity
Changed in version 4.8: The /document notification resource was added.
Changed in version 4.17: The placeholder notification resource was added.
Applying notifications to entire resources¶
Notifications can be applied to entire resources. For example if used on the item resource, then events that occur to any item will potentially trigger the event.
Retrieve all notifications that exists within an entire resource¶
-
GET
{notification-resource}/
¶ Lists URIs to all notifications that exists within the given resource.
Produces: - application/xml, application/json – A URIListDocument containing URIs to all available notifications.
- text/plain – A CRLF-delimited list of URIs.
Role: {notification-entity-read-role}
Example¶
GET /item/job/notification
Accept: application/xml
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<uri>VX-573</uri>
</URIListDocument>
Create a new notification that is applied to the entire resource¶
-
POST
{notification-resource}/
¶ Adds a notification that is applied to an entire resource
Accepts: - application/xml, application/json – NotificationDocument
Produces: - application/xml, application/json – URIListDocument
- text/plain – The id of the notification.
Role: {notification-entity-write-role}
Example¶
Create a notification that triggers when PLACEHOLDER_IMPORT job finish.
POST /item/job/notification
Content-Type: application/xml
<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<action>
<http>
<url>http://10.10.0.3/notify-job</url>
<timeout>5</timeout>
<retry>3</retry>
<method>POST</method>
<contentType>application/xml</contentType>
</http>
</action>
<trigger>
<job>
<finished/>
<filter>
<type>PLACEHOLDER_IMPORT</type>
</filter>
</job>
</trigger>
</NotificationDocument>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<uri>VX-573</uri>
</URIListDocument>
Deletes all notifications that exists within an entire resource¶
-
DELETE
{notification-resource}/
¶ Removes all notifications that exists within the specified resource.
Status Codes: - 200 OK – Everything went well.
Role: {notification-entity-write-role}
Retrieve a particular notification¶
-
GET
{notification-resource}/
(notification-id)¶ Retrieves a particular notification with the given id.
Status Codes: - 404 Not found – No notification with that id exists in that resource.
Produces: - application/xml, application/json – NotificationDocument
Role: {notification-entity-read-role}
Example¶
Retrieve job notification VX-573.
GET /job/notification/VX-573
Accept: application/xml
<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<action>
<http>
<url>http://10.10.0.3/notify-job</url>
<timeout>5</timeout>
<retry>3</retry>
<method>POST</method>
<contentType>application/xml</contentType>
</http>
</action>
<trigger>
<job>
<finished/>
<filter>
<type>PLACEHOLDER_IMPORT</type>
</filter>
</job>
</trigger>
</NotificationDocument>
Remove a particular notification¶
-
DELETE
{notification-resource}/
(notification-id)¶ Removes a particular notification with the given id.
Status Codes: - 200 OK – The notification was successfully removed.
- 404 Not found – No notification with that id exists in that resource.
Role: {notification-entity-write-role}
Applying notifications to specific entities¶
Notifications can also be applied on specific entities, for example a single job.
Note
These resources do not apply for the /storage/file
endpoint.
Retrieve all notifications that exists for a particular entity¶
-
GET
{notification-entity}/
(entity-id)/notification/
¶ Lists URIs to all notifications that exists for a given entity.
Produces: - application/xml, application/json – A URIListDocument containing URIs to all available notifications.
- text/plain – A CRLF-delimited list of URIs.
Role: {notification-entity-read-role}
Create a new notification that is applied to a particular entity¶
-
POST
{notification-entity}/
(entity-id)/notification/
¶ Adds a notification to the given entity.
Accepts: - application/xml, application/json – NotificationDocument
Produces: - application/xml, application/json – URIListDocument
- text/plain – The id of the notification.
Role: {notification-entity-write-role}
Deletes all notifications that exists within an entire resource¶
-
DELETE
{notification-entity}/
(entity-id)/notification/
¶ Removes all notifications that exists within the specified entity.
Status Codes: - 200 OK – Everything went well.
Role: {notification-entity-write-role}
Retrieve a particular notification¶
-
GET
{notification-entity}/
(entity-id)/notification/
(notification-id)¶ Retrieves a particular notification with the given id.
Status Codes: - 404 Not found – No notification with that id exists in that resource.
Produces: - application/xml, application/json – NotificationDocument
Role: {notification-entity-read-role}
Remove a particular notification¶
-
DELETE
{notification-entity}/
(entity-id)/notification/
(notification-id)¶ Removes a particular notification with the given id.
Status Codes: - 200 OK – The notification was successfully removed.
- 404 Not found – No notification with that id exists in that resource.
Role: {notification-entity-write-role}
Change a particular notification on a whole entity¶
-
PUT
{notification-resource}/
(notification-id)¶ Change the action and/or trigger of the notification that exists within the given resource.
Accepts: - application/xml, application/json – NotificationDocument
Produces: - application/xml, application/json – NotificationDocument
Role: {notification-entity-write-role}
Status Codes: - 200 OK – The notification was successfully changed.
- 404 Not found – No notification with that id exists in that resource.
Change a particular notification on a specific entity¶
-
PUT
{notification-entity}/
(entity-id)/notification/
(notification-id)¶ Change the action and/or trigger of the notification that exists within the given resource.
Accepts: - application/xml, application/json – NotificationDocument
Produces: - application/xml, application/json – NotificationDocument
Role: {notification-entity-write-role}
Status Codes: - 200 OK – The notification was successfully changed.
- 404 Not found – No notification with that id exists in that resource.
Example¶
GET /item/VX-43/notification/VX-573
<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<action>
<http>
<url>http://10.10.0.3/notify-job</url>
<timeout>5</timeout>
<retry>3</retry>
<method>POST</method>
<contentType>application/xml</contentType>
</http>
</action>
<trigger>
<job>
<finished/>
<filter>
<type>PLACEHOLDER_IMPORT</type>
</filter>
</job>
</trigger>
</NotificationDocument>
PUT /item/VX-43/notification/VX-573
Content-Type: application/xml
<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<action>
<http>
<url>http://service.example.com/notify</url>
<timeout>5</timeout>
<retry>3</retry>
<method>POST</method>
<contentType>application/xml</contentType>
</http>
</action>
<trigger>
<job>
<finished/>
<filter>
<type>TRANSCODE</type>
</filter>
</job>
</trigger>
</NotificationDocument>
GET /item/VX-43/notification/VX-573
<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<action>
<http>
<url>http://service.example.com/notify</url>
<timeout>5</timeout>
<retry>3</retry>
<method>POST</method>
<contentType>application/xml</contentType>
</http>
</action>
<trigger>
<job>
<finished/>
<filter>
<type>TRANSCODE</type>
</filter>
</job>
</trigger>
</NotificationDocument>