Validations Overview

Less than 10 minutes to read

Validation in the Sage 200 Web Amendability Schema allows you to enforce data integrity, provide informative messages, and guide users through the process of data entry. This guide provides an overview of how to effectively utilise the validation section in the schema, covering various types of validations, their effects, and practical examples.

Types of Validations

There are three types of validations available in the Sage 200 Web Amendability Schema:

Errors: Displays a red prohibited sign and prevents the screen from being saved if validation fails. Ideal for critical data integrity checks.
Warnings: Displays a yellow warning triangle and allows saving of the screen despite the warning. Useful for issues that should be flagged to the user, but are not invalid.

When validations appear

Errors will be shown once a field is considered to have been “touched”. This usually happens when a user blurs out of the field - i.e. they tab to the next input or click elsewhere on the page. When the user submits a form, all fields will be touched, which means any errors on fields the user has not interacted with will be highlighted.
Warnings will usually be shown regardless of whether the user has touched the field. Otherwise, the behaviour is the same as for errors.

Deconstructing a Basic Validation

Let’s break down the basic validation below:

“field”: “name”: Specifies that the validation is targeting the “name” field on the screen.
“type”: “string”: Specifies that the field under validation is of type string. This means that constraints such as min will check string length; if the type was number, then min would validate that the field was at least that value.
“constraints”: Describes the constraints associated with the validation, which in this case is a required field check.
- “required”: {“message”: “Is required”}: Indicates that the “name” field must not be left empty. If this condition is violated, the form will have errors, “Is required” will be displayed on the field, and form submission will be prevented.

"validations": {
  "errors": [
    {
      "field": "name",
      "type": "string",
      "constraints": {
        "required": {
          "message": "Is required"
        }
      }
    }
  ]
}

In some cases, you may want to validate a field with respect to another. Instead of using a fixed value, you can use the id of another field in the value property. For instance, consider the following validation:

"validations": {
  "errors": [
    {
      "field": "reorder_level",
      "type": "number",
      "constraints": {
        "min": {
          "value": "spare_number_1",
          "message": "Value entered is less than ${min}"
        }
      }
    }
  ]
}

In this example, the value property is set to spare_number_1, which represents the ID of a field. This means that the validation will use the actual value stored in the field with the ID spare_number_1 as the minimum value. This approach can be particularly useful when you need to ensure that certain values meet specific criteria based on dynamic or calculated conditions.

A common use case for this is with dates, where you’d like a delivery date to always be on or after the order date, never before.

Validation in Grids (Arrays)

Grids in the Sage 200 Web Portal display arrays of data returned by the API. For example, imagine the API response for a form returns the following data;

{
  "id": 1,
  "code": "ABB001",
  "name": "Abbey Retail Ltd",
  "contacts": [
    {
      "id": 1,
      "name": "Hayley Bass",
      "email": "[email protected]"
    },
    {
      "id": 2,
      "name": "Ian Mowbray",
      "email": "[email protected]"
    }
  ]
}

To validate that any name field in our contacts grid has a value;

include the gridName property in your validation.
include the field name as name.
- Note we also have a name field outside of the array/grid. The use of gridName means we’ll only be targeting the name field in the grid. If we didn’t include the gridName property, then we would be targeting the main name field outside of the grid.

"validations": {
  "warnings": [
    {
      "gridName": "contacts",
      "field": "name",
      "type": "string",
      "constraints": {
        "required": {
          "message": "Is required"
        }
      }
    }
  ]
},

If you wish to reference another field in your constraint - e.g. if one date must be greater than another, then the comparison will be with that field in the same row - we only support references to another sibling or sibling descendant field.

Child forms

It’s common to edit individual grid lines or related entities in a Dialog or DialogFullscreen which contains a Form. To target your validations at this child form, you must pass the id of the form to the formIds field in your validation.

For example:

{
  "validations": {
    "errors": [
      {
        "formIds": ["contactDetailsForm"],
        "field": "name",
        "type": "string",
        "constraints": {
          "required": {
            "message": "Contact must have a name"
          }
        }
      }
    ]
  }
}

The id prop is required on any child form you add to a screen. If you’re adding fields and validations to an existing child form, you can find the id of the form using your browser dev tools.

If the formIds property is specified in a validation, it will only target the listed child forms, and never targets the parent form.

Targeting grids within child forms

When targeting a grid within a child dialog, simply build up all of the properties we have looked at so far.

{
  "validations": {
    "errors": [
      {
        "formIds": ["contactDetailsForm"],
        "gridName": "contacts",
        "field": "name",
        "type": "string",
        "constraints": {
          "required": {
            "message": "Contact must have a name"
          }
        }
      }
    ]
  }
}

In the above example, note how with formIds, gridName, and field, we’re progressively getting more specific with what we’re targeting.

formIds: The validation is tied to a specific form with the ID contactDetailsForm. This property takes an array, so you can specify multiple child forms (on the pages already specified in your schema) if you wish.
gridName: The gridName property is set to “contacts,” indicating the grid you want to validate.
field: Within the designated grid (“contacts”), the validation targets the “name” field. This is the field you want to validate.
type: The validation type is set to “string,” indicating that the data in the “name” field should be a string value.
constraints: Here, a constraint is set up for the validation. The “required” constraint specifies that the field must not be blank.

Full Component Validation Example

Here’s an example of how to set up a validation on a component using the Sage 200 Web Amendability Schema:

{
  "version": "1.0",
  "pages": [
    "sales/new-customer",
    "sales/amend-customer",
    "sales/view-customer"
  ],
  "uiExtensions": [
    {
      "id": "tempButton",
      "component": {
        "Date": {
          "id": "account_opened",
          "label": "Follow Up",
          "allowEmptyValue": true
        }
      }
    }
  ],
  "actions": {},
  "validations": {
    "errors": [
      {
        "field": "account_opened",
        "type": "date",
        "constraints": {
          "min": {
            "value": {
              "get": {
                "datetime": "NOW"
              }
            },
            "message": "Date must be atleast today."
          }
        }
      }
    ]
  },
  "events": [
    {
      "onLoad": [
        {
          "set": {
            "pageExtension": {
              "componentId": "name",
              "panel": "right",
              "uiExtension": "tempButton"
            }
          }
        }
      ]
    }
  ]
}

In this example:

A date component “Follow Up” is created and added to specified pages.
The validation is defined under the “validations” section using the “errors” type.
It ensures that the “account_opened” date is atleast todays date (“NOW”).