The role of the connector is to bridge the data structures in the workflow with the business object. It is the responsibility of MQ Workflow to take action depending on the verbs set in the business object--the connector can guarantee only that the workflow successfully receives the content. Accordingly, the connector has no means of influencing a business object in the MQ Workflow product. In fact, given the nature of MQ Workflow, a persistent data structure may not exist for the business object as it may act only as a trigger for subsequent workflow.
The Business Object Handler (BOHandler) processes all business objects in the same manner regardless of the verb. Using a DOM parser, the connector constructs a WfMessage.
The connector checks the application-specific text of the top-level business object to ensure that a name-value pair of the form cw_mo_wfptcfg=XXX is defined. The child meta-object identified by XXX is parsed and values are interpreted.
The template that is executed is identified by meta-object attribute ProcessTemplateName. These templates provide the structures necessary to specify entire commands to MQ Workflow as well as to contain the results. If attribute ProcessInstanceName is specified, the connector executes the existing instance; otherwise, it creates a new instance of the template. The template is executed under the authorities granted to the user identified by attribute UserId of the child meta-object. If the attribute is not specified, the value of connector configuration property ApplicationUserID is used instead. For more on templates, see Top-level business object and content configuration in Modifying the WebSphere MQ Workflow application.
The connector supports the following business object verbs for requests to control an existing workflow:
Upon receipt of a message from MQ Workflow, the connector identifies the verb of the business object from the value of ProgramParameters in the WfMessage. The text for ProgramParameters must include a name=value pair specifying the verb of the business object contained in the message. For example, to specify a delete verb, the element text includes the name=value pair verb=Delete.
However, in the opposite direction, the connector does not dictate to MQ Workflow which verb to use to process the request. When issuing a business object to MQ Workflow, the connector ignores the verb of the business object. Instead, the connector converts the business object to XML and incorporates the content into a WfMessage for MQ Workflow. The workflow to which the business object is issued determines the action taken (not the verb specified for the business object by the collaboration)
Using the MQ Workflow connector XML API, a collaboration can monitor and control the status of the workflow process. Upon successfully controlling a workflow operation, the connector populates a process instance object (MO_MQWorkflow_ProcessInstance) with details of the process. The connector considers any object with app-text equal to ProcessInstance to be an instance of an MO_MQWorkflow_ProcessInstance.
The connector converts the business object to XML and incorporates the content into a WfMessage of MQ Workflow. The verb specified for the business object determines the action performed on the process instance.
When using the XML API, the connector supports the following verbs for an MO_MQWorkflow_ProcessInstance:
The connector deletes the specified process instance from MQ Workflow. The process instance must be in one of the following states: Ready, Finished, or Terminated. If the process does not exist or could not be deleted, the connector returns BON_FAIL. Otherwise, the connector returns a populated MO_MQWorkflow_ProcessInstance object with new status.
The connector issues a request to suspend the workflow process and returns BON_FAIL if the process does not exist or if it cannot be suspended. The process instance must be in the state of Running. If the deep option is true, all non-autonomous sub-processes are also suspended. If the process does not exist or could not be suspended, the connector returns BON_FAIL. Otherwise, the connector returns a populated MO_MQWorkflow_ProcessInstance object with new status.
The connector terminates a process instance and all of its non-autonomous sub-processes. All running, checked-out, and suspended activities are terminated. The process must in one of the following states: Running, Suspended, or Suspending. If the process does not exist or cannot be terminated, the connector returns BON_FAIL. Otherwise, the connector returns a populated MO_MQWorkflow_ProcessInstance object with new status.
The connector issues a request to restart the workflow process instance. Only finished or terminated top-level process instances can be restarted. If the process does not exist or could not be restarted, the connector returns BON_FAIL. Otherwise, the connector returns a populated MO_MQWorkflow_ProcessInstance object with new status.
The connector issues a request to resume processing of a suspended or suspending process instance. If the deep option is true, all non-autonomous sub-processes are also resumed. If the process does not exist or could not be resumed, the connector returns BON_FAIL. Otherwise, the connector returns a populated MO_MQWorkflow_ProcessInstance object with new status.
If the attribute ResponseTimeout of the configuration meta-object is less than zero, the connector issues requests to the MQ Workflow server without waiting for a response. If an error occurs while the process is executing, the collaboration has no means of being notified. Figure 4 shows an example of an asynchronous request.
Figure 4. Example asynchronous connector request to MQ Workflow
If a non-negative ResponseTimeout is provided in the child meta-object and attribute ExecutionMode is Asynchronous, the connector issues a request and returns a process instance ID to the collaboration. Successful receipt of a process instance ID does not imply successful completion of the corresponding workflow process. The collaboration must perform a "Retrieve" on the process instance ID to determine the status. This is useful for long-lived transactions. Figure 5 illustrates this process.
Figure 5. Example asynchronous connector request for a process instance ID
When a non-negative ResponseTimeout attribute is provided in the child meta-object and attribute ExecutionMode is Synchronous, the connector issues a synchronous request. The request does not return successfully until the workflow process has completed. Synchronous request processing guarantees that a collaboration is apprised of the success or failure of an MQ Workflow process that the collaboration initiates. For short-lived transactions, synchronous processing is an efficient means of generating immediate feedback. Figure 6 illustrates a synchronous request.
Figure 6. Example synchronous connector request to MQ Workflow