Discovery is a deliverable, not a meeting

An integration discovery phase is often described as a conversation, which is why it so frequently produces nothing durable. A conversation leaves two parties with two different recollections of what was agreed, and those recollections diverge further every week until acceptance testing, at which point somebody has to pay for the gap. Discovery should instead be understood as a production task with a tangible output: a pack of documents, written down, dated, and specific enough that a different engineer could pick them up and build from them without re-interviewing anybody.

The practical test is straightforward. If your integrator left the project tomorrow, could their replacement read what was produced and begin work? If the answer is no, discovery did not happen. What happened was a scoping call, and the quotation that followed it is an estimate resting on memory. That is the point at which fixed-scope work quietly becomes time-and-materials work, regardless of what the paperwork says.

This article sets out what should be in the pack, field by field and artefact by artefact. It is written for the operations or finance manager who is being asked to approve a discovery document and is not certain what good looks like. You do not need to read code to review it. You do need to be able to tell the difference between a document that records facts and one that records intentions.

The deliverables an integration discovery phase should hand over

A complete discovery pack is smaller than people expect and more specific than they are comfortable with. It is not a forty-page methodology document. It is typically fifteen to thirty pages of tables, sample data and explicit decisions, and the value sits almost entirely in the tables. Each item below should exist as its own named artefact, not as a paragraph buried in a proposal.

Where a document in the pack says "to be confirmed", that is acceptable, provided each outstanding item carries an owner and a date. Where it says "as required" or "standard mapping", that is not acceptable; those phrases are placeholders for work nobody has yet done, and they will surface during acceptance testing as change requests.

  • Field-level data dictionary — Every field that moves, with its source name, target name, data type, length constraints, whether it is mandatory, and the transformation rule applied. One row per field, per direction.
  • Sample payload library — Real anonymised records pulled from the live systems, not invented examples. A standard order, a discounted order, a multi-line order, a refund, a cancellation, a foreign-currency order and at least one record that is known to be malformed.
  • Volumetrics and timing — Daily and peak-day record counts, the hours during which they arrive, and the batch sizes involved. This governs whether the design polls, listens for webhooks, or queues.
  • Failure catalogue — A list of the ways each step can fail, what the system should do in each case, and who is notified. Retries, dead-lettering, partial completion and duplicate suppression all belong here.
  • Access and credentials register — Which accounts, API keys, sandbox environments and VPN routes are needed, who owns each, and whether they currently exist. Missing access is the most common cause of a stalled start date.
  • Acceptance criteria — The specific tests that will be run at the end of the build, with expected results, agreed before any code is written.
  • Explicit out-of-scope list — The things discussed and deliberately excluded. This protects both parties and is usually the most-read page in the document six months later.

Field-level mapping is where discovery earns its fee

The data dictionary is the heart of the pack, and it is where superficial discovery is most easily exposed. Consider a common requirement: orders from Shopify posting into Sage 200 as sales invoices. At a summary level this is four or five concepts — customer, order lines, totals, tax, payment. At field level it is routinely eighty to a hundred and twenty mappings, and the interesting ones are never the obvious ones.

Shopify holds a customer email as the practical unique identifier, while Sage 200 expects a customer account reference with its own length and character constraints. The pack must state the rule: do guest checkouts post to a single generic cash-sale account, or does each new email generate a new customer record? If the latter, who decides the account reference format, and what happens when two customers share a surname and the derived code collides? A discovery document that answers this in one sentence has saved a fortnight. One that says "map customers across" has saved nothing.

The same applies to tax. The pack should name the exact tax codes in use, show which Shopify tax line maps to which Sage 200 code, and state what the integration does when it encounters a combination it does not recognise — reject the order, post it to a holding code, or halt the run. Each of those is a legitimate choice, and finance should be the one making it, not the developer at two o'clock on a Thursday afternoon.

Where a warehouse is involved, the mapping widens again. If Peoplevox is handling fulfilment, discovery must establish whether the despatch confirmation carries the carrier reference, whether partial despatches generate one confirmation or several, and whether the stock figure the storefront displays comes from the warehouse or the ERP. Two systems both claiming to hold stock truth is the single most expensive ambiguity to discover after go-live.

Volumetrics, timing and the failure catalogue

