Configure Custom Validation Criteria

Learn how configure Validation Criteria for Agencies not already supported by Vault Safety.

Last Updated

Note Beginning with 24R1 in April 2024 and for all subsequent releases, the new Vault Safety Help site is the official site for all Vault Safety Help content. This site reflects updates until the 23R3 release only. For the latest information, visit the new site.

About Custom Validation Criteria

As standard, Vault Safety provides Validation Criteria for the ICH, EMA, FDA, FDA VAERS, and PMDA health authorities.

If you need to add custom Validation Criteria to enforce data quality requirements for Submissions or Distributions other than the ones already included in Vault Safety, you can configure your Vault by adding custom Validation Criteria. This custom criteria then runs as part of Case and Submission Validation.

The next section describes how you can add custom Validation Criteria to your Vault.

Create Custom Validation Criteria

Complete the following steps to create and configure custom Validation Criteria:

  1. Go to Business Admin > Objects > Validation Criteria.
  2. Select Create.
  3. Enter the details of the Validation Criteria.
    See the Custom Validation Criteria Field Reference for help with specifying the value for each of the fields.
  4. Select Save.

Repeat the above steps for each custom Validation Criteria required.

Custom Validation Criteria Field Reference

FIELD DESCRIPTION
Name Enter the name of the custom Validation Criteria.
Source Select Custom.

Note If you require a Custom SDK validation, contact Veeva Technical Services.
Always Evaluate Select this option if the system should evaluate this Validation Criteria for all global and regional destinations regardless of the Case having a reporting obligation.
Agency

Select the Agency to which the Validation Criteria applies.

Leave this field blank if the custom rule is a global validation.

If this validation is regional and only applies to a specific agency, then select the appropriate Agency.

If you are using a File Format validation, the system will evaluate the rule only when validations are run for one of the specified File Format and Agency pairings.

Conformance Enter the description of the Validation Criteria.
Data Element Specify the E2B element ID that the custom rule will validate.
Data Element Name Specify the E2B element ID name that the custom rule will validate.
File Format

Select which standard E2B file formats the Validation Criteria applies to.

If you are using Case Data or Case Data - Expression, you can leave this field blank.

If you are using File Format, select the standard E2B file formats to which the Validation Criteria applies. This field works with the Agency field and must be aligned accordingly. For example, if you select ‘EMA’ for the Agency, you must select an EMA File Format. The system will evaluate the rule only when validations are run for one of the specified File Format and Agency pairings.

Evaluation Level Select one or more levels (Case, Submission, and/or Domestic Case) at which the system will evaluate the Validation Criteria.

For example, select Case if the rule is intended to be evaluated when validations are run from the Case level only.

Result Status Type

Select whether the system should treat a rule violation as a Warning, Fail, or Hard Fail.

This field is directly tied to the Validation Status field of the associated Validation Result object.

  • Either a Fail or Hard Fail result will prevent an auto-submission to a gateway.
  • Only a Hard Fail result will prevent you from triggering the Submit to Gateway action.
Vault Object (required) Enter the API name of the relevant object for the validated E2B field. When validation results are generated, they will contain a link to the specified object. For example, case_drug_history__v.
Vault Field (required) Enter the API name of the relevant field for the validated E2B field. When validation results are generated, they will contain a link to the specified object. For example, mpid_version__v.
Rule Version Enter the version number of the Validation Criteria.

Note If there are multiple validation criteria records with the same name, only the latest version of the rule will be evaluated.
Rule Formula Enter the formula used to validate against the specified E2B files.

See Validation Expression Language below for instructions on how to write a rule formula.

Rule Formula Format

Select whether to use File Format, Case Data, or Case Data - Expression for formula execution:

  • File Format: A JSON schema validation based on Case data that is specific to an E2B format
  • Case Data: A JSON schema validation based on Case data that is not specific to an E2B format
  • Case Data - Expression: A Vault Expression Language-based validation based on Case data that is not specific to an E2B format

If left blank, the system defaults to File Format.

