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.
