Human Approval Sample

The purpose of this sample is to provide a detailed set of instructions for adding human interaction in the loan approval sample that is used in the ActiveVOS Tutorial. To create the human interaction of approving a loan, we will leverage WS-BPEL Extension for People and WS-Human Task. The starting point for this sample will be the completed project that is built when you run through the steps of the ActiveVOS Tutorial. Even though this sample is self-contained we recommend that you complete the ActiveVOS Tutorial since it describes the loan process activities and how to use the ActiveVOS Designer in greater detail.

Getting Started

To start we are going to create a new orchestration project based on the Human Approval sample template. By using this template we will create a new orchestration project which includes a complete loan approval process as a starting point that we will then modify by adding human interaction.

Step 1. Create a new Orchestration Project

Open the ActiveVOS Designer and select File > New > Orchestration Project from the main menu.
Enter a value of HumanApproval for the Project name and press Next.

Select Human Approval from the list of ActiveVOS Samples to use the Human Approval template.

Press Finish.

Preparing the process for Human Interaction

The process that we will begin with is based on the Loan Approval process that is built when you complete the ActiveVOS Tutorial. During this part of the sample we are going to:

Replace the web service that determines if a loan should be approved or rejected with a people activity so that a human can make this decision
Update the logic to return an immediate acknowledgment to the loan requester if this path of the process is taken
Send a message to the Customer Service Representative once the people activity completes

Step 1. Remove the LoanApprover invoke activity

Since the decision to approve or reject a loan will now be handled by a person we will update the loan approval process by removing the call to the loan approver web service. This functionality will be replaced by a people activity.

From the Navigator view expand the bpel folder and open the loanProcessHuman.bpel process.
Open the Palette and drop a Sequence container on the canvas beneath the InvokeLoanApprover activity.
Select the Properties view for the Sequence and give it a Activity Name of ReviewActivities.
Move the target of the link labeled large loan from the InvokeLoanApprover activity and move it to the new ReviewActivities sequence container.
Move the target of the link labeled review from the InvokeRiskAssessor activity and move it to the new ReviewActivities Sequence container.
Delete the link from the InvokeLoanAppover activity to the ReturnApprovalResponse activity.
Your process should now look similar to this:

Delete the InvokeLoanApprover activity.
In the Outline view expand the Participant Partner Links section, right-click on the LoanApproval node and delete it. This will also remove the LoanApproval participant from the Participants view.

Step 2. Send an acknowledgment to the loan requester

Before we invoke the people activity it makes sense to reply back to the loan requester that the loan is now going in to a human review cycle. We can accomplish this by adding a Reply activity.

Copy the ReturnApprovalResponse activity and drop it in to the ReviewActivities sequence.
Rename this activity to ReturnUnderReviewResponse.

Step 3: Create the message used in the acknowledgment

Before we send the Reply to the loan requester we need to format a message indicating that the loan is now under review. To accomplish this by defining the Data properties associated with the Reply activity. This implicitly builds an Assign statement that initializes the required message variable.

Select the ReturnUnderReviewResponse activity.
In the Properties view for this activity, select the Data tab.
In the Assignment dropdown, select XPaths.
Press the Add button to create a new XPath copy expression.
Edit the XPath expression as follows:

In the first column headed E/L (for Expression/Literal), select L (for Literal). A generated default literal value will appear in the From column.
Edit the literal value in the From column by clicking on it and clicking the ... button that appears there:
In the Literal Contents dialog box that appears, change the following values in the generated XML to match the contents displayed below.

Change the value in the <loan:responseToLoanRequest> element to underReview
Remove the value of string in <loan:responseDescription>
Because it is not needed, you can delete the optional <loan:rejectionReason> ...</loan:rejectionReason> element.

Because we are allocating a literal value for the entire content of the approval variable, we don't need to specify a value for the To Path part of the Assignment.

Adding Human Interaction

After the acknowledgment is sent to the loan requester we can add the People activity to the process.

Step 1. Add the LoanApproval Human Task Participant and Task Owners and Administrators.

To create the human interaction of approving a loan, we will leverage WS-BPEL For People and WS-Human Task.

