Validating coaches in heritage human services

To ensure that a coach that is in your heritage human service passes valid data in the flow, use validation to check its data.

About this task

In a heritage human service, you validate the data that is in the coach before the flow proceeds to the next step in the service flow. You validate the data by adding a validation element and a stay on page event. The validation element can be a nested service or a server script. The server script is the simpler implementation although the nested service provides greater flexibility. In the following diagram, Coach1 is being validated by a server script and Coach2 is being validated by a validation service:

The following steps describe how to validate by using a server script. For information about using a validation service to validate coach data, see Example: validating a coach in a heritage human service.

1. To validate the coach data before a particular boundary event occurs, select the line for that boundary event. In the properties for the line, set the Fire Validation property to Before. The coach has a validate icon to indicate that you can now connect the coach to the validation script.
2. Add a server script to validate the data to the human service diagram.
3. Select the script of the validation pattern. In the Script properties, add JavaScript code that identifies problematic data. Use the tw.system.addCoachValidationError(CoachValidation coachValidation, String errorBOPath, String errorMessage) API to add the error data to the coachValidation system variable. For example, you want two fields to have a value. They are bound to var1 and var2. To ensure that they have a value, use code like the following example code:

   if (tw.local.var1 == ""){
   	tw.system.addCoachValidationError(tw.system.coachValidation, "tw.local.var1", "Enter a value for field 1");
   }
   if (tw.local.var2 == ""){
   	tw.system.addCoachValidationError(tw.system.coachValidation, "tw.local.var2", "Enter a value for field 2");
   }

   The tw.system.coachValidation parameter is the system variable 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 identifies what is wrong with the data and tells the user how to fix the problem.
   Important:

   • A coach in a heritage human service 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 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, code the validation server script to remove formatting before it validates the text contents.
4. Connect the validate icon of the coach to the validation script.
5. Add a Stay on Page event. Connect the validation script to the Stay on Page event. 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 script 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.