Documentation

Stepwise Checklists for Confluence: user guide

Everything the app does, in the order you will meet it: the checklist of a page, the macro, templates, the Checklists page of a space, search, and the details admins ask about.

On this page
  1. Getting started
  2. Working with a checklist
  3. The macro
  4. Templates and automatic adding
  5. The Checklists page
  6. CQL reference
  7. Premium features
  8. Permissions
  9. Limits
  10. Data and security
  11. Troubleshooting
  12. On the roadmap

Getting started

Stepwise Checklists is a Confluence Cloud app. A Confluence admin installs it from the Atlassian Marketplace and approves its permissions (they are explained under Permissions). After that there is nothing to switch on: the app is available on every page, in every space.

It is a separate app from Stepwise Checklists for Jira: each is installed on its own and keeps its own templates.

Confluence admins find a short start guide inside Confluence as well, in Confluence settings under Stepwise Checklists.

The Get started tab of the Stepwise Checklists admin page, listing four steps: open the checklist of a page, show the checklist inside the page, create templates per space, find pages by checklist state.
Roll out in four steps: checklist, macro, templates, CQL.

Open the checklist of a page

  1. Open any page.
  2. Choose Checklist under the page title, in the line with the author and the date.
  3. The checklist of the page opens in a popup.

There is nothing to add page by page: Checklist is there on every page, and every page has one checklist. You do not need to edit the page to use it.

Checklists are available on pages. Blog posts do not have one yet.

Your first checklist

An empty checklist says “No checklist yet” and offers two ways to begin:

  • Type the first step into the field What needs to be done? and press Enter. Keep typing: every Enter adds the next step.
  • Or click one of the template buttons to start from a checklist your space admin has prepared.
An empty checklist popup with the button Add an item and three template buttons: Page review, Release checklist and Runbook.
Start in one click from a template, or just type the first step.

The line above the checklist shows progress, for example “6 of 12”, and how many required steps are left. When nothing is open any more it says “Complete”.

Working with a checklist

A Confluence page with its checklist open in a popup: twelve steps in three sections, with Required and N/A tags.
The checklist opens from the page byline: sections, required steps and progress, no page edit needed.

Steps

To do thisDo this
Add a stepType into Add an item at the bottom of the checklist and press Enter.
Add a section headingStart the line with #, for example # Security review. Headings group steps and are not counted in progress.
Add a required stepStart the line with !, for example ! Links and attachments open.
Add many steps at oncePaste a list into the add field: one line becomes one step. See Paste a list.
Complete a stepTick its checkbox. Tick again to reopen it.
Skip a step that does not fitOpen the step’s actions menu and choose Mark as not applicable. The step gets an N/A tag and counts as resolved. Reopen brings it back.
Make a step required or optionalActions menu → Make required or Make optional. Required steps carry a Required tag.
Rename a stepClick its text, or focus the step and press Enter or F2. Enter saves, Esc cancels.
Turn a step into a heading, or backActions menu → Turn into a heading or Turn into an item.
ReorderDrag the step by its handle, press Alt + ↑ or Alt + ↓, or use Move up and Move down in the actions menu.
Delete a stepActions menu → Delete.

A step can hold up to 500 characters. Web addresses in the text become links.

Ticking does not edit the page

The checklist is kept with the page, not typed into its text. Adding, ticking and reordering steps does not open the editor and does not create a new page version. Everyone who can see the page sees the progress.

Paste a list

Copy a list from a document, a chat or a spreadsheet column and paste it into the add field. Every line becomes a step. Two marks at the start of a line are understood:

# Before you start
! Access and permissions are confirmed
! Rollback steps are written down
People affected are informed

This adds one heading, two required steps and one ordinary step. Bullets, numbering and checkbox marks at the start of a line (-, *, 1., [ ], [x]) are dropped, so a list copied from a document or from Markdown comes in clean.

Actions for the whole checklist

The Templates button adds a template to the page. The More checklist actions menu next to it holds the rest:

Hide completed items / Show completed items
Keeps only the open steps on screen. A line tells how many are hidden and brings them back with one click.
Copy as text
Copies the checklist to the clipboard, ready to paste into a comment, a message or the checklist of another page.
Reopen all items
Every step goes back to open. The steps themselves stay.
Remove checklist
Removes all steps from this page. Protected steps that came from a template stay.

