Systems integration checklist: planning the failures

A dependable integration plans around what goes wrong. Decide which system owns each field, how an item is identified, what happens when a message arrives twice or fails, who is told, and who owns the connection once it is live. This checklist covers each of those.

What is a systems integration?

A systems integration is an arrangement that moves information between two or more systems, so somebody enters each fact once and it then travels. It depends less on software than on agreement: which system owns which field, when information moves, and what to do when a move does not succeed.

Most integration disappointment comes from planning only the path where everything works. That path is the easy part, and it is what a demonstration shows you. The hours go into the rest: a field arriving empty, the same message arriving twice, a system refusing a write, a connection quietly expiring. Plan those and the join lasts. Skip them and it works for a month.

There are three ways to connect systems, and the choice matters less than the planning does.

A built-in connector: Offered by one of the systems. Quickest to set up, limited to what the supplier decided, and it fails in whatever way the supplier chose.
A middleware service: A service that sits between systems and moves information on rules you configure. Good for common joins; you depend on another supplier.
A custom integration: Written for your join. The logic and the error handling are yours, and so is the upkeep.

Systems of record and access

Start by naming the owner of each field. Two systems holding the same field will eventually disagree, and without a stated winner nobody can resolve it. Then confirm access before scoping anything, because permission is the item most often discovered late.

Each field being moved has one named system of record.
Where two systems hold a field, the direction of travel is written down.
An account with the right permission exists in each system, and you know who controls it.
Any credential has a stated owner and a note of when it expires.
The limits on how often each system will accept a request are known and recorded.
Somebody has confirmed that each system offers an interface for other software to use.

The last item sounds obvious and is the usual reason a project stops. A system with no interface for other software cannot be joined, however much everyone would like it to be, and that is a constraint to hear early.

Field mapping and validation

Map every field explicitly, with its valid values and what to do with an invalid one. A mapping that lists field names and no rules is a list of future surprises.

Name and type: The field in each system, and what kind of value it holds. A date stored as text in one system and a date in the other is a defect waiting to happen.
Required or optional: Which fields must be present for a transfer to proceed, and which may be empty without consequence.
Valid values: The accepted range or list, including how a currency, a date or a phone-style field is formatted on each side.
Invalid handling: What happens to a value that fails the rule: set it aside, write a default, or stop and ask a person. Decide per field.
Trimming and case: Whether spacing and capitalisation are normalised before comparison, which is where duplicate customers usually come from.

What is idempotency, and why does it matter?

Idempotency means you can repeat an operation as often as you like without changing the outcome. It matters because messages really do arrive twice: networks retry a delivery, people submit the same form again, and somebody reruns a job that failed halfway through. Without it, every repeat creates a duplicate.

The mechanism is simple. Give each item a stable identifier that both systems can agree on, and make every write look for that identifier before creating anything. If it exists, update it. If it does not, create it. Said that way it sounds obvious, and it is still the single most common omission in an integration built at speed.

Each item being moved carries a stable identifier both systems can match on.
Every write checks for that identifier before it creates a record.
A repeated message updates the existing record rather than adding a second.
Records that look like duplicates but are not have a documented way to be told apart.
A merge procedure exists for the duplicates that get through, and somebody owns it.

When something fails: alerts, recovery and replay

Decide how a failure becomes visible, and to whom, before the build. A connection that fails loudly is a small problem. One that fails quietly is the reason people distrust integrations.

Each kind of failure has a class: retry automatically, set aside, or alert a person at once.
Automatic retries have a limit and a widening gap between attempts, so a struggling system is not overwhelmed.
Items that cannot be processed are held somewhere with the reason they failed.
Held items can be run again once the cause is fixed, without being re-entered by hand.
Alerts go to a named person, not to a shared address nobody watches.
Somebody can tell, on any given day, whether the connection ran and what it moved.

Ownership and documentation after launch

An integration needs an owner inside the business, and documentation short enough that somebody will actually read it. Both take little effort at the end of a build and a great deal to reconstruct a year later.

One named person owns the connection and is told when it fails.
A written note says what moves, in which direction, and when.
The credentials and their expiry dates are recorded where the owner can find them.
The manual fallback is written down, so work continues while the join is down.
A review date is set to check that the connection is still doing what it was built for.

