Site notes and runbooks
Two things travel with an alert so that whoever is paged doesn’t start from nothing:
- A site note is a fact about your environment, kept on a device, a zone, a location (a hall, a floor) or the whole organisation: “Hall B APs are in metal cages: expect weak 6 GHz”, “IDF-3 is locked after 18:00, security ext. 4411 has the key”. A note applies to everything under what it is on.
- A runbook is what to do when one alert rule fires: short steps or a link, kept on the rule.
Both go out with alert notifications (except recoveries in email and Jira) and show in the Alerts page’s problem drawer. You add and change them through Claude; there is no dashboard form for either.
How do I add a note?
Section titled “How do I add a note?”Tell Claude what you know, for example “Note on AP-17 that it reboots when
the kitchen is busy; it’s being replaced this week, so let the note expire in 7
days.” Claude uses the notes functions:
| Function | What it does | Role |
|---|---|---|
notes.list | Notes, newest first, filtered by target or text; includeExpired adds expired ones | Any |
notes.for_entity | Every note that applies to one entity, nearest first | Any |
notes.add | Add a note to an inventory id, a location id, or org | Operator or above |
notes.update | Change a note’s text or expiry; clearExpiry: true makes it permanent | Operator or above |
notes.remove | Delete a note | Operator or above |
Operators can write notes because the people who handle alerts are the ones who
learn these things. A viewer who asks gets write_blocked. Each note records
its author’s email and when it was changed.
Which notes apply to a device?
Section titled “Which notes apply to a device?”A note applies to what it is on and everything under it. For one device,
notes.for_entity returns, nearest first:
| Via | Notes on |
|---|---|
self | The device itself |
container | What contains it: its AP group, zone, switch (for a port) and so on |
location | The location it is placed in, and the locations above it |
org | The whole organisation |
So a note on the location Hall B shows for every AP placed there. Claude is told to read
a device’s notes before investigating it, and inventory.describe shows them
too. A notification carries up to 10.
What limits apply?
Section titled “What limits apply?”| Limit | Value | At the limit |
|---|---|---|
| Note length | 2,000 characters | Refused by the call’s argument check: text is at most 2,000 characters |
| Notes per target | 50 | <target> already has 50 notes; update or remove one. |
| Notes per organisation | 5,000 | ”The organisation has 5000 notes; remove some first.” |
A note on an id that isn’t in the inventory is refused with No entity …; a note goes on an inventory id (use inventory.find({ text })), a location, or "org".
Can a note expire?
Section titled “Can a note expire?”Yes: give it expiresInDays (0.01 to 3,650) or an expiresAt date, which
must be in the future. An expired note stops showing in notifications and
lookups, and is deleted 30 days after it expired. Until then, includeExpired
lists it. Without an expiry a note is permanent.
How do I add a runbook to a rule?
Section titled “How do I add a runbook to a rule?”Ask Claude to set the rule’s runbook, for example “Add a runbook to
ap-offline: check the switch port’s PoE first, then call facilities on ext.
2200.” It is a field of the rule, up to 4,000 characters, set like any other
with alerts.update_rule or in the rules’ YAML, so it needs the engineer
role or above. On the Alerts page’s Rules tab, a rule with a runbook has a
Runbook line that expands to show it.
Where do they appear?
Section titled “Where do they appear?”In every notification except recoveries, and in the Alerts page’s problem drawer (under Runbook and Notes). Problem, escalation and acknowledgement notifications all carry both.
| Channel | Runbook | Notes |
|---|---|---|
| In full | Each note, with where it is from and who wrote it | |
| Jira | In full, in the issue or comment | As in email |
| Signed JSON webhook | runbook | notes |
| Slack and Microsoft Teams | The first three lines | Not shown |
| PagerDuty | In the alert’s custom details | In the alert’s custom details |
| ServiceNow | In the incident description | In the incident description |
Email and Jira leave both off recoveries. Post-mortems include the runbook and notes too.