Getting Started with X12 Translation

Requirements:
IPWorks EDI

Introduction

IPWorks EDI and IPWorks EDI Translator include components for reading, writing, and translating X12 documents. This article will focus on using the X12Translator component to translate X12 into XML or JSON and vice versa.

Contents

  1. Converting X12 to XML
  2. Converting X12 to JSON
  3. Converting XML to X12
  4. Converting JSON to X12

Converting X12 to XML

The X12Translator component simplifies the conversion of X12 documents to XML or JSON 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 options and 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 x12translator = new X12translator(); //EDI to XML x12translator.SchemaFormat = X12translatorSchemaFormats.schemaJSON; x12translator.InputFormat = X12translatorInputFormats.xifX12; x12translator.OutputFormat = X12translatorOutputFormats.xofXML; x12translator.LoadSchema("C:\\schemas\\00401_810.json"); x12translator.InputFile = myEDIFile; x12translator.Translate(); string translatedXML = x12translator.OutputData; x12translator.Reset(); //XML to EDI x12translator.InputFormat = X12translatorInputFormats.xifXML; x12translator.OutputFormat = X12translatorOutputFormats.xofX12; x12translator.InputData = translatedXML; x12translator.Translate(); string translatedEDI = x12translator.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.

The component supports the following schema formats:

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

x12translator.SchemaFormat = X12translatorSchemaFormats.schemaJSON; x12translator.LoadSchema("C:\\schemas\\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: 

...
    <FunctionalGroup>
        <Meta>
            <GS01 desc="Functional Identifier Code">IN</GS01>
            <GS02 desc="Application Sender's Code">ACME</GS02>
            <GS03 desc="Application Receiver'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>
...

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 x12translator.AddRenamingRule("GS01:FunctionalIdentifierCode");

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

    <FunctionalGroup>
        <Meta>
            <FunctionalIdentifierCode desc="Functional Identifier Code">IN</FunctionalIdentifierCode>
            <GS02 desc="Application Sender's Code">ACME</GS02>
            <GS03 desc="Application Receiver'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>

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

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

Using Schema Names

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 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:

... <_373 desc="Date">20150708 <_76 desc="Invoice Number">3003014445 <_373 desc="Date" xsi:nil="true"/> <_324 desc="Purchase Order Number">0476553272 <_328 desc="Release Number" xsi:nil="true"/> <_327 desc="Change Order Sequence Number" xsi:nil="true"/> <_640 desc="Transaction Type Code">DR ...

Here is the same portion when translated with UseSchemaName set to False (default):

... 20150708 3003014445 0476553272 DR ...

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 X12Translator 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 X12 to JSON

The X12Translator component simplifies the conversion of X12 documents to XML or JSON 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 options and 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 JSON x12translator.SchemaFormat = X12translatorSchemaFormats.schemaJSON; x12translator.InputFormat = X12translatorInputFormats.xifX12; x12translator.OutputFormat = X12translatorOutputFormats.xofJSON; x12translator.LoadSchema("C:\\schemas\\00401_810.json"); x12translator.InputFile = myEDIFile; x12translator.Translate(); string translatedJSON = x12translator.OutputData; x12translator.Reset(); //JSON to EDI x12translator.InputFormat = X12translatorInputFormats.xifJSON; x12translator.OutputFormat = X12translatorOutputFormats.xofX12; x12translator.InputData = translatedJSON; x12translator.Translate(); string translatedEDI = x12translator.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 JSON.

The component supports the following schema formats:

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

x12translator.SchemaFormat = X12translatorSchemaFormats.schemaJSON; x12translator.LoadSchema("C:\\schemas\\00401_810.json");

Renaming Elements

The EDI Translator component optionally supports renaming EDI elements when translating to JSON. By default the name 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 JSON without renaming: 

...
	"functionalgroups": [{
		"meta": {
			"type": "FunctionalGroup",
			"GS01": {
				"desc": "Functional Identifier Code",
				"value": "IN"
			},
			"GS02": {
				"desc": "Application Sender's Code",
				"value": "ACME"
			},
			"GS03": {
				"desc": "Application Receiver's Code",
				"value": "WAYNE_TECH"
			},
...

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

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

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

...
	"functionalgroups": [{
		"meta": {
			"type": "FunctionalGroup",
			"FunctionalIdentifierCode": {
				"desc": "Functional Identifier Code",
				"value": "IN"
			},
			"GS02": {
				"desc": "Application Sender's Code",
				"value": "ACME"
			},
			"GS03": {
				"desc": "Application Receiver's Code",
				"value": "WAYNE_TECH"
			},
...

As seen above the JSON now contains friendly element names as defined by the renaming rule.

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

Translating to JSON

In order to translate from X12 to JSON, the InputFormat must be set to inform the X12Translator 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, JSON 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.

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 X12translatorInputFormats.ifXML. This value tells the component to translate from XML. Similarly, the OutputFormat must be set to X12translatorOutputFormats.ofX12 to instruct the component to format the output as X12 data.

//XML -> X12 x12translator.Reset(); x12translator.InputFormat = X12translatorInputFormats.xifXML; x12translator.OutputFormat = X12translatorOutputFormats.xofX12; x12translator.InputData = translatedXML; x12translator.Translate(); string translatedX12 = x12translator.OutputData;

Converting JSON to X12

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

The InputFormat property must be set to X12translatorInputFormats.ifJSON. This value tells the component to translate from JSON. Similarly, the OutputFormat must be set to X12translatorOutputFormats.ofX12 to instruct the component to format the output as X12 data.

//JSON -> X12 x12translator.Reset(); x12translator.InputFormat = X12translatorInputFormats.xifJSON; x12translator.OutputFormat = X12translatorOutputFormats.xofX12; x12translator.InputData = translatedJSON; x12translator.Translate(); string translatedX12 = x12translator.OutputData;

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

Copyright © 2024 /n software, Inc.
Contact
Terms of Use
Privacy Statement