Write the integration contract first

Write the agreement down before building. It fits on two pages and it settles the arguments that otherwise surface after launch.

Every field being moved, with its system of record and direction of travel.
What triggers a transfer, and how often it may run.
Valid values for each field, and the handling for an invalid one.
The identifier used to recognise a repeated item.
The failure classes, who is alerted, and how long items are kept for replay.
Who owns the connection after launch, and the date of the first review.

Common mistakes

Four mistakes account for most integration regret, and each has a plain correction.

Building only the happy path: The demonstration works and the live system does not. Write the failure handling into the scope before the build starts.
Leaving ownership unstated: Two systems both believing they own a field produces data nobody trusts. Name one owner per field, in writing.
Trusting that messages arrive once: They do not. Give each item an identifier and check for it before every write, so a repeat updates instead of duplicating.
Sending alerts nowhere: An alert to a shared address nobody watches is the same as no alert. Send it to a named person who is answerable for it.

References

Two public references carry the engineering part of this guide, both opened and read on Thursday, October 8, 2026. The project on API security describes the failure modes that matter when systems talk to each other, including what happens when a connection trusts input it should have checked (the project).

For the build itself, the secure software development framework published by NIST sets out practices a buyer can hold a builder to, including how changes are reviewed before they reach a live system (the framework).

If you are not yet sure that connecting systems is the right move, the systems decision framework sets out the four options. If the question is whether to replace a tool instead, read custom software or an off-the-shelf tool. If the join is meant to remove repeat work once it is in place, the AI automation readiness guide covers the checks for that.

Systems integration is the service that covers this work. The same team at Mavrin Labs writes the agreement and builds the connection, so the people who set the rules are the people who answer for them. A connection planned this way gives hours back to the staff who were re-keying records, without replacing the systems they already rely on.

Frequently asked questions

What is a system of record and why does it matter?

A system of record is the one place that holds the truth about a given piece of information, such as a customer's address or the status of an order. It matters because two systems holding the same field will eventually disagree, and without a stated winner every later question becomes an argument. Name the owner for each field before anyone writes a mapping. That single decision prevents most of the data mess people blame on integrations.

Why do integrations create duplicate records?

Duplicates appear when a message arrives more than once and nothing recognises the repeat. Networks retry, people submit forms twice, and somebody reruns a job that failed halfway. The fix is to give each item a stable identifier and to make every write check for that identifier first, so a repeated message updates the existing record instead of creating a second one. Engineers call that property idempotency, and designing it in takes far less work than cleaning up after it.

How will I know when an integration stops working?

You will know only if somebody is told, which means alerting has to be part of the build rather than an addition. Decide which failures raise an alert, where the alert goes, and who is responsible for acting on it. Silent failure is the expensive case: records stop moving, staff assume the system handled it, and the gap is discovered weeks later by a customer. A connection that fails loudly is a minor inconvenience.

What should happen to a message that cannot be processed?

A message that cannot be processed should be set aside rather than discarded, with enough detail to understand why it failed and to run it again once the cause is fixed. Keeping those items in one place turns a mystery into a short list somebody can work through. Discarding them means the only record of the loss is the gap it leaves, and nobody finds that gap until it matters.

Do I need a middleware service or a custom integration?

A middleware service suits common joins between popular systems, where somebody has already solved the mapping and you are configuring rather than building. A custom integration suits joins where the logic is yours, where a system has no ready connector, or where you need the error handling to behave a particular way. Start with the ready-made option and move on when it will not do what you need, rather than before.

What should the written agreement cover before building?

The written agreement should name every field being moved, which system owns each one, what triggers a transfer, what counts as a valid value, what happens to an invalid one, who is alerted on failure, how long items are kept for replay, and who owns the connection after launch. Agreeing that first turns most integration arguments into a reference check, because the awkward questions have already been answered in writing.

Who writes these guides

Mavrin Labs delivers client work as a team in mixed roles, led by our founder. The people who write these guides are the people who build the systems described in them, and every page is reviewed before it is published.

Which hours would you take back first?

Send Mavrin Labs one workflow that is costing you the most time, and the reply comes back by email from the people who would build the fix.

Start a conversation

The integration checklist: planning past the happy path