Application-connector communication method

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.

The connector and the UPES

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

Connector-initiated requests: XML API

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

  1. The connector receives a request from a collaboration for a business object destined for MQ Workflow.
  2. 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.
  3. The connector posts the request to the XML input queue of the MQ Workflow server.
  4. The MQ Workflow server receives the request and performs an action as specified by the business object content. Running in parallel, the connector either a) return successfully (if no response is expected) or b) optionally, wait for a response message.
  5. 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.
  6. 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.

MQ Workflow-Initiated requests

Figure 3 illustrates an MQ Workflow-initiated request to the connector.

Figure 3. MQ Workflow-Initiated request

  1. During workflow implementation, a UPES is defined such that messages sent to it are issued to the connector input queue.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. The requesting MQ Workflow UPES (program node) receives the response code and resulting business data structure.

Copyright IBM Corp. 1997, 2003