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

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:
Produces:
  • application/xml, application/jsonURIListDocument
  • 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:
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:
Produces:
  • application/xml, application/jsonURIListDocument
  • 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:
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:
Produces:
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:
Produces:
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>