A statement of work for business systems integration usually lists the interfaces to be built, the systems on each end, the tools to be used and the date of go-live. It rarely lists the thing that decides whether the integration is still working in a year: a document that lets a person who did not build it understand it, watch it and fix it.
We call that document a run book, and we treat it as the deliverable. The interfaces are what the project builds. The run book is what the business keeps.
An integration is built once, by someone who knows why every field is mapped the way it is. Then that person moves on, to another project, another job, another company. The integration keeps running, and for a while nothing happens. Then a credential expires, a vendor changes a field name, or a volume threshold is crossed, and the integration stops or, worse, keeps running and does the wrong thing.
The person who inherits it is handed a tool with a set of flows and no account of why they exist. The reasoning was in the builder's head. This is the same failure we described in why automation projects stall on tribal knowledge, applied to the layer that connects everything else.
A run book is short. Each interface gets about one page, and a company with eight interfaces has an eight-page document, which a new administrator can read in an afternoon. It holds seven things.
Purpose and owner. Why the interface exists, in one sentence a non-technical person would accept, and the named person responsible for it in your business.
Direction and keys. Which system sends, which receives, and which field identifies the same record on both ends. If the key is a name and not an identifier, say so, because that is where duplicates come from.
The field map. What moves, in what shape, and what is deliberately left behind. The decision about which system owns each value is the one made in system of record against source of truth, and the run book records the outcome.
Schedule and triggers. When it runs, what starts it, how long it normally takes.
Failure behavior. What happens to a record that is rejected, a record that arrives twice, and a run that does not finish. Where the failed ones are listed, who looks, and how to replay one safely.
Access. Which account the integration uses, who holds it, when it expires and how it is renewed. Never the credential itself.
Change log. The last several changes, who made them and why, and a name to ask.
None of this is difficult to write. It is difficult to write at the end of a project when everyone is tired, which is why it belongs in the scope and the acceptance test rather than in the goodwill of the builder.
A document is only useful if it works for someone other than its author. The test is simple, and a buyer can run it before accepting the work.
Pick one interface. Give the run book to a person who did not build it, someone in your business or a colleague from another team. Ask the builder to cause one failure, such as a record rejected for a missing field. Then ask the new person to find the failed record, say why it failed, fix the cause and replay it, using only the run book.
If they do it in under an hour, the run book is real. If they need to ask the builder at any step, the step is missing from the document, and the builder fixes the document, not the person. Two or three of these tests, on different interfaces, will show where the gaps are.
The builder writes the first draft while the integration is still fresh, because that is when the reasons are remembered. The business owner then reads it and marks every sentence they do not understand. Those marks are the useful part, because each one is a place where the next administrator would have been stuck.
Keep it where the people who run the systems already look, not in a project folder that closes when the project does. Add a line to the change log whenever a flow is edited, even for a small fix. A run book that is correct on go-live day and stale six months later is only slightly better than none, because it is trusted and wrong.
The cost of skipping the run book does not appear on the project. It appears later, in three forms.
The first is time to recover. When something breaks and nobody knows how the integration works, the first hours go on rediscovering it, with the business waiting.
The second is fear of change. A flow nobody understands is a flow nobody dares touch, so the business works around it. A manual step grows beside the integration, then another, and the integration is soon carrying a smaller part of the work than anyone thinks.
The third is dependence. If the builder is the only person who can fix it, they have a hold on the business that neither side intended. Better for both if the knowledge is on paper.
Imagine a company whose order system and accounting system were connected by a contractor two years ago. The flow pushes each shipped order to accounting as an invoice draft. It runs every night.
One Tuesday the access token the flow uses expires. Nothing alerts, because the flow reports failure only to a mailbox that the contractor set up and nobody reads. For eleven nights, about thirty shipments a night do not reach accounting. The month-end close finds three hundred and thirty missing invoices, worth a good deal of revenue that has not been billed.
With a run book, three entries would have changed this. The access entry would have said the token expires every ninety days and who renews it. The failure entry would have said where failures are listed and that a person looks each morning. The owner entry would have named the person in your business who answers for it. The token still expires, but the gap is one night, not eleven.
List your integrations, and for each one write down whether a run book exists and when it was last read by someone who did not write it. Choose the one with the highest cost of failure, usually the one that touches money or customer orders, and run the replay test on it this month. You will learn more from that single hour than from any review of the tooling.
We write the run book as part of every integration we build, and the acceptance test includes the replay. We start with a no-risk discovery: we read your current integrations, write the missing run book pages for the ones that matter most, and show you where the gaps are, and you pay for the discovery only if you go on. A build comes with a guaranteed estimate, so if we estimate low, we absorb the difference. After go-live, Managed Technical Operations keeps the run book current and the failure lists watched.
An integration that only its builder can run is not finished.
In a no-risk discovery we look at your CRM, finance and operations systems and who owns each part, and show what a connected system would do differently. You pay only if you proceed. Or see how we approach it.
More on the same problem:
"Something isn't working." "We're outgrowing our tools." "We're afraid to make the wrong move." No-Risk Discovery is a short, practical conversation that gets you clarity before you commit to anything big. We'll tell you if we're a fit. If we're not, we'll tell you that too.
Say who you are and ask. A person replies within one business day.
