EDI Templates

What are EDI templates?

EDI template is any .NET class that is annotated (both the class itself and its properties) with our DOM attributes.

The purpose of EDI Templates is:

  • To represent the structure of EDI transactions as described in their implementation guides
  • To be lightweight and easy for modification
  • To support inheritance and to implement common interfaces
  • To be ready for XML serialization
  • To be ready for JSON serialization
  • To be Entity Framework POCOs

The above statements mean that you can turn any .NET class into EDI template regardless. This comes in handy if you plan to use your existing domain model to support EDI rather than having to maintain a separate model just for EDI.

Check out the full example solutions here:

 

 

 


 

 

 

What is EDI DOM?

EDI Document Object Model (EDI DOM) is a new approach for handling EDI files or EDI documents programmatically in the same way modern browsers handle XML and HTML.

All EDI specifications are usually distributed in the form of PDF files accompanied by machine-readable XML schemas (XSDs). It is widely accepted that EDI can be converted to XML and then handled via XML DOM or some sort of wrapper around it. We've taken a step back in this approach and cut out XML completely. Our DOM model relies purely on OOP classes and annotations to represent EDI transactions. EDI documents are then parsed to instances of those same EDI transaction classes.

The same way as XML provides access to its data via a unified set of attributes, elements, and interfaces, EDI DOM introduces a set of annotations that can turn plain C# classes and class hierarchies into fully compliant EDI specifications. The benefits of this approach are obvious but let's mention some of them:

  • Simplified mapping - EDI documents are parsed directly to instances of the DOM classes. There is no need for graphical mapping software, XSLT, or other quirky mapping techniques.
  • Easy customization - EDI specifications are simple C# classes that can be edited with any text editor. Changes are trivial and adhering to any partner-specific format is quick, easy, and does not require EDI experience.
  • Performance gain - EDI documents are streamed directly into instances of the C# EDI DOM classes, hence there are no internal hops and no XML serialization.
  • Developer friendly - EDI documents are transposed directly to .NET POCOs. They become part of the existing domain model with no extra treatment and without having to adopt additional technologies or applications.

 

 

 


 

 

 

How to represent my EDI Guideline with EDI Template?

Step 1: Ensure that the guideline is correctly represented by the EDI template. Look for:

  • Correct position of the segment\loop, represented by the PosAttribute
  • Segment names, represented by the class name
  • Loop names, represented by the name of the first segment in the loop
  • Correct usage, represented by the RequiredAttribure if mandatory and no attribute if optional
  • Correct number of repetitions, represented by the ListCountAttribute

amceclip1.png

  

 

 


 

 

 

Step 2: Do the same for each loop, segment, and composite data element. Look for:

 

amceclip2.png

 


 

 

 

How to modify my EDI Templates?

Overview

Sometimes you may need to modify your existing EDI template(s) for reasons such as:

  1. A trading partner uses an extra filed for segment ABC
  2. A trading partner uses loop ABC before loop DEF
  3. My DBA wants to add some extra properties for the table primary keys

It is perfectly fine to go ahead and do any of these changes. The rule of thumb is to maintain the baseline version in a separate project and to move all partner-specific customization into their own projects. This way the baseline version is shielded from any changes and all new modifications are safely isolated into their own containers.

 

 

 


 

 

 

Trading partner-specific customization

For example - let's assume that you exchange X12 4010 EDI messages with multiple trading partners. A new trading partner comes along, however, they use a custom representation of BEG segments, which introduces a new property and marks the release number at position 4 as mandatory for validation.

Download the example projects:

Keep the standard X12 templates in a separate project. A good design is to also move the segment and complex interfaces files into a separate project and add a reference to it:

mceclip0.png

Create a separate project, for this particular trading partner only, let's call it PartnerB. Then copy the file for message 850, the segments file, the EDI codes file, and the complex elements file, to which we are going to apply all the partner-specific modifications.

mceclip1.png

Ensure to add a reference to the common interfaces project, given that you created one.

Open EF_X12_004010_Segments.cs and apply the following modifications to the BEG segment:

mceclip5.png

mceclip4.png

The changes are:

  • The property at position 4 is marked as [Required]
  • A new property is added at position 13 - NewField_13

The modification will let the new template to support the following BEG segment:

BEG*00*SA*XX-1234*MANDATORY*20170301**NA******NEWVALUE~

where NEWVALUE is at position 13.

We now have two projects defining a template for purchase order (TS 850), so how to tell the parser when to use which one? In the event of knowing the origin of the EDI file you can simply change the template assembly in the X12Reader constructor like this:

// partnerSource can be folder name, file name, etc.
string templateAssembly = "EdiFabric.Examples.X12.Templates.V4010";
if(partnerSource == "ParnerB")
templateAssembly = "EdiFabric.Examples.X12.Templates.V4010.PartnerB";

using (var ediReader = new X12Reader(ediStream, templateAssembly))

 

 

 


 

 

 

Load Factory

All modifications can be dynamically loaded by using a load factory. Every EDI document identifies the sender by the Sender ID in the ISA\UNB segment. This identifier is unique across the trading partners you'll be exchanging messages with.

For our scenario above, we need to identify the trading partner that uses the modified BEG segment and to load the TS850 template from the customized project. For all other trading partners, we will be loading the baseline version of the TS850 template.

Let's assume that this trading partner ID is CUSTOM1 and when we receive EDI document from this partner:

ISA*00* *00* *16*CUSTOM1 *1B*RECEIVER1 *071216*1406*U*00204*000000263*1*T*>~

we will load the modified template:

abmceclip1.png

and tell the reader to use this logic when reading EDI documents:

var ediReader = new X12Reader(ediStream, FullTemplateFactory)

  

 

 


 

 

 

 

How to add custom properties to my EDI Templates?

Sometimes you might need to modify your existing EDI template(s) and add your own custom properties that are irrelevant to both the parser and EDI in general. This is known as "mixed-mode" when the template is used not only for EDI but for other purposes as well.

All you need to do is to simply add the property. The parser only uses properties annotated with PosAttribute and discards all others. You can take a look at the Id property we added to every class in order to be used by Entity Framework as a POCO:

 

mceclip6.png

You still have to add all the properties needed for serialization to XML\JSON.

 

 

 

 


 

 

 

EDI Templates and Inheritance

All templates support inheritance. This allows you to define a custom template that reuses, extends, or modifies the behavior of an original template.

When EdiFabric Framework is incorporated into any existing applications, the common architecture is to introduce a mapping layer to convert the instances of EDI templates into instances of other classes, usually database or the existing domain.

EDI template inheritance minimizes the impact to that mapping layer when template modifications are required. Any new template that inherits from another template, retains the existing mapping functionality applicable to the original template. The mapping logic for the modification can be implemented in a separate component thus having no impact whatsoever on the existing maps.

EDI template inheritance can be applied to any EDI DOM class by following these rules:

  • Inherited classes must still define all DOM and validation attributes. For example, if you want to inherit from

The new class must still define the original DOM attributes:

  • Hidden or overridden properties must still define all DOM and validation attributes. For example, if want to add an extra validation attribute to ReleaseNumber_04 property and make it mandatory

 

The new class must still define the original DOM attributes:

  • To ensure that properties in a base and any inherited classes do not duplicate positions. The parser will throw an exception if there are any properties marked with the PosAttribute for the same position.
Was this article helpful?
2 out of 2 found this helpful