11 Designing the Human Task Workflow System

This chapter of the tutorial describes how to add user tasks to handle the manual approval or rejection of a purchase order.

This chapter contains the following topics:

• Introduction

• Designing the Human Workflow System for Manual Approval of an Order

• Summary

11.1 Introduction

This phase of the tutorial adds to the process you designed in Chapter 10, "Designing the Database Adapter to Insert Data". Ensure that you have successfully completed that phase before performing this one. This phase extends the previous project steps by calling an external manual service through human task capabilities. It includes a call out to another Web service that handles human tasks and uses predefined (default) graphical user interface screens for user actions. You perform the following key tasks:

• Create a new BPEL process named OrderApproval.

• Design the BPEL process to add workflow functionality to handle the manual approval or rejection of a purchase order.

• Deploy the OrderApproval BPEL process.

• Run the OrderApproval BPEL process from Oracle BPEL Control.

• Access the Oracle BPEL Worklist Application URL to approve the order.

• Return to the OrderBooking BPEL process and create a partner link (named POAService) that interacts with the OrderApproval BPEL process.

• Design the BPEL process to invoke POAService.

• Deploy the OrderBooking BPEL process.

• Run the OrderBooking BPEL process from Oracle BPEL Control.

• Access the Oracle BPEL Worklist Application URL to approve the order.

11.2 Designing the Human Workflow System for Manual Approval of an Order

This section contains these topics:

• Modeling the Order Approval Process

• Creating a Partner Link for the Order Approval Service

• Creating a Scope Activity

• Creating Invoke and Receive Activities

• Creating an Initial Assign Activity

• Creating a Second Assign Activity

• Validating, Compiling, and Deploying the Order Process

• Running and Verifying the Order Process

11.2.1 Modeling the Order Approval Process

In this phase of the tutorial, you create a new project, Order Approval, and define the human workflow process, a sequential workflow in which the order is approved or rejected. The order is first assigned to the Supervisor role. After a user with the Supervisor role approves the order, it is sent to the user's manager for final approval.

This section contains these tasks:

• Creating the Order Approval Process and Importing the Schema

• Adding a Human Task to the Order Approval Process

• Assigning Input and Output Parameters for the Human Task

• Creating a Task Form for the Worklist

• Modeling the Task Outcome

• Validating, Compiling, and Deploying the Order Approval Process

• Running the Order Approval Process

11.2.1.1 Creating the Order Approval Process and Importing the Schema

Summary:

After creating the BPEL process, you import the OrderBookingPO.xsd schema.

1. In OrderBookingapplication, create an asynchronous BPEL process with the name OrderApproval.

   See "Creating the Order Booking Project and Importing the Schema" for a refresher on how to create a project.

2. Click Next.

3. Click the flashlight next to Input Schema Element to browse for OrderBookingPO.xsd in

   SOA_Oracle_Home\bpel\samples\tutorials\127.OrderBookingTutorial\
   OrderApproval\bpel
   
   

   The Type Chooser window appears.

4. Expand and select Imported Schemas > OrderBookingPO.xsd > PurchaseOrder.

5. Click OK.

6. Click the flashlight next to Output Schema Element and repeat Step 4.

7. Click Finish.

   The schemas are now imported into the project. OrderBookingPO.xsd appears under Order Approval > Integration Content > Schemas in the Application Navigator, and under Schemas in the Structure section. The BPEL process—a Receive activity (receiveInput) and an Invoke activity (callbackClient)—is displayed.

11.2.1.2 Adding a Human Task to the Order Approval Process

Summary:

When you define the human task, the OrderApproval.task file—the task configuration metadata file—is created.

1. Select Process Activities from the Component Palette section.

2. Drag and drop a Human Task activity from the Component Palette to between receiveInput and callbackClient.

3. Click the Create Task Definition icon (second icon).

   
   Description of the illustration wf_task_def.gif
   
   

4. Enter OrderApproval for the human task name and click OK. (Accept the default location.)

   The OrderApproval.task file is created.

   The Human Task editor is displayed.

