Getting Started with EDI Objects for X12

Requirements:
EDISDK

Introduction

EDI Objects in EDI SDK provide a strongly typed, schema-driven interface to X12 documents. EDI Objects model X12 documents as an object (class) hierarchy that matches a given X12 schema. As a result, developers do not need to navigate segments through tag names and tracking element positions, but rather can use an intuitive set of named properties and methods to read, write, and modify EDI data.

The first section of this guide covers the process of generating EDI Objects:

• Importing X12 schema files into EDI SDK
• Using the CLI tool to create EDI Objects from schema files

The second section provides an introduction to using EDI Objects:

• Using EDI Objects to read X12 documents
• Handling repeating X12 segments
• Working with mixed transaction set types
• Using EDI Objects to write X12 documents

Generating EDI Objects

EDI Objects are generated from EDI schema files. EDI SDK includes the tools necessary to import these schema files, then generate the class files that make up EDI Objects.

Importing X12 Schema Files

X12 schemas are not distributed with EDI SDK, and should be acquired from a licensed source. Once acquired, EDI SDK provides the tools necessary to import these schema files so that they can be used to generate EDI Objects.

Our X12 Import Guide provides details on how to import schema files for further use.

Creating EDI Object Class Files

Once the X12 schemas are imported, the resulting XML can be used along with the ediobjects.exe tool to generate classes that reflect the message, segment, and element structure. This ensures consistent, reliable classes across all message types.

First, identify the version and specific messages required. For example, an organization using X12 4010 may need the 810 and 850 EDI Objects.

The CLI command follows this pattern for X12:

./ediobjects.exe "/path/to/4010.xml" -m 810,850 -o "/path/to/X12Out/" -l java

Omitting the -m flag will default to generating EDI Objects for all transaction sets in the source directory.

Generated EDI Objects provide classes for all messages, groups, segments, and elements, reflecting the schema hierarchy. Repeating segments and groups are exposed as collections, and nested structures are represented through the object hierarchy. Each set of EDI Objects supports reading, writing, and validating without requiring separate classes or helper modules for each task.

The generated EDI Objects code is fully accessible, allowing inspection and easy integration into existing projects. Because all EDI Objects follow the same structure, adding support for additional message types requires only generating the new EDI Objects and including it in the build. For trading partners using custom implementations or when extending standard specifications, EDI Objects can be regenerated from modified schemas and integrated seamlessly.

Using EDI Objects

Once generated, EDI Objects can be used to easily read, write, and modify X12 documents. This section provides an introduction to common operations using EDI Objects.

Using EDI Objects to Read X12 documents

The object-oriented interface of EDI Objects means that reading X12 documents becomes a matter of accessing named properties rather than parsing segment tags and element positions.

Accessing Segment Data

Unlike traditional methods that rely on element positions, EDI Objects provide explicit property paths:

itemNumber = po1loop.PO1.ProductServiceId1.Value;

Property names derive directly from the EDI specification, making the code self-documenting. The structure reflects the schema exactly, eliminating ambiguity about composite contents or element positions within the hierarchy.

Handling Repeating Segments

EDI transaction sets frequently contain repeating segments and loops. EDI Objects represent these as collections, enabling natural iteration without segment counters or manual index management.

Processing ID codes from multiple N1 Loops:

foreach (var n1Loop in order.N1LoopList)
{
  if (n1Loop.N1.EntityIdentifierCode1.CodeValueDesc == "Ship To")
  {
   string idCode = n1Loop.N1.IdentificationCode.Value;
  }
} 

EDI Objects handle repeating segments internally, letting programs focus on business logic like checking qualifiers and extracting quantities.

Working with Mixed transaction set Types

EDI interchanges can contain multiple transaction set types in a single file. EDI Objects handle this by exposing all transaction sets through a common ITransactionSet interface. Each transaction set is automatically routed to a handler method that matches its specific type.

One option for C# is to use the dynamic keyword:

foreach (ITransactionSet transactionSet in funcGroup.TransactionSets)
{
  Process((dynamic)transactionSet, lineItems);
}
  
private static void Process(T810 order, List<LineItem> lineitems) { ... } 
private static void Process(T850 order, List<LineItem> lineitems) { ... } 

In Java, the correct method is found and called based on the transaction set type:

for (ITransactionSet tset : fGroup.getTransactionSets()) {
  System.out.println(tset.getClass());
  processTransactionSet(tset, lineItems);
}
  
private static void processTransactionSet(Object tset, List<LineItem> items) { 
  Method m = x12ediobjectreader.class.getDeclaredMethod(
    "processTransactionSet",
    tset.getClass(),
    List.class
  );
  m.invoke(null, tset, items);
} 

private static void processTransactionSet(T850 order, List<LineItem> lineitems) {...}
private static void processTransactionSet(T810 order, List<LineItem> lineitems) {...} 

This approach eliminates the need to manually inspect transaction set header segments to determine transaction set type. The EDI Objects provides the correctly typed object, and the handler methods route each transaction set to the appropriate processing logic. The same iteration code handles files containing any combination of transaction set types.

Using EDI Objects to Write X12 documents

Creating X12 documents with EDI Objects follows the same property-based approach used for reading. The schema-driven structure ensures values can only be assigned to valid locations.

Building Document Structure

Creating a document involves instantiating the transaction set type and populating its properties:

T850 t850 = new T850();
//ST*850*000000002~
t850.ST.TransactionSetControlNumber.Value = "000000002";
//BEG*00*DS*0476696888**20090320~
t850.BEG.TransactionSetPurposeCode.Value = "00";
t850.BEG.PurchaseOrderTypeCode.Value = "DS";
t850.BEG.PurchaseOrderNumber.Value = "0476696888";
t850.BEG.Date.Value = "20090320";

Value validation occurs when the document is written. As the EDI Objects serializes the document to EDI format, values are validated against schema requirements. Individual elements and components include a checkValue() method that can be called to validate specific data points before writing the complete document.

Adding Line Items

Repeating groups are created by adding instances to the appropriate collection:

T850.TN1Loop n1Loop = new T850.TN1Loop();
n1Loop.N1.EntityIdentifierCode1.Value = "ST";
n1Loop.N1.Name.Value = "BUYSNACKS PORT";
n1Loop.N1.IdentificationCodeQualifier.Value = "91";
n1Loop.N1.IdentificationCode.Value = "1223334445";
t850.N1LoopList.Add(n1Loop);

The EDI Objects maintains proper segment ordering and hierarchy, ensuring that line items and their child segments appear in the correct location within the document structure.

Next Steps

The consistent structure across all EDI Objects means that knowledge of one TransactionSet type translates directly to others. Whether working with X12 shipping notices or custom transaction set types, the property-based approach remains the same. As additional transaction set types are needed, generate the corresponding EDI Objects and integrate it into the project using the same patterns established with the first TransactionSet type.