Actions

An action is what will be done when a notification is triggered. The action taken is that a message will be sent to either a HTTP, EJB, Amazon SQS (New in 4.7.) or JMS recipient, or being processed by a JavaScript.

An action can be sent either synchronously or asynchronously. The behaviour of synchronous vs. asynchronous notifications differ somewhat between the different action types, and is explained in the reference below. In general, however, synchronous notifications are sent from the same thread from where it was triggered, and asynchronous notifications are sent in a separate thread, allowing processing to continue right away after triggering.

Asynchronous delivery

Asynchronous notifications are delivered by multiple threads, one thread per notification endpoint (HTTP endpoint, EJB method, JMS queue, SQS endpoint or script.) This can be customized by defining a thread group name for the actions. Notifications with the same thread group name will then be delivered by the same thread.

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        <http synchronous="false" group="app_notifications">
            ...
        </http>
    </action>
    <trigger>
        ...
    </trigger>
</NotificationDocument>

Changed in version 4.6: In prior versions, all asynchronous notifications were delivered sequentially by a single thread.

HTTP

Action parameters

The details of the HTTP action are set in the action element in the notification definition.

url
The URL to the HTTP resource. Mandatory parameter. (New in 4.1.4.) Basic auth username and password is supported. (http://user:password@host...)
method
The HTTP method to use, POST and PUT are supported. Mandatory parameter.
timeout
The timeout (in seconds) before assuming network failure. Use 0 or none to specify that there is no timeout. Mandatory parameter.
retry
The number of retries. Mandatory parameter.
synchronous
See below. Mandatory parameter.
contentType
The content type of the message sent to the destination. For supported values, see below. Optional value.

Request body in notification message

The message in the request body depends on contentType:

text/plain
Default format. A CRLF-delimited list with tab-separated rows that consist of the key followed by its values.
application/xml
SimpleMetadataDocument
application/json
SimpleMetadataDocument

Error-handling logic

The output depends on the content-type set in the action definition. The way the HTTP action works depends on if it is setup as synchronous or asynchronous. Below is a table that shows the differences.

Response Synchronous Asynchronous
Connection timeout Stops Will retry for a specified number of times
Receives HTTP code 2xx Continues Continues
Receives HTTP code 4xx Stops Stops
Receives HTTP code 5xx Stops Will retry for a specified number of times

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <action>
        <http synchronous="false">
            <retry>3</retry>
            <contentType>application/json</contentType>
            <url>http://example.com/notify</url>
            <method>POST</method>
            <timeout>5</timeout>
        </http>
    </action>
    <trigger>
        ...
    </trigger>
</NotificationDocument>

EJB

Methods in EJBs must have the following signature and should not throw any exceptions. A null value as a response will always be regarded as that the message is not accepted and the action should stop. Note that returning the empty string is not the same as returning null, and will just be treated as an empty response.

public java.lang.String methodName(java.util.Map<java.lang.String, java.util.List<java.lang.String>>)

Note

JNDI names must be prefixed by vidibrain (case insensitive). The interface name must match the class named plus the postfix Remote.

Action parameters

The details of the EJB action are set in the action element in the notification definition.

bean
The JNDI name of the bean. Mandatory parameter.
method
The method name of the bean. See above for method signature. Mandatory parameter.
data
(New in 4.13.) Key-value pairs with additional parameters that are passed to the bean method in the java.util.Map<> parameter. The keys in the map are the keys in the NotificationDocument prefixed by data/ (e.g. the key uri in the NotificationDocument will get the key data/uri in the map).
synchronous
See below. Mandatory parameter.

Error-handling logic

Response Synchronous Asynchronous
Could not find the bean Stops Continues
Could not find the method Stops Continues
Returns null value Stops Continues
Returns non-null value Continues Continues

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
      <ejb synchronous="true">
         <bean>vidibrain.beans.MyBeanRemote</bean>
         <method>myMethod</method>
         <data>
            <key>param1</key>
            <value>value1</value>
         </data>
         <data>
            <key>param2</key>
            <value>value2</value>
         </data>
         <data>
            <key>param3</key>
            <value>value3</value>
         </data>
      </ejb>
   </action>
   <trigger>
      ...
   </trigger>
</NotificationDocument>

JMS

JMS queues can be notified. While it is possible to call them in asynchronous mode, there is not much point in doing so. This is since messages on JMS queues always are treated asynchronously. Below a table can be seen over what the outcome is based on the different responses.

Action parameters

The details of the EJB action are set in the action element in the notification definition.

queueFactory
The JNDI name of the JMS factory. Mandatory parameter.
queue
The JNDI name of the JMS queue. Mandatory parameter.
synchronous
See below. Mandatory parameter.
contentType
(New in 4.2.1.) The content type of the message sent to the destination. For supported values, see below. Optional value.

Notification message

The JMS message depends on contentType:

application/x-java-serialized-object
Default format. An ObjectMessage with a Map<String, List<String> > object.
text/plain
A TextMessage with a CRLF-delimited list with tab-separated rows that consist of the key followed by its values.
application/xml
A TextMessage with SimpleMetadataDocument
application/json
A TextMessage with SimpleMetadataDocument

Error-handling logic

Response Synchronous Asynchronous
Could not find the queue Stops Continues
Could not find the queue factory Stops Continues

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
      <jms synchronous="true">
         <queueFactory>VidibrainQueueFactory</queueFactory>
         <queue>VidibrainQueue</queue>
      </jms>
   </action>
   <trigger>
      ...
   </trigger>
</NotificationDocument>

JavaScript

New in version 4.2.

With a notification with a JavaScript action, it is possible to script actions directly in Vidispine. All of the output values (see below), are mapped to its respective variable in the JavaScript environment, unless if it is a multi-value list, then it is mapped to name + List. All output values are also available in the variable data, which is a Map from the id to a List of strings.

Action parameters

The details of the EJB action are set in the action element in the notification definition.

script
The actual JavaScript. Mandatory parameter.
synchronous
See below. Mandatory parameter.

Error-handling logic

Response Synchronous Asynchronous
Errors (exceptions) in the execution Stops Continues

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <action>
      <javascript>
         <script>
             logger.log("itemId: "+itemId+", "+data);
         </script>
      </javascript>
   </action>
   <trigger>
      ...
   </trigger>
</NotificationDocument>

Amazon SQS

New in version 4.7.

endpoint
The endpoint of the SQS. Mandatory parameter.
queue
The queue name. Mandatory parameter.
accessKey

AWS access key. Note that the secret field should not be empty if this field is set.

Optional parameter.

secret

If accessKey is set, this field should be the AWS secret key. Otherwise, it should be the alias of the secret that contains the credentials to SQS.

Optional parameter.

synchronous

Mandatory parameter.

More info about synchronous/asynchronous notification.

contentType
The content type of the message sent to the destination. For supported values, see below. Optional value.

Request body in notification message

The message in the request body depends on contentType:

text/plain
Default format. A CRLF-delimited list with tab-separated rows that consist of the key followed by its values.
application/xml
SimpleMetadataDocument
application/json
SimpleMetadataDocument

Example

<NotificationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <action>
    <sqs synchronous="false">
      <contentType>application/xml</contentType>
      <endpoint>sqs.eu-west-1.amazonaws.com</endpoint>
      <queue>notification</queue>
      <secret>aws</secret>
    </sqs>
  </action>
  <trigger>
    ...
  </trigger>
</NotificationDocument>