User guide

Last updated 30 September 2026

Runbooks for Confluence and Jira turns a Confluence page into a versioned procedure and runs it as a tracked checklist from a Jira or Jira Service Management work item. A responder starts a run, marks each step done, skipped or failed, and the app records who did what, when, and against which version of the page. When the source page changes, an open run shows that it has drifted and the responder can move it onto the new version. A procedure nobody has run or reviewed within its review interval shows as stale. A Rovo agent can do the same things in conversation.

This guide covers what a site administrator needs to install the app and what an operations user needs to write a runbook and run it. Write to support@apps.sundar.am with any question this guide does not answer.

Installing the app

Confluence is required. Jira, including Jira Service Management, is optional and can be added at install time or later; the app keeps one shared installation across whichever products it runs on, with Confluence holding the data. If only Confluence is installed, the steps macro works fully and the run panel is absent, since there is no Jira work item to carry it.

Installing the app grants it the following permissions, and nothing beyond them:

• Reading Confluence pages and their version history, and searching Confluence for pages that carry the steps macro.
• Checking, for a given page, whether the person asking can read or edit it.
• Reading Jira and Jira Service Management work items, to check permissions and attach a run to its work item. The app writes nothing to Jira or JSM.
• The app's own hosted storage, where every procedure, run and event is kept.
• Reporting stored account identifiers to Atlassian's personal data service, as every app that stores them must.

The app uses paid licensing. While a licence is not active on a site, every part of the app that reads or searches keeps working, including the Rovo agent's own lookups, but every action that writes is refused. Writing controls are hidden and replaced by one message: "This app's licence is not active on this site, so it is read-only. A site administrator can renew it in Manage apps."

Writing a runbook page

A runbook is an ordinary Confluence page with one steps macro inserted on it. The macro is titled "Runbook steps" when you add it, and its configuration editor opens automatically the first time you insert it. The page is the source of truth: every step's instruction, its optional role, precondition and expected outcome, and the review interval all live in the macro's own configuration, which has the page's own edit history.

In the configuration editor, each step has these fields:

• Instruction, required. What the responder must do.
• Role, optional. Who is expected to carry out the step.
• Precondition, optional. What must be true before the step is attempted.
• Expected outcome, optional. What tells the responder the step succeeded.

Use "Add step" to add a step, "Move up" and "Move down" to reorder it, and "Remove" to delete it. "Review interval (days)" sets how long the procedure may go without a completed run or a review before it counts as stale; leave it blank and it defaults to 90 days. "Save" writes the configuration back to the page.

The editor saves the steps as a small JSON document, and the rules below apply to this shape:

{
  "schema": 1,
  "reviewIntervalDays": 90,
  "steps": [
    {
      "key": "3f9a1c2b-...",
      "instruction": "Restart the ingestion worker.",
      "role": "On-call engineer",
      "precondition": "The queue depth alert has fired.",
      "expectedOutcome": "The worker reports healthy within two minutes.",
      "automationRuleId": null
    }
  ]
}

Each step's key is generated by the editor when the step is created and stays with it through edits and reordering; you never type one yourself. automationRuleId is not editable in this version of the app and is always saved as null. An empty role, precondition or expected outcome is saved as null rather than an empty string.

The parser that decides whether a version of the page is usable enforces these rules, and rejects a document that breaks them, with a reason shown against the procedure:

• At most 100 steps.
• Each text field at most 4,000 characters.
• An instruction cannot be empty or made only of spaces.
• The review interval, if set, must be a whole number of days from 1 to 3,650.
• No two steps may share a key, and no field beyond the ones above is allowed.

The editor warns you while you type if a document would fail, but it never blocks Save: the app checks each version when it captures the page, and that check decides the version's status. If a captured version fails, the procedure shows "Invalid" with the reason, and no run can be started against it until a later, valid version is captured.

The macro itself displays only the instruction of each step, numbered in order. Role, precondition and expected outcome are stored with the version and used when the procedure is diffed or replayed, but are not shown on the page.

The macro's status and version

Below the steps, the macro shows the procedure's status: "Ready" once a valid version has been captured, "Not yet captured" before the first capture, or "Invalid" with the reason. While the app is still catching up on a page's history, it shows "History is catching up" alongside whichever status already applies; this clears on its own as capture finishes, and needs no action from you.

"Version" is a counter that increases only when the content of the steps changes: reordering steps or changing their text moves it on, but changing only the review interval does not. Two badges can appear alongside it: "Stale", when no run has completed and no review has been recorded within the review interval since the procedure was first published, and "Review needed", which is explained below.

Anyone who can edit the page sees a "Mark reviewed" button. Using it records that the procedure has been checked, clears "Review needed" if it was showing, and restarts the stale clock from now. It has no effect on the steps themselves; to change those, edit the page.

The macro's run summary

