EDI Tasks

Overview

This document describes the tasks available for parsing, creating, and managing EDI (Electronic Data Interchange) files within the CargoXplorer TMS System. These tasks support various EDI transaction sets including 204, 214, 216, 856, 861, and 990.

YAML Structure

EDI tasks follow a consistent structure that allows for flexible configuration of EDI processing operations.

Attribute Description

EDI/Parse

The EDI/Parse task converts raw EDI data into structured JSON format for further processing.

task: "EDI/Parse@1"
name: parseEDI
inputs:
  ediData: "ISA*00*          *00*          *ZZ*ABCDEFGH      *ZZ*123456789      *210101*1030*U*00401*000000001*0*P*>\nGS*SH*ABCDEFGH*123456789*20210101*1030*1*X*004010\nST*856*0001\n..."
  transactionSet: "856" # Optional - Specific transaction set to parse
  validateSchema: true # Optional - Validate against EDI schema
  preserveWhitespace: false # Optional - Preserve whitespace in element data
outputs:
  - name: "parsedData"
    mapping: "result"
  - name: "transactionType"
    mapping: "transactionType"

Attribute Details:

Input Parameter	Description
`ediData`	Raw EDI data string to be parsed
`transactionSet`	Specific EDI transaction set to parse (e.g., 856, 214)
`validateSchema`	Whether to validate the EDI data against its schema
`preserveWhitespace`	Whether to preserve whitespace in element data

Output:

{
  "parsedData": {
    "interchangeHeader": {...},
    "functionalGroups": [...],
    "segments": [...],
    "transactionSets": [...]
  },
  "transactionType": "856"
}

EDI/Generate

The EDI/Generate task creates EDI files from structured data.

task: "EDI/Generate@1"
name: generateEDI
inputs:
  data:
    {
      "header":
        {
          "senderId": "ABCDEFGH",
          "receiverId": "123456789",
          "controlNumber": "000000001",
        },
      "shipment": { "billOfLadingNumber": "BOL12345", "shipDate": "20230515" },
    }
  transactionSet: "856" # Required - Transaction set to generate
  template: "standard" # Optional - Template name to use
  options:
    segmentTerminator: "~"
    elementSeparator: "*"
    subElementSeparator: ">"
    lineEnding: "\n"
outputs:
  - name: "ediString"
    mapping: "ediString"
  - name: "controlNumbers"
    mapping: "controlNumbers"

Attribute Details:

Input Parameter	Description
`data`	Structured data to convert to EDI format
`transactionSet`	EDI transaction set to generate
`template`	Named template to use for generation
`options.segmentTerminator`	Character used to terminate segments
`options.elementSeparator`	Character used to separate elements
`options.subElementSeparator`	Character used to separate sub-elements
`options.lineEnding`	Line ending character sequence

Output:

{
  "ediString": "ISA*00*          *00*          *ZZ*ABCDEFGH      *ZZ*123456789      *230515*1030*U*00401*000000001*0*P*>\nGS*SH*ABCDEFGH*123456789*20230515*1030*1*X*004010\nST*856*0001\n...",
  "controlNumbers": {
    "interchangeControlNumber": "000000001",
    "groupControlNumber": "1",
    "transactionSetControlNumber": "0001"
  }
}

EDI/Validate

The EDI/Validate task validates EDI data against standard schemas or custom validation rules.

task: "EDI/Validate@1"
name: validateEDI
inputs:
  ediData: "ISA*00*          *00*          *ZZ*ABCDEFGH      *ZZ*123456789      *210101*1030*U*00401*000000001*0*P*>\nGS*SH*ABCDEFGH*123456789*20210101*1030*1*X*004010\nST*856*0001\n..."
  transactionSet: "856" # Required - Transaction set to validate
  customRules:
    [
      {
        "segment": "REF",
        "element": "REF01",
        "rule": "required",
        "message": "Reference qualifier is required",
      },
    ]
  strictMode: true # Optional - Fail on any validation error
outputs:
  - name: "isValid"
    mapping: "isValid"
  - name: "validationErrors"
    mapping: "errors"

Attribute Details:

Input Parameter	Description
`ediData`	Raw EDI data string to validate
`transactionSet`	EDI transaction set to validate against
`customRules`	Array of custom validation rules
`strictMode`	Whether to fail on any validation error

Output:

{
  "isValid": false,
  "validationErrors": [
    {
      "segment": "REF",
      "position": 12,
      "element": "REF01",
      "message": "Reference qualifier is required",
      "severity": "error"
    }
  ]
}

