Working with Human Workflow in SOA 12c

Human workflow in SOA allows a manual action to be performed on a pending or running business process before it can proceed further. This workflow is mainly used to aid the functionality of taking business decisions at run time.

In this blog, we would see an example of how to work with human workflow/tasks in SOA 12c.

Our use case is a simple leave approval process, where the leave requests are submitted to manager for approval. The manager can then manually approve/reject/defer the request.

How to create the project:

1. Create an empty SOA composite project. I have named mine as PGHumanWorkflowProject.

2. I have created a simple LeaveApplication.xsd for the project. It goes something like this. The request element - LeaveRequest has 3 fields to convey the details of the leave. The response element LeaveResponse has only one field RequestStatus which provides the status of the leave request once an action has been performed on it.


<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="www.pgservices.com/leaveapplication"
            targetNamespace="www.pgservices.com/leaveapplication" elementFormDefault="qualified">
  <xsd:element name="LeaveRequest">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="NoOfDays"/>
        <xsd:element name="Reason"/>
        <xsd:element name="TypeOfLeave">
          <xsd:simpleType>
            <xsd:restriction base="xsd:string">
              <xsd:enumeration value="Earned Leave"/>
              <xsd:enumeration value="Sick Leave"/>
              <xsd:enumeration value="Loss of Pay"/>
            </xsd:restriction>
          </xsd:simpleType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="LeaveResponse">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="RequestStatus">
         <xsd:simpleType>
            <xsd:restriction base="xsd:string">
              <xsd:enumeration value="APPROVED"/>
              <xsd:enumeration value="REJECTED"/>
              <xsd:enumeration value="PENDING"/>
            </xsd:restriction>
          </xsd:simpleType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>



3. Now create an Asynchronous BPEL process in the empty composite and give a name. PGHumanWFProject in my case. As this process does not receive a response until a human action is taken, an asynchronous process needs to be created.

4. Update the default input and output variables to the LeaveRequest and LeaveResponse elements from the above created schema and complete BPEL creation.

5. The auto generated wsdl looks as follows with two port types - One for invocation and other for callback.

6. Next step is to start with the Human workflow. Insert a Human Task activity in the composite.

7. In the Create Human Task wizard, provide a name and click ok.

8. Double click on the Human Task. Following screen will appear.

9. Click on the right most icon in the Task Title row. An Expression Builder window will open. Enter the title you would want for the Human task. Add a meaningful description in the task window.

10. Next click on the outcome field. A dialog appears with all the options to choose. APPROVE, REJECT and DEFER are my possible outcomes. Click OK.

11. Now click the next tab in the left section which is the Data tab. Through this screen, you can map the input that needs to be passed to this Human task activity. We need to pass the Leave Request as xml to human task.

       a. Hence, click on the + icon to the right of data and choose "Add other parameter". In the Add Task Parameter, select Element button and the click on the torch next to it.

       b. Select LeaveRequest in the Type Chooser window and click ok for the two screens.

12. Click on the Assignment tab in the left section. This screen allows you to add the user who can access the leave task request. Say for example, there is a user/login named - testuser defined in administration console. You can add this user as a participant here, so that only testuser can access this request and perform any action upon it.

13. Select "Single Participant" icon from the components and drop into the drop participant section in Assignment tab as follows.

14. Click on Edit Participant for the following window to open. Under Participant Names, click on +. Select Identification Type as User, Data Type as By Name and Value as the userId whom you would want to give the access. In my case, I would want weblogic user to take action on the task created through this process.
Click on OK.

15. Now you are back to the task screen. The task has been created successfully. In the left top, you would see a button called Form. Click the Auto-Generate Task Form under Form dropdown. This will create a UI application for the form.

16. A popup would come up where you can enter the name of the UI project and then click OK.

17. An ADF webproject is created with the details you provide. Once, all the files are generated as part of the ADF project. Save and close all.

18. Back in the composite page, connect the BPEL composite to the Human Task component. Composite.xml looks as follows.

19. Open the BPEL process. Drag a Human Task SOA component and drop it below Receive activity.

20. Choose the Task Definition as the one that we created in the earlier steps and click on Ok.

21. Once, you choose Task Definition, the task screen gets loaded with the additional details. Under Task Parameters section, you would already see the Parameter as LeaveRequest. Click on the button under BPEL variable. Choose LeaveRequest element under inputVariable. This will ensure that the inputVariable element is mapped directly to the human task input.

22. Once you click OK, you will see that the BPEL has Human task component as well as Switch activities created for each of the possible outcomes chosen earlier.

As I chose, APPROVE, REJECT and DEFER as outcomes, you would see three switch branches in addition to the default branch.

23. Expand the LeaveApplnHumanTaskDefinition2 activity. You would see an invoke activity which calls the human task and receive activity which waits for the callback response once an action is taken on the request.

24. The conditions in the switch activity are already populated with appropriate conditions as follows.

25. You can also see that each sequence in the switch already has Assign activities. By default, the payload of the task response is mapped to input variable of the BPEL. You can delete that mapping.

Instead map as follows - 

The task response variable -> systemAttributes -> outcome field maps to outputVariable -> LeaveResponse -> RequestStatus.

26. Update the mappings similarly in all the sequences. In the default sequence, instead of mapping the outcome, you can just hard the RequestStatus to INVALID RESPONSE.

27. Now we are done with the BPEL project with Human task. Deploy it to the SOA server. While deployment, you would see a task flow deployment page, where you would have to select the UI project that got generated when the Human task was created. This makes sure that the SOA project is deployed along with the UI project.

Test the project:

1. Go to em console and click on the test button of this project.

2. Enter the input arguments as follows and click on Test webservice.

3. In the flow trace of the tested instance, you would see that the LeaveApplnHumanTaskDefinition is in Running state. This means that the task has been submitted and someone should act upon the request.

4. In order to perform an action on the task, login to the worklist app using the following URL. Login with the user that you added in the Add Participant tab. In my case, I added as weblogic user.

http://<serverhostname:portnumber>/integration/worklistapp

5. In the worklist app, you can see the Leave Application task as follows. Select the task and from the Actions dropdown and choose appropriate action. I choose Approve. You would see that the task vanishes from the tasks screen.

6. Now go back to the em console and open the instance that was running earlier. You would see the status of the human task as completed now

7. Click on the Task definition, you can find the Outcome as APPROVE.

 8. The BPEL response variable is also populated with the outcome as per the mapping as follows.