5. For Title, enter Purchase Order Approval.

6. Accept the default values for Priority and Outcomes.

7. For Parameters, click the + icon on the right side of the window.

   The Add Task Parameter window is displayed.

8. Click Element and then the flashlight icon.

9. In the Type Chooser window, expand and select Project Schema Files > OrderBookingPO.xsd > PurchaseOrder, and click OK.

   
   Description of the illustration wf_typechooser.gif
   
   

10. In the Add a Parameter window, click Modifiable via worklist and click OK.

    This ensures that you can modify task data using the Oracle BPEL Worklist Application.

11. In the Assignment and Routing Policy section, click the + icon on the right side of the window.

    The Add Participant Type window is displayed.

12. For Type, select Management Chain.

    This participant type routes tasks for approval to multiple users in a management chain hierarchy.

13. For Label, enter Order Approvers.

14. Click By name.

    In this example, you assign the task to the Supervisor group and specify one level of the management chain above the user who acts on the task.

15. For Group Id(s), click the flashlight to display the Identity lookup dialog window.

    Ensure that your integration server connection is selected.

16. Ensure that Oracle BPEL Server is running and click Lookup to see a list of all groups currently in the system.

17. Select Supervisor, click Select, and click OK.

    
    Description of the illustration wf_identity_serivce.gif
    
    

18. In the Number of Approvers section of the Add Participant Type window, enter 1 in the Maximum Number of Chain Levels Up field. Click OK.

19. In the Assignment and Routing Policy section, click Enable abrupt completion condition.

    The Early Completion Details window is automatically displayed.

20. Select REJECT and move it to the Selected list. Click OK.

    
    Description of the illustration wf_reject.gif
    
    

21. Select Save from the File main menu.

22. Click the X next to OrderApproval.task to close the Human Task editor.

    
    Description of the illustration wf_close.gif
    
    

11.2.1.3 Assigning Input and Output Parameters for the Human Task

Summary:

Map the fields to the variables in the BPEL process.

1. Double-click OrderApproval.bpel to see the Human Task activity, OrderApproval_1, in the BPEL process.

   
   Description of the illustration wf_humantask4.gif
   
   

2. Double-click OrderApproval_1.

3. In the Task Title field, add the word for to the end of the expression Purchase Order Approval.

4. Click the icon at the right to use the XPath Expression Builder.

5. In the BPEL Variables section, expand and select inputVariable> payload > ns1:PurchaseOrder > ns1:CustID.

6. Click Insert Into Expression.

   The XPath expression corresponding to ns1:CustID appears in the Expression section.

7. Click OK.

   The XPath expression is appended to the task title.

8. Click the icon at the right to use the XPath Expression Builder for the Initiator field.

9. Repeat Steps 5 through 7 to insert the same XPath expression in the Initiator field.

   
   Description of the illustration wf_humantask5.gif
   
   

10. Click the flashlight icon in the BPEL Variable column.

    The Task Parameters window appears.

11. In the Task Parameters window, expand and select Variables > inputVariable > payload > ns1:PurchaseOrder.

12. Click Insert Into Expression, and click OK.

13. In the Human Task window, click OK.

14. Select Save from the File main menu.

11.2.1.4 Creating a Task Form for the Worklist

Summary:

An autogenerated task form, payload-body.jsp, is created.

1. In the Application Navigator, right-click the OrderApproval folder that includes the .task file and select Auto Generate Simple Task Form.

   The autogenerated task form file appears:

   
   Description of the illustration wf_jsp.gif
   
   

2. Close payload-body.jsp by clicking the X sign at the top.

11.2.1.5 Modeling the Task Outcome

Summary:

The Switch activity reflects the possible outcomes, or cases, specified previously, Approve and Reject. It also has an Otherwise case to represent other outcomes, such as errored, stale, or expired. Inside each of the cases, you can add activities to complete modeling of the business process. The copyPayloadFromTask Assign activities copy the payload back to its source.