Templates are created in Space settings, not from a page: see Create a template.

How progress is counted

Progress is the share of steps that are resolved: done or marked not applicable. Headings are not counted. A checklist is complete when it has at least one step and none of them is open.

Keyboard

KeysWhat happens
Enter in the add fieldAdds the step and keeps the field ready for the next one
Esc in the add fieldClears the field
Enter or F2 on a stepStarts renaming
Enter while renamingSaves the new text
Esc while renamingCancels
Alt + ↑ / Alt + ↓Moves the step up or down
Tab / Shift + TabMoves between steps, tags and menus, as everywhere in Confluence

The macro

The Stepwise checklist macro shows the checklist of a page inside the page body, so readers tick steps right where they read. It is the same checklist as the one under Checklist in the byline: a step ticked in one place is ticked in the other.

Insert the macro

  1. Edit the page.
  2. Type /Stepwise checklist where the checklist should appear and insert the macro.
  3. Publish the page.
The Confluence editor with the Stepwise checklist macro: a preview card showing 6 of 12 done, the first three steps and the line +11 more.
In the editor the macro is a read-only preview. Ticking happens on the published page.

While you edit the page, the macro shows a preview: the progress, the first steps and the note “The checklist of this page appears here. Tick items on the published page, here or from Checklist under the page title.” Steps cannot be changed in the preview.

On the published page

A published page with the checklist in the page body under the heading Review checklist.
Place the same checklist in the page body with a macro.

On the published page the macro is the full checklist, with every action described under Working with a checklist. People who can only view the page see it read-only.

  • The macro always shows the checklist of the page it is placed on.
  • The checklist does not live in the macro. Removing the macro from the page leaves the checklist where it is, under Checklist in the byline.
  • Inserting or removing the macro is a normal page edit. Ticking steps in it is not.

Templates and automatic adding

A template is a reusable checklist: your page review, runbook, onboarding or release steps. Templates belong to a space and are managed by its space admins in Space settings → Integrations → Checklist templates.

The Checklist templates page with three templates and seven examples to start from.
Reusable templates for each space: page review, runbook, release steps.

Create a template

  1. Open Space settings → Integrations → Checklist templates.
  2. Click New template, or pick one of the seven examples under Start from an example: Page review, Runbook, New hire onboarding, Meeting follow-up, Definition of Done, Release checklist, Code review. An example opens in the editor so you can adjust it before saving.
  3. Give it a name and, if you like, a description that is shown next to the name.
  4. Add the steps one by one with Add item, or use Paste a list: one line per step, # for a heading, ! for a required step.
  5. Use the buttons at the end of each row to mark it as a section heading or as a required item, and to move or delete it.
  6. Click Save.
The Edit template dialog with name, description, five steps and the switch Add to new pages in this space automatically.
Switch on automatic adding and every new page in the space starts with the template.

The menu on a template card lets you edit, duplicate or delete it. Deleting a template does not touch checklists that were already added to pages: they stay as they are.

Templates are created only here. To turn a checklist you already wrote on a page into a template, choose More checklist actions → Copy as text on the page and then Paste a list in the template editor: headings and required marks come along.

Add a template to a page

Anyone who can edit the page can click Templates in the checklist and pick a template. Its steps are added to the checklist. The menu lists the templates of the space under This space.

The Templates menu in the checklist popup, listing three templates of the space and one from the shared library.

Automatic adding

A template can add itself to every new page of its space:

  1. Open the template in the editor.
  2. Switch on Add to new pages in this space automatically.
  3. Save.

From then on, a new page in the space starts with that checklist as soon as it is created. A few things to know:

  • It applies to pages created after you switch it on. Existing pages are not changed.
  • If several templates of the space are set to add automatically, all of them are added.
  • Template cards show the tag “New pages” so you can see at a glance what adds itself.
  • It applies to pages. Blog posts do not get a checklist.

The Checklists page

Every space gets a Checklists page in its navigation. Everyone who can see the space can open it. It shows where every checklist in the space stands.

