#847 OIC May 21 Release - B2B support for UN EDIFACT Part 1

The May 21 release of OIC brings lots of new features to B2B. This post will focus on the new UN EDIFACT support, but will also detail our new auto-generation of - send/receive pre-processor integrations - feature. 

The usual caveat from me at the outset - I am not an EDI/EDIFACT expert - many folks tasked with creating such integrations are also not, so this is for you!

Version 1 of B2B in OIC supported X12, now we are also providing UN EDIFACT support. So what is the difference between the 2, apart from the fact that the latter is mainly used in Europe?

Apparently X12 has made inroads into the healthcare market (HIPAA), whereas UN EDIFACT has not. Both standards are used in areas such as supply chain, government etc.

This post begins with an introduction to the format of an order in UN EDIFACT, it is rather pedestrian, if fact probably boring for most of you, who are at home in EDI. I go through the order document line for line, this I am mainly doing for my own benefit, so that I actually understand the values being sent. 

The post continues with a short introduction to the transport protocol I will use, AS2. Finally, we get to the section that covers the implementation of a simple UN EDIFACT orders based B2B transaction in OIC. 

As already mentioned in my previous OIC B2B post from February - I like to think of the concept of pre-processing and processing of the EDIFACT Order. The "pre-processing" does the transport validation and business message validation. For example, is the Order document from a registered trading partner. The May 21 release of B2B will auto-generate the "pre-processing" send/receive integrations, allowing us to concentrate on implementing the backend business logic to take that EDIFACT order, convert it into xml and process it accordingly; in my case - creating a Sales Order in Netsuite.  

UN EDIFACT - ORDER document

So let's begin with an introduction to the UN EDIFACT ORDER format - 

I have an example of such a file -

Now to an explanation of the Segments and fields - 

UNB - think of this as the message envelope - it contains identifiers for the sender and recipient.

UNG - Functional group header e.g. to group multiple issuers in one transmission file with invoices.

UNH - Message Header - must contain message type code and version e.g. Orders and 96A.

BGM - Beginning of Message - identifying the order - document name, number etc.

DTM - Date - i.e. order date

FTX - Free Text 

NAD  - Name and Address

LIN - Line Item

PIA - Additional Product Id

IMD - Item Description

MEA - Measurements i.e. physical measurements of the item ordered

QTY - Quantity - i.e. quantity ordered.

PRI - Price details

SCC - scheduling conditions i.e. for delivery

UNS - Section control to separate the detail and summary sections.

UNT - Trailer - This segment ends the message. It details the total number of segments in the message and the control reference number of the message.

UNZ - the interchange trailer

Let's look at the UNB in more detail - here is a simple example -

UNB+UNOC:3+SENDER1:14+RECIPIENT1:14+210428:0121+1234+ORDERS'

UNOC - controlling agency UNO refers to UN/ECE and C is the level

Then we see the separator : 

3 - syntax version number
+ Now to the sender identifier, in my case SENDER1
:14 - Sender Qualifier 
+ Recipient identification - RECIPIENT1
:14 - Sender Qualifier 
Now to the Date of Message - 210428 (YYMMDD)
:Time - 0121 (HHMM)
+ Interchange Control Reference - 1234 - a unique value, assigned by the sender
+ Recipient's Password reference - ORDERS 

Next comes the Functional Group Header - UNG -

UNG+ORDERS+SENDER1+RECIPIENT1+200707:1500+1+UN+D:96A'

+ORDERS  - type of Message in the Group

+SENDER1 + RECIPIENT1 - self explanatory

+210501:1500 - Date time of Preparation   

+1 - Functional Group Reference Nr

+UN - Controlling Agency

+D:96A - Message Version

Now to the header -

UNH+1+ORDERS:D:96A:UN:EAN008'

+ 1 - reference message number
+ ORDERS - Message Type Identifier
:D:96A - Message Type and version number
:UN - Controlling agency
:EAN008' - Association assigned code.

Now the BGM (Beginning of Message) segment - this is optional.

BGM+220::9+123+9'

+220 - Message name code - 220 = orders
::9 - code list 9 = EAN
+ Document number - 123  - e.g. PO reference nr
+ 9 - message function code number

Now the DTM segment - Date Time 

DTM+137:20210428:102'

+137 - Date Qualifier - 137 is the default value.

:20210428 - Date in CCYYMMDD format 

:102 - Date format qualifier. Default value is 102

The FTX segment - Free Text

FTX+PUR+3++ STORE CUSTOMER ORDER:CP01’

PUR refers to Purchasing information.

Now to NAD - Name and Address segments - 

The first line refers to the buyer / sender.

The second line to the supplier/recipient.

The third line refers to the GLN - Global Location number of the recipient/supplier, see more about this in the AS2 section below. 

The fourth line refers to delivery address

NAD+BY+SENDER1::9'

