EDI/Edifact Plugin

Edi/Edifact Message Plugin

The Edifact Message plugin provides extensive support for Edifact message processing.

Background Information

Edifact is an international standard for the exchange of business transaction messages, such as invoices, orders, quotes etc. Edifact transactions is heavily used in B2B communications, and supported by SAP, Oracle, IBM and other business processing systems.

Edifact messages consist of a number of records (called "segments"), which themself contain a number of data elements. Both non-composite and composite data elements are possible.

Edifact messages are surrounded by a header- and trailer segment.

An edifact transaction may contain multiple individual messages, and is itself surrounded by a transaction header segment and a transaction trailer segment.

For comprehensive documentation and a full specification, see United Nations Economic Commision for Europe in general, and Introducing UN/Edifact in particular.

Edifact Messages

UN/Edifact defines the overall format and layout of edifact messages. Standard specifications are typically published twice a year. New revisions typically add additional data elements, additional segment types and messages. New revisions are typically backward compatible. That is previous definitions are seldom (if ever) obsoleted.

All messages and segments contains a tag (or message type) field, which allows for the type of message/segment to be identified. Thus, in theory, it is possible to extract field values from arbitrary messages, even if the concrete message layout is unknown.

However, the semantic interpretation of a particular datum highly depends on its position inside the message. For example, a DTM-segment's datetime value can be extracted easily, but its interpretation (delivery date, invoice date, quotation date etc.) is only possible if the overall message structure is known.

Message Subsets

The definitions as published by UN/Unice define the overall structure of messages and segments. However, most concrete application do not need/use/support the full set of possible segments in a message. Many segments are specified as optional and not supported/expected by many concrete users.

For this typical B2B transaction systems expect and handle only subsets of the over all message set and subsets of the possible segment set within those messages.

Meta Descriptions

In order for a correct semantic interpretation, modification and verification of data elements, a meta description is required, which specifies the format of a message (segment order and grouping) and of data aelements (alphanumeric, numeric, minimum/maximum size and value etc.).

Such specifications are published by UN/Unice for the overall framework, and by companies for the B2B partners. Specifications exist in both formal (machine readable) formats and in non-formal (human readable) formats. Formal specification formats are SEF (Structured Edifact Format Specification) and XSD (XML Schema definitions). Non-formal specification are PDF, HTML and Text formats.

The biggest challenges in dealing with Edifact is the trouble to get formal (machine readable) specifications.

SEF format files provide all required information and would be perfect for this task - however, SEF seems to be obsolete and SEF specifications for newer versions are hard to find (which is a pity). SEF files are not available from UN/Unice.

XSD seems to be the way to go, but official XSD sepcifications are rare and not published by UN.

DFDL is a new XML-based definition standard, which is very promising in theory. However, it is relatively new. Only a small subset of Edifact messages is formally specified in this format.

Official documents from UN/Unice include PDF, HTML and Text files. Although being informal, existing html and text files seem to follow a common layout and structure.

Edifact Smalltalk Class Library

This library contains all real functionality of the edifact plugin. The expecco action library (edifact.ets) contains interfacing blocks to the functions found there.

Edifact Message Decoder

Includes a general message/segment/data decoder, which is able to read arbitrary (unknown) messages. Such textual messages (wire data) is decoded and presented as a hierarchy of objects, which model the message, segments and elements. The decoder can decode arbitrary messages - i.e. a meta description is not required for basic decoding.

Edifact Message Encoder

This encodes a message object back into the external edifact wire representation. It cares for the character set, separator definitions etc. In general, the original input is regenerated (with minor differences) when the a decoded edifact message is encoded back to wire data.

Edifact Object Representation Framework