1. Double-click OrderApproval.bpel.

2. Expand the taskSwitch Switch activity.

3. Drag and drop an Assign activity to below the copyPayloadFromTask Assign activity in the <case Task outcome is APPROVE> section of the Switch activity.

4. Double-click the Assign icon to display the Assign window.

5. Click the General tab.

6. Enter assignOrderApproval1 in the Name field.

7. Click Apply.

8. Click the Copy Operation tab.

9. Click Create and select Copy Operation.

10. Enter the following details:

    Field	Value
    From
    Type	Expression
    Expression	string('Accepted')
    To
    Type	Variable
    Variables	Select and expand Variables > inputVariable > payload > ns1:PurchaseOrder > ns1:OrderInfo > ns1:OrderComments Note: The namespace number values (for example, ns1, ns2) can vary. Use the namespace values that automatically appear.

    
    

    Note that the XPath field shows that the expression is set to

    /ns1:PurchaseOrder/ns1:OrderInfo/ns1:OrderComments
    
    

11. Click OK to close the Create Copy Operation window and the Assign window.

12. Repeat Steps 3 through 11 to create an Assign activity below the copyPayloadFromTask Assign activity in the <case Task outcome is REJECT> section. Enter the same details as described above, with the following exceptions:

    • Name it assignOrderApproval2

    • Set the Expression field to string('Rejected')

13. Repeat Steps 3 through 11 to create an Assign Activity below the copyPayloadFromTask Assign activity in the <otherwise> section. Enter the same details as described above, with the following exceptions:

    • Name it assignOrderApproval3

    • Set the Expression field to string('Rejected')

14. Drag and drop an Assign activity from the Component Palette section to below (outside) the Switch activity.

15. Double-click the Assign icon to display the Assign window.

16. Click the General tab.

17. Enter setOutputVariable in the Name field.

18. Click Apply.

19. Click the Copy Operation tab.

20. Click Create and select Copy Operation.

21. Enter the following details:

    Field	Value
    From
    Type	Variable
    Variables	Expand and select Variables > inputVariable > payload > ns1:PurchaseOrder Note: The namespace number values (for example, ns1, ns2) can vary. Use the namespace values that automatically appear.
    To
    Type	Variable
    Variables	Expand and select Variables > outputVariable > payload > ns1:PurchaseOrder

    
    

22. Click OK to close the Create Copy Operation window and the Assign window.

    The process looks as follows:

    
    Description of the illustration wf_orderapproval1_2.gif
    
    

23. Select Save from the File main menu.

24. Click the - sign to close the taskSwitch Switch activity.

11.2.1.6 Validating, Compiling, and Deploying the Order Approval Process

1. Go to the Application Navigator section.

2. Right-click OrderApproval.

3. Select Deploy > my_integration_server_connection > Deploy to default domain.

   This compiles the BPEL process. Check for errors by clicking the buttons at the bottom of the window. If there are no errors, deployment was successful. If deployment was unsuccessful, see Step 4.

11.2.1.7 Running the Order Approval Process

1. Log into Oracle BPEL Control by selecting Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > BPEL Control (or refresh the page if it is already open).

   The Dashboard tab of Oracle BPEL Control appears.

2. Enter the following details to log into Oracle BPEL Control and click Login:

   Field	Value
   Username	oc4jadmin
   Password	password

   
   

   Where password is the value you entered during installation.

   All services are running if the TaskActionHandler and TaskManager services appear in the Dashboard tab.

3. Click OrderApproval in the Deployed BPEL Processes list.

4. Enter details in all fields of the HTML Form. You can also use a text editor to copy and paste these details from the contents of the OrderBookingPO_1.xml file:

   Note:

   Do not copy and paste from Internet Explorer or Mozilla Firefox. You must use a text editor to perform this task.

   1. Click the XML Source radio button.

   2. Copy and paste the contents of OrderBookingPO_1.xml into the field that appears.

