Configure Custom Validation Criteria

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

About Custom Validation Criteria

As standard, Vault Safety provides Validation Criteria for the ICH, EMA, FDA, FDA VAERS, PMDA, and MFDS 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:

Go to Business Admin > Objects > Validation Criteria.
Select Create.
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.
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, Vault 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 unless you are configuring the Validation Criteria for a specific agency or agencies. If you are using File Format, or are configuring a Validation Criteria to run for a specific agency or agencies only, 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 Vault 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 Vault 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 Writing Custom Validation Criteria Rule Formulas 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, Vault 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, Vault evaluates this rule instead of the superseded rule.
API Name	Enter a unique `__c` API name for this Validation Criteria*.

Write Custom Validation Criteria Rule Formulas

When writing the Rule Formula for a custom Validation Criteria record that uses the Case Data - Expression Rule Formula format, use either of the following methods:

VS_LET(var, path_to_validating_records, expression): Using this method, you can select any Vault Safety object as the beginning of the path to the validating records (the top-level object).
expression: With this method, the top-level object is either a Case or a Transmission.

Path to Validating Records

The path_to_validating_records tells the Rule Engine where to find the set of records to evaluate relative to the top-level object. The Rule Engine performs the expression defined in the Rule Formula field on each record to obtain a set of pass and fail results. Vault stores these results in the Validation Results and Validation Results Summary for the Case.

It is important to use the correct Vault object relationship names when specifying this path. 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.

You can also specify Case Documents (case_documents__v) as the top-level object to validate attachment descriptions (Case > Source > Attachments) and literature references (Case > Source > Literature).

Example: VS_LET(cd, case_documents__v, IF(cd.classification__v = "Literature", not(isblank(cd.reference_text__v)), true)) validates that any Case Document classified as Literature does not have a blank Reference field.

Rule Formula Expression

When writing the Rule Formula for your custom Validation Criteria (either as a standalone expression or as a VS_LET statement), you can use any of the functions and operators in the Vault Formula Reference Guide and any of the following functions, which are specific to Vault Safety:

Function	Description	Example
`VS_LET(var, path_to_validating_records, expression)`	Returns the result of a validation performed on the records of a Vault object. The parts of the `VS_LET` function are defined as follows: `var`: An alias to the records found at the resolved `path_to_validating_records`. You can use this alias in place of the path in your `expression` to make it easier to read. `path_to_validating_records`: The 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`: The expression that will be evaluated on the validating records. The result of the expression must evaluate to a true or false value.	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 ) Explanation: 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, Vault returns true if the MPID Version field is also specified, or false if it is not.
`VS_CONTAINS(string array, string)`	Returns true or 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 true or false depending on whether or not `string` matches the regular expression (regex) in `string`.	`VS_MATCHES("veeva", "^veeva.*$")` returns true.
`VS_ANYOF(array_expression, LAMBDA(array_element_alias, boolean_expression))`	Returns true or false depending on whether or not the `boolean_expression` is true for any of the array elements (`array_element_alias`) in the `array_expression`.	`VS_ANYOF(case_version__v.case_adverse_events_case_version__vr.days_hospitalized__v, LAMBDA (e,e>2))` returns true if any of the Case Adverse Events related to this Case have a Days Hospitalized value of two (2) or more.

See About Object Relationships: How to View Relationships for more information on inbound and outbound object relationships.

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

Note: 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 function will be added in a future release. If you require this function now, you must use either JSON or the SDK.

Troubleshoot Validation Criteria

If Vault encounters one (1) or more validation errors when running the Evaluate Regulatory Conformance action for a Case or a Submission, the Validation Status field of the Validation Results Summary record changes to Error.

Common Validation Criteria errors include the following:

A missing or incorrect Vault object
A missing or incorrect Vault field
An incorrect Rule Formula (including invalid references and null pointer exceptions)
An invalid JSON schema

To help diagnose the error, Vault provides Validation Error logs for individual Cases and Submissions, and for individual Validation Criteria.

The Validation Error logs are in CSV format.

Validation Error Logs for Cases and Submissions

The Validation Error Log for a Case or Submission lists all the Validation Criteria that failed for that record.

You can obtain the Validation Error Log for a Case or Submission by navigating to the Validations Results (Failures & Warnings) section and selecting the Validation Results Summary record. The Validation Status field of this record shows Error. From the Validation Results Summary record, select the Download Validation Error Log action from the All Actions menu.

Note: The transmission_id column is populated only for Transmission (Submission or Distribution) records and is left blank for Case records.

Validation Error Logs for Validation Criteria

The Validation Error Log for a Validation Criteria record lists all Case or Submission records where the Validation Criteria failed. Validation Criteria records that caused an error are in the Error lifecycle state.

You can obtain the Validation Error Log for a Validation Criteria record by going to Business Admin > Objects > Validation Criteria and selecting the Validation Criteria record. From the Validation Criteria record, select the Download Validation Error Log action from the All Actions menu.

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:

E2B(R2): sample-full-e2br2-json.json
FDA E2B(R2): sample-full-fda-e2br2-json.json
HC E2B(R2): sample-full-hc-e2br2-json.json
E2B(R3): sample-full-e2br3-json.json
EMA E2B(R3): sample-full-ema-e2br3-json.json
FDA VAERS E2B(R3): sample-full-fda-e2br3-json.json
PMDA E2B(R3): sample-full-pmda-e2br3-json.json
Case Data: sample-full-case.json

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.