Notifications

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

GET /item/job/notification
Accept: application/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:
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>

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

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.

Note

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