Working with User Tasks

This tutorial walks you through the steps you need to follow to create a form in a BPMN user task.

Let's get started!

1. Open Eclipse.
2. Under the Help menu, click Install New Software. In the resulting panel, click the Add button to add a repository and fill in the following fields:
   

    

   
   Fill in the following repository details for BPMN.
   
   • Name: BPMN 2.0 designer
   • Location: http://product-dist.wso2.com/p2/developer-studio-kernel/4.1.0/bps-tools/releases/3.6.0/
3. Click OK to add the plugin. 
4. Once the plugin is added, click Select All, and then click Next. This takes you to the Install Details panel.
5. Click Next. This takes you to the Review Licenses panel.
6. Read the license text, accept the terms of the license agreement and click Finish. You will see a message as follows:
   

   

    
7. Click Yes to restart Eclipse.
8. Once Eclipse restarts, navigate to File > New > Other. 
9. From the window that appears, select WSO2 > BPMN > BPMN Project and click Next. 

10. Provide a suitable Project Name and click Finish. 

11. Right-click on your project and navigate to New > Other.

12. From the window that appears, select WSO2 > BPMN > BPMN Diagram and click Next.

13. Select your project in the viewer and enter a File name.
     

    Tip: The following example expands on creating a business process scenario, The manager invokes an order approval process where it is possible to set the product ID. Additionally, an employee from a goods division can set the quantity and the unit price of the product. The quantity and the unit price are used to calculate the total cost. If the total cost is above 100,000, the order will have to be approved by an employee from the orderApproval Group before the order mail is dispatched. Alternatively, if the cost is below 100,000, the order mail is dispatched without approval. In this example, the process is named “OrderApproval”.

14. Click Finish. You will see a canvas to model your BPMN package. You will see that the palette is positioned on the right side of the screen. You can drag and drop models from the palette onto the canvas and do your modelling.
15. To implement the order approval process, drag and drop a StartEvent element, two UserTask elements, a MailTask element and a Terminate Event element on the canvas.
    

16. Link up the flow according to the business logic. 

    Tip: According to the business logic in this example, the Start Event should trigger the Fill Order Form User Task. So connect the Start Event to the Fill Order Form User Task.

17. In the Connection tab, select Sequence Flow. Connect the Start Event to the Fill Order Form User Task.

    Tip: It is useful to understand the condition logic for this sequence. Here, if the total cost calculated from the quantity and unit price is above 100,000 a user task has to be executed or the mail task comes into play. In order to add this condition statement, click on the Fill Order Form User Task and you will be able to see few tooltips hovering around the Fill Order Form User Task on the canvas. The diamond shape with a cross in the middle implies an Exclusive Gateway.

18. Select the Fill Order Form User Task by clicking on it and click on the Exclusive Gateway tooltip on the right of the tool.
    
19. Once you click the Exclusive Gateway, a bigger diamond with a cross in the middle should appear on the canvas next to the Fill Order Form User Task. The Fill Order Form User Task will point to it.
    
20. The rest of the flow is fairly straightforward. Use the Sequence Flow to connect the tools and the final diagram will be similar to what is shown below.
    
    After the diagram has been constructed, you must configure the properties of each element to fulfil the business logic.

21. Click on the Start Event element and set the following properties in the general tab.

    • Id: fillOrderDetails

    • Name: Enter Order Details

22. To get the order details, you must create a form to get the product ID from the manager who invokes the process. Click Form in the properties of the Start Event.
    
23. Click on the New button and use the new window as shown below to create a productID field.
     

    

    
    Ensure that you enter the following details.

    • Id: productID

    • Name: Product Id

    • Type: string

    • Variable: productID

24. Click OK. Once you have filled the form, the table in the form tab should look similar to the following.
    

    

    
    Now that the configurations for the start event have been set, you can configure the Fill Order Form User Task, which is a claimable task by the goods division, where an employee of the goods division will be able to claim and complete the form. 