These classes model edifact objects as messages, segments, composite- and non-composite data elements. Without a meta descritpion of the message set, data elements can by accessed by numeric indices (segment#, element#). With a meta description, elements are accessable by more user friendly names, such as the official UN standard field names (C009, C123, 4056 etc), or user assigned application field names (delivaryDate, deliveryLocation, street, city etc.)

Edifact Schema Definition Framework

This set of classes represent a meta description of edifact objects. They can be hand-written, dynamically constructed or read in from external specification files in various formats.

Edifact Schema Definition Readers

These classes read external meta specifications in various formats and create a schema object. Schema objects are needed to correctly interpret element data, to acces elements by user friendly names, and to create new messages which have the correct segment and segment group structure. Readers exist for the following formats:

• XSD
• DFDL
• SEF
• HTML (as in UN docs)
• Text (as in UN docs)
• bots (import specs written in the python programming language, written for the bots processor)
• internal private format

Smalltalk Library API

Decoding a Message

given the following Edifact message in wire data form:

UNA:+.? '
UNB+UNOC:3+Senderkennung+Empfaengerkennung+060620:0931+1++1234567'
UNH+1+ORDERS:D:96A:UN'
BGM+220+B10001'
DTM+4:20060620:102'
NAD+BY+++Bestellername+Strasse+Stadt++23436+xx'
LIN+1++Produkt Schrauben:SA'
QTY+1:1000'
UNS+S'
CNT+2:1'
UNT+9+1'
UNZ+1+1234567'

assuming, the above message (as String) is held in the "msg" variable, it can be decoded with:

    document := EdifactDecoder decode:msg.

Accessing Document and Message Components

EdifactDocument API

"document" will be an instance of EdifactDocument and supports the API:

• numberOfMessages - returns the number of individual messages in the transaction
• messages - a collection of messages contained in the transaction
• headerSegment - returns the transmission advice segment (the 'UNA' segment)
• headerSegment - returns the transaction header segment (the 'UNB' segment)
• trailerSegment - returns the transaction trailer segment (the 'UNZ' segment)

Individual messages are fetched as instances of EdifactMessage via "document messages at:<index>" or enumerated with "document messages do:[:each | ...]".
Examples:

   bgmSegment := document messages first segments first.
   dtmSegmeent := document messages first segments at:2.

EdifactMessage API

EdifactMessage supports the API:

• segments - a collection of individual segments inside the message (exludes header and trailer)
• headerSegment - returns the message header segment (the 'UNH' segment)
• trailerSegment - returns the message trailer segment (the 'UNT' segment)

• messageType - extracts the message type from the message header as a string. In the above example, this would be 'ORDERS'.

The list of version d14b message types is found at [1] and [2].

• controllingAgency - extracts the standards controlling agency which defined the message structure. In the above, this would be 'UN'.
• version - extracts the message structure standard version number. In the above message, this is '96A'.
• release - extracts the message structure standard release number. In the above message, this is 'D'.

• messageSchema - return the message's schema definition (see below)
• edifactVersion - return the messageSet which contains the message and segment schemas (see below)

The "controllingAgency", "version" and "release" fields are required to determine which meta schema definition is to be used (see below for details)

EdifactSegment API

Segments as returned by any of the above understand the following API:

• tag - the segments's id (eg. 'UNA', 'DTM', 'BGM' etc.) The list of version d14b tags is found at [3].

• dataElementAt:index - return a possibly composite data element. This is a wrapper object, which holds on both the schema definition (if known) and the data value.
• dataElementStringAt:index - return the datum as a string. If the element is not present, an empty string is returned.
• dataElementValueAt:index - return the datum as a string or number or nil, if the element is not present.

• dataElementAt:index1 at:index2 - similar to the above, but return a composite element's subcomponent
• dataElementStringAt:index1 at:index2 - similar to the above, but return a composite element's subcomponent's string
• dataElementValueAt:index1 at:index2 - similar to the above, but return a composite element's subcomponent' value

• dataElementAt:index put:newElement
• dataElementStringAt:index put:newString
• dataElementValueAt:index put:newObject

• dataElementAt:index1 at:index2 put:newElement
• dataElementStringAt:index1 at:index2 put:newString
• dataElementValueAt:index1 at:index2 put:newObject

Examples:

   dtmSegment id -> 'DTM'
   (dtmSegment dataElementStringAt:1) -> '4:20060620:102'
   (dtmSegment dataElementValueAt:1) -> #('4' '20060620' '102')
   (dtmSegment dataElementStringAt:1 at:2) -> '20060620'

Wellknown Segment Types

For some wellknown, heavily used segment types, user friendly accessors are available:

UNB Segment API

UNB (transmission header):

• interchangeRecipient
• interchangeSender
• processingPriorityCode
• testIndicator

• -- more to be documented --

UNH Segment API

UNH (message header):

• messageIdentifier - the contents of the S009 element as a composite string (with colons)
• messageType - the contents of the S009:0065 element
• messageVersionNumber - the contents of the S009:0052 element
• messageReleaseNumber - the contents of the S009:0054 element
• controllingAgency - the contents of the S009:0051 element
• associationAssignedCode - the contents of the S009:0057 element
• -- more to be documented --

DTM Segment API

DTM (date time segment):

• dateTimeString - retrieves the 2nd component, which is the date time as a string
• dateTimeFormat - retrieves the 3rd component, which specifies the format of the dateTimeString
• dateTime - converts the dateTimeString as specified by dateTimeFormat and returns a Date, Time, Timestamp, TimeDuration or similar object.

NAD Segment API

NAD (name and address segment):

• city - retrieces the city component
• street - retrieves the street component
• - to be documented -

QTY Segment API

QTY (quantity):

• - to be documented -

MOA Segment API

MOA (monetary amount)

• - to be documented -

Getting a Schema Definition

Schema definitions are imported via the schema parsers. These parsers read specifications in various formats and return an instance of EdifactMessageSet. This holds the definitions of segments and messages. Because schema parsing may be a relatively expensive operation (depending on the format), these schema definitions are cached both in memory and as an option also in external files (schea cache folder).

Assuming, a schema definition is present in SEF format in the file "~expecco/definitions/un/d10a/sef/INVOIC.SEF", read it with:

   messageSet := EdifactSEFParser parseFile: '~expecco/definitions/un/d10a/sef/INVOIC.SEF'.

For XSD schema definitions use the EdifactXSDParser, as in:

   messageSet := EdifactXSDParser parseFile: '~expecco/definitions/un/d10a/xsd/INVOIC.xsd'.

The expecco plugin contains definition files for all UN versions d93a to d14b in the "definitions" subfolder of the plugin.

For standard definitions, a more convenient automatic parsing is possible, by asking the utility class "EdifactVersion" for a particular schema. Give it the controlling agency, version and release, as in:

   messageSet := EdifactVersion controllingAgency:'UN' version:'03A' release:'D'.

Notice that this is also the proper way to get an incoming message's schema definition and done by the "EdifactMessage >> messageSchema method).

MessageSet API

A message set object contains the definitions of one or more messages (as described in the schema file) and of all required (eg. referred to) segments. You can fetch individual messageSchemas with:

• aMessageSchema messageSchemaAt:messageType, where messageType is one of 'INVOIC', 'ORDERS', etc.

and segment schemas with:

• aMessageSchema segmentSchemaAt:segmentID, where segmentID is one of 'BGM', 'DTM' etc.

MessageSets are organized in a hierarchy, and missing schemas are also searched in a messageSet's baseSchema. Typically, messageSets for custom applications have the more general standard UN messageSet as their baseSchema.

MessageSets are cached internally, to prevent parsing overhead.

Accessing fields with Schema Information Present

if a schem is known, fields and segments and groups of segments can be accessed by name. Assuming the standard schema for the ORDERS message, the above message has the following group schema:

       UNA:+.? '   
       UNB+UNOC:3+Senderkennung+Empfaengerkennung+060620:0931+1++1234567'
       UNH+1+ORDERS:D:96A:UN'
       BGM+220+B10001'
       DTM+4:20060620:102'
SG2    NAD+BY+++Bestellername+Strasse+Stadt++23436+xx'
SG25   LIN+1++Produkt Schrauben:SA'
SG25   QTY+1:1000'
       UNS+S'
       CNT+2:1'
       UNT+9+1'
       UNZ+1+1234567'

eg. the NAD belongs to SG2 and the LIN+QTY belong to SG25. Without proper knowledge of which segment group a segment belongs to, it is usually hard to impossible to correctly interpret the values inside the message (just consider the fact, that there are normally multiple NAD, LIN, QTY etc. segments present).

Accessing fields with XPath like Accesors

When a message knows its schema, you can access elements by xpath:

• message dataElementStringAt:'/SG25/QTY/

or, as a convenient shortcut:

• message xPathGet:'/SG25/QTY'

Many of the XPath search and filter functions are possible, for example, to find the second quantity in a message which contains multiple instances of SG25, use:

• message xPathGet:'/SG25[2]/QTY'

or, to find all fields which contain a particular value, use:

• message xPathGet:'//QTY[contains(text(),"100.0")]'

Edifact Plugin Library for Expecco

---

Back to Online Documentation.

Edifact Plugin Library for Expecco

---

Back to Online Documentation.

---

Copyright © 2014-2024 eXept Software AG