Getting Started with X12 Translation

Requirements: IP*Works! EDI

Introduction

The IP*Works! EDI suite includes components for reading, writing, and translating X12 documents, as well as the transmission of secure transactions over the Internet. This article will focus on using the EDITranslator component to translate X12 into XML and also XML into X12.

Contents

  1. Converting X12 to XML
  2. Converting XML to X12

Converting X12 to XML

The EDITranslator 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 EDITranslator component provides, so please consult the help document for additional options and details.

Quick Example

Translation with the EDITranslator 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.

Editranslator translator = new Editranslator();

//EDI to XML
translator.SchemaFormat = EditranslatorSchemaFormats.schemaJSON;
translator.InputFormat = EditranslatorInputFormats.ifX12
translator.OutputFormat = EditranslatorOutputFormats.ofXML;
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 = EditranslatorInputFormats.ifXML;
translator.OutputFormat = EditranslatorOutputFormats.ofX12;
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 = EditranslatorSchemaFormats.schemaJSON;
translator.LoadSchema("C:/EDI/schemas/RSSBus_00401_810.json");

Renaming Elements

The EDI Translator 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 XML 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

In order to translate from X12 to XML, the InputFormat must be set to inform the EDITranslator component of the type of data being provided. In this case, this property should be set to X12. You must also instruct the component on the output format. In this case, XML will be selected. After these options are configured, translating is as simple as calling the Translate method. EDI data can be read from a string, a file on disk, or a stream. Likewise, the output 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 X12 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 X12.

Converting XML to X12

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

The InputFormat property must be set to EditranslatorInputFormats.ifXML. This value tells the component to translate from XML. Similarly, the OutputFormat must be set to EditranslatorOutputFormats.ofX12 to instruct the component to format the output as X12 data.

//XML -> X12
Editranslator1.Reset();
Editranslator1.InputFormat = EditranslatorInputFormats.ifXML;
Editranslator1.OutputFormat = EditranslatorOutputFormats.ofX12;

Editranslator1.InputData = translatedXML;

Editranslator1.Translate();

string translatedX12 = Editranslator1.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.