Home:Developers:Tutorials & Examples:Converting EDI to XML

Converting Custom EDI Message Types to XML with DataDirect XML Converters™

You can use DataDirect XML Converters™ to define extensions to standard EDI message types. This allows the DataDirect XML Converter for EDI to convert proprietary EDI message types that are based on an extension (or restriction) to a standard EDI message type. You can create custom EDI message types for:

• EDIFACT-style messages (EDIFACT-style includes IATA and EANCOM)
• X12-style messages

Custom message types must be either EDIFACT- or X12-style messages, since the auto-detection feature of the DataDirect XML Converters™ engine depends on the initial segments of those dialects as well as on the general syntax of the document. You cannot, for example, create an HL7 EDI message, since HL7 is structurally different (it allows messages to span documents, it allows segments to be split and continued, it has a sub-field structure, and so on).

Process Overview

The process for converting an EDI file that includes a custom EDI message type to XML has the following steps:

1. Create an XML document (myCustomEDI.extension, for example) that describes how the custom EDI message type differs from the EDI standard on which it is based — its extensions or restrictions, in other words. The purpose of this document is to teach the DataDirect XML Converter engine the differences between your custom EDI message type and the EDI standard message type on which it is based.

In order to do this, you need to structure the document using one of two XML Schemas provided by DataDirect Technologies — CustomEDI-extend.xsd or CustomEDI-complete.xsd. These XML Schemas are described in the following section, XML Schemas for Custom EDI Message Types.

2. Validate myCustomEDI.extension against the appropriate XML Schema.


3. Invoke the XML Converter for EDI in your application. In addition to the EDI file you wish to convert to XML, specify the XML document that contains the description of the EDI extension/restriction you created in Step 1.

For example, to convert myCustomEDI.edi to XML, you might invoke the XML Converter for EDI in a Java application as follows:

1 import javax.xml.transform.stream.*;  2 import com.ddtek.xmlconverter.*;  3 public class ConverterOne {  4     public static void main(String[] args) throws Throwable {  5         ConverterFactory factory = new ConverterFactory();  6         ConvertToXML toXML = factory.newConvertToXML("converter:EDI:user=myCustomEDI.extension");  7         toXML.convert(new StreamSource("myCustomEDI.edi"), new StreamResult("myCustomEDI.edi.xml");  8     }  9 }

Example

See Example: Converting a Custom EDI Message Type with DataDirect XML Converters™ to see how to convert a custom EDI file to XML.

XML Schemas for Custom EDI Message Types

Stylus Studio includes two XML Schemas used to validate the XML document you use to define your custom EDI message type:

• CustomEDI-extend.xsd — Use CustomEDI-extend.xsd when you are modifying an existing EDI message type and you need to define only a few differences between your custom message type and the EDI standard. DataDirect XML Converters™ uses the EDI standard for anything you do not define explicitly in your XML document — a certain segment or composite element, for example.
• CustomEDI-complete.xsd — Use CustomEDI-complete.xsd when you are creating a custom EDI message type from scratch, that is, reusing no components from an existing EDI standard. This XML Schema is for a completely described message type, which can include one or more messages, one or more segments, zero or more composites, and one or more elements. It assumes that all pieces needed are described within the XML.

The ROOT Element

The root element of the custom EDI message type XML document is <edi>. Within the root element, you can define each of the following components: <message>, <segment>, <composite>, and <element>. When one component references another, it will always be in the form of a <use-...> element. For example, a <message> will have one or more <use-segment> elements within it, which will refer to the <segment>s defined elsewhere in the file.

The Message Element

Each EDI message is composed of one or more <message> elements (or messages). Within each message there are groups of segments, which can be nested, so each group can contain other groups, segments, or a mix. Within each segment there can be a mix of composite fields and elements, and composite fields are also made up of elements.

The <message> element will have a mandatory attribute, @name, which is the name of the EDI message. This must match what is found in the file in a UNH/UIH segment for EDIFACT, or in an ST segment for X12. Something like "ORDERS" or "811", for example.

The <message> element should also have a @title attribute, which sets the human-readable title. It can also have a child <description> element, which can contain an arbitrarily long description.

Next should be one or more <group> or <use-segment> elements. They can be mixed, although order does matter. The <use-segment> elements have three attributes:

• @name, which contains the name of a <segment> elsewhere in the file (or elsewhere in the internal standards if the keyref-less version of the schema is being used to augment an existing EDI definition)
• @mandatory, whose "true" or "false" value indicates whether the segment is mandatory
• @count, which indicates the maximum number of times the segment may appear. Note that the count must be greater than zero, and @mandatory="true" means that at least one must appear — if @count="99" and @mandatory="true" it does not mean that 99 are required, however.

The Group Element

The <group> element can contain one or more <group> and/or <use-segment> elements. The <group> element allows also an optional <description> element for documentation purposes.

Group elements also have two attributes, @count and @mandatory, which behave as described in The Message Element.

The Segment Element

The <segment> element, like messages, has @name and @title attributes. The name should be the name of the segment as it will appear in the EDI document, such as "NAD" or "F6X" or "ID1", for example. It also supports the optional <description> element.

Each <segment> contains one or more elements – either simple elements referred to by the <use-element> construct, or component elements referred to by the <use-composite> construct. The order is very significant. Both <use-element> and <use-composite> take two attributes, @name and @mandatory:

• @name points to an <element> (in the former case) or <composite> (in the latter) within the file (or elsewhere in the internal standards if the keyref-less version of the schema is being used to augment an existing EDI definition)
• @mandatory is whether the element or component must be present. Often in EDI messages, an element or composite can be left out, either by putting two delimiters together with no content or by eliminating unneeded fields from the end of a segment. This attribute indicates whether that practice is allowed for that particular element/composite.

Composite Fields

A <composite> element is like a , except that it cannot contain <use-composite> elements. It can only contain <use-element> elements. It is used to build up more complicated structures of related information. One use is to hook together a date and a time field, or a date and a date-format and a purpose-of-date.

Composite names usually look like C???, E??? or S???, with the ??? being a three-digit number. While this is true for both X12 and EDIFACT, it is neither a rule nor a requirement.

Elements

An <element> describes the most basic component of an EDI message. Element names are typically numbers, although X12 has a number of elements in which the first character is the letter 'I' followed by a two-digit number. The name is in the mandatory @name attribute. The @title attribute is a human-readable description of the element's purpose.

The mandatory @type attribute describes the datatype. EDIFACT and X12 both use:

• 'a' (alphabetical)
• 'an' (alphanumerical)
• 'n' (numerical)

X12 expands on the list of types with these additional types:

• 'id' (identifier - this must be contained within a code list)
• 'b' (binary - raw bits)
• 'dt' (date, in CCYYMMDD format)
• 'n0' (same as 'n')
• 'n1' through 'n9' (these are numeric, but scaled — the digit tells how many places to the left to move the decimal — so that a "123" stored as 'n2' would be exported as 1.23 when going from EDI to XML, and '1.23' in XML would be rendered in the EDI as '123')

The mandatory @maxLength attribute indicates how many characters at most can be in the value. The optional @minLength sets the minimum length. The default for the latter is "0".

Optionally, each element can have its values further constrained by an enumerated list. That list is denoted by a series of <item> elements within the <element>.

Each <item> has a @key attribute which holds the value that would appear in the EDI, and the text content of the <item> element is the description of that value.

For More Information

See Example: Creating a Custom EDI Message Type with DataDirect XML Converters™ to see how easy it is to create a custom EDI message type with DataDirect XML Converters™.

Tired of reading? Watch a video that shows how easy it is to use DataDirect XML Converters™ in a .NET application.