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, Java, Amazon SQS, Amazon SNS 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, Java method, JMS queue, SQS endpoint, SNS 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>

HTTP

Performs a HTTP request.

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

Java

Invokes a Java class method.

Methods in the Java classes 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

For classes to be discovered, Spring Context Indexer must be used to index the components in any custom JAR files exposed to Vidispine.

Note

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

Changed in version 5.0: These are now plain Java class method invocations, as Vidispine no longer runs in an EJB container.

Action parameters

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

Note

For legacy reasons, the name of the element is ejb.

bean
The fully qualified name of the class. Mandatory parameter.
method
The method name of the class. See above for method signature. Mandatory parameter.
data
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

Sends a JMS message.

When running a standalone ActiveMQ instance, it is possible to send notifications to any queue that has been set up there. 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 JMS action are set in the action element in the notification definition.

queue
The JNDI name of the JMS queue. 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.

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">
         <queue>MyNotificationQueue</queue>
      </jms>
   </action>
   <trigger>
      ...
   </trigger>
</NotificationDocument>

JavaScript

Executes a JavaScript.

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

It is possible to send a message to Amazon SQS. Both standard and FIFO queues are supported.

New in version 5.2: Support for FIFO queues added.

Prerequisites

An SQS queue must first be created to receive the messages. In order to send notifications to the queue, the user (as defined by the accessKey in the NotificationDocument) must have the permissions:

  • sqs:SendMessage
  • sqs:GetQueueUrl

New in version 21.3: Support for IAM roles added.

If a role is being used, the role must have the required permissions, and the user must have permission to assume the role (sts:AssumeRole).

SQS parameters

The SQS notification can be configured using the following fields and attributes of the NotificationDocument:

queue

The queue name. For FIFO queues the name has to end with .fifo.

Mandatory parameter.

endpoint

The endpoint of the SQS.

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.

Optional parameter.

roleArn

The roleArn to define the IAM role to use, if using IAM role.

Optional parameter.

roleSessionName

The role session name, if using IAM role.

Optional parameter. VidiCore will assign a name if not set.

roleExternalId

The Amazon externalId to use if using IAM role.

Optional parameter. Required only if roleArn is set and the specified role is configured with an sts:ExternalId condition

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.

messageGroupId

The id that specifies that a message belongs to a specific message group. If you don’t need multiple ordered message groups, specify the same message group ID for all your messages.

For FIFO queues this parameter is mandatory. For standard queues this parameter is forbidden

New in version 5.2.

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>

Amazon SNS

New in version 5.2.

Sends a message to Amazon SNS.

Prerequisites

An SNS topic must first be created to receive the notifications. In order to send SNS notifications, the user (as defined by the accessKey in the NotificationDocument) must have the permission:

  • sns:Publish.

New in version 21.3: Support for IAM roles added.

If a role is being used, the role must have the required permissions, and the user must have permission to assume the role (sts:AssumeRole).

SNS parameters

The SNS notification can be configured using the following fields and attributes of the NotificationDocument:

topic
The topic ARN. Mandatory parameter.
endpoint

The endpoint of the SNS.

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.

Optional parameter.

roleArn

The roleArn to define the IAM role to use, if using IAM role.

Optional parameter.

roleSessionName

The role session name, if using IAM role.

Optional parameter. VidiCore will assign a name if not set.

roleExternalId

The Amazon externalId to use if using IAM role.

Optional parameter. Required only if roleArn is set and the specified role is configured with an sts:ExternalId condition

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>
    <sns synchronous="false">
      <contentType>application/xml</contentType>
      <endpoint>sns.eu-west-1.amazonaws.com</endpoint>
      <topic>arn:aws:sns:eu-west-1:#############:sns-topic-name</topic>
      <secret>aws</secret>
    </sns>
  </action>
  <trigger>
    ...
  </trigger>
</NotificationDocument>