The Overview tab with four tiles and a table of six pages with their checklist progress.
One page shows every checklist in the space and what is waiting on required steps.

Overview tab

  • Four tiles count the pages With a checklist, In progress, Waiting on required items and Complete. Click a tile to filter the table.
  • The table lists each page with its title, progress and the number of required steps left. The title opens the page.
  • Refresh reloads the numbers.
  • You see the pages you have access to. Pages that are restricted for you are not listed.
  • The page shows up to the 200 most recently modified pages that have a checklist. For anything beyond that, use the CQL fields.

Insights tab

The second tab, Insights, is described under Premium features.

CQL reference

Every checklist publishes four numbers that Confluence indexes. Use them in advanced search and in any macro that takes CQL.

FieldValueMeaning
checklistProgress0–100Percent of steps that are done or not applicable
checklistItemsNumberSteps in the checklist (headings are not counted)
checklistOpenItemsNumberSteps that are still open
checklistRequiredOpenNumberRequired steps that are still open

The fields are numbers, so they work with =, !=, >, >=, < and <=.

Examples

FindCQL
Pages of one space that still have required steps openspace = ENG and checklistRequiredOpen > 0
Any unfinished checklistchecklistProgress < 100
Checklists that are completechecklistOpenItems = 0 and checklistItems > 0
Checklists that are more than half done but not finishedchecklistProgress >= 50 and checklistProgress < 100
Checklists nobody has startedspace = ENG and checklistProgress = 0
Runbooks with open steps, by labellabel = "runbook" and checklistOpenItems > 0
Long checklists in one spacespace = ENG and checklistItems > 20
  • Pages without a checklist have no values in these fields and are not matched by them.
  • Confluence updates its search index shortly after a checklist changes. A search run in the same moment can still show the previous numbers.
  • Only the four numbers are indexed. The text of the steps is not part of these fields.
  • space and label in the examples are Confluence’s own CQL fields; the checklist fields combine with any of them.

Premium features

Premium is the Advanced edition of Stepwise Checklists on the Atlassian Marketplace. It is meant for teams that run the same standards across many spaces, and adds three things. A Confluence admin can switch editions at any time.

Shared library

Templates that every space can use: one Definition of Done or security review for the whole company, managed in one place.

  • Confluence admins manage it in Confluence settings → Stepwise Checklists → Shared library. The editor is the same as for space templates.
  • Shared templates appear in the Templates menu of every page, in every space, under Shared library.
  • A shared template can also be set to Add to new pages in every space automatically.
The Shared library tab of the Stepwise Checklists admin page with one template, Security review, and two protected steps.

Protected items

In the template editor, the lock button marks a step as protected. Once that template is added to a page, a protected step cannot be renamed, removed, made optional or turned into a heading there. It shows a small lock, and Remove checklist leaves it in place. People still tick it like any other step, can mark it not applicable when it does not fit, and can move it.

Use protection for the steps that must not be edited away, such as a security or compliance check, and leave the rest of the checklist flexible.

Insights

The Insights tab of the Checklists page shows where work gets stuck in a space, so you can fix the process, not chase people.

  • Tiles: Average completion, Not started, Waiting on required items.
  • Most often left open: steps that slow work down, or that people forget.
  • Most often marked not applicable: candidates to remove from the template or make optional.
The Insights tab with three tiles and two lists of steps with bars.

Insights are counted from the pages listed on the Overview tab.

If a site moves back to the Standard edition, shared templates are kept but no longer offered to the team, and a Confluence admin can still delete them. Protected steps that are already on pages stay as they are.

Permissions

Who can do what

The app has no permission settings of its own. It follows Confluence, page restrictions included.

ActionWho
See a checklistAnyone who can view the page
Add, tick, edit and reorder steps; add a template to a pageAnyone who can edit the page
Insert or remove the macroAnyone who can edit the page, as for any other page content
Create, edit and delete templates of a spaceSpace admins, in Space settings
Open the Checklists page of a spaceAnyone who can see the space. It lists the pages that person can view.
Manage the shared libraryConfluence admins

People who can view a page but not edit it see its checklist read-only.

What the app is allowed to do

When the app is installed, Confluence asks the admin to approve seven permissions:

