Customize Stedi Guides
New to EDI? We recommend reviewing our EDI Essentials documentation. It explains the components of an EDI document's structure, including the various types of and uses for segments and elements.
Segments and Loops
To add additional segments:
- Click either Heading, Detail, or Summary in the left sidebar to view a list of the possible segments for that section.
- Click the box next to each segment to change whether it is included in the transaction set.
- R: Required. Some implementation guides use M instead (for Mandatory).
- O: Optional.
- N: Not used by this implementation guide.
Hierarchical Levels
Example Use Case
Consider the following hierarchical information about customer grocery orders.
ORD02208
├── Package
├── Milk
The following EDI example shows the HL loops that define this information.
HL*1**O*1~
PRF*ORD02208***20220815~
HL*2*1*P*1~
TD1*CTN*1~
REF*CN*1B487311569~
HL*3*2*I*0~
LIN*D002*BN*75206331361~
SN1**1*EA~
PID*F*TRN***MILK~
The first HL segment defines the order at the highest level of the hierarchy. It has four elements.
Element | Name | Description |
---|---|---|
HL-01 | ID Number | Identifies this entry of the HL loop. |
HL-02 | Parent ID Number | The ID Number of the order that this package relates to. |
HL-03 | Level Code | Specifies the type of the entry. In this case, a package. |
HL-04 | Child Code | Specifies whether this entry has children. 1 means yes. |
Then, the document continues:
- The PRF segment contains information about the order itself, including the order number ORD02208.
- The HL segment repeats when the order becomes a package, and the package itself is described by the segments TD1 and REF.
- the HL segment repeats once more when the order contains an item, and the item itself is described by the segments LIN, SN1, and PID.
Add an HL loop to your guide
EDI does not enforce a specific hierarchy in your transaction set. You can add HL loops to your Stedi guide to define the hierarchical relationships you need for your use case.
You must add HL loops to your guides one level at a time. For example, you would create three nested HL segments to capture the following hierarchy.
Order
├── Package
├── Item
To add an HL loop for this scenario:
- Click the DETAIL heading in the left sidebar.
- Click the box next to the HL Loop to change its status from Not Used.
- Choose a code to describe the type of entry for this level of the hierarchy. In this example, you would choose
O
for order. - Click Save to add the HL segment under DETAIL.
- Click the HL Loop, scroll to the list of HL segments.
- Click the box next to HL Loop to add it and select a code. In this example, you'd select
P
for package. - Repeat this process for the final hierarchy level describing the item.
HL Loop Variations
Sometimes, an implementation guide allows for variations of a hierarchy. For example, if a ship notice only has one package, you can leave out the package information.
Variants
Loops and segments allow you to create variants. A variant is a specific version of a loop or a segment that is used in a particular context.
Discriminants
Variants must be uniquely identifiable from each other. To do this, you must add a discriminant that differentiates each variant. The discriminant tells the guide's EDI Inspector and the EDI Translate APIs when one variant should be used over the other for validating, generating, or parsing EDI documents.
bill to
variant, you'd use the BT
qualifier, and for the ship to variant, you'd use the ST
qualifier.The type of discriminant depends on whether the loop is hierarchical:
- For hierarchical loops (HL loops), set a unique HL Level Code (HL-03) on each variant.
- For non-hierarchical loops and segments, set a unique allowed value on each variant.
You do not need to place the discriminant on the first element of the first segment. You can place it in any element of the first segment. The only requirement is that the discriminant must be unique amongst all variants.
Elements
To add or remove elements from a segment:
- Click the segment's name and scroll to find the list of possible elements.
- Click the box next to each element to change whether it is included in the segment.
Some PDF guides have elements marked as conditional (X). These have special rules associated with them. At this step, you should mark them as optional.
Conditional elements
R0103
means that you must specify at least one of the elements 01
or 03
.R010304
would mean that you must specify at least one of the elements 01
, 03
, or 04
.Letter | Name | Condition |
---|---|---|
C | Condition | If the first element is present, then all the other elements must be present. |
E | Exclusive | Only one of the elements may be present. |
L | List conditional | If the first element is present, then at least one of the other elements must be present. |
P | Paired | If one of the elements is present, then all elements must be present. |
R | Required | At least one of the elements must be present. |
Add Conditions
You must specify conditions for elements on the segment level. To add conditions:
- Click the segment name in the left sidebar.
- Scroll to the Conditions section in the center column and click + Add condition.
EDI Reference: Learn more about X12 EDI relational conditions in our EDI Reference documentation.
Data type and size
Every element has a specific data type and size. Your guide automatically copies the data type and size settings from the base specification for the transaction set. Implementation guides typically use the same data type and size as the base specification, so we recommend leaving the default settings as is, unless you have a specific reason for updating them.
Allowed values
Many elements have a value based on a standardized list of codes. For example, the date/time segment has the date qualifier segment, which indicates the type of date to include. The base specifiation lists well over a hundred possible codes. The implementation guide should list which ones are valid for you.
To update the list of accepted codes for an element:
- Click the element's name in the left sidebar.
- Scroll to the Allowed values section in the center column and click Add code value.
- Add one or more codes that are appropriate for your use cases.
Delimiters
Delimiters separate the segments and elements in an EDI file.
As a default, Stedi recommends the following choices:
- Element:
*
- Segment:
~
- Repetition:
^
- Component Element:
>
:
, <
, and \
.*
and you know incoming data contains mathematical expressions, you could agree to use x
instead of *
for relevant expressions (4x2
instead of 4*2
).Writing EDI
:
or \
instead of >
and <
as delimiters. Likewise, you may want to avoid :
if your text data includes time values in HH:MM:SS
format. We recommend considering the following guidance from the X12 documentation.The following characters usually occur in data. They should not be used as delimiters:
- Upper (
A-Z
) and lowercase (a-z
) letters - Digits (
0-9
) - Blank space (
- Minus sign (
-
)
The following characters often appear in data. Use as delimiter characters with caution.
! " & ' ( ) * + , - . / : ; ? =
The following characters sometimes appear in data. Use as delimiter characters with caution.
% @ [ ] _ \ | < > ~ ^ `
Reading EDI
We recommend allowing your trading partners to use any type of delimiter when sending data. They may have different data requirements and have likely already worked to ensure there are no conflicts with EDI delimiters.
X12 provides this guidance about character frequency.
The following characters usually occur in data. They should not be used as delimiters:
- Upper (
A-Z
) and lowercase (a-z
) letters - Digits (
0-9
) - Blank space (
- Minus sign (
-
)
The following characters often appear in data. Use as delimiter characters with caution.
! " & ' ( ) * + , - . / : ; ? =
The following characters sometimes appear in data. Use as delimiter characters with caution.
% @ [ ] _ \ | < > ~ ^ `
Sample EDI files for public guides
You can include multiple EDI sample files in Stedi guides to help new trading partners understand valid usage patterns faster and reduce onboarding time. The guide builder automatically validates each sample against the guide's specifications, so you can fix any errors before you provide them to trading partners.
You can also add a description to each sample that gives trading partners even more context about the intended use cases. The description appears at the top of the guide's EDI Inspector.
To add samples:
- Click Overview in the left sidebar and scroll to the EDI Samples section in the center column.
- In the About tab, add a Name and an optional Description.
- in the EDI Content tab, paste a sample file or customize an autogenerated sample based on the guide's specifications.
- Click Create sample.
Feedback
Have an idea for something we could improve? Page not clear? We love feedback - send us a message.