Integration Design: [Programme or solution name]
Complete design for the integrations between a set of applications:
landscape, catalogue of interfaces, a detailed specification per
integration (pattern, trigger, volume, mapping, transformation, error
handling, retries, idempotency, monitoring), canonical data model,
security, service levels, testing and cutover. Patterns are named using
the vocabulary of Enterprise Integration Patterns (Hohpe and Woolf).
Replace every [bracketed] value and every row marked Example.
Worked examples integrate an e-commerce platform with an ERP, a
warehouse system and a CRM.
Document control
| Field | Value |
|---|
| Document ID | [INT-DES-COMMERCE-001] |
| Programme / solution | [Commerce replatforming] |
| Integration platform | [iPaaS / ESB / message broker / custom services] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Integration architect | [@integration-architect] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Related | [Solution architecture], [Data dictionary], [Test plan], [Cutover plan] |
Approvals
| Role | Name | Decision | Date |
|---|
| Integration architect | [@name] | [Approved / Changes requested] | YYYY-MM-DD |
| ERP system owner | [@name] | [Decision] | YYYY-MM-DD |
| Warehouse system owner | [@name] | [Decision] | YYYY-MM-DD |
| Security | [@name] | [Decision] | YYYY-MM-DD |
| Business data owner | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft of catalogue |
| 0.2 | YYYY-MM-DD | [@name] | Example: INT-03 changed from nightly file to near real-time events |
| 1.0 | YYYY-MM-DD | [@name] | Example: Approved for build |
Contents
1. Introduction
1.1 Purpose
[What this document decides. Example: "This document specifies how the new
commerce platform exchanges orders, products, stock and customers with
the ERP, warehouse management system and CRM, and how those exchanges
are monitored and cut over from the legacy platform."]
1.2 Scope
| In scope | Out of scope |
|---|
| Example: Order, product, price, stock, customer and shipment flows | Finance consolidation between ERP instances |
| Example: Migration of open orders at cutover | Historical order migration (separate data migration plan) |
| [Item] | [Item] |
1.3 Constraints and assumptions
- [Example: ERP exposes only SOAP services and nightly file exports; no
event capability before its upgrade in Q4.]
- [Example: Warehouse system processes orders in waves every 15 minutes.]
- [Example: All integrations run on the existing integration platform; no
new middleware licences.]
2. Integration landscape
The landscape below shows the systems and the numbered integrations
(INT-nn) that connect them through the integration platform.
| System | Role | Owner | Technology | Integration capabilities |
|---|
| Commerce platform | Storefront, cart, orders | [@owner] | SaaS | REST API, webhooks |
| ERP | Products, prices, finance | [@owner] | [Product, version] | SOAP services, SFTP files |
| Warehouse management | Picking, packing, shipping | [@owner] | [Product] | REST API, message queue |
| CRM | Customer profiles, marketing consent | [@owner] | SaaS | REST API, bulk API |
| Carrier | Labels, tracking | External | REST API | REST API, webhooks |
3. Integration catalogue
| ID | Name | Source | Target | Pattern(s) | Style | Trigger | Frequency | Volume (peak) | Priority |
|---|
| INT-01 | Product master | ERP | Commerce | File Transfer, Message Translator | Batch | Schedule | Nightly 02:00 | 60 000 products | High |
| INT-02 | Price update | ERP | Commerce | Polling Consumer, Message Translator | Near real-time | Change poll | Every 5 min | 5 000 changes/hour | High |
| INT-03 | Stock level | WMS | Commerce | Event Message, Aggregator | Event | Stock movement | Continuous | 30 events/s | Critical |
| INT-04 | Order export | Commerce | ERP, WMS | Event Message, Recipient List, Message Translator | Event | Order paid | Continuous | 15 orders/s | Critical |
| INT-05 | Shipment confirmation | WMS | Commerce, ERP | Event Message, Publish-Subscribe Channel | Event | Parcel dispatched | Continuous | 12/s | High |
| INT-06 | Carrier label | Integration platform | Carrier | Request-Reply | Synchronous | Pack complete | On demand | 12/s | Critical |
| INT-07 | Customer sync | Commerce | CRM | Event Message, Content Enricher | Event | Account change | Continuous | 3/s | Medium |
| [INT-nn] | [Name] | [Source] | [Target] | [Patterns] | [Style] | [Trigger] | [Frequency] | [Volume] | [Priority] |
4. Integration principles and patterns
4.1 Principles
| ID | Principle | Consequence |
|---|
| IP-01 | Systems are loosely coupled through the integration platform | No point-to-point database links |
| IP-02 | Each data entity has one system of record | Section 6.2 lists the owner of each entity |
| IP-03 | Prefer events for changes, request-reply only when the caller needs the answer now | Stock and orders are events; labels are request-reply |
| IP-04 | Every message is traceable end to end | Correlation ID on every message and log entry |
| IP-05 | Every consumer is idempotent | Duplicates never create duplicate business records |
| IP-06 | Translation to and from the canonical model happens at the edges | Source and target adapters own their mappings |
4.2 Pattern catalogue
| Pattern | Used for | Implementation on this platform |
|---|
| Message Channel | Transport between producer and consumer | Broker topic or queue per flow |
| Publish-Subscribe Channel | One event, several consumers | Topic with one subscription per consumer |
| Event Message | Notify that something happened | CloudEvents-style envelope, canonical payload |
| Request-Reply | Synchronous call needing an answer | HTTPS call with timeout and correlation ID |
| Message Translator | Convert formats and structures | Mapping in adapter, defined in 5.x mapping tables |
| Content Enricher | Add data the source does not send | Lookup to system of record, cached |
| Content-Based Router | Route by message content | Rules on country or order type |
| Recipient List | Send to a computed list of targets | Order export to ERP and WMS |
| Aggregator | Combine related messages | Stock events aggregated per SKU per 10 s window |
| Idempotent Receiver | Ignore duplicates | Deduplication store keyed by message ID |
| Dead Letter Channel | Hold messages that cannot be delivered | Per-flow dead-letter queue |
| Polling Consumer | Read from a source without events | Scheduled query on change timestamp |
| File Transfer | Bulk exchange | SFTP with checksum and control file |
5. Integration specifications
5.1 INT-04 Order export
This integration sends every paid order to the ERP for invoicing and to
the warehouse for fulfilment.
5.1.1 Overview
| Attribute | Value |
|---|
| Purpose | Make paid orders available for fulfilment and invoicing |
| Source / target | Commerce platform to ERP and WMS |
| Patterns | Event Message, Recipient List, Message Translator, Idempotent Receiver, Dead Letter Channel |
| Trigger | Commerce webhook order.paid |
| Frequency and volume | Continuous; 3 orders/s average, 15/s peak; 250 000 per month |
| Message size | 2 to 20 KB |
| Latency target | Order in WMS within 60 s at p95 |
| Ordering | Per order only (key orderId) |
5.1.2 Flow
The sequence shows the happy path and the duplicate case.
5.1.3 Field mapping
| # | Source field (Commerce) | Canonical field | Target field (ERP) | Target field (WMS) | Rule |
|---|
| 1 | id | order.externalId | CustomerPO | reference | Copy |
| 2 | created_at | order.orderedAt | DocDate | orderDate | Convert RFC 3339 UTC to ERP local date YYYYMMDD |
| 3 | customer.id | order.customerRef | SoldTo | not sent | Lookup ERP customer number via cross-reference table XR-01 |
| 4 | line_items[].sku | lines[].sku | Material | sku | Upper case; strip spaces |
| 5 | line_items[].quantity | lines[].quantity | TargetQty | qty | Integer |
| 6 | line_items[].price | lines[].unitPrice | NetPrice | not sent | Decimal string to ERP decimal with 2 places |
| 7 | shipping_address.country_code | shipTo.country | Country | country | ISO 3166-1 alpha-2 unchanged |
| 8 | shipping_lines[0].code | shipping.method | ShipCond | serviceLevel | Value map VM-01 |
| 9 | none | order.salesOrg | SalesOrg | not sent | Constant 1000 for EU web orders |
| [n] | [Source] | [Canonical] | [Target] | [Target] | [Rule] |
Value map VM-01 (shipping method):
| Commerce code | Canonical | ERP ShipCond | WMS serviceLevel |
|---|
standard | STANDARD | 01 | STD |
express | EXPRESS | 02 | EXP |
click_collect | PICKUP | 05 | PCK |
5.1.4 Transformation and validation rules
- Reject (to dead letter) any order whose total does not equal the sum of
lines plus shipping minus discounts, within 0.01.
- Split orders with more than [999] lines because the ERP limit is 999.
- Orders with country outside [EU list] are routed by a Content-Based
Router to the export queue for manual customs handling.
5.1.5 Error handling, retries and idempotency
| Error | Detection | Handling |
|---|
| ERP unavailable or timeout (30 s) | SOAP fault or timeout | Retry 5 times with backoff 1, 2, 4, 8, 16 min, then dead letter and alert |
| ERP business error (unknown material) | SOAP fault code | No retry; dead letter; ticket to product data team |
| WMS 409 Conflict | HTTP status | Treat as success (order already exists) |
| WMS 5xx | HTTP status | Retry as for ERP |
| Duplicate webhook | eventId already stored | Acknowledge, no processing |
Idempotency: the integration stores eventId for 7 days; ERP calls carry
CustomerPO and the ERP rejects duplicates on it; WMS uses reference as
a unique key.
5.1.6 Monitoring
| Metric | Threshold | Action |
|---|
| Orders received versus exported per hour | Difference above 0.5% | Alert integration support |
| End-to-end latency p95 | Above 60 s for 15 min | Alert |
| Dead letter count | Any message | Ticket; above 20 in 1 hour pages on call |
5.2 INT-03 Stock level
| Attribute | Value |
|---|
| Purpose | Keep available stock in the storefront accurate to prevent overselling |
| Patterns | Event Message, Aggregator, Message Translator |
| Trigger | WMS stock movement event |
| Frequency and volume | 30 events/s peak; aggregated to at most one update per SKU every 10 s |
| Mapping | item_code to sku; qty_available - qty_allocated to available |
| Error handling | Retry 3 times; on failure the next aggregate supersedes; nightly full reconciliation file corrects drift |
| Idempotency | Updates are absolute quantities with a sequence number; older sequence numbers are ignored |
| Monitoring | Reconciliation differences above 1% of SKUs raise an alert |
5.3 [INT-nn] [Integration name]
[Repeat the layout of 5.1 (overview, flow, mapping, rules, errors,
monitoring) for each remaining catalogue entry.]
6. Canonical data model
6.1 Canonical entities
The canonical model below is the form messages take inside the
integration platform; adapters translate to and from it.
6.2 Systems of record
| Entity | System of record | Consumers | Key | Cross-reference |
|---|
| Product | ERP | Commerce, WMS | sku | n/a |
| Price | ERP | Commerce | sku + price list | n/a |
| Stock | WMS | Commerce | sku + site | n/a |
| Order | Commerce (until paid), then ERP | ERP, WMS | externalId | XR-02 Commerce ID to ERP order number |
| Customer | Commerce | CRM, ERP | customerRef | XR-01 Commerce ID to ERP customer number |
7. Error handling and operations
| Topic | Standard |
|---|
| Retry policy | Exponential backoff, maximum 5 attempts, then Dead Letter Channel |
| Dead letter handling | Reviewed daily by integration support; resubmission through the platform console with audit trail |
| Correlation | correlationId generated at entry, propagated to every hop and log |
| Logging | Message metadata always; payloads only in non-production or masked |
| Reprocessing | Every flow supports replay from a given time for [7 days] |
| Support model | L1 integration support [hours], L2 platform team, L3 system owners |
| Runbooks | One per integration, linked from the monitoring dashboard |
8. Security
| Integration | Authentication | Transport | Data classification | Notes |
|---|
| INT-04 inbound webhook | HMAC signature with shared secret, rotated 90 days | HTTPS | Personal | Timestamp checked within 5 min |
| INT-04 to ERP | Client certificate | TLS over private link | Personal | Service account with create-order rights only |
| INT-01 file | SSH key per partner | SFTP | Internal | Files encrypted at rest; deleted after 30 days |
| INT-06 carrier | OAuth 2.0 client credentials | HTTPS | Personal (address) | Outbound allow-list |
| [INT-nn] | [Method] | [Transport] | [Class] | [Notes] |
General controls: credentials in the secrets manager; least-privilege
service accounts per integration; platform console access by SSO with
MFA; audit log of resubmissions and mapping changes.
9. Service levels
| ID | Availability | Latency target | Data freshness | Support hours | Measured by |
|---|
| INT-03 | 99.9% | p95 under 30 s | Stock no older than 60 s | 24x7 | Platform metrics |
| INT-04 | 99.9% | p95 under 60 s | n/a | 24x7 | End-to-end tracking |
| INT-01 | 99% of nightly runs complete by 05:00 | n/a | Daily | Business hours | Job monitor |
| [INT-nn] | [Target] | [Target] | [Target] | [Hours] | [Method] |
Overall flow availability for a chain of n independent steps with
availability ai:
Aflow=i=1∏nai For INT-04 with Commerce (99.95%), platform (99.95%) and ERP (99.9%), the
result is about 99.80%, so retries and queuing are needed to meet the
99.9% target.
10. Testing
| Level | Scope | Environment | Exit criterion |
|---|
| Unit | Mappings and transformation rules | Developer / CI | 100% of mapping rows covered by tests |
| Contract | Message schemas and API contracts against each system | CI with mocks | All contracts pass |
| System integration | End-to-end flows across real test systems | SIT | All catalogue flows pass happy path and listed error cases |
| Performance | Peak volume plus 50% | Performance environment | Latency targets met; no message loss |
| Resilience | Target outage, duplicate and out-of-order messages | SIT | Recovery without data loss or duplicates |
| User acceptance | Business scenarios across systems | UAT | Sign-off by process owners |
| Test case | Integration | Scenario | Expected result |
|---|
| TC-INT04-01 | INT-04 | Example: Paid order with 3 lines, standard shipping | ERP and WMS orders created within 60 s; values match mapping |
| TC-INT04-05 | INT-04 | Example: Same webhook delivered twice | One order in each target |
| TC-INT04-07 | INT-04 | Example: ERP down for 20 minutes | Orders delivered after recovery in order |
| [TC-nn] | [INT] | [Scenario] | [Result] |
11. Cutover and transition
| Step | Activity | Owner | Timing | Verification |
|---|
| 1 | Freeze mapping and configuration changes | Integration lead | T-7 days | Change freeze notice |
| 2 | Load product, price and customer masters (INT-01, INT-07 bulk) | Data team | T-3 days | Counts and checksums match |
| 3 | Run legacy and new stock flows in parallel, compare | Integration team | T-3 to T-1 | Difference under 0.1% |
| 4 | Stop legacy order export; drain queues | Integration team | T-0 22:00 | Queue depth zero |
| 5 | Migrate open orders | Data team | T-0 22:30 | Count reconciled |
| 6 | Enable new INT-04 and INT-05 | Integration team | T-0 23:30 | Test order end to end |
| 7 | Go / no-go decision | Cutover manager | T-0 23:45 | Criteria below |
| 8 | Hypercare with extended monitoring | All | T+1 to T+14 days | Daily reconciliation report |
Go / no-go criteria: all critical integrations pass smoke tests; no open
severity 1 or 2 defects; reconciliation within tolerance. Rollback:
re-enable the legacy export and replay orders captured since step 6 from
the integration platform store.
12. Appendices
12.1 Glossary
| Term | Meaning |
|---|
| Canonical data model | Shared message format used inside the integration platform |
| System of record | The system whose value of a data item is authoritative |
| Cross-reference table | Mapping of identifiers between systems |
| Hypercare | Period of increased support after go-live |
| [Term] | [Meaning] |
12.2 References
| Reference | Use |
|---|
| Hohpe, G. and Woolf, B., Enterprise Integration Patterns, Addison-Wesley, 2003 | Pattern names in sections 3 to 5 |
| [System API documentation] | Interface details |
| [Data dictionary] | Field definitions |
Standard and licence note
Based on common industry practice for integration design. Pattern names
follow the vocabulary of Gregor Hohpe and Bobby Woolf, Enterprise
Integration Patterns: Designing, Building, and Deploying Messaging
Solutions (Addison-Wesley, 2003); only the pattern names are used, and
no text or diagrams from the book are reproduced. Original text written
for this collection. Template licence: MIT.