Event handling
An event occurs when an MQ Workflow UPES posts a request
to the connector input queue. The connector detects events by polling
the input queue. This section describes the Event Handling process.
Event
notification
After detecting an event, the connector performs the steps
described below.
- The connector loads the XML message into a DOM parser.
- The connector verifies that this is a WfMessage and checks for
a recognized template.
- After identifying the input data structure contained in the
message, the connector creates a business object of type <boprefix><data structure name>. For example, if connector configuration property boprefix has a value of WfRequest_ and the connector receives a message containing a data structure
named MyCustomer, the connector expects that structure to conform to a child
of the top-level business object WfRequest_MyCustomer. The connector uses the XML data handler to convert the XML
data structure to the business object.
- The connector locates element ProgramParameters in the WfMessage.
The ProgramParameters field contains application parameters specified
by the user in the actual MQ Workflow.
- If the business object created by the data handler does not
have a verb specified, the connector sets the verb using data specified
in the ProgramParameters portion of the request message.
- To determine whether MQ Workflow expects a response to its request,
the connector evaluates element ResponseRequired in container WfMessageHeader of
the XML document for a value of yes, no, or iferror. A value of yes indicates that MQ Workflow is actively waiting for a response
message from the connector on the status of the request.
Note:
The ResponseRequired element corresponds to the
mode in the program activity properties of the MQ Workflow Buildtime
configuration (see Defining the Workflow Server in
Figure 22). If you specify the asynchronous mode, then
ResponseRequired=no; if you specify synchronous mode, then
ResponseRequired=yes.
- If a response is expected (ResponseRequired=yes), the connector evaluates the data specified in the ProgramParameters
element in the WfMessage to determine how to handle the request.
- If a collaboration is specified in ProgramParameters, the connector
sends the request to the collaboration using the executeCollaboration() method. Because this method is a synchronous request to the
collaboration, the return from the method call may take time. The
method returns the response object in its argument. The connector
generates a response message by populating the response object,
then sends the response to the MQ Workflow server.
- If a collaboration is not specified in ProgramParameters, the
connector posts the request to all subscribing collaborations using
the gotApplEvent() method. The connector populates the business
object shown in the argument of the gotApplEvent() method with the
meta-object that contains the MQ Workflow Activity information (such
as ActImplCorrelID). The method posts the request to the collaboration,
so the connector receives the return from the method call immediately.
Since no response object is returned by the method call, no response message
is generated or sent to the MQ Workflow server. Instead, the collaboration
must send the corresponding response object to the MQ Workflow server
using the service call request. The response object must include
the meta-object that contains the MQ Workflow Activity information
(such as ActImplCorrelID). The connector then constructs an appropriate
response message based on the service call request. The response
message contains the MQ Workflow Activity information and the return
code from the collaboration as well as the response business object.
The response message is sent to the MQ Workflow server. If an error
occurs at the step 8 or 9 above due to problems unrelated to the business
content of the message, the connector logs the error and does not generate
a response WfMessage.
- The message is optionally archived in the archive, error, or
unsubscribed queue.
Message
retrieval
The connector polls its input queue at regular intervals
for messages. When the connector finds a message, it retrieves it
from the queue and passes it to the DOM parser and XML data handler
to obtain the WfMessage content. The connector uses the data structure extracted
from the WfMessage to generate an appropriate business object with a verb. See Error handling for event
failure scenarios.
The connector processes messages by first opening a transactional
session to the input queue. This transactional approach allows for
the small chance that a business object could be delivered to a
collaboration twice due to the connector successfully submitting
the business object but failing to commit the transaction in the
queue. To avoid this problem, the connector moves all messages to
an in-progress queue. There, the message is held until processing
is complete. If the connector shuts down unexpectedly during processing,
the message remains in the in-progress queue instead of being reinstated
to the original input queue.
Note:
The connector does not remove the message from the
in-progress queue until: 1) The message has been converted to a
business object 2) the business object is delivered to InterChange
Server, and 3) a return value is received.
Message
recovery
Upon initialization, the connector checks the in-progress
queue for messages that have not been completely processed, presumably
due to a connector shutdown. The connector configuration property InDoubtEvents allows you to specify one of four options for handling recovery
of such messages: fail on startup, reprocess, ignore, or log error.
FailOnStartup
With the FailOnStartup option, if the connector finds
messages in the in-progress queue during initialization, it logs
an error and immediately shuts down. It is the responsibility of
the user or system administrator to examine the message and take appropriate
action, either to delete these messages entirely or move them to
another queue.
Reprocess
With the reprocessing option, if the connector finds any
messages in the in-progress queue during initialization, it processes
these messages first during subsequent polls. When all messages
in the in-progress queue have been processed, the connector begins
processing messages from the input queue.
Ignore
With the ignore option, if the connector finds any messages
in the in-progress queue during initialization, the connector ignores
them, but does not shut down. It begins processing messages from
the input queue.
Log error
With the log error option, if the connector finds any
messages in the in-progress queue during initialization, it logs
an error but does not shut down. It begins processing messages from
the input queue.
Message archive
If the connector property ArchiveQueue is specified and identifies a valid queue, the connector
places copies of all successfully processed messages in the archive
queue. If ArchiveQueue is undefined, successfully processed messages are discarded
after processing. For more information on archiving unsubscribed
or erroneous messages, see Error handling in Developing business objects.
