<< Click to Display Table of Contents >> Navigation:  5. Detailed description of the Actions > 5.2. Input Actions > 5.2.12. Edi-Fact / X12 Reader > 5.2.12.1. Background information about EDI/X12 files

EDI/X12 files are text files that contains a tree data structure (much like XML or JSON). The ReadEdiX12 Action creates a simple table from the EDI/X12 files: i.e. it ‘flattens” the tree-structure to obtain a simple table.

 

An EDI/X12 file is composed of different “Segments”. Each Segment is separated from the next one using a special character: the “Segment Terminator”.

 

 
Each segment is composed of several “Data Elements”. The different “Data Elements” are separated using a special character: the “Data Element Delimiter”.

 

 

 

The first “Data Element” of a segment contains the Segment Name. Some “Data Elements” (but not all) are composed of several (sub)fields. These special “Data Elements” are named “Composite Data Elements”. Each field inside a “Composite Data Element” is is separated from the next field using a special character: the “Sub-Element Delimiter”.

 

 

 

Here is an example of EDI/X12 file (we added a CR/LF after each segment to make it easier to read):

 

 

 
 

Inside an EDI file, the NAD segment contains an address.

In the example above the addess is:

        XYZ Company

        123 Church Street

        1050 Brussels – BE

If the street name contains a special characters (such as the ‘, the + or the : ), we need to “escape” it (so that it’s not interpreted as a “Segment Terminator”, a “Data Element Separator” or a “Sub-Element Separator”). The default “Escape” character is the “Question Mark”(?).

For example, if the street name is:

         2+ Is it Bob? Street

… the EDI file contains:

          2?+ Is it Bob?? Street

 

 
 

Let’s now illustrate the tree structure of an EDI/X12 file.
 

Let’s create an EDI/X12 file that represents the following tree:

 

 

 
The corresponding EDI/X12 file is (we added CR/LF and spaces after each segment to make it easier to read):

 

 

 

The corresponding XML or JSON file is:

 

 

 
A difficulty with EDI/X12 files is that there are no tags inside the file that “close” a level: i.e. There are no “</loop>” tags (i.e. no “end-of-loop” tags), no “</iteration>” tags (no “end-of-iteration” tags) (…or in JSON: There are no “]” or “}”).

 

Inside an EDI/X12 file, to know if you need to either “go down” a hierarchical level, either “close” a hierarchical level (i.e. “go up”) or either start a new iteration at the same hierarchical level, you need to refer to the grammar of the EDI/X12 file. Without the grammar, you cannot properly decipher an EDI/X12 file. Here is the grammar used to parse the above file (note that this grammar refers to the segments “EEE” and “GGG” but the example file did not contain any such segments, since they are optional):
 

 
 

The grammar contains two type of tags: “Seg” tags and “Loop” tags.

 

The “Seg” tags indicate that the EDI/X12 file might contain here a specific segment, with a specific name. The attributes of a “Seg” tag are:
 

•“id”: the name of the segment

•“l” (optional: if omitted, l=0): if l=1, then the segment if mandatory (i.e. it must appear inside the EDI/X12 file). “l” stands of “lower bound”.

•“u” (optional: if omitted, u=1): The number of time this segment might be repeated inside the ED/XC12 file. If u=-1, then an unlimited number of repetition is authorized. “u” stands of “upper bound”.

 

The “Loop” tag indicates that the EDI/X12 file might contain here a loop (i.e. a repetition of several segments). “Loops” are sometime refered as “Segment groups” inside Edi-Fact documentation. You can have a Loop within a Loop. The attributes of a “Loop” tag are:
 

•“id”: the name of the loop. Usefull only for debugging purposes. It’s not used to parse the EDI/X12 file. It’s also used when saving the .anatella file (The XPath expressions used to describe the fields to extract out of the EDI/X12 file are using the loop’s names).

•“l” (optional: if omitted, l=0): if l=1, then the loop if mandatory (i.e. the loop must appear inside the EDI/X12) file.

