Jama Connector 26.3
Jama Connector Help

# 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 Jama 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 Jama Connector faster than they can be processed.

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

Jama 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

1. Stop Jama Connector.
2. Open the Jama Connector configuration file in a text editor.

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

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

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

6. Save and close the configuration file. You must restart Jama 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.

Copyright 2026 Open Text
Version 26.3 | Last updated July 2026

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: Knowledge Discovery Jama Connector 26.3

Topic Title: Asynchronous Action Event Handlers