Event Manager configuration settings

Edit online

Draft comment:
This topic only applies to BAW, and is located in the BAW repository. Last updated on 2025-03-13 12:15

To understand how the IBM® Business Automation Workflow Event Manager works, review the configuration properties.

Do not directly edit the 80EventManager.xml file; use the 100Custom.xml for any required configuration changes. For information about changing configuration properties, see Creating a 100Custom.xml configuration file.

Task loader properties

The task loader is a dedicated thread of an Event Manager instance that loads Event Manager tasks into in-memory queues. The default parameter settings of the task loader are optimized for most usage patterns. Typically there is no need to tune any of these parameters.

<loader-long-period>15000</loader-long-period>: Specified milliseconds between major loads of the task loader. For every task loader long period, the Event Manager looks at each synchronous and asynchronous queue that it has access to and fills them to capacity.
<loader-short-period>2000</loader-short-period>: Specifies milliseconds between minor loads of the task loader. For every task loader short period, the Event Manager looks through each of the queues that the Event Manager filled to capacity during the last short or long period, and fills them to capacity. Do not change this setting.
<loader-advance-window>15000</loader-advance-window>: Specifies milliseconds before execution that the task loader can acquire a task For scheduled tasks, this parameter specifies how far in advance the Event Manager looks for tasks. Recommendation: set this property as equal to <loader-long-period>. The value is set to 15000 by default, which is the same as the <loader-long-period> value.
<kick-on-schedule>true</kick-on-schedule>: If set to true, the task loader is kicked into an immediate major load anytime a new task is scheduled. Newly scheduled tasks are executed almost immediately. Do not change this setting.

Queue capacity properties

The Event Manager queues are used for scheduling Event Manager tasks. When you define an undercover agent in Process Designer, you specify whether to use a particular synchronous queue or the asynchronous undercover agent (UCA) queue.

<sync-queue-capacity>10</sync-queue-capacity>: Specifies the maximum number of Event Manager tasks that are loaded into memory for each synchronous UCA queue.
<async-queue-capacity>10</async-queue-capacity>: Specifies the number of Event Manager tasks that are loaded into memory for the asynchronous UCA queue.
<bpd-queue-capacity>40</bpd-queue-capacity>: Specifies the number of Event Manager tasks that are loaded into memory for the process queue, which is an asynchronous queue that covers Event Manager tasks that execute processes, timers, system tasks, and decision tasks.
Tip: To optimize throughput and scaling, start with a bpd-queue-capacity of 10 per physical processor core (for example, 40 for a 4-processor core configuration), with a maximum value of 80.
<system-queue-capacity>10</system-queue-capacity>: Specifies the number of Event Manager tasks that are loaded into memory for the Event Manager internal system queue, for example, blackout calendar update tasks.

When the server starts, the value of the async-queue-capacity setting is checked and compared to the value of the maxConnections setting for the datasource. The value of the async-queue-capacity setting is automatically adjusted if the condition specified in the following formula is met:

maxConnections < 2 * (async-queue-capacity + bpd-queue-capacity + system-queue-capacity) + 5 synchronous queues

If the value of the async-queue-capacity setting is adjusted, warnings are written to the server logs. For example:

CWLLG2156W: The database connection pool size (200) of the Process Server data source might be too small.
CWLLG2236W: The configured 'async-queue-capacity' parameter of '22900' has been changed to '5'.
CWLLG2236W: The configured 'bpd-queue-capacity' parameter of '22900' has been changed to '98'.
CWLLG2236W: The configured 'system-queue-capacity' parameter of '22900' has been changed to '5'

Use the following guidelines to help calculate or adjust the value of the async-queue-capacity setting:

If the connection pool is large enough, use the values that are currently configured.
If the connection pool is too small, choose one of the following options:
- If the queue capacity is less than or equal to the specified minimum value, only print a warning.
- If the queue capacity is greater than the specified minimum value, adjust the queue capacity value but ensure that the value is not less than the minimum specified value.

Note: Adjusted values for the async-queue-capacity setting are not written to the TeamWorksConfiguration.running.xml file. The file would still contain the original values.

Thread pool properties

The thread pool properties designate the worker threads that are used by Event Manager.

<use-was-work-manager>true</use-was-work-manager>

Specifies whether the WebSphere® Application Server Work Manager is designated for the thread pool. In on-premises environments, it is set to true and in container environments, it is set to false. This property is not intended for customization, as altering it may lead to unexpected issues.

<use-managed-executor-service>true</use-managed-executor-service>

Specifies whether the Liberty executor service is designated for the thread pool. In on-premises environments, it is set to false and in container environment, it is set to true. This property is not intended for customization, as altering it may lead to unexpected issues.

<was-work-manager>wm/BPMEventManagerWorkManager</was-work-manager>

Specifies the WebSphere Application Server Work Manager that is used. This property is for on-premises environment only. The Growable attribute in the Work Manager must be set to true. This property is not intended for customization.

<managed-executor-service>concurrent/execSvcForEM</managed-executor-service>

This property is for container environment only. This property is not intended for customization.

Note:

Throttling the Event Manager is done by decreasing the queue capacity, such as bpd-queue-capacity, async-queue-capacity, system-queue-capacity, and sync-queue-capacity.
The total available IBM Business Automation Workflow database connections in the application server connection pool should be at least the sum of the maximum number of threads in all thread pools in the server. This includes the web container and event manager. The maximum number of threads allowed by the Event Manager is equals to the sum of the queue capacity of all Event Manager queues.

<re-execute-limit>5</re-execute-limit>

Specifies maximum number of times the Event Manager tries to execute a task if it ends with an exception.

Tip: Event Manager tasks that fail and reach the re-execute-limit are put on hold. The tasks are retained in the database, but they are flagged to be on hold and rescheduled to be run in the future when the BPMReplayOnHoldEMTasks command is run.

<em-thread-reuse>false</em-thread-reuse>

The default value of em-thread-reuse is true. When new Event Manager tasks are scheduled during the current task execution, this setting avoids the Event Manager thread switch within the specified time period from thread-reuse-duration for following scenarios:

Event Manager tasks associated with a process instance, but Optimize Execution for Latency is not selected in the process.
All Event Manager tasks are not associated to any process instance.

Heartbeat properties

A heartbeat is a dedicated thread of an Event Manager instance that periodically signals that the Event Manager instance is still running.

<heartbeat-period>30000</heartbeat-period>: Specifies milliseconds between heartbeats. Do not change this setting. If the setting is changed, it must be less than the <heartbeat-expiration> divided by 4.
<heartbeat-expiration>240000</heartbeat-expiration>: Specifies milliseconds for a heartbeat to expire. Do not change this setting. If the setting is changed, it must be larger than 4 times the <heartbeat-period>.

Reaper property

A reaper is a dedicated thread for each cluster member that checks if there are Event Manager tasks owned by expired Event Manager instances. If it finds those tasks, the reaper resets the state to scheduled and the ownership to unassigned. Therefore, other Event Manager instances pick up the work.

<reaper-period>120000</reaper-period>: Specifies milliseconds between activity of expired Event Manager reaper. Do not change this setting.

Other Event Manager properties

<start-paused>false</start-paused>: Allows the Event Manager to be started in paused state. The Event Manager can be resumed using the Event Manager monitor in the Process Admin Console.
<name>EM instance name</name>: Specifies name of the Event Manager instance. The name is used in Event Manager monitor in the Process Admin Console.