Volume changes architecture. A business posting two hundred orders a day and a business posting twelve thousand on a Black Friday peak need materially different designs, and the cost difference is not marginal. Discovery should produce actual figures taken from the systems rather than estimates offered in a meeting: orders per day over the last twelve months, the single busiest day, the distribution across the working day, and the average number of lines per order. If the business sells through Amazon Seller as well, settlement file sizes and reporting cadence belong in the same table, because a monthly settlement import has a completely different profile from a rolling order feed.

Timing requirements need to be stated as numbers rather than adjectives. "Near real time" means nothing in a specification. "Order appears in the ERP within fifteen minutes of payment capture, measured at the ninety-fifth percentile" is testable, and it tells the engineer whether a five-minute poll is sufficient or whether webhooks and a queue are required. The business should set this figure, because it is a commercial decision about how long the warehouse can wait, not a technical one.

The failure catalogue is the artefact most often omitted, and the one that most reliably predicts how the first month of live running will go. For each step in the flow, it should record what happens when the target system is unavailable, when a record is rejected for validation, when the same record arrives twice, and when a batch completes halfway. The answers may be simple — retry three times with increasing delay, then park the record and email the operations inbox — but they must be written down and agreed, because each one implies code that somebody has to pay for.

This catalogue also defines who looks after the integration once it is live. A parked record is only useful if a named person checks the queue each morning and knows what to do with its contents. Discovery is the correct time to decide whether that person sits in your finance team or ours, and to establish what the handover documentation must therefore explain.

How to review the pack before you sign

You can audit a discovery document without technical knowledge by reading it for specificity. Search for the vague phrases: "standard", "as appropriate", "usual", "etc". Each occurrence is an unresolved decision. Then check that every sample payload in the pack is traceable to a real record you could find in your own system today — invented examples mean the engineer has not yet connected to anything and is working from documentation rather than from your data, which is a materially different level of confidence.

Next, take three awkward real-world cases from your own operation and look for them by name in the document. A refund issued against an order from the previous financial year. An order containing a gift card. A customer who changed their delivery address after despatch was raised. If discovery has been done properly, each of those appears either in the data dictionary with a rule, or in the out-of-scope list with a reason. If they appear nowhere, they will appear later as change requests.

Finally, confirm that the acceptance criteria were written during discovery rather than promised for later. The acceptance tests are the definition of done; agreeing them before the build is what makes a fixed scope meaningful. If the estimate arrives before the tests, the estimate is covering an undefined quantity of work, and the contingency in it is either being paid by you or absorbed as risk by the supplier — neither of which produces a calm project.

A discovery that holds up in production has a particular feel to it. It is unglamorous, heavily tabular, occasionally tedious to read, and it contains decisions you had not realised were yours to make. That discomfort is the point. The alternative is a short, agreeable document, a confident estimate, and a difficult conversation in week six.

What happens to the pack after go-live

The discovery pack is not a project artefact to be filed and forgotten once the build is accepted. It becomes the first section of the handover documentation, and it remains the reference point for every subsequent change. When Shopify alters an API version, when Sage 200 is upgraded, or when a new sales channel is added eighteen months from now, the data dictionary tells whoever picks the work up exactly what is already mapped and why particular decisions were taken.

For that reason the pack should be written to be read by someone who was not in the room. Decisions should carry their rationale in a sentence, not merely their outcome. "Guest checkouts post to account CASH01 because finance reconciles these against the card provider statement rather than by customer" is worth considerably more in two years' time than "guest checkouts post to CASH01".

Code and documentation are handed over on completion, and the discovery pack is the part of that handover a non-technical manager can actually use. It is also what protects a business from being tied to a single supplier. Ownership of the integration rests with whoever holds the written description of how it works. That should be you.

Key points

  • Discovery is measured by its artefacts, not its duration: a field-level data dictionary, a library of real sample payloads, volumetrics, a failure catalogue, an access register and written acceptance criteria.
  • Vague phrasing such as "standard mapping" or "as appropriate" marks a decision nobody has made yet, and those decisions resurface as change requests during acceptance testing.
  • Test a discovery pack by looking for three awkward cases from your own operation; each should appear either with a mapping rule or on the explicit out-of-scope list.