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:

1. Click either Heading, Detail, or Summary in the left sidebar to view a list of the possible segments for that section.
2. 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.

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:

1. Click the DETAIL heading in the left sidebar.
2. Click the box next to the HL Loop to change its status from Not Used.
3. Choose a code to describe the type of entry for this level of the hierarchy. In this example, you would choose O for order.
4. Click Save to add the HL segment under DETAIL.
5. Click the HL Loop, scroll to the list of HL segments.
6. Click the box next to HL Loop to add it and select a code. In this example, you'd select P for package.
7. 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.

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:

1. Click the segment's name and scroll to find the list of possible elements.
2. 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

Add Conditions

You must specify conditions for elements on the segment level. To add conditions:

1. Click the segment name in the left sidebar.
2. 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:

1. Click the element's name in the left sidebar.
2. Scroll to the Allowed values section in the center column and click Add code value.
3. 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: >

Writing EDI

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:

1. Click Overview in the left sidebar and scroll to the EDI Samples section in the center column.
2. In the About tab, add a Name and an optional Description.
3. in the EDI Content tab, paste a sample file or customize an autogenerated sample based on the guide's specifications.
4. Click Create sample.