25. Click on the Fill Order Form User Task. In the Properties tab, assign an Id and Name, similarly to how you assigned a Id and Name to the start event. You can use the following values.
    

    • Id: fillOrderForm

    • Name: Fill Order Form

26. Click Main Config in the Properties pane. Since there is no specific user who the task is to be assigned and anyone from the goods division can claim the task and execute it, set the Candidate Group to goodsDivision. This allows any employee under the goods division to claim and complete the task.

27. Create the form that the employee needs to fill. To do this, click on the Form tab in the Properties pane. Add the following fields in a similar manner to how you added form attributes for the start event.

    	productID	quantity	unitPrice
    Id	productID	quantity	unitPrice
    Name	Product ID	Quantity	Unit Price
    Type	string	long	double
    Variable	productID	quantity	unitPrice

    Once the above fields are added to the form, the table in your Form should look similar to the following:

    

    Note

    Once you create the form in the above manner, the variables are added to the process scope so that you can use those in any task based on your requirement.

28. Now that you have configured your Fill Order Form User Task, you can identify the two flows. There can be a default flow and a conditional flow.

    1. To assign the default flow, set an appropriate ID for the flow, which is the Sequence Flow element from the exclusive gateway to mail task. Click on this flow.
       
    2. Set the Id value as shown below:
       
29. Similarly, assign an ID to the Sequence Flow from the exclusive gateway to the Approve Order User Task.
    • Id: approveOrder
30. To set orderProduct as the default flow, do the following.
    1. Click on the exclusive gateway. 
    2. Click the General tab in the Properties pane and select orderProduct in the dropdown to assign it.
       
31. To assign the Conditional flow, click on the approveOrder Sequence Flow element, navigate to the Main Config tab. In the condition field, define the condition as ${(quantity*unitPrice) > 100000}. This is for calculating the total cost and checking if it exceeds 100,000. If it does, it will take the conditional flow.
    

    

    
     You have now configured the conditional flow. If the total cost exceeds 100,000, the flow is directed to the Approve Order User Task.

32. To configure the Approve Order User Task, do the following. 

    1. Click on the Approve Order User Task. 

    2. In the General tab, assign an appropriate ID and Name. 

    3. In the Main Config tab, you must set the Candidate Group as the “orderApproval” group, as according to the scenario, anyone from the order approval group can claim the task and complete the task. 

    4. To allow the approver to view the order details, you must create a form to display the Product ID, Quantity and Unit Price. To do this, navigate to the Form tab in the Properties pane and create the fields as show in the diagram below.

       Note: The fields are only readable.

       

33. Now you have configured the properties for the Approve Order User Task. To accommodate a scenario for the orderApproval group rejecting an order, you must add an end event to this User Task. Therefore this process can terminate at Approve Order User Task.
    
34. To configure the Mail Task, do the following. 
    1. Click on the Order Product Mail Task. In the Properties pane, select the General tab.

       • Id: mtOrderProduct

       • Name: Order Product

    2. Select the Main Config tab, and fill the respective fields (i.e., To, From, Subject). 
    3. In the non-HTML field, enter “Order ${quantity} of ${productID} at the rate of ${unitPrice}”. The variable will be used to create the mail body.
    4. Follow the instructions on the Working with the Email Task page to configure the Mail Task. 

    Note

    If you want to call a new User Task from an existing User Task when a particular event is triggered, you can add a Boundary Event.
    For example, if you want a mail to be sent when an order is not approved within a day, you can add a Timer Boundary Event in the Fill Order Form User Task as follows, so that it triggers a mail to be sent indicating that the order has not been approved:
     

    The model is now complete as the necessary logic has been applied.

35. To create the Business Archive File (.bar), do the following.

    1. On the Explorer, found in the upper left of your screen, navigate to Package Explorer. 

    2. Right click on the package and select “Create deployment artifacts”.

    3. Navigate to the location of the source. You will find the .bar file inside the deployment folder.