What is an integration runbook?

An integration runbook is the operating guide for a connected business process. It tells the next person what the integration does, how to recognize a problem and who can decide what happens next. A useful runbook also explains recovery boundaries, so your investigation does not repeat a business action by accident.

Use HP Tuners as a running example. Its published flow moves new WooCommerce orders into NetSuite, sends cash refunds entered in NetSuite back to WooCommerce each night and pushes available stock to WooCommerce by SKU each day. The map explains how the fields in those flows line up. The runbook explains what someone should do when a refund was entered in NetSuite but cannot be found in WooCommerce the next morning.

A runbook and a build document

A build document describes implementation. A runbook helps someone operate the result. The reader may be an on-call engineer, an internal systems owner or the integration provider's support team.

They need a useful starting point before they understand every implementation detail. Name the source, destination, expected timing and responsible team. Identify the process in terms the business recognizes.

For the HP Tuners example, the description should make clear which WooCommerce order statuses move into NetSuite. Otherwise someone might investigate an order that was never eligible to move.

Define normal before describing failure

Write down what a healthy process looks like. That might include the expected schedule, the records eligible for movement and the evidence available after a run.

Use business expectations rather than a generic green status. A workflow can execute without moving an order if the order did not meet the agreed conditions.

Record dependencies too. If a destination needs an existing customer or item, the operator should know how that relationship is established. A missing prerequisite calls for a different response from an unavailable application.

For timing, distinguish when the source made the record available from when the integration should process it. That prevents an upstream delay from being silently assigned to the connection.

Give the investigation a starting record

The runbook should say which identifier someone needs when reporting a problem. For a missing refund, start with the NetSuite refund reference, the night it should have moved and the WooCommerce account.

Then describe the evidence the operator can inspect: the source record, the integration activity and any known destination record. Avoid copying private customer data into a general troubleshooting document.

The useful question is where the expected sequence stopped. Was the order eligible? Was a destination request attempted? Is the result known? Each answer narrows the next action.

Our NetSuite readiness checklist shows why business conditions and missing inputs deserve attention before launch. A runbook carries those decisions into the work after launch.

Make recovery a deliberate decision

A button that starts a workflow again does not establish whether starting it again is safe. The runbook needs to explain how the team checks whether the original action already happened.

An order may have reached the destination even if the confirmation did not return. Repeating the create operation without checking can produce a duplicate business record.

State who is allowed to decide on a replay or correction. Describe the supporting evidence and the cases that require a business owner. Keep the operational instruction aligned with the integration's actual behavior.

If recovery is not yet defined for a particular failure, say so. A visible gap gives the team something to resolve. A confident but untested instruction gives the next operator a new problem.

Separate authority from notification

The person who receives a problem report may not be the person who can approve a financial correction. Record both responsibilities.

For example, the integration team may investigate whether an order was created while the business decides how to handle a posting-date correction. The runbook should get the question to the right owner without implying that technical access provides business authority.

Include an escalation path for an unavailable owner. Keep contact information current in the appropriate internal system rather than embed a private address in public documentation.

Test the document with another person

Give a teammate a safe example and the runbook. Ask them to identify the affected process, find the relevant evidence and explain the next permitted step.

The test should not require them to make an actual production change. Its purpose is to reveal assumptions in the document. If they need the original implementer to translate every sentence, the handover is incomplete.

Review the runbook after an accepted integration change. A new destination, schedule or recovery rule can make an old operating instruction wrong.

Pick the flow your team gets asked about most. Write its normal state and its first investigation step, then hand the draft to someone who did not build it.

Talk to us