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:

  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.
Always Evaluate Select this option if Vault 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.

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. Vault 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.
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.

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:

  1. 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).
  2. 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(literature_reference__v)), true)) validates that any Case Document classified as “Literature” does not have a blank Literature 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(expression) Returns true or false depending on whether or not the expression within the function is true for any of the records from the inbound object relationship. 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 zero (0).

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.

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.

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:

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

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