5. Click Post XML Message.

   The BPEL Processes tab displays a message similar to the following:

   Test Instance Initiated
   
   

6. Click the Instances tab at the top.

7. Click the OrderApproval instance.

   A message appears indicating that the instance is active.

8. Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > Sample Worklist Application to access the login window for Oracle BPEL Worklist Application:

9. Log in as jcooper/welcome1.

   This displays Oracle BPEL Worklist Application. A task waiting to be approved appears.

10. Select Claim in the Actions list for the task to approve.

11. Click Go.

    The task details and payload information appear. Since this task is configured to be approved by two users, the task is routed to jstein, the manager of jcooper if it is accepted. If the task is rejected, the OrderApproval process identifies the task as rejected and completes processing.

12. Review the information. For example, the following information appears if you copied and pasted in the contents of OrderBookingPO_1.xml.

    
    Description of the illustration wf_worklist.gif
    
    

13. Select Approve from the Task Action list and click Go.

14. Log out as user jcooper.

15. Log into Oracle BPEL Worklist Application as jstein/welcome1.

16. Select Approve from the Actions list and click Go.

    After processing, no tasks appear in Oracle BPEL Worklist Application.

17. Log out.

18. Return to Oracle BPEL Control.

19. Click the Instances tab at the top.

20. Click the OrderApproval instance.

    A message appears indicating that the instance has completed.

21. Click the Audit and Flow links to observe additional details about the completed OrderApproval process.

11.2.2 Creating a Partner Link for the Order Approval Service

Summary:

You now create a partner link for the OrderApproval service.

1. Ensure that you are in the OrderBooking process.

2. Double-click OrderBooking.bpel.

3. Select Services from the Component Palette section.

4. Drag and drop a PartnerLink activity from the Component Palette section onto the right side of the designer window.

5. Enter the following values to create a partner link for the OrderApproval service:

   Note:

   For the WSDL File field below, click the flashlight (the second icon from the left named Service Explorer) to access the Service Explorer window for automatically selecting the OrderApproval service.

   Field	Value
   Name	POAService
   WSDL File	Access this URL by clicking the Service Explorer flashlight icon and expanding and selecting BPEL Services > my_ integration_server_connection > processes > default > OrderApproval http://localhost:8888/orabpel/default/OrderApproval/OrderApproval?wsdl See Also: "Setting the Hostname in Your Oracle JDeveloper Web Browser Preferences" if you receive a parsing error when attempting to add a WSDL file in the Service Explorer window.
   Partner Link Type	OrderApproval
   Partner Role	OrderApprovalProvider
   My Role	OrderApprovalRequester

   
   

6. Click OK.

7. Select Save from the File main menu.

11.2.3 Creating a Scope Activity

Summary:

You now create a Scope activity to group all activities that form a logical step to be executed.

1. Drag and drop a Scope activity from the Component Palette section to below the SelectSupplier Switch activity.

2. Double-click the scope icon to display the Scope window.

3. Enter UserApproval in the Name field of the General tab.

4. Click OK.

   In this phase of the tutorial, you create the Invoke, Receive, and Assign activities inside this Scope activity.

5. Click the + sign to expand the Scope activity.

6. Select Save from the File main menu.

11.2.4 Creating Invoke and Receive Activities

1. Drag and drop an Invoke activity from the Component Palette section into the UserApproval Scope activity.

2. Double-click the Invoke icon to display the Invoke window.

3. Enter the following details:

   Field	Value
   Name	invokePOAService
   Partner Link	POAService

   
   

   The Operation (initiate) field is automatically filled in.

4. Click the first icon to the right of the Input Variable field. This is the automatic variable creation icon.

5. Click OK on the Create Variable window that appears.

   A variable named invokePOAService_initiate_InputVariable is automatically created in the Input Variable field. This variable is automatically assigned a message type of OrderApprovalRequestMessage.

6. Click OK.

7. Drag and drop a Receive activity to below the invokePOAService Invoke activity inside the UserApproval Scope activity.

