Build EDI
Overview
The Build EDI flow step is used to transform data into an EDI document. This is useful when a particular target system only accepts EDI.
This guide assumes a basic understanding of EDI purpose and structure. For more information on EDI, refer to this document.
Getting Started
To get started with the Build EDI flow step, create a new flow step and select Build EDI from the list of available step types
Build EDI Step
The step takes envelope data and a list of transactions, transforming it all into an EDI string.
Next, we’ll go over the necessary fields needed to build a simple EDI document.
Separators
Before we start filling out any data, we need to decide which separators we want to use for our EDI document. The two most important separators are the element separator and the segment terminator.
Here’s an example EDI snippet:
NM1*John*Doe~
BGN*Example*~
In the above example, the element separator is * and the segment terminator is ~.
You can fill out the element and segment fields like so:
EDI Separators
Envelopes
EDI uses several layers of enveloping to denote each section of the document.
For instance, the transaction envelope wraps each transaction and provides data about the segment data inside. Similarly, the group envelope wraps the transaction envelope, and the interchange envelope wraps the group envelope.
In the flow step, each configurable envelope piece is represented as a string. These can be derived from expressions or hard-coded depending on the data requirements.
Here’s an example of some hard-coded envelope values in the Build EDI step:
EDI Envelopes
Building Transactions
Transactions are the heart of an EDI document, containing the data you intend to transmit to a target system. An EDI document can contain multiple transactions.
In the Build EDI step, transactions are represented as an array of objects.
A simple representation of 2 empty transactions looks something like this:
// List of transactions
[
{},
{}
]
Assuming that the Identifier Code is 123 and the Convention Reference is ABCDEF, the above produces the following EDI (with line breaks for readability):
ST*123*0001*ABCDEF~
SE*2*0001~
ST*123*0002*ABCDEF~
SE*2*0002~
If we want segments in our transactions, we represent them as properties with array values.
Building on our previous transactions example, here’s an example of a single transaction with two segments:
// List of transactions
[
// Transaction
{
// First segment
NM1: [
{
NM101:"John",
NM102:"Doe"
}
],
// Second segment
BGN:[
{
BGN01:"Example",
BGN02:""
}
]
}
]
Which maps to the following EDI:
ST*123*0001*ABCDEF~
NM1*John*Doe~
BGN*Example*~
SE*4*0001~
We can fill out the step with our example data like so:
Transaction Body
If we ran the step now, we would get something that looks like this for our output:
EDI Output
In the above example, fake data has been used for the envelope fields in order to get the step to run. It’s a little difficult to read on its own, so let’s split it up line by line:
ISA*00* *00* *30*123CORP *99*SOMECOMPANY *230329*1741*^*00501*680111692*1*T*:~
GS*BE*ABCCORP*SOMECOMPANY*20230329*1741*1*X*005010X220A1~
ST*834*0001*ABCDEF~
NM1*John*Doe~
BGN*Example~
SE*4*0001~
GE*1*1~
IEA*1*680111692~
We can see that the JavaScript transaction we filled out earlier turned into a ST/SE envelope, with our NM1 and BGN fields filled out properly!
Note that the BGN02 property from earlier was truncated from our final output. This is intended. Any empty trailing properties will be removed from the final output.
Segments That Share Names
Property names that contain : will be truncated starting from and including the : to allow for properties of the same name to exist. Here’s an example:
REF*123~
REF*ABC~
The above is valid EDI, but invalid JavaScript/JSON. Therefore, a : with identifying text is needed:
{
// Notice the ":" used to differentiate both REF properties
"REF:A":[
{
REF01:"123"
}
],
"REF:B":[
{
REF01:"ABC"
}
]
}
Each REF:<whatever> above will get trimmed down to just REF, allowing for both valid JavaScript/JSON and EDI.
Nested Segments
Nested segments should be inserted as a property at the end of the segment object.
Here’s an example, abbreviated for clarity:
// Segment
BGN:[
{
BGN01:"Example",
BGN02:"",
// Nested segment
HD:[
{
HD01:"Dental"
}
]
}
]
Which produces the following abbreviated EDI:
ST*123*0001*ABCDEF~
BGN*Example*~
HD*Dental~
SE*3*0001~