What belongs in an integration mapping specification?

An integration mapping specification is the written agreement for how information in one system becomes information in another. It identifies the source field, the destination field and the rule connecting them. A useful specification also explains missing values, exceptions and how your team will check the result.

Think of an order moving from an online store into an accounting system. Both systems may have a field called Customer. That does not establish whether the order should use an existing account, create a new one or stop because a match is unclear. The specification records that decision before the workflow has to make it.

A field map and a process diagram

A process diagram shows the handoff: an order reaches an agreed status and moves to accounting. A field map describes the information needed to make that handoff valid.

Use the diagram to explain the sequence and the map to review the rules. A small process can have a short map. A complicated destination record may need a longer one even if the diagram is a single arrow.

The goal is a document the business and the integration team can both inspect. A spreadsheet is sufficient if it records the decisions clearly and stays aligned with the running work.

Start with the record identity

For the order example, record the source order identifier and the destination's corresponding identifier. State how the integration recognizes an order it has already handled.

Then identify the account and environment. A field called Customer ID is ambiguous if the reader cannot tell which application supplies it. The same identifier can mean different things in a test account and a production account.

Include the business event that permits the record to move. An unconfirmed order and an accepted order may contain similar fields but have different meanings for the destination.

Write the rule, not just the pair

A useful mapping entry might say that the source's customer reference is looked up against an approved external identifier in the destination. If exactly one customer matches, use that record. If none or several match, stop for review under the agreed process.

That is an illustrative rule. Your business may choose a different one. The important part is that the decision is explicit enough to test.

For dates, state the timezone and whether the value represents an instant or a business date. For amounts, state the currency and rounding rule. For a blank field, explain whether blank means unknown, clear the destination value or leave the existing value alone.

Those distinctions keep an apparently simple map from becoming a series of guesses during implementation.

Include the line items

An order header can be correct while its lines are wrong. Specify how items are recognized and how quantities, discounts and taxes should be represented.

If the source and destination organize the information differently, describe the transformation. Combining lines or expanding a source item into several destination lines changes how the result should be checked.

Our published NetSuite readiness checklist shows the cases that belong here. In one project the products needed four or five option dimensions and the destination store allowed three, so someone had to decide how each item would be represented. In another, NetSuite items were missing their unit of measure and a team member cleared the errors by hand for hours every week. The field map is where decisions like those become reviewable instructions for the particular flow.

Keep the failure decision beside the rule

For every important lookup or conversion, record what happens when the expected value is missing. Do not leave that behavior to whichever person happens to encounter the first exception.

In the customer example, a missing match might require a business owner to confirm the account. The specification should name the decision and the route for that review. It should also establish whether the rest of the order can proceed.

This is how the document helps after launch. The support team can compare an unexpected result with the rule the business accepted.

Test with recognizable examples

Use a normal order, a missing customer reference and an order containing an item the destination cannot yet recognize. Add business-specific cases the team already knows require special treatment.

For each, record the expected destination result or the expected stop. A test passes when the record means what the business intended. An accepted request alone does not prove that.

Keep the specification with the integration's operating information. Update it when an accepted change alters the mapping. An old map can be more misleading than no map if everyone assumes it still describes production.

Start the specification with your next order flow. Write the identity rule and one missing-value decision, then review both with the person who owns the records.

Talk to us