EDI/Transform

The EDI/Transform task converts between different EDI formats or maps EDI data to custom formats.

task: "EDI/Transform@1"
name: transformEDI
inputs:
  sourceData:
    {
      "interchangeHeader": { ... },
      "functionalGroups": [...],
      "segments": [...],
      "transactionSets": [...],
    }
  sourceFormat: "X12" # Required - Source EDI format
  targetFormat: "EDIFACT" # Required - Target EDI format
  mappingTemplate: "x12ToEdifact856" # Optional - Named mapping template
  customMapping:
    {
      "sourceField": "targetField",
      "sourceSegment.element": "targetSegment.element",
    }
outputs:
  - name: "transformedData"
    mapping: "result"

Attribute Details:

Input Parameter	Description
`sourceData`	Source EDI data (parsed or raw)
`sourceFormat`	Source EDI format (X12, EDIFACT, etc.)
`targetFormat`	Target EDI format
`mappingTemplate`	Named template for transformation
`customMapping`	Custom field mapping rules

Output:

{
  "transformedData": {
    "raw": "UNB+UNOA:1+SENDER+RECEIVER+230515:1030+1+++++1'\nUNH+1+DESADV:D:96A:UN'\n...",
    "structured": {
      "interchangeHeader": {...},
      "messages": [...]
    }
  }
}

EDI/ExtractData

The EDI/ExtractData task extracts specific data elements from EDI documents.

task: "EDI/ExtractData@1"
name: extractEDIData
inputs:
  ediData: "ISA*00*          *00*          *ZZ*ABCDEFGH      *ZZ*123456789      *210101*1030*U*00401*000000001*0*P*>\nGS*SH*ABCDEFGH*123456789*20210101*1030*1*X*004010\nST*856*0001\n..."
  extractionRules:
    [
      { "path": "ST-856/HL-S/TD1/TD101", "name": "packagingCode" },
      { "path": "ST-856/HL-S/TD1/TD102", "name": "ladingQuantity" },
      {
        "path": "ST-856/HL-S/REF[REF01=BM]/REF02",
        "name": "billOfLadingNumber",
      },
    ]
outputs:
  - name: "extractedData"
    mapping: "data"

Attribute Details:

Input Parameter	Description
`ediData`	Raw EDI data string to extract from
`extractionRules`	Array of rules defining what data to extract

Output:

{
  "extractedData": {
    "packagingCode": "PLT",
    "ladingQuantity": "10",
    "billOfLadingNumber": "BOL12345"
  }
}

EDI/Acknowledge

The EDI/Acknowledge task generates functional acknowledgments (997/999) for received EDI documents.

task: "EDI/Acknowledge@1"
name: acknowledgeEDI
inputs:
  ediData: "ISA*00*          *00*          *ZZ*ABCDEFGH      *ZZ*123456789      *210101*1030*U*00401*000000001*0*P*>\nGS*SH*ABCDEFGH*123456789*20210101*1030*1*X*004010\nST*856*0001\n..."
  acknowledgmentType: "997" # Required - 997 or 999
  status: "A" # Optional - A (Accepted), P (Partially Accepted), R (Rejected)
  errors:
    [
      {
        "segment": "N1",
        "position": 15,
        "code": "7",
        "description": "Missing required segment",
      },
    ]
  options:
    swapIds: true # Swap sender/receiver IDs
    useOriginalControlNumbers: false
outputs:
  - name: "acknowledgment"
    mapping: "ediString"

Attribute Details:

Input Parameter	Description
`ediData`	Original EDI data to acknowledge
`acknowledgmentType`	Type of acknowledgment to generate (997 or 999)
`status`	Overall acknowledgment status
`errors`	Array of errors to include in acknowledgment
`options.swapIds`	Whether to swap sender/receiver IDs
`options.useOriginalControlNumbers`	Whether to reference original control numbers

Output:

{
  "acknowledgment": "ISA*00*          *00*          *ZZ*123456789      *ZZ*ABCDEFGH      *210101*1030*U*00401*000000002*0*P*>\nGS*FA*123456789*ABCDEFGH*20210101*1030*2*X*004010\nST*997*0001\n..."
}

EDI/BatchProcess

The EDI/BatchProcess task processes multiple EDI files in a single operation.

