test

Sun B2B Suite ASC X12 OTD Library User's Guide

Chapter 2 Overview of ASC X12 OTD Library

This chapter provides an overview of the ASC X12 OTD Library as well as its support for ASC X12 directory versions, SEF file versions, and validation.

This chapter contains the following topics:

ASC X12 OTD Library: Introduction

The Accredited Standards Committee (ASC) X12 was chartered by the American National Standards Institute (ANSI) in 1979 to develop uniform standards for interindustry electronic interchange of business transactions. The result was the X12 standard. This standard allows the electronic exchange of machine-readable information between businesses.

Data Interchange Standards Association (DISA) group publishes the X12 standard. This X12 group develops, maintains, interprets, and promotes the proper use of the ASC standard. The group comes together three times a year to develop and maintain electronic EDI standards. The DISA group’s main objective is to develop standards to facilitate electronic interchange that relates to business transactions, such as order placement and processing, shipping and receiving information, invoicing, and payment information.

For more information on the X12 standard, see the following Web sites:

http://www.disa.org and specifically http://www.x12.org/x12org/index.cfm

X12 implementation guides can be obtained at the following Web sites:

http://www.wpc-edi.com; specifically, http://www.wpc-edi.com/tg4/tg4home.asp

ASC X12 messages have a message structure, which indicates how data elements are organized and related to each other for a particular EDI transaction. In the Sun Java Composite Application Platform Suite, message structures are defined as OTDs. Each OTD consists of:

The transaction set structure of an invoice that is sent from one trading partner to another defines the header, trailer, segments, and data elements required by invoice transactions. The ASC X12 OTD Library for a specific version includes transaction set structures for each of the transactions available in that version. You can use these structures as provided, or customize them to suit your business needs.

eGate Integrator uses OTDs based on ASC X12 message structures to verify that the data in the messages coming in or going out is in the correct format. There is a message structure for each ASC X12 transaction.

The list of transactions provided is different for each version of ASC X12.

The ASC X12 OTD Library provides ASC X12 OTDs that you can use to build Sun Java Composite Application Platform Suite Projects for interfacing with ASC X12 systems. You can use the OTDs standalone with eGate Integrator or in combination with eXchange Integrator and eGate Integrator.

ASC X12 Version Support

This product includes OTDs for the following X12 versions.

Table 2–1 Supported X12 Versions

  • 4010

  • 4011

  • 4012

  • 4020

  • 4021

  • 4022

  • 4030

  • 4031

  • 4032

  • 4040

  • 4041

  • 4042

  • 4050

  • 4051

  • 4052

  • 4060

  • 4061

  • 5010

  • 5020

The library OTDs only accept messages with all the envelope segment information. If you need to generate a custom OTD without an envelope segment, use the SEF OTD wizard as described in Creating ASC X12 OTDs from SEF Files Using the SEF OTD Wizard.

SEF File Support

This product supports SEF versions 1.5 and 1.6 when the SEF OTD wizard is used to build custom OTDs. For more information about the SEF OTD wizard, refer to Creating ASC X12 OTDs from SEF Files Using the SEF OTD Wizard.

The SEF OTD wizard does not handle the following information and sections:

ASC X12 Validation Support

Within each X12 OTD are Java methods and Java bean nodes for handling validation as described in performValidation. The marshal and unmarshal methods of the envelope OTDs handle enveloping and de-enveloping as described in marshal and unmarshal. No pre-built translations are supplied with the OTD libraries; these can be built in the Java Collaboration Editor.

X12 OTDs have validations and translations, but a validation does not generate an acknowledgment transaction. Instead, it generates a string.

The output string of the validation (see check and checkAll) is in XML format conforming to the X12OTDErrors.xsd file. Refer to Contents of the X12OTDErrors.xsd File for more information. For a sample of the validation output XML, refer to Sample of Validation Output XML.

On Demand Parsing

For performance enhancement reasons, the unmarshal() method does not unmarshal the entire message to the leaf element and subelement level. Instead, it does the following:

This behavior is also referred to as “parse on demand,” meaning that elements within a segment or composite are not unmarshaled until an element in that segment or composite is accessed by a getxxx() method invoked in a Collaboration or during marshaling. The OTD may assign unmarshaled segments and composites to a pool that is ready to be freed from memory by the Java Virtual Machine software. Once these segments or composites are freed from memory, they become unparsed. If the element within the segment or composite is accessed again, the OTD reparses the segment or composite.

By default, X12 OTDs set no limit of parsed segments or composites held in memory. You can specify a limit for parsed and freed segments or composites by using the following methods at the OTD root levels:

You can use these methods to set and control the runtime memory use of the unmarshaling process.

Sample of ANSI Output

