Running a Validation RuleLast Updated: 07/15/2016 Introduced in Verision: 2.0 |
To ensure that a user enters valid data in a form’s required fields, you can configure a form to run validation rules. The rules can run upon submission of the form, upon a field losing focus (i.e. the user clicking out of a field), or upon startup of the form. The startup method of executing a validation rule displays alerts next to the fields when the form first loads. This can be useful for highlighting form fields that must be changed because their default values, or values inherited from a preceding step, are invalid.
Example
In this scenario, a minimum age for an applicant is at least 18 years old. A validation rule will evaluate year of birth of the applicant against the current year and enforce this business rule for minimum age. Our example validation rule will expect a date. If the year of birth is earlier than the end date, the rule will return a truthful outcome. Otherwise, it will return false. The validation rule is created in the topic “Creating a Validation Rule.”
The form in which the rule will be used is configured as follows:
The validation rule is applied in the Form Designer, from the Surface level for the form. Click on the Explorer tab on the right. Click on Surface.
Notice the Custom Validation Rules section. Click on Add.
In the RuleName field, enter a name for the rule, such as “VerifyAge.” In the Rule field, browse to the location of the rule and select the rule.
In the ValidationBreakText field, type the message to appear to the user when the rule is broken. For example, “Only applicants over age 18 years are allowed.”
The Break Level options are Warning or Fatal. The Warning setting will show the message, however let the form submit. The Fatal setting will not allow the form to submit until the condition is corrected (i.e. the date changed to a year that will allow the rule to evaluate true.) In this example, leave the default as Fatal.
The ApplyToControls setting tells the rule which form control(s) to watch. Check the checkbox for DatePicker 1. If you had multiple form controls to which the rule applies, you would select all applicable controls.
Next, configure the inputs for the rule. Click on the DOB input line, and click Edit.
In the resulting Edit object pop-up, change DOB’s input type from “InputData” to “Form.”
Next, define the form control which will serve as the DOB input by selecting the FormDataName “ApplicantAge.”
To set the rule to run any time the date value changes, check the RunOnValueChanged checkbox.
This completes our definition for the DOB input; click the OK button to close the Edit Object pop-up.
Next, select the desired trigger events to run the rule in the Triggers section. Upon the occurrence of the selected event, the rule will trigger. Some additional triggers (depending on what other form fields are present) are:
Under Rule Excecution, select whether to run the rule when the form loads, and/or whether to run the rule on all or only specific outcomes.
Under Advanced, configure settings as desired.
- Inputs Missing Behavior – When no information is provided in the field being watched, the behavior can be a warning message (non-fatal and the form can be submitted), a fatal error (thus preventing form submission), or ignored.
- Inputs Missing Message – Unless the behavior is set to Ignored, the message in this field displays when the rule input is missing.
- Rule Exception Behavior – When the rule itself fails, the behavior can be a warning message (non-fatal and the form can be submitted), a fatal error (thus preventing form submission), or ignored.
- Rule Exception Message – Unless the rule behavior is set to Ignored, the message in this field displays when the rule execution errors.
- Append Server Exception Message – When selected, includes the code generated on the server by the error and shows that to the user.
Click OK to save the validation rule.
There is one other rule setting, from the Surface of the form, under Rules:
To run this rule at startup, check the Rules > RunOutcomeRulesAtStartup check the box. When this is selected, the rule executes upon loading of the form. A user seeing this form for the first time can tell immediately which values need to be changed in order for the form to be valid.
Lastly, test the rule by running the flow. From the flow’s Action menu, select Run Flow.
When the rule is marked as RunOutcomeRulesAtStartup, the form shows as follows:
Once the user enters a valid date and clicks out of the date field, the error message disappears:
