X12 to XML: Functionality and Operation

Requirements

This utility converts an X12 interchange containing one or more functional groups, each containing one or more transaction sets, into XML instance documents. An instance document is created for each transaction set. Here's a summary of the required functionality.

• Inputs : A valid X12 interchange. The second input is a directory path where file description documents (as discussed in Chapter 6) relevant to the interchange may be found.

• Processing : An appropriate file description document is loaded for each transaction set in the interchange. An Element is created in the output document for each data element, each composite data structure, each segment, and each segment group. The organization of a transaction set is derived from a file description document. Data element content is converted from X12 data types to schema language data types as specified in the file description document. Empty or missing data elements do not create Elements in the output document. For each functional group processed , an XML representation of a 997 Functional Acknowledgment is created.

• Output : One or more XML instance documents, each in a single file. The root Element name is derived from the grammar in the file description document. The file name is formed by appending the transaction set control number to the root Element name and adding the extension .xml. The documents for each functional group are placed in a separate subdirectory. The subdirectories are named according to the sender IDs and group types in the GS segment. The 997 Functional Acknowledgments are created in the passed output directory and named as discussed below.

You may recall my earlier comment that I would focus primarily on the basic functionality required in most trading situations. Although Functional Acknowledgments are capable of reporting syntax errors, they are most often used only as return receipts and are required in most trading situations. Functional Acknowledgments are clearly beyond the scope of file format conversion, but for this utility to meet the minimum requirements for most trading situations we must be able to generate them. Note, however, that we will generate them only to indicate acceptance (that is, receipt) of a group and not to report errors.

Running the Utility

This section provides instructions for running the X12 to XML utility from the command line.

For Java:

java X12ToXML InputFile.dat OutputDirectory

FileDescriptionDirectory

or

java X12ToXML -h

For C++ on Win32:

X12ToXML InputFile.dat OutputDirectory FileDescriptionDirectory

or

X12ToXML -h

Options follow the parameters except for the help option, which may be specified by itself.

Parameters:

• First : File specification of the input interchange file (required). The specification may include the full or relative path name. If no path name is specified, the file is assumed to reside in the current working directory. The full file name must be specified, but there is no restriction on the extension name.

• Second : Path specification of the output directory (required). The directory must exist. Either a relative or an absolute path name may be specified. The trailing directory separator character is optional. A subdirectory for each functional group is created beneath this directory. The subdirectories are named by concatenating the Functional Group Identifier Code in GS01 to the Application Sender's Code in GS02. Output files within these directories are named by appending the Transaction Set Control Number in ST02 to the Root name as specified in the file description document's Grammar Element.

• Third : Directory path for the file description documents (required). The trailing directory separator character is optional. During processing the utility uses identifying information in the control segments to determine the file description document required to convert the transaction set currently being processed (see the discussion on naming requirements below). These file description documents must reside in this directory path.

Options:

• -v (Validate) : Validate the created XML documents before writing them to disk. The documents are validated against the schema specified in the file description document.

• -h (Help) : Display a help message and exit without further processing.

Naming requirement for file description documents:

File description documents used with this utility must conform to a specific naming convention for their local file names. Their names must be formed by concatenating the following values:

• GS Application Sender's Code in GS02, followed by a hyphen

• GS Functional Identifier Code in GS01, followed by a hyphen

• ST Transaction Set Identifier Code in ST01, followed by a hyphen

• GS Version/Release in GS08

• A file type extension of .xml

( Note : Some values of GS Version/Release, such as those sometimes used for TDCC or UCS versions, may not yield valid file names for the operating system.)

As an example of the naming convention, suppose we receive an interchange from Big Box Discount Stores that contains 850 Purchase Orders in version 004010 of X12. Suppose they use BIGBOX for the sender ID in the GS segment. The X12ToXML utility will look in the passed directory for a file description document named:

 BIGBOX-PO-850-004010.xml 

A version 1.0 Babel Blaster requirement is to remove this naming restriction, but it's not a bad convention to follow anyway.

Naming convention for Functional Acknowledgments:

An XML representation of an X12 997 Functional Acknowledgment is created for each functional group the utility processes. The files for these XML documents are placed in an FA_Out subdirectory of the passed directory. Individual acknowledgments are named by concatenating the following values:

• GS Application Sender's Code in GS02, followed by a hyphen

• GS Functional Identifier Code in GS01

• A file type extension of .xml

For example, the Functional Acknowledgment for Big Box Discount Stores purchase orders on a UNIX system would be named:

 FA_Out/BIGBOXBUYER-PO.xml 

Restrictions:

