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 executed in the same transaction as the event, an error that should occur when running the script would cause the transaction to be rollbacked.

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.

List of the execution context support variables for callback scripts

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.