Skip to main content
Sign in

Intro to Stedi and EDI in Chain.io

Johnny Bilotta
  • Updated

Overview

Stedi is an implementation within the Chain.io portal that allows our customers and users to process and execute EDI transactions within their Flow Executions.

Although Stedi is integrated into our system, it is important to understand that you must have a Stedi account to use it along with the Chain.io portal, and add EDI translations to your Flow Executions.

Setting up a Stedi Account

We will set up the Stedi account for you during your customer on-boarding process. If you have gone through this process, please contact your Chain.io Customer Success Manager or Sales Representative.

We highly recommend you review and bookmark the Stedi support documentation. Stedi’s support documentation can be found here.

Chain.io Integration Flow Types That Support EDI via Stedi

  • ASN/Milestone
    • Send Milestone
      • 214 (Shipment Status)
      • 315 (Shipment Status)
    • Send ASN
      • 856 (Send ASN)
  • Freight Operations
    • Send Milestone
      • 214 (Shipment Status)
      • 315 (Shipment Status)
    • Send ASN
      • 856 (Send ASN)
    • Receive Load Tender / Booking
      • 204 (Load Tender)
    • Send Load Tender / Booking Acknowledgement
      • 990 (Load Tender Response)
    • Send Freight Invoice
      • 110 / 210 / 310 (Freight Invoice)
  • PO Management Automation
    • Send Milestone
      • 214 (Shipment Status)
      • 315 (Shipment Status)
    • Send ASN
      • 856 (Send ASN - but including PO Line information like color/size/sku)
    • Receive Load Tender / Booking
      • 204 (Load Tender)
    • Send Load Tender / Booking Acknowledgement
      • 990 (Load Tender Response)
    • Send Freight Invoice
      • 110 / 210 / 310 (Freight Invoice - # varies by mode but many people using the 210 to cover all modes)
    • Receive Purchase Order
      • 850 (Purchase Order)
      • 860 (Purchase Order Change)
    • Receive Product Master
      • 832 (Item Master)

  • Carrier Operations
    • Send Milestone
      • 214 (Shipment Status)
      • 315 (Shipment Status)
    • Send ASN
      • 856 (ASN)
    • Receive Load Tender / Booking
      • 204 (Load Tender)
    • Send Load Tender / Booking Acknowledgement
      • 990 (Load Tender Response)
    • Send Freight Invoice
      • 110 / 210 / 310
  • Warehouse Automation
    • Receive Warehouse Order
      • 940
    • Send Warehouse Shipment
      • 945
      • 856 (ASN)
    • Receive Product Master
      • 832 (Item Master)
    • Receive Inventory
      • 944
    • Send Inventory Status
      • 945
  • Customs Operations
    • Receive Commercial Invoice
      • 810 (Commercial Invoice)
    • Send Milestones
      • 214 (Shipment Status - but used for Clearance status)
      • 315 (Shipment Status - but used for Clearance status)
    • Send Customs Declaration
      • 856 (ASN - but including duty/tax/fee details)

 

How Does Stedi Work

There are two sides to the Stedi platform that we use. Guides and Mappings. Each are essential when working with Stedi within the Chain.io portal. Below we will go into detail about how to use each. We strongly encourage you review and bookmark the Stedi Documentation as well.

Guides

Stedi’s EDI translation services are built around what they call guides. A guide represents an implementation of single X12 / EDIFACT Transaction Set to match a customer’s specification of that transaction set. Eg: “Matson 204 Transportation Motor Carrier Load Tender”They have tooling to allow a dev to easily work through a customer spec and turn it into a guide.

It is intended that guides will be created by the customer (or by Stedi on behalf of customer), or by Chain.io in on a professional services basis.

Once created, the guide provides:

  • Documentation of the spec
  • Validation of EDI docs to see if they match the spec
  • A JSON Schema document that represents an “EDI Like JSON” document that can be used in their mapping tool.
  • The ability to translate between EDI and and “EDI Like JSON”
  • See What is an Implementation Guide

Mappings

  • Mappings in Stedi are used to convert a JSON format, such as a Standard Shipment document, to an “EDI Like” JSON document that the guide can use when converting to EDI. Or vice versa.
  • The goal is to use a JSON format that can easily be converted to or from Chain.io canonical. Ideally it is a representation of the data as used by our systems, not a representation of an edi format. That is what guides are for.
  • Mappings are implemented as a JSONata schema. This enables a great deal of flexibility.
  • Stedi provides a very powerful and easy to use online editor for creating and editing mappings between guides and JSON Documents.
    • The user provides a source and a target for the mapping. In EDI -> JSON transformations the source would point at the Stedi GUIDE built for this integration and the target would be either the JSON Schema for the JSON document type used by flow, or an example document of that type which Stedi will use to infer the schema.
    • For JSON -> EDI transformations the source will be the JSON doc or schema and the destination will be a Guide.
  • In addition to making it much easier to write the mapping, the editor also does validation on the fly. So if you try to map an int field into a string field it will yell at you.
  • See Mappings on Stedi.com
  • It is expected that in general Mappings between a particular Transaction Set and JSON type will be very similar across different specific guides for that transaction set. So it will probably make sense for us to maintain a library of starter mappings. They can be imported or cut and pasted into Stedi.

Setting up a Guide and Mapping in Stedi

  1. Go to https://www.stedi.com/app/guides/create to create a new guide
  2. Choose a Transaction Set and Version
  3. Create a guide to match customer requirements. Click "select guide-nodes" in the lower left corner if there are elements you want that are not present.


  4. When your guide is setup the way you want, click on Actions-> Create Mapping in the upper right corner:


  5. Specify if you are mapping from EDI or To EDI, click create
  6. Depending on if you are writing to EDI or reading from EDI, Select Set Source, or Set Target. This is where you will paste in a sample of the Chain.io JSON (or JSON schema)



  1. Implement your mapping between the guide and the json.
  2. When you are setting up your flow, you can click the magnifying glass icon next to Guide or Mapping ID to go to the list of created items to copy the id.
  3. Stedi provides extensive documentation on setting up guides and mappings. In addition they are happy to help if you want to contact them in the #stedi-chainio channel in Slack.

 

How to use EDI in a flow in portal:

Note: this example assumes that the transaction type the user wants to integrate is already configured in the portal. See "How to add a transaction type to portal" section for instructions on adding a new transaction type.

From EDI

This is the process to follow when you want to receive EDI files.

  1. Select the transaction type you want from the Source File Type drop down. Eg: Stedi 204 EDI. Below the dropdown you will see an info section that will tell you what JSON file type the flow will be expecting to be output by the EDI conversion process. This is the JSON type that you are mapping to. It will be the output from the EDI mapping process.
  2. You will need either a JSON schema or a sample document of that type. (We should make these available for download at this point in the portal. For now, you'll need to find a sample)
  3. Customer (or PS dev) should go to their Stedi and create a new Guide and mapping. You should be able to test the mapping on the Stedi site.
  4. Add the guide and mapping ids to the EDI settings for the flow. You can look up the ids but clicking on the magnifying glass icon. That will take you to the correct list on Stedi's site to select the id.
  5. An API Key is required. API Keys can be generated on Stedi's website. You can use a separate API Key for processing the guide and the mapping if desired. (They probably won't be different but if for some reason we want to have them on different accounts we need this functionality. Eg: we want to run a mapping or guide we offer from our account )
  6. If you would like to return a 997 to the sender of the EDI file, click on "Send 997 Acknowledgement".
    1. At the moment we only support sending 997s as a response when the source system/connection are SFTP. We will be adding support for using an SFTP Job or AS2 in the future.
    2. You will then have to chose what directory they should be uploaded to. Right now this will go to the source SFTP server. If we need to ability to send to a different SFTP server in the future that functionality can be added.
    3. Currently we only send positive acknowledgements. If the EDI is successfully mapped into the Chain.io JSON type, we will generate and transmit the 997.
  7. Fill out any additional settings associated with the Chain.io JSON File Type. The type. "Chain.io Booking Response JSON" used below does not have any options, but if there are options defined for the type such as mappings, they will be displayed below the EDI settings. (you can see an example of this in the To EDI example below)
  8. The compiled flow will now translate incoming EDI files to Chain.io Booking Response JSON before the rest of the flow starts. After that conversion, the rest of the flow proceeds as normal.

 

 

Flow Execution:

Below is an example flow invocation for a flow that receives EDI. All of the intermediate and transmitted files are attached to the flow execution. This should make debugging issues far easier than it currently is.

Things to note:

  1. Data tags will be published for each Group and Interchange Control numbers from the incoming EDI message. These are useful for diagnosing issues with the partner that sent the EDI.
  2. The original EDI input file will be added to the execution.
  3. The intermediate file generated when the guide processes the input EDI file. This is what is passed into the mapping.
  4. The Chain.io JSON file that is the output of the mapping is attached.
  5. The 997 Ack that was generated and sent to the original sender's sftp.
  6. There are detailed logs explaining each step of the transformation process, along with any errors that may have occurred.

To EDI

When you want to be able to output EDI files, the process is very similar to receiving EDI. But there are significantly more settings.

  1. Select the transaction type you want from the Destination File Type drop down. Eg: Stedi 990 EDI Test (ignore Test text for purposes of this doc). Below the dropdown you will see an info section that will tell you what JSON file type the flow will be expecting from the output converter of the flow. This is the JSON type that you are mapping from. It will be the input type that is converted to EDI.
  2. You will need either a JSON schema or a sample document of that type. (We should make these available for download at this point in the portal. For now, you'll need to find a sample)
  3. Customer (or PS dev) should go to their Stedi and create a new Guide and mapping. You should be able to test the mapping on the Stedi site.
  4. Add the guide and mapping ids to the EDI settings for the flow. You can look up the ids but clicking on the magnifying glass icon. That will take you to the correct list on Stedi's site to select the id.
  5. An API Key is required. API Keys can be generated on Stedi's website. You can use a separate API Key for processing the guide and the mapping if desired. (They probably won't be different but if for some reason we want to have them on different accounts we need this functionality. Eg: we want to run a mapping or guide we offer from our account )
  6. There are a number of additional fields that are required for generating an EDI file such as Sender and Receiver Ids. These will be used to generate the EDI Envelope for the file. These can be included in the destination EDI type via the EDI Guide.
  7. If you want to require a 997 Acknowledgement before a flow is marked as complete, then click on "Expect 997 Acknowledgement.
    1. Right now, we only process acknowledgements when the EDI is being sent to an SFTP Destination System/Connection. It will automatically use the same settings (with the directory specified in the setting for this section) to look for EDI acknowledgements.
    2. If 997 is expected, the status of any flow Execution that successfully sends a file will be set to "Pending Acknowledgement" (or just "pending").
    3. It will only be set to success if it receives an acknowledgement for each of the files it has sent. (If multiple files are passed in to the flow, each will be sent out and each will need to be acknowledged.
    4. If the flow is not received within the time specified by "Expect 997 Within", the status will be changed to a logical fail.
  8. You can see that in this case the Booking Response EDI 990 Chain.io file type does have additional settings. The settings "Additional References" and "Make Optional Fields Required" are both from that file type. They would be the only settings to show up if you used that file type as the source file type instead of the Stedi ED 990 type.

 

 

Flow Execution

Below is an example flow invocation for a flow that outputs EDI as well as expects and receives a 997 acknowledgement. . All of the intermediate and transmitted files are attached to the flow execution. This should make debugging issues far easier than it currently is.

Things to note:

  1. Acknowledged Date: The date and time the final 997 required was received and the status was changed to "success". If the 997 never comes, then it will display the Acknowledgement Expired date and time, which is the when the status was changed to "logical_fail"
  2. Data tags of the 997 messages received. Useful if you need to discuss the 997 with partner that sent it (and received EDI)
  3. Data tags will be published for each Group and Interchange Control number generated. (There can be more than one if multiple files are published for each). Useful for diagnosing issues with the partner the EDI was sent to.
  4. The original JSON input file will be added to the execution.
  5. The intermediate file generated when the mapping has been applied to the input file. This is what was passed into the guide.
  6. EDI output that will be sent to destination.
  7. The files containing any 997 Acks received.
  8. There are detailed logs explaining each step of the transformation process, along with any errors that may have occurred. Additionally messages will be recorded whenever an ack has been received as well as when all required 997s have been received, or a 997 times out.

For more information see Stedi EDI Integration - How it works

 



Related articles

Powered by Zendesk