Unless otherwise noted, all numeric limits may be modified by changing parameters in the program source and appropriate type definitions in the file description document schemas.

• An X12 data element may contain a maximum of 1,023 bytes.

• A segment may be no longer than 16,383 bytes.

• A maximum of 100 X12 data elements per segment is supported. This includes repeated elements and component data elements within composite data structures.

• There is no absolute limit on the number of segments; the number is only practically limited by system memory.

• Each X12 data element must be assigned a unique Element name.

• XML Element names are limited to 127 characters .

• Data element grammar Elements must be specified in their segment description Element in ascending order by their position within the segment or composite data structure.

• Path lengths for complete file specifications are limited to 127 characters.

• Schema location URIs are limited to 127 characters.

• A maximum of 999 output XML documents from each functional group is supported.

• The TA1 Interchange Acknowledgment control segment is not currently supported and will cause a parsing error if encountered . (It is very seldom used. Supporting it is among the Babel Blaster version 1.0 requirements.)

• GS sender IDs must be valid directory names for the operating system where the utility is run.

• In the current implementation there can be only one instance in an interchange of a functional group type per GS sender ID. This is due to the naming convention used for output directories.

• Functional Acknowledgments are created only to indicate acceptance of a functional group. Neither transaction set acceptance nor error reporting are supported.

Sample Input and Output: 850 Purchase Order

Big Daddy's Gourmet Cocoa has hit the big time! The company is now selling to major retail grocery and discount chains, and they all want to send their orders as X12 850 Purchase Orders. Of course, they all have slightly different implementation guides, but Table 9.1 shows an abbreviated summary of a fairly representative guide. Note : The Segment Group column is empty if the segment is not part of a segment group. The BEG and a few other header level segments fall into this category.

You'll note a few things about this sample implementation. Only the N1 segment is transmitted; there isn't a full N1 loop. It is becoming increasingly common to use identifiers such as DUNS or DUNS+4 numbers to reference a location or party already in the system rather than transmitting full address information. The PO1 segment has only a single product code, though sometimes more than one is sent (I assume as a convenience and crosscheck for the vendor). Overall, this is a fairly compact implementation of the 850 Purchase Order.

The sample interchange below shows one functional group with two transaction sets.

Sample Input Interchange (PurchaseOrders.X12)

 ISA*00*    *00*     *ZZ*BIGBOX     *12*   9727839573   *030123*0600*U*00401*000000357*0*P*>~ GS*PO*BIGBOX*9727839573*20030123*0600*114*X*004010~ ST*850*0001~ BEG*00*SA*4497-0561**20030123~ DTM*001*20030206~ N1*ST*BIG BOX - STORE #97*92*001234567S097~ PO1*1*10*CA*30.36**UP*35790000122~ PID*F****Instant Hot Cocoa Mix - Mint flavor~ PO1*2*30*CA*31.08**UP*35790000724~ PID*F****Instant Hot Cocoa Mix - Vanilla flavor~ CTT*2~ SE*10*0001~ ST*850*0002~ BEG*00*SA*4445-0323**20030123~ DTM*001*20030206~ N1*ST*BIG BOX - STORE #45*92*001234567S045~ PO1*1*20*CA*30.36**UP*35790000122~ PID*F****Instant Hot Cocoa Mix - Mint flavor~ PO1*2*40*CA*31.08**UP*35790000641~ PID*F****Instant Hot Cocoa Mix - Dutch Chocolate flavor~ CTT*2~ SE*10*0002~ GE*2*114~ IEA*1*000000357~ 

Table 9.1. Sample X12 850 Purchase Order Implementation Guide

Segment Group	Segment	Tag	Data Element Position	Data Element or Composite Data Structure Number andName	X12 Data Type	Minimum Length	Maximum Maximum Length	Description and Comments
	Beginning Segment for Purchase Order	BEG	01	353 Transaction Set Purpose Code	ID	2	2	00 for original purchase order
			02	92 Purchase Order Type Code	ID	2	2	SA for stand-alone order
			03	324 Purchase order number	AN	1	22	Buyer-assigned purchase Order Number
			05	373 Date	DT	8	8	Purchase order date
	Date/Time Reference	DTM	01	374 Date/Time Qualifier	ID	3	3	002 for requested delivery date or 010 for requested ship date
			02	373 Date	DT	8	8