Note File Format is used for all standard ICH E2B(R3) Validation Criteria.
Supersedes If this Validation Criteria supersedes an existing Validation Criteria, select the name of the superseded rule in this field.

If this rule and the superseded rule are both due to be evaluated, the system will evaluate this rule instead of the superseded rule.

API Name Enter a unique *__c API name for this Validation Criteria.

Validation Expression Language

When entering the Rule Formula for a custom Validation Criteria record, use the Validation Expression Language as follows.

Rule Formula Format

The Rule Formula should be in one of the following formats:

  1. VS_LET(var, path_to_validating_records, expression)
  2. expression

Using VS_LET, you can select any Vault Safety object as the beginning of the path to the validating records (the top-level object). Using expression only, the top-level object is either Case or Transmission.

The parts of the VS_LET formula are defined as follows:

  • var acts as an “alias” that the records found at the resolved path will be assigned to.
  • path_to_validating_records represents a path to the Vault object being validated, beginning from the top-level object (for example, case_version__v, transmission__v, localized_case__v) or the validating record alias var defined in the VS_LET function, with each following node in the path separated by a period (‘.’). The path navigates through the objects using the appropriate object field relationship names.
  • expression represents the expression that will be evaluated on the validating records.

Example: The following expression validates that if the MPID field is specified for a Case Product, the MPID Version must also be specified:

 1	VS_LET(
 2   cp,
 3   case_version__v.case_products_case_version__vr,
 4   IF(
 5      NOT(
 6         ISBLANK(cp.mpid__v)
 7      ),
 8      NOT(
 9         ISBLANK(cp.mpid_version__v)
10      ),
11      TRUE
12   )
13  )
  • Line #2: Defines the name of the alias (cp in this example) that refers to the list of validating Products, as set by line #3.
  • Line #3: Defines the path to the validating records. In this example, the list of Case Products.
  • Lines #3-12: Defines the expression to be performed on each of the items in the list referred to by cp. In this example, if the MPID field is specified for a Case Product, the system returns TRUE if the MPID Version field is also specified, or FALSE if it is not.

Path to Validating Records

When specifying the path to the validating records, it is important to use the correct Vault object relationship names. To obtain the relationship names for an object, go to Admin > Configuration > Objects > [object] > Relationships.

Example: case_version__v.case_products_case_version__vr returns all of the Case Products associated with the Case. To obtain a list of Pass and Fail results (which are stored in the Validation Results and Validation Summary), the system iterates through the list of Case Products and performs the expression defined in the Rule Formula field on each Product.

Rule Formula Expression

When writing the expression for your custom Validation Criteria, you can use any of the functions and operators in the Vault Formula Reference Guide, and either of the following two functions, which are specific to Vault Safety:

FUNCTION DESCRIPTION EXAMPLE
VS_CONTAINS(string array, string) Returns a boolean value (TRUE/FALSE) depending on whether or not string is present inside string array. VS_CONTAINS(["one", "two", "three"], "two") returns TRUE
VS_MATCHES(string, string) Returns a boolean value (TRUE/FALSE) depending on whether or not string matches the regular expression (regex) in string. VS_MATCHES("veeva", "^veeva.*$") returns TRUE

Note All function names (including Vault Platform functions) are case-sensitive and must be in all capitals.

Note The result of the expression must evaluate to a binary (TRUE or FALSE) value.

For further information on writing custom formulas, see Creating Formulas in Vault.

Note Consider the following limitations when creating custom Validation Criteria using the Vault Expression Engine:

  • The system does not validate Case Document Attachments or Literature Attachments.
  • The Validation Expression Language does not currently provide an 'at least one of' function (for example, 'at least one of the Case Products has an expiration'). This ability will be added in a future release. If you require this function now, you must use either JSON or the SDK.

Appendix: Custom Validation Criteria Using JSON

