Notification reference [VC 21.3.1 GEN]

Most URLs that acts as resources in the 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
/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 relevant 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

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.

List 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

NONE

GET /item/job/notification
Accept: application/xml

HTML/XML

<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-573</uri>
</URIListDocument>

Create a 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.

NONE

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>

HTML/XML

<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-573</uri>
</URIListDocument>

Delete 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 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.

NONE

GET /job/notification/VX-573
Accept: application/xml

HTML/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>

Delete a 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.

These resources do not apply for the /storage/file endpoint.

List 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 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}

Delete all notifications that is applied to a particular entity

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

Delete a 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

NONE

GET /item/VX-43/notification/VX-573

HTML/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>

NONE

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>

HTML/XML

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>