Asynchronous Action Event Handlers

Some of the actions that you can send to Knowledge Discovery are asynchronous (fetch for connectors, or process for Media Server are just two examples). Asynchronous actions do not run immediately, but are added to a queue. This means that the person or application that sends the action does not receive an immediate response. However, you can configure Box Connector to call an event handler when an asynchronous action starts, finishes, or encounters an error.

You might use an event handler to:

Return data about an event back to the application that sent the action.
Write event data to a text file, to log any errors that occur.

You can also use event handlers to monitor the size of asynchronous action queues. If a queue becomes full this might indicate a problem, or that applications are making requests to Box Connector faster than they can be processed.

Box Connector can call an event handler for the following events.

OnStart	Called when an asynchronous action starts processing.
OnFinish	Called when an asynchronous action finishes processing successfully.
OnError	Called when an asynchronous action fails and cannot continue.
OnErrorReport	Called when an asynchronous action encounters an error, but the action continues. NOTE: The `OnErrorReport` event is used only by the following components: Exchange Web Service Connector File System Connector IMAP Connector Web Connector
OnQueueEvent	The `OnQueueEvent` handler is called when an asynchronous action queue becomes full, becomes empty, or the queue size passes certain thresholds. A `QueueFull` event occurs when the action queue becomes full. A `QueueFilling` event occurs when the queue size exceeds a configurable threshold (`QueueFillingThreshold`) and the last event was a `QueueEmpty` or `QueueEmptying` event. A `QueueEmptying` event occurs when the queue size falls below a configurable threshold (`QueueEmptyingThreshold`) and the last event was a `QueueFull` or `QueueFilling` event. A `QueueEmpty` event occurs when the action queue becomes empty.

Box Connector supports the following types of event handler:

The HttpHandler sends event data to a URL.
The LuaHandler runs a Lua script. The event data is passed into the script.
The TextFileHandler writes event data to a text file.

Configure an Event Handler

To configure an event handler, follow these steps.

To configure an event handler

Stop Box Connector.
Open the Box Connector configuration file in a text editor.
Set the OnStart, OnFinish, OnError, or OnQueueEvent parameter to specify the name of a section in the configuration file that contains the event handler settings.
- To run an event handler for all asynchronous actions, set these parameters in the [Actions] section. For example:
```
[Actions]
OnStart=NormalEvents
OnFinish=NormalEvents
OnError=ErrorEvents
```
- To run an event handler for a specific action, set these parameters in the [ActionName] section, where ActionName is the name of the action. The following example calls an event handler when the Example action starts and finishes successfully, and uses a different event handler to monitor the queue size:
```
[Example]
OnStart=NormalEvents
OnFinish=NormalEvents
OnQueueEvent=QueueSizeEvents
```
Create a new section in the configuration file to contain the settings for your event handler. You must name the section using the name you specified with the OnStart, OnFinish, OnError, or OnQueueEvent parameter.

In the new section, set the LibraryName parameter.

LibraryName

The type of event handler to use to handle the event.

To write event data to a text file, set this parameter to TextFileHandler, and then set the FilePath parameter to specify the path of the file.
To send event data to a URL, set this parameter to HttpHandler, and then use the HTTP event handler parameters to specify the URL, proxy server settings, credentials, and so on.
To run a Lua script, set this parameter to LuaHandler, and then use the LuaScript parameter to specify the script to run. For information about writing the script, see Write a Lua Script to Handle Events.

For example:

[NormalEvents]
LibraryName=TextFileHandler
FilePath=./events.txt

[ErrorEvents]
LibraryName=HTTPHandler
URL=http://handlers:8080/lo-proxy/callback.htm?

[QueueSizeEvents]
LibraryName=LuaHandler
LuaScript=./handle_queue_events.lua

Save and close the configuration file. You must restart Box Connector for your changes to take effect.

Write a Lua Script to Handle Events

The Lua event handler runs a Lua script to handle events. The Lua script must contain a function named handler with the arguments request and xml, as shown below:

Copy

function handler(request, xml)
    ...
end

request is a table holding the request parameters. For example, if the request was action=Example&MyParam=Value, the table will contain a key MyParam with the value Value. Some events, for example queue size events, are not related to a specific action and so the table might be empty.
xml is a string of XML that contains information about the event.