As noted in the introduction, the connector for MQ Workflow supports the
XML API communication mode.
Using the XML API, the connector can send messages that trigger actions in
MQ Workflow and handle synchronous requests from MQ Workflow during connector
polling. The connector polls a fixed queue to which request MQ messages
are issued, processes the content, and returns response messages (to a second
queue if necessary). In addition to business content, any XML message
issued to the connector indicates the collaboration to execute, the verb to
use, and other processing information.
To use the XML API, you must configure a UPES that specifies the input
queue of the connector.
When using the XML message API, the connector does not directly poll MQ
Workflow to check for new events. You must configure MQ Workflow nodes
to issue requests to external queues such as that of the connector. The
connector then can poll these external queues.
You configure the MQ Workflow nodes to issue requests to external queues
via a UPES. A UPES is a program that is designed to accept requests
from the MQ Workflow server. A UPES can, in turn, interact with the
server to retrieve any additional data and to pass results back. MQ
Workflow handles the conversion of the request to an XML message and
vice-versa.
As shown in Figure 1, the connector acts much like a UPES node in an MQ Workflow
system. In fact, the connector is transparent to the MQ Workflow
server.
Figure 1. Connector function as an MQ Workflow UPES

When the connector receives a message on behalf of a collaboration, the
connector issues an XML request message to the XML input queue of the MQ
Workflow server. Optionally (synchronously), the connector waits for a
response message to be returned by the MQ Workflow server. The server
triggers a workflow process and issues a response as necessary.
Figure 2 illustrates a message request communication from a
collaboration via the connector to an MQ Workflow.
Figure 2. XML API communication mode: Connector-initiated request

- The connector receives a request from a collaboration for a business
object destined for MQ Workflow.
- The connector converts the request object contained in the parent business
object to XML using the XML data handler. Using a DOM parser, the
XML-serialized business object is incorporated into a larger XML message
conforming to the MQ Workflow message DTD. Information about which
workflow process to create and execute is encapsulated in the (configuration
meta-object) that is contained in the parent business object.
- The connector posts the request to the XML input queue of the MQ Workflow
server.
- The MQ Workflow server receives the request and performs an action as
specified by the business object content. Running in parallel, the
connector will either a) return successfully (if no response is expected) or
b) optionally, wait for a response message.
- Depending on the request message issued by the connector, the MQ Workflow
server may return a response immediately that contains only the process
instance identifier (PID) of the concurrently executing process. Or the
MQ Workflow server may wait until the process is complete before returning the
resulting output data structure.
- Using an XML DOM parser, the connector extracts the output data structure
and process ID from the response message. As necessary, these
structures are converted to business objects using the XML data handler and
added to the parent business object. This object is then returned to
the awaiting collaboration.
Figure 3 illustrates an MQ Workflow initiated request to the
connector.
Figure 3. MQ Workflow initiated request

- During workflow implementation, a UPES is defined such that messages sent
to it are issued to the connector input queue.
- To request an action from a collaboration, the MQ Server routes the
request data structure to the UPES (as indicated by "program node"
above). MQ Workflow then sends an XML-based program invocation message
to the designated connector input queue. The message contains the
workflow data structure.
- The connector retrieves the message while polling the queue, parses the
content using an XML DOM parser and converts the input data structure to a
business object using the XML Data Handler.
- If the request is to execute asynchronously, as specified by the user when
defining the UPES (program node), the connector posts the business object to
all waiting collaborations and does not send a response back to the MQ
Workflow server.
- If the request is to execute synchronously and the collaboration name is
specified in the command line parameters (see Figure 20), the connector sends the business object to the specific
collaboration and waits for a return.The connector constructs an
appropriate response message based on the return. The response contains
any business object changes. The response is then sent to the MQ
Workflow server.
- If the request is to execute synchronously and the collaboration name is
not specified in the command line parameters (see Figure 20), the connector posts the business object to all waiting
collaborations and does not send a response back to the MQ Workflow
server. Although this case is similar to the asynchronous case above,
the MQ Workflow server is still waiting for the reply from the
connector. Therefore it is the responsibility of collaboration to send
the corresponding response to the connector using the service call
request.
- The requesting MQ Workflow UPES (program node) receives the response code
and resulting business data structure.
