Page Approval

Last modified by slauriere on 2026/11/12 13:30

 XWiki
 Feature
 Active
 
 
No

Description

Overview

Purpose

Page Approval is an extension that adds a version-based approval workflow to wiki pages. Readers see the latest approved version of a page while its authors keep working on the next one. Each version is a draft, a candidate for approval or approved.

Related extensions or proposals

Related extensions or proposals and how Page Approval differs from them:

  • Publication Workflow: a page is written as a draft copy and published over a separate page, so it exists twice, and the published page's creator and last contributor are not the users who wrote it. Here one page holds every version, and readers see the approved one by default.
  • Change Request: proposed changes live outside the page until an approver merges them, so unapproved content never reaches the page or its history. Here every save goes into the page's history.
  • Draft Documents: changes are kept out of the page until one editor publishes them, with no approval step. Here pages enter a workflow where each version has a status and only approvers can approve one. A future version of Page Approval may store its drafts as Draft Documents.

Key Features

  • Three statuses for each version: draft, candidate for approval, approved
  • Readers see the latest approved version by default, with the comments, tags and ratings added since
  • A new page is visible only to its approvers and its creator until its first approval
  • An approvers group for each page, computed when the page enters the workflow
  • Access to newer versions from the approved one
  • Archiving
  • A dashboard of the pages under approval

Terminology

  • Approvers group: the group whose members approve a page's versions, computed when the page enters the workflow.
  • Workflow classes: the classes whose objects, when a page is created, put it in the workflow.
  • Read restriction: the view rule that limits an unapproved page to its approvers and its creator, removed by its first approval.
  • Whitelisted change: a change, such as a comment, that keeps an approved page approved.
  • Default view: the version shown when none is requested, the latest approved one.
  • Approval records: a page's approval events and summary, kept in its hidden Approvals child page.
  • Archived: a state of the page, set by its approvers, that hides it.

Functional Requirements

Version Status Management

Status States

  1. Draft: the status of a new version, unless it only adds whitelisted changes to an approved one.
  2. Candidate for Approval: a version submitted to the approvers.
  3. Approved: a version an approver approved, or one that only adds whitelisted changes to it.

A status decides which version readers see by default, not who may read it.

Status Transitions

Submitting, approving and rejecting move a version between the three statuses. Every save creates a new version, so the diagram follows the page's latest version.

  [*] --> Draft: created with a workflow class
  [*] --> Approved: initialization job
  Draft --> Candidate: submit
  Candidate --> Draft: reject, or any save
  Candidate --> Approved: approve
  Approved --> Approved: whitelisted save
  Approved --> Draft: any other save

The state of the page itself, archiving included:

  state "Unapproved: visible to approvers and creator" as Unapproved
  state "Approved: readable by all with view right" as Approved
  state "Archived: hidden" as Archived
  [*] --> Unapproved: created with a workflow class
  [*] --> Approved: initialization job
  Unapproved --> Approved: first approval
  Unapproved --> Archived: archive
  Approved --> Archived: archive
  Archived --> Unapproved: restore, never approved
  Archived --> Approved: restore

Whitelisted Changes

Some ordinary actions save the page as a new version: adding, editing or removing a comment or a tag, and rating the page when average ratings are stored on it. As long as no draft is pending, these saves keep an approved page approved, so they reach readers without waiting for an approver.

A save is whitelisted when it leaves the content, the attachments and the page's fields unchanged (the author fields and the hidden flag aside), and every object it adds, changes or removes belongs to a whitelisted class. Admins set the list of whitelisted classes in the wiki administration. It starts with comments, tags and average ratings. A change to the page's rights is never whitelisted.

Once a save that is not whitelisted has created a draft, later comments, tags and ratings belong to that draft, and readers see them only when a version that includes them is approved. A rollback to the approved content is a draft as well, which an approver approves again. The check fails closed: a save the extension could not check is a draft.

Access Control

Approvers Group

