Installing the module

How to install and enable the Universal Field Validator external module on a REDCap instance, and where the per-project rules are configured.

Installing takes three steps: a REDCap administrator enables the module once per server, a project administrator enables it on a project, and a designer adds the rules.

1. Install the module — administrator, once per server

From a downloaded copy

Put the module folder on the server under modules/, named with its version — for example redcap/modules/universal_validator_v1.6.1/. The folder must contain config.json at its top level.
Go to Control Center → External Modules → Manage. The module appears as available. Click Enable.

Download a versioned copy from the releases page.

From the REDCap repository (once published): Control Center → External Modules → View modules available in the repository → find Universal Field Validator → Download → Enable.

2. Enable it on a project — project administrator

Project External Modules page → Enable a module → Universal Field Validator.

3. Add validation rules

One rule is one kind of validation, applied to any number of fields. There are two places to declare rules and they mix freely. A field claimed twice shows a configuration error rather than quietly running two validators.

A. The Configure dialog

Add one Validation rule per kind of validation:

Rule label — optional, your own name for the rule, such as "Specimen IDs".
What this rule checks — the rule kind: Single value, Pooled, Constraint, Required or Choices.
Field(s) — pick fields with the picker and click its + to add more to the same rule, or type extra field names into the fast entry box, comma- or space-separated. Unknown names show a configuration error.
Check-character method — must match how the IDs were minted. The generator's default is ISO 7064 Mod 37,36. To validate a plain format with no check character, choose No check character and set the format pattern.

B. Field annotations — best for bulk setup

Tag fields where you already design them: the Action Tags / Field Annotation box in the Online Designer, or the field_annotation column of the data dictionary CSV. To validate 50 fields, fill one spreadsheet column and upload the dictionary once.

@UVALIDATE                                     default check, message only
@UVALIDATE=verhoeff                            pick the algorithm
@UVALIDATE={"algorithm":"none","pattern":"FC[0-9]{4}","blockSave":"hard"}
@UVALIDATE={"type":"pooled","expectedIds":3}   pooled field, warn unless 3 IDs

Recognised JSON keys for @UVALIDATE: type, algorithm, source, pattern, strip, keepChars, idLengths, idMinLen, idMaxLen, expectedIds, blockSave, when, suggestFix, note. Use double quotes inside the JSON.

A malformed tag — a typo'd key, an unknown algorithm, bad JSON, or a tag on an unsupported field type — shows a configuration error in a notice at the top of the form rather than failing silently. Fields with identical tags are grouped into one rule automatically.

The other four tags are documented on their own pages: @UVASSERT, @UVREQUIRED, @UVUNIQUE and @UVCHOICES.

Requirements

REDCap 13.7.0 or later (External Module Framework version 14)
PHP 7.4.0 or later

The full install document, including the parts not repeated here, is docs/INSTALL.md in the repository.