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