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

This example shows you how to validate the data in a coach within a client-side human service using client-side validation.

1. Create the client-side human service that will contain the coach to be validated. See Building a client-side human service.
2. In the Variables tab for the human service, create two private variables, startDate and endDate, and set the type of each variable to Date.
   
3. In the client-side human service diagram, rename the coach to Prompt for Start and End Dates.
   
4. In the Coaches tab, from the Variables section of the palette, drop the startDate and endDate parameters onto the coach. Leave the default OK button unchanged.
   
5. In the coach, select the Start date parameter and ensure that it is bound to the startDate variable in the Behavior section of the General tab.
   
6. Repeat step 5 for the End date parameter to verify that it is correctly bound to the endDate variable, and then save the coach configuration.
7. In the diagram, add a script, an exclusive gateway, and an intermediate event, which automatically becomes a stay on page event. Rename the script to Validate variable values and the exclusive gateway to Validation errors?. Connect these elements in the following order:
   
   1. Delete the flow line between the coach and the end event.
   2. Connect the coach to the script.
   3. Connect the script to the exclusive gateway.
   4. Connect the exclusive gateway to the stay on page event. Rename the flow line to Yes. Because this is the first flow line leaving the gateway, it has the / indicator to show that it is the default flow. The stay-on-page event loops the flow back to the coach.
   5. Connect the exclusive gateway to the end event.
   The human service flow now contains a coach validation pattern. The flow goes first to the script. If the data is not valid, the script creates and adds validation errors to the tw.system.coachValidation object. The gateway determines the path that the flow takes. If the data is valid, the flow goes to the next step in the flow, which is the end event. If the data is not valid, a validation error is recorded and the flow loops back to the coach.
8. Select the validate variable values script and, in the Script tab, 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 coach view, there is nowhere to display a validation error if one occurs.
   • If a coach 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 coach view binding where [] indicates that the object is a list. For example, if a coach 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");

9. Select the exclusive gateway and, in its Implementation properties, create the test. The test is tw.system.coachValidation.validationErrors.length==0. The test checks for the presence of validation errors and, if there are none, routes it to the rest of the flow. If there are errors, the flow goes to the stay on page event so that the coach can show the control with the problematic data and a message.
   
10. Save your changes, and then run the human service by clicking Run .
11. 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.