This section shows an excerpt of the XML X12 4010 850 transaction in ANSI format:


ISA*00*          *00*          *01*9012345720000  *01*9088877320000
  *011001*1718*U*00200*000000001*0*T*:~GS*PO*901234572000*908887732000*
20011001*1615*1*T*004010~ST*850*0001~BEG*01*BK*99AKDF9DAL393*39483920
193843*20011001*AN3920943*AC*IBM*02*AE*02*BA~CUR*AC*USA*.2939*SE*USA*
IMF*002*20011001*0718*021*20011001*1952*038*20011001*1615*002*2001100
1*0718*021*20011001*1952~REF*AB*3920394930203*GENERAL
 PURPOSE*BT:12345678900987654321768958473:CM:500:AB:3920394930203~PER*
AC*ARTHUR JONES*TE*(614)555-1212*TE*(614)555-1212*TE*(614)555-
1212*ADDL CONTACT
Note –

The X12 OTDs accept standard ANSI X12 format . You do not need to specify the input format for existing Business Processes or Collaborations. By default, the OTD output is ANSI. To change the output to XML (reserved for future use), use the setXmlOutput (boolean) method. For information, refer to setXmlOutput. To verify whether the output is XML (reserved for future use), use the getXmlOutput() method. For information, refer to getXmlOutput.

Errors and Exceptions

For all X12 OTDs, including the three envelope OTDs (located in Sun SeeBeyond ⇒ OTD Library ⇒ X12 ⇒ envelope), if the incoming message cannot be parsed for example, if the OTD cannot find the ISA segment, then the unmarshal() method generates a com.stc.otd.runtime.UnmarshalException.

The cause of the UnmarshalException depends on which envelope threw the exception:

You can also use the isUnmarshalComplete() method on an OTD to verify whether the unmarshal() method completed its parsing successfully. Successful completion does not guarantee that the OTD instance is free of data errors within segments and composites, because elements are not unmarshaled until the first invocation of the leaf element getElementXxxx() method of a segment or composite. For more information, see On Demand Parsing

. Encountering this exception triggers an automatic background unmarshal of the entire segment. Note that the value returned by the isUnmarshalComplete() method is not influenced by the outcome of the automatic background unmarshal. Instead, its value reflects what was set by the explicit invocation of the unmarshal() method.

ISA Segment Parsing

The ISA segment in an ASC X12 message is of fixed length, and has sixteen fixed-length data fields. The fixed-length property of the ISA segment enables you to define the fixed positions for delimiters, such as segment terminator and element separator, that are critical for parsing the X12 message. Logic is built into the fully-enveloped OTDs, including the X12 Interchange Envelope OTD to retrieve the delimiters at certain fixed positions and use these delimiters to unmarshal the message.

However, if any of the sixteen data fields is longer or shorter than defined in the specification, the positions of delimiters are nonstandard. This error will result in parsing difficulties and probable runtime failure. In some cases, data that is incorrectly specified in this way can cause conflicting delimiter values, such as element separator defined the same as segment terminator, rendering the whole message unparsable.

Steps Taken to Check for ISA Segment Errors

Assuming valid data, the logic for checking ISA segment errors is as follows:

  1. Check whether the character at index=3 is a valid element separator. If not, an UnmarshalException is thrown, and the unmarshaling process is terminated.

  2. Check whether the characters at index=6,17,20,31,34,50,53,69,76,81,83,89,99,101,103 is same as that at index=3. If not, an UnmarshalException is thrown with an error message that begins "ISA Segment Error", and processing continues with variable length parsing.

  3. Check whether the character at index=104 is a valid subelement separator. If not, an UnmarshalException is thrown with an error message that begins "ISA Segment Error", and processing continues with variable-length parsing.

  4. Check whether the character at index=105 is a valid segment terminator, and also verify that this character is different from the element separator and subelement separator. If not, an UnmarshalException is thrown with an error message that begins "ISA Segment Error", and processing continues with variable-length parsing .

  5. If the version of X12 is version 4020 or later, check whether the character at index=82 is a valid repetition separator and different from the element separator, subelement separator, and segment terminator. If not, an UnmarshalException is thrown with an error message that begins "ISA Segment Error", and processing continues with variable-length parsing .

  6. If variable-length parsing becomes necessary, the ISA segment is parsed using the element separator to retrieve the next sixteeen data elements. After this ISA parsing, an UnmarshalException is thrown with an error message that begins "ISA Segment Error", and the OTD with ISA segment parsed may be examined later to retrieve the parsed ISA segment.

If the message does not have a terminator for its last segment , the ISA segment is also parsed before an UnmarshalException is thrown. You can catch this UnmarshalException and examine the parsed ISA segment in the OTD, for example, to generate negative TA1 acknowledgment.