Agreeing What Your ERP Integration Must Do. Define shared data meanings, timing and ownership before mapping fields.
Two systems can exchange a message successfully and still disagree about what happened. One may report a quantity in cases while the other interprets it as individual units. One may call an order “accepted” when it has merely entered a queue; another may treat that status as permission to ship.
Before agreeing field mappings, write the operating agreement behind the interface. Define the business event, the meaning of important values, who is authoritative, when information must arrive, and how the parties establish that the intended work is complete.
This business-language interface contract gives process owners something they can review and technical teams something precise to implement. It also gives support teams the context they will need when a message is late, contradictory, or only partly processed.
Start with the event and its consequence
Describe one business event in a sentence: “When the warehouse confirms a shipment, the receiving process records the dispatched quantities against the correct order lines.” Identify what has already happened, what should happen next, and which role owns the complete outcome.
Define the event boundary carefully. Picking, packing, dispatching, carrier acceptance, and customer delivery can be different events. A convenient field name should not collapse them into one meaning unless that is the approved operating design.
Specify whether the message reports a fact, requests an action, or provides a current snapshot. These forms need different handling. A report that ten units were shipped describes an event. An instruction to ship ten units asks another process to create one. A snapshot saying that ten units have shipped in total may replace an earlier summary rather than add another ten.
Ask the business owner what should happen if the event is delayed or missing. That answer helps establish the interface's importance and the fallback process. Technical priority should reflect the operating consequence, not simply how frequently the interface runs.
Build a shared definition for every consequential value
Focus first on fields that affect identification, quantity, money, timing, status, and control decisions. For each, record its business definition, allowed values, unit or currency where relevant, source, effective-date behavior, and treatment when missing or unknown.
An identifier needs a scope. A customer account, delivery site, legal entity, and contact may each have different identifiers even when users casually call them “customer.” State which entity the field refers to and how the receiving process resolves it. Include what happens when the reference is new, inactive, or ambiguous.
Dates need meaning as well as format. Distinguish event time, entry time, requested date, posting date, and effective date. Agree on time zones and calendar interpretation where relevant. A date-only field may be appropriate for one purpose and inadequate for another.
Units need a conversion rule and evidence. If a case contains multiple individual units, identify which conversion applies and whether that relationship can change over time. A technically valid conversion using today's master data may misrepresent an older event if the pack definition changed.
Define empty values deliberately. Missing, unknown, not applicable, and zero may carry different meanings. If the target substitutes a default, the contract should state the default's meaning, where it is allowed, and how users can detect that it was applied.
Assign authority where updates can conflict
For each consequential data element or transaction state, identify the authoritative source and the process permitted to change it. An interface connecting two systems does not automatically establish which one should win when they disagree.
Authority can vary by attribute or lifecycle stage. One process may own an order request before acceptance, while another controls fulfillment status afterward. Document the handoff and the rule for late changes. Avoid allowing two teams to overwrite each other's valid updates through separate interfaces.
State how corrections work. Does the originator send a replacement, a reversal, an adjustment, or a new version? How does the recipient link the correction to the original event? Which changes require business approval, and how are downstream consequences assessed?
A timestamp alone may not settle a conflict. The latest arrival can contain older business information, and clocks or update paths may differ. Technical designers should select an appropriate conflict and ordering mechanism, while business owners define which outcome is correct.
Specify freshness and completeness in operating terms
“Real time” leaves several questions unresolved. Identify the event that starts the timing expectation, the point at which the receiver must be able to use the information, and the operating consequence if that expectation is missed.
Some processes need a fresh status before committing the next action. Others can tolerate a scheduled batch if its cutoff, completeness, and exception handling are clear. The appropriate timing follows the process, and the technical team must verify that the chosen design can support it under expected conditions.
Define completeness at the appropriate level. A message may contain one line, a complete document, or a batch of documents. The receiving process needs to know whether more information is expected and what it may do with a partial set. Otherwise, the first successful delivery can be mistaken for the whole business event.
Include the reconciliation period and owner. Even when individual acknowledgments exist, the business may need a way to compare what should have crossed the boundary with what was actually accepted and completed.
A hypothetical shipment reveals the semantic gap
Consider a hypothetical distributor sending shipment confirmations from a warehouse process into its order-management process. The warehouse reports that two cases of an item were dispatched. Each case contains twelve individual units for this shipment, so the intended dispatched quantity is twenty-four units.
The original mapping connects a field named “quantity” to another field with the same name. The target expects individual units and records two. The message is well formed, delivered, and accepted, yet the order remains open for a quantity that has already left the warehouse.
The interface contract resolves the ambiguity by defining the quantity basis, the applicable conversion reference, the shipment and order-line identifiers, and the event meaning. It also specifies how the receiving process checks that the conversion is valid for the item and event being reported. The numbers are illustrative and do not describe a product capability.
A second test changes the situation: the message is accepted into a queue but processing fails because the target cannot resolve the delivery site. The contract distinguishes receipt of the message from successful business application. The exception is assigned to a named resolver, and the order process does not treat the shipment update as complete merely because transport succeeded.
A third test introduces a correction after the original shipment confirmation. The business owners decide how the correction should affect dispatched and remaining quantities, and the technical team verifies the implemented behavior. The contract records the result so support staff do not have to invent a rule during an incident.
Make acknowledgments describe what is known
Define the states the sender and receiver can establish: received, validated, accepted for processing, applied to the business record, rejected, or awaiting resolution. Use only states the architecture can genuinely support and define the evidence for each.
A technical success response may confirm receipt without proving that the business action completed. Where processing continues asynchronously, specify how the final outcome becomes visible and who checks overdue or unresolved work. The exact mechanism depends on the interface design.
For failures, distinguish a known rejection from an unknown outcome. If the connection breaks after the receiving system may have applied the transaction, blindly resending can create a duplicate effect. The recovery contract should explain how to establish the outcome and when a retry is demonstrably safe.
Keep this part connected to the incident runbook. The business-language contract defines the intended behavior and authority; the runbook provides the operational steps for the implemented architecture. Both should be reviewed together when behavior changes.
Turn the contract into a reviewable record
For each interface, maintain an operating record containing:
- Business event, purpose, population, and end-to-end owner
- Source and destination responsibilities
- Important field meanings, identifiers, units, dates, and statuses
- Authority, correction, and effective-date rules
- Freshness, completeness, and ordering expectations
- Acknowledgment states and evidence of business completion
- Exception ownership, safe recovery conditions, and reconciliation
- Access and data-minimization requirements reviewed by the appropriate owners
- Version, compatibility decisions, acceptance scenarios, and support contacts
Keep this record connected to the detailed technical specification. Neither should become an independent truth. When a mapping changes, assess whether it also changes business meaning, exception handling, or evidence available to the receiving process.
The implementation should transmit only the information needed for the authorized purpose. Technical and security owners should verify access, protection, and logging against the actual design. Avoid placing unnecessary sensitive content in messages or diagnostic records simply because the interface can carry it.
Test disagreements deliberately
A useful acceptance set includes a normal event and cases that challenge meaning: an unfamiliar identifier, an unexpected unit, an inactive reference, a late event, a partial document, a correction, and a repeated submission. Add the high-consequence exceptions specific to the process.
For each test, compare the business outcome with the contract, rather than checking only that the payload arrived. Have the sender's process owner, receiver's process owner, and technical owner review disagreements together. A mismatch between their interpretations is a design issue worth resolving before production.
For an immediate improvement, take one active interface and ask both sides to explain the same five fields independently. Compare their answers about identity, quantity, date, status, and correction. Any difference is a concrete starting point for the contract. The most valuable integration discussion often begins where familiar field names conceal different operating assumptions.
