Why integrations fail in the second year

Almost every integration we are asked to rescue was working when it was handed over. That is the part people find hard to believe, and it is the most important fact about the problem: the failure is not in the build. It is in the eighteen months after it.

A working integration is a set of assumptions about two systems. Every one of those assumptions has an expiry date, and they expire quietly.

1. The upstream system adds a field, or changes what an existing one means. Nothing errors; the data is simply wrong now.
2. Someone changes a process. A step that used to happen before invoicing now happens after, and the integration is still ordering the world the old way.
3. The person who understood it leaves. The integration keeps running, and nobody left can say what it is supposed to do.

Not more testing at handover. The tests pass at handover. That is the whole problem. What helps is making the assumptions visible and checkable while the system is running.

• Reconcile, do not trust. A daily count on both sides, compared, with somebody's name against the mismatch.
• Fail loudly on the unexpected. An unknown value should stop the row and raise it, not be coerced into the nearest known one.
• Write down what the integration believes. Not how it works — what it assumes is true about the other system.

That sentence is not an excuse. It is a design brief. If the business will move, and it will, the integration has to be built to notice.