When a page enters the workflow, the extension computes its approvers group and grants it edit right on the page's hidden Approvals child. The page's approvers are the users with that right, so checking whether someone is an approver is XWiki's own edit-right check. Admins can always approve.

  • Default group: set in the wiki administration.
  • Custom resolvers: Velocity or Groovy scripts, written by wiki admins, for pages whose approvers depend on other data. Each applies to the pages carrying an object of a given class. For example, a procedure page's approvers can be the managers of the department it belongs to. A resolver runs with its author's rights, never those of the user creating the page.
  • Failing closed: a resolver that fails, times out, or returns something other than an existing group leaves the page with no approvers group, so only admins can approve it.
  • Changing the group: admins and approvers edit the rights of the Approvals child. The child's history records each change, and the page under approval gets no new version.
  • Visibility: every reader sees the page's approvers group in the status banner.

The approvers group is computed once, when the page enters the workflow, and stored as rights rather than resolved at each check. The approver check, the read restriction and the dashboard then run no script, and the group does not change behind the approvers' backs when the data it came from changes.

Document Visibility Rules

Before the first approval, the page is visible only to its approvers and its creator, so contributors keep access to the unapproved pages they create. The restriction is a "page and children" view rule in the page's own WebPreferences, so writing and lifting it adds no version to the page, and the first approval removes it. The extension touches only that rule, never the rules an admin added there.

After the first approval, the extension restricts no reader: every user with view right reads every version.

Limit. The restriction holds against readers, not against the page's editors, who can open the page to others by adding page rights. The page's history shows who did.

Permission Matrix

UserBefore the first approvalAfter it
User with view right on the pageNo accessEvery version, the approved one by default
Page creatorEvery versionEvery version
ApproverEvery version, and the approver actionsEvery version, and the approver actions
AdminEverythingEverything

Staying in the Workflow

Once a page is under approval, it stays under approval. Removing its workflow class objects does not take it out, and there is no exit action.

Entering the Workflow

On creation. A page enters the workflow when its first save carries an object of one of the workflow classes, a list set in the wiki administration. A page given such an object on a later save does not enter it, and neither does a page moved, copied with its children or restored from the recycle bin. The page starts as a draft, under the read restriction. Entering writes only outside the page, so it adds no version to it.

Existing pages. An initialization job, which admins run manually whenever they add a workflow class, puts the existing pages carrying that class under approval and approves their current version as is, without review and with no read restriction, so readers keep seeing them. Leaving existing pages out would keep them out of the workflow for good, and every later change to them would go unreviewed. The cost: "approved" does not always mean that an approver read that version. The job's report names the pages it skips.

There is no per-space switch and no action that puts a single existing page under approval.

Default View

When a user opens a page without naming a version:

  • If the page has an approved version, they see the latest approved version. When it is not the current version, the extension redirects to it, and XWiki renders it as an older revision, in restricted mode.
  • Otherwise, the approvers and the creator see the current version, with a banner saying it is not approved.

Not an access control. Once a page has an approved version, every version stays readable by every user with view right, through its URL, the history, diffs, REST and exports. Search results and inclusions serve the current version, which may be a draft, since serving the approved version would mean indexing an older revision. Content that must stay confidential until it is approved cannot rely on the extension after a page's first approval.

Restricted mode. XWiki's restricted mode for older revisions is kept. Rendering them with full rights would run scripts without the checks that applied when they were saved, so pages under approval should keep scripts out of their own content.

Approval Actions

  • Submit for Approval: users with edit right on the page. The current draft becomes the candidate, and a newer submission withdraws an older candidate.
  • Approve and Reject: approvers only, with an optional comment.
  • Archive and Restore: approvers only.
  • View approval history: every user who can view the page.

Approvers may approve a version they wrote or submitted, because an approvers group may have a single member. The approval records who gave it.

Dashboard

The {{approvalDashboard/}} macro lists the pages under approval that the user can view, with their status and approvers. Its createdByMe, awaitingApproval and archived parameters preset its filters, which the user can still change. The first two together list a user's own pages waiting for an approver, and archived pages are left out unless the archived filter is set.

