Example: validating a coach in a client-side human service

Edit online

This example shows you how to use the data change properties of a coach in a client-side human service to validate the coach data without exiting the coach.

About this task

The following example demonstrates how to validate the data that a user enters in the coach so that an error message shows up in the coach when the data is not valid. The example also demonstrates how to prevent the user from proceeding to the next step when the data is not valid.

The example contains a Prompt for Start and End Dates coach, which has a Start date field, an End date field, and an OK button. The start date precedes the end date. To validate the coach data, you will specify a client-side JavaScript in the coach to perform the validation.

Note: This example shows you how to validate a coach in a client-side human service using IBM® Process Designer. For information about validating a coach in a heritage human service (deprecated), see Example: validating coach data in a heritage human service in the desktop Process Designer (deprecated).

Procedure

Create the client-side human service that contains the coach to be validated. See Building a client-side human service.
In the Variables coach of the human service, create two private variables, startDate and endDate, and set the type of each variable to Date.
In the client-side human service diagram, rename the coach to Prompt for Start and End Dates.
In the coach, use the top insertion point of the OK button to add two Date Time Picker views (stacked vertically), rename the views to startDate and endDate, and ensure that they are bound to the startDate and endDatevariables, respectively. Leave the default OK button unchanged.
Save the coach configuration.
In the diagram view for the coach, under Data Change > Script, enter the following JavaScript construct:
```
if (tw.local.startDate.getTime() > tw.local.endDate.getTime())
	tw.system.coachValidation.addValidationError("tw.local.startDate", "The start date must precede the end date. Set the start date before the end date, and try again.");
```
In the coachValidation object, the first string contains the full variable path to the elements whose data is to be validated. The second string is the message for the user, which specifies what is wrong with the data and tells the user how to fix the problem.
Note:
- If the data element that is being validated is not bound to a view, there is nowhere to display a validation error if one occurs.
- If a view that is being validated contains rich text, the validation script must remove the formatting before validating the contents.
- If you are validating a list and you want the error to refer to the entire list, the variableName parameter must include [] as a suffix. This matches view binding where [] indicates that the object is a list. For example, if a view is bound to tw.local.var3[], which is a list, you need code like the following example:
```
tw.system.coachValidation.addValidationError("tw.local.var3[]", "Var3 has validation error");
```
Optional: To prevent the user from proceeding to the next step when the data is not valid, complete the following steps:
1. In the Variables coach for the human service, add another private variable named readyToSubmit, and set its type to Boolean.
2. In the Data Change > Script properties of the coach, append the following JavaScript code to the existing script:
```
tw.local.readyToSubmit = tw.system.coachValidation.validationErrors.length==0;
```
3. In the coach, configure the OK button to be read-only when not ready, as shown:
Click Save or Finish Editing.
For details about declaring variables for the client-side human services, see Declaring variables
Click Run to run the human service.
In the browser that displays the coach, test the validation by completing the following steps:
1. Set the End date to a date that precedes the start date. Click OK.
  The browser highlights the Start date field and displays a warning icon. If you hover over the warning icon, you see a message that the start date must precede the end date.
2. Set the end date to a date that succeeds the start date. Click OK.
  The human service completes successfully because both dates are valid.