•“u” (optional: if omitted, u=1): The number of time this loop might be repeated inside the ED/XC12 file. If u=-1, then an unlimited number of repetition is authorized.

 

The first segment inside a Loop is special: It marks:
 

•The start of the loop (i.e. We “go down” one hierarchical level).

•The start of a new iteration of the loop (i.e. We stay at the same hierarchical level and we start a new iteration of the loop)

 

For example, if we have the following grammar:
 

    <Seg id=’AAA’>

    <Loop id=’G0’>

          <Seg id=’BBB’/>

          <Seg id=’CCC’/>

    </Loop>

    <Seg id=’CCC’/>

 
… and the following EDI files:

 

 
 
 

The following grammar:

   <Seg id=’AAA’>

   <Seg id=’BBB’>

   <Seg id=’CCC’>

…won’t be able to parse this file:

   AAA+1’

   CCC+1’

   BBB+1’

…because Anatella expects the segment “BBB” after the segment “AAA” (and not the segment “CCC”).

 

In such situation, you will get a parsing error. To solve the error, you need to correct the grammar. (The correct grammar for the above example is:

   <Seg id=’AAA’>  <Seg id=’CCC’>  <Seg id=’BBB’>   ).To easily find what corrections are required inside the grammar, you can activate the “Grammar Debug Mode”:

 

     

 

When the “Grammar Debug Mode” is activated, you’ll see inside the Anatella Log window some messages that gives you a precise explanation of the parser state (it explains you at which position inside the hierarchical structure of the document the parser is). You can see when the EDI/X12 parser “goes down” or “goes up” one hierarchical level, when it starts a new iteration, etc.

 

For example:

        EDI/X12: parsing segment UNB - extract 5 element(s).

        EDI/X12: parsing segment UNH -nothing to extract.

        EDI/X12: parsing segment BGM -nothing to extract.

        EDI/X12: parsing segment DTM -nothing to extract.

        EDI/X12: skipping segment DTM

        EDI/X12: skipping segment DTM

        EDI/X12: Entering Loop 'G0' starting with 'RFF'

        EDI/X12: parsing segment RFF -nothing to extract.

        EDI/X12: Leaving Loop 'G0'

        EDI/X12: Entering Loop 'G1' starting with 'NAD'

        EDI/X12: parsing segment NAD -nothing to extract.

        EDI/X12: Next iteration (1) of Loop 'G1' starting with 'NAD'

        EDI/X12: skipping segment NAD

        EDI/X12: Entering Loop 'G2' starting with 'RFF'

        EDI/X12: skipping segment RFF

        EDI/X12: Leaving Loop 'G2'

        EDI/X12: Next iteration (2) of Loop 'G1' starting with 'NAD'

        EDI/X12: skipping segment NAD

        EDI/X12: Next iteration (3) of Loop 'G1' starting with 'NAD'

        EDI/X12: skipping segment NAD

        EDI/X12: Entering Loop 'G2' starting with 'RFF'

        EDI/X12: skipping segment RFF

        EDI/X12: Leaving Loop 'G2'

        EDI/X12: Leaving Loop 'G1'

        EDI/X12: Entering Loop 'G6' starting with 'CUX'

        EDI/X12: parsing segment CUX -nothing to extract.

        EDI/X12: Leaving Loop 'G6'

        …

 

 
Once all the segments are assembled according to a grammar, they form a complete electronic document. When you need to transfer several of these electronic documents, you can include them inside a single file. The procedure is named “enveloping”. The envelope data is composed of different additional segments that precedes and follows all the electronic documents. This is illustrated on the following charts:

 

 

 
Functional Groups, often referred to as the “inner envelope,” are made up of one or more documents, all of the same type, which can be batched together into one file. Functional Groups are optional in EDI and (often) mandatory in X12.

 

If present, the UNA segment inside EDI files sets the values of the special characters (i.e. It sets the value of the “Segment Terminator”, the “Data Element Separator”, etc. for the current file).