Home /  Guides / 

Customize Stedi Guides

After you create a Stedi guide, you can customize it for your specific requirements. You can also add sample files to help partners learn valid usage patterns faster.
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

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. Some implementation guides use M instead (for Mandatory).
    • 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.

ElementNameDescription
HL-01ID NumberIdentifies this entry of the HL loop.
HL-02Parent ID NumberThe ID Number of the order that this package relates to.
HL-03Level CodeSpecifies the type of the entry. In this case, a package.
HL-04Child CodeSpecifies 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:

  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 Duplicate this node to add variant.

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.

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

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

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.
LetterNameCondition
CConditionIf the first element is present, then all the other elements must be present.
EExclusiveOnly one of the elements may be present.
LList conditionalIf the first element is present, then at least one of the other elements must be present.
PPairedIf one of the elements is present, then all elements must be present.
RRequiredAt least one of the elements must be present.

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.

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

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. EDI Translate uses the delimiters you set in the guide 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

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. Visit the EDI Translate documentation for details.

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.
EDI samples attached to the guide are available on your public guide's interactive web page and are included when partners download the guide as a PDF.
Segments and LoopsElementsDelimitersSample EDI files for public guides

Feedback

Have an idea for something we could improve? Page not clear? We love feedback - send us a message.

Stedi

Build EDI integrations fast, without being an EDI expert

Start building
About
ProductPricingCareersContactBlog
Follow
  1. Twitter
  2. GitHub
Backed by
AdditionBloomberg BetaFirst RoundStripeUSV
Customer AgreementService TermsPrivacy Notice

Stedi is a registered trademark of Stedi, Inc. All names, logos, and brands of third parties listed on our site are trademarks of their respective owners (including “X12”, which is a trademark of X12 Incorporated). Stedi, Inc. and its products and services are not endorsed by, sponsored by, or affiliated with these third parties. Our use of these names, logos, and brands is for identification purposes only, and does not imply any such endorsement, sponsorship, or affiliation.