It was decided that a group called loanreps will be allowed to claim and work on the tasks, while a group called loanmgrs would be administrators (who can escalate and reassign tasks). In BPEL, we refer to these as Logical People Groups. They are added in the Participants view under Human Task Participants.

Logical People Group definitions will need to be defined for both loanreps and loanmgrs, and then the groups can be associated with the proper role for the task.

In the Participants view, right click Human Task Participants, and select New Human Task Participant. A new participant role, named Role1, will be added to the Participants view.
Select Role1 so that it is displayed in the Properties View. Edit the value for Name from Role1 to loanreps. Later, when we define a deployment descriptor for the process, we will associate this Logical People Group name with an actual set of users that our configured Identity Service will resolve at runtime.
Repeat 1 through 2 above to add a second Logical People Group, this time naming it loanmgrs.

Step 2. Create the loan approval Human Task.

Now that we have declared the Logical People Groups, we are able to define the tasks. We start with WSDL defining the interactions. We will reuse the LoanApproval WSDL that we removed from the process earlier, but this time it will provide definitions for interaction with a human instead of a service.

In the Participants view, right click the loanreps Logical People Group, and select New Human Task... . The Human Task dialog opens, showing available port types. Remember that in WS-BPEL For People, people activities are just another type of service interaction, and they are declared in WSDL.
Expand the LoanApproval port type to display the approve operation, select it and press OK. A new task will appear in the Participants view, under loanreps, called Task1.
Select Task1 so that is displayed in the Properties view. Edit the value of the Name property to approveTask.
Display the properties for the approveTask task in the Properties view. You can do this by selecting the approveTask task in the Participants view or in the Outline view.
Select the Task tab and set the following properties:

Priority: 3

Select the Presentation tab in the Properties view and set the following properties:

Display Name: Loan for review
Subject: Please look at this loan and approve or decline it. (for {$loansummary})
Type: default

Still at the Presentation tab, we will now define the loansummary substitution variable that we referenced in the value for Subject:

Press the ellipsis button at the right of the panel.
In the Presentation Parameters dialog that appears, press Add to add a new parameter. A new parameter called param1 and of type string will appear.
Click on the Parameter name to make it editable, and key in loansummary.
Leave the Type as string.
Click on the Expression to make it editable, and enter the following value:
concat( htd:getInput('Document')/loan:lastName , ", ", htd:getInput('Document')/loan:firstName , "; $" ,htd:getInput('Document')/loan:amountRequested )
Your dialog should look similar to this:

Step 3. Complete Binding the Task Owners and Administrators to the Task

The Potential Owners Role was automatically set to loanreps when you created the task, but now we will assign other users to some of the other task roles. We will assign the loanmgrs Logical People Group to the Business Administrators role, and we will also assign the literal value Loan Process to the Task Initiator role.

Select the Assignment tab and set the value for Business Administrator to loanmgrs as follows:

Click in the Value column for Role Name Business Administrator. An ellipsis button will appear. Click it to display the Role dialog.
In the Role dialog, select Logical People Group in the Type dropdown.
In the Group dropdown, select loanmgrs, and press OK.

Still at the Assignment tab, set a value for Task initiator as follows:

Click in the Value column for Role Name Task Initiator. An ellipsis button will appear. Click it to display the Role dialog.
In the Role dialog, select Literal in the Type dropdown.
Press the Generate... button to generate XML for a user.
Edit the value of the ht:user element to say Loan Process.
Your dialog should look like this:

Step 4. Setting Task Deadlines

You can specify one or more deadlines by which a task must be started and also one or more deadlines by which a task must be completed. If a particular start date or completion date is missed, you can trigger one or more escalation actions. For example, if you set a start the task deadline for two hours after a task has been created and the deadline is missed, you can send a notification to the task owner. We are going to set the following deadlines:

A start deadline that will be triggered if the task is not claimed and started by a loanrep within 2 hours
A completion deadline that will be triggered if the task is not completed by a loanrep within 130 minutes

Step 4a. Setting the Start Deadline

