Example: validating a coach in a heritage human service

This example shows you how to validate the data in a coach within a heritage human 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.

The example shows how to validate a coach in a heritage human service using IBM Process Designer. For more information about validating a coach in a human service, see Validating client-side coaches using client-side validation.

Create the CreditCardApplication business object with the following parameters:
- name(String)
- salary(Decimal)
- creditLimit(Decimal)
Create the CreateCreditApplication heritage 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. Relabel the default OK button to Submit.
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:
1. From the library, create a general system service called CreditApplicationFormValidation.
2. On the Variables page of the service, add application(CreditCardApplication) as an input of the service.
  Important: 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.
3. Add a server script to the service diagram and connect the start and end nodes to the script.
4. 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 heritage human service diagram.
Select the CreditApplicationFormValidation service and open the data mapping properties. To provide the data to the validation service, add the application private variable as an input map. To map the output of the validation service to the CoachValidation object, add the following variable as an output map:
```
tw.system.coachValidation
```
Important: 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 node of the Credit Application coach to the CreditApplicationFormValidation service.
Add a Stay on Page node to the diagram.
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.
Save your changes and then run the heritage human service by clicking the button.
In the browser that displays the coach, test the validation by doing the following:
1. Leave the Name field empty, type a 1 into the Salary field and into the Credit Limit field. Click Submit. The browser displays a message that the Name field cannot be empty.
2. Type a name into the Name field, and replace the 1 in the Salary field with a 0. Click Submit. The browser displays a message that the salary must be more than 0.
3. Replace the 0 in the Salary field with a 1. Replace the 1 in the Credit Limit field with a 3. Click Submit. The browser displays a message that the credit limit cannot be more than twice the salary.
4. Replace the 3 in the Credit Limit field with a 2. Click Submit. The human service now finishes because all three values are now valid.

Restriction:

Pay attention to the following behavior when you debug a coach and step through each activity in the flow as the coach service is running: If coach data validation is required at a step, the validate boundary event path loops back and goes back to open a new coach. Because the validate boundary event response cannot go back to the originating coach during the debugging, you do not see a visual error during debugging. You can step through a coach and see the validation error on the debug page, but the flow always returns to a new coach.

After you have debugged the validation path, and you have reviewed the debug info page, including tw.system.coachValidation error information, select one of the following options:

Run to continue.
Run to the next break point that is defined in the next step in a regular boundary event flow. This option moves to the next step in the regular boundary event flow.