EDI Integrations (850/856/997)

Electronic Data Interchange (EDI) is a standardized format for exchanging business documents between trading partners. Rather than sending human-readable CSVs or JSON, EDI uses a compact, segment-based format that has been the backbone of supply chain communication for decades. The SureDone Automation Engine has built-in support for parsing EDI documents and generating acknowledgments.

Supported EDI Specifications

The Automation Engine currently supports three EDI transaction sets:

How EDI Parsing Works

EDI documents use a specific structure with two types of delimiters:

• Element separator (*): Separates individual data elements within a segment
• Segment terminator (~): Marks the end of a segment

A typical EDI line looks like this:

PO1*1*3*EA*29.95**BP*WIDGET-001*VP*WIDGET-001~

This is a PO1 (line item) segment containing:

• Line item number: 1
• Quantity: 3
• Unit of measure: EA (each)
• Unit price: 29.95
• Buyer's part number: WIDGET-001
• Vendor's part number: WIDGET-001

The Automation Engine parses each segment by splitting on * and indexes elements by their position (e.g., PO101 is the first element of the PO1 segment, PO102 is the second, and so on). These parsed values are then mapped through your field_map and processed like any other automation.

EDI Configuration Options

EDI-specific settings live in your file_configs:

ISA Control Numbers

EDI documents require unique control numbers at three levels: ISA (interchange), GS (functional group), and ST (transaction set). The Automation Engine tracks these automatically per sender/receiver pair and increments them with each transaction. These are available in your templates as:

• {{edi_isa}} -- Interchange control number
• {{edi_gs}} -- Group control number
• {{edi_st}} -- Transaction set control number

EDI 850: Purchase Orders (Export)

The 850 spec is used to send purchase orders to vendors. This is typically an order export automation that takes orders from SureDone and formats them as EDI documents using a Twig template.

Example Configuration

{
  "name": "EDI 850 - Purchase Orders",
  "vendor": "Vendor Corp",
  "active": true,
  "schedule": "*/15 * * * *",
  "type": "orders",
  "action": "export",
  "connection": {
    "type": "sftp",
    "address": "sftp.vendor.com",
    "username": "{{sftp_user}}",
    "password": "{{sftp_pass}}",
    "path": "/inbound/850/",
    "port": 22
  },
  "file_configs": [
    {
      "search": "status:=READY",
      "edi_spec": "850",
      "edi_sender_id": "SUREDONE",
      "edi_receiver_id": "VENDORCORP",
      "template": "ISA*00*          *00*          *23*{{ data['edi_sender_id'] }}       *01*{{ data['edi_receiver_id'] }}     *...",
      "order_update_export": {
        "status": "PENDING"
      }
    }
  ]
}

Key points:

• The search filter finds orders with status "READY" for export.
• The template generates the EDI 850 document using Twig syntax, with access to all order data and EDI control numbers.
• After successful export, order_update_export updates the order status to "PENDING" so it is not exported again.

EDI 856: Advance Ship Notices (Import)

The 856 spec is used to receive shipment tracking from vendors. When a vendor ships your order, they send an 856 document containing tracking numbers, carrier codes, and shipment dates.

Example Configuration

{
  "name": "EDI 856 - Ship Notices",
  "vendor": "Vendor Corp",
  "active": true,
  "schedule": "0 * * * *",
  "type": "orders",
  "action": "import",
  "connection": {
    "type": "sdsftp",
    "user_id": "10001",
    "path": "import/orders/856"
  },
  "file_configs": [
    {
      "regex": "/.*/",
      "edi_spec": "856",
      "edi_sender_id": "SUREDONE",
      "edi_receiver_id": "VENDORCORP",
      "edi_export_path": "export/orders/997",
      "template": "... 997 acknowledgment template ...",
      "value_map": {
        "UPSN": "UPS",
        "FDCC": "FEDEX",
        "USPS": "USPS"
      },
      "delete_remote_file": true
    }
  ]
}

SCAC Carrier Codes

EDI 856 documents use SCAC (Standard Carrier Alpha Code) codes to identify carriers. The engine includes a built-in SCAC code lookup table that maps common codes to carrier names. You can supplement or override these mappings using value_map:

"value_map": {
  "UPSN": "UPS",
  "FDCC": "FEDEX",
  "FXNL": "FedEx Ground"
}

The engine checks your value_map first, then falls back to the built-in SCAC lookup table if no match is found.

Automatic 997 Acknowledgment

When processing an 856 document, the engine can automatically generate and send a 997 Functional Acknowledgment back to the vendor. This confirms that you received and successfully processed the ship notice.

To enable this:

1. Set edi_export_path to the directory where acknowledgments should be sent.
2. Provide a template with the 997 format.

The acknowledgment includes result data from the 856 parsing:

• {{edi_result}} -- "success" or "error"
• {{edi_gs06}} -- The GS06 value from the received document (for reference)
• {{edi_st02}} -- The ST02 value from the received document (for reference)

EDI 997: Functional Acknowledgment (Import)

The 997 is a receipt confirmation. When you send an 850 to a vendor, they send back a 997 acknowledging they received it. Importing the 997 updates the order status based on the acknowledgment result.

Example Configuration

{
  "name": "EDI 997 - Acknowledgments",
  "vendor": "Vendor Corp",
  "active": true,
  "schedule": "0 * * * *",
  "type": "orders",
  "action": "import",
  "connection": {
    "type": "sdsftp",
    "user_id": "10001",
    "path": "import/orders/997"
  },
  "file_configs": [
    {
      "regex": "/.*/",
      "edi_spec": "997",
      "edi_sender_id": "SUREDONE",
      "edi_receiver_id": "VENDORCORP",
      "delete_remote_file": true
    }
  ]
}

When a 997 document is received acknowledging a Purchase Order (AK101 = "PO"), the engine looks up the original order using the GS and transaction set control numbers from the 997, and sets the order status to ORDERED.

EDI Locking

EDI operations require sequential control number generation. To prevent duplicate control numbers when multiple automations run simultaneously, the engine acquires a database lock per sender/receiver pair. If a lock cannot be obtained (because another EDI automation for the same trading partner is running), the automation is automatically requeued and will retry shortly.