XML::ASCX12 - ASCX12 EDI to XML Module
use XML::ASCX12; my $ascx12 = new XML::ASCX12(); $ascx12->convertfile("/path/to/edi_input", "/path/to/xml_output");
XML::ASCX12 started as a project to process X12 EDI files from shipping vendors (i.e. transaction sets 110, 820 and 997). However, this module can be extended to support any valid transaction set (catalog).
If you've ever taken a look at an ASCX12 document you'll see why. The EDI format is very compact, which makes is great for transmission. However this comes at a cost.
The main challenge when dealing with EDI data is parsing through the structure. Here we find loops within loops within loops. In this non-extensible, flat format, human parsing is nearly impossible and machine parsing is a task at best.
A quick background of how a typical EDI is formed:
+----> ISA - Interchange Control Header | GS - Functional Group Header <--------+ | ST - Transaction Set Header | Envelope [transaction set specific] Functional Group | SE - Transaction Set Trailer | | GE - Functional Group Trailer <--------+ +----> ISE - Interchange Control Trailer
The Transmission Envelope can have one or more Functional Group. A Functional Group can have one or more Transaction Set. Then each specific catalog (transaction set) can have it's own hierarchical rules.
This sort of structure really lends itself to XML. So using the power of Perl, this module was created to make accessing EDI information easier.
To learn more, the official ASC X12 group has a website http://www.x12.org.
This is a new module and has a few limitations.
EDI -> XML
This module converts from EDI to XML. If you want to go in the other direction, suggest creating an XSL stylesheet and use XML::XSLT or similar to preform a transformation.
Adding Transaction Sets
Adding new catalogs is a manual process. The XML::ASCX12::Segments and the XML::ASCX12::Catalogs need to be manually updated. A future development effort could store this information in dbm files with an import script if demand exists.
You will (hopefully) find consistent coding style throughout this module. Any private variable or method if prefixed with an underscore (_). Any static method or variable is named in ALL_CAPS.
_
ALL_CAPS
The tabs are set at 4 spaces and the POD is physically close to the stuff it is describing to promote fantastic ongoing documentation.
We use the Carp module to handle errors. Some day there may be a better error handler and maybe an error object to reference, but for now it croaks when there is a problem.
XML::ASCX12::Catalogs module is required and probably part of this package, as is the XML::ASCX12::Segments.
These variables are not exported and not intended to be accessed externally. They are listed here for documentation purposes only.
@_LOOPS
Dynamic and keeps track of which loop we are on.
%_XMLREP
Static variable used to lookup bad XML characters.
$_XMLHEAD
Static variable containing the XML header for the output.
The new method is the OO constructor. The default for the segment terminator is ASCII 85 hex. The default for the data element separator is ASCII 1D hex. The default for the sub-element separator is ASCII 1F hex.
85
1D
1F
my $xmlrpc = new XML::ASCX12();
The defaults can be overridden by passing them into the constructor.
my $xmlrpc = new XML::ASCX12('\x0D', '\x2A', '\x3A');
The object that returns is now ready to transform EDI files.
This method will transform and EDI file to XML using the configuration information passed in from the constructor.
my $xmlrpc = new XML::ASCX12(); $xmlrpc->convertfile('/path/to/EDI.dat', '/path/to/EDI.xml');
You may also pass filehandles (or references to filehandles):
$xmlrpc->convertfile(\*INFILE, \*OUTFILE);
This method will transform an EDI data stream, returning wellformed XML.
my $xmlrpc = new XML::ASCX12(); my $xml = $xmlrpc->convertdata($binary_edi_data);
Static public method used to encode and return data suitable for ASCII XML CDATA
$xml_ready_string = XML::ASCX12::XMLENC($raw_data);
This is an internal private method that processes a segment. It is called by _proc_transaction() while looping per-segment.
_proc_transaction()
This is a private method called by _proc_segment(). Each segment consists of elements, this is where they are processed.
_proc_segment()
This is an internal private method. It will either open a loop if we can or return nothing.
This routine is a private method. It will recurse to close any open loops.
Private internal method to actually return the XML that signifies a closed loop. It is called by _closeloop().
_closeloop()
Private method that clears out catalog data and loads standard ASCX12 structure.
This is a private static method. It uses the rules in the XML::ASCX12::Catalogs to determine if a parent is allowed to have the child loop. Returns 0 or 1.
0
1
Here are some things that would make this module even better. They are in no particular order:
Error Handling
Maybe throw in an error object to keep track of things
Encoding Support
Anyone that could review to make sure we are using the correct encodings We basically read in the EDI file in binary and use the ASCII HEX-equivalent for the separators. Many EDI-producing systems use EBCDIC and not UTF-8 so be careful when specifying the values.
Live Transaction Set (Catalog) Library
Make a live repository of transaction set data (catalogs). I'd really like use XML to describe each catalog and import them to local dbm files or tied hashes during install and via an update script. This project will be driven if there is adaquate demand.
According to the ASC X12 website (http://www.x12.org), there are 315 transaction sets. This module has 3, so there are 312 that could be added.
XML Documentation
Create a DTD and maybe even an XML Schema for the XML output. There ought to be better documentation here.
Brian Kaney <brian@vermonster.com>, Jay Powers <jpowers@cpan.org>
http://www.vermonster.com/
Copyright (c) 2004 Vermonster LLC. All rights reserved.
This library is free software. You can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Basically you may use this library in commercial or non-commercial applications. However, If you make any changes directly to any files in this library, you are obligated to submit your modifications back to the authors and/or copyright holder. If the modification is suitable, it will be added to the library and released to the back to public. This way we can all benefit from each other's hard work!
If you have any questions, comments or suggestions please contact the author.
Carp, XML::ASCX12::Catalogs and XML::ASCX12::Segments
To install XML::ASCX12, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::ASCX12
CPAN shell
perl -MCPAN -e shell install XML::ASCX12
For more information on module installation, please visit the detailed CPAN module installation guide.