Advanced: Build Stedi guides

You can create, import, and customize guides for any of the 300+ X12 transaction sets.

Most users don’t need to build custom guides - we strongly recommend importing your trading partner’s guides from the Stedi Network into your account for free.

However, many trading partners send EDI files that are not 100% compliant with their official guide for a transaction set. For example, they may use different codes for an element. In these cases, you can edit existing guides so that they accurately represent the EDI files you receive.

​

Edit existing guides

Go to your Stedi account and find the guide you want to edit.

To edit, click the ellipses (…) next to the guide and select Edit. The guide opens in the guide builder.

​

Create guides

You can create a custom guide from the base specification for a transaction set from any X12 release. To create a guide:

1. Go to your Stedi account and click Create guide.
2. Select an X12 Release and the Transaction Set base specfication you want to customize.
3. Enter a unique Name for your guide and click Create. The new guide opens in the guide builder.

​

Lock guides

When you’re finished editing, you can lock a guide to prevent further updates. Locking helps prevent accidental changes or deletions to guides in production.

Any user in your Stedi account can lock guides, but only an account admin can unlock guides.

To lock a guide, go to the Actions menu and select Lock. No one can update, delete, or publish a locked guide. However, you can duplicate locked guides, if needed.

To unlock the guide, an admin can go to the Actions menu and select Unlock.

​

Segments and Loops

By default, the guide builder only lists the segments required in the base transaction set. You can add additional segments to your custom guide.

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. Note: Some PDF implementation guides use a designation of M (for Mandatory) instead. In these cases, R is still the appropriate choice.
   • O: Optional.
   • N: Not used by this implementation guide.

​

Hierarchical Levels

An HL segment identifies dependencies between hierarchically related data segments. For example, there may be hierarchical relationships between components of packing information in an 856 Ship Notice.

​

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

X12 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.

You can convey this information to your trading partners by creating variants within a single Stedi guide or by creating a separate Stedi guide for each variant.

​

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.

To create a variant, go to the segment and click + Create variant under the Variant group section.

​

Variant sequence

Some trading partners require that you send certain iterations of loops or segments before others. To address these requirements, specify the Variant sequence, or position number, for each variant. This approach ensures that the variants appear in a specific order when you use this guide to write EDI.

Variants with lower numbers are written before higher numbers, and variants without a defined sequence are written last.

You can only set the variant sequence for loops or segments with a variant defined. To set the variant sequence, click the loop or segment you want to edit and open the Advanced menu.

​

Discriminants

Variants must be uniquely identifiable from each other. To do this, you must add a discriminant that differentiates each variant. The discriminant tells Stedi when one variant should be used over the other for validating, generating, or parsing EDI documents.

For example, you could specify that partners include two N1 Name loops in each 850 Purchase Order: one for the ship to contact and another for the bill to party. In this case you’d add the Entity Identifier Code as the discriminant for N1 Name loops. For the 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 required element of the first segment. The only requirement is that the discriminant must be unique amongst all variants.

​

Elements

By default, the guide builder only includes the elements for each segment that are required in the base transaction set. You can add additional elements to your custom guide.

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.

​

Conditional elements

Some elements come with conditions that tell you when they should be included. For example, if you specify a date in the date/time-segment, you must also specify a date qualifier. Similarly, if you specify a time, you must also specify a time qualifier. You can specify either a date or a time, but you must include at least one.

Every condition begins with a letter that specifies the type of condition, followed by one or more element numbers to which the condition applies. For example, R0103 means that you must specify at least one of the elements 01 or 03.

It’s possible to specify more than two elements, so R010304 would mean that you must specify at least one of the elements 01, 03, or 04.

​

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.

​

Data type and length

Every element has a specific data type and length. Your guide automatically copies the data type and length settings from the base specification for the transaction set. Implementation guides typically use the same data type and length as the base specification, so we recommend leaving the default settings as is, unless you have a specific reason for updating them.

To edit the element’s data type, click the element name in the sidebar and open the Advanced menu in the center column.

​

Maximum length of numeric elements

Numeric elements in Stedi Guides have a maximum length of 15. This differs from the X12 specification, which does not enforce a maximum length for numeric data element types. The reason for this discrepancy is that most common programming languages and libraries deserialize JSON numbers to double precision floating point numbers, which have a maximum of 15 digits of precision. This maximum length ensures that numbers do not have their value changed in the process.

By default, Guides has reduced the length of certain X12 data elements to improve usability. For example, X12 element [212 Unit Price](https://www.stedi.com/edi/x12/element/212) has a maximum length of 17. In Guides, this is reduced to 15 by default, since very few use cases legitimately require 17 digits of pricing precision.

If you need additional digits of precision, you can always change a numeric field to a string, which allows you to choose an arbitrary length.

When working with numbers where precision is important, we recommend deserializing to decimal types with the appropriate precision for your business case.

​

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.

When you create a guide, you can set delimiters in the Overview pane in the top left. Stedi uses the guide’s delimiters when writing EDI. As a default, Stedi recommends the following choices:

• Element: *
• Segment: ~
• Repetition: ^
• Component Element: >

Other common choices for the component element include :, <, and \.

Choosing delimiters for reading and writing EDI depends on your and your trading partner’s data requirements. Clearly communicate the character restrictions with the business groups that are sending the data. You should also agree on substitution characters when a delimiter appears in the data. For example, if your delimiter is * 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

Stedi will parse your data incorrectly if the delimiter you choose appears elsewhere in your data. For example, if your input uses mathematical symbols, then we recommend choosing : 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

​

Delimiters

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.

Stedi automatically infers the delimiters from incoming EDI files.

​

X12 guidance for delimiters

X12 provides the following guidance about delimiters.

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.

% @ [ ] \_ { } \ | < > ~ ^ `

​

Attachments

You can attach files to any Stedi guide and choose whether the attachments are public or private (only available to members of your Stedi account).

For example, you may want to add private attachments that help your team debug issues in your EDI pipeline, such as the original PDF specifications or a changelog. For a public guide, you may want to attach an appendix with a supplementary code list or a diagram that helps your partners understand the messaging flow.

To add attachments to a guide in your account, navigate to its Overview page, scroll to the Attachments section, and click Attach file.

​

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. Click on + Add Sample.
2. In the EDI Sample tab, add a Name and paste a sample file or customize an autogenerated sample based on the guide’s specifications.
3. You may add an an optional Description in the Description tab.
4. Click Create sample.

EDI samples attached to the guide are used:

1. In the Generate EDI test file flow.
2. On your public guide’s interactive web page and are included when partners download the guide as a PDF.