8. Double-click the Receive icon to display the Receive window.

9. Enter the following details:

   Field	Value
   Name	receivePOAService
   Partner Link	POAService

   
   

   The Operation (onResult) field is automatically filled in.

10. Click the first icon to the right of the Variable field. This is the automatic variable creation icon.

11. Click OK on the Create Variable window that appears.

    A variable named receivePOAService_onResult_InputVariable is automatically created in the Variable field. This variable is automatically assigned a message type of OrderApprovalResponseMessage.

12. Click OK.

13. Select Save from the File main menu.

11.2.5 Creating an Initial Assign Activity

1. Drag and drop an Assign activity from the Component Palette section to above the invokePOAService Invoke activity and inside the UserApproval Scope activity.

2. Double-click the Assign icon to display the Assign window.

3. Enter assignPOADataIn in the Name field of the General tab.

4. Click Apply.

5. Click the Copy Operation tab.

6. Click Create and select Copy Operation to display the Create Copy Operation window.

7. Enter the following details:

   Field	Value
   From
   Type	Variable
   Variables	Expand and select Variables > inputVariable > payload
   To
   Type	Variable
   Variables	Expand and select Variables > invokePOAService_initiate_inputVariable > payload

   
   

8. Click OK to close the Create Copy Operation window and the Assign window.

9. Select Save from the File main menu.

11.2.6 Creating a Second Assign Activity

1. Drag and drop an Assign activity from the Component Palette section to below the receivePOAService Receive activity and inside the UserApproval Scope activity.

2. Double-click the Assign icon to display the Assign window.

3. Enter UserResponse in the Name field of the General tab.

4. Click Apply.

5. Click the Copy Operation tab.

6. Click Create and select Copy Operation to display the Create Copy Operation window.

7. Enter the following details:

   Field	Value
   From
   Type	Variable
   Variables	Expand and select Variables > receivePOAService_onResult_InputVariable > payload > ns1:PurchaseOrder > ns1:OrderInfo > ns1:OrderComments Note: The namespace number values (for example, ns1, ns2) can vary. Use the namespace values that automatically appear.
   To
   Type	Variable
   Variables	Expand and select Variables > inputVariable > payload > ns1:PurchaseOrder > ns1:OrderInfo > ns1:OrderStatus

   
   

8. Click OK.

9. Click Create and select Copy Operation in the Copy Operation tab again to display the Create Copy Operation window.

10. Enter the following details to create a second statement:

    Note:

    Instead of manually entering an expression, you can press Ctrl and then the space bar in the Expression field. Scroll through the list of values that appears and double-click the value you want. Edit the value as necessary. As you enter information, a trailing slash can appear. This means you are being prompted for additional information. Either enter additional information, or press the Esc key and delete the trailing slash to complete the input of information.

    Field	Value
    From
    Type	Expression
    Expression	concat(bpws:getVariableData('inputVariable','payload','/ns1:PurchaseOrder/ns1:OrderInfo/ns1:OrderComments'), ', User Review Complete')
    To
    Type	Variable
    Variables	Expand and select Variables > inputVariable > payload > ns1:PurchaseOrder > ns1:OrderInfo > ns1:OrderComments

    
    

11. Click OK to close the Create Copy Operation window and the Assign window.

    When complete, the designer window looks as follows:

    
    Description of the illustration obph10.gif
    
    

12. Click the - sign to close the UserApproval Scope activity.

13. Select Save from the File main menu.

11.2.7 Validating, Compiling, and Deploying the Order Process

1. Go to the Application Navigator section.

2. Right-click OrderBooking.

3. Select Deploy > my_integration_server_connection > Deploy to default domain.

4. Increment the version number of the project when prompted (for example, enter 1.7) and click OK.

   This compiles the BPEL process. Check for errors by clicking the buttons at the bottom of the window. If there are no errors, deployment was successful. If deployment was unsuccessful, see Step 4.

11.2.8 Running and Verifying the Order Process

