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 based on the project that you build when you complete 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 using 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

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



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



4. 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 "Invoke Loan Approver" 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.

1. From the Navigator view expand the bpel folder and open the loanProcessHuman.bpel process
   
2. Select the "Invoke Loan Approver" activity on the canvas, right-click and select the Delete option.
3. 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. Update the acknowledgment sent 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 updating the existing Reply activity that followed the "Invoke Loan Approver" activity that we deleted in the previous step.

1. Select the <reply> activity named Reply and rename it to Under Review.

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 accomplish this by defining the Data properties associated with the Reply activity. This implicitly builds an Assign statement that initializes the required message variable.

1. Select the Under Review <reply> activity.
2. In the Properties view for this activity, select the Data tab.
3. Change the Assignment from Single Variable to XPaths.
4. Press the Add button to create a new XPath copy expression.
5. Edit the XPath expression as follows:
• In the first column headed E/L (for Expression/Literal), select Literal.
• To generate a default literal press the ... button in the From column.
• When the Literal Contents dialog opens press the Generate... button
• Accept the default values to create the loan:loanApprovalResponse element:
  
• Change the 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.
• We also won't be using the approver variable so we can delete this variable from the Variables section in the Outline view.

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.

1. 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.
2. 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.
3. 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.

1. 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.
2. 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.
3. Select Task1 so that is displayed in the Properties view. Edit the value of the Name property to approveTask.
4. 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.
5. Select the Task tab and set the following properties:
1. Priority: 3

6. Select the Presentation tab in the Properties view and set the following properties:
1. Display Name: Loan for review
2. Subject: Please look at this loan and approve or decline it. (for {$loansummary})
3. Type: default

7. Still at the Presentation tab, we will now define the loansummary substitution variable that we referenced in the value for Subject:
1. Press the ellipsis button at the right of the panel.
2. 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.
3. Click on the Parameter name to make it editable, and key in loansummary.
4. Leave the Type as string.
5. 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 )
6. 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. 

1. Select the Assignment tab and set the value for Business Administrator to loanmgrs as follows:
1. Click in the Value column for Role Name Business Administrator. An ellipsis button   will appear. Click it to display the Role dialog.
2. In the Role dialog, select Logical People Group in the Type dropdown.
3. In the Group dropdown, select loanmgrs, and press OK.
2. Still at the Assignment tab, set a value for Task initiator as follows:
1. Click in the Value column for Role Name Task Initiator. An ellipsis button   will appear. Click it to display the Role dialog.
2. In the Role dialog, select Literal in the Type dropdown.
3. Press the Generate... button to generate XML for a user.
4. Edit the value of the ht:user element to say Loan Process.
5. 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

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

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

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

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

10. 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. 
11. In the Properties view select the Notification tab and set the following properties:
• Name: ReminderToReps
• Priority: 2
12. Press the ellipsis button to the right of the Notification Interface field. 

13. 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.
14. 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.



15. 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.
16. 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

1. In the Outline view select the Completion Deadline and press the Escalation tab in the Properties view.
2. Select the Inline Notification labeled InlineNofication1 and press the Go To button.
3. In the Properties view select the Notification tab and change the name to EscalateIfNotActedUpon.
4. In the Outline view expand the EscalateIfNotActedUpon node and select the child node labeled N1.  
5. In the Properties view select the Notification tab and set the following properties:
• Name: NotifyReassignToManager
• Priority: 1
• Notification Interface: remind/loanhuman:LoanApprovalPeople


6. 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!

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

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

10. Select the Reassignment labeled Reassignment1 and press the Go To button.
11. In the Properties view select the Reassignment tab and change the name to ReassignToMgr1.
12. 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 an Ajax Form (or an XSL file or a custom rendering) that will be used to render the task information in the ActiveVOS Central Task forms. You can edit this form to customize how task information is presented to the user in the ActiveVOS Central web application.

1. In the Outline view select the approveTask.
1. In the Properties view select the Renderings tab and then the ActiveVOS Ajax Form tab.
2. The Create Form button presents a dialog were you can specify the project folder and name for the form.  The value for XHTML URI will be populated for you.
3. In our case, we will create the form in the form/task folder and use the default name of approveTask.html as shown below.

