How to read X12 specifications

This article is about reading and understanding typical ANSI X12 specifications, generated with tools like SpecBuilder in PDF or MS Word format. Usually specifications are straight-forward, but there are some nuances you should be aware of.

An X12 specification is a particular implementation of X12 transaction, defined by a company to be used with its partners.

Prerequisites: you should be familiar with X12 components, such as transactions, loops/groups, segments and elements.

1. Cover Page

Often (but not always) it starts with a Cover page which contains X12 transaction set number (such as 850 for Purchase Order or 810 for Invoice), version, publication date, author, logo and some other things.

001 cover

The most important information is Transaction Set number (856 on the picture above) and X12 version (4010). Also I usually check the publication date to make sure it is not too old – if it is from 1990s, I would probably ask if it is the latest version.

Continue reading

Typical mapping issues: the order of qualified segments/loops

From time to time I face trading partners, which require a particular order of qualified segments/loops. For example, N1 (BY), then N1 (SE), then N1 (SF) and then N1 (ST). So I ask developers who work on the outbound maps to generate such things in the order defined in the specifications. I.e. if the spec lists DTM (010) first and DTM (002) second, the map should do the same – just in case. For inbound maps I obviously ask developers not to use positions but qualifiers.

Gennady Kim

Typical mapping issues: CTT-01 in X12 856

A typical issue – when an unexperienced developer works on the outbound X12 856 documents (ASNs/Ship Notices), they often populate CTT-01 with the number of products this Ship Notice contains. Partly because of its definition of

CTT-01 354 Number of Line Items
Total number of line items in the transaction set

But for X12 856 CTT-01 should contain the number of HL groups/loops. There is a note about it in the standard:

NOTES 3/010 Number of line items (CTT01) is the accumulation of the number of HL segments. If used, hash total (CTT02) is the sum of the value of units shipped (SN102) for each SN1 segment.

Gennady Kim

Typical mapping issues: Vendor Number

Decided to start publishing very short posts about typical issues/mistakes map developers make working on the maps.

And Vendor Number is one of the things (unexperienced) developers often do not understand. For some reasons they think it is some kind of an additional document identifier, like PO number – and map it (I witnessed it multiple times) to things like Sales Order number, End Customer PO number or even PO number itself.

The reality is that Vendor Numbers are IDs buyer/purchaser assigns to its vendors/suppliers, and it stays the same across the documents with the same sender/receiver ID.

Usually it comes in Purchase Orders (X12 850) as

REF*IA*12345'

and should be sent back in Invoices (X12 810) the same way

REF*IA*12345'

In some cases it might be even hardcoded in the outbound maps.
Gennady Kim

Typical X12/EDIFACT/SAP IDoc mapping: scheduled line items in Purchase Orders

A short explanation on how companies describe/schedule multiple deliveries in their Purchase Orders in different EDI formats. For example, a company wants to purchase 200 kilograms of product ABC, but they want it to be delivered within several days, like 50 kilogram on 06 Oct 2020, 50 kilogram on 08 Oct 2020, 40 kilogram on 10 Oct 2020 and 60 kilogram on 12 Oct 2020.

Order #0000001
Product ABC123 - 200 KG
    2020-10-06: 50 KGM
    2020-10-08: 50 KGM
    2020-10-10: 40 KGM
    2020-10-12: 60 KGM

X12 850
X12 uses SCH loop for this purpose. SCH-01 is the quantity, SCH-02 is the unit of measurement, SHC-05 is the date qualifier (usually 002 – Delivery Requested) and SCH-06 is the requested delivery date.

PO1*00010*200*KG***IN*ABC123'
    SCH*50*KG***002*20201006'     << 002 Delivery Requested
    SCH*50*KG***002*20201008'
    SCH*40*KG***002*20201010'
    SCH*60*KG***002*20201012'

EDIFACT ORDERS
EDIFACT usually uses SCC group with 4017 element of “1” (Firm) + QTY (11, Split quantity) and DTM (2, Delivery date/time, requested)

