Note: Nintex Apps data centers are located in West US and Australia (AUS). In-region processing of Nintex Apps data is only available in these regions.

Client-Side Validation

Note:  Currently, client-side validation is only available for fields in the Form component.

Client-side validation lets you validate a user's input against the field's expected format (e.g., email address, Social Security number, and more). Validation is client-side, which means the user doesn't have to save the form–and query the server–to be alerted that their input doesn't match the field's required format. If validation fails, error messages appear that advise users on how to fix the error.

Validation timing

Validation can occur at any of the following moments:

  • User leaves the field
  • User changes the field's value
  • User leaves the field and then on subsequent value changes
  • Save model changes action runs

This is set in the Validations tab of the field's Properties pane. Determining when to validate is based on a number of factors, most notably how much attention you want to draw towards the field's expected format. For example, validating when the user changes the field's value means that users will immediately see an error, even if they haven't finished typing—for that reason, it's best to use this sparingly and only for critical inputs.

To show errors inline, ensure that Show errors inline is enabled in the Form component's Properties pane under Display > Errors. If this property is disabled, error messages will appear at the top of the form, removed from the context of the field itself.

Validation types

Within the Validations tab, click add Add to create a new validation. Validation criteria is set by the Validate based on property for all validations except Required.

Validations can occur based on the following criteria:

  • Required (appears on every field)
  • Field length
  • Format
  • Formula
  • Snippet

Required and field length validations are based on metadata, while others are based on custom logic. The standard formats are out-of-the-box, meaning you could validate an email field without setting up custom code. The custom formula and snippet options are more advanced, but offer greater flexibility for complicated inputs.

Required

This validation determines whether or not an error occurs when the end user leaves the field blank. It appears on all fields, and if the field's metadata states that a field is required, this field is set to True and cannot be updated.

Default error message

Required

Example: Validate that a field has a value and show a custom error message if not

This is an example page. Its data resets each time the page is loaded.

In this example, we're validating that the field has a value while the user fills out the form—displaying a custom error without initiating Save.

  1. Select the field in the Form component on the canvas.

  2. In the Properties pane, click Validations.

  3. Click the Required validation.

  4. Set the following properties:

    • Only validate on save: Unchecked

    • Required: True

      Note:  If the field is marked as required in the model or by the connection, this field is always true.

    • Override default error message with: Your account must have a name.

  5. Click Save.

  6. Click Preview to view the field and test the validation. Try clicking away from the Account name field before entering a field value to see the validation in action.

Format

Standard format validation is only available on EMAIL, DATE, TEXT, and URL field types. The four standard input formats for validation are:

  • Email: example@example.com

  • Social Security number: ##-###-####

  • Date: MM/DD/YYYY

    Note:  The expected date format varies depending on the user's locale, which is set by the user in their Locale settings. For example, if the user set their locale to English (United Kingdom), the expected date format would be DD/MM/YYYY.

  • URL: example.com

Default error messages

Each standard format has a default error message. This can be customized through the Override error message with property. If that property isn't changed, the following default errors appear for each format:

Date

Must match format: MM/DD/YYYY

Note:  The expected date format varies depending on the user's locale, which is set by the user in their locale settings. For example, if the user set their locale to English (United Kingdom), the expected date format would be DD/MM/YYYY.

Email

Must match format: example@example.com

Social Security number

Must match format: ###-##-####

URL

Must match format: example.com

Example: Validate input for Social Security number format

This is an example page. Its data resets each time the page is loaded.