If required, you can use JSON instead of the Vault Expression Language to create custom Validation Criteria. However, we recommend using the Vault Expression Language described above as it is considerably quicker and easier to configure than the JSON method. The JSON method will continue to be supported but will not be enhanced in future releases.

The JSON method is similar to that described in Create Custom Validation Criteria above, except that the code you enter in the Rule Formula field must be valid JSON.

When E2B files are generated for standard (non-custom) file formats, all of the relevant E2B data is exposed in structured JSON for validation purposes. The following files are examples of the structured JSON for the standard formats that can be used for reference:

You can find validation criteria types, including syntax and limitations, on the JSON Schema website.

Note Unlike standard JSON schema, the validation JSON schema must have a top-level description annotation. This annotation must contain the JSON path to the validated element (for example, "description": "#/sectionC/sectionC2Rs") and will determine how the associated validation results are generated.

Custom Validation Criteria Examples

Consider the following examples of custom Validation Criteria configured in Vault Safety and the JSON syntax for each:

Example 1: Simple Rule

  • File Format: HC E2B(R2)
  • Agency: Health Canada
  • Data Element: A.2.1.2f
  • Data Element Name: Reporter’s Postcode
  • Conformance: “This field is required.”
  • Vault Object: case_contact__v
  • Vault Field: postalcode_value__v
  • Rule Formula: Simple_Rule_Formula.json

Example 2: Complex Rule

  • File Format: FDA VAERS E2B(R3)
  • Agency: FDA
  • Data Element: D.2.1
  • Data Element Name: Date of Birth
  • Conformance: “FDA requires that at least one of the data elements in the Age Information section (Date of Birth (D.2.1), Age at Time of Vaccination (FDA.D.2.1a/b), Age at time of Onset of Reaction (D.2.2a/b), Gestation Period When Reaction / Event Was Observed in the Foetus (D.2.2.1a/b), and Patient Age Group (D.2.3)) be populated, preferably Date of Birth and Age at the Time of Vaccination. If Local Criteria Report Type = Malfunction Only (No AE), then all age fields are optional.”
  • Vault Object: case_version__v
  • Vault Field: dob_idate__v
  • Rule Formula: Complex_Rule_Formula.json

Example 3: Detailed JSON Structure Example

  • File Format: FDA VAERS E2B(R3)
  • Agency: FDA
  • Data Element: D.10.8.r.2a
  • Data Element Name: MPID Version Date / Number
  • Conformance: “This field is required when Medicinal Product Identifier (MPID) (D.10.8.r.2b) is populated.”
  • Vault Object: case_drug_history__v
  • Vault Field: mpid_version__v
  • Rule Formula:
 1 {
 2  "$schema": "http://json-schema.org/draft-07/schema#",
 3  "type": "object",
 4  "description": "#/sectionD/d_10_patientParent/d_10_8_r_parentDrugHistory",
 5  "definitions": {
 6    "d_10_8_r_2b_POPULATED": {
 7      "properties": {
 8        "_2b_MPID": {
 9          "type": "string",
10          "minLength": 1
11        }
12      },
13      "required": ["_2b_MPID"]
14    },
15    "d_10_8_r_2a_EXISTS": {
16      "properties": {
17        "_2a_MPIDVersionDataNumber": {
18          "type": "string",
19          "minLength": 1
20        }
21      },
22      "required": ["_2a_MPIDVersionDataNumber"]
23    }
24  },
25  "properties": {
26    "sectionD": {
27      "type": "object",
28      "properties": {
29        "d_10_patientParent": {
30          "type": "object",
31          "properties": {
32            "d_10_8_r_parentDrugHistory": {
33              "type": "array",
34              "items": {
35                "type": "object",
36                "if": {
37                  "$ref": "#/definitions/d_10_8_r_2b_POPULATED"
38                },
39                "then": {
40                  "$ref": "#/definitions/d_10_8_r_2a_EXISTS"
41                }
42              }
43            }
44          }
45        }
46      }
47    }
48  }
49 }

Line #2: “$schema” key

Specifies the URI for the desired JSON schema version. We recommend using "http://json-schema.org/draft-07/schema#".

