Events and communication with external applications

Events occur as the database changes during processing. Unlike tasks, these events do not follow any timed schedule and happen only as a result of specific changes that occur. The Transaction Server monitors the events and determines whether an event handler is registered for the event. The event handlers are used to do more processing, such as sending information to external applications and starting other Transaction Server processes.

Event handlers are written to handle one or more specific event types. For example, handlers that process batches (ICLs) typically handle more than one type of event. This method allows the handler to start specific processes as batch (ICL) states change or as batches (ICLs) and transmissions are accepted or rejected by different components.

Like tasks, event handlers are configured by using the task scheduler. The scheduler intercepts the events and uses the scheduler XML file, Scheduler.xml, to determine whether a handler is registered for the event. For more information about using the task scheduler, see Configuring the scheduler. For more information about using tasks, see Task scheduler.

Many event handlers are provided with the Transaction Server. These handlers allow the user to configure when certain Transaction Server processes occur, or to configure when another process is notified of the event with a JMS message. Also, you can write your own handlers.

Inter-process communication

The Transaction Server Messaging API allows inter-process communication by using event handlers. The Messaging API delivers messages to message queues that are listened to by various applications. The applications can then act upon the message that was received. The Java™ Messaging Service (JMS) is used as a platform by the Messaging API and as an application-neutral interface between the Transaction Server and any external applications. These messages tie all of the components together and allow the various components to be distributed efficiently based on the particular user work load and needs.

Transaction Server internal event queue

Normally, the message queues are used to notify the Transaction Server about events from FTM applications. To help improve the performance of event processing, the Transaction Server also has an internal event queue that is used for certain events. For example, the events for database changes that are made by the Transaction Server itself are placed on this internal queue instead of an external IBM® MQ queue.

Events that are placed on the internal event queue include events for the situations that are shown in the following list.
  • Database changes that are made by the Transaction Server itself. These changes are typically the result of applyUpdates Messaging API requests from external applications.
  • Overdue trackable items from running the TrackingMonitor task.

Event workers read and process the events and tasks from this internal queue. You can configure the size of the internal event queue by specifying the number of event workers and the maximum number of events that can be on the queue for an event worker. The number of event workers is specified in the numEventWorkers property in the Transaction Server property file. The internalEventQueueThresholdMultiplier property is the maximum number of events that can be on the internal queue for each event worker. The maximum number of entries that can be on the internal event queue is calculated by multiplying the values of these two configuration properties.

If the number of entries on the internal event queue reaches the maximum number of entries, the JMS listeners begin to selectively process messages from the IBM MQ queues. When the internal event queue is full, the listeners skip the applyUpdates requests and leave them on the external queue. Normal processing of the external queue resumes when the number of entries on the internal queue decreases so that it is equal to the number of event workers that are specified.

To monitor the size of the internal event queue and its contents, use the status detail command from the Transaction Server user interface.

Event type descriptions

The following table shows the event types to use when the event handlers are configured in the Transaction Server scheduler XML file.
Table 1. Event types for configuring the event handlers in the scheduler XML file
Event types Description
BatchDelete Occurs when batch (ICL) delete processing is occurring.
BusinessDayPublishEvent Occurs when a topic for a business day was published.
BusinessDayPurgeEvent Occurs when various events in the cycle purge process happen. These events are:
  1. Overall purge started
  2. Individual business day purge started
  3. Individual business day purge ended
  4. Individual business day purge requeued
  5. Overall business day purge ended
BusinessDayStatusChange Occurs when a cycle status is modified in the Transaction Server.
DuplicateDetected Occurs when the Transaction Server receives all Duplicate Detect responses for a batch (ICL).
DuplicateReviewed Occurs when the Transaction Server receives a response from the Duplicate Detect engine that the potential duplicates are reviewed.
EndOfDayCheck Occurs when the check that verifies whether end of day can be run is done and when end of day is run.
EntryUowStateChange Occurs when the unit of work state for an entry is modified in the Transaction Server.
FileTrackingStateChange Occurs when a transmission tracking entry state was changed.
HoldoverBusinessDayEvent Occurs when holdover processing was requested by an operator.
LoadExpectedPresentments Occurs when a business day is activated and expected transmissions are associated with it.
MoveUow Occurs when a unit of work is moved from one business day to another.
OutPresentmentGroupState Occurs when the Transaction Server detects a state change on an outbound transmission.
ParticipantAccountChange Occurs when the status changes for an account of a participant. The status is either open or closed.
ParticipantWindowOverrideColumnChange Occurs when a participant that is defined as a sender overrides the receipt cutoff time for a delivery window.
PaymentAdded Occurs when a new payment is inserted into a unit of work that already completed ingestion.
PaymentDeleted Occurs when a payment is deleted.
PaymentExceptionChange Occurs when the exception status of a transaction changes.
PaymentUpdate Occurs when a payment is updated.
PresentmentColumnChange Occurs when the value of a column in the presentment table changes for a specific batch (ICL). Each batch (ICL) is represented by a row in the presentment table.
PresentmentGroupColumnChange Occurs when the value of a column in the presentment_group table changes for a specific transmission. Each transmission is represented by a row in the presentment_group table.
PresentmentGroupLoaded Occurs when the Transaction Server finishes loading a group of batches (ICLs) from a transmission.
PresentmentGroupStateChange Occurs when the Transaction Server detects that all of the batches (ICLs) in an inbound transmission just reached the same state. This event occurs when either the state for the inbound transmission itself changes or when the last individual batch (ICL) in the transmission reaches the same state as the rest of the batches (ICLs) in the transmission.

