MES ↔ ERP Data Contract Sample (Production Orders, Genealogy, Inventory)

Purpose and Scope

This template defines a clear, versioned data contract for synchronizing production orders (work orders), lot genealogy, and inventory transactions between ERP and MES. It is intended to reduce integration errors, preserve traceability, and provide operational rules for validation, retries, reconciliation, and phased rollouts.

How to use this template

• Adopt the contract fields and types as a starting point.
• Agree on transport, auth, and versioning headers before implementation.
• Use the testing checklist and reconciliation rules during cutover.
• Record contract version in every message header and in your change-control process.

Common Principles

• Single source for authoritative fields: For each domain (order master, bill-of-materials, inventory), identify the authoritative system and list which fields are writable by that system.
• Idempotency: Each message must include an idempotency key to safely retry without duplication.
• Timestamps & timezone: All timestamps use ISO 8601 UTC unless plant-local fields are explicitly required; include both eventTimestamp and sourceTimestamp where useful.
• Versioning: Include contractVersion and schemaVersion in headers. Use semantic versioning and a deprecation policy.
• Validation & error codes: Define machine-readable error codes and human-friendly messages. Distinguish between transient (retryable) and permanent (reject) errors.
• Security: TLS, mutual TLS or OAuth2 as agreed. Sign or hash payloads when regulatory traceability requires it.

Message Patterns & Frequencies

• ERP → MES (master data + orders): Real-time push on create/update for production orders. Optionally bulk nightly sync for full reconciliation.
• MES → ERP (status & consumption): Event-driven status updates (scheduledStart, actualStart, completed) and material consumption transactions in near-real-time. If low-bandwidth, use batched transactions with max latency SLA.
• Genealogy publish: MES publishes lot genealogy at lot completion or shift-end (depending on process). For regulated products, publish immediately when lot is sealed.
• Inventory transactions: Real-time for critical processes (shipping, receiving). Periodic batch for non-critical adjustments with reconciliation.

Sample Schemas (selected fields)

Production Order (Work Order)

Purpose: Create and maintain the execution order in MES. ERP is typically authoritative for planning fields; MES may update execution fields.

• orderId (string) — internal canonical id (required)
• externalOrderId (string) — ERP id
• plantId (string)
• lineId / resourceGroupId (string)
• productId / sku (string)
• quantityPlanned (decimal) — units
• uom (string)
• priority (enum) — {low, normal, high, urgent}
• status (enum) — {created, scheduled, released, in_progress, completed, closed, cancelled}
• scheduledStart (timestamp), scheduledEnd (timestamp)
• actualStart (timestamp), actualEnd (timestamp)
• routingVersion (string), bomVersion (string)
• materialReservations (array) — list of reserved sku/lot and qty
• customAttributes (map)

Lot Genealogy

Purpose: Preserve traceability from raw materials to finished lots.

• lotId (string) — produced lot id
• productId (string)
• parentLotIds (array) — material lot references
• quantityProduced (decimal), uom
• producedOn (timestamp), equipmentId, processStepId
• operatorId (string)
• materialConsumptions (array) — {sku, lotId, qty}
• qualityResults (map) — key/value or reference to report
• traceabilityDocs (array) — links or references to certificates

Inventory Transaction

Purpose: Record receipts, issues, transfers, and adjustments.

• transactionId (string)
• transactionType (enum) — {receive, issue, transfer, adjustment, consumption}
• sku (string), lotId (optional)
• quantity (decimal), uom
• locationId (string), toLocationId (for transfers)
• reasonCode (string) — link to agreed reason catalog
• sourceDocumentRef (string) — e.g., orderId, shipmentId
• timestamp (timestamp)
• sourceSystem (enum) — {ERP, MES}

Error Handling & Retries

Establish deterministic retry and poison message handling:

