Managing events (callbacks)
Synchronous and Asynchronous callbacks¶
Since version 1.5, Content Script supports the definition of Event Callbacks: in response to specific actions performed on Content Server, it is possible to execute one or more Content Scripts.
The callbacks can be:
-
synchronous: the script is executed within the same transaction as the triggering action. Synchronous callbacks are configured through the CSSynchEvents container.
-
asynchronous: the triggering action completes normally. The callback script is executed later on. Asynchronous callbacks are configured in the CSEvents container.
Since synchronous callbacks are performed in the same transaction as the event, any errors that occur during script execution will cause the transaction to roll back.
Performance
Since synchronous callbacks are executed in the same transaction as the event, make sure that any action performed by the script requires a reasonable time span for execution. Otherwise, the user experience could be affected negatively.
The definition of Content Script callbacks is based on a convention over configuration approach. In order to register a new callback, a script should be placed somewhere in a nested container structure in the CSSynchEvents or CSEvents container, following a specific naming convention.
The first level under the container indicates the object or object subtype to which the callbacks are bound.
The naming convention is one of the following:
-
D<nodeID> -
S<subtype>
where nodeID identifies the node unequivocally and subtype identifies a specific object subtype on Content Server.
Examples:
D2000 will intercept events on the Enterprise Workspace
S144 will intercept event on Document type objects (subtype: 144)
The second level should be once again a container and specifies the event type. The name of this container should be one of:
-
ChildNodeAdded
-
ChildNodeCreate
-
NodeAddVersion
-
NodeAddVersionPre
-
NodeCopy
-
NodeCreate
-
NodeCreatePre
-
NodeMove
-
NodeRename
-
NodeUpdate
-
NodeUpdateCategories
Inside the Event Type container it is possible to place one or more Content Scripts that will be invoked when the callback is triggered.
The Module Suite Administration pages feature a Manage Callbacks tool that can be used to verify, at any time, all the callbacks that are bound to a specific object or subtype.
In the following tables we present a summary of the supported Events and the information regarding the variables that are injected in the Execution Context, automatically by the framework, for each event. These variables can be useful to implement the required business logic within the Script.
| Event Name | Execution Context Param | Type | Description |
|----------------------|-------------------------|--------------------|-----------------------------------------------------------------------------|
| All | callbackID | String | The CSEvent Name (NodeAddVersion, NodeUpdateCategories, etc) |
| | eventSourceID | Integer | The dataid of the node that triggered the event |
| NodeAddVersion | nodeID | Integer | The document that has received the new version |
| NodeAddVersionPre | nodeID | Integer | The document that has received the new version |
| NodeUpdateCategories | nodeID | Integer | The updated node’s id |
| | addedCategories | List<String> | The list of added categories |
| | deletedCategories | List<String> | The list of removed categories |
| | changes | ChangeAssoc | The list of applied attributes changes. (SEE THE TABLE BELOW FOR DETAILS) |
| NodeCopy | nodeID | Integer | The id of the node that has been copied |
| | newNodeID | Integer | The newly created node’s id |
| ChildNodeAdded | nodeID | Integer | The id of the node where a new content has been added |
| | newNodeID | Integer | The newly created node’s id |
| NodeCreate | newNodeID | Integer | The newly created node’s id |
| NodeCreatePre | newNodeID | Integer | The newly created node’s id |
| ChildNodeCreate | nodeID | Integer | The id of the node where a new content has been added |
| | newNodeID | Integer | The newly created node’s id |
| NodeMove | nodeID | Integer | The moved node’s id |
| NodeRename | nodeID | Integer | The renamed node’s id |
| | oldName*Can be null* | String | The previous node’s name |
| | newName | String | The current node’s name |
| NodeUpdate | nodeID | Integer | The updated node’s id |
The following table is related to the structure of the **ChangeAssoc**
object, necessary to manage **NodeUpdateCategories** type events.
| Property name | Type | Description
|---------------|---------|--------------------------------------------------------------------------------------------------------------------------|
| attributePath | List | The path of the modified attribute inside the category.
{“Name”,0}: represents the path to the first value of the attribute “Name”
{“Name”,1}: represents the path to the second value of the attribute “Name”
{“Addresses”, 2, “ZipCode”, 0}: represents the path to the first value of the attribute ZipCode in the third
occurrence of the Set attribute Addresses |
| oldValue | Dynamic | The previous attribute’s value |
| newValue | Dynamic | The present attribute’s value |
| categoryName | String | The category name |
InterruptCallbackException - transaction roll-backed¶
There are cases in which you might want your synchronous callback to cause the roll-back of the original event transaction (to prevent its completion), e.g. you implemented a synch-callback triggered by the NodeCreate event and you want to use it to ensure that the node that is going to be created respects some specific business rule, for example, it's a PDF document. In this cases, you can just raise an un-catched InterruptCallback exception from within your callback script.
E.g.
log.error("Running ${self.parent.parent.name}:${self.parent.name}:${self.name} for $nodeID")
out << "This is the mother of all failures..."
throw new InterruptCallbackException("New Callback Exception...")
Returning meaningful messages to your users
To return a message to your users you have just to add an output statement to your script.