Articles in this section

Setting Up Validations

Avatar
Support
  • Updated
Follow

This article explains how to use Validations in Brilliant Assessments. Validations allow you to check respondent input, compare values to constants, and display error, warning, or informational messages during an assessment.

Validations are only available if the Enable Calculations checkbox in the Assessment Settings is selected. To create a validation, you add a calculation and then choose one of the Validation Types in the Calculation Type field.

On this page

What Validations Do

Validations allow you to:

  • Compare the result of a calculation to a constant. For example, check if the total of several numeric fields equals 100.
  • Check if allowable combinations of answers have been selected. For example, maybe "Always" can only be selected once per subsection.
  • Display a message if a certain score has or hasn't been attained in the assessment so far, and potentially end the assessment.

Validation Types

When a validation evaluates to "true" (meaning the condition is met), a dialogue box is displayed to the respondent. The three validation types control what buttons appear on that dialogue box:

Type Behaviour
Validation Error Displays a dialogue box with a Return button only. The respondent must go back and correct their input.
Validation Warning Displays a dialogue box with a Return button and a Next button. The respondent can go back or continue.
Validation Information Displays a dialogue box with a Next button only. The respondent acknowledges the message and continues.

For example, the output from an error validation may appear like this:

Example validation error dialogue box

Note: Validations can be placed anywhere in an assessment but are hidden in the response. They are always calculated when the section they belong to is saved, either by clicking Next or Save Progress.

Setting Up a Validation

Validations use the power of Microsoft's Transact-SQL. As well as regular operators like + - * / with or without brackets, advanced users can access the Mathematical and String functions that Transact-SQL offers. Database statements are not allowed for security reasons.

Validations always use Case statements that result in "True" (display the message) or "False" (no message). The validation messages often use the Cast function to combine numeric results into a text message.

Tips for writing validations:

  • The format is: case when [condition] then 'true' else 'false' end. The true and false may be transposed if that makes the condition simpler.
  • Literals can be entered as a number for numerics, or with single quotes for character strings.
  • If you have numeric user input, the Answer Type should be Numeric or Decimal rather than Text.
  • If you use selected answers (e.g. single choice) as input, the Answer Short Name will be used. It should be entered as a number with no formatting (e.g. 300000 not $300,000).
  • When scores are used in a calculation they are returned as a percentage. For example, 0.6 = 60%. If you want the Likert equivalent, multiply by 5 (assuming Potential Points = 5).
  • Comments can be added between /* and */ to document the validation.
  • Support will help build more complex validations for you.

Validation Fields Reference

Validation setup screen in the assessment builder

The screenshot above shows the validation setup screen. The numbered fields are explained below.

  1. Validation Indicator. Validations are denoted in the assessment builder with a tick before the Validation name.
  2. Calculation Name. Used for identification purposes only.
  3. Calculation Number. Used for reference and is interchangeable with a question number. You can refer to this number in a merge string in the feedback report to display the result of a calculation.
  4. Calculation Type. Select one of the three validation types: Validation error, Validation warning, or Validation information.
  5. Potential Points. Not relevant to a validation. Should be set to 0.
  6. Merge Fields (Validation). Use the merge field drop-down lists to choose answers or scores to include in the validation formula. Scores can be accessed at all summary levels. Click the Add button to insert the merge string at the cursor position.
  7. Validation Formula. Enter the Case statement that evaluates to true or false. True means the validation message will be displayed. When true, the answer is marked as selected, so you can make other questions, subsections, or sections conditional on the validation result.
  8. Calculate after Scoring. Indicates whether scoring for the assessment (including the current page) should be calculated before the validation runs. Use this when you need the "current score" as part of the validation.
  9. Result is Numeric. Not relevant for validations.
  10. Merge Fields (Validation Message). Use the merge field drop-down lists to specify answers and scores to include in the validation message. Click the Add button to insert the merge string at the cursor position.
  11. Validation Message. Enter the message that should be displayed in the dialogue box. To include numeric values in the text, use the Cast function: CAST([expression] as varchar(max)). Use + signs to concatenate strings.
  12. Documentation. Unlimited documentation of the validation can be entered here. It does not affect the validation or appear anywhere else.
  13. Segmentations. Not used for validations.
  14. Conditions. A validation can be conditional like a question. If the condition is not met, the system treats the validation as unanswered and no check is performed.
  15. Report Text. Not used for validations.

Debugging Validations

As a system administrator, you can view the workings of validations from within a response for diagnostic purposes. Open the Section menu (to the left of the Section name on the response header) and select Calculations.

Response section menu showing Calculations option

The Calculations form shows validations along with regular calculations:

Calculations diagnostic form showing validation details

  1. Validation Name. The name of the validation.
  2. Location. Section / Subsection / Question Number of the validation.
  3. Result. If the validation message was shown, this field will be "true".
  4. Calculated Score. Not used by validations.
  5. SQL Detail. The validations are shown as they are passed to SQL for calculation.
    • The system pre-resolves all merge strings, so you can see the current values.
    • The calculation of the message is shown even if it wasn't displayed.
    • SQL has a quirk that if it is only passed whole numbers it will always return a whole number. For that reason, numbers are multiplied by 1.00 to give them decimal places.
    • If there is an error in either formula, an error message will be shown. That error is from SQL and is usually quite cryptic. Most errors are caused by unmatched brackets or missing operators. Support can help you with these if you cannot find them.

Validation Examples

Email Validation

Email error validation example

FAQs & Troubleshooting

Use the questions below to troubleshoot common validation issues.

+ Where do I add a validation in my assessment?

Validations are added as calculations. Go to the section where you want the validation to run, add a new calculation, and then in the Calculation Type field, select one of the three validation types (Error, Warning, or Information). Make sure the Enable Calculations checkbox is selected in your Assessment Settings.

+ What's the difference between a validation error, warning, and information?

The three types control what the respondent can do when the validation is triggered:

  • Error - Shows a Return button only. The respondent must go back and fix their input.
  • Warning - Shows both Return and Next buttons. The respondent can go back or choose to continue.
  • Information - Shows a Next button only. The respondent acknowledges the message and moves on.
+ When does a validation run?

Validations are calculated when the responses to the section they belong to are saved. This happens when the respondent clicks Next or Save Progress. If you need the current score as part of the validation, enable the Calculate after Scoring option.

+ Can I make a validation conditional?

Yes. Validations support conditions the same way questions do. When a condition is set and not met, the system treats the validation as unanswered and no check is performed. You can configure conditions in the Conditions field on the validation setup screen.

+ Why am I getting a SQL error in my validation?

SQL errors in validations are usually caused by:

  • Unmatched brackets - Check that every opening bracket has a matching closing bracket.
  • Missing operators - Make sure you have +, -, *, or / between values where needed.
  • Whole number division - SQL returns whole numbers when only passed whole numbers. Multiply by 1.00 to get decimal results.
  • Missing quotes - String literals must be wrapped in single quotes.

You can diagnose these errors by viewing the Calculations form from the Section menu in a response. If you cannot find the issue, contact Support for help.

Related articles

Comments

0 comments

Please sign in to leave a comment.