From the Participants view or the Outline view select the approveTask node and select the Deadlines tab in the Properties view.
Click the Add button and set the following properties:

Press OK.
Click in the blank value under the Expression column and press the ellipses button (…) and set the duration expression shown below:

Repeat steps 1-4 and create a completion deadline with a Duration Alarm Type for 10 minutes later ('PT130M')
The two task deadlines appear in the Properties view as shown here:

In the Outline view select the Start Deadline and select the Escalations tab in the Properties view.
Select the Inline Notification labeled InlineNofication1 and press the Go To button.
In the Properties view select the Notification tab and change the name to TwoHourReminder.

In the Outline view expand the TwoHourReminder node and select the child node labeled N1. This is the where we define the escalation action that will be triggered if the deadline is reached.
In the Properties view select the Notification tab and set the following properties:

Name: ReminderToReps
Priority: 2

Press the ellipsis button to the right of the Notification Interface field.

In the Notification Interface dialog that appears, navigate to the LoanApprovalPeople port type, and select the remind operation. The remind operation is a one-way operation that we will use to notify the loanreps that a loan application has been waiting for review for two hours.
In the Properties view select the Presentation tab and set the following properties:

Display Name: Unclaimed Task reminder
Subject: There is a loan task waiting to be claimed. ({$lastname}, {$firstname}; ${$amount} priority {$priority})
Description Type: default
Description Content: A loan review has been unclaimed for 2 hours. Please go to your inbox and claim if appropriate.

In the Properties view select the Presentation tab, press the ellipsis to the right of the Subject field, and set the following presentation parameters:

Parameter	Type	Expression
firstname	string	htd:getInput('Document', 'approveTask')/loan:firstName
lastname	string	htd:getInput('Document', 'approveTask')/loan:lastName
amount	string	htd:getInput('Document', 'approveTask')/loan:amountRequested
priority	string	htd:getTaskPriority()

Your completed dialog should look similar to this:

Press OK.

In the Properties view select the Assignment tab and set the properties as shown in the below by pressing the ellipses (...) button in the Value column:

Step 4b. Setting the Completion Deadline

In the Outline view select the Completion Deadline and press the Escalation tab in the Properties view.
Select the Inline Notification labeled InlineNofication1 and press the Go To button.
In the Properties view select the Notification tab and change the name to EscalateIfNotActedUpon.
In the Outline view expand the EscalateIfNotActedUpon node and select the child node labeled N1.
In the Properties view select the Notification tab and set the following properties:

Name: NotifyReassignToManager
Priority: 1
Notification Interface: remind/LoanApprovalPeople

In the Properties view select the Presentation tab and set the following properties:

Display Name: Escalated To Manager
Subject: This loan is being reassigned to loanmgr1 for review
Description Type: default
Description Content: Needs to be completed within 10 minutes!

In the Properties view select the Assignment tab and set the properties as shown in the below by pressing the ellipses (...) button in the Value column:

In the Outline view select the Completion Deadline and press the Escalation tab in the Properties view.
Press the Add button and specify Reassignment for the Escalation Type:

Select the Reassignment labeled Reassignment1 and press the Go To button.
In the Properties view select the Reassignment tab and change the name to ReassignToMgr1.
In the Properties view select the Assignment tab and set the properties by pressing the ellipses (...) button in the Value column:

Select Literal for the Type.
Press the Generate... button
Change the value in <ht:user> from Some User to loanmgr1

Press OK.

Step 5. Setting Task Renderings

ActiveVOS Designer can create default XSL stylesheets that will be used to render the task information in the ActiveVOS Inbox screens. You can edit these stylesheets to customize how task information is presented to the user in the Inbox application.

In the Properties view, select the Renderings tab:

The Create XSL button presents a dialog showing the stylesheet files it will create. If you ask ActiveVOS Designer to create stylesheets for you, they will be placed in the xsl subfolder of your project, and the values for Presentation URI and Command URI will be populated for you.
In our case, however, we are using our own modified XSL for the inbox rendering. These xsl stylesheets already exist in the xsl subfolder of the project. Using the browse buttons on the right, navigate to the following locations and select the following values:

