Validation rules

Good data capture is not only about reading values; it is about knowing they are right. The Validation tab of a Batch Setup holds three kinds of checks:

• Formatters tidy a value before it is checked, for example upper case or removing spaces.
• Validators check one value, for example a pattern, a range or a check digit.
• Rules check several fields, whole documents or the whole batch, for example Net + VAT = Total.

You define formatters and validators once, and each field picks the ones it needs. Rules apply on their own. You can try everything on sample values before saving.

Work with the Validation tab

1. Open the Batch Setup and go to the Validation tab. Create a draft first if the version is released.
2. Choose the tab Formatters, Validators or Rules on the left (each shows how many there are) and click Add.
3. Give it a Name and choose its Type.
4. Fill in the settings.
5. Try it under Try it and click Try.
6. Click Save validation.

Find what you need

Long lists are easy to search. Above the list:

• Search finds items by name, type, message, or the name of a field that uses them.
• All types shows only one type, with how many of each there are.
• For formatters and validators, Used or not shows the ones fields use, or the ones Not used (the count of unused ones is also a link above the list).
• For rules, filter by what they check (Several fields, Whole document, Whole batch) and by result (Errors, Warnings, Switched off).
• Clear filters shows everything again.

Each item shows its type and main settings, and a badge with how many fields use it (unused when none). The item you choose opens on the right, which stays in view while you scroll the list. The tab you were on is remembered.

Use the small arrows to change the order in each list (they show when no search or filter is active). For formatters and validators, the order a field lists them is the order they run.

Then open each field (see Fields and extraction) and add the formatters and validators it should use with Add…. The field's lists show only the chosen items, in the order they run; use the arrows to change the order. Where a rule's settings take a list of fields, you build it the same way.

Formatters

Formatters run before validation, so calculations and checks see the tidied value.

Validators

A field passes only if all its validators pass. Empty values are only checked by Not empty and Script.

Every validator can have a Message shown when it fails. Leave it empty for an automatic message that shows the value.

Tip: Combine a formatter and a validator for VAT numbers: Remove characters (space, dash, dot), then Check digit with UK VAT number. The check accepts numbers with or without the GB prefix.

A script validator:

return value.startsWith('PO') || 'Order numbers start with PO';

Dictionaries in checks

A dictionary is a list of allowed values, optionally each with a value of its own (a translation). Dictionaries are listed under Administration › Batch Settings › Dictionaries. They usually come from an import from another product, which can also replace a dictionary's entries with a new version.

• The In a dictionary validator (type dictionary) checks that the value is an entry, for example { "dictionary": "Titles" }. Tick Also accept the dictionary's values (acceptValues) to accept the entry's value too, not only the entry itself.
• The Translate with a dictionary formatter (type translate) replaces a value by its entry's value, for example { "dictionary": "OtherLanguageTitles" }. Unknown values are kept.

For example, a "Title" field read from tick boxes can be checked against a Titles dictionary with the entries Mr, Mrs, Miss and Ms.

DocView keeps dictionaries in memory and reloads one as soon as a new version is imported.

Rules

Rules look at more than one value. For each rule you choose:

Rules across fields

Compare two fields compares numbers as numbers and dates as dates; otherwise it compares text.

Rules for whole documents

Rules for the whole batch

Batch rules run on real batches: after extraction, whenever fields are saved in indexing, and when the batch is released. Batch rule errors stop the release.

Scripts that correct values

Script rules return true to pass, false or a message to fail, or an object with set to correct values. Values an operator typed are not overwritten. For example, work out VAT at 20 %:

return { set: { Vat: round(num(fields.Net) * 0.2, 2) } };

fields holds the values by name and tables holds line items, for example tables.LineItems[0].Amount. num() reads amounts such as £1,250.00 and round() rounds them. A batch script example:

return documents.every(d => d.fields.Currency === documents[0].fields.Currency) || 'Mixed currencies';

Scripts run in a sandbox. The editor offers suggestions for fields and helpers as you type.

Script helpers

The same helpers work in server event scripts. For example, a rule that accepts a title from either of two dictionaries:

return inDictionary('Titles', fields.Title) || translate('OtherLanguageTitles', fields.Title) !== null
    || 'Unknown title';

Where operators see the results

Failed validators and rules are shown on the fields they concern in Correction and Index / Validate. Errors must be fixed before a document can be completed; warnings are shown only. Documents that fail validation also stop straight-through processing, so they reach an operator.

Server Validate event scripts count as rules too. See Events and scripts.

Checks on the field itself

Simple checks such as a pattern, length, range, date formats or allowed values can also be set directly on a field, without a named validator. Named validators are better when several fields share the same check.