# Workflow automation run-book

Template v1 - 2026-10-18 - MiniAI Labs - https://miniailabs.in/resources/templates/
Free to use and adapt for your own projects. A generic template, not a client document.

Write one run-book per workflow. Keep it next to the workflow, in the same repository or folder, and update it in the same change that alters the workflow. Write it for the person who is called when the workflow breaks and has never seen it before.

Never paste passwords, API keys or tokens into this document. Record where each secret is stored and who can rotate it.

## 1. Identity

| Field | Value |
|---|---|
| Workflow name | |
| What it does, in one sentence | |
| Business owner (decides what it should do) | |
| Technical owner (fixes it) | |
| Backup technical owner | |
| Platform (n8n, Make, Zapier, custom code, other) | |
| Where it runs (account, server or region) | |
| Where the workflow definition is versioned | |
| Hours in which failures must be handled | |

## 2. Trigger

- Trigger type: webhook / schedule / polling / queue message / manual
- Source system and event: ____________________
- Normal volume and peak volume: ____________________
- What happens if the trigger fires twice for the same event: ____________________
- Key used to detect duplicates (idempotency key): ____________________

## 3. Systems and credentials

| System | What the workflow does there (read / create / update / delete) | Credential name | Where it is stored | Scopes granted | Owner | Rotation due |
|---|---|---|---|---|---|---|
| | | | | | | |
| | | | | | | |

- [ ] Each credential has the smallest scope that works.
- [ ] Credentials belong to a service account or the organisation, not to one person's login.

## 4. Steps

| # | Step | System | Action | On failure | Retries (how many, how long apart) | Safe to repeat? |
|---|---|---|---|---|---|---|
| 1 | | | | | | Yes / No |
| 2 | | | | | | |
| 3 | | | | | | |

A step marked No under "Safe to repeat?" needs a duplicate check before it runs again (see section 7).
Design notes on retries, duplicates and dead letters: https://miniailabs.in/resources/guides/workflow-automation-reliability/

## 5. AI steps (skip if there are none)

| Step | Model and provider | Instructions stored at | Output checked by (schema, rule or person) | If the check fails |
|---|---|---|---|---|
| | | | | |

- [ ] Model output is validated before it is written to another system.
- [ ] Invalid or low-confidence output goes to a person, not into the record.

## 6. When it fails

- Where failed runs are kept, with their input (error workflow, dead-letter list, queue): ____________________
- Who is alerted, and where (chat channel, email, on-call tool): ____________________
- The alert must contain: workflow name, failed step, error message, a link to the run, and the record it was working on.
- Expected response inside the hours in section 1: ____________________
- Outside those hours: ____________________

## 7. Replaying a failed run

1. Find the failed run and read the error.
2. Fix the cause (bad data, an expired credential, an outside system that was down) before replaying.
3. Check which steps already completed for this record (see "Safe to repeat?").
4. Replay with the same idempotency key, so a step that already succeeded is not repeated.
5. Confirm the result in the target system.
6. Record the incident in the log in section 12.

## 8. Manual fallback

If the workflow is switched off, the work is done by hand like this:

- Who does it: ____________________
- Steps: ____________________
- Where the backlog is listed, so it can be replayed or closed later: ____________________

## 9. Switching it off

- How to pause it without losing incoming events: ____________________
- Who may switch it off: ____________________
- Who must be told while it is off: ____________________

## 10. Known limits

| Limit | Value | Source (vendor page and the date you checked it) |
|---|---|---|
| Rate limit of each connected API | | |
| Platform plan limits (executions, operations, tasks) | | |
| Largest payload the workflow handles | | |

## 11. Monthly health check

- [ ] Failed runs this month reviewed, with their causes recorded.
- [ ] The dead-letter list is empty, or every item in it has an owner.
- [ ] Credentials due for rotation next month identified.
- [ ] Usage checked against plan limits.
- [ ] This run-book still matches the workflow.

## 12. Change and incident log

| Date | Change or incident | By | Run-book updated? |
|---|---|---|---|
| | | | Yes / No |