Data Mapping
Part of Designing reliable workflows between business applications
Mapping inputs and outputs before building an integration
Create an input-to-output contract for an integration, including field meaning, missing values, destination results and rejection paths.
Before building an integration, define the input that authorises one action and the output that confirms it, then map the fields needed between them. A small contract exposes missing data, unclear ownership and assumptions while the design can still change.
In this hypothetical example, an order system reports a paid order and a fulfilment system is asked to create a dispatch request. The field names are illustrative. A real mapping must use the selected systems’ documented operations and payloads.
Define one source-to-destination action
Record the source event, destination operation and owner of each endpoint. Specify whether the destination creates a record, updates one or accepts work for later processing.
The input contract should include a stable order reference, eligibility data and required destination values. The output contract should distinguish request acceptance from completion and identify the destination ID to retain. If processing is asynchronous, those are separate milestones.
Define a source-to-destination action contract
- Record the source event, destination operation and endpoint owner
- Specify whether the destination creates, updates or accepts work for later processing
- Define the input contractstable order reference, eligibility data and required destination values
- Define the output contractrequest acceptance, destination ID and later completion status
- If processing is asynchronous, treat acceptance and completion as separate milestones
Build a first-pass field map
| Input or lookup | Meaning to confirm | Outbound use | If unavailable |
|---|---|---|---|
order_id | Stable source order identity | Reference on dispatch request | Stop; do not invent an ID. |
payment_state | Authoritative paid state | Eligibility decision | Look up the source state or route for review. |
delivery_method | Service selected for this order | Agreed destination service code | Route an unsupported value for correction. |
delivery_address | Address valid for this order | Destination address fields | Hold the request until required parts are available. |
For each real row, add the source path, type, example, requiredness, transformation owner and destination field. Check whether the event contains a complete record or only changed fields; the latter may require a source lookup.
Map outputs separately: note the response that confirms acceptance, the destination request ID, any later status that confirms completion, and the lookup available after a timeout. A missing response must not be treated as proof that the destination did nothing.
First-pass field map attributes to capture
- Source path
- Data type
- Example value
- Requiredness
- Transformation owner
- Destination field
- Whether the event contains a complete record or only changed fields
Define rejection rules
Place a safe sample input beside the expected outbound record. Check meaning as well as format: an internal order ID and a customer-facing number may look similar but serve different purposes. A date may represent a calendar day or a timestamp. Agree conversion rules with both system owners.
Mark fields as required, conditionally required or optional. In JSON, a missing property differs from one explicitly set to null; an empty string differs again. Preserve those distinctions unless the destination operation defines how to handle them. A schema can validate structure and types, while business rules decide whether a valid-looking value is appropriate.
For rejected input, specify whether to look up missing source data, hold it for correction or classify it as ineligible. Record the reason and owner. A default that passes validation can still send the wrong instruction.
JSON value states to preserve in rejection rules
- Missing propertyProperty is absent; distinguish it from a property that is present with no value.
- Null valueProperty is present but explicitly set to null; not the same as missing or empty.
- Empty stringProperty is present with an empty string; a third distinct state to preserve unless the destination operation defines how to handle it.
Handling rejected input
- Look up missing source data
- Hold for correction
- Classify as ineligible
- Record the reason and owner
Review the handoff
Ask the source owner when each field becomes available and how it changes. Ask the destination owner which operation and response indicate success, whether a request can be found by source reference, and what duplicate submission would do. For an ordinary input, and for missing, changed or unsupported values, write the expected outbound payload or rejection decision.
The resulting contract can guide a connector configuration or code implementation without making either tool the authority for the data’s business meaning.
Handoff review questions
- Ask the source owner when each field becomes available and how it changes
- Ask the destination owner which operation and response indicate success
- Confirm whether a request can be found by source reference
- Confirm what duplicate submission would do
- Write the expected outbound payload or rejection decision for ordinary, missing, changed and unsupported values
- Keep the data's business meaning with the business owners, not the connector or code tool
