Confluence
Proofroom reads policy pages kept in Confluence Cloud with a read-only API token: each page’s version history and the approval of its linked Proofroom policy become evidence of the yearly review, who can edit the page becomes an access list to review, and a page’s text can be imported as a Proofroom draft. Add it on Policies → Where your policies live → Confluence → Connect (or Integrations → Catalogue → Confluence).
What each collector shows
| Collector | Kind | Default cadence | What it shows | Suggested controls |
|---|---|---|---|---|
| Policy document reviews | snapshot | quarterly | Each tracked page with when it last changed and who changed it, its versions in the last 12 months (number, date, author, version message) and whether a review was recorded: its linked Proofroom policy approved (with changes, or reviewed with no changes) in the 12 months before the run. A change in Confluence is shown with its date but is not counted as a review; minor edits and Proofroom’s own publishing back are not counted as changes. A page that is gone is listed as not found and not counted as reviewed. | PCI DSS 12.1.2; SOC 2 CC5.3 |
| Who can edit policy documents | snapshot | quarterly | For each tracked page, the people and groups named in its edit restriction; or, with no edit restriction, everyone the space lets add or edit pages and the space admins. | SOC 2 CC6.2, CC6.3 |
The collectors start when the first page is tracked. A page with no edit rights at all would mean Proofroom cannot see the space’s permissions, so that run fails instead of filing “nobody can edit”.
Create the token
Use a dedicated Atlassian account (for example proofroom@yourcompany.com) that can view the policy spaces and
nothing else. Proofroom never needs edit rights to read.
- Sign in as that account at https://id.atlassian.com/manage-profile/security/api-tokens.
- Choose Create API token with scopes, name it “Proofroom”, pick Confluence, and tick these scopes:
read:space:confluence: the spaces, and each space’s permissions.read:page:confluence: the pages, their versions and their text.read:user:confluence: the names of the people who changed a page or may edit it.read:content-details:confluence: a page’s edit restriction.read:group:confluence: the names of groups with edit rights.
- Copy the token. With a scoped token Proofroom calls
api.atlassian.com/ex/confluence/<cloud id>, as Atlassian requires; it reads the cloud id fromhttps://<site>.atlassian.net/_edge/tenant_info.
A classic API token (without scopes) also works: choose classic as the token kind. It can do whatever the account can, so keep the account view-only.
Connect
| Field | Value |
|---|---|
| Site URL | https://<site>.atlassian.net |
| The account’s email | |
| API token | From step 2 |
| Token kind | Scoped (or classic) |
Test connection lists the spaces the account can see.
Then, on Policies → Where your policies live → the connection:
- Pick spaces: tick the spaces that hold policies and save.
- Check now: Proofroom lists every current page in those spaces.
- Tick Track for each page that is a policy, procedure or standard, and link it to its Proofroom policy. Proofroom suggests links by title; nothing is linked until you save.
- Import as draft turns a page’s text into a Proofroom draft (macros keep their text, not their formatting). Check it, then submit it for approval as usual.
Confluence does not record reviews, only edits, so a review is recorded in Proofroom: link each tracked page to its Proofroom policy and approve it once a year (with changes, or as reviewed with no changes). A tracked page whose policy was not approved in 12 months becomes a task, checked daily; editing the page in Confluence does not answer it.
Publishing approved policies back (optional, off by default)
When a linked Proofroom policy is approved, Proofroom can replace the page’s text with the approved version as a new Confluence version. This needs write access, so it has its own token:
- Scoped token: create a second API token for the same account with the scope
write:page:confluence(and the read scopes above), and give the account permission to edit the policy pages. The read token keeps its read-only scopes. - Classic token: a classic token can do whatever its account can, so the read account must stay view-only and a
separate account publishes. Create an account that may edit the policy pages (for example
proofroom-publish@yourcompany.com), create a classic token for it, and enter its email as the publish account email. Proofroom refuses to publish with a classic token until a separate publish account is given.
On the connection’s settings, tick Publish approved policies and paste the token as the publish token. Proofroom uses the publish token only to publish, and the version it writes is not counted as a change in Confluence. A failure is shown on the document and retried daily.
After the first run
- The integration page shows both collectors with a run each; the evidence lists every tracked page.
- Open a page’s history in Confluence and compare it with the versions in the evidence.
- Compare the editor list with the space’s permissions (Space settings → Permissions).