• On transient error: retry with exponential backoff (e.g., 30s, 2m, 10m), max 5 attempts.
• On persistent validation failure: return a permanent error code and human-readable message; do not retry automatically.
• Poison message policy: after max retries, move to DLQ/Poison queue; notify integrators and create reconciliation event.
• Idempotency: client must supply idempotencyKey so repeated deliveries are safe.

Reconciliation Rules & SLAs

Agree on measurable reconciliation steps:

• SLA for message acknowledgement: ack within 30s for synchronous calls; for async, ack receipt within 5 minutes.
• Reconciliation window: daily automated reconciliation between MES and ERP for orders and inventory, with actionable exceptions surfaced to operations.
• Tolerances: set acceptable numeric tolerances (e.g., inventory count variance <= 0.5% for non-regulated SKUs); exceedances trigger investigation workflow.
• Reconciliation fields: match by SKU+location+lot+timestamp range or by orderId and line.

Example Error Codes

• 1000 — MISSING_REQUIRED_FIELD
• 1001 — INVALID_TIMESTAMP_FORMAT
• 2000 — BUSINESS_RULE_VIOLATION (e.g., reserved quantity insufficient)
• 3000 — CONFLICT (version mismatch)
• 4000 — AUTH_FAILURE

Testing & Acceptance Checklist

1. Agree and freeze schema version for pilot (contractVersion X.Y.Z).
2. Unit test: send valid and invalid sample messages; verify error codes and no silent failures.
3. Integration test: parallel run—MES receives ERP orders while ERP continues to execute; compare results for 48–72 hours.
4. Golden data test: run a contained set of orders through both systems and compare genealogy, inventory balances, and order statuses.
5. Negative tests: malformed payloads, duplicate messages, network failures, and large-volume bursts.
6. Reconciliation test: run daily reconcile and validate exception reports and resolution workflow.
7. Rollback simulation: validate backout steps from shadow mode to original state.

Incremental Rollout & Rollback Rules

• Phased approach: pilot on one plant or product family → extend to similar lines → full roll-out.
• Shadow mode: write messages to the new integration without affecting production state; compare outcomes for a full shift/production cycle.
• Parallel-run mode: allow both systems to record transactions; use reconciliation to ensure parity before cutover.
• Rollback steps: disable writes from the new connector, replay previously queued messages to original system if needed, and run reconciliation to repair state.
• Data migration: if historical data needs migrating, perform a migration plan with staged verification; do not rely on a single bulk migration without verification.

Change Control & Governance

• All contract changes require a change ticket, impact assessment, and a backward-compatibility statement.
• Maintain a deprecation schedule: mark fields deprecated, support them for at least one full release cycle, then remove per agreed date.
• Include contact points for escalation and a runbook for data incidents.

Operational Notes & Quick Start Checklist

• Confirm authoritative owner for each field before development.
• Agree transport (REST webhook, message bus, file drops) and monitoring rules.
• Create a small set of golden test messages (create/update/complete/cancel for orders; receive/issue/adjust for inventory; genealogy sample) and share them with both teams.
• Instrument observability: metrics for message rates, error rates, reconciliation drift, and DLQ counts.

Appendix — Minimal Example Message (Production Order)

{
  "contractVersion": "1.0.0",
  "idempotencyKey": "erp-order-12345-v1",
  "orderId": "WO-000987",
  "externalOrderId": "ERP-12345",
  "plantId": "PLANT-A",
  "productId": "SKU-44-XL",
  "quantityPlanned": 1200,
  "uom": "ea",
  "status": "released",
  "scheduledStart": "2026-08-10T06:00:00Z"
}

Use this template as a starting point. Teams should produce a signed, versioned final contract document that fills in field-level authority, precise enumerations, agreed transport/auth mechanisms, and the pilot rollout plan.

Where to go next

Create a pilot scope document that lists the plant(s), product families, and the reconciliation KPIs. Consider implementing an interactive mapping checklist (see capability notes) to capture agreed-on field mappings and acceptance test results.