Presentation URI: project:/HumanApproval/xsl/loan_taskdetail.xsl

Command URI: project:/HumanApproval/xsl/loan_param2commands.xsl

That's it. The task is now complete with escalations, notifications, and rendering information. All that remains is to create a People Activity based on the task, and to place it in the process.

Step 6. Creating the People Activity

Now that we have defined the human task, the last step is to create a people activity in the process that uses the task. Although we have already defined most of the details of the human interaction through setting properties associated with the task, the people activity has a few properties of its own as well, and we will set those to appropriate values.

In the Participants view, select the approveTask. Drag it from the Participants view to a position inside the ReviewActivities sequence, directly under the ReturnUnderReviewResponse activity. When a horizontal bar appears underneath the ReturnReviewResponse activity, release the mouse button to drop the new people activity activity in place:
The people activity appears on the canvas. The activity is named by default the same as the underlying task, approveTask:
Select the people activity, and the associated Properties view. Edit the properties for the activity as follows:

On the People Activity tab:

Change the name to ReviewLoan

On the Input tab:

In the Assignment dropdown, select Single Variable.
In the Variable dropdown, select creditInformation.

On the Output tab:

In the Assignment dropdown, select Single Variable.
In the Variable dropdown, declare a new output variable as follows:

select New Variable... and assign the following values:

Variable Name: approve-task

Scope - accept the default value of Process

Variable Type - accept the default value of Element

On the Assignment tab, no changes are required. Note that the role assignment information that was entered during task definition has been propagated to the people activity automatically. It can be overridden here if desired.
On the Schedule tab:

The schedule tab allows you to control when the activity is executed, and how long it is allowed to take. These parameters are separate from the escalation deadlines that are part of the task definition, and all are taken into account at runtime.
Set the Expression for Expiration for the Task:

Select Duration, and enter 'PT180M' for the maximum allowed duration for the people activity.

We have now completed the definition of both a human task for loan application review, and a people activity using that task. We added the people activity to the process at the appropriate location. In the final part of the process, we will notify our Customer Service Department of the loan approval decision, so that they can inform the customer.

Completing the Human Review

In this section we will update the loan approval process by invoking a web service that will notify the Customer Service Department of the status of the loan.

Step 1. Notify Customer Service of Decision

In the Participants view, right click Partner Service Providers to create a new Partner Service Provider. Navigate to the notify operation of the LoanCRM port type, select it, and press OK.
The LoanCRM port type is added to the Participants view with the default name Provider. Highlight this entry in the Participants view, and change the Name value to CustomerService.
The value in the Service Interface property will show something like ns3:LoanCRM. For readability, let's rename the namespace to something more meaningful. In the Outline view, expand the Namespaces node, and select ns3 (or whatever namespace value appears in the Service Interface property for LoanCRM in your process). On the properties sheet for the namespace, change the Name to crmws. Save the process.
We are now ready to add the invoke to the process. In the Participants view, expand the CustomerService provider and select the notify operation. Drag it to the canvas and drop it into the ReviewActivities sequence container, as the last activity (after the ReviewLoan people activity). A new invoke activity will appear, with the default name notify.

Edit the properties of the invoke as follows:

At the Invoke tab:

Name: NotifyCustomerServiceOfDecision

At the Input tab:

Assignment: Single Variable
Variable: approve-task

Press Finish
Save your process. Your process should now look similar to this:

The modifications to the process are now complete.

Updating Fault Handling

In this section we will update the fault handling of the original loan approval process to handle an expired human task.

Step 1. Notify Customer Service if the human task has expired

Select the Fault Hanlders tab.
From the Palette drag a Catch activity and drop it on the canvas.
In the properties view set the following properties:

Fault Name: b4p:taskExpired (you can use the ellipses... button and select this)

From the Participants view, in the Partner Service Providers section, expand the CustomerService provider and drag the notify operation inside the new Catch activity.

In the Properties view, at the Invoke Tab, set the Activity Name to: NotifyCRMOfExpiration.
At the Input tab, select Single Variable and select variable approve-task from the Variable dropdown.

