XML to X12: Functionality and Operation

Requirements

The general requirement for this utility is to convert one or more XML instance documents, each representing a single logical document, into an X12 transaction set. The transaction sets are bundled into one functional group and interchange. Here's a summary of the required functionality.

• Inputs : There are two user -specified inputs. The first is a directory containing one or more XML instance documents, each in a single file. All have the same grammar. The second input is a file description document (as discussed in Chapter 6) that describes the XML documents and the X12 interchange to be produced. The utility also uses a document for maintaining EDI control numbers , as described in a later section of this chapter.

• Processing : Each input Element corresponding to a segment (as described in the file description document) is written to a segment in a transaction set. Each of its child Elements corresponding to data elements are written to the appropriate positions in the segment. Schema language data types are converted to X12 data types according to the data element descriptions in the file description document. XML Elements corresponding to segment groups and composite data structures are not directly used. Envelope segments are created based on values from the file description document, and incremented sequence numbers from the control number document.

• Output : A valid X12 interchange.

Again, in keeping with the basic functionality required in most trading situations, we must go a bit beyond simple file format conversion. Many major EDI users audit the control numbers used in interchanges and functional groups and reject interchanges with duplicate control numbers. Some also check with a trading partner if there is a missing number in a sequence of control numbers. So, we're including minimal support for sequence number generation.

Running the Utility

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

For Java:

java -DBBHOME=BBHomeDirectory XMLToX12 InputDirectory

OutputFile.X12 FileDescription.XML

or

java XMLToX12 -h

Note : The -D option for the Java virtual machine defines the BBHOME system property. Replace BBHomeDirectory with the directory path on your system for the Babel Blaster Home directory. The utility uses this path to retrieve the EDIControl.xml file.

For C++ on Win32:

XMLToX12 InputDirectory OutputFile.X12 FileDescription.XML

or

XMLToX12 -h

Note : The BBHOME environment variable must be set to the directory path on your system for the Babel Blaster Home directory. The utility uses this path to retrieve the EDIControl.xml file.

As we did in Chapter 5, we're using a system property in Java and an environment variable in C++. Refer back to that chapter for a more detailed discussion of the rationale and how to set environment variables .

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

Parameters:

• First : Path specification of the input directory (required). Either a relative or an absolute path name may be specified. The trailing directory separator character is optional.

• Second : File specification of the output interchange file (required). The specification may include the full or relative path name. If no path name is specified, the interchange file will be created in the current working directory. An extension may be specified, but if not specified the file will be created without one. If a file with the specified name already exists, it will be overwritten.

• Third : File specification of the file description document (required). 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.

Options:

• -v (Validate) : Validate the XML documents before processing. The documents are validated against the schema referenced in the document root Element.

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

Since a specific file description document file name is passed to the utility, there are no restrictions on how the file is named.

Note : This utility requires that at least the skeleton EDIControl.xml file be present in a directory pointed to by the BBHOME system property in the Java implementation or by the operating system environment variable in the C++ implementation.

Restrictions:

The restrictions are the same as those specified for the X12 to XML utility, plus the following.

• The segment identifier Element need not be present in the input document. It will be converted if present, but the contents will be overwritten by the segment identifier specified in the grammar.

• All the XML documents processed must be converted to the same X12 transaction set type. One functional group with all these transaction sets is produced, and only one functional group is written to each interchange.

Sample Input and Output: 810 Invoice

Big Daddy's big customers who are sending orders by X12 EDI also want the invoices to be sent to them by X12 EDI. Big Daddy doesn't want to pay the $25 to $100 penalty for each invoice those customers have to process manually. So, Big Daddy needs to create X12 810 Invoices from his system. Table 9.2 shows a summary of a typical 810 implementation. Note : The Segment Group column is empty if the segment is not part of a segment group.

Table 9.2. Sample X12 810 Invoice Implementation Guide

Segment Group	Segment	Tag	Data Element Position	Data Element or Composite Data Structure Number and Name	X12 Data Type	Minimum Length	Maximum Length	Description and Comments
	Beginning Segment for Invoice	BIG	01	373 Date	DT	8	8	The invoice date
			02	76 Invoice Number	AN	1	22	Seller-assigned invoice number
			04	324 Purchase Order Number	AN	1	22	Relevant buyer-assigned purchase order number
