Home:Developers:Tutorials & Examples:Translate X12 to XML

Translating X12 documents to XML

XML Converters are able to handle X12 and many other EDI dialects easily, managing and converting X12 transaction sets, segments, elements, and code lists to XML. XML Converters use their embedded X12 dictionary for helping you create syntactically pure and semantically accurate X12, converting to/from XML or diagnosing problems with incoming and outgoing X12 data.

This page will cover these areas involved with the X12 subset of XML Converters:

1. X12 to XML without coding
2. X12 to XML (and vice-versa) from your Java or .NET application
3. Using Stylus Studio to test your X12 conversions

Note that the XML Converters use the same URL notation for all EDI standards, X12, EDIFACT, IATA, and so on; XML Converters figure out from the document itself which EDI dialect is being used. That implies that the following examples apply with little changes to all the EDI flavors supported by XML Converters.

X12 to XML without coding

XML Converters can be used through their Java or .NET APIs (described here), or without the need of any coding, using their URI Resolver. The URI Resolver provides on-the-fly, streaming conversions of documents from one format to another. The URI Resolver plugs easily into any XML processing engine (XQuery engines, XSLT engines, …), and makes the result of a conversion accessible to the XML processing engine the same way a normal URL can be accessed. For example, you can use fn:doc() in XQuery to automatically trigger an X12 to XML conversion; or you can use document() in XSLT to do the same.

The URL format that triggers the use of the XML Converters URI Resolver to convert X12 to XML, is:

converter:EDI<options>?<URL-for-X12-source>

The "converter:EDI" portion of the URL is the one that activates the XML Converters URI Resolver; when the XML Converters URI Resolver is properly registered with the processing engine you are using (how to register a URI Resolver varies from one processing engine to another), URLs that use the "converter:" scheme are redirected to XML Converters for resolution. The "EDI" part tells XML Converters that it's dealing with an EDI-based conversion, which is what an X12 conversion is. Different values include CSV (Comma Separated Value files), TAB (Tab Separated Value files), SYLK (Symbolic Link Format), and more; the full list is available here.

The <options> section is optional, and it can contain any number of settings supported by the conversion flavor in use; the set of options supported by the EDI format is described here. For example "long=yes" will instruct XML Converters to generate longer, more descriptive element names for the XML generated starting from an X12 message.

A simple XQuery using the XML Converters URI Resolver may look like:

<orders> {
    for $order in doc('converter:EDI:long=yes?file:///c:/order.x12')//GROUP_28
    return $order
} </orders>

A similar XSLT using the XML Converters URI Resolver, will look like:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
     <orders>
         <xsl:for-each select="document('converter:EDI:long=yes?file:///c:/ order.edi')//GROUP_28">
             <xsl:copy-of select="."/>
         </xsl:for-each>
     </orders>
</xsl:template>
</xsl:stylesheet>

Without any additional coding, your XML processing engine is able to access the result of a complex X12 to XML conversion just using a URL format supported by XML Converters!

X12 to XML from your Java or .NET application

There are cases in which you want to access X12 to XML (or XML to X12) conversions from your Java or .NET application rather than from an XML processing engine. XML Converters expose easy to use Java and .NET APIs that make integration with your application a snap!

For example, suppose you want to convert an X12 message to XML in your Java application. The following simple lines will achieve the goal:

ConverterFactory factory = new ConverterFactory();
Source converterSource = new StreamSource ("c:/order.x12");
Result converterResult = new StreamResult ("c:/order.xml");
Converter toXml = factory. newConvertToXML ("converter:EDI");
toXml. convert (converterSource, converterResult);

The X12 message order.x12 is converted into the order.xml XML file. Of course instead of saving the result of the operation on the file system, your application can consume the result as SAX or StAX events, or materialize it in memory as XML DOM. Similarly, the input X12 message can be a stream that doesn’t correspond to a resource on the file system, but maybe it’s available in memory, or incoming on your Enterprise Service Bus.

The corresponding C# example is, not by chance, very similar:

ConverterFactory factory = new ConverterFactory();
Source converterSource = new UriSource("c:\\order.x12");
Result converterResult = new UriResult("c:\\order.xml");
Converter toXml = factory.CreateConvertToXml("converter:EDI");
toXml.Convert(converterSource, converterResult);

Of course, also in the .NET case the conversion is not limited to the use of files; full support for XmlWriter and XmlReader is available in XML Converters for .NET. And how complicated is it to convert an XML document into its corresponding X12 format?

Java:

ConverterFactory factory = new ConverterFactory();
Source converterSource = new StreamSource("order.xml");
Result converterResult = new StreamResult ("order.x12.fromxml");
Converter fromXml = factory. newConvertFromXML ("converter:EDI");
fromXml. convert (converterSource, converterResult);

C#:

ConverterFactory factory = new ConverterFactory();
Source converterSource = new UriSource("c:\\order.xml");
Result converterResult = new UriResult("c:\\order.x12.fromxml");
Converter fromXml = factory.CreateConvertFromXml("converter:EDI");
fromXml.Convert(converterSource, converterResult);

All the options described here can be specified when creating the Converter object; so, for example you can change the examples above to use the longer, more descriptive XML element names:

Converter fromXml = factory. newConvertFromXML ("converter:EDI:long=yes");

A complete description of the Java API is available here; the .NET API is discussed in detail here.

Using Stylus Studio to test X12 conversions

XML Converters are fully integrated in Stylus Studio; testing an X12 to XML conversion in Stylus Studio is as simple as opening a file.

First, use the same File|Open dialog you are used to in other applications to choose the file, except right before hitting Open, put a check in the special box labeled "Open using XML Converter."

Next, select the correct converter, which in this case is the "Electronic Data Interchange (EDI)" converter (which includes X12, EDIFACT, IATA and others).

On the right side, there are several options that vary by converter. Changing them changes the URL prefix shown at the bottom of the dialog; you can always use the URL displayed by Stylus Studio to reference the conversion through the XML Converters API or the URI resolver as discussed in the previous examples. Properly formed X12 files will open without any change to the default options, but occasionally you might need to instruct XML Converters to relax some validation, or to format the XML output slightly differently.

So, after choosing the filename, checking one checkbox, pressing one button (Open), selecting the converter and pressing another button (OK), we've got a converted file in our XML editor. It’s that easy!

You can use the same process to select the converted X12 file as an input for your XQuery or XSLT that you are developing inside Stylus Studio.