2. Create ActiveVOS Central forms for the task notifications by expanding the approveTask in the Outline view and creating new ActiveVOS Ajax Forms for the two notifications: ReminderToReps and NotifyReassignToManager (highlighted in the screenshot below).

Step 6. Creating the People Activity

1. In the Participants view, select the approveTask. Drag it from the Participants view to a position after the Under Review <reply> activity:
   
2. The people activity appears on the canvas. The activity is named by default the same as the underlying task, approveTask:
   
3. Select the people activity, and the associated Properties view. Edit the properties for the activity as follows:
1. On the People Activity tab:
• Change the name to ReviewLoan
2. 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.
3. 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.
4. On the Input tab:
• In the Assignment dropdown, select Single Variable.
• In the Variable dropdown, select creditInformation.
5. 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
4. 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

1. 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.
   
2. 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.
3. The value in the Service Interface property will show something like n31:LoanCRM. For readability, let's rename the namespace to something more meaningful. In the Outline view, expand the Namespaces node, and select ns31 (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.
4. 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.



5. Edit the properties of the invoke as follows:
1. At the Invoke tab:
1. Name: Notify Customer Service Of Decision
2. At the Input tab:
1. Assignment: Single Variable
2. Variable: approve-task
6. Add a Start/End event after the invoke.
7. Save your process.  Your process should now look similar to this:
8. 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.

1. Select the Fault Handlers tab.
2. From the Palette drag a Catch activity and drop it on the canvas.
3. In the properties view set the following properties:
• Fault Name: b4p:taskExpired (you can use the ellipses... button and select this)
4. 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: Notify CRM Of Expiration.
• At the Input tab, select XPaths
• Choose Literal for the E/L type and use the following
• 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 Part: Document


5. Your fault handler should now look similar to this:
6. Save your process.

Simulating the Process

Creating a Request Form

Prior to deploying the process we will create a Request Form that we can use to invoke the process on the server.  Two steps are required here: 1) create the form and 2) create an ActiveVOS Central Configuration (.avcconfig) file that is used to define the structure and contents of the ActiveVOS Central application.

Step 1: Create the Request Form

1. In the Project Explorer right-click on the form folder and select New > Process Request Form.
2. Expand the LoanProcess port type and select the request operation as shown here:

3. Press Next.
4. Name the form HumanApproval.html.

5. Press Finish.
6. Open the HumanApproval.html form and change the text [Replace with a service name] to LoanProcessServiceHuman.
7. Save the file.

Step 2: Create the ActiveVOS Central Configuration

1. In the Project Explorer right-click on the deploy folder and select New > Central Configuration.  Enter a value of HumanApproval.avcconfig for the file name and press Finish.
2. Scroll down to the Requests section and replace the <tns:requestCategoryDefs> with this code:

  <!--  Requests - example note that the values should be replaced with those from your application -->
  <tns:requestCategoryDefs>
    <tns:requestCategoryDef id="education_category" name="Tutorial and Samples">
      <avccom:requestDef id="hac_request" name="Human Approval Completed Form">
         <avccom:allowedRoles>
            <avccom:role>loanreps</avccom:role>
            <avccom:role>loanmgrs</avccom:role>
        </avccom:allowedRoles>
        <avccom:description>Submit loan approval request (Human Approval Completed Sample).</avccom:description>
 <avccom:formLocation>project:/HumanApprovalCompleted/form/request/HumanApprovalCompleted.html</avccom:formLocation>
      </avccom:requestDef>
    </tns:requestCategoryDef>
  </tns:requestCategoryDefs>


3. This will deploy the HumanApproval.html file to ActiveVOS Central and allow access to anyone with the loanreps or loanmgrs role. The file should look similar to this:

4. Save the file.
5. The request form and the ActiveVOS Central configuration file are now ready to be deployed.  Instructions for deploying can be found in the Human Approval Completed Orchestration Process template.

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.

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

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

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

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

6. 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:

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

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

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

Copyright (c) 2004-2010 Active Endpoints, Inc.