In this example, we're validating that the user's input matches the standard format for Social Security numbers (##-###-####).

  1. Select the field in the Form component on the canvas.

  2. In the Properties pane, click Validations.

  3. Select User leaves the field in the Show error message when dropdown.

  4. Click add next to Validations.

  5. Set the following properties:

    • Enable: Checked
    • Validate based on: Format
    • Input format: Social Security number

  6. Click Save.

  7. Click Preview to view the field and test the validation. Try entering an incorrect value, such as 123ABC123, to see the validation in action.

Field length

This validation returns an error when the field value exceeds the maximum length as determined by the field's metadata. These validations trigger whenever a user enters a character; the Show error message when property has no effect.

Default error message

Can't exceed <maximum length> characters

Example: Input must be shorter than 20 characters

This is an example page. Its data resets each time the page is loaded.

In this example, we're ensuring that an opportunity's description is shorter than 20 characters.

  1. If needed, select the field in the model and set its Length property to 20.

  2. Select the field in the Form component on the canvas.

  3. In the Properties pane, click Validations then click add.

  4. Set the following properties:

    • Enable: Checked
    • Validate based on: Field length
    • Override error message with: Use brief descriptions, no longer than a sentence.

  5. Click Save.

  6. Click Preview to view the field and test the validation.

Formula

If your field requires validation that isn't covered by the four standard formats, you can also validate based on a custom formula—which can be made up of one or more fields and formula functions. Formula validation can be applied to any field type. If the formula returns FALSE, error messages appear based on your validation rule. This is particularly useful for more complicated formats, such as inputs that must fall within a specific numerical range.

Default error message

Inputs validated by formula have a standard error message. This can be customized through the Override error message with property. If that property isn't changed, the following error appears: Must match custom validation rules.

Example: Input must exceed 15000

This is an example page. Its data resets each time the page is loaded.

In this example, we're ensuring opportunityAmount is higher than 15000. Remember to adjust the formula as needed for your use case.

  1. Select the field in the Form component on the canvas.

  2. In the Properties pane, click Validations.

  3. Select User leaves the field and then on subsequent value changes in the Show error message when dropdown.

  4. Click add next to Validations.

  5. Set the following properties:

    • Enable: Checked
    • Validate based on: Formula
    • Formula: {{opportunityAmount}} > 15000
    • Override error message with: Must exceed 15000

  6. Click Save.

  7. Click Preview to view the field and test the validation.

Snippet

Validation by snippet allows for granular control over the input and reusability across different fields through the use of JavaScript. Snippet validation can be applied to any field type. If the snippet runs and returns FALSE, error messages appear based on your validation rule. Create validation snippets as Generic JS Snippet resources in the JavaScript tab of the Elements pane.

Nintex Apps passes the field value to validate through arguments[0] so it's often best to begin validation snippets by declaring this as a variable or constant:

const fieldValue = arguments[0];

Default error message

Inputs validated by snippet have a standard error message. This can be customized through the Override error message with property. If that property isn't changed, the following error appears: Must match custom validation rules.

Example: Input must only contain letters

This is an example page. Its data resets each time the page is loaded.

This snippet uses regular expressions to ensure the field value only contains lowercase and capital letters. Numbers, symbols, and other characters will cause the validation to throw an error.

  1. In the Elements pane, select the JavaScript tab.

  2. Click add in the JavaScript tab.

  3. Enter the following properties:

    • Resource type: Generic JS snippet

    • Snippet name: OnlyLetters

    • Snippet body:

      Copy 
      const fieldValue = arguments[0];
      return /^[a-zA-Z]+$/.test(fieldValue);

  4. In the canvas, select the field in the Form component.

  5. In the Properties pane, click Validations.

  6. Select User changes the field's value in the Show error message when dropdown.

  7. Click add next to Validations.

  8. Set the following properties:

    • Enable: Checked
    • Validate based on: Snippet
    • Snippet: OnlyLetters
    • Override default error message with: Must only contain letters

  9. Click Save.

  10. Click Preview to view the field and test the validation.

Validation within repeater components

Some components, like the Deck, iterate through each model row to create repeating UI elements, and are sometimes called "repeater components". When using client-side validation with a Form component nested within a repeater component, do not assign unique IDs to the fields within the Form.

Because Form fields can appear multiple times when nested within a repeater component, hardcoded field IDs are no longer "unique," and validations cannot be calculated correctly. Thus, Nintex Apps requires its own auto-generated unique IDs when dealing with fields that may appear multiple times.

Validation tab properties

  • Show error message when: This determines when error messages appear. It applies to all validation rules for the given field.

    • User leaves the field: This is the standard blur HTML event, so errors appear as soon as the user navigates away from the input.

    • User changes the field's value: This is the standard change HTML event. Errors appear when the user pauses briefly after adjusting the input and disappear when the user fulfills the input requirements.

    • User leaves the field and then on subsequent value changes: Errors appear when the user first navigates away from the field and then navigates back —the validation then behaves like "User changes the field's value."

      This is useful when you don't want to immediately show an error message, but you'd like to validate when they return to the input—thus minimizing the errors the user may encounter before they've finished changing the input.

    • Save model changes action runs: Errors appear when the user initiates the Save model changes action.

The following properties are available on individual validations:

  • Only validate on save: ( Only available on Required validation ): When enabled, ignores the value of Show error message when and only validates whether the field has a value when the user saves.

  • Required: ( Only available on Required validation ) Validates based on whether or not the field value is empty when validations are set to run.

    Note:  If the field's metadata states that a field is required, this field is set to True and cannot be updated.

  • Enable: When selected, the specific validation rule is applied to the input and error messages display when requirements aren't met.

    Note:  Enable is set per-rule, so you can enable/disable individual validation rules for one field.

  • Validate based on: The type of requirements that the input must meet to pass validation

    • Field length: Validates whether or not the user has typed more characters than allowed by the field's metadata.
    • Format: Validates based on one of four standard input formats:
      • Date: MM/DD/YYYY
      • Email: example@example.com
      • Social Security number: ###-##-####
      • URL: example.com
    • Formula: Validates based on a custom formula. If the formula runs and returns FALSE, error messages appear.
    • Snippet: Validates based on a JavaScript snippet. If the snippet runs and returns FALSE, error messages appear.
      • Snippet: The name of the snippet to validate with

  • Override default error message with: Replaces the system's default inline message with a custom message.