Archiving

  • Archiving marks the page archived, recording who, when and an optional comment. Restoring undoes it.
  • It changes no version status: an archived approved page stays approved.
  • The archived page becomes hidden, so it drops out of search and navigation for users who do not display hidden pages. It stays readable by direct link, with an "Archived" banner and its date.

An archived page stays editable. An edit creates a draft, which waits for the page to be restored before it can be approved.

Technical Architecture

Component Overview

The extension is made of XClasses for the approval records and the resolvers, a script service, event listeners, and templates and JavaScript for its UI. It adds no right checking of its own: access follows XWiki's rights, plus the read restriction of an unapproved page.

Data Model

Page (1) ---- (1) <page>.Approvals          hidden child page, its edit right names the approvers
                  (1) ---- (*) ApprovalEvent     the page's approval history
                  (1) ---- (1) ApprovalSummary   what the dashboard filters and sorts on

ApprovalEvent XClass

One object per action, enter, submit, approve, reject, archive or restore, with the version it applies to, the user, the date and an optional comment. The events are authoritative: every state of a page is derived from them, whether it is under approval, its latest approved version, its candidate and whether it is archived. What the dashboard filters on is also stored, in a summary, since a value derived from events cannot be filtered in a database query.

Where Approval Records Live

A page's records live in its hidden child page, <page>.Approvals, not on the page itself. On the page, any editor could rewrite them, and every approval would save the page and make the approver its last author, whereas a page's creator and last contributor must remain the users who wrote it.

  • Its edit right names the page's approvers. Only admins may delete it: the extension makes XWiki.superadmin its creator, since XWiki lets a page's creator delete it whatever the page's rights.
  • The extension writes the records with its own rights, after checking the user's right for the action. Approvers may also correct them by hand. A hand edit that would take the page out of the workflow or leave it with no approvers is refused, and after any other the extension brings the summary and the read restriction back in line with the events and rights.
  • The records travel with the page when it is copied or exported with its children. When it is moved, the extension moves them, and an unapproved page's read restriction, along with it: XWiki's move job moves only the pages the user may delete, so a contributor's move would otherwise leave them behind. A move that would make a page under approval terminal is refused.
  • When the page is deleted, its records go to the recycle bin with it, so a page created later at the same place does not inherit them. Restoring the page alone leaves it out of the workflow, and an admin who restores the Approvals child too puts it back under approval.

Pages under approval are non-terminal, so that each has its own Approvals child and its own WebPreferences for the read restriction.

ApproversResolver XClass

One object per custom resolver, on a configuration page only wiki admins can edit: the class whose objects select the pages it applies to, the script language (Velocity or Groovy), the script and a description. The script receives the page's reference and returns a group.

ApprovalSummary XClass

One object per page under approval, next to its events: whether the page has an approved version, its candidate version, whether it is archived, and where its read restriction is. The extension rewrites it with each event, and after a hand edit of the events.

Script Service

Scripts reach the extension through $services.pageApproval: the status of each version, the latest approved version, the default version, whether the current user is an approver, the approvers group, and the actions (submit, approve, reject, archive, restore). Read methods return nothing for a page the user cannot view.

Submit applies to the current version when it is a draft, Approve and Reject to the candidate, and an archived page can be neither submitted nor approved. An action whose precondition fails records nothing and says why.

User Interface Components

Approval Action Buttons

An "Approval" group in the page's "more actions" menu holds Submit for Approval, Approve Version, Reject Version, Archive or Restore, and View Approved Version, each shown only to the users who may use it and only when it applies.

Status Indicator

A banner in the page header shows:

  • the displayed version's status, as a warning when it is not approved
  • a notice when a newer version exists, with its status and a link to it, which is how an editor finds the draft they just saved
  • the page's approvers group
  • "Archived" with its date
  • a link to the page's approval history, which lists its versions with their statuses, then its events

Configuration

In the "Page approval" section of the wiki administration:

  • Workflow classes
  • Whitelisted classes
  • Default approvers group
  • Custom approvers resolvers (wiki admins only) and their timeout
  • The initialization job

 


Get Connected