LIN+00010++ABC123:BP'
    QTY+21:200:KGM'     << 21 Ordered quantity
    SCC+1'     << 1 Firm
        QTY+11:50:KGM'          << 11 Split quantity
        DTM+2:20201006:102'     << 2 Delivery date/time, requested
    SCC+1'
        QTY+11:50:KGM'
        DTM+2:20201008:102'
    SCC+1'
        QTY+11:40:KGM'
        DTM+2:20201010:102'
    SCC+1'
        QTY+11:60:KGM'
        DTM+2:20201012:102'

SAP IDoc ORDERS
IDoc uses E1EDP20 segments with WMENG for quantity and EDATU for requested delivery date.

<E1EDP01 SEGMENT="1">
      <POSEX>000010</POSEX>
      <MENGE>200</MENGE>
      <MENEE>KGM</MENEE>

      <E1EDP20 SEGMENT="1">
            <WMENG>50</WMENG>
            <EDATU>20201006</EDATU>
      </E1EDP20>
      <E1EDP20 SEGMENT="1">
            <WMENG>50</WMENG>
            <EDATU>20201008</EDATU>
      </E1EDP20>
      <E1EDP20 SEGMENT="1">
            <WMENG>40</WMENG>
            <EDATU>20201010</EDATU>
      </E1EDP20>
      <E1EDP20 SEGMENT="1">
            <WMENG>60</WMENG>
            <EDATU>20201012</EDATU>
      </E1EDP20>

      <E1EDP19 SEGMENT="1">
            <QUALF>001</QUALF>
            <IDTNR>ABC123</IDTNR>
      </E1EDP19>
</E1EDP01>

Gennady Kim

Typical X12/EDIFACT/SAP IDoc mapping: relationship between different O2C business concepts and SAP IDoc/X12/EDIFACT structures

In the following table I’ve tried to connect typical business concepts used in order to cash (O2C) process and EDI documents’ groups/loop, segments/records and elements/fields.
I used structures from SAP IDoc of ORDERS05, INVOIC02 and DELVRY03 (but it could be applied to other DELVRY* and SHPMNT* messages); X12 of 850 (Purchase Order), 810 (Invoice) and 856 (Advanced Ship Notice); EDIFACT – segments used everywhere (ORDERS, INVOIC and DESADV in particular)

This table is based on my experience and your implementation might be different. Please also take into account that different formats might use different codelists so you cannot map codes as is – you’ll need a code conversion.

Continue reading

Typical X12/EDIFACT/SAP IDoc mapping: a batch split

Today I want to explain how batch split works in SAP IDocs. For some reasons many developers have difficulty with this so I hope they would find this helpful.

What is the batch? Imagine a bakery which makes bread. Bread is the product. Batch is the bread of the same type made at one baking, i.e. a specific instance of this product. Batch has the same manufacturing/expiration dates, (usually) the same taste and other characteristics. So, the bakery makes the same bread 5 days a week and every baking produces a new batch – 5 different batches during a work week.

What is the batch split? In SAP IDoc it is a situation when the product contains one or more batches (specific instances) and the IDoc contains information about both product and its batches. It is where people are usually confused because IDoc uses the same records for both product (material) and its batch(es).

For example, in DELVRY SAP IDoc products/batches are described with E1EDL24. When there is no batch split, there will be one E1EDL24 per product:

E1EDL24
    POSNR = 000010
    MATNR = 123456
    ARKTX = Wholewheat Bread
    LFIMG = 125.00
    VRKME = EA

A straight-forward situation – 125 loafs of Wholewheat Bread have been shipped. But it becomes different (and a bit tricky) when such IDoc contains information not only about the product, but also about its batches. If these 125 loafs are actually 100 loafs baked yesterday and 25 baked today, it will be something like this:

E1EDL24  <<< this is the product
    POSNR = 000010
    MATNR = 123456
    ARKTX = Wholewheat Bread
    LFIMG = 0.00    <<< its quantity is zero (!!)
    VRKME = EA
