Defining Data Validation

Data validations are defined using JSON by adding the editChecks section in the System/CP JSON configuration. It is a separate section in JSON.

Whenever the specified records are created or updated, the rules are evaluated, and if a rule fails, the system shows an error message and prevents saving.

Properties Used in Edit Checks

Constraint Level Properties

Property	Required	Description

Property	Required	Description
records	Yes	List of records on which validation should be evaluated. Whenever these records are created or modified, the rules are enforced. Possible values: cpr, visit, specimen, or a combination.
forms	No	List of form names whose data is used in validation. If not specified, only core fields are validated.
rules	Yes	List of rules that must be satisfied by the specified records and forms.

Rule Level Properties

Property	Required	Description

Property	Required	Description
when	No	Specifies when the rule is applicable. For example, apply only for primary specimens.
expr	Yes	The validation condition that must evaluate to true. If false, the record cannot be saved.
description	Yes	User-friendly error message displayed when the rule fails.

Aliases Used in Edit Checks

Record Aliases

Alias	Refers To	Usage

Alias	Refers To	Usage
#cpr	Collection Protocol Registration	Access CPR-level core fields in expr
#visit	Visit record	Access visit-level core fields in expr
`#specimen`	Specimen record	Access specimen-level core fields in expr

Form Record Aliases

Alias	Refers To	How It Works

Alias	Refers To	How It Works
`cprForms`	CPR-level forms	Map indexed by form name
`visitForms`	Visit-level forms	Map indexed by form name
`specimenForms`	Specimen-level forms	Map indexed by form name

Accessing Form Data Examples

Example	Description

Example	Description
`specimenForms['SpecimenFrozenEvent']`	Access the latest SpecimenFrozenEvent form record
`specimenForms['SpecimenFrozenEvent$Array']`	Access all SpecimenFrozenEvent records for the specimen

Example:

Visit date should be the same or later than the registration date

For more examples, please refer to the wiki page Data Validation Examples

{
  "name" : "editChecks",
  "data" : {
    "constraints" : [ 
      {
        "records" : [ "cpr", "visit" ],
        "rules" : [
          {
            "expr" : "#cpr.registrationDate != null && #visit.visitDate != null && !#cpr.registrationDate.after(#visit.visitDate)",
            "description" : "Visit date should be same or later than the registration date!"
          } 
        ]
      }
    ]
  }
}

Data Validation Fields

We can set up data validation on these 3 types of fields and their combinations:

Core fields
Custom fields
Custom form fields
A combination of the core fields, custom fields, and custom form fields

Level	Field Name	Field Expression

Level	Field Name	Field Expression
Participant	PPID	`#cpr.ppid`
Participant	First Name	`#cpr.participant.firstName`
Participant	Middle Name	`#cpr.participant.middleName`
Participant	Last Name	`#cpr.participant.lastName`
Participant	Registration Date	`#cpr.registrationDate`
Participant	External Subject ID	`#cpr.externalSubjectId`
Participant	Registration Site	`#cpr.site`
Participant	Birth Date	`#cpr.participant.birthDate`
Participant	Social Security Number	`#cpr.participant.uid`
Participant	eMPI	`#cpr.participant.empi`
Participant	Gender	`#cpr.participant.gender`
Participant	Vital Status	`#cpr.participant.vitalStatus`
Participant	Death Date	`#cpr.participant.deathDate`
Participant	Races	`#cpr.participant.races`
Participant	Ethnicity	`#cpr.participant.ethnicities`
Participant	MRN	`#cpr.participant.pmis`
Visit	Name	`#cpr.participant.pmis`
Visit	Name	`#visit.name`
Visit	Status	`#visit.status`
Visit	Missed By	`#visit.missedBy`
Visit	Missed Reason	`#visit.missedReason`
Visit	Visit Date	`#visit.visitDate`
Visit	Visit Site	`#visit.site`
Visit	Clinical Diagnosis	`#visit.clinicalDiagnoses`
Visit	Clinical Status	`#visit.surgicalPathologyNumber`
Visit	SPR	`#visit.clinicalStatus`
Visit	Visit Comments	`#visit.comments`
Specimen	Label	`#specimen.label`
Specimen	Barcode	`#specimen.barcode`
Specimen	Lineage	`#specimen.lineage`
Specimen	Collection Status	`#specimen.status`
Specimen	Type	`#specimen.type`
Specimen	Anatomic Site	`#specimen.anatomicSite`
Specimen	Laterality	`#specimen.laterality`
Specimen	Pathology Status	`#specimen.pathology`
Specimen	Initial Qty	`#specimen.initialQty`
Specimen	Available Qty	`#specimen.availableQty`
Specimen	Concentration	`#specimen.concentration`
Specimen	Parent Specimen Label	`#specimen.parentLabel`
Specimen	Biohazard	`#specimen.biohazards`
Specimen	Location	`#specimen.storageLocation`
Specimen	Created On	`#specimen.createdOn`
Specimen	Freezer Thaw Cycle	`#specimen.freezeThawCycles`
Specimen	Increment Freeze Thaw Cycle	`#specimen.incrParentFreezeThaw`
Specimen	Comments	`#specimen.comments`
Specimen	Collection Date	`#specimen.collectionEvent.time`
Specimen	Collector	`#specimen.collectionEvent.user`
Specimen	Received Date	`#specimen.receivedEvent.time`
Specimen	Receiver	`#specimen.receivedEvent.user`
Specimen	Collection Container	`#specimen.collectionEvent.container`
Specimen	Collection Procedure	`#specimen.collectionEvent.procedure`
Specimen	Received Quality	`#specimen.receivedEvent.receivedQuality`
Specimen	Frozen Time	`#specimen.events.SpecimenFrozenEvent.time`
Specimen	Frozen Method	`#specimen.events.SpecimenFrozenEvent.frozenMethod`
Specimen	Frozen Comments	`#specimen.events.SpecimenFrozenEvent.comments`

Adding Multiple Data Validations

In case there are many data validations to be performed, here is a tip that could help in avoiding errors:

Check and test the data entry workflow after adding each validation. This will allow you to identify if any validation fails and will be useful in rectifying the failed one. If all the validations are added together, it will be difficult to identify the validation in case the above error ‘Cannot index into a null value’ occurs.