Running the scenarios
Before you run the scenarios:
- Start InterChange Server if it is not already running.
- Start the WBI Adapter for WebSphere MQ Workflow if it is not already
running, using the -fkey option (to prevent automatic
polling).
- Start the Visual Test Connector if it is not already running.
Simulate the Port Connector by starting the Visual Test Connector, defining
a profile for PortConnector and binding the agent.
Synchronous request
This scenario passes business data to a defined workflow process and
retrieves the end result. This is a synchronous call because, after
issuing the request to WebSphere MQ Workflow, the adapter blocks until the
initiated workflow process completes.
In this scenario, you retrieve the status of a fictitious order by passing
an order key to workflow process Lookup_Order_Status. This
workflow has only one action, which is to issue a retrieve to an IBM WebSphere
Business Integration Server to get information about the order. This
demonstrates how the adapter can issue a synchronous request to WebSphere MQ
Workflow, and how WebSphere MQ Workflow can issue a synchronous request to the
adapter.
- Create a sample order Using the Visual Test Connector, create a
new instance of business object MQWF_SampleItemOrder with the verb
Create and populate it as follows (undefined values should be
CxIgnore):
MQWF_SampleItemOrder
- Input_ItemOrder
- MO_Config
- ProcessTemplateName = Lookup_Order_Status
- KeepName = false
- UserId = UserName
- ExecutionMode = Synchronous
- ResponseTimeout = 600000
- TimeoutFatal = false
- Send this object to the adapter The adapter will convert this
object to a request message and issue it to the WebSphere MQ Workflow
server. The adapter should not return immediately, but instead begin
waiting for a response from WebSphere MQ Workflow.
WebSphere MQ Workflow receives the request from the adapter to synchronously
create and invoke process template Lookup_Order_Status using the
data from object
MQWF_SampleItemOrder.Input_ItemOrder. The first and
only step of this workflow process is to retrieve data structure
SampleItemOrder from the IBM WebSphere Business Integration Server
using the tracking number as a key. To do this, MQ Workflow issues a
request message to the input queue of the adapter and begins waiting for a
response itself. This can be verified by checking the WebSphere MQ
Workflow Client application.
- Press p in the adapter agent window to poll for events. The adapter
finds the request issued by WebSphere MQ Workflow (triggered by our original
request). The adapter converts the request message to object
MQWF_SampleItemOrder with verb Retrieve and posts it to
collaboration SampleItemOrderSync_MQWF_to_Port.
- Accept the request via the Visual Test Connector. Verify that
attribute TrackingNumber of object
MQWF_SampleItemOrder.Input_ItemOrder is ABC123
(the same as that of our initial request). Populate object
MQWF_SampleItemOrder.Output_ItemOrder as follows and then
select Reply Success to complete the request:
- Output_ItemOrder
- TrackingNumber = ABC123
- Approved = YES
The adapter returns a response to WebSphere MQ Workflow, passing back the
business data contained in
MQWF_SampleItemOrder.Output_ItemOrder.WebSphere MQ
Workflow receives the response from the adapter and incorporates the data into
a response message for the original request, which is then issued back to the
ReplyTo queue of the adapter. The adapter retrieves the response
message and returns any changes or errors to the collaboration. This
completes the synchronous workflow request. The object returned to the
collaboration should be populated as follows:
- MQWF_SampleItemOrder
- Input_ItemOrder
- MO_Config
- ProcessTemplateName = Lookup_Order_Status
- KeepName = false
- UserId = UserName
- ExecutionMode = Synchronous
- ResponseTimeout = 600000
- TimeoutFatal = false
- Output_ItemOrder
- TrackingNumber = ABC123
- Approved = YES
- ProcessInstance This should be populated but
the values cannot be predicted. The process state should be
TERMINATED.
- Note:
- If you fail to complete this process within 10 minutes (600000 milliseconds
as configured in the meta-object), the adapter will report that it failed to
receive a response from WebSphere MQ Workflow.
Asynchronous request
In this scenario, the adapter passers business data to a defined workflow
process but does not wait for the process to complete. This is an
asynchronous call-- after issuing the request to WebSphere MQ Workflow,
the adapter receives a process id to use in tracking the process as it
executes in parallel. In this scenario, the adapter issues an order to
workflow process Approve_Order to begin the task of approving an
order (and later to check on whether the approval has completed). The
workflow process retrieves information about the item ordered and updates the
order approval based on whether sufficient quantities of the item are in
stock. This scenario demonstrates how the adapter can trigger the start
of workflow process asynchronously and how the adapter can monitor the status
of a workflow process executing in parallel.
- Using the Visual Test Connector, create a new instance of business object
MQWF_SampleItemOrder with verb Create and populate it as
follows (undefined values should be CxIgnore):
- MQWF_SampleItemOrder
- Input_ItemOrder
- TrackingNumber = ABC123
- Customer = Billy Bob
- Item
- Name = Hammer
- Quantity = 1
- MO_Config
- ProcessTemplateName = Approve_Order
- KeepName = false
- UserId = UserName
- ExecutionMode = Asynchronous
- ResponseTimeout = 500
- TimeoutFatal = false
- Send MQWF_SampleItemOrder to the adapter, which converts this
object to a request message and issues it to the WebSphere MQ Workflow
server. The adapter then waits for a response that includes the process
instance ID. WebSphere MQ Workflow receives the request from the
adapter to asynchronously create and invoke process template
Approve_Order using the data from object
MQWF_SampleItemOrder.Input_ItemOrder. Once the
process is started, WebSphere MQ Workflow immediately issues a response back
to the adapter containing the id of the workflow process initiated. The
workflow process also starts its first step, which is retrieving data
structure SampleItem with name = Hammer from the IBM
WebSphere Business Integration Server. These are two separate
actions: a response is being issued to the ReplyTo queue of the adapter
while simultaneously a request is being issued to the input queue of the
adapter. The adapter receives the response from WebSphere MQ Workflow
and returns a business object to the calling collaboration. This object
is similar to the following:
- MQWF_SampleItemOrder
- Input_ItemOrder
- TrackingNumber = ABC123
- Customer = Billy Bob
- Item
- Name = Hammer
- Quantity = 1
- MO_Config
- ProcessTemplateName = Approve_Order
- KeepName = false
- UserId = UserName
- ExecutionMode = Asynchronous
- ResponseTimeout = 5000
- TimeoutFatal = false
- ProcessInstance This should be populated but the
values cannot be predicted.
- Note:
- Remember the value of attribute ProcessInstanceID for use later in
this tutorial.
At this point, the workflow process is executing in parallel to
collaboration processing. The only means of tracking or controlling the
workflow process is via the ProcessInstanceID returned in object
MQWF_SampleItemOrder.ProcessInstance.
- Using the Visual Test Connector, create a new instance of business object
MO_MQWorkflow_ProcessInstance with verb
Terminate. Using the XML API is required in WebSphere MQ
Workflow 3.4 and is recommended for WebSphere MQ Workflow
3.3.2. To use the XML API, set Adapter Configuration
Property JavaCorbaApi = False and, to monitor the workflow process
(MO_MQWorkflow_ProcessInstance), set ProcessInstanceName =
ProcInstName (the ProcInstName returned in the previous
step.
- Note:
- For the XML API, the Restart and Delete verbs only are supported.
- SendMO_MQWorkflow_ProcessInstance to the adapter and it should
return the status of the workflow process. The attribute
ProcInstState should equal RUNNING.
- To resume the workflow process started in this scenario, press p in the
adapter agent window to poll for events. The adapter finds the request
issued by WebSphere MQ Workflow (triggered by the original request).
The adapter then converts this request message to object
MQWF_SampleItem with the verb Retrieve and posts it to
collaboration SampleItemSync_MQWF_to_Port.
- Accept the request via the Visual Test Connector. Verify that
attribute Name of object
MQWF_SampleItem.Input_Item is Hammer.
Populate object MQWF_SampleItem.Output_Item as shown below
and then select Reply Success to complete the request.
- Output_Item
- Name = Hammer
- Price = 14.99
- Stock = 20
The adapter returns a response to WebSphere MQ Workflow, passing back the
business data contained in
MQWF_SampleItem.Output_Item. WebSphere MQ Workflow
receives the response from the adapter and checks if the value of
Stock is greater than the value Quantity in the original
order. If so, there are enough hammers in stock to complete the order
and therefore it is approved. The workflow process performs its final
step by updating the order in InterChange Server and issues a
SampleItemOrder data structure to the input queue of the adapter
with the same key as the original order but now with attribute
Approve equal to Y.
- To process this final request from WebSphere MQ Workflow, press p in the
adapter agent window to poll for events. The adapter finds the request
issued by WebSphere MQ Workflow, creates object
MQWF_SampleItemOrder with the verb Update and then posts
the object to collaboration
SampleItemOrderSync_MQWF_to_Port. You can simply accept this
request (since there are no records to update in this scenario. Once
the adapter issues a response, both the request from IBM WebSphere Business
Integration Server and the workflow process are complete.
Workflow process control
This scenario demonstrates how to control a workflow process by terminating
a process that is under way.
- Start with step 1 of as described in Asynchronous request, but instead of issuing business object
MO_MQWorkflow_ProcessInstance with verb Retrieve, change
the verb to Suspend. Send this object to the adapter and
verify via the WebSphere MQ Workflow Client application that the process
suspends
- Note:
- The process will remain in a state of SUSPENDING until it can
complete its first request to InterChange Server--this reflects the
functionality of WebSphere MQ Workflow, and not the adapter.
- Change the verb to Resume and re-send the object. The
state of the workflow process changes back to RUNNING.
- Change the verb to Terminate and re-send the object. The
state of the workflow process will change to TERMINATED. You
can verify this by issuing the object with verb Retrieve. In
this manner, you have successfully controlled and monitored the state of a
workflow process via ICS.
- Note:
- A request message may remain in the input queue of the adapter even thought
the process that generated this request is terminated. This is
normal. Although the adapter will process this request, WebSphere MQ
Workflow will ignore any response generated.
Synchronous request from WebSphere MQ Workflow
This scenario simulates a synchronous request from WebSphere MQ Workflow to
ICS and its response. The difference from Scenario 1 is that the
adapter calls the collaboration asynchronously (whereas scenario 1 makes all
calls synchronously). This scenario is more practical than scenario 1
because another workflow process does not have to wait for the workflow
process to complete.
- Create an update request. On the WebSphere MQ Workflow client,
create and start a workflow process instance, and then fill an input data
structure SampleItemRequest as follows:
- SampleItemRequest
- Name = Hammer
- Price = 14.99
- Stock = 20
WebSphere MQ Workflow synchronously issues this request to the input
queue of the adapter and waits for a response.
- Enter p in the adapter agent window to poll for events. The adapter
finds the request issued by WebSphere MQ Workflow. The adapter converts
this request message to object MQWF_SampleItemRequest with verb
Update. The adapter also converts the business object to a
generic business object MQWF_GBO_SampleItem by using
mapMQWF_Sample_RequesttoGBOand then publishes it
asynchronously. At this point, the adapter does not wait for its
response and can receive another request.
- Accept the request via the Visual Test Connector. Collaboration
SampleItemRequest_MQWF_to_MQWF subscribing the generic business
object receives the object and it will be accepted by the Visual Test
Connector.Verify that attribute Name of object
MQWF_GBO_SampleItem.InputItem and
MQWF_GBO_SampleItem.OutputItem is Hammer (the
same as that of our initial request). Fills empty attributes of object
MQWF_GBO_SampleItem.OutputItem as follows and then select
ReplySuccess to send the generic business object to the
adapter.
- MQWF_GBO_SampleItemOrder
- ContainerInfo
- All attributes except ReturnCode are filled.
- (Do not change ActImplCorrelID, which is used as
ID in MQWF)
- InputItem
- Name = Hammer
- Price = 14.99
- Stock = 20
- OutputItem
- Name = Hammer
- Price = 11.25
- Stock = 8
The adapter receives the generic business object and converts it to
object MQWF_SampleItemResponse by using map
MQWF_Sample_GBOtoResponse. The adapter returns a response to
WebSphere MQ Workflow with the business data contained in
MQWF_SampleItemResponse.Output_Item. WebSphere MQ
Workflow receives the response from the adapter and checks the value of
ActImplCorrelID. If there is a workflow process that matches
the value of ActImplCorrelID, then the process completes.
The corresponding process instance in the WebSphere MQ Workflow client will
disappear. (You may need to refresh the window.)