task: "EDI/BatchProcess@1"
name: batchProcessEDI
inputs:
  files:
    [
      {
        "name": "order1.edi",
        "content": "ISA*00*...",
        "transactionSet": "850",
      },
      {
        "name": "shipment1.edi",
        "content": "ISA*00*...",
        "transactionSet": "856",
      },
    ]
  operation: "parse" # Required - Operation to perform (parse, validate, transform)
  options:
    continueOnError: true
    groupByTransactionSet: true
outputs:
  - name: "results"
    mapping: "results"
  - name: "summary"
    mapping: "summary"

Attribute Details:

Input Parameter	Description
`files`	Array of EDI files to process
`operation`	Operation to perform on each file
`options.continueOnError`	Whether to continue processing after errors
`options.groupByTransactionSet`	Whether to group results by transaction set

Output:

{
  "results": [
    {
      "fileName": "order1.edi",
      "transactionSet": "850",
      "success": true,
      "data": {...}
    },
    {
      "fileName": "shipment1.edi",
      "transactionSet": "856",
      "success": true,
      "data": {...}
    }
  ],
  "summary": {
    "total": 2,
    "successful": 2,
    "failed": 0,
    "byTransactionSet": {
      "850": 1,
      "856": 1
    }
  }
}

Examples

Parsing an EDI 856 Shipment Notice

task: "EDI/Parse@1"
name: parseShipmentNotice
inputs:
  ediData: "{{ workflow.input.ediContent }}"
  transactionSet: "856"
  validateSchema: true
outputs:
  - name: "shipmentData"
    mapping: "result"
  - name: "transactionType"
    mapping: "transactionType"

Generating an EDI 214 Shipment Status Message

task: "EDI/Generate@1"
name: generateStatusUpdate
inputs:
  data:
    {
      "header":
        {
          "senderId": "{{ company.ediId }}",
          "receiverId": "{{ partner.ediId }}",
          "controlNumber": "{{ sequence.ediControl }}",
        },
      "statusDetails":
        {
          "shipmentId": "{{ shipment.id }}",
          "statusCode": "AG",
          "statusDescription": "Delivered",
          "statusDate": "{{ formatDate shipment.deliveryDate 'YYYYMMDD' }}",
          "statusTime": "{{ formatDate shipment.deliveryTime 'HHmm' }}",
        },
    }
  transactionSet: "214"
  template: "standardDelivery"
outputs:
  - name: "ediMessage"
    mapping: "ediString"
  - name: "controlInfo"
    mapping: "controlNumbers"

Creating and Validating an EDI 204 Motor Carrier Load Tender

task: "EDI/Generate@1"
name: generateLoadTender
inputs:
  data: "{{ shipment }}"
  transactionSet: "204"
  template: "carrierLoadTender"
outputs:
  - name: "ediTender"
    mapping: "ediString"

task: "EDI/Validate@1"
name: validateLoadTender
inputs:
  ediData: "{{ generateLoadTender.ediTender }}"
  transactionSet: "204"
  strictMode: true
outputs:
  - name: "isValid"
    mapping: "isValid"
  - name: "validationErrors"
    mapping: "errors"

Best Practices

Pre-validate Data: Always validate your data structures before generating EDI documents to prevent syntax errors.
Use Templates: Create reusable templates for common EDI transaction sets to ensure consistency.
Implement Error Handling: Set up proper error handling for EDI parsing and validation to gracefully handle malformed documents.
Control Number Management: Implement a robust system for managing EDI control numbers to prevent duplicates.
Logging: Log all EDI transactions for audit and troubleshooting purposes.
Testing: Test EDI documents with trading partners' test systems before moving to production.
Acknowledgments: Always process and respond to acknowledgments (997/999) to ensure successful transmission.

Overview​

YAML Structure​

Attribute Description​

EDI/Parse​

EDI/Generate​

EDI/Validate​

EDI/Transform​

EDI/ExtractData​

EDI/Acknowledge​

EDI/BatchProcess​

Examples​

Parsing an EDI 856 Shipment Notice​

Generating an EDI 214 Shipment Status Message​

Creating and Validating an EDI 204 Motor Carrier Load Tender​

Best Practices​

Related Topics​

Overview

YAML Structure

Attribute Description

EDI/Parse

EDI/Generate

EDI/Validate

EDI/Transform

EDI/ExtractData

EDI/Acknowledge

EDI/BatchProcess

Examples

Parsing an EDI 856 Shipment Notice

Generating an EDI 214 Shipment Status Message

Creating and Validating an EDI 204 Motor Carrier Load Tender

Best Practices

Related Topics