Using Stedi to Turn EDI Transactions Into a Json API

Let’s start with answers to some of the common questions about EDI to help you become more familiar with the EDI format. Afterwards, you’ll learn how one solution, Stedi, can help you build a custom EDI integration.

What is EDI?

EDI (Electronic Data Interchange) was developed in the 1970s with the goal of replacing paper-based business documents and manual data entry with computer-to-computer data exchange. Instead of sending a paper document, EDI allowed computers to send data files.

Today, multiple EDI standards exist and their adoption rates vary by geographic region and industry.  In simple terms, an EDI standard is a list of commonly used business document definitions, where each definition is normally identified with a number or code. For example, the X12 standard is quite broad and includes transportation, health care, insurance, and legal documents among others.

Each document definition describes the fields the document contains and the syntax that a computer system can use to encode data.  In technical terms, an EDI document is a file with data formatted using a combination of alphanumeric codes, special characters, and line breaks, sometimes using a specific XML format.  In order to use EDI, your system needs to be able to receive and send files and have the required logic to parse the information using the EDI standard that you are targeting.

How does EDI relate to larger information systems?

Businesses often use multiple software systems that store, receive and transmit business data.  Software engineers that design such information systems may use general software development patterns to allow these systems to communicate, for example, by creating an Application Programming Interface or API based on standards such as REST or SOAP.  Under these standards, each system defines its own ad hoc document definitions. EDI, on other hand, provides a common set of document definitions that all businesses can use to send and receive information.

Even though EDI standards provide a standard language for electronic communication, we find that translating from the EDI format to a custom data model is often required. In the example of a warehouse, a shipping manifest in EDI format gives us information such as a related purchase order number, carrier details, and descriptions of the items being shipped. In order to store this information, we should normalize this data in our database, and we may need to associate these items to additional data in the warehouse’s internal data model. This step requires us to extract the data from the EDI document and then map it to the warehouse system’s data model.

Conversely, if we want to send EDI documents to other business partners, we need to be able to transform our internal system’s data into an EDI document.  In order to do this, we need to extend our architecture with a new component that is responsible for receiving EDI documents and translating them from the EDI standard into the data model that we use inside our system.

Integrating EDI with Stedi

At FullStack Labs, we try to recommend solutions that will make custom development faster and less expensive while still delivering high-quality business software. When starting a project that requires custom EDI integration, one choice is to write a completely custom solution. This would be very costly and add considerable time to the development effort.

Alternatively, we could use open source EDI libraries as a starting point for our EDI component.  These may save some initial development effort, but they have limited support options which mean higher ongoing maintenance costs, uncertainty, and potential business disruption in the long term.  

Stedi is a startup that has created a product that supports developers building custom EDI integrations. Currently, Stedi has two offerings: a free EDI reference and a paid EDI integration platform. The paid EDI product from Stedi strikes a balance between these two choices by providing pre-built EDI integration tooling that shortens development time and cost while offering a product maintained by EDI experts that will support your business in the long term.   

The EDI Reference

The EDI reference gives detailed descriptions of X12 EDI documents. The reference covers multiple X12 releases. For each release, it breaks down transaction sets, segments, and elements.  A transaction set is a high-level document, ranging from numbers 100 to 999. Each transaction set is made up of segments, and segments contain elements.

Looking at their documentation, let’s take a look at the information it provides regarding an example EDI purchase order shown below. We’ll unpack the two lines boxed in red to get an understanding of how an EDI file works. I’ll add links below to the documentation, but Stedi may still require you to create a free account in order to view it.

We can see that the transaction set number for a purchase order is 850. Drilling down, we find that the first segment, ST, is the Transaction Set Header, which contains the first element, the Transaction Set Identifier Code, which lists all the transaction sets possible in the X12 specification (in this case, 850). This element is the identifying element that tells us what transaction set, or document type, we’re reading. Going further, the next segment is BEG, or Beginning Segment for Purchase Order, whose first element is Transaction Set Purpose Code, which lists codes like 00, 01, and 02, which map to Original, Cancellation, and Add, respectively.  In this case, we have “00” so this is the original purchase order. The rest of the segment lists the purchase order type (in the below example, SA, or Stands Alone), the PO number (A99999-01), and the PO Date (1997-02-14).

This brief overview of the documentation gives us an idea of the cryptic nature of EDI, but Stedi’s documentation is very well done and with some systematic study can allow humans to read an EDI document. Stedi even provides a very convenient EDI Inspector that allows you to break down the values in an X12 EDI document.

Stedi’s EDI Integration Platform

At this point, we have a better understanding of the value an existing EDI library provides.  Stedi’s API consists of several components that help developers quickly build a custom EDI integration.

The first component is called EDI Core.  EDI core is responsible for translating an EDI document into something that Stedi has cleverly calle JEDI (JSON EDI).  Taking the above example document, EDI Core will translate it to:

We can see that the values that were written on the individual lines above have been parsed into JSON objects.  To a developer, this is slightly more readable, but it still contains a lot of EDI codes that are not human-friendly.

To assist with mapping the JEDI to more human-readable JSON, Stedi offers a mapping feature.  Currently, it is only code-based, but a visual mapping UI will be available in their online console soon.  

The mapping feature is a javascript function that accepts JEDI as an argument and returns a javascript object, allowing the developer to use functions such as map to parse JEDI arrays into simpler custom JSON shapes which can be consumed by a webhook, enabling real-time updates of EDI data as it arrives.  

One limitation is that there currently is no way to look up EDI element codes, although Stedi responded that this feature is on their roadmap for possible future development. Stedi’s documentation does provide values for EDI codes, so it would be up to the developer to create lookup tables in their own code with human-friendly values for the document types they need to support. 

In addition to the EDI Core product, Stedi offers several other products that help you quickly stand up EDI infrastructure, giving you a toolbox for quickly creating test and production EDI environments. These products are still in developer preview, although Stedi has reported that stable versions will become available soon. For developers familiar with cloud infrastructure and infrastructure as code (IaC), the patterns Stedi has used should seem familiar, as they have created a collection of cloud-based services that developers can provision to support EDI processing. You can find out more about these products by consulting their documentation.

Depending on what industry you work in, it’s possible that as a developer you may not have encountered EDI before. At this point, I hope that you are more familiar with the EDI format and have a better idea of how one solution, Stedi, can help you build a custom EDI integration.