1. Log into Oracle BPEL Control by selecting Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > BPEL Control (or refresh the page if it is already open).

2. Enter the following details to log into Oracle BPEL Control and click Login:

   Field	Value
   Username	oc4jadmin
   Password	password

   
   

3. Verify that the processes are deployed (OrderApproval, OrderBooking, and all other processes, including TaskActionHandler). OrderApproval uses TaskActionHandler with a more sophisticated user interaction flow compared to the simpler TaskManager used by SelectManufacturing.

4. Start the correct OrderBooking version instance in one of the following ways:

   • Copy SOA_Oracle_Home\bpel\samples\tutorials\127.OrderBookingTutorial\PracticeFiles\OrderBookingPO_1.xml to a temporary directory (drive_letter:\temp on Windows operating systems or /temp on Unix operation systems).

   • Click the process and provide input to the default graphical user interface page in either of the following ways:

     • Enter details in all fields of the HTML Form and click Post XML Message.

     • Click the XML Source radio button. Use a text editor to copy and paste the contents of the OrderBookingPO_1.xml file into the field that appears. Click Post XML Message.

       Note:

       Do not copy and paste from Internet Explorer or Mozilla Firefox. You must use a text editor to perform this task.

     • Open the provided CreateOrderBookingUI application at http://localhost:8888/CreateOrderBookingUI and provide inputs to initiate a process.

5. Verify that the OrderBooking process has started.

6. Provide a price quote for SelectManufacturing from the following graphical user interface:

   http://localhost:8888/SelectManufacturingUI
   

   After providing a quote, watch the process instance execute and invoke the user approval service at OrderApproval. Go to Oracle BPEL Control and verify that the OrderApproval process and TaskActionHandler process have both started.

7. Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > Sample Worklist Application to access the login window for Oracle BPEL Worklist Application.

8. Log in as jcooper/welcome1. Default users are provided at install time in the following configuration file:

   SOA_Oracle_Home\bpel\system\appserver\oc4j\j2ee\home\config\jazn-data.xml
   
   

   
   Description of the illustration obph10bpm1.gif
   
   

   The list shows the task awaiting user actions.

9. Select Claim in the Actions list and click Go to claim a task.

10. View the task details, the comments section, and so on.

11. Approve or reject the task by selecting Accept or Reject from the Task Action list, and click Go.

12. Log out of user jcooper. Rejects go directly back to the process, while approved tasks require the next level of approval.

13. Log in as jstein/welcome1 (the default manager of jcooper in the hierarchy defined in the jazn-data.xml configuration file listed in Step 8).

    The list shows the task awaiting user actions.

    
    Description of the illustration obph10bpm3.gif
    
    

14. View the task details, the comments section, and so on.

15. Approve or reject the task in the Actions list and click Go.

    After the jstein comments, the approved tasks of jcooper are returned to the process.

16. View Oracle BPEL Control, database tables, or temporary directory you specified (drive_letter:\temp on Windows operating systems or /temp on Unix operation systems) for completion of the process (as examined in previous tutorial phases).

11.3 Summary

You have now added user tasks to handle the manual approval or rejection of a purchase order. This phase extended the previous project steps by calling an external manual service through human task capabilities. It included a call out to another service that handled human tasks and used predefined (default) graphical user interface screens for user actions. You performed the following key tasks:

• Created a new BPEL process named OrderApproval.

• Designed the BPEL process to add workflow functionality to handle the manual approval or rejection of a purchase order.

• Deployed the OrderApproval BPEL process.

• Ran the OrderApproval BPEL process from Oracle BPEL Control.

• Accessed the Oracle BPEL Worklist Application URL to approve the order.

• Returned to the OrderBooking BPEL process and created a partner link (named POAService) that interacted with the OrderApproval BPEL process.

• Designed the BPEL process to invoke POAService.

• Deployed the OrderBooking BPEL process.

• Ran the OrderBooking BPEL process from Oracle BPEL Control.

• Accessed the Oracle BPEL Worklist Application URL to approve the order.