Header N1	Name	N1	01	98 Entity Identifier Code	ID	2	3	Two N1 loops must be sent: one with the Ship To location contains an ST in this element, the other with the Remit To party contains an RE in this element
			02	93 Name	AN	1	60	For ST, the name of the receiving location; for RE, the vendor name
			03	66 Identification Code Qualifier	ID	1	2	For ST, 92 for Assigned by Buyer or Buyer's Agent; for RE, 9 for DUNS number
			04	67 Identification Code	AN	2	80	For ST, the buyer-assigned DUNS+4 number (the buyer's DUNS number followed by a four-digit receiving location code); for RE, the DUNS number
	Terms of Sale/Deferred Terms of Sale	ITD	01	336 Terms Type Code	ID	2	2	01 for Basic
			03	338 Terms Discount Percent	R	1	6
			04	370 Terms Discount Due Date	DT	8	8	Date payment is due for discount to apply
			05	351 Terms Discount Days Due	N0	1	3	Number of days in the discount period
			06	446 Terms Net Due Date	DT	8	8	Date on which the net amount is due
			07	386 Terms Net Days	N0	1	3	Number of days until the net amount is due
IT1	Baseline Item Data (Invoice)	IT1	01	350 Assigned Identification	AN	1	20	Sometimes optional, but usually must match the line item number on the corresponding purchase order
			02	358 Quantity Invoiced	R	1	10
			03	355 Unit or Basis for Measurement Code	ID	2	2	Must match the unit of measurement of the corresponding purchase order; 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
IT1	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
	Total Monetary Value Summary	TDS	01	610 Amount	N2	1	15	Total amount of invoice before terms discount
	Transaction Totals	CTT	01	354 Number of Line Items	N0	1	6	The total number of line items in the transaction set

As with the sample implementation guide for our 850 Purchase Order, only the N1 segment is transmitted; there isn't a full N1 loop. Like the PO1 segment, the IT1 segment has only a single product code. Though you would think that major buyers could get by with just one product identifier, I have seen some implementation guides that require three. In addition to a standard UPC code they require their own internal identifier and their vendor's catalog identifier. Sellers don't have much choice but to comply if they want to keep the business.

Here are two invoice instance documents that correspond to the 810 Invoice. As noted earlier I use a naming convention based on segment ID and data element position. You may choose whatever Element names you like.

Sample Input (X12Invoice01.xml)

 <?xml version="1.0" encoding="UTF-8"?> <X12Invoice     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:noNamespaceSchemaLocation="X12Invoice.xsd">   <BIG>     <BIG01>2003-01-27</BIG01>     <BIG02>2003030</BIG02>     <BIG04>4497-0561</BIG04>   </BIG>   <N1Header>     <N1>       <N101>ST</N101>       <N102>BIG BOX - STORE #97</N102>       <N103>92</N103>       <N104>001234567S097</N104>     </N1>   </N1Header>   <N1Header>     <N1>       <N101>RE</N101>       <N102>BIG DADDY'S GOURMET COCOA</N102>       <N103>9</N103>       <N104>987651234</N104>     </N1>   </N1Header>   <ITD>     <ITD01>01</ITD01>     <ITD03>5</ITD03>     <ITD04>2003-02-27</ITD04>     <ITD05>30</ITD05>     <ITD06>2003-02-27</ITD06>     <ITD07>31</ITD07>   </ITD>   <IT1Group>     <IT1>       <IT101>1</IT101>       <IT102>10</IT102>       <IT103>CA</IT103>       <IT104>30.36</IT104>       <IT106>UP</IT106>       <IT107>35790000122</IT107>     </IT1>     <PID>       <PID01>F</PID01>       <PID05>Instant Hot Cocoa Mix - Mint flavor</PID05>     </PID>   </IT1Group>   <IT1Group>     <IT1>       <IT101>2</IT101>       <IT102>30</IT102>       <IT103>CA</IT103>       <IT104>31.08</IT104>       <IT106>UP</IT106>       <IT107>35790000724</IT107>     </IT1>     <PID>       <PID01>F</PID01>       <PID05>Instant Hot Cocoa Mix - Vanilla flavor</PID05>     </PID>   </IT1Group>   <TDS>     <TDS01>1236.00</TDS01>   </TDS>   <CTT>     <CTT01>2</CTT01>   </CTT> </X12Invoice> 

Sample Input (X12Invoice02.xml)

 <?xml version="1.0" encoding="UTF-8"?> <X12Invoice     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:noNamespaceSchemaLocation="X12Invoice.xsd">   <BIG>     <BIG01>2003-01-27</BIG01>     <BIG02>2003030</BIG02>     <BIG04>4445-0323</BIG04>   </BIG>   <N1Header>     <N1>       <N101>ST</N101>       <N102>BIG BOX - STORE #45</N102>       <N103>92</N103>       <N104>001234567S045</N104>     </N1>   </N1Header>   <N1Header>     <N1>       <N101>RE</N101>       <N102>BIG DADDY'S GOURMET COCOA</N102>       <N103>9</N103>       <N104>987651234</N104>     </N1>   </N1Header>   <ITD>     <ITD01>01</ITD01>     <ITD03>5</ITD03>     <ITD04>2003-02-27</ITD04>     <ITD05>30</ITD05>     <ITD06>2003-02-27</ITD06>     <ITD07>31</ITD07>   </ITD>   <IT1Group>     <IT1>       <IT101>1</IT101>       <IT102>20</IT102>       <IT103>CA</IT103>       <IT104>30.36</IT104>       <IT106>UP</IT106>       <IT107>35790000122</IT107>     </IT1>     <PID>       <PID01>F</PID01>       <PID05>Instant Hot Cocoa Mix - Mint flavor</PID05>     </PID>   </IT1Group>   <IT1Group>     <IT1>       <IT101>2</IT101>       <IT102>40</IT102>       <IT103>CA</IT103>       <IT104>31.08</IT104>       <IT106>UP</IT106>       <IT107>35790000641</IT107>     </IT1>     <PID>       <PID01>F</PID01>       <PID05>         Instant Hot Cocoa Mix - Dutch Chocolate flavor       </PID05>     </PID>   </IT1Group>   <TDS>     <TDS01>1850.40</TDS01>   </TDS>   <CTT>     <CTT01>2</CTT01>   </CTT> </X12Invoice> 

Here is the resulting interchange.

Sample Output (Invoices.X12)

 ISA*00*     *00*     *12*9727839573  *ZZ*   BIGBOX      *030125*1058*U*00401*000000006*0*P*~ GS*IN*9727839573*BIGBOX*X*20030125*1058*6*004010~ ST*810*0001~ BIG*20030127*2003030**4497-0561~ N1*ST*BIG BOX - STORE #97*92*001234567S097~ N1*RE*BIG DADDY'S GOURMET COCOA*9*987651234~ ITD*01**5*20030227*30*20030227*31~ IT1*1*10*CA*30.36**UP*35790000122~ PID*F****Instant Hot Cocoa Mix - Mint flavor~ IT1*2*30*CA*31.08**UP*35790000724~ PID*F****Instant Hot Cocoa Mix - Vanilla flavor~ TDS*123600~ CTT*2~ SE*12*0001~ ST*810*0002~ BIG*20030127*2003030**2003-01-23~ N1*ST*BIG BOX - STORE #45*92*001234567S045~ N1*RE*BIG DADDY'S GOURMET COCOA*9*987651234~ ITD*01**5*20030227*30*20030227*31~ IT1*1*20*CA*30.36**UP*35790000122~ PID*F****Instant Hot Cocoa Mix - Mint flavor~ IT1*2*40*CA*31.08**UP*35790000641~ PID*F****Instant Hot Cocoa Mix - Dutch Chocolate flavor~ TDS*185040~ CTT*2~ SE*12*0002~ GE*2*6~ IEA*1*000000006~ 

Again, the line breaks (and indentation on the continuation of the ISA segment) would not appear in actual usage and are included only to improve readability.