An example of this event is when all of the batches (ICLs) in a transmission reach the same state.
PresentmentStateChange Occurs when the Transaction Server detects a state change on a batch (ICL).
ProcessingWindowActivityColumnChange Occurs when a row is changed or inserted in the processing_window_activity table. New rows are inserted into this table as business days are activated.
SegmentColumnChange Occurs when the value of a column in the segment table changes for a specific segment.
SegmentStateChange Occurs when the Transaction Server detects a state change on a segment.
SendEndOfDayFilesEvent Occurs when a send end of day files process is requested by an operator.
ServerShutdown Occurs when the Transaction Server is shutting down.
TaskStateChange Occurs when a Transaction Server task state was changed.
TracerUowStateChange Occurs when the unit of work state of a tracer is modified in the Transaction Server.
TrackedItemOverdue Occurs when an expected event item becomes overdue or late. This event occurs only if the TrackingMonitor is configured as a scheduled task.
TransmissionCreated Occurs when a transmission is created.
UnloadDepositGroup Occurs when an inbound transmission unload operation is requesting work by an external application.
UowLockingChange Occurs when a unit of work is locked for editing.

Event types for the Messaging API event handlers

The following table shows which event types are handled by each Messaging API event handler.
Table 2. Messaging API event handlers and event types
Event handler Event types handled by the handler
AccountUpdateEventHandler ParticipantAccountChange
BatchDeleteEventHandler BatchDelete
BusinessDayPublishEventHandler BusinessDayPublishEvent
BusinessDayStateEventHandler BusinessDayStatusChange
EndOfDayCheckEventHandler EndOfDayCheck
EntryLoadedEventHandler EntryUowStateChange
EntryStatesEventHandler EntryUowStateChange
FileTrackingEventHandler FileTrackingStateChange
HoldoverBusinessDayEventHandler HoldoverBusinessDayEvent
MoveUowEventHandler MoveUow
OutPresentmentGroupStatesEventHandler OutPresentmentGroupState
PaymentAddedEventHandler PaymentAdded
PaymentDeletedEventHandler PaymentDeleted
PaymentExceptionEventHandler PaymentExceptionChange
PaymentReadyEventHandler PaymentExceptionChange
PresentmentGroupEventHandler
  • PresentmentColumnChange
  • PresentmentGroupColumnChange
  • PresentmentGroupLoaded
  • PresentmentGroupStateChange
PresentmentGroupLoadedEventHandler PresentmentGroupLoaded
PresentmentReadyEventHandler
  • PresentmentColumnChange
  • PresentmentGroupColumnChange
  • PresentmentStateChange
PresentmentStatesEventHandler
  • PresentmentColumnChange
  • PresentmentGroupColumnChange
  • PresentmentStateChange
ProcessingWindowActivityEventHandler
  • ParticipantWindowOverrideColumnChange
  • ProcessingWindowOverrideColumnChange
PurgeEventHandler BusinessDayPurgeEvent
SendEndOfDayFilesEventHandler SendEndOfDayFilesEvent
TrackableOverdueEventHandler TrackedItemOverdue
TransmissionCreatedEventHandler TransmissionCreated
UnloadDepositGroupEventHandler UnloadDepositGroup
UowLockingChangeEventHandler UowLockingChange
VectorFileHandler UowLockingChange

Event types for the predefined event handlers

The following table shows which event types are handled by each predefined event handler.
Table 3. Predefined event handlers and event types
Event handler Event types handled by the handler
CyclePurgeMaintenance BusinessDayPurgeEvent
DupDetectHandler
  • OutPresentmentGroupState
  • PaymentExceptionChange
  • PresentmentColumnChange
  • PresentmentGroupColumnChange
  • PresentmentGroupLoaded
  • PresentmentStateChange
GeneralPurposeEventHandler - This handler is a sample event handler.
  • BatchDelete
  • BusinessDayPublishEvent
  • BusinessDayPurgeEvent
  • BusinessDayStatusChange
  • CPCSActivateCategory
  • DuplicateDetected
  • DuplicateReviewed
  • EndOfDayCheck
  • EntryUowStateChange
  • FileTrackingStateChange
  • HoldoverBusinessDayEvent
  • LoadExpectedPresentments
  • MoveUow
  • OutPresentmentGroupState
  • PaymentAdded
  • PaymentDeleted
  • PaymentExceptionChange
  • PresentmentColumnChange
  • PresentmentGroupColumnChange
  • PresentmentGroupLoaded
  • PresentmentGroupStateChange
  • PresentmentStateChange
  • SegmentColumnChange
  • SegmentStateChange
  • SendEndOfDayFilesEvent
  • ServerShutdown
  • TaskStateChange
  • TracerUowStateChange
  • TrackedItemOverdue
  • TransmissionCreated
  • UnloadDepositGroup
  • UowLockingChange
LoadExpectedPresentmentsEventHandler
  • BusinessDayStatusChange
  • LoadExpectedPresentments
PiclistGenerator
  • EntryUowStateChange
  • TracerUowStateChange
PreLoadISNFileHandler
  • PresentmentGroupColumnChange
  • PresentmentGroupStateChange
PreLoadISNHandler
  • PresentmentColumnChange
  • PresentmentGroupColumnChange
  • PresentmentStateChange
PresentmentStatusCompleteEventHandler
  • PresentmentColumnChange
  • PresentmentStateChange
TrackingEventHandler TrackedItemOverdue
UnloadDepositGroupGatewayEventHandler UnloadDepositGroup