Header N1	Name	N1	01	98 Entity Identifier Code	ID	2	3	One N1 loop is sent with an ST in this element
			02	93 Name	AN	1	60	The name of the receiving location
			03	66 Identification Code Qualifier	ID	1	2	92 for Assigned by Buyer or Buyer's Agent
			04	67 Identification Code	AN	2	80	The buyer-assigned DUNS+4 number (the buyer's DUNS number followed by a four-digit receiving location code)
PO1	Baseline Item Data	PO1	01	350 Assigned Identification	AN	1	20	The line item number
			02	330 Quantity Ordered	R	1	15
			03	355 Unit or Basis for Measurement Code	ID	2	2	Usually EA for each or CA for case
			04	212 Unit Price	R	1	17
			06	235 Product/ Service ID Qualifier	ID	2	2	Usually UP for UPC Consumer Package Code (1-5-5-1)
			07	234 Product/ Service ID	AN	1	48	The UPC code for the item
PO1	Product/ Item Description	PID	01	349 Item Description Type	ID	1	1	F for free-form item description
			05	352 Description	AN	1	80	The item description
	Transaction Totals	CTT	01	354 Number of Line Items	N0	1	6	The total number of line items in the transaction set

The line breaks (and indentation on the continuation of the ISA segment) exist here only for readability. They would not appear in a compliant data stream.

Listed below are the two XML documents produced by the utility from this interchange. This and the XMLToX12 utility allow the user to specify the choice of names for the Elements that represent the various X12 components . I use a convention based on segment IDs and data element position. You could use more descriptive English names if you prefer.

Sample Output (X12PurchaseOrder0001.xml)

 <?xml version="1.0" encoding="UTF-8"?> <X12PurchaseOrder     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:noNamespaceSchemaLocation="X12PurchaseOrder.xsd">   <BEG>     <BEG01>00</BEG01>     <BEG02>SA</BEG02>     <BEG03>4497-0561</BEG03>     <BEG05>2003-01-23</BEG05>   </BEG>   <DTM>     <DTM01>001</DTM01>     <DTM02>2003-02-06</DTM02>   </DTM>   <N1Header>     <N1>       <N101>ST</N101>       <N102>BIG BOX - STORE #97</N102>       <N103>92</N103>       <N104>001234567S097</N104>     </N1>   </N1Header>   <PO1Group>     <PO1>       <PO101>1</PO101>       <PO102>10</PO102>       <PO103>CA</PO103>       <PO104>30.36</PO104>       <PO106>UP</PO106>       <PO107>35790000122</PO107>     </PO1>     <PID>       <PID01>F</PID01>       <PID05>Instant Hot Cocoa Mix - Mint flavor</PID05>     </PID>   </PO1Group>   <PO1Group>     <PO1>       <PO101>2</PO101>       <PO102>30</PO102>       <PO103>CA</PO103>       <PO104>31.08</PO104>       <PO106>UP</PO106>       <PO107>35790000724</PO107>     </PO1>     <PID>       <PID01>F</PID01>       <PID05>Instant Hot Cocoa Mix - Vanilla flavor</PID05>     </PID>   </PO1Group>   <CTT>     <CTT01>2</CTT01>   </CTT> </X12PurchaseOrder> 

Sample Output (X12PurchaseOrder0002.xml)

 <?xml version="1.0" encoding="UTF-8"?> <X12PurchaseOrder     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:noNamespaceSchemaLocation="X12PurchaseOrder.xsd">   <BEG>     <BEG01>00</BEG01>     <BEG02>SA</BEG02>     <BEG03>4445-0323</BEG03>     <BEG05>2003-01-23</BEG05>   </BEG>   <DTM>     <DTM01>001</DTM01>     <DTM02>2003-02-06</DTM02>   </DTM>   <N1Header>     <N1>       <N101>ST</N101>       <N102>BIG BOX - STORE #45</N102>       <N103>92</N103>       <N104>001234567S045</N104>     </N1>   </N1Header>   <PO1Group>     <PO1>       <PO101>1</PO101>       <PO102>20</PO102>       <PO103>CA</PO103>       <PO104>30.36</PO104>       <PO106>UP</PO106>       <PO107>35790000122</PO107>     </PO1>     <PID>       <PID01>F</PID01>       <PID05>Instant Hot Cocoa Mix - Mint flavor</PID05>     </PID>   </PO1Group>   <PO1Group>     <PO1>       <PO101>2</PO101>       <PO102>40</PO102>       <PO103>CA</PO103>       <PO104>31.08</PO104>       <PO106>UP</PO106>       <PO107>35790000641</PO107>     </PO1>     <PID>       <PID01>F</PID01>       <PID05>         Instant Hot Cocoa Mix - Dutch Chocolate flavor       </PID05>     </PID>   </PO1Group>   <CTT>     <CTT01>2</CTT01>   </CTT> </X12PurchaseOrder>