This document discusses how to use a human task component to control the business flow in a business state machine with IBM® WebSphere ®Process Server Version 6.0.1 (hereafter referred to as Process Server). A state machine awaits operations to transition from one state to another. These operations may be driven by user input or by other Service Component Architecture (SCA) components. In this example, we implement a simplified order process using a state machine. The order is loosely based on an internal order process, such as getting office supplies from a central supply department. Traditional real-world order processing scenarios involve human interaction at some point in the process. We simulate this interactivity by requiring human approval (most likely by a manager) for orders over $100. Thus we can easily get a red stapler, but have to have approval to get a FAX machine.
In our order process, we use the human task to get the request to the manager, who will analyze the order and return a decision to approve or disapprove the order. Figure 1, shown below, is a high-level portion of the order state machine that we will be focusing on.
Figure 1. High-level representation of the state machine
The first state shown in the diagram is
Building Order. This is similar to an order being in the shopping
cart, where items can be added or removed as desired. Once the order has all of the items intended for
order operation is used to move the order to the next step in its processing. There are two
transitions out of the
Building Order state. One is followed when the total amount of the order is less
than or equal to $100, and the other when the order is greater than $100. When the order is $100 or less,
no special approval is required, and the order can be shipped. On the other hand, if the amount is greater
than $100, the order has to be approved (via a human task) by a manager. When processing the human task, the
manager will either approve or disapprove the order. If the manager approves, the order is shipped. If
the manager disapproves, then the order goes back to Building Order state so that one or more items can be removed
and the order resubmitted.
Designing the order process
From the design and practice perspective, the first thing that needs to be determined is how the business state machine and human task will interact. The business state machine needs to initiate the human task as part of processing an operation and transition based on the human task response, once it is processed. Currently the only way a business state machine can directly initiate a human task is through a two-way interface; however, using this interface would cause the business state machine to wait until the human task is completed. This is unacceptable, since the business state machine would be stuck processing the operation. This would mean the business state machine is between states and thus would not be able to accept other operations, such as a request to cancel the order.
Therefore, to avoid this problem the human task needs to be initiated using a one-way operation. In this way the business state machine can initiate the human task during one of its operations and then, via a callback, process the
approval decision from the human task.
Thus, to get our use-case to work properly, we need to have:
- A human task to obtain the necessary approval.
- A mechanism to callback to the business state machine once the human task is completed.
Business Process Execution Language (BPEL) processes have the ability to invoke a human task as well as other components, so we can use a BPEL process as a wrapper for the human task.
Hence, the design pattern for invoking a human task from the business state machine is as follows:
- The business state machine will invoke a BPEL process, which will include an inline human task activity (why this needs to be inline will be discussed later).
- Once the order is approved or declined by the manager, the BPEL process will return the result of the human task to the business state machine by invoking an operation on the business state machine. This serves as the callback mechanism we were missing when trying to invoke the human task directly from the business state machine. Therefore, the business state machine actually invokes a long-running BPEL process that in turn calls the human task.
- After the human task is completed, the BPEL process will invoke the business state machine, and the state machine logic will continue. The Assembly Diagram for this design pattern is shown in Figure 2 below.
Figure 2. Assembly Diagram for the human task call
Notice that the client operations and the callback operation should be put in separate interfaces. In our example BSMOrder has two interfaces:
BSMOrderCallbackInterface provides the callback operation for the BPEL process and
BSMOrderInterface provides the client interface for the business state machine.
Designing the business state machine
The business state machine design is based on the states of the order and the transitions between those states. Figure 3 shows the design of the BSMOrder business state machine.
Figure 3. BSMOrder business state machine
BSMOrder business state machine: An instance of the BSMOrder business state machine is created when the
create operation (identified by the gear icon) is called on it. In this example, we only pass the
orderId and a
totalAmount to create the business state machine instance. A real-world application would require much more information, such as the order lines that make up the order.
Building Order state: After the business state machine is created, it goes into the Building Order state. From this state we can either update the order (using the
updateOrder operation) or place the order (via the
updateOrder operation allows the total dollar amount of the order to be changed. In a real-world application this operation would support more complex modifications, including addition and deletion of order lines in the order.
order operation is used to place the order and can, as shown in Figure 4, the following figure, take one of two transitions based on conditions (identified by blue diamond icons) defined in the business state machine logic.
Figure 4. State machine conditional transitions
Approved state: If the total order is $100 or less, then the manager is not required to approve the order and the business state machine will transition to the Approved state where it will wait for the order to ship. However, if the total order is greater than $100, then manager approval via a human task is required.
This is implemented by defining conditions on the transitions caused by the
order operation. These conditions are defined using Java™ snippets that return a Boolean value. For the
Approval Needed? Yes condition the Java snippet is:
return totalAmount.compareTo( new Float( 100.00f )) > 0;
We use the same snippet for the
Approval Needed? No condition, however, the option to invert the result it used. In a real-world application these conditions could be much more complex and could need to change while the application is running. For example being able to change the dollar amount used to determine when approval is needed. The business state machine provides the ability for a condition to call (invoke) another component to perform the condition check. This component could be a Process Server Business Rule that allows values, such as the $100 in our example, to be changed while the application is running.
Awaiting Approval state: In the case where manager approval is required, the Request Approval action (identified by a pinwheel icon) invokes the OrderApproval BPEL process. Since this process is invoked asynchronously, the business state machine transitions to the Awaiting Approval state where it will wait for the manager to approve or disapprove the order. Once processed, the OrderApproval instance will call the business state machine's
approvalResponse operation with the result of the approval and then end. If the manager approves the order, the business state machine will transition to the Approved state and await shipment. For the
"Approve" condition the Java snippet is:
return ( approvalResponse_Input_approvalResponse.equals("approve") );
approvalResponse_Input_approvalResponse contains the approval response value that was passed in on the
approvalResponse operation. It is filled in by the business state machine from the operation and made available to the conditions and actions associated with the operation.
On the other hand, if the order is not approved (
"disapprove"), then it will be sent back to the Building Order state where the user can change the order amount. The Java snippet for the
"Disapprove" condition is a little more complicated:
String response = approvalResponse_Input_approvalResponse;
return response.equals("disapprove") || !response.equals("approve");
The additional check that the value is not
"Approve" makes it so that any response other than
"Approve" will be assumed to be a
"Disapprove". Now that the business state machine is back in the Building Order state, the order amount can be changed (using
updateOrder) and the order operation will try again. If the order is still greater than $100, a new call to the
order operation will create a new OrderApproval instance that will again require manager approval.
Designing OrderApproval with an inline ApproveOrderTask
As discussed earlier, if the order amount is greater than $100, the Request Approval action in the business state machine will asynchronously invoke BSMOrderApproval. This process is straightforward. It receives the
orderId from the business state machine and immediately calls the inline ApproveOrderTask human task activity. Because a human task is defined, BSMOrderApproval must be a long-running process.
Now the ApproveOrderTask can be claimed and worked on. Once the task is completed, the resulting value is defined in the
approvalResponse variable. In our example, the human task does not use security and allows anyone to claim or work on the task. In a real-world scenario, the restrictions for claiming and approving the order would obviously be much stricter. The manager will either approve or disapprove the order. The BPEL process will immediately take the response and forward it to the callback operation
approvalResponse on the business state machine. The BPEL process uses the
orderId it was passed when it was initiated back to the business state machine. This
orderId (the correlation information) ensures the same business state machine that initiated the ApproveOrder task is called back to. Once this callback is complete, the BSMOrderApproval ends. The order approval process is shown in Figure 5.
Figure 5. Order approval process
Example run requiring approval
With our two components created and wired together, let's go through an example run of the order business state machine and the approval BPEL process (with the inline human task). For our example, we used the Business Process Choreographer (BPC) Explorer to create and work with the business state machine and to work with the human task.
Create an order. Using the template associated with the business state machine, create an order by specifying an
orderIdand the dollar amount of our order. The
orderIdis used for correlation. Notice that we specify an amount of $150, implying that this will need manager approval.
Figure 6. Create order instance
Invoke the order operation (event) on our BSM instance. Notice that we must use the same
orderIdwe used to create the process, since it is used for correlation.
Figure 7. Order ID is used for correlation between states
Since the order amount is greater than $100, an instance of the BSMOrderApproval process is created for us, as well as an ApproveOrderTask. When creating the BSMOrderApproval process we pass the
orderIdwill be used as a parameter when calling back to the business state machine so that the callback is to the right BSM instance.
We assume the role of the manager and use the BPC Explorer to process the approval task, deciding to disapprove the order.
Figure 8. Human task disapproval
This causes the
approvalResponseoperation to be called, with an approval response value of
"disapprove"(and the orderId for correlation). The different conditions for the transitions caused by the approvalResponse operation are checked and the
"Disapprove"condition is the on that evaluates to true, so the business state machine transitions back to the Building Order state.
Notice now that our BSMOrderApproval process is no longer running, nor is the ApproveOrderTask. However, our order business state machine is still active and running, and is currently waiting in the Building Order state.
Update the order by calling the
updateOrderoperation. Enter the
newAmount. Try lowering the amount to $125, to get the order approved this time.
Figure 9. Enter new order amount
updateOrderis a self-transition, we are still in the Building Order state. We need to call the order operation again, as we did above with our correct
Approve the order. Our order is still greater than $100, so we again have to get approval from the manager. Thus, a new BSMOrderApproval process with a new ApproveOrderTask is created for us. Hopefully they will approve our order this time.
Again we assume the role of manager, but this time we do approve the order.
Figure 10. Approve order
This causes the
approvalResponseoperation to be called on the business state machine with a value of
approve. Again all of the conditions for transitions that can be caused by this operation are check, but this time the transition associated with the
Approvecondition is taken.
Order for $125 was approved this time. The BSMOrderApproval instance is no longer running, and our business state machine is in the Approved state.
Ship the order. Finally, the order is shipped and the business state machine completes.
You may have noticed in our example a number of things labeled "log xxx". These points contained Java™ snippets that used System.out.println to write out progress information. Below is the console output of the case we just described showing the output from these points:
BSMOrder(3536) Created BSMOrder(3536) State is Building Order: Amount = 150.0 BSMOrder(3536) State is Awaiting Approval BSMOrderApproval(3536): Start Task BSMOrderApproval(3536): Task Finished. Approval Response is disapprove BSMOrder(3536) Disapproved BSMOrder(3536) State is Building Order: Amount = 150.0 BSMOrder(3536) State is Building Order: Amount = 125.0 BSMOrder(3536) State is Awaiting Approval BSMOrderApproval(3536): Start Task BSMOrderApproval(3536): Task Finished. Approval Response is approve BSMOrder(3536) Approved BSMOrder(3536) State is Approved BSMOrder(3536) State is Shipped
Cancelling the OrderApprovalProcess
Another common element that needs to be supported is order cancellation. An order can be cancelled either by the manager (via the human task) or by canceling the order directly. The difficulty arises because our solution has two process instances that are running, and the cancellation needs to be coordinated between the two. Our current design does not support order cancellation, so we must first add a
Canceled state to the business state machine.
The case where the manager cancels the order via the human task is straightforward. The approval response of
cancel must now be handled, so a transition from the
Awaiting Approval state to the
Canceled state is added with a condition that checks if the approval response is "cancel". This is similar to the condition for "approve" described above. We must also modify the condition for disapprove such that its Java snippet is now:
String response = approvalResponse_Input_approvalResponse;
return ( response.equals("disapprove" ) || ( !response.equals("approve") && !response.equals("cancel")));
On the other hand, the case where the order is cancelled directly is more complex. We cannot simply add a transition from the
Awaiting Approval state to the
Canceled state driven by the cancel operation.. If we did this, the human task would not be removed and when the OrderApproval process handled the response from the human task it would encounter an exception trying to perform the callback to the business state machine that no longer exists. To solve this problem we need to add an action (Cancel Approval) to this transition to cancel the human task. Figure 11 shows the updated business state machine:
Figure 11. Revised business state machine with cancel support
How does this action cancel the human task? As shown in Figure 12, this is done by adding an event handler to the BSMOrderApproval process that will terminate the process.
Figure 12. Event handler in BSMOrderApproval
This event handler is driven by the
cancel operation being called on the BSMOrderApproval process. This handler logs that the cancel has occurred and then terminates the process. Due to the possibility of order cancellation (hence, a need to terminate the human task), the human task must be inline. If the task was represented as a standalone component, the running task instance would not be terminated when the BSMOrderApproval process was terminated. However, because the task is inline, it is automatically terminated as well.
If we rerun the example above and cancel at Step (3), the resulting output is:
BSMOrder(o1) Created BSMOrder(o1) State is Building Order: Amount = 150.0 BSMOrder(o1) State is Awaiting Approval BSMOrderApproval(o1): Start Task BSMOrderApproval(o1): Cancelled BSMOrder(o1) State is Cancel
As shown in our example, human interaction with business state machines can be performed by encapsulating the human task in a separate long-running process that does the appropriate callback to the business state machine. In addition, this can support cancelling the human task from the business state machine, by in-lining the human task and having the process support an event handler that terminates the process and inline task activity. While our example focused on a single human interaction with the business state machine, this pattern can be applied to the state machine for each human interaction that is needed.
|Project Interchange of BSM invoking Human Task||InvokeHTfromBSM_PI.zip||15KB|
- SOA programming model for implementing Web services, Part 3: Process choreography and business state machines
- SOA programming model for implementing Web services, Part 8: Human-based Web services
- WebSphere Process Server
- WebSphere Business Integration zone
- New to WebSphere Business Integration
- Technical Podcast series
- WebSphere Process Server and WebSphere Integration Developer resource page
- developerWorks events and webcasts
Get products and technologies
- Build your next development project with IBM trial software, available for download directly from developerWorks.