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.

  1. The connector loads the XML message into a DOM parser.
  2. The connector verifies that this is a WfMessage and checks for a recognized template.
  3. 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.
  4. The connector locates element ProgramParameters in the WfMessage. The ProgramParameters field contains application parameters specified by the user in the actual MQ Workflow.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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.

Copyright IBM Corp. 1997, 2004