PermissionWhy the app needs it
read:page:confluenceTo read the checklist of a page and what the current person may do with that page
write:page:confluenceTo save the checklist with its page
read:space:confluenceTo show the name of the space and to check whether the current person is a space admin
read:confluence-userOnly to check whether the current person is a Confluence admin, for the shared library. Nothing from the profile is read or stored.
search:confluenceTo find the pages with a checklist for the Checklists page of a space
read:confluence-content.summaryTo learn when a page is created, so that templates can be added to it automatically
storage:appTo keep templates in Atlassian-hosted app storage

Limits

WhatLimit
Checklists on one pageOne
Steps on one page, headings included150
Length of one step500 characters
Steps in one template80
Templates in one space50
Templates in the shared library100
Template name80 characters
Template description300 characters
Pages listed on the Checklists pageThe 200 most recently modified
Content typesPages. Blog posts are not supported yet.

The step limits exist because a checklist is stored in one Confluence content property, and Confluence caps the size of a property. When a checklist is full, it says so and asks you to remove a step before adding another.

Data and security

  • A checklist is stored with its page, as the Confluence content property stepwise_checklist. It moves and gets deleted together with the page.
  • Templates are stored in Atlassian-hosted app storage (Forge storage).
  • Nothing is sent to any other server. There are no external services, no analytics and no third parties.
  • The app stores checklist text, the state of each step and the time a step was completed. It does not store account ids, names or emails.
  • The data follows your Confluence data residency.
  • If the app is uninstalled, templates are removed with it. Checklists remain with the pages as content properties, and reinstalling the app shows them again.

More detail, including an architecture diagram: Security and data. Legal wording: Privacy policy.

Troubleshooting

I do not see Checklist under the page title
It is shown on pages, in the line with the author and the date. If it is missing on every page, ask a Confluence admin whether the app is installed on the site.
“Checklists are available on pages.”
You opened the checklist or the macro on a blog post. Checklists work on pages only for now.
The checklist is read-only
You can view the page but are not allowed to edit it, for example because of a page restriction. If the checklist shows the note “Checklists are read-only” for everybody, the app’s licence on the site is not active: everything stays visible, and a Confluence admin can restore editing under Confluence’s app management.
I cannot tick steps in the macro
In the editor the macro is a preview. Publish or close the editor and tick on the published page, in the macro or from Checklist under the page title.
I cannot rename or delete one of the steps
A step with a lock icon is protected: it comes from a template whose owner decided it must stay as written. You can still tick it or mark it not applicable.
I cannot add another step
A checklist holds 150 steps. Remove one to add another, or split the work across several pages.
A template was not added to a new page
Check that Add to new pages in this space automatically is switched on in the template, that the page is in that space, that it is a page and not a blog post, and that it was created after you saved the template. The checklist is added moments after creation: reload the page if you opened it immediately.
The Templates menu says “No templates yet”
The space has no templates. A space admin can create them in Space settings → Integrations → Checklist templates.
I cannot find “Save as template” on a page
Templates are created in Space settings only. Use Copy as text on the page and Paste a list in the template editor to carry a checklist over.
A page is missing from the Checklists page
The Checklists page shows up to the 200 most recently modified pages with a checklist, and only pages you can view. A checklist that was created a moment ago appears once Confluence has indexed it: click Refresh.
A CQL search with a checklist field returns nothing
Pages without a checklist are not matched by these fields. Check the spelling of the field (checklistProgress, checklistItems, checklistOpenItems, checklistRequiredOpen) and give Confluence a moment to index a checklist that was just changed.
“Copying is blocked by the browser”
Your browser did not allow access to the clipboard. Allow clipboard access for your Confluence site in the browser settings and try Copy as text again.
“The checklist could not be loaded”
Click Try again or reload the page. If it keeps happening, write to support and tell us what you see.

On the roadmap

These are not in the app today. We list them so that you know what to expect and what not to look for yet. There are no dates attached.

  • Progress shown right in the page byline
  • Checklists on blog posts
  • Rules that add a template by label or by parent page
  • Page approvals with named reviewers
  • Translations of the interface (it is in English today; checklist text can be in any language)

Missing something else? Tell us.