Getting Started with EDIFACT Translation

Requirements:
IPWorks EDI

Introduction

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

Contents

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

Converting EDIFACT to XML

The EDIFACTTranslator component is designed to convert EDIFACT 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 EDIFACTTranslator component provides, so please consult the help document for additional options and details.

Quick Example

The following sections discuss the details of how EDIFACT documents can be translated to XML. The following sample code will be used as a basis for discussing these options.

Edifacttranslator editranslator = new Edifacttranslator(); editranslator.SchemaFormat = EdifacttranslatorSchemaFormats.schemaJSON; editranslator.InputFormat = EdifacttranslatorInputFormats.eifEDIFACT; editranslator.OutputFormat = EdifacttranslatorOutputFormats.eofXML; editranslator.LoadSchema("C:\\schemas\\D09B_ORDERS.json"); editranslator.InputFile = myEDIFile; //EDI -> XML editranslator.Translate(); string translatedXML = editranslator.OutputData; //XML -> EDI editranslator.Reset(); editranslator.InputFormat = EdifacttranslatorInputFormats.eifXML; editranslator.OutputFormat = EdifacttranslatorOutputFormats.eofEDIFACT; editranslator.InputData = translatedXML; editranslator.Translate(); string translatedEDI = editranslator.OutputData;

Loading an EDI Schema

To begin, it is recommended to provide an EDI schema that describes the EDIFACT document being translated. This is not required, but it does allow 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 D09B ORDERS message with a Altova schema. To load the schema call the LoadSchema method. For instance:

editranslator.SchemaFormat = EdifacttranslatorSchemaFormats.schemaJSON; editranslator.LoadSchema("C:\\schemas\\D09B_ORDERS.json");

Renaming Rules

The EDIFACTTranslator 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 EDIFACT document and schema. For instance:

EDIFACT data

UNA:+.? ' UNB+UNOA:2+MGATE1:65+TESTER:65+020508:1413+0709210008' UNH+1+ORDERS:D:09B:UN:1.1' BGM+E40+MKIDI5422' DTM+137:199904081315:203' DTM+203:20110408:102' DTM+Z02:20110408:203' DTM+273:201011:610' ...

Translated to XML without renaming: 

...
    <TransactionSet>
        <TX-D09B-ORDERS type="TransactionSet">
            <Meta>
                <UNH1 desc="MESSAGE REFERENCE NUMBER">1</UNH1>
                <UNH2 type="Composite" desc="MESSAGE IDENTIFIER">
                    <UNH2.1 desc="Message type">ORDERS</UNH2.1>
                    <UNH2.2 desc="Message version number">D</UNH2.2>
                    <UNH2.3 desc="Message release number">09B</UNH2.3>
                    <UNH2.4 desc="Controlling agency, coded">UN</UNH2.4>
                    <UNH2.5 desc="Association assigned code">1.1</UNH2.5>
                </UNH2>
            </Meta>
            <BGM type="Segment">
                <BGM01 type="Composite" desc="DOCUMENT/MESSAGE NAME">
                    <BGM0101 desc="Document name code">E40</BGM0101>
                </BGM01>
                <BGM02 type="Composite" desc="DOCUMENT/MESSAGE IDENTIFICATION">
                    <BGM0201 desc="Document identifier">MKIDI5422</BGM0201>
                </BGM02>
            </BGM>
...

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

//Define renaming rules editranslator.AddRenamingRule("UNH2:MsgId"); editranslator.AddRenamingRule("BGM01:DocName");

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

...
    <TransactionSet>
        <TX-D09B-ORDERS type="TransactionSet">
            <Meta>
                <UNH1 desc="MESSAGE REFERENCE NUMBER">1</UNH1>
                <MsgId type="Composite" desc="MESSAGE IDENTIFIER">
                    <UNH2.1 desc="Message type">ORDERS</UNH2.1>
                    <UNH2.2 desc="Message version number">D</UNH2.2>
                    <UNH2.3 desc="Message release number">09B</UNH2.3>
                    <UNH2.4 desc="Controlling agency, coded">UN</UNH2.4>
                    <UNH2.5 desc="Association assigned code">1.1</UNH2.5>
                </MsgId>
            </Meta>
            <BGM type="Segment">
                <DocName type="Composite" desc="DOCUMENT/MESSAGE NAME">
                    <BGM0101 desc="Document name code">E40</BGM0101>
                </DocName>
                <BGM02 type="Composite" desc="DOCUMENT/MESSAGE IDENTIFICATION">
                    <BGM0201 desc="Document identifier">MKIDI5422</BGM0201>
                </BGM02>
            </BGM>
...

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

No Renaming:
<UNH2 type="Composite" desc="MESSAGE IDENTIFIER">

Renaming rule "UNH2:MsgId":
<MsgId type="Composite" desc="MESSAGE IDENTIFIER">

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

Translating to XML

In order to translate from EDIFACT to XML, the InputFormat must be set to inform the EDIFACTTranslator component of the type of data being provided. In this case, this property should be set to EdifacttranslatorInputFormats.ifEDIFACT. You must also instruct the component on the output format, which in this case will be EdifacttranslatorOutputFormats.ofXML. 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 EDIFACT data to XML you may optionally call ExportXMLSchema. This method outputs a XML schema (.xsd) which can be helpful when constructing XML messages outside of the component which can later be translated back to EDIFACT.

Converting EDIFACT to JSON

The EDIFACTTranslator component is designed to convert EDIFACT 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 EDIFACTTranslator component provides, so please consult the help document for additional options and details.

Quick Example

The following sections discuss the details of how EDIFACT documents can be translated to JSON. The following sample code will be used as a basis for discussing these options.

