Connected tools / GUIDE + WORKSHEET
Document an integration so someone else can own it
A practical integration runbook template covering ownership, data flow, failures, recovery, and access without exposing secrets.
THE STARTING POINT
Document the business outcome, data flow, account ownership, monitoring, and safe recovery steps. A useful handover lets a second person identify a failure and decide what to do without the original builder. Keep credentials in the approved secret store, not inside the runbook.
Explain the reason and the boundaries
Start with what the integration does for the business and what it deliberately does not handle. List triggers, source and destination systems, identifiers, field ownership, and assumptions. Include a normal example and an exception. A diagram is helpful only if the labels explain where decisions, transformations, and responsibility change.
Document operation and recovery
Show where to see recent runs, how to identify an event, and how to verify its destination state. State which failures can be retried and which need input correction or human review. Record access owners and the process for rotating credentials without copying their values. Describe how to pause the workflow and what happens to queued work while paused.
Test the handover with another person
Ask someone who did not build the integration to trace a sample event and explain the response to a simulated failure. Note missing access and ambiguous steps. Make the runbook part of future changes: a new field, destination, or retry policy can make old instructions wrong. Assign both a business owner and a technical maintainer.
WORKED EXAMPLE / ILLUSTRATIVE
A fictional billing handover test
A new maintainer can see failed jobs but cannot access the destination to verify them. The test reveals that documentation alone is insufficient; the right access and escalation route must also exist.
| Handover task | Evidence | Gap to close |
|---|---|---|
| Trace event E-42 | Source and workflow logs available | None |
| Confirm destination write | Destination access missing | Grant appropriate read access |
| Decide whether to replay | Repeated-write behavior undocumented | Add recovery rule and test |
MAKE IT USEFUL
Integration runbook
Keep secret values out of this document.
Your notes stay in this page and are not sent to Smithers. Download or copy them before leaving; refreshing clears them.
Before you put it to work
- A second person can trace an event.
- Access ownership is documented.
- Recovery instructions address repeated writes.
- The document changes with the integration.
Do not publish internal system URLs, credentials, or customer information in a public runbook. Use this worksheet privately for your own setup.
IF THIS LOOKS FAMILIAR
Your tools. Your particular mess.
The worksheet is yours to use. If the difficult part is making it work with the systems you already have, that's the kind of thing we help with.