Create an Assign activity in the fault handler before the NotifyCRMOfExpiration activity and add (using the ellipsis button) a Copy operation with the following properties:

From Type: Literal
Literal Contents:

<loan:loanApprovalResponse xmlns:loan="http://schemas.active-endpoints.com/sample/LoanRequest/2008/02/loanRequest.xsd">
   <loan:responseToLoanRequest>declined</loan:responseToLoanRequest>
   <loan:responseDescription>We regret that your application could not be processed under our Qik-Approve guidelines. Please reapply in person at one of our offices.</loan:responseDescription>
   <loan:rejectionReason>
      <loan:reason>infoRequired</loan:reason>
      <loan:description>Loan underwriting could not be completed in the recommended time window.</loan:description>
   </loan:rejectionReason>
</loan:loanApprovalResponse>

To Type: Variable
Variable: approve-task

In the Properties view set the Activity Name for the Assign to: CreateExpirationResponse.
Create a link from the CreateExpirationResponse to the NotifyCRMOfExpiration activity.
Your fault handler should now look similar to this:

Save your process.

Simulating the Process

Now that the process is complete it would be a good time to simulate the execution of the process prior to deploying and running the process live on the server. Detailed instructions for simulating the Loan Process are described in Tutorial Part 8: Simulating the Process of the ActiveVOS Tutorial so they are not repeated here. Once you are satisfied that your process behaves as expected you can turn your attention to deploying the process and running it on the ActiveVOS Server.

Preparing for Deployment

In this section we will prepare the process for deployment by creating the Process Deployment Descriptor (.pdd) file. For more information on the deployment please refer to the Deploying your Processes chapter in the ActiveVOS Designer Help system.

Step 1: Create a process deployment descriptor

A Process Deployment Descriptor (.pdd) file describes the relationship between the partner links defined in the BPEL file and the implementation required to interact with actual partner endpoints. You create a .pdd file to add address information about your endpoint references. The .pdd file is an integral part of the deployment package for the process.

In the Navigator view right-click on the loanProcessHuman.bpel process and New > Deployment Descriptor to open the New Deployment Descriptor dialog.
Select the deploy folder, and press Finish, as shown.

The loanProcessHuman.pdd file is opened in the PDD editor as shown below. Notice that the properties of the General tab are displayed.

Accept the defaults on the General tab and press the Partner Links tab to define the bindings to the web services called by the process.

Set the runtime bindings for the CustomerService partner link by clicking on the CustomerService row and set the following properties:

Invoke Handler: WSA Address
Endpoint type: static
Press the ellipses (...) button next to the textarea labeled Endpoint Reference to open the Endpoint Reference dialog
Select the loanCRM.wsdl file from the WSDL: dropdown list.

Press OK.
Notice that the Endpoint Reference information is now filled in using the values contained in the loanCRM.wsdl file:

Set the runtime binding information for the RiskAssessment partner link by selecting the RiskAssessment row and set the following properties:

Invoke Handler: WSA Address
Endpoint type: static
Press the ellipses (...) button next to the textarea labeled Endpoint Reference to open the Endpoint Reference dialog
Select the riskAssessment.wsdl file from the WSDL: dropdown list.

Press OK.
Notice that the Endpoint Reference information is now filled in using the values contained in the riskAssessment.wsdl file:

Next set the runtime binding information for the LoanProcess partner link by selecting the LoanProcess row and setting the following properties:

Binding: Document Literal
Service: LoanProcessServiceHuman
Notice that the Endpoint Reference information is now complete:

The final step is to bind the Logical People Groups to actual server roles. Select the People tab and set the following properties:

Expand the Master Section on the left side of the dialog and select the loanmgrs.
Select Static from the Type: dropdown list.
Select the Groups radio button.
Press the Add... button
Enter a value of loanmgrs.
Press OK.
Repeat the previous steps to set a static group named loanreps for the loanreps Logical People Group.

Save the file.

Running the Process on the Server

Your process is now ready to be deployed. Deployment is the act of publishing your BPEL process to the ActiveVOS server where it can run. Once the process is deployed you can run it on the server. The steps for deployment and running the process on the server are defined in the Human Approval Completed documentation.