Getting Started with X12Translator

Requirements: X12 Integrator

Introduction

The X12 Integrator suite includes components for reading, writing, and translating X12 documents. This article will focus on using the X12Translator component to translate EDI into XML and also XML into EDI.

Contents

  1. Converting EDI to XML
  2. Converting XML to EDI

Converting EDI to XML

The X12Translator component simplifies the conversion of X12 documents to XML and vice versa. The steps below demonstrate the typical process for these conversions. This guide will not cover all possible functionality the X12Translator component provides, so please consult the help document for additional details.

Quick Example

Translation with the X12Translator component is simple, so the easiest introduction is a quick example. The following sample code will be used as a basis for discussing the details that follow.

X12translator translator = new X12translator();

//EDI to XML
translator.SchemaFormat = X12translatorSchemaFormats.schemaJSON;
translator.LoadSchema("C:/EDI/schemas/RSSBus_00401_810.json");
translator.InputFile = "C:/EDI/myEDIFile.edi";
translator.Translate();
string translatedXML = translator.OutputData;

translator.Reset();

//XML to EDI
translator.InputFormat = X12translatorInputFormats.ifXML;
translator.InputData = translatedXML;
translator.Translate();
string translatedEDI = translator.OutputData;

Loading an EDI Schema

To begin, it is recommended to provide an EDI schema that describes the X12 document that will be translated. This is not required, but it allows details such as proper element names and descriptive details to be included in the translated XML.