Edifacttranslator editranslator = new Edifacttranslator(); editranslator.SchemaFormat = EdifacttranslatorSchemaFormats.schemaJSON; editranslator.LoadSchema("C:\\schemas\\D09B_ORDERS.json"); editranslator.InputFormat = EdifacttranslatorInputFormats.eifEDIFACT; editranslator.OutputFormat = EdifacttranslatorOutputFormats.eofJSON; editranslator.InputFile = myEDIFile; //EDI -> JSON editranslator.Translate(); string translatedJSON = editranslator.OutputData; //JSON -> EDI editranslator.Reset(); editranslator.InputFormat = EdifacttranslatorInputFormats.eifJSON; editranslator.OutputFormat = EdifacttranslatorOutputFormats.eofEDIFACT; editranslator.InputData = translatedJSON; editranslator.Translate();

Loading an EDI Schema

To begin, it is recommended to provide an EDI schema that describes the EDIFACT document being translated. This is not required, but it does allow 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 D09B ORDERS message with a Altova schema. To load the schema call the LoadSchema method. For instance:

editranslator.SchemaFormat = EdifacttranslatorSchemaFormats.schemaJSON; editranslator.LoadSchema("C:\\schemas\\D09B_ORDERS.json");

Renaming Rules

The EDIFACTTranslator component optionally supports renaming EDI elements when translating to JSON. By default the name will be automatically determined by the component from the EDIFACT document and schema. For instance:

EDIFACT data

UNA:+.? ' UNB+UNOA:2+MGATE1:65+TESTER:65+020508:1413+0709210008' UNH+1+ORDERS:D:09B:UN:1.1' BGM+E40+MKIDI5422' DTM+137:199904081315:203' DTM+203:20110408:102' DTM+Z02:20110408:203' DTM+273:201011:610' ...

Translated to JSON without renaming: 

	"transactionsets": [{
		"meta": {
			"type": "TransactionSet",
			"UNH1": {
				"desc": "MESSAGE REFERENCE NUMBER",
				"value": "1"
			},
			"UNH2": {
				"type": "Composite",
				"desc": "MESSAGE IDENTIFIER",
				"UNH2.1": {
					"desc": "Message type",
					"value": "ORDERS"
				},
				"UNH2.2": {
					"desc": "Message version number",
					"value": "D"
				},
				"UNH2.3": {
					"desc": "Message release number",
					"value": "09B"
				},
				"UNH2.4": {
					"desc": "Controlling agency, coded",
					"value": "UN"
				},
				"UNH2.5": {
					"desc": "Association assigned code",
					"value": "1.1"
				}
			}
		},
		"segments": [{
			"type": "Segment",
			"name": "BGM",
			"BGM01": {
				"type": "Composite",
				"desc": "DOCUMENT\/MESSAGE NAME",
				"BGM0101": {
					"desc": "Document name code",
					"value": "E40"
				}
			},
...

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:JSONName. For instance

//Define renaming rules editranslator.AddRenamingRule("UNH2:MsgId"); editranslator.AddRenamingRule("BGM01:DocName");

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

	"transactionsets": [{
		"meta": {
			"type": "TransactionSet",
			"UNH1": {
				"desc": "MESSAGE REFERENCE NUMBER",
				"value": "1"
			},
			"MsgId": {
				"type": "Composite",
				"desc": "MESSAGE IDENTIFIER",
				"UNH2.1": {
					"desc": "Message type",
					"value": "ORDERS"
				},
				"UNH2.2": {
					"desc": "Message version number",
					"value": "D"
				},
				"UNH2.3": {
					"desc": "Message release number",
					"value": "09B"
				},
				"UNH2.4": {
					"desc": "Controlling agency, coded",
					"value": "UN"
				},
				"UNH2.5": {
					"desc": "Association assigned code",
					"value": "1.1"
				}
			}
		},
		"segments": [{
			"type": "Segment",
			"name": "BGM",
			"DocName": {
				"type": "Composite",
				"desc": "DOCUMENT\/MESSAGE NAME",
				"BGM0101": {
					"desc": "Document name code",
					"value": "E40"
				}
			},

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 EDIFACT to JSON, the InputFormat must be set to inform the EDIFACTTranslator component of the type of data being provided. In this case, this property should be set to EdifacttranslatorInputFormats.ifEDIFACT. You must also instruct the component on the output format, which in this case will be EdifacttranslatorOutputFormats.ofJSON. 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 EDIFACT

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

The InputFormat property must be set to EdifacttranslatorInputFormats.ifXML. This value tells the component to translate from XML. Similarly, the OutputFormat must be set to EdifacttranslatorOutputFormats.ofEDIFACT to instruct the component to format the output as EDIFACT data.

//XML -> EDIFACT editranslator.Reset(); editranslator.InputFormat = EdifacttranslatorInputFormats.eifXML; editranslator.OutputFormat = EdifacttranslatorOutputFormats.eofEDIFACT; editranslator.InputData = translatedXML; editranslator.Translate(); string translatedEDIFACT = editranslator.OutputData;

Converting JSON to EDIFACT

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

The InputFormat property must be set to EdifacttranslatorInputFormats.ifJSON. This value tells the component to translate from JSON. Similarly, the OutputFormat must be set to EdifacttranslatorOutputFormats.ofEDIFACT to instruct the component to format the output as EDIFACT data.

//JSON -> EDIFACT editranslator.Reset(); editranslator.InputFormat = EdifacttranslatorInputFormats.eifJSON; editranslator.OutputFormat = EdifacttranslatorOutputFormats.eofEDIFACT; editranslator.InputData = translatedJSON; editranslator.Translate(); string translatedEDIFACT = editranslator.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