PULSE PULSE user guide
Documentation version: tracks the PULSE app version — this edition describes PULSE 1.0.0 (Forge deploy 5.54.0, 2026-09-21). The guide lives in the app repository (docs/user-guide.md) and ships with every release; test/docs/userGuide.test.ts fails the build when a setting or message exists in the product and not here.
PULSE is one Confluence app with ten macros, all reading Jira as you — a macro can never show you an issue Jira would not let you open yourself. Nothing is written to Jira, and nothing on a page is generated by an AI model: every sentence is a template over numbers you can check (see Metric definitions).
1. Installing — two steps, in this order
- Install PULSE on Confluence first. Open the installation link your PULSE contact gives you (it comes from the Forge developer console; PULSE is not on the Marketplace), choose the Confluence site, and consent to the read-only scopes listed (or, from the repository,
forge install --product confluence --site <your-site>). Confluence owns installation, upgrades, storage and data residency: everything PULSE stores lives on the Confluence side and inherits that site's residency. - Then connect Jira. Open the same installation link again and choose the Jira site the boards live on (
forge install --product jira --site <your-site>). Until this is done every macro shows "Unable to load delivery data" / a connect-Jira state rather than an error you have to decode.
Uninstalling from Confluence removes PULSE from Jira as well; there is no separate Jira-side state. An upgrade never changes what a macro shows without telling you: a macro configured by a newer version says "This macro was configured by a newer version of PULSE" until the site catches up.
Permissions requested: read-only Jira scopes only (projects, boards, sprints, issues, changelogs, versions, fields) plus Confluence storage for your own cache. No write scope, and no asApp access — a lint rule in the codebase forbids it.
2. Your first macro in five minutes
- Edit a Confluence page, type
/pulse, and pick PULSE Delivery Health. - In the panel choose a Jira project, a Board on it, and a Sprint (Current sprint follows the board's active sprint; Last closed sprint is fixed to the most recently completed one; or pick a named sprint).
- Optionally give it a Title; save the panel, then publish the page.
The macro renders with the six key figures, the attention list and the trend sections. If a card says a number is unavailable it also says why — that is designed, not broken (§5).
Every other macro starts from the same three choices; the Sprint Goal macro asks for the goal text and its issues instead of trend settings, and Backlog Health takes a board or a JQL.
3. The macros
| Macro | What it shows | Its own settings |
|---|---|---|
| PULSE Delivery Health | overall health, sprint progress, velocity, cycle time, blockers, aging, trends, risk radar, release readiness, throughput, attention, recent activity | everything in §4.1 |
| PULSE Attention | the ranked "what needs management attention" list on its own | scope only |
| PULSE Sprint Radar | sprint completion, scope change, status distribution and workflow concentration, blockers and aging | scope only |
| PULSE Sprint Goal | one sprint goal, the issues that constitute it, and the computed risk to it | Sprint goal, critical issues, Your assessment (optional), Notes (optional) |
| PULSE Daily Scrum | completed / blocked / stale / in progress / updated since the last working day | Activity window, Stale after (days), Group by |
| PULSE Dependency Radar | the sprint's issue links as a diagram with the dependency risks | relationship types, Depth (hops beyond the sprint), Linked issues loaded beyond the sprint |
| PULSE Backlog Health | hygiene rules over the backlog with thresholds | Backlog to assess (board backlog or Issues matching a JQL), rules, Stale after / Old after / Too large above / Stagnant after |
| PULSE Retro Intelligence | the facts a retrospective starts from, by area, and the discussion topics they raise | Compare with the previous (3/6/10/12 sprints) |
| PULSE Stakeholder Update | a status update assembled from the dashboard's numbers, previewed and copied | Reporting period, Number of days, Template, Custom wording, Sections |
| PULSE Forecast | the next sprint's likely completion from the last six closed sprints, or a plain refusal | Closed sprints to show, Horizon |
4. Every setting
4.1 Delivery Health
Scope — Jira project (required), Board (required, listed for the project), Sprint (required: Current sprint (stays current), Most recent completed sprint, or a named sprint). Historical trend period — Last 3/6/10/12 sprints of closed-sprint history behind velocity and cycle-time trends (default 6).
Thresholds — each is a whole number within the range shown in the panel:
| Setting | Meaning | Default · range |
|---|---|---|
| Blocked for more than (days) | flag an issue once it has been blocked for this many days | 3 · 1–90 |
| Active age after (days) | flag an issue that has sat in an active status this long | 5 · 1–90 |
| Sprint risk when incomplete exceeds (%) | flag sprint delivery risk when more than this share of committed work is still incomplete late in the sprint | 20 · 1–100 |
| Cycle-time warning above average (%) | warn when current cycle time exceeds the historical average by more than this percentage | 25 · 1–500 |
| Stale after no update for (days) | flag an issue that has not been updated for this many days | 14 · 1–365 |
| Release window (days) | how close a release date must be before its remaining work is treated as urgent | 7 · 1–90 |
| Old in backlog after (days) | treat an unresolved issue as old once it has existed this many days (backlog age, not active age) | 90 · 1–730 |
| Expected work in progress (issues) | how many issues the team expects to have in progress at once; a status holding more than this is a concentration | 10 · 1–500 |
Filters — components, issue types, priorities and labels narrow the issues every PULSE macro on the page counts, before any number is calculated: an issue must match every group you set (within a group, any value matches). Components and issue types are the project's own; priorities are the site's; labels are the site's list, searchable, capped at the first 1,000 when a site has more (the panel says so). The macro header then shows a Filtered row with each value and "N of M issues"; a value that no longer exists in Jira is shown struck through as unavailable, so an empty page is explained rather than mysterious — edit the page to remove it. Apply filters to historical sprints too applies the same filters to the trend history (off by default, because it can leave history too thin to trend and rewrites past velocity).
Sections — switch each on or off: Overall delivery health, Sprint progress, Velocity, Cycle time, Blockers, Aging issues, Velocity trend, Cycle-time trend, Issue flow, Risk radar, Release readiness, Team throughput, What needs management attention, Recent activity, Sprint commitment, Quick links. A section the board cannot support is disabled with the reason.
Presentation — Dashboard title (defaults to the project name), Description, Refresh (Manual only, Every 15 minutes, Every 30 minutes, Every hour, Every 4 hours, Daily).
What counts as blocked — any combination of A status mapped to Blocked, The Jira flag (impediment) and Labels that mean blocked (comma-separated). At least one must be on; the dashboard states the definition in use next to every blocked count.
Story point field — Detect automatically (the populated story-point field on the board) or a named field. Points are used only when at least 80% of the countable issues are estimated; otherwise the card is retitled by issue count and says why.
Release to report on — Nearest unreleased version by date or a named version. A named version that has since been released falls back to the automatic choice, and the card says so.
Status mapping — every board status is shown with the role PULSE inferred from its Jira category (to do, active, review, qa, blocked, done); override any of them. Roles, never status names, drive every metric.
4.2 The other macros' settings
- Sprint Goal — Sprint goal (one sentence, required), the sprint's issues with a critical checkbox each, Your assessment (optional) shown beside the computed risk (it never hides a finding), Notes (optional).
- Daily Scrum — Activity window: Previous working day (default) (on a Monday that is Friday), or Last 1/2/3/7 days; Stale after (days); Group by: No grouping (default) or Assignee — a display choice only; PULSE never computes or ranks per-person activity.
- Dependency Radar — relationship types (blocks, depends on, duplicates, clones, causes, relates to, other link), Depth (hops beyond the sprint) (default 2), Linked issues loaded beyond the sprint (default 500; when the budget is hit the diagram says how many were left out).
- Backlog Health — Backlog to assess: the board backlog or Issues matching a JQL (the JQL is shown on the macro); per-rule on/off; Stale after (days without an update), Old after (days since creation), Too large above (story points), Stagnant after (days in the current status).
- Retro Intelligence — Compare with the previous 3, 6 (default), 10 or 12 sprints. Fewer than 3 completed sprints means no comparison is made — it is stated, not guessed.
- Stakeholder Update — Reporting period: The selected sprint (default) or The last N days with Number of days (1–90); Template: Steering committee, Delivery team, or Custom wording (your own lines with
{fields}, stored with the macro; a line naming a field that does not exist blocks the save and lists the fields); Sections — switching Risks off is disclosed in the update itself. - Forecast — Closed sprints to show (6, 10 or 12; the forecast is always computed from the last 6 that finished work) and Horizon (1–3 sprints; more sprints multiply the likely range, they never make the forecast more certain). See Forecast.
5. When a card says something is unavailable
PULSE never shows a zero, a dash or a placeholder in place of a number it could not compute honestly. An unavailable card carries the reason, for example "Not enough completed sprints yet for an average — 0 available, 3 needed." or "Forecasts need at least 6 completed sprints with finished work; this board has 2." These resolve on their own as the board accumulates history. The rules for each metric are in Metric definitions, linked from every card's How … is calculated.
Designed empty states you may see, and what they mean:
| Message | Meaning |
|---|---|
| PULSE is not configured yet (or PULSE <macro> is not configured yet) | the page was published without saving the panel — edit the page and configure the macro |
| This board does not use sprints | a Kanban board; choose a scrum board, or a board with sprints enabled |
| Board not found | the configured board was deleted or is no longer visible to you |
| Nothing to show yet | the sprint has no issues yet |
| No recent activity / Nothing changed | nothing moved inside the activity window |
| Nothing in the standup | no issue completed, was blocked, went stale, is in progress or was updated in the window |
| No dependencies / No dependencies to draw | the sprint's issues carry no links of the selected types |
| Nothing to assess | the backlog source returned no issues |
| Nothing to observe / No flagged topics | the retro area has no data, or no observation crossed a topic threshold |
| No goal written yet / Nothing currently threatens this goal | the Sprint Goal macro has no text, or no rule fires on its issues |
| No forecast | the history cannot support a forecast; the reason and the sprints considered are shown |
| Progress unavailable / Scope change unavailable | the sprint has no committed work, or no changelog evidence of what left the sprint |
| This macro was configured by a newer version of PULSE | the site has not upgraded yet; nothing is shown that could be wrong |
6. Troubleshooting — the failure messages and what to do
Every failure states what happened and what to do; the Reference code beneath it identifies the request in PULSE's own logs (no Jira content is ever in a message).
| Message | Cause | What to do |
|---|---|---|
| Jira did not recognise your session. | your Jira sign-in expired or the Jira connection is not installed | Sign in to Jira again, then reload this page. If it persists after sign-in, an admin should complete step 2 of the install. |
| Unable to access this Jira project. | you lack browse permission on the project or board | Ask a Jira administrator for access to the project or board this macro points at. The macro sees exactly what you see; it cannot be granted more. |
| The Jira project, board or sprint this macro points at no longer exists, or you can no longer see it. | deleted or hidden target | Edit the page and point the PULSE macro at something that exists. |
| Jira temporarily limited requests. Please try again. | Jira rate-limited the site | Wait a minute and refresh; this resolves on its own. Several macros on one page share a per-viewer cache, so a second load is cheap. |
| Jira took too long to answer. | a very large sprint, release or link graph | Refresh. If it keeps happening, narrow the macro's scope to fewer issues. Filters, a smaller node budget or a shorter trend period all narrow it. |
| Unable to load delivery data. | an unexpected Jira response | Refresh. If it persists, quote the reference code to support. |
| This macro's configuration is not valid. | a stored setting is out of range or refers to something that no longer exists | Edit the page and open the PULSE macro settings to fix it. The panel names the field. |
| There is not enough data yet to show this. | the board lacks the history a section needs | It will appear once the board has the history it needs; nothing is wrong. |
| This board or project is set up in a way PULSE does not support yet. | for example a board with no sprints for a sprint macro, or a next-gen board without a story-point field | Choose a different board, or check the macro settings for what is supported. |
Other things that look like faults but are not: numbers that differ from a Jira gadget (PULSE excludes sub-tasks and uses calendar time — see the definitions); a section that "disappeared" (it was switched off in Sections, or the board cannot support it and the panel says so); a dashboard that looks different for a colleague (they see their own Jira permissions, and their own per-viewer cache).
7. Accessibility and export
Every chart has a data table (Show data table), every mark is keyboard reachable, colour never carries meaning alone, and pages render in Confluence's light and dark themes (accessibility notes). Exporting a page to PDF or Word replaces each macro with its text summary.
8. Getting help
Quote the macro name, the page, and the Reference code from any failure. Support channel and response times are published on the Marketplace listing.
9. Licensing
PULSE is free. It is installed from an installation link rather than the Marketplace (see section 1), so there is no subscription, no evaluation period and nothing to renew. If a future Marketplace listing ever carries a licence, the macros are already built to say so rather than go blank: an inactive licence renders "PULSE is not licensed on this site" with the page's configuration kept, never cached numbers.