A worksheet for the records, owners, access, errors, reconciliation and real-world tests behind a business system integration.
In short
Start by naming the record each system owns and the exact event that should move data. Agree who can access each system, what happens if a transfer fails or its outcome is unclear, how records are reconciled, and the real cases that will prove the integration works.
“Connect these two systems” sounds simple until the same customer, order or payment has different meanings in each one. The useful brief is a record of what moves, when it moves and how people discover that something went wrong.
| Question | Write down |
|---|---|
| Which record? | For example, an order, invoice, customer or stock movement. |
| Which system is the master? | The one system allowed to create or correct the official value. |
| What starts the transfer? | The event that starts it, where the data goes and whether anything comes back. |
| How are records matched? | The values, such as an order number, that identify the same record on both sides. |
| Who controls access? | Who approves logins, test access and changes to either system. |
| What if a transfer fails? | What staff see when a transfer fails or its outcome is unclear. |
| How are mismatches found? | How to find missing, duplicate or disagreeing records (reconciliation), and who fixes them. |
| How will you test it? | Real examples and exceptions that the owners of both systems sign off. |
Do not start with every field in an API. Start with the business record and the decision each system is allowed to make about it.
Networks fail and systems time out. A timeout does not always mean the other system rejected the change; it may have completed the action without returning a confirmation. Agree how to check the remote record before anyone retries a payment, booking or stock update.
Also decide who watches the integration after launch. A dashboard that says “success” is not enough if the numbers in the two systems no longer agree. Run a reconciliation daily or weekly, depending on how much a mismatch costs you.
Say an order platform sends a confirmed order to an accounting system. The order platform owns the order lines; accounting owns the invoice number. Both store the order ID so staff can match them. If the accounting API times out, the team checks whether an invoice already exists for that order before sending it again. A test set includes a normal order, a cancelled order, a duplicate request and a rejected customer record.
We have done this on live systems: consolidating TCE Baby's data for reporting, and linking AWC's loyalty platform to SAP.
Bring the owners of both systems into the discussion. Collect interface documentation if it exists, note contractual or vendor access limits and mark unknown fields clearly. The quotation brief helps turn this worksheet into a scoped project request.
Founder and Managing Director, Antdragon
Rosaan started Antdragon in 2020 to be the team that stays accountable once software goes live, and works with business owners on the systems they rely on every day.
Filed under Connecting systems
Most businesses only fully understand what they need once people start using the software. Why that happens, and how the way you pay for development makes it easier or harder to handle.
Rosaan Ramasamy · · 5 min read
A copyable brief that helps a software team understand users, workflows, priorities, constraints, dependencies and how you will accept the work.
Rosaan Ramasamy · · 2 min read
A checklist for deciding whether to repair a system, replace one part or plan a full rebuild, without committing before the evidence is in.
Rosaan Ramasamy · · 2 min read
