EDI Validation

Documents generated from EDI Generator, should usually be validated before sending them to partners.

EDI validation rule types

Validation rules in EDI Generator fall into 3 main categories.

Structural rules

These ensure the correct structure of the EDI document; e.g.

• whether a mandatory loop/segment is missing
• whether the number of loop/segment entries is below minimum/above maximum allowed
• whether the segments appear in correct order/position inside each loop
• whether there are any unexpected/unknown entries in the EDI field hierarchy

These can be changed by modifying the transaction set (EDI spec) definition.

Data (segment/element) rules

These apply to a segment and its data elements; e.g.

• whether a required element is missing (e.g. entity ID code N101, in case of an entity name, N1 segment)
• whether the element’s value does not match its data type (e.g. letters appearing in a numeric field)
• whether the value range/size is satisfied (e.g. min and max lengths of an alphanumeric element)
• whether the element’s value is acceptable (e.g. a value outside of the allowed set of ID codes)

These can be changed/overridden at two places:

• If the rule is within the scope of a single segment (i.e. each occurrence of the segment has to be checked separately), define a custom segment linked to the corresponding EDI definition. This can override any desired element (position) within the segment, with proper data type, length, allowed-values list, etc.

  If the segment appears at multiple places inside the document, e.g. ASN REF in shipment and order levels, the override will apply to every such usage.

• If the rule applies to a group of segment occurrences taken together (e.g. at least one occurrence must match the rule, but not necessarily every one), define a path-based data rule which could apply across multiple segments.

Data (Element) Rules

Rules defined in a custom segment will apply to every occurrence of that segment, individually. If you want more flexibility, such as ensuring that there is at least one copy/occurrence of the segment with a specific ID code under a data element field, you can use data rules which can gather (match) and check data/element values across multiple segments using JSONPath syntax.

These rules currently support the following conditions:

• mandatory values: at least one segment must exist with each value
• recommended values: the vendor prefers to see at least one segment with each value, but it is not a strict requirement
• allowed values: only these values are allowed in the element/field; usually used to restrict the standard ID codes list (which can often contain hundreds or thousands of options) to a handful that is actually being used by the vendor

Conditional (Syntax) Rules

These are a type of segment rules that validate combinations of data elements (or relationships among them) inside a segment, such as:

• if REF02 is present, then REF03 is required (R0203, on reference identification, REF)
• at least one of IT102, IT104, IT106 has to be present (P020304, on item data, IT1)

By default, EDIG will follow the standard set of syntax rules that are defined for each segment, based on the X12 version of the document.

These rules can be overridden under the Standard Segment Rules section of the Rules Editor. If at least one conditional rule is specified here, the standard conditional rules for the segment will be ignored, and only the user-specified rule(s) will be evaluated.

Custom Rules

These are code snippets (NodeJS) that can be added to a loop or segment, to be invoked/run during validation of that loop/segment. You can use these to write more complex rules involving multiple elements, sub-trees, calculations, conditions, looping, scanning, storing and reusing results across rules, and so on.

When to use

Custom rules are only required, when the condition you hope to check is too complex/dynamic to be represented by the other rule types; e.g.

• checking the length of a field only if another related field is set to a specific value/code
• checking a sequence of (qualifier, value)-type element pairs (e.g. IT06-IT24 of invoice item data fields) for presence of desired values

Syntax

Each custom rule, is treated as the body of a function of this format/signature:

function (data, loop | segment, err, warn, ctx, path) {

This means that, in any custom rule, you would have access to the following pieces of data:

You can find examples for each parameter, under the How it Works section of the Rules Editor.

Using this data, you can calculate whether the current loop/segment is valid and compliant with the partner’s EDI definition/spec, and:

• invoke warn(message) to report each warning (e.g. a “recommended” or “preferred” usage that is missing).
• invoke err(message) to report each error (e.g. a “mandatory” or “required” condition that is not met).
• throw an exception with a suitable message, to end the current validation step with a single error.

Within a rule:

• you can do any standard NodeJS operations - calculations, comparisons, switch-case, looping, etc.
• you can use JSONPath({path, json}) expressions, driven by the jsonpath-plus library, to lookup and extract data - from either the current data sub-tree or the full EDI JSON (ctx.json).
• you do not have access to external libraries, filesystem/operating system related functions, etc.
• your logic must complete execution within 1 second.

Examples

Custom rule can be written at the desired loop/segment level, by referring to the JSON format of the source EDI.

For example, given the HLS loop structure from a standard X12 856 (ASN):

  "HL:03=S_LOOP": [
    {
      "HL:03=S": ["HL", "1", "", "S"],
      ..
      "REF": [
        ["REF", "BM", "bmValue"],
        ["REF", "PK", "pkValue"]
      ],
      ..

• To verify number of digits in REF02 when REF01=PK (second data element of each REF segment that is being used as a packing list number), you could write on segment REF:

  if (data[1] === 'PK' and !/^\d{15}$/.test(data[2])) {
  err(`Acme requires a 15-digit packing list number; found "${data[2]}"`);
  }
  

• To do the same validation but on the second REF instead, you can leverage the current position passed in path; e.g. ['ST', 0, .., 'REF', 1] (with the position index right after 'REF' being 1), indicates that the currently validated REF is at zero-based position 1 in the set of HLS -> REFs; i.e. the second REF. So you would write a rule for segment REF:

  if (path[path.length - 1] === 1) {
  // we're on the second REF; do the regex-based 15-digit check
  }
  

• To verify the count of REFs (in which case we need visibility to all available REF segments), you could write a rule on REF’s parent loop HLS:

  if (data.REF?.length < 3) {
  err("Vendor Acme requires at least 3 REFs under shipment HLS");
  }
  

Validation rules editor

You can associate validation rules with a loop or segment on an EDI definition (transaction set specification), using the Validation Rules button on the EDI definition editor.

Rules editor has 3 sections, corresponding to rule types described above:

• Data/Element Rules
• Standard Segment Rules
• Custom Rules

After defining/editing the rules, click the Done button (check icon) on the dialog header.

Rule modifications will actually get saved, only when you save the parent/owning EDI definition - not when you click Done.

Validating generated EDI documents

Generate button of the EDI document composition views (e.g. ASN editor) has an associated drop-down, where you can select the validation approach to use for the currently composed document:

1. Skip Validation: Completely skips the validation step, even if the EDI definition has an associated rule-set.
2. Validate: This is the recommended option; EDIG will validate the document after it is converted to EDI format, and decide how to proceed:
   • If there are critical errors, document will be halted (not allowed to send out) until the errors are fixed and re-validated.
   • If there are only non-criticial warnings (e.g. some vendor-recommended value not being used), you will be informed about them - but the document will be allowed to proceed to the next (sending) step.
3. Validate and proceed: EDIG will validate the document and show you the discovered errors/warnings, but will also allow you to ignore them proceed to the sending step.

Use (1) and (3) with caution: only if you know what you are doing, and are ready to accept the consequences of sending a possibly malformed/non-compliant document to your partner.

After a validation cycle, EDIG will show you a summary of errors and/or warnings detected in that cycle. When possible, EDIG will also provide a direct navigation button pointing to the offending field, and highlight the field itself with the error.

In case there were multiple issues, you can re-check the list later by clicking the error indicator icon displayed on the editor’s header.