NAME

XML::ASCX12 - ASCX12 EDI to XML Module

SYNOPSIS

    use XML::ASCX12;
    
    my $ascx12 = new XML::ASCX12();
    $ascx12->convertfile("/path/to/edi_input", "/path/to/xml_output");

INFORMATION

Module Description

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).

Why are you doing this?

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.

Module Limitations

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.

Style Guide

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.

The tabs are set at 4 spaces and the POD is physically close to the stuff it is describing to promote fantastic ongoing documentation.

REQUIREMENTS

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.

VARIABLE AND METHODS

Private Variables

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.

Public Methods

object = new([$segment_terminator], [$data_element_separator], [$subelement_separator])

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.

    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.

boolean = $obj->convertfile($input, $output)

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);

string = $obj->convertdata($input)

This method will transform an EDI data stream, returning wellformed XML.

    my $xmlrpc = new XML::ASCX12();
    my $xml = $xmlrpc->convertdata($binary_edi_data);

string = XMLENC($string)

Static public method used to encode and return data suitable for ASCII XML CDATA

    $xml_ready_string = XML::ASCX12::XMLENC($raw_data);

Private Methods

string = _proc_segment($segment_data);

This is an internal private method that processes a segment using $LOOPNEST. It is called by convertfile() or convertdata() while looping per-segment.

string = _proc_segment_in_child($segment_data);

This is an internal private method that processes a segment using $IN_CHILD. It is called by _proc_segment() when $IN_CHILD is defined.

string = _proc_element($segment_code, @elements)

This is a private method called by _proc_segment(). Each segment consists of elements, this is where they are processed.

string = _openloop($loop_to_open, $last_opened_loop)

This is an internal private method. It will either open a loop if we can or return nothing.

void = _closeloop($loop_to_close, $last_opened_loop, $current_segment, $trigger)

This routine is a private method. It will recurse to close any open loops.

string = _execclose($loop_to_close)

Private internal method to actually return the XML that signifies a closed loop. It is called by _closeloop().

void = _unload_catalog()

Private method that clears out catalog data and loads standard ASCX12 structure. Also initializes ISA and GS data common to all Catalogs.

boolean = _CANHAVE($parent_loop, $child_loop)

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.

TODO

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 4, so there are 311 that could be added.

  Documentation for Catalog 175 (Court Notice Transaction Set) is available from the US Bankruptcy Courts (http://www.ebnuscourts.com/documents/edi.adp).

• XML Documentation

  Create a DTD and maybe even an XML Schema for the XML output. There ought to be better documentation here.

AUTHORS

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.

SEE ALSO

Carp, XML::ASCX12::Catalogs and XML::ASCX12::Segments

cpanm XML::ASCX12

perl -MCPAN -e shell
install XML::ASCX12