If you do not already have a set of schemas the RSSBus JSON schemas (http://www.rssbus.com/schemas/) may be used.

The component supports the following schema formats:

In this article we will use a 810 document with an RSSBus JSON schema. To load the schema call the LoadSchema method. For instance:

translator.SchemaFormat = X12translatorSchemaFormats.schemaJSON;
translator.LoadSchema("C:/EDI/schemas/RSSBus_00401_810.json");

Renaming Elements

The X12Translator component optionally supports renaming EDI elements when translating to XML. By default the XML element names will be automatically determined by the component from the X12 document and schema. For example:

X12 data

ISA*00*          *00*          *ZZ*ACME           *ZZ*WAYNE_TECH     *160707*1544*U*00401*000000006*0*T*>~
GS*IN*ACME*WAYNE_TECH*20160707*1544*6*T*004010~
ST*810*0001~
BIG*20150708*3003014445**0476553272***DR~
CUR*SE*USD~
REF*8M*0056~
N1*BY*Company*92*544380~
N3*Address~
N4*City*CA*Postal Code~
N1*ST*Name*92*0607047800010~
N3*Address~
N4*City**200131*US~
N1*RE*Name*92*5095956~
N3*Address~
N4*City*IL*Postal Code~
IT1*20*2500*EA*36.96**BP*335S0594~
REF*KK*0099778154~
REF*PO*0476553272*20~
TDS*9240000~
CTT*1~
SE*19*0001~
GE*1*6~
IEA*1*000000006~

Translated to EDI without renaming:

<Interchange xmlns="http://www.nsoftware.com">
<Meta>
<ISA01 desc="Authorization Information Qualifier">00</ISA01>
<ISA02 desc="Authorization Information">          </ISA02>
<ISA03 desc="Security Information Qualifer">00</ISA03>
<ISA04 desc="Security Information">          </ISA04>
<ISA05 desc="Interchange ID Qualifier">ZZ</ISA05>
<ISA06 desc="Interchange Sender ID">ACME           </ISA06>
<ISA07 desc="Interchange ID Qualifier">ZZ</ISA07>
<ISA08 desc="Interchange Receiver ID">WAYNE_TECH     </ISA08>
<ISA09 desc="Interchange Date">160707</ISA09>
<ISA10 desc="Interchange Time">1544</ISA10>
<ISA11 desc="Interchange Control Standards Identifier">U</ISA11>
<ISA12 desc="Interchange Control Version Number Code">00401</ISA12>
<ISA13 desc="Inter Control Number">000000006</ISA13>
<ISA14 desc="Acknowlegment Requested Code">0</ISA14>
<ISA15 desc="Interchange Usage Indicator Code">T</ISA15>
<ISA16 desc="Component Element Separator">&gt;</ISA16>
</Meta>
<FunctionalGroup>
<Meta>
<GS01 desc="Functional Identifier Code">IN</GS01>
<GS02 desc="Application Sender&apos;s Code">ACME</GS02>
<GS03 desc="Application Receiver&apos;s Code">WAYNE_TECH</GS03>
<GS04 desc="Date">20160707</GS04>
<GS05 desc="Time">1544</GS05>
<GS06 desc="Group Control Number">6</GS06>
<GS07 desc="Responsible Agency Code">T</GS07>
<GS08 desc="Version / Release / Industry Identifier Code">004010</GS08>
</Meta>
<TransactionSet>
<TX-00401-810 type="TransactionSet">
<Meta>
<ST01 desc="Transaction Set Identifier Code">810</ST01>
<ST02 desc="Transaction Set Control Number">0001</ST02>
</Meta>
<BIG type="Segment">
<BIG01 desc="Date">20150708</BIG01>
<BIG02 desc="Invoice Number">3003014445</BIG02>
<BIG03 desc="Date"/>
<BIG04 desc="Purchase Order Number">0476553272</BIG04>
<BIG05 desc="Release Number"/>
<BIG06 desc="Change Order Sequence Number"/>
<BIG07 desc="Transaction Type Code">DR</BIG07>
</BIG>
<CUR type="Segment">
<CUR01 desc="Entity Identifier Code">SE</CUR01>
<CUR02 desc="Currency Code">USD</CUR02>
</CUR>
<REF type="Segment">
<REF01 desc="Reference Identification Qualifier">8M</REF01>
<REF02 desc="Reference Identification">0056</REF02>
</REF>
<N1Loop1 type="Loop">
<N1 type="Segment">
<N101 desc="Entity Identifier Code">BY</N101>
<N102 desc="Name">Company</N102>
<N103 desc="Identification Code Qualifier">92</N103>
<N104 desc="Identification Code">544380</N104>
</N1>
<N3 type="Segment">
<N301 desc="Address Information">Address</N301>
</N3>
<N4 type="Segment">
<N401 desc="City Name">City</N401>
<N402 desc="State or Province Code">CA</N402>
<N403 desc="Postal Code">Postal Code</N403>
</N4>
</N1Loop1>
<N1Loop1 type="Loop">
<N1 type="Segment">
<N101 desc="Entity Identifier Code">ST</N101>
<N102 desc="Name">Name</N102>
<N103 desc="Identification Code Qualifier">92</N103>
<N104 desc="Identification Code">0607047800010</N104>
</N1>
<N3 type="Segment">
<N301 desc="Address Information">Address</N301>
</N3>
<N4 type="Segment">
<N401 desc="City Name">City</N401>
<N402 desc="State or Province Code"/>
<N403 desc="Postal Code">200131</N403>
<N404 desc="Country Code">US</N404>
</N4>
</N1Loop1>
<N1Loop1 type="Loop">
<N1 type="Segment">
<N101 desc="Entity Identifier Code">RE</N101>
<N102 desc="Name">Name</N102>
<N103 desc="Identification Code Qualifier">92</N103>
<N104 desc="Identification Code">5095956</N104>
</N1>
<N3 type="Segment">
<N301 desc="Address Information">Address</N301>
</N3>
<N4 type="Segment">
<N401 desc="City Name">City</N401>
<N402 desc="State or Province Code">IL</N402>
<N403 desc="Postal Code">Postal Code</N403>
</N4>
</N1Loop1>
<IT1Loop1 type="Loop">
<IT1 type="Segment">
<IT101 desc="Assigned Identification">20</IT101>
<IT102 desc="Quantity Invoiced">2500</IT102>
<IT103 desc="Unit or Basis for Measurement Code">EA</IT103>
<IT104 desc="Unit Price">36.96</IT104>
<IT105 desc="Basis of Unit Price Code"/>
<IT106 desc="Product/Service ID Qualifier">BP</IT106>
<IT107 desc="Product/Service ID">335S0594</IT107>
</IT1>
<REF type="Segment">
<REF01 desc="Reference Identification Qualifier">KK</REF01>
<REF02 desc="Reference Identification">0099778154</REF02>
</REF>
<REF type="Segment">
<REF01 desc="Reference Identification Qualifier">PO</REF01>
<REF02 desc="Reference Identification">0476553272</REF02>
<REF03 desc="Description">20</REF03>
</REF>
</IT1Loop1>
<TDS type="Segment">
<TDS01 desc="Amount">9240000</TDS01>
</TDS>
<CTT type="Segment">
<CTT01 desc="Number of Line Items">1</CTT01>
</CTT>
</TX-00401-810>
</TransactionSet>
</FunctionalGroup>
</Interchange>

For convenience of the entity consuming the XML data the EDI elements can be renamed when converting to XML. Renaming rules take the format EDIName:XMLName. For instance

//renaming rules
translator.AddRenamingRule("GS01:FunctionalIdentifierCode");

The above code will result in XML that is translated with renaming.

<Interchange xmlns="http://www.nsoftware.com">
<Meta>
<ISA01 desc="Authorization Information Qualifier">00</ISA01>
<ISA02 desc="Authorization Information">          </ISA02>
<ISA03 desc="Security Information Qualifer">00</ISA03>
<ISA04 desc="Security Information">          </ISA04>
...
<FunctionalGroup>
<Meta>
<FunctionalIdentifierCode desc="Functional Identifier Code">IN</FunctionalIdentifierCode>
<GS02 desc="Application Sender&apos;s Code">ACME</GS02>
<GS03 desc="Application Receiver&apos;s Code">WAYNE_TECH</GS03>
<GS04 desc="Date">20160707</GS04>
<GS05 desc="Time">1544</GS05>
<GS06 desc="Group Control Number">6</GS06>
<GS07 desc="Responsible Agency Code">T</GS07>
<GS08 desc="Version / Release / Industry Identifier Code">004010</GS08>
</Meta>
<TransactionSet>
<TX-00401-810 type="TransactionSet">
...
</Interchange>

As seen above the XML now contains friendly element names as defined by the renaming rule. To highlight this:

No Renaming:
<GS01 desc="Functional Identifier Code">IN</GS01>

Renaming rule "GS01:FunctionalIdentifierCode":
<FunctionalIdentifierCode desc="Functional Identifier Code">IN</FunctionalIdentifierCode>

Renaming rules can also be saved and loaded by calling SaveRenamingRules and LoadRenamingRules.

UseSchemaName

The UseSchemaName property can be used to easily and automatically rename XML elements according to the EDI schema. This property only applies when using the RSSBus JSON schemas. If set to true, the element names in the translated EDI are taken from the ID values of the EDI elements in the schema files.

For example, here is a portion of the result when the above EDI document is translated with UseSchemaName set to true:

<Interchange xmlns="http://www.nsoftware.com">
<Meta>
<ISA01 desc="Authorization Information Qualifier">00</ISA01>
<ISA02 desc="Authorization Information">          </ISA02>
...
<CUR type="Segment">
<_98 desc="Entity Identifier Code">SE</_98>
<_100 desc="Currency Code">USD</_100>
</CUR>
<REF type="Segment">
<_128 desc="Reference Identification Qualifier">8M</_128>
<_127 desc="Reference Identification">0056</_127>
</REF>
<N1Loop1 type="Loop">
<N1 type="Segment">
<_98 desc="Entity Identifier Code">BY</_98>
<_93 desc="Name">Company</_93>
<_66 desc="Identification Code Qualifier">92</_66>
<_67 desc="Identification Code">544380</_67>
</N1>
...
</Interchange>

Note that element names that would begin with an integer are prefixed by the "_" character in order to be valid XML.

Translating to XML

Translating from EDI to XML is as simple as calling the Translate method. EDI data can be read from a string, a file on disk, or a stream. Likewise XML data can be saved to a string, a file on disk, or a stream. Please refer to the Quick Sample section for a code example.

After translating the EDI data to XML you may optionally call ExportXMLSchema. This method outputs an XML schema (.xsd) to the file path passed as a parameter. This can be helpful when constructing XML messages outside of the component which can later be translated back to EDI.

Converting XML to EDI

To translate XML to EDI specify the XML input, set InputFormat to indicate that the input is XML, and call the Translate method. An EDI schema is not required.

The InputFormat property must be set to X12translatorInputFormats.ifXML. This value tells the component to translate from XML to EDI instead of the other way around. The output format is always assumed based on the value set in InputFormat.

//XML -> EDI
X12Translator1.Reset();
X12Translator1.InputFormat = X12translatorInputFormats.ifXML;
X12Translator1.InputData = translatedXML;

X12Translator1.Translate();

string translatedEDI = X12Translator1.OutputData;


We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.