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).
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.
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>
</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 aMap<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 accessKey. 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 secretKey; Otherwise, it should be the alias of the secret that contains the credentials to SQS.Optional parameter.
More info about storing secrets in Vidispine.
synchronous
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
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>