Chapter 1 Overview of the UN/EDIFACT OTD Library

This chapter provides an overview of the UN/EDIFACT OTD Library as well as its support for UN/EDIFACT directory versions, SEF file versions, validation, and the UNA segment.

This chapter contains the following topics:

• About the UN/EDIFACT OTD Library

• References

• UN/EDIFACT Directory Support

• SEF File Support

• UN/EDIFACT Validation Support

• UNA Segment Support

• On Demand Parsing

• Errors and Exceptions

About the UN/EDIFACT OTD Library

The United Nations/Electronic Data Interchange (UN/EDIFACT) for Administration, Commerce and Transport protocol was developed for the electronic exchange of machine-readable information between businesses.

The UN/EDIFACT Working Group (EWG) develops, maintains, interprets, and promotes the use of the UN/EDIFACT standard.

UN/EDIFACT messages are structured according to very strict rules. Messages are in ASCII format. The standard defines all these message elements, their sequence, and also their grouping.

UN/EDIFACT publishes the messages for each version separately from the envelopes (header and trailer segments) that are used with those messages.

The messages are available online at:

http://www.gefeg.com/en/standard/edifact/edifact.htm

The envelopes are available online at:

http://www.gefeg.com/jswg/

A new version of UN/EDIFACT messages is released several times a year, containing most of the messages in the previous version, plus any new messages that have been approved by the standards organization. The envelopes are updated with a new version infrequently.

UN/EDIFACT messages have a message structure, which indicates how data elements are organized and related to each other for a particular EDI transaction. In the ICAN Suite, message structures are defined as OTDs. Each OTD consists of the following:

• Physical hierarchy: The predefined way in which envelopes, segments, and data elements are organized to describe a particular UN/EDIFACT EDI transaction.

• Delimiters: The specific predefined characters that are used to mark the beginning and end of envelopes, segments, and data elements.

• Properties: The characteristics of a data element, such as the length of each element, default values, and indicators that specify attributes of a data element—for example, whether it is required, optional, or repeating.

The message level 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 UN/EDIFACT OTD Library for a specific version includes message level 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 UN/EDIFACT 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 UN/EDIFACT transaction.

The list of transactions provided is different for each version of UN/EDIFACT.

The UN/EDIFACT OTD Library provides UN/EDIFACT OTDs that you can use to build ICAN Projects for interfacing with UN/EDIFACT systems. You can use the OTDs standalone with eGate Integrator or in combination with eXchange Integrator, eGate Integrator, and the UN/EDIFACT Manager Composite Application.

References

The following resources provide additional information about the UN/EDIFACT protocol:

• The United Nations Economic Commission of Europe (UN/ECE) is one of the five regional commissions of the United Nations. The UN/ECE Web site contains technical information concerning rules, standards, recent UN/EDIFACT directories, syntax, and so on.

  http://www.unece.org/trade/untdid/welcome.htm

• UN/EDIFACT publishes the messages for each version separately from the envelopes (header and trailer segments) that are used with those messages.

  The messages are published at:

  http://www.gefeg.com/en/standard/edifact/index.htm

  The envelopes are published at:

  http://www.gefeg.com/jswg/

UN/EDIFACT Directory Support

The UN/EDIFACT OTD Library provides OTDs for the following UN/EDIFACT directories:

• D.01A and B

• D.00A and B

• D.99A and B

• D.98A and B

• D.97A and B

• D.96A and B

• D.95A and B

SEF File Support

The UN/EDIFACT OTD Library support 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 UN/EDIFACT OTDs from SEF Files.

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

• In the .SEMREFS section, semantic rules with its type of the “exit routine” are ignored as per SEF specification. An exit routine specifies an external routine (such as a COM-enabled server program supporting OLE automation) to run for translators or EDI data analyzers.

• The .TEXT sections (including subsections such as .TEXT,SETS, .TEXT,SEGS, .TEXT,COMS, .TEXT,ELMS, .TEXT,SEGS) are ignored due to the fact that these sections store information about changes in a standard’s text, such as notes, comments, names, purposes, descriptions, titles, semantic notes, explanations, and definitions.

UN/EDIFACT Validation Support

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

EDIFACT 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 EDFOTDErrors.xsd file. Refer to Contents of the EDFOTDErrors.xsd File for more information. For a sample of the validation output XML, refer to Sample Validation Output XML.

Currently the segment syntax error code (SegmSyntErroCode) and data element syntax error code (DataElemSyntErroCode) use the same codes as the X12 protocol.

UNA Segment Support

All UN/EDIFACT messages have a UNA segment (service string advice). It is used to send delimiter and indicator characters. The UNA segment is optional per the UN/EDIFACT specification.

The string has a mandatory fixed length of 9 characters. The first three are “UNA,” immediately followed by the 6 characters as defined in ISO 9735.

The UNA segment template is a fixed length with segment ID = UNA, followed by 6 one-byte fields. Each field specifies a separator or other service character. For more information, refer to Setting Delimiters and Indicators.

The OTD Library provides the getmarshalUNA() method to UN/EDIFACT OTD top “outer” level with its Java type of java.lang.Boolean. For information, refer to getMarshalUNA.

• If its value is java.lang.Boolean.TRUE, then UNA segment data is always included in the output message.

• If its value is java.lang.Boolean.FALSE, then UNA segment data is never included in the output message.

• If its value is null (or user never sets its value), then inclusion of UNA segment data in the output message is based on the following:

If any delimiter values are set through UNA segment object, the UNA segment data is included in the output message regardless of default or non-default delimiters are used. Otherwise,

• If non-default delimiters are used, then UNA segment data is included in the output message.

• If default delimiters are used, then UNA segment data is not included in the output message.

On Demand Parsing

For performance enhancement reasons, the unmarshal() method does not unmarshal the entire message. Instead, it does the following:

• Unmarshals the incoming message at the segment and composite level. In other words, the OTD checks for all relevant segments and composites and reports any missing or extra segments or composites.

• Reports trailing delimiter for elements and composites.

This 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 in the Collaboration using a getxxx() method. The OTD may assigned unmarshaled segments and composites to a pool that is ready to be freed from memory by the Java Virtual Machine (JVM). Once these segments or composites are freed from memory, they become unparsed. If the element within segment or composite is accessed again, the OTD reparses the segment or composite.

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

• setMaxParsedSegsComsNum() method (setMaxParsedSegsComsNum

• setMaxFreedSegsComsNum() method (setMaxFreedSegsComsNum)

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

Errors and Exceptions

For all UN/EDIFACT OTDs, including the two envelope OTDs, if the incoming message cannot be parsed (for example, if the OTD cannot find the UNB segment), then the unmarshal() method generates a com.stc.otd.runtime.UnmarshalException.

You can also use the isUnmarshalComplete() method to learn whether unmarshal() executed without reporting any errors. Successful completion does not guarantee that the OTD instance is free of unmarshal exceptions within segments, however, since elements are not unmarshaled until the first getElementXxxx() method of a segment is encountered (see On Demand Parsing). Encountering this triggers an automatic background unmarshal of the entire segment. Note that the value returned by isUnmarshalComplete() 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.