Verb processing

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)

XML API verb processing

Note:
For MQ Workflow version 3.3.2 and higher, the XML API is recommended for verb processing.

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:

Delete

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.

Suspend

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.

Terminate

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.

Restart

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.

Resume

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.

Asynchronous requests

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 a sample asynchronous request.

Figure 4. Sample asynchronous connector request to MQ Workflow

  1. The connector receives a WfRequest_MyCustomer top-level business object with a negative "ResponseTimeout" attribute.
  2. The connector issues a request to the MQ Workflow server containing object "MyCustomer" as the data structure to be passed to the process.
  3. The connector returns successfully without waiting for a response. An error occurs only if the connector fails to put a message in the XML input queue of the MQ Workflow server.

Asynchronous requests for a process instance ID

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. Sample asynchronous connector request for a process instance ID

  1. The connector receives a WfRequest_MyCustomer top-level business object that specifies a non-negative value for attribute ResponseTimeout and the value Asynchronous for attribute ExecutionMode.
  2. The connector issues a request message to the MQ Workflow server containing object MyCustomer as the input data structure for process template CustomerCreditCheck. The connector waits (up to 5000 ms) for a reply.
  3. A new MQ Workflow process instance CustomerCreditCheck is instantiated. Before the workflow process finishes, a response message is returned to the connector. The message contains only a process instance ID.
  4. The connector populates object MyProcessInstance with the process instance information. If MQ Workflow returns an error message, the connector returns BON_FAIL and conveys the error message provided in the workflow message.

Synchronous requests

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. Sample synchronous connector request to MQ Workflow

  1. The connector receives a WfRequest_MyCustomer top-level business object and the configuration meta-object specifies a non-negative value for attribute ResponseTimeout and the value Synchronous for attribute ExecutionMode.
  2. The connector issues a request message to the MQ Workflow server containing object MyCustomer as the input data structure for process template CustomerCreditCheck. The connector waits for a reply (up to 5000 ms).
  3. A new instance of workflow process CustomerCreditCheck is instantiated in MQ Workflow. When the workflow process finishes, a response message is returned to the connector.
    Note:
    For long-lived synchronous transactions, ensure that the value for ResponseTimeout is sufficient to allow the entire process to execute.
  4. The connector transforms the data structure returned by the process to response object MyCreditCheck. In addition, the connector populates object MyProcessInstance with the process instance information. If MQ Workflow returns an error message, the connector returns BON_FAIL and conveys the error message provided in the MQ Workflow message.

Copyright IBM Corp. 1997, 2003