Beneath the status, the macro lists the runs it knows about: every open run, and the ten most recently completed, each shown as its work item key, its status, and for a completed run, the counts of steps skipped, failed and not recorded. Only runs on a work item you can see are counted or shown; if Jira is not installed, or nothing is visible, the summary reads "No runs yet." Runs that were abandoned rather than completed do not appear here; they can still be seen from the work item's own run panel.

Running a procedure from a work item

On a Jira or Jira Service Management work item, the "Runbooks" panel lets a responder find a procedure, start a run, and work through it.

Type into "Search by title" and choose "Search". This matches against a page's title and its own text, not against the text inside a steps macro's configuration, since that is not indexed; a query is one to 100 characters of letters, digits, spaces, and the punctuation -_.', and the search returns up to 25 pages carrying a steps macro, each marked "Ready", "Catching up", "Not yet captured", "Invalid" or "Unavailable". Choosing a result that is still capturing shows its status but nothing to start; choose it again once it is ready.

Once a ready procedure is selected, "Start run" pins the run to the exact version of the page current at that moment. Every step of that run is then shown with three buttons: "Done", "Skipped" and "Failed". Recording a step, in any of these three ways, is what the run's history is built from; a note can be attached to a step only when it is recorded through the Rovo agent (below), not from this panel.

An open run can be closed in one of two ways, each behind a confirmation: "Complete run", asked to confirm as "Complete this run? This closes it and cannot be undone", and "Abandon run", asked to confirm as "Abandon this run? This closes it and cannot be undone". Completing a run that has any step skipped, failed, or never recorded sets the procedure's "Review needed" badge; this stays until someone marks the procedure reviewed from the macro, even if a later run completes cleanly.

The "Runs on this work item" list shows every run against that work item, newest first, so a responder can reopen and review a run already closed.

Drift, and applying it

A run has drifted when the page has moved on to a version different from the one the run is pinned to, or when the procedure's current version is no longer usable. A drifted run shows a warning naming what changed: steps added, removed, changed, or reordered. If the procedure's current version is itself invalid or otherwise not ready, the warning explains that drift cannot be diffed or applied, and the run stays on its original version until a later version is ready.

Choosing "Apply the current version" moves the run onto the procedure's current version. A step's recorded result is carried forward only when that exact step, unchanged in both its key and its content, still exists in the new version; a changed or new step starts unrecorded, and a removed step drops out of the run's current view while its earlier result stays in the run's history. Reordering the steps alone still counts as drift and still needs applying, but since reordering does not change any step's own content, every result carries forward once it is applied.

The Rovo agent

The app registers a Rovo agent, described to it as helping operations teams follow their runbooks: finding the procedure that fits a situation, starting a run on the work item, recording each step as the responder reports it, and reporting the state of a run. The agent is told never to mark a step done unless the user says it is done, to check for an open run before starting a new one, to present a list of stale procedures as possibly incomplete, and, if an action answers that the app is unlicensed, to say so and not retry it.

Conversation starters offered to a user are "Which runbook covers this incident?", "What is left on this run?" and "Which runbooks are stale?" Behind these, the agent can find procedures by keyword, start a run on a work item, read the full state of a run including its drift, record a step as done, skipped or failed with an optional note, and list procedures that are stale. Recording a step through the agent is the only way to attach a note to it; the panel's own buttons do not offer one.

The agent acts as the person using it and sees only what that person could see and do in Confluence and Jira; it is refused wherever the same action in the panel would be refused. While the licence is not active, it cannot start a run or record a step.

Permissions: who can see and do what

The app grants nothing that Confluence and Jira do not already grant the person acting, and it checks this on every read and every action.

• Finding a procedure by search shows only pages the searching person can already read in Confluence.
• Viewing a procedure's status, its version, or its stale and review-needed state needs permission to read the Confluence page.
• Starting a run, recording a step, applying drift, completing or abandoning a run each need permission to read the Confluence page and to edit the Jira or JSM work item.
• Marking a procedure reviewed needs permission to edit the Confluence page, since the review interval itself is set by editing the page.
• The run summary on the macro counts and shows only runs on work items the viewer can read.

The Rovo agent is held to the same checks as a person using the panel directly.

When the licence is inactive

An inactive licence makes the app read-only. The steps macro, the run panel and the configuration editor each show the message above and hide every control that writes: starting or recording a run, applying drift, completing or abandoning it, marking a procedure reviewed, and editing steps. Reading continues without any change: the macro's status and run summary, the panel's search and run history, and the Rovo agent's own lookups of procedures, run state and stale procedures all keep working. Capture, the background process that keeps a procedure's stored version in step with the page, is unaffected either way, so nothing falls behind while the licence is inactive and a renewed licence finds everything already current.

Where data is stored

The app has no servers of its own. Every procedure, its version history, every run and every event is kept in Atlassian's own hosted storage inside your Atlassian site, and the app makes no calls to any address outside Atlassian. Full detail on what is stored, why, and for how long is in the privacy policy.

Getting help

Write to support@apps.sundar.am for any question about installing, configuring or running the app. Report a security issue to security@apps.sundar.am, as described on the security page.