Example: validating a Coach with a service

IBM BPM, V8.0.1, All platforms > Create processes in IBM Process Designer > Create user interfaces for business processes > Coach and Coach View examples
Example: validating a Coach with a service

This example shows you how to validate the data in a Coach by using a validation service.
The example contains a Credit Application Coach that gathers information for a credit card application. To simplify the example, the Coach has only a Name field, a Salary field, a Credit Limit field and a Submit button. The Name and Salary fields must contain values and the Credit Limit maximum is double the Salary field value.
The example uses a general system service to validate the Coach data. With the exception of Ajax services and human services, you can use any service type and you are not limited in how the service does the validation. However, the service must construct a CoachValidation business object to contain the validation information that it returns to the Coach as output. This sample uses the addCoachValidationError API to construct the business object. For the sake of simplicity, the service in the example uses a script to validate the data.
Create the CreditCardApplication business object with the following parameters:

name(String)
salary(Decimal)
creditLimit(Decimal)

Create the CreateCreditApplication human service.
Add application(CreditCardApplication) as a private variable.

In the diagram, add the Create Application Coach and then open the Coach.
From the Variables section of the palette, drop the name, salary, and creditLimit parameters onto the Coach. Add a Submit button.

In the diagram, connect the Credit Application Coach to the start and end nodes.
Select the connection between the Credit Application Coach and the end node. Set Fire Validation to Before. The connection now has a check mark at its start. The Coach has an icon
to indicate that you can now connect the Coach to the validation service. This change means that when the user clicks the Submit button, the flow first goes to the validation service to do the data validation. If the data is valid, the flow then goes to the end node. If you leave Fire Validation at its default of Never, the data validation does not occur and the flow goes directly to the end node.
Create the service to validate the Coach data:
Create a general system service called CreditApplicationFormValidation.
Add application(CreditCardApplication) as an input of the service.
The name and the type of the service input must match the name and type of the Coach variable that contains the data that you want to validate. Add validate(CoachValidation) as an output of the service. The service must have one output only and it is of the CoachValidation type. The presence of this output indicates that the service is a validation service. In this case, the example uses the input to provide the data that the service validates.

Add a server script to the service diagram and connect the start and end nodes to the script.
In the implementation of the server script, add the following code to construct the CoachValidation business object:
tw.local.validate = new tw.object.CoachValidation();

if (tw.local.application.name == ""){
    tw.system.addCoachValidationError(tw.local.validate, "tw.local.application.name",     "The name cannot be empty.");} if ( tw.local.application.salary <= 0){
    tw.system.addCoachValidationError(tw.local.validate, "tw.local.application.salary",     "The salary must be above 0.");} if (tw.local.application.creditLimit > 2 * tw.local.application.salary){
    tw.system.addCoachValidationError(tw.local.validate, "tw.local.application.creditLimit",     "The credit limit cannot be more than double the salary. " + "The maximum credit limit is $" + 
    2 * tw.local.application.salary + ".");}
The tw.local.validate parameter is the CoachValidation business object that contains the validation information. The first string contains the full variable path to the data element with the problematic data. The second string is the message for the user. The message should identify what is wrong with the data or tell the user how to fix the problem.
Important:

A Coach can use only one validation service or server script to validate its data. However, more than one Coach can use the same validation service or script.
If the data element being validated is not bound to a Coach View, there is nowhere to display a validation error if one occurs.
If a Coach View being validated contains rich text, the validation service must remove any formatting before validating the contents.
Add the CreditApplicationFormValidation service to the CreateCreditApplication human service diagram.
Select the CreditApplicationFormValidation service and open the data mapping properties. To map the output of the validation service to the CoachValidation object, add the following variable as an output map:
tw.system.coachValidation
To provide the data to the validation service, add the application private variable as an input map.
The output mapping to the system variable is mandatory for the Coach to use the service as a validation service. The tw.system.coachValidation parameter is the system variable that contains the validation information.
Connect the validate icon of the Credit Application Coach to the CreditApplicationFormValidation service.
Connect the CreditApplicationFormValidation service to the Stay On Page node. This construction loops the flow back to the Coach if the data in the Coach is not valid. The system passes error information back to the Coach and users see an indicator beside the Coach View with the problematic data. If the validation service provides error messages, users see the appropriate message when they hover over an indicator. If the data is valid, the system processes the boundary event to move to the next step.
Coach and Coach View examples

Related tasks:
Developing reusable Coach Views

Related reference:
The validate event handler