EDI Translation Components

The toolkit includes components for the EDI standards EDIFACT and X12. The components can be used to read, translate, or create documents. The following components are available:

EDIFACTReader Parses an incoming EDIFACT document so you may read the data in the document.
EDIFACTValidator Validates the contents of an EDIFACT document and returns any errors.
EDIFACTWriter Generates new EDIFACT documents from scratch.
EDIFACTTranslator Provides a simple way to convert EDIFACT to XML and vice versa.
X12Reader Parses an incoming X12 document so you may read the data in the document.
X12Validator Validates the contents of an X12 document and returns any errors.
X12Writer Generates new X12 documents from scratch.
X12Translator Provides a simple way to convert X12 to XML and vice versa.

EDI Documents: Segments

The primary structure of EDI documents are segments. Each segment contains a specific set of known (expected) data. In many cases, a segment is represented as a single line. Segments are separated by a segment delimiter.

Each segment starts with a tag that identifies the kind of data the segment contains. However, tags are not unique, and the context will determine the information the tag represents. Examples of tags are ISA, GS, N4, etc. Here's an example X12 segment in which the tag of the segment is BIG and the "~" character is the segment delimiter: 

BIG*19971211*00001**A99999-01~
A segment can be further decomposed into 0 or more data elements. The sample segment above contains 4 data elements (delimited by '*'), with one of them being empty. Elements are located within a segment by their position, which is why empty elements must be represented with successive asterisks as shown in the example above. However, if an element is optional (doesn't require a value) and there are no other elements with a value after that, it may not appear. In other words, the fact that the segment in the instance document contains 4 data elements does not mean that it always will if the remaining data elements are empty.

In some cases a data element can be a composite element, split into components separated with a different delimiter, for example: 

DTM+137:20000101:102'
This sample EDIFACT segment uses a single quote (') as the segment delimiter, '+' as the element delimiter, and ':' as the component delimiter, so it has a single data element with 3 components.

EDI Documents: Structure

As described previously, the structure of entire EDI documents is made out of segments, with header/footer segment pairs forming nested envelopes around the data. These envelopes are well known and organized as follows:

  • All EDI Interchanges (documents) contain interchange header and footer segments. This is the outer envelope. The interchange header segment contains information such as an interchange ID, where it comes from, and where it should go. The interchange footer segment contains information that allows you to validate that the interchange is complete.
  • An EDI Transaction (commonly called a message in EDIFACT) contains the actual EDI data. Again, each transaction contains header and footer segments that identify the type of transaction (i.e. an invoice or a purchase order), the number of segments, etc.
  • An Interchange can contain EDI transactions directly, but transactions can also be grouped inside functional groups. Each functional group contains its own header and footer segments. The information contained in the group header and footer depends on the specification, but it generally identifies the type of transactions contained in the group and the specification version used.

In EDIFACT and X12, the header and footer segments for interchanges, functional groups, and transactions have known tags. Below is a table that identifies the Segment Type and its corresponding tag in X12 and EDIFACT:

Segment Type X12 Tag EDIFACT Tag
Service String Advice-UNA
Interchange Header ISA UNB
Functional Group Header GS UNG
Transaction Header ST UNH
Transaction Footer SE UNT
Functional Group Footer GE UNE
Interchange Footer IEA UNZ
Note: The Service String Advice segment only occurs in EDIFACT documents and may appear at the start of the document. It serves to let the parser determine the delimiters that will be used in the rest of the document. Here's an example of a Service String Advice Segment: 
UNA:+.? '
This specifies that the component delimiter will be ':', the element delimiter will be '+', the escape character will be '?' and the segment delimiter will be the single quote ('). The '.' is the decimal point character, and the space ' ' is reserved for future use.

Parsing Transactions: Loading and Compiling Schemas

Before loading or writing a document with the reader or writer components, a schema will need to be loaded using the LoadSchema() method. The LoadSchema() method can parse schemas and use them for basic validation and interpretation of EDI documents at runtime.

The components also support parsing an EDI or X12 document without loading a schema. Note that in this scenario descriptions of segments and elements will not be available, and the document will not be validated.

EDIFACT Schema Format

EDI SDK's schemas use an intuitive XML format, where each version of a standard is contained in a single file. That file uses the version number as the name of the root element, and contains sections for defining messages, segments that appear in those messages, elements that might appear in a segment, and valid code values for certain elements.

Optional Schema Development Services

Customers can create their own schemas or optionally take advantage of our schema development professional services to convert existing EDI schemas to our custom format. Contact support@nsoftware.com for more details.

Root Element

To create a new EDIFACT schema, first create the root element and name it based on the version of the standard that you want to use, such as "D97A" or "D21B". Then add each of the four sections of the schema:

<D23A> <Messages> ... </Messages> <Segments> ... </Segments> <Elements> ... </Elements> <Codes> ... </Codes> </D23A>

Messages

The Messages section contains all defined messages. See the following as an example:

<Messages> <APERAK desc="Application error and acknowledgement" category="Transport"> ... </APERAK> <AUTHOR desc="Authorization" category="Finance"> ... </AUTHOR> ...... </Messages>

A message tag uses the message type as the tag name. It has a "desc" attribute with a human-readable description of the message and a "category" attribute that specifies what category of EDI message it belongs to. The message tag also contains a representation of any segments and groups of segments that appear in the message, like this:

<APERAK desc="Application error and acknowledgement" category="Transport"> <UNH/> <BGM/> <DTM req="0" maxcount="9"/> <FTX req="0" maxcount="9"/> <CNT req="0" maxcount="9"/> <DOCGroup req="0" maxcount="99"> ... </DOCGroup> <RFFGroup req="0" maxcount="9"> ... </RFFGroup> <NADGroup req="0" maxcount="9"> ... </NADGroup> <ERCGroup req="0" maxcount="99999"> ... </ERCGroup> <UNT/> </APERAK>

Every segment or group in a message definition has 2 attributes: "req" and "maxcount".

  • "req" : If 'req="0"' appears, the segment/group is optional. If "req" doesn't appear, the segment/group is considered mandatory.
  • "maxcount": Specifies the maximum number of times the segment or group can appear. Must be an integer value. If "maxcount" is not specified, the segment or group may only appear once.

To add a new message type, add an XML element inside the Messages section, then lay out the structure of the segments that should appear within the message.

Groups contain a list of segments, which can also be further organized into subgroups. For example:

<ERCGroup req="0" maxcount="99999"> <ERC/> <FTX req="0"/> <RFFGroup2 req="0" maxcount="9"> <RFF/> <FTX req="0" maxcount="9"/> </RFFGroup2> </ERCGroup>

Segments

The Segments section contains all defined segments:

<Segments> <AAI desc="Accommodation allocation information"> ... </AAI> <ADI desc="Health care claim adjudication information"> ... </ADI> ...... </Segments>

Every segment has a "desc" attribute, which contains a human-readable description of the segment. It also contains an ordered list of elements that appear within the segment.

To add a new segment, create an XML tag with a matching name and add a list of elements. Elements in the list should be named with the segment name followed by a position, such as "ADI-060" for the sixth element in the ADI segment. <ADI desc="Health care claim adjudication information"> <ADI-010 ref="EE206" maxcount="3"/> <ADI-020 ref="EE021" req="0" maxcount="3"/> <ADI-030 ref="E1229" req="0"/> <ADI-040 ref="EE017" req="0" maxcount="15"/> <ADI-050 ref="E6060" req="0" maxcount="3"/> <ADI-060 ref="EE030" req="0" maxcount="15"/> <ADI-070 ref="E9620" req="0" maxcount="4"/> <ADI-080 ref="E5389" req="0"/> <ADI-090 ref="EE507" req="0"/> <ADI-100 ref="E9639" req="0"/> <ADI-110 ref="E5482" req="0"/> </ADI>

Every element in a segment has 3 attributes: "ref", "req" and "maxcount".

  • "ref" : This value is used to referenced the element in the Elements list (see Section 4).
  • "req" : If 'req="0"' appears, the element is optional. If "req" doesn't appear, the element is considered mandatory.
  • "maxcount" : Specifies the maximum number of times the element can appear. Must be an integer value. If the "maxcount" attribute is not present, the element may only appear once.

Note: Header and footer segments such as UNB, UNG, UNH, UNT, UNE, and UNZ are recognized by the EDIFACT components by default, and do not need to be added to the Segments section.

Elements

The Elements section contains all defined elements. See the following:

<Elements> <E0035 type="N" minlen="1" maxlen="1" desc="Test indicator"/> <E0051 type="AN" minlen="1" maxlen="3" desc="Controlling agency, coded"/> ...... <EC001 type="composite" desc="Transport means"> <C001-010 ref="E8179" req="0"/> <C001-020 ref="E1131" req="0"/> <C001-030 ref="E3055" req="0"/> <C001-040 ref="E8178" req="0"/> </EC001> ...... </Elements>

For each of the elements referenced in a segment, you will need to add the element to the Elements section of the schema. The structure of the XML will depend on whether the element is a simple element (contains only one value) or a composite element (contains multiple related values). All elements' names have the prefix 'E' followed by the element's identifier.

Simple Element

A simple element has 5 attributes ("type", "min", "max", "codes" and "desc") and no child elements: <E1001 type="AN" minlen="1" maxlen="3" codes="C1001" desc="Document name code"/>

  • "type": The valid characters for the value. This can be "A", "AN" or "N". ("A" means alphabetic only; "N" means numeric (0~9) only; "AN" means any alphanumeric character)
  • "minlen" : The minimum length of the value.
  • "maxlen" : The maximum length of the value.
  • "codes" : If this appears, it indicates that the valid values for this element are defined in the Codes element (see Section 5).
  • "desc": A human-readable description of the element.

Composite Element

A composite element's name will have a second letter after the initial 'E'. It also has a "type" attribute (which is always "composite") and a "desc" attribute with a description of the element. It contains tags for each of its component elements, with references to a simple element definition for each component:

<EC001 type="composite" desc="Transport means"> <C001-010 ref="E8179" req="0"/> <C001-020 ref="E1131" req="0"/> <C001-030 ref="E3055" req="0"/> <C001-040 ref="E8178" req="0"/> </EC001>

  • Every component has a name in the format of "[Element Name]-[Component Position]". For example, for component "C001-030", the "Element Name" is "C001", and the "Component Position" is "030"
  • Every component element has 2 attributes: "ref" and "req":
    • "ref" : Contains a reference to the type of simple element that should appear in that location.
    • "req" : If 'req="0"' appears, the component is optional. If the "req" attribute doesn't appear, the component is mandatory.

After adding a composite element, each of its components should be added to the Elements section as simple elements as well.

Codes

The Codes element contains all defined codes, which specify the valid values for elements. See the following:

<Codes> <C1001 desc="Document name code"> ... </C1001> <C1049 desc="Message section code"> ... </C1049> ...... <Codes>

For any elements that have a "codes" attribute, create an entry in the Codes section of the schema. The name of the XML element should start with C and match the value in the "codes" attribute of the element that uses the list. The only attribute is the "desc" attribute, which contains a human-readable description of the code.

For each valid value, add an "Item" element with a "value" attribute containing the value. The item should also have a "desc" attribute describing its meaning.

<C1049 desc="Message section code"> <Item value="1" desc="Heading section"/> <Item value="2" desc="Detail section"/> <Item value="5" desc="Multiple sections"/> <Item value="6" desc="Summary section"/> <Item value="7" desc="Sub-line item"/> <Item value="8" desc="Commercial heading section of CUSDEC"/> <Item value="9" desc="Commercial line detail section of CUSDEC"/> <Item value="10" desc="Customs item detail section of CUSDEC"/> <Item value="11" desc="Customs sub-item detail section of CUSDEC"/> </C1049>

Once all of the codes have been added, the schema should be ready for use. To test it, you can try loading the schema in the EDIFACTReader component and parsing a message of the appropriate type:

EDIFACTReader reader = new EDIFACTReader(); reader.LoadSchema("C:/Path/to/D23A.xml", "APERAK"); reader.InputFile = "C:/Path/to/Example_APERAK.edi"; reader.Parse();

X12 Schema Format

EDI SDK's schemas use an intuitive XML format, where each version of a standard is contained in a single file. That file uses the version number as the name of the root element, and contains sections for defining transaction sets, segments that appear in those transaction sets, elements that might appear in a segment, and valid code values for certain elements.

Optional Schema Development Services

Customers can create their own schemas or optionally take advantage of our schema development professional services to convert existing EDI schemas to our custom format. Contact support@nsoftware.com for more details.

Root Element

To create a new X12 schema, first create the root element and name it based on the version of the standard that you want to use, such as "R5010" or "R8030". Then add each of the four sections of the schema:

<R5010> <TransactionSets> ... </TransactionSets> <Segments> ... </Segments> <Elements> ... </Elements> <Codes> ... </Codes> </R5010>

Transaction Sets

The TransactionSets section contains all defined transaction sets. See the following as an example:

<TransactionSets> <T100 desc="Insurance Plan Description" category="Insurance"> ... </T100> <T101 desc="Name and Address Lists" category="Supply Chain"> ... </T101> ...... </TransactionSets>

A transaction set tag uses the transaction type as the tag name. It has a "desc" attribute with a human-readable description of the transaction set and a "category" attribute that specifies what category of EDI transaction it belongs to. The tag also contains a representation of any segments and loops of segments that appear in the transaction set, like this:

<T101 desc="Name and Address Lists" category="Supply Chain"> <ST/> <BGN/> <DTMLoop maxcount="unlimited"> <DTM/> <N1 maxcount="unlimited"/> <N9Loop req="0" maxcount="unlimited"> <N9/> <LXLoop maxcount="unlimited"> <LX/> <IN2 req="0" maxcount="unlimited"/> <NX2 req="0" maxcount="unlimited"/> <REF req="0" maxcount="unlimited"/> <SPA req="0"/> <COM req="0" maxcount="unlimited"/> </LXLoop> </N9Loop> </DTMLoop> <SE/> </T101>

Every segment or loop in a transaction set definition has 2 attributes: "req" and "maxcount".

  • "req" : If 'req="0"' appears, the segment/loop is optional. If "req" doesn't appear, the segment/loop is considered mandatory.
  • "maxcount": Specifies the maximum number of times the segment or loop can appear. This can either be "unlimited" or a specific integer value. If "maxcount" is not specified, the segment or loop may only appear once.

To add a new transaction set, add an XML element inside the TransactionSets section, then lay out the structure of the segments that should appear within the transaction set.

Loops contain a list of segments, which can contain nested loops. For example:

<N9Loop req="0" maxcount="unlimited"> <N9/> <LXLoop maxcount="unlimited"> <LX/> <IN2 req="0" maxcount="unlimited"/> <NX2 req="0" maxcount="unlimited"/> <REF req="0" maxcount="unlimited"/> <SPA req="0"/> <COM req="0" maxcount="unlimited"/> </LXLoop> </N9Loop>

Segments

The Segments section contains all defined segments:

<Segments> <AAA desc="Request Validation"> ... </AAA> <ACD desc="Account Description"> ... </ACD> ...... </Segments>

Every segment has a "desc" attribute, which contains a human-readable description of the segment. It also contains an ordered list of elements that appear within the segment.

To add a new segment, create an XML tag with a matching name and add a list of elements. Elements in the list should be named with the segment name followed by a position, such as "ACT-06" for the sixth element in the ADI segment. <ACT desc="Account Identification"> <ACT-01 ref="E508"/> <ACT-02 ref="E93" req="0"/> <ACT-03 ref="E66" req="0" rule="P0304"/> <ACT-04 ref="E67" req="0"/> <ACT-05 ref="E569" req="0" rule="C0506"/> <ACT-06 ref="E508" req="0"/> <ACT-07 ref="E352" req="0" rule="C0705"/> <ACT-08 ref="E107" req="0"/> <ACT-09 ref="E1216" req="0"/> </ACT>

Every element in a segment has 3 attributes: "ref", "req" and "maxcount".

  • "ref" : This value is used to referenced the element in the Elements list (see Section 4).
  • "req" : If 'req="0"' appears, the element is optional. If "req" doesn't appear, the element is considered mandatory.
  • "rule" : Specifies when the segment appears relative to other segments. A rule consists of a letter that specifies the type of rule and two or more two-digit element numbers indicating which elements within the segment the rule applies to:
    • 'C' : Conditional - If the first element appears, all the other listed elements are mandatory. If the first element is absent, the other elements are optional.
    • 'L' : List Conditional - If the first element appears, at least one of the other listed elements must appear.
    • 'P' : Paired - If any of the listed elements appear, all of the listed elements must be present.
    • 'R' : Required - At least one of the listed elements must appear in the segment.
    • 'E' : Exclusive - At most one of the listed elements may appear in the segment.

Note: Header and footer segments such as ISA, IAE, GS, GE, ST, and SE are recognized by the X12 components by default, and do not need to be added to the Segments section.

Elements

The Elements section contains all defined elements. See the following:

<Elements> ...... <E7 type="AN" minlen="6" maxlen="17" desc="Bank Account Number"/> <E8 type="ID" minlen="1" maxlen="1" codes="C8" desc="Bank Client Code"/> ...... <EC002 type="composite" desc="Actions Indicated"> <C002-01 ref="E704"/> <C002-02 ref="E704" req="0"/> <C002-03 ref="E704" req="0"/> <C002-04 ref="E704" req="0"/> <C002-05 ref="E704" req="0"/> </EC002> ...... </Elements>

For each of the elements referenced in a segment, you will need to add the element to the Elements section of the schema. The structure of the XML will depend on whether the element is a simple element (contains only one value) or a composite element (contains multiple related values). All elements' names have the prefix 'E' followed by the element's identifier.

Simple Element

A simple element has 5 attributes ("type", "min", "max", "codes" and "desc") and no child elements: <E1001 type="AN" minlen="1" maxlen="3" codes="C1001" desc="Document name code"/>

  • "type": The valid characters for the value. This can be "A", "AN" or "N". ("A" means alphabetic only; "N" means numeric (0~9) only; "AN" means any alphanumeric character)
  • "minlen" : The minimum length of the value.
  • "maxlen" : The maximum length of the value.
  • "codes" : If this appears, it indicates that the valid values for this element are defined in the Codes element (see Section 5).
  • "desc": A human-readable description of the element.

Composite Element

A composite element's name will have a second letter after the initial 'E'. It also has a "type" attribute (which is always "composite") and a "desc" attribute with a description of the element. It contains tags for each of its component elements, with references to a simple element definition for each component:

<EC002 type="composite" desc="Actions Indicated"> <C002-01 ref="E704"/> <C002-02 ref="E704" req="0"/> <C002-03 ref="E704" req="0"/> <C002-04 ref="E704" req="0"/> <C002-05 ref="E704" req="0"/> </EC002>

  • Every component has a name in the format of "[Element Name]-[Component Position]". For example, for component "C001-030", the "Element Name" is "C001", and the "Component Position" is "030"
  • Every component element has 2 attributes: "ref" and "req":
    • "ref" : Contains a reference to the type of simple element that should appear in that location.
    • "req" : If 'req="0"' appears, the component is optional. If the "req" attribute doesn't appear, the component is mandatory.

After adding a composite element, each of its components should be added to the Elements section as simple elements as well.

Codes

The Codes element contains all defined codes, which specify the valid values for elements. See the following:

<Codes> <C8 desc="Bank Client Code"> ... </C8> <C9 desc="Late Reason Code"> ... </C9> ...... <Codes>

For any elements that have a "codes" attribute, create an entry in the Codes section of the schema. The name of the XML element should start with C and match the value in the "codes" attribute of the element that uses the list. The only attribute is the "desc" attribute, which contains a human-readable description of the code.

For each valid value, add an "Item" element with a "value" attribute containing the value. The item should also have a "desc" attribute describing its meaning.

<C8 desc="Bank Client Code"> <Item value="E" desc="Payee"/> <Item value="R" desc="Payer"/> </C8>

Once all of the codes have been added, the schema should be ready for use. To test it, you can try loading the schema in the X12Reader component and parsing a transaction of the appropriate type:

X12Reader reader = new X12Reader(); reader.LoadSchema("C:/Path/to/R5010.xml", "T101"); reader.InputFile = "C:/Path/to/Example_T101.edi"; reader.Parse();