Line #3: “type” key

Specifies the data type for a schema. The top-level JSON element in the structured JSON is always type "object".

Line #4: “description” key

Specifies the JSON path to the validated JSON element. In this case, the validated JSON element "_2a_MPIDVersionDataNumber" is located in "sectionD → d_10_patientParent → d_10_8_r_parentDrugHistory".

Lines #5-24: “definitions”

Specifies a map of JSON schemas. Each of the schemas defined in this map can be referenced and evaluated by using the "$ref" keyword. While not required, definitions can help increase readability when there are multiple schemas (to help describe what each one is validating) and/or for defining a schema that will be used multiple times.

Line #6-14: “d_10_8_r_2b_POPULATED” schema

Specifies the schema for ensuring that D.10.8.r.2b ("_2b_MPID") is populated. This schema is referenced later using the "$ref" keyword, within the schema for "d_10_8_r_parentDrugHistory".

  • "type": "string" → Enforces a string value
  • "minlength": "1" → Enforces a non-blank value
  • "required" : ["_2b_MPID"] → Enforces the element’s existence

Line #15-24: “d_10_8_r_2a_EXISTS” schema

Specifies the schema for ensuring that D.10.8.r.2a ("_2a_MPIDVersionDataNumber") is populated. This schema is referenced later using the "$ref" keyword, within the schema for "d_10_8_r_parentDrugHistory".

  • "type": "string" → Enforces a string value
  • "minlength": "1" → Enforces a non-blank value
  • "required" : ["_2a_MPIDVersionDataNumber"] → Enforces the element’s existence

Lines #25-48: “properties” (top-level)

Specifies the properties of the top-level JSON object. The value of the "properties" is an object where each key is the name of a property or element and each value is a schema used to validate that element.

Lines #26-47: “sectionD” schema

Specifies the JSON schema for the "sectionD" object.

Line #27: “type”: “object” Specifies the type of "sectionD", which is an object containing key-value pairs (properties).

Line #28: “properties” (sectionD)

Specifies the properties of the "sectionD" JSON object. It contains key-value pairs where each key is the name of a property/element under "sectionD" and the value is a schema used to validate that property.

Lines #29-45: “d_10_patientParent” schema

Specifies the JSON schema for the "d_10_patientParent" property.

Line #30: “type”: “object”

Specifies the type of "d_10_patientParent", which is an object containing key-value pairs (properties).

Line #31: “properties” (d_10_patientParent)

Specifies the properties of the "d_10_patientParent" JSON object. It contains key-value pairs where each key is the name of a property/element under "d_10_patientParent" and the value is a schema used to validate that property.

Lines #32-43: “d_10_8_r_parentDrugHistory” schema

Specifies the JSON schema for the "d_10_8_r_parentDrugHistory" property:

Line #33: “type”: “array”

Specifies the type of "d_10_8_r_parentDrugHistory", which is an array containing ordered elements.

Lines #34-42: “items” (d_10_8_r_parentDrugHistory)

Specifies a single schema that will be used to validate against all items in the "d_10_8_r_parentDrugHistory" array.

Lines #36-41: “if” → “then”

Specifies that the evaluation of a schema ("then") is dependent on the outcome of the evaluation of another schema ("if"). In this case, the E2B field D.10.8.r.2a is required (then) only when the E2B field D.10.8.r.2b is populated (if).

Line #36-38: “if” schema

Specifies the "if" schema. In this case, the schema is "#/definitions/d_10_8_r_2b_POPULATED", which was defined earlier and is being referenced using the "$ref" keyword.

Line #39-41: “then” schema

Specifies the "then" schema. In this case, the schema is "#/definitions/d_10_8_r_2a_EXISTS" which was defined earlier and is being referenced using the "$ref" keyword.

Example 4: Case Data JSON Structure Examples

Manage EDQM Mapping for Dose Form and Routes of Administration Terms
Manage Transmission Profiles
Next →

Related Docs