Event handler registration

An event handler must be registered with the task scheduler XML so that it is run for a specific event type. Registration of event handlers is similar to that of tasks, except an event type is needed and no timer information is necessary.

All events have the following required and optional XML tags:

Table 1. Event handler XML tags
Tag	Required	Description
EVENT	Yes	Scheduler events are defined by using this tag set. The event tag has the following attributes: mode This attribute controls whether extra log messages are produced for the event. The additional messages can be used to debug the processing of events. Set the mode attribute to debug to enable the additional logging. The additional logging is disabled when the attribute is omitted or it is set to standard. Not all the event handlers produce the additional debug log information.
NAME	Yes	The name is a user-specified string that is used to identify the event in traces. Give each event a different and unique name value for debugging purposes. This tag can appear only one time for an event.
TYPE	Yes	Event type specification. Table 1 shows the valid event types. Multiple event types can be specified for a single event.
EXEC	Yes	The class name of the event handler that is called when one of the event types occur. It must handle the event types that are specified in the type tag and must be a predefined event handler. This tag can appear only one time for an event.
INFO	No	This tag is provided for consistency with the task XML specification.
PARAMETER	Whether this tag is required depends on the event handler. For more information about which parameters are allowed and which are required, see the documentation for the specific event handler.	Configuration property values for the specific event handler. You can use a list of comma-separated values in the parameter tag for many event handlers. The list of values are logically ORed together except when `presStates#` is used for sequenced parameters in the name attribute of the parameter tag. When the `presStates#` attribute is used, the comma-separated values are logically ANDed together. The parameter tag has the following attributes: name This attribute is the name of the event handler parameter that is associated with this parameter tag. priorValue This attribute is the value that a column had before the event. This attribute is used to limit the event handler to running only when a column changes from one specific value to another. It is only used by PresentmentColumnChange events. include This attribute indicates whether this parameter needs to be included in this scheduler instance. For more information about this attribute, see Configuring the Scheduler. Note: The PARAMETER tag is not available for all the event handlers.
PARAMETERREF	No	This tag is used to specify a named PARAMETERSET for the event. The PARAMETERSET must be one that is specified in the Scheduler.xml file. Multiple PARAMETERREF tags can be used for a single event. Note: The PARAMETERREF tag is available only for event handlers that have PARAMETER tags.

The following table shows other XML tags that you can use when you are registering an event handler.

Table 2. Other event handler tags in the task scheduler XML
Tag	Required	Description
PARAMETERSET	No	A group of one or more parameter tags that is given a name so event tag sets can reference it. This method is useful when multiple events need to use the same parameters and their values. For more information about PARAMETERSET, see Configuring the Scheduler.

Example event handler processing

The sample scheduler XML in the following example is used to send batches (ICLs) to Distribution after they are balanced.

<EVENT>
   <NAME>Distribution - Batch</NAME>
   <TYPE>PresentmentStateChange</TYPE>
   <TYPE>PresentmentColumnChange</TYPE>
   <TYPE>PresentmentGroupColumnChange</TYPE>
   <EXEC>com.ibm.paydir.ima.txsvr.event.appbridge.PresentmentReadyEventHandler</EXEC>
   <PARAMETER name="workType">Present</PARAMETER>
   <PARAMETER name="msgType">presStatesReached</PARAMETER>
   <PARAMETER name="presStates">BALANCED</PARAMETER>
   <PARAMETER name="outboundReady">!2</PARAMETER>
   <PARAMETER name="group.condition">ACCEPTED</PARAMETER>
   <PARAMETER name="inbound.condition">ACCEPTED</PARAMETER>
   <PARAMETER name="condition">ACCEPTED</PARAMETER>
   <PARAMETER name="pending">N</PARAMETER>
   <PARAMETER name="group.pending">N</PARAMETER>
   <PARAMETER name="presLevel">PROC</PARAMETER>
   <PARAMETERREF>schedulerReferenceProperties</PARAMETERREF>
   <PARAMETERREF>sendToDistribution</PARAMETERREF>
</EVENT>

For this event XML stanza, the PresentmentReadyEventHandler event handler is called when any of the following events occur.

A PresentmentStateChange event, which indicates that a state of the batch (ICL) was changed.
A PresentmentColumnChange event, which indicates that a value in a database column was changed for the batch (ICL). The value that changed is in a database column that is not in the timestamp format.
A PresentmentGroupColumnChange event, which indicates that a value in a database column was changed for the transmission. The value that changed is in a database column that is not in the timestamp format.

The event parameters that are defined in the XML specify the criteria that must be met for the batches (ICLs) to be sent to Distribution. The PresentmentReadyEventHandler event handler first checks only the event parameters that are its triggers. The trigger event parameters are used to determine whether the state and column changes that occurred are the ones that are necessary to send the batches (ICLs). In this example, the trigger event parameters are satisfied when either one of the following column change or state change events occur.

The balanced state changed for the batch (ICL).
One of the columns that define the status for the batch (ICL) or transmission changed. The value of the condition, pending, and overrideable columns determines the status of a batch (ICL) or transmission.

Any other column change event or state change event is ignored because it is not defined as a trigger event parameter. Refer to the list of event parameters for a specific event handler to see which parameters are its trigger event parameters.

After the event handler determines that the trigger event parameters are satisfied, the additional event parameters in the XML are used to determine whether the presStatesReached message is sent to Distribution.

For this example scheduler XML, the presStatesReached message is sent when all the following criteria are met.

The balanced state is set.
The condition of the processing batch (ICL), the inbound batch (ICL), and the transmission are all accepted.
No batches (ICLs) or transmissions are pending.
Distribution is not finished mapping transactions and batches (ICLs) to outbound transmissions. The outboundReady parameter is set to 2 when mapping is complete.

This sample event XML stanza references parameter sets to determine how and where to send the message. The parameter sets are shown in the following list.

The schedulerReferenceProperties parameter set contains all the parameters that are necessary to connect to IBM® MQ.
The sendToDistribution parameter set defines the name of the queue that the message is to be sent to and the destination ID.

The workType and msgType parameters are part of the message that is sent. The recipient must recognize the values for these parameters for the message to be processed as expected.