E1EDL24  <<< this is the 1st batch
    POSNR = 900001
    MATNR = 123456
    ARKTX = Wholewheat Bread
    LFIMG = 100.00    <<< its quantity is 100
    VRKME = EA
    HIPOS = 000010    <<< link to the "parent" product
    CHARG = ABC1234    <<< Batch ID
    VFDAT = 20200315    <<< Expiration Date
E1EDL24  <<< this is the 2nd batch
    POSNR = 900002
    MATNR = 123456
    ARKTX = Wholewheat Bread
    LFIMG = 25.00    <<< its quantity is 25
    VRKME = EA
    HIPOS = 000010    <<< link to the "parent" product
    CHARG = ABC1235    <<< Batch ID
    VFDAT = 20200316    <<< Expiration Date

So you could see the difference – now there is one E1EDL24 with zero quantity and no HIPOS, and 2 E1EDL24s with HIPOS which is the same as POSNR of the “parent” product. Usually there are 2 indicators of a batch split situation – (1) when some E1EDL24s have POSNRs which start with “9” and (2) when some E1EDL24s contain HIPOS elements. If you see such E1EDL24s – they are batches. I personally check the presence of HIPOS to understand if this is a batch and LFIMG of zero to understand it is the main product.

CHARG is the batch number, unique ID assigned to this particular batch.

I think it is obvious you cannot treat E1EDL24s equally when there is a batch split situation. Your implementation will depend on the requirements. If the trading partner isn’t interested in batches – you should use the main item only (“E1EDL24 with no HIPOS”) and use LFIMG of this item (if not zero) or the sum of LFIMGs of its batches (E1EDL24s where HIPOS is equal to the POSNR of this item). If they need batches – use batches (“E1EDL24 with HIPOS”) for items.

Also, there could be some mixed situations – when SAP IDoc might contain both products with and without batches. Or when the trading partner wants to have only one product but list all the batch numbers under it. And so on – but I hope it is clear now how to process such things.

Gennady Kim

Typical X12/EDIFACT/SAP IDoc mapping: Allowances/Charges

Allowances/Charges are typical information you can find in Invoices. Usually allowance is a discount/credit provided by seller. Charge – amount buyer should pay in addition to money paid for goods/services (such as freight cost, late payment fees and others). There could be multiple Allowances/Charges per invoice, they could be applied to different levels (products or total amount). There are several ways to describe allowances/charges in EDI – as a percent from the total amount (for example, 5%), as a fixed sum (for example $120) or as an amount per unit (for example $0.10 per kilogram). In EDI data the following segments/records are used for Allowances/Charges: SAC (Service, Promotion, Allowance, or Charge Information) in X12, ALC (Allowance or charge) + MOA (Monetary amount) + PCD (Percentage details) in EDIFACT and E1EDK05 (Document header conditions)/E1EDP05 (Document Item Conditions) in IDoc (INVOIC02).

Sometimes terms “surcharge”, “discount”, “adjustment”, “A/C” and other might be used instead.

Examples:
X12:

SAC*C*D240***5935**********VAL FR CHARGE~

EDIFACT:

ALC+C++++FC:::VAL FR CHARGE'
MOA+8:59.35'

SAP IDoc:

<E1EDK05 SEGMENT="1">
	<ALCKZ>+</ALCKZ>
	<KSCHL>ZFAC</KSCHL>
	<KOTXT>VAL FR CHARGE</KOTXT>
	<BETRG>59.35</BETRG>
</E1EDK05>

Continue reading

Typical X12/EDIFACT/SAP IDoc mapping: Hazardous Materials / Dangerous Goods

Recently I’ve been working with different logistic documents (SAP IDoc/X12/EDIFACT and CIDX/ChemXML) which contain information about Hazardous Materials/Dangerous Goods. I used a lot of sources to find information about the data and its usage, and want to share my humble knowledge here.

As always, it is just an idea, and your implementation might be different. But in the most cases the core logic will follow this idea. Mention should be made that HazMat data is very important and you must understand what you are doing. If you have any concerns, or not sure you understand it completely – you must contact subject matter experts (SMEs). This article is more about “HazMat data from EDI point of view” rather than ready-to-use implementation guide.
Continue reading