Canonical Generalized Feedback Implementation Guide and Specifications

Modified on Tue, May 26 at 9:28 AM

ECGrid Simplify

Canonical Generalized Feedback Format Specification

Version: 1.0 Date: May 26, 2026 Owner: ECGrid Product

1. Purpose

This document defines the canonical Generalized Feedback format used by ECGrid Simplify. It is the single source of truth for generalized feedback structure, field definitions, data types, length limits, required fields, and serialization rules across XML and JSON.

The Generalized Feedback (997 / Functional Acknowledgment) document provides acknowledgment of EDI transaction set receipt and processing status. It confirms that documents (POs, ASNs, invoices, etc.) have been received and processed by the recipient system. Both XML and JSON representations convey the same logical feedback. A JSON Schema (Simplify_Generalized_Feedback.schema.json) provides machine-enforceable validation. This document is the human-readable companion.

2. Scope

In scope:

Generalized feedback document structure and core fields.
Field-level definitions, data types, length limits, and validation rules.
Canonical XML and JSON representations.
Trading partner identification and sender/receiver routing.
Document reference and shipment tracking information.

Out of scope:

Transport (HTTPS, AS2, SFTP). Covered in ECGrid Simplify API docs.
Detailed error reporting and rejection codes (covered in separate error specification).
Batch processing and multi-transaction acknowledgment logic.

3. Document Structure

A Generalized Feedback payload contains a single feedback message. The message provides EDI transaction acknowledgment with routing information, document references, and optional shipment/logistics details.

Top-level shape:

generalizedFeedbackMessage

└── generalizedFeedback (required, exactly one)

├── tradingPartnerID

├── documentId

├── sender / senderQualifier

├── receiver / receiverQualifier

├── vendorID

├── shipmentId / bookingDate

└── reservationCode

4. Core Fields

The generalized feedback message contains trading partner routing information and document acknowledgment details.

Field	Type	Length	Req	Description	Example
tradingPartnerID	string	1–35	Yes	ECGrid trading partner identifier. Routes the document.	SEV2TEST01
documentId	string	1–35	Yes	Unique identifier for this feedback document.	FB-2026-05-001
userId	string	1–35	No	User ID of the system processing the feedback.	USER123
sender	string	2–17	Yes	Sender ID in the qualifier namespace (recipient of original transaction).	SEV2TEST02
senderQualifier	string	1–4	Yes	Qualifier for sender ID (e.g. SE, ZZ, 01, 14).	SE
receiver	string	2–17	Yes	Receiver ID in the qualifier namespace (sender of original transaction).	SEV2TEST01
receiverQualifier	string	1–4	Yes	Qualifier for receiver ID.	SE
groupSender	string	1–9	No	EDI functional group sender ID.	1
groupReceiver	string	1–9	No	EDI functional group receiver ID.	1
vendorID	string	1–35	No	Vendor/supplier identifier (if feedback relates to vendor transaction).	VEND12345
scac	string	2–4	No	Standard Carrier Alpha Code (if feedback relates to transportation).	SAIA
shipmentId	string	1–35	No	Shipment identifier being acknowledged.	SHIP-2026-05-001
bookingDate	string	8	No	Booking or reservation date. YYYYMMDD.	20260526
reservationCode	string	1–35	No	Reservation or confirmation code for reference.	RES-2026-05-ABC

5. Field Semantics and Business Rules

5.1 Routing Fields

The Sender and Receiver fields indicate the direction of the feedback relative to the original transaction. Importantly, these are reversed from the original transaction: the Sender of the feedback is the Receiver of the original transaction, and vice versa.

Example:
Original PO: Sender=Buyer, Receiver=Supplier
PO Feedback: Sender=Supplier (acknowledging receipt), Receiver=Buyer (original sender)

5.2 Qualifier Codes

Common qualifier codes for identifying trading partners:

SE – Swedish or Sweden identifier
ZZ – Mutually defined (custom, proprietary)
01 – DUNS (Dun & Bradstreet number)
14 – DUNS+4
92 – Assigned by buyer

5.3 Optional Logistics Fields

Fields like shipmentId, scac, bookingDate, and reservationCode are optional and provided when the feedback relates to shipment tracking or transportation logistics. These fields enable end-to-end supply chain visibility.

6. Naming Conventions

XML: PascalCase for all element names (e.g. GeneralizedFeedback, TradingPartnerID, ShipmentId).
JSON: camelCase for all field names (e.g. generalizedFeedback, tradingPartnerID, shipmentId).
Field semantics and length limits are identical across both. Only casing differs.
Empty optional values in XML use self-closing tags (e.g. <VendorID/>). In JSON, use empty string or null.

7. Usage Scenarios

7.1 PO Acknowledgment Feedback

Scenario: Buyer sends a PO to Supplier. Supplier receives and processes the PO, and sends generalized feedback to confirm receipt.

Trading Partners: Original Sender (Buyer) → Original Receiver (Supplier); Feedback Sender (Supplier) → Feedback Receiver (Buyer)
Fields Used: tradingPartnerID, documentId, sender, receiver, vendorID

7.2 Invoice Acknowledgment Feedback

Scenario: Supplier sends an invoice to Buyer. Buyer receives and processes the invoice, and sends feedback confirmation.

Fields Used: tradingPartnerID, documentId, sender, receiver

7.3 Shipment Tracking Feedback

Scenario: Carrier/supplier communicates shipment status with optional booking or reservation details.

Fields Used: tradingPartnerID, documentId, sender, receiver, scac, shipmentId, bookingDate, reservationCode

8. XML Example

Example 1: PO Acknowledgment Feedback

Example 2: Shipment Acknowledgment Feedback with Tracking

9. JSON Example

Example 1: PO Acknowledgment Feedback

{
"generalizedFeedbackMessage": {
"generalizedFeedback": {
"tradingPartnerID": "SEV2TEST01",
"documentId": "FB-2026-05-001",
"senderQualifier": "SE",
"sender": "SEV2TEST01",
"receiverQualifier": "SE",
"receiver": "SEV2TEST02",
"vendorID": "VEND12345"
}
}
}

Example 2: Shipment Acknowledgment Feedback with Tracking

{
"generalizedFeedbackMessage": {
"generalizedFeedback": {
"tradingPartnerID": "SEV2TEST01",
"documentId": "FB-2026-05-ASN-001",
"senderQualifier": "SE",
"sender": "SEV2TEST01",
"receiverQualifier": "SE",
"receiver": "SEV2TEST02",
"scac": "SAIA",
"shipmentId": "SHIP-2026-05-001",
"bookingDate": "20260526",
"reservationCode": "RES-2026-05-ABC"
}
}
}

10. Implementation Notes

10.1 Async Communication

Generalized Feedback is typically sent asynchronously after processing the original transaction. The feedback document should be sent as soon as processing is complete, whether successful or with errors.

10.2 Correlation

Implementers should correlate feedback with original transactions using tradingPartnerID and documentId. Additional context from vendorID or shipmentId may help with transaction matching.

10.3 Routing Inversion

Remember that sender and receiver are reversed in feedback compared to the original transaction. The party receiving the original document sends the feedback back to the party that originated it.

10.4 Optional Fields

Fields like SCAC, shipmentId, bookingDate, and reservationCode are optional. Include them only when the feedback relates to shipment tracking or logistics operations. Omit them for document receipt acknowledgments.