NAD+SU+RECIPIENT1::9'

NAD+DP+RECIPIENT1GLN::9'

NAD+UC+++WINDSBACH+HAUPTSTRASSE 1+WINDSBACH++91575+DE'

DP - Delivery Party
UC - Ultimate Consignee
+++WINDSBACH - store name, think of a retail shop in the town of Windsbach.
+Hauptstrasse 1 - street and house number
+WINDSBACH - town or city
+91575 - Postcode / zip
+DE- Country code

Now to the line items - 

LIN+00001++7290005554759:EN'

+ 00001 - Line item number
:EN - Item loading count - Number type code. Default value is EN.
7290005554759 - EAN code for the product EAN - type of barcode that encodes article number (European Article Number)

Next segment is PIA - Additional Product Id -

PIA+5+25588903:SA'

+5 - Product ID function qualifier - defaults to 5

+25588903 - Suppler article number

:SA - Code type (Supplier Article)

Next, IMD lines - Item Description

IMD+F++:::Hare of the Dog T-Shirt'

+F - Item Type (F - Free form description)

:::Hare of the Dog T-Shirt - Item Description 1

Other Item type codes include -

Now to segment QTY - quantity -

QTY+ 52:10:EA'

+52 - quantity qualifier- default is 52

:10 - quantity of T-shirts ordered

:EA - Each

Now to Price (PRI) -

PRI+AAA:98.20::NTP:1:EA’

+AAA - Price Qualifier - default value is AAA - which means - net price including charges.

:29.99 - Price

:NTP - Qualifying Price Type - Default value is NTP - Net Unit Price

:1 - Basis i.e. 1 T-Shirt costs 29.99

:EA - Each

Next comes UNS - the separator -

UNS+S'

then UNT - the trailer -

UNT+15+ 1'

15 - the number of segments in the message

+1 - Message reference number, same as in the header segment

Finally, UNZ - the trailer -

UNZ+1+1234'

+1 - number of messages, in my case, 1.

+ - Message reference from UNB

The complete document - 

UNB+UNOC:3+slc13rud:14+CommiskeyWindsbach:14+210428:0121+1234+ORDERS'

UNG+ORDERS+slc13rud+1234+200707:1500+1+UN+D:96A'

UNH+1+ORDERS:D:96A:UN:EAN008'BGM+220::9+123+9'DTM+137:20210428:102'

FTX+PUR+3++ STORE CUSTOMER ORDER:CP01'NAD+BY+SENDER1::9'

NAD+SU+RECIPIENT1::9'

NAD+DP+RECIPIENT1GLN::9'

NAD+UC+++WINDSBACH+HAUPTSTRASSE 1+WINDSBACH++91575+DE'

LIN+00001++7290005554759:EN'

PIA+5+25588903:SA'

IMD+F++:::Hare of the Dog T-Shirt'

QTY+110:10:EA'

PRI+AAA:98.20::NTP:1:EA'

UNS+S'UNT+15+1'

UNE+1+1'UNZ+1+1234'

So much for the quick introduction to UN EDIFACT, now to the transport protocol I will use -

AS2.

AS2 Transport Protocol

Applicability Statement 2 - what a name! Essentially an http based protocol for transmitting messages (usually EDI). AS2 packs the message in a secure envelope. AS2 is payload agnostic, so it can be used to transport any content.

AS2 GLN - Global Location Number that uniquely identifies a party involved in document exchange. 

This is a 13 digit number.

Creating the Integration in OIC

Create the Document Definition -

 

Create the Trading Partner Agreement -

The following integrations have been generated - 

Let's look at the Receive flow - think of this as a pre-processing step before the order is actually orchestrated.

in a bit more detail...

Receive-AS2 -

then the SWITCH, which tests for a business message -

 

Translate-EDI - 

Map to Translate-EDI - sources values from the incoming AS2 payload -

We then have the message processing loop -

Business Message Processing - this can then be configured to invoke a back end integration that actually does the orders processing e.g. create a sales order in Netsuite.

Can, is probably the wrong word here, the local invoke call has to be implemented, if you want the order to be processed.

Now to a simple sanity test - 

First I need to ensure my B2B transport and agreement are deployed - 

I also need to ensure the "Receive" integration has been activated.

Now to testing - currently, you cannot this the integration directly in OIC, so I am using my favourite tool, Postman - 

 

I click on the Metadata URL - 

I use this in Postman - and add the following HTTP headers -

My EDIFACT Payload is as follows - 

Note, I have changed the header to have valid ids for Receiver and Sender.

I check the B2B Tracking in OIC - 

So from an AS" perspective, all in good in the Kingdom of Denmark!

I now click on the Business Messages tab - 

Backend Integration Failed- correct, I have not, as yet, implemented that.

I check out the Integration flow - 

 

Here is the payload - 

I will create the "backend" integration in the next post - but for now - enjoy your Sunday!