Actions [VC 21.3 GEN]

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.

HTML/XML

<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

HTML/XML

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

JAVA

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

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

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.

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

HTML/XML

<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

HTML/XML

<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

HTML/XML

<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

HTML/XML

<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

HTML/XML

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