Wiki source code of Page Approval

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

Show last authors
1 {{box title="**Table of contents**"}}
2 {{toc start="2" depth="3"/}}
3 {{/box}}
4
5 == Overview ==
6
7 === Purpose ===
8
9 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.
10
11 === Related extensions or proposals ===
12
13 Related extensions or proposals and how Page Approval differs from them:
14
15 * [[**Publication Workflow**>>extensions:Extension.XWiki Publication Workflow Application]]: 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.
16 * [[**Change Request**>>extensions:Extension.Application Change Request - UI.WebHome]]: 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.
17 * [[**Draft Documents**>>Proposal.DocumentDrafts]]: 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.
18
19 === Key Features ===
20
21 * Three statuses for each version: draft, candidate for approval, approved
22 * Readers see the latest approved version by default, with the comments, tags and ratings added since
23 * A new page is visible only to its approvers and its creator until its first approval
24 * An approvers group for each page, computed when the page enters the workflow
25 * Access to newer versions from the approved one
26 * Archiving
27 * A dashboard of the pages under approval
28
29 === Terminology ===
30
31 * **Approvers group**: the group whose members approve a page's versions, computed when the page enters the workflow.
32 * **Workflow classes**: the classes whose objects, when a page is created, put it in the workflow.
33 * **Read restriction**: the view rule that limits an unapproved page to its approvers and its creator, removed by its first approval.
34 * **Whitelisted change**: a change, such as a comment, that keeps an approved page approved.
35 * **Default view**: the version shown when none is requested, the latest approved one.
36 * **Approval records**: a page's approval events and summary, kept in its hidden {{code language="none"}}Approvals{{/code}} child page.
37 * **Archived**: a state of the page, set by its approvers, that hides it.
38
39 == Functional Requirements ==
40
41 === Version Status Management ===
42
43 ==== Status States ====
44
45 1. **Draft**: the status of a new version, unless it only adds whitelisted changes to an approved one.
46 1. **Candidate for Approval**: a version submitted to the approvers.
47 1. **Approved**: a version an approver approved, or one that only adds whitelisted changes to it.
48
49 A status decides which version readers see by default, not who may read it.
50
51 ==== Status Transitions ====
52
53 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.
54
55 {{code}}
56 [*] --> Draft: created with a workflow class
57 [*] --> Approved: initialization job
58 Draft --> Candidate: submit
59 Candidate --> Draft: reject, or any save
60 Candidate --> Approved: approve
61 Approved --> Approved: whitelisted save
62 Approved --> Draft: any other save
63 {{/code}}
64
65 The state of the page itself, archiving included:
66
67 {{code}}
68 state "Unapproved: visible to approvers and creator" as Unapproved
69 state "Approved: readable by all with view right" as Approved
70 state "Archived: hidden" as Archived
71 [*] --> Unapproved: created with a workflow class
72 [*] --> Approved: initialization job
73 Unapproved --> Approved: first approval
74 Unapproved --> Archived: archive
75 Approved --> Archived: archive
76 Archived --> Unapproved: restore, never approved
77 Archived --> Approved: restore
78 {{/code}}
79
80 ==== Whitelisted Changes ====
81
82 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.
83
84 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.
85
86 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.
87
88 === Access Control ===
89
90 ==== Approvers Group ====
91
92 When a page enters the workflow, the extension computes its approvers group and grants it edit right on the page's hidden {{code language="none"}}Approvals{{/code}} 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.
93
94 * **Default group**: set in the wiki administration.
95 * **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.
96 * **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.
97 * **Changing the group**: admins and approvers edit the rights of the {{code language="none"}}Approvals{{/code}} child. The child's history records each change, and the page under approval gets no new version.
98 * **Visibility**: every reader sees the page's approvers group in the status banner.
99
100 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.
101
102 ==== Document Visibility Rules ====
103
104 **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 {{code language="none"}}WebPreferences{{/code}}, 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.
105
106 **After the first approval**, the extension restricts no reader: every user with view right reads every version.
107
108 **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.
109
110 ==== Permission Matrix ====
111
112 |=User|=Before the first approval|=After it
113 |User with view right on the page|No access|Every version, the approved one by default
114 |Page creator|Every version|Every version
115 |Approver|Every version, and the approver actions|Every version, and the approver actions
116 |Admin|Everything|Everything
117
118 ==== Staying in the Workflow ====
119
120 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.
121
122 ==== Entering the Workflow ====
123
124 **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.
125
126 **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.
127
128 There is no per-space switch and no action that puts a single existing page under approval.
129
130 === Default View ===
131
132 When a user opens a page without naming a version:
133
134 * 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.
135 * Otherwise, the approvers and the creator see the current version, with a banner saying it is not approved.
136
137 **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.
138
139 **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.
140
141 === Approval Actions ===
142
143 * **Submit for Approval**: users with edit right on the page. The current draft becomes the candidate, and a newer submission withdraws an older candidate.
144 * **Approve** and **Reject**: approvers only, with an optional comment.
145 * **Archive** and **Restore**: approvers only.
146 * **View approval history**: every user who can view the page.
147
148 Approvers may approve a version they wrote or submitted, because an approvers group may have a single member. The approval records who gave it.
149
150 === Dashboard ===
151
152 The {{code language="none"}}{{approvalDashboard/}}{{/code}} macro lists the pages under approval that the user can view, with their status and approvers. Its {{code language="none"}}createdByMe{{/code}}, {{code language="none"}}awaitingApproval{{/code}} and {{code language="none"}}archived{{/code}} 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 {{code language="none"}}archived{{/code}} filter is set.
153
154 === Archiving ===
155
156 * Archiving marks the page archived, recording who, when and an optional comment. Restoring undoes it.
157 * It changes no version status: an archived approved page stays approved.
158 * 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.
159
160 An archived page stays editable. An edit creates a draft, which waits for the page to be restored before it can be approved.
161
162 == Technical Architecture ==
163
164 === Component Overview ===
165
166 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.
167
168 === Data Model ===
169
170 {{code language=""}}
171 Page (1) ---- (1) <page>.Approvals hidden child page, its edit right names the approvers
172 (1) ---- (*) ApprovalEvent the page's approval history
173 (1) ---- (1) ApprovalSummary what the dashboard filters and sorts on
174 {{/code}}
175
176 ==== ApprovalEvent XClass ====
177
178 One object per action, {{code language="none"}}enter{{/code}}, {{code language="none"}}submit{{/code}}, {{code language="none"}}approve{{/code}}, {{code language="none"}}reject{{/code}}, {{code language="none"}}archive{{/code}} or {{code language="none"}}restore{{/code}}, 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.
179
180 ==== Where Approval Records Live ====
181
182 A page's records live in its hidden child page, {{code language="none"}}<page>.Approvals{{/code}}, 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.
183
184 * Its edit right names the page's approvers. Only admins may delete it: the extension makes {{code language="none"}}XWiki.superadmin{{/code}} its creator, since XWiki lets a page's creator delete it whatever the page's rights.
185 * 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.
186 * 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.
187 * 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 {{code language="none"}}Approvals{{/code}} child too puts it back under approval.
188
189 Pages under approval are non-terminal, so that each has its own {{code language="none"}}Approvals{{/code}} child and its own {{code language="none"}}WebPreferences{{/code}} for the read restriction.
190
191 ==== ApproversResolver XClass ====
192
193 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.
194
195 ==== ApprovalSummary XClass ====
196
197 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.
198
199 === Script Service ===
200
201 Scripts reach the extension through {{code language="none"}}$services.pageApproval{{/code}}: 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.
202
203 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.
204
205 === User Interface Components ===
206
207 ==== Approval Action Buttons ====
208
209 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.
210
211 ==== Status Indicator ====
212
213 A banner in the page header shows:
214
215 * the displayed version's status, as a warning when it is not approved
216 * 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
217 * the page's approvers group
218 * "Archived" with its date
219 * a link to the page's approval history, which lists its versions with their statuses, then its events
220
221 == Configuration ==
222
223 In the "Page approval" section of the wiki administration:
224
225 * Workflow classes
226 * Whitelisted classes
227 * Default approvers group
228 * Custom approvers resolvers (wiki admins only) and their timeout
229 * The initialization job

Get Connected