Implementing two-way interactions between a business state machine and a human task using WebSphere Process Server

Human interaction or intervention is often required as part of business processing. For example, a manager's approval may be required before an order greater than a certain monetary amount can be shipped. WebSphere Process Server Version 6.0.1 provides human tasks for just these types of situations. Human tasks are components that allow service-based applications to interact with people. By design, human tasks expose a two-way interface, which makes it difficult to invoke them directly when using business state machines within Process Server. In this article, we discuss how to use business state machines and human tasks together, using an example that requires a human approval step for a simplified order process implemented as a business state machine.

Share:

Geoffrey A. Beers (beersga@yahoo.com), Software Engineer, IBM

Geoffrey Beers is a software engineer at IBM in Rochester, Minnesota. He works in the Rochester Bringup Lab and SWAT team for WebSphere Process Server. You can reach Geoffrey at beersga@yahoo.com.



James Carey (jecarey@us.ibm.com), Senior Software Engineer, IBM

James Carey is currently a senior software engineer with IBM's System & Technology Group. Previously James was a member of the WebSphere Process Server architecture team where he focused on Business State Machines.



26 July 2006

Also available in Chinese

Introduction

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 machineFigure 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 purchase, the 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:

  1. 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).
  2. 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.
  3. 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 callFigure 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: BSMOrderInterface and BSMOrderCallbackInterface. 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 machineFigure 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 order operation).

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.

The 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 transitionsFigure 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") );

The variable 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 processFigure 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.

  1. Create an order. Using the template associated with the business state machine, create an order by specifying an orderId and the dollar amount of our order. The orderId is used for correlation. Notice that we specify an amount of $150, implying that this will need manager approval.

    Figure 6. Create order instanceFigure 6. Create order instance

  2. Invoke the order operation (event) on our BSM instance. Notice that we must use the same orderId we used to create the process, since it is used for correlation.

    Figure 7. Order ID is used for correlation between statesFigure 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 orderId. The orderId will 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 disapprovalFigure 8. Human task disapproval

    This causes the approvalResponse operation 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.

  3. 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.

  4. Update the order by calling the updateOrder operation. Enter the orderId and newAmount. Try lowering the amount to $125, to get the order approved this time.

    Figure 9. Enter new order amountFigure 9. Enter new order amount

  5. Since updateOrder is 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 orderId.

  6. 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.

  7. Again we assume the role of manager, but this time we do approve the order.

    Figure 10. Approve orderFigure 10. Approve order

    This causes the approvalResponse operation 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 Approve condition is taken.

  8. Order for $125 was approved this time. The BSMOrderApproval instance is no longer running, and our business state machine is in the Approved state.

  9. 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 supportFigure 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 BSMOrderApprovalFigure 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

Conclusion

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.


Download

DescriptionNameSize
Project Interchange of BSM invoking Human TaskInvokeHTfromBSM_PI.zip15KB

Resources

Learn

Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=148143
ArticleTitle=Implementing two-way interactions between a business state machine and a human task using WebSphere Process Server
publish-date=07262006