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 new ReviewActivities Sequence container.
Your process should now look similar to this:

Delete the InvokeLoanApprover activity.
In the Outline view expand the Partner Links section, right-click on the LoanApproval node and delete it.

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. We can accomplish this using an Assign containing a Copy Operation.

Within the Process Variables view, you can create a Copy Operation automatically. The copy operation that we will create will copy a literal value to the approval process variable.

Display the Process Variables view, which is stacked next to Interfaces view.
Right-mouse click the approval variable, and select Open.
Right-mouse click the approval message, and select Copy > To, as the illustration shows.

Note: The Copy > To option means create the TO side of the Copy Operation.

In the Copy Operations dialog, complete the FROM part as follows:

Select Literal from the Type list.
Select the XML Builder button.
In the Preferences dialog, notice that the matching data type, loanApprovalResponse, is selected as the Root Element. The element-based approval message is a single part element.
Select Finish.

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.

Click OK, and you will see a new Assign activity in the Process Editor. The activity is in the upper left corner.
Move the Assign activity in to the ReviewActivities sequence before the UnderReviewResponse activity.
Rename the Assign to Acknowledge.

Adding Human Interaction

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

Step 1. Create the People Activity and Task

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

From the Interfaces view, in the Port Types section, expand the LoanApproval port type and drag the approve operation to the canvas and drop in to the ReviewActivities sequence after the UnderReviewResponse activity.
Select BPEL for People Activity with task (two-way operation only):

Press Next.
Complete the operation wizard with these instructions:

Accept the defaults for the Task dialog
Use the existing Input variable creditInformation.
Create a new Output variable named approve-task:

Press Finish.
Note: If the People Activity appears in the wrong place within the Sequence, simply drag and drop it into the proper location as shown below:

Change the name of the People Activity to ReviewLoan.
In the Outline view select the ReviewLoan, then select the Schedule tab in the Properties view.
Create an Expiration for the people activity by selecting the Duration radio button and entering a value of 'PT180M' for the Expression:

In the Outline view select the approveTask, then select the Task tab in the Properties view and set the following properties:

Priority: 3

In the Outline view select the approveTask, then 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

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

Presentation URI: project:/HumanApproval/xsl-renderings/loan_taskdetail.xsl
Command URI: project:/HumanApproval/xsl-renderings/loan_param2commands.xsl

Note: You can generate the Inbox XSL by selecting the Create XSL button. In our case we are using our own modified XSL for the Inbox rendering.

In the Properties view select the All tab, select the Parameters properties and set the following parameters:

Parameter	Type	Expression
loansummary	string	concat( htd:getInput('Document')/loan:lastName , ", ", htd:getInput('Document')/loan:firstName , "; $" ,htd:getInput('Document')/loan:amountRequested )

Your completed dialog should look similar to this:

In the Properties view select the All tab, select the Delegation properties and set the following parameters:

Type: Literal
Value: use the following contents:

<ht:organizationalEntity xmlns:ht="http://www.example.org/WS-HT" xmlns:wsht="http://www.example.org/WS-HT">
    <ht:groups>
        <ht:group>loanreps</ht:group>
        <ht:group>loanmgrs</ht:group>
    </ht:groups>
</ht:organizationalEntity>

Step 2. Defining Task Owners and Administrators

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.

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.

From the Outline view right-click on Human interactions > Add > Human Interaction > Logical People Group

From the Properties view define a group name loanmgrs.
To add sample users to the new group select the All tab in the Properties view and press the ellipses button (...) next to the People Group Value property:

On the Organizational Entity Definition dialog press the Generate User button to generate sample XML that can be modified to define some sample users for the group. Modify the generated XML to define two users, loanmgr1 and loanmgr2 as shown here:

Press the OK button to save the changes.
Repeat steps 1-5 to create a new Logical People Group named loanreps with the following two users:

loanrep1
loanrep2

Step 3. Bind the Task Owners and Administrators to the Task

Now that the Logical People Groups have been defined we need to assign those groups to the in-line task that was created in our People activity.

In the Outline view select the approveTask, then select the Assignment tab in the Properties view:

By clicking on the ellipses button (...) next to Potential Owners and Business Administrators you can assign the role of loanreps to Potential Owners and loanmgrs to Business Administrators resulting in the following:

Set the Task Initiator property to use a value of "Loan Process" by clicking on the ellipses button (...) then

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

Save the process.

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 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 presses the ellipses button (…) and set the duration expression shown below:

Repeat steps 1-4 and create a completion deadline 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 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 FiveMinuteReminder.

In the Outline view expand the FiveMinuteReminder node and select the child node labeled N1.
In the Properties view select the Notification tab and set the following properties:

Name: ReminderToReps
Priority: 2
Interface Port Type: loanhuman:LoanApprovalPeople
Interface Operation: remind

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 5 minutes. Please go to your inbox and claim if appropriate.

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 Properties view select the All tab, select the Parameters properties and set the following presentation parameters:

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

Your completed dialog should look similar to this:

Press OK.

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.
n the Outline view expand the FiveMinuteReminder 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
Interface Port Type: loanhuman:LoanApprovalPeople
Interface Operation: remind

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

That's it. The People activity is now complete with escalations and notifications.

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

From the Interfaces view, in the Partner Link Types section, expand the LoanCRMLT partner link type and drag the notify operation to the canvas and drop in to the ReviewActivities sequence after the ReviewLoan activity.
Select Invoke for the Activity Type.

Press Next.
Choose the Create new Partner Link option, set the Name to LoanCRMLT and the Location to Process.

Press Next.
Choose the Use existing Variable option and make sure that approve-task is selected.

Press Finish.
In the Properties view set the Activity Name to NotifyCustomerServiceOfDecision.
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 handlilng 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 Interfaces view, in the Partner Link Types section, expand the LoanCRMLT partner link type and drag the notify operation inside the new Catch acvitiy.

Select Invoke for the Activity Type and press Next.
Accept the default to Use existing Partner Link and ensure that LoanCRMLT is selected from the drop-down list.
Use an existing Variable for the Input Variable dialog but change the value to approve-task.
Press Finish.
In the Properties view set the Activity Name to: NotifyCRMOfExpiration.

Create an Assign activity in the fault handler before the NotifiyCRMOfExpiration activity and set 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
Part: Document

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 simuate 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 statisfied 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 properites 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 LoanCRMLT partner link by clicking on the LoanCRMLT row and set the following properties:

Invoke Handler: WSA Address
Endpoint type: static
Press the ellipses (...) button next to the textarea labeled Endoint Reference to open the Endpoint Rerenece 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 Endoint Reference to open the Endpoint Rerenece 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.