← Back to Policy Management Changelog

Version Control & Owner Approvals

Every document in the plugin carries a version number, a changelog and a set of content snapshots, so you can always show what a policy said, who changed it, who approved it, and when. This guide is for the people who write and own your policies — compliance leads, quality managers, practice managers and site administrators. It covers how versions are created, how to compare and restore earlier wording, how to schedule a change for a future date, the owner approval workflow that stops a new version going live until the right person signs it off, and the periodic document review sign-off.

Versioning is switched on by default. You control it with Enable Versioning under Settings → Features. When it is off, the Version & Changelog box disappears from the document editor and no new versions are recorded.

How versioning works

Version numbers use three parts — major.minor.patch — and a new document starts at 1.0.0. When you first create a document, the plugin records an “Initial Version” entry in its changelog. If the person creating the document is in one of your Approver User Roles, they are recorded as its approver too.

Saving a document does not change its version number on its own. You create a new version by adding a changelog entry and choosing the type of change:

Change type	Example	When to use	Effect on acknowledgements (default setting)
Patch	1.0.0 → 1.0.1	Typos and minor fixes that don’t change the meaning	Existing acknowledgements stay valid
Minor	1.0.0 → 1.1.0	Content updates, new sections, clarifications	Existing acknowledgements stay valid
Major	1.0.0 → 2.0.0	Rewrites or substantial policy changes	Existing acknowledgements stop counting — everyone must acknowledge again

The re-acknowledgement level applies to the whole site. You set it with Re-Acknowledgement Trigger Level under Settings → Acknowledgements & Notifications:

Option	Changes that make staff acknowledge again
Major changes only (recommended) (default)	Major only
Minor and major changes	Minor and major
All changes (patch, minor, and major)	Every new version

Choose the change type carefully. It decides whether your whole audience has to acknowledge the document again.

Publishing a new version

Open the document in the WordPress editor.
Make your changes to the content.
Scroll to the Version & Changelog box below the editor. It shows the Current Version.
Under Add Changelog Entry, choose the Change Type: Patch (typos, minor fixes), Minor (content updates) or Major (significant changes, invalidates acknowledgements). Patch is selected by default.
Describe what changed in Description of Changes. As soon as you type a description, the New Version number appears so you can check it before saving. The description is kept in the version history and can be shown to staff (see Changelog visibility below).
Optionally choose who approved the change in Approved By. The list shows users in your Approver User Roles (or all users if no approver roles are set). The name is recorded only if that person is the document’s owner or holds an approver role. Otherwise the entry shows no approver.
Click Update (or Publish).

Before the new content is saved, the plugin takes a snapshot of the previous content so you can compare or restore it later. If the owner approval workflow is on and you are not allowed to approve your own change, the new version is held for approval instead of going live (see The owner approval workflow below).

Important: A new version is only created when you write a Description of Changes. If you edit a published document and save without one, your edits go live straight away under the existing version number. They don’t trigger re-acknowledgement and don’t go through owner approval. A snapshot of the previous content is still kept.

Scheduling an update (keep the current version live until a date)

Sometimes a policy change is approved now but takes effect later. For example, a new leave policy starts on 1 July, and staff must keep seeing the current wording until then. Schedule this update handles this:

Open the published document and make your content changes.
In the Compliance & Status panel, set Effective From to the date the new wording takes effect.
Tick Schedule this update — keep the current version live until the date above, then publish these changes automatically.
Save/update the document.

The current version stays live and visible to staff. Your new wording is held aside and goes live automatically at midnight (your site’s time zone) at the start of the effective date. When it goes live, the outgoing version is snapshotted as usual. While an update is scheduled, the panel shows a notice: “An update is scheduled to go live on …”. To change the scheduled wording, edit and re-save with the box still ticked. To cancel the schedule, untick the box and save. Your edited wording then goes live immediately, as a normal save would.

A few things to know:

Scheduling needs versioning enabled, a published document that already has an earlier snapshot, and an Effective From date after today. If any of these is missing, the box has no effect.
Without scheduling, a future Effective From date hides the whole document from staff (everyone except editors) until the date arrives. That’s right for brand-new documents, but usually not for updates to existing ones. The editor warns you either way.
The version number and changelog note you enter are recorded when you save, not held back with the scheduled wording.
The swap runs on WordPress’s scheduler. If your site has no visitors at midnight, the once-a-day maintenance check (see Daily automation below) applies any update whose date has passed.

Version history

To view a document’s history, open it in the editor and scroll to the Version & Changelog box.

Version History lists every changelog entry, newest first, with its Version, Type (Major, Minor or Patch), Date, Changes, Author and Approved By. Each row has Edit and Delete buttons for anyone who can edit the document:

Edit lets you correct the version label, type, date, description and author of an entry.
Delete removes the entry after you confirm.

After an edit or deletion, the document’s current version label is reset to the version on the latest remaining entry. Editing or deleting history doesn’t change the document content, and doesn’t trigger or undo re-acknowledgement. Use it only to fix mistakes. Your changelog is part of your audit trail.

Staff see a Version History section on the document page itself, listing each version and its date. Whether they also see the change descriptions depends on Changelog visibility (below). On the public page, patch entries carry the same “Minor” badge as minor entries.

Version snapshots, comparing and restoring

The Version Snapshots & Rollback section of the same box lists saved copies of earlier content, oldest first. Each one shows the Version, Date, Saved By and Content hash.

A snapshot is saved automatically whenever:

you save a content change together with a changelog entry, or
you save any content change to a document that is already published, even without a changelog entry.

Only content changes create snapshots. Saving with an unchanged body doesn’t.

For each snapshot you can:

View Changes — compare the snapshot with the current content. Choose Side by Side or Inline under Diff view. Title, content and excerpt changes are shown separately. Inline view shows added and removed words. For very large documents it falls back to a line-by-line comparison.
Restore — put that version’s content back after you confirm.

What a restore does: the current content is saved as a new snapshot first, labelled “Auto-saved before rollback to v…”. The old title, content and excerpt are then restored, and the document’s version number goes back to the restored snapshot’s version. A “Rolled back to version …” entry is added to the version history, so nothing is lost and the rollback is on record.

Keep in mind:

A restore takes effect immediately. It does not go through owner approval, and it does not ask staff to acknowledge again.
Only people who can edit the document can view changes or restore.
If a document has no snapshots yet, the box explains that one will be created the next time you save a change.

The number of snapshots kept per document is set by Version Snapshot Limit (see the end of this page).

The SHA-256 content fingerprint

Every version snapshot stores a SHA-256 hash of the document. This is a digital fingerprint: a 64-character string generated from the exact version number, title, content and excerpt. The Content hash column shows the first 12 characters. Hover over it to see the full hash.

If someone changes the document afterwards, even by a single character, the hash changes. The hash of the version a person acknowledged is also stored on their acknowledgement record and included in the attestation export (see Compliance Reporting & Attestation Exports). Years later, you can show exactly which content a staff member acknowledged. Snapshots taken before content hashing existed are marked legacy. Re-saving the document creates a hashed snapshot for the new version.

You don’t need to do anything to use this feature. It is automatic.

The owner approval workflow

When it is on, the approval workflow makes sure a document’s owner signs off a new version before staff see it. A document owner is an owner title (for example “Policy Owner” or “Director of Nursing”) that you assign to one WordPress user. Each document can name one owner.

Setting it up

Approvals need someone who can approve a held version, so there is a one-time setup first:

Go to Settings → User Management and define an owner title (governance role), such as “Policy Owner”.
Under Document Owner Assignments on the same tab, pick the WordPress user who holds each title. As an alternative, or as well, choose one or more Approver User Roles.
Go to Settings → Features, tick Enable Version Approval and save. If you haven’t completed step 1–2, the setting is refused with the message “Configure at least one approver role or document owner before enabling version approval”, with a link to User Management. Until the prerequisite is met, the Version Approval tab also shows a “Setting up version approvals” checklist.
On each document, set its Document Owner. The approval email goes to the user assigned to that owner title.

What happens when a version is submitted

An editor saves a new version (adds a changelog entry and clicks Update).
The new content is held back. Staff keep seeing the previously approved version. In the editor, the Version & Changelog box shows a Pending Version Approval notice: “Version … submitted by … on … is awaiting owner approval”, with the description of changes.
If Email Notifications is on and the document has an assigned owner, the owner receives the Version Approval Required email (see Approval emails below).
The owner (or an administrator) approves or rejects the version from the email, the admin, or the front-end Pending Approvals page.
On approval, the held content goes live, the version number moves up, the approver is recorded in the changelog, and re-acknowledgement starts if the change type meets your trigger level.
On rejection, the held version is discarded and the live document stays as it was. The person who submitted the change receives a Version Change Rejected email with any reason given. The rejected wording is not kept as a version, so copy it somewhere first if you may want to rework it.

The very first version of a new document is not held. Approval applies to later versions.

Who can skip approval

A new version goes live straight away, without waiting, when:

the editor is the document’s owner and Auto-Approve Owner Changes is on (the default);
the editor holds one of your Approver User Roles;
an administrator ticks Approve immediately (administrator override — bypasses owner approval) in the Version & Changelog box before saving. This box only appears to administrators while version approval is on.

In each case, the changelog records that person as the approver.

There is one more case. If version approval is on but a document has no owner and your site has no approver roles, nobody could ever approve it. The version therefore goes live straight away, and the changelog records no approver rather than pretending one existed. Give every governed document an owner to avoid this.

Approving or rejecting from the email

The Approve Version button in the email works without logging in:

Click Approve Version. A Confirm Version Approval page opens: “Click below to finish approving this version.”
Click Confirm approval. This two-step design stops email security scanners from approving a version just by following the link.
The new version goes live immediately. You see “Version approved. The new version is now live.” with a link to the document. If you are logged in and can edit the document, you are taken to its edit screen instead.

The email has no reject link. To reject, use Reject in the admin or on the front-end Pending Approvals page.

Preview Changes in the email shows the held version on the document page, so you can read it before approving. View in Admin opens the document’s edit screen.

The approval link expires after Approval Link Expiry (Days), which is 30 days by default. After that, approve from the admin instead.

The Pending Approvals screen

Policy Management → Pending Approvals lists every held version. The menu item shows a count of waiting versions. Each row shows the Document, Version, Change Type, Description, Submitted By and Submitted date, with three actions:

Preview opens the held version on the document page in a new tab.
Approve asks you to confirm (“Approve this version? It will go live immediately.”).
Reject asks for an optional reason, which is included in the rejection email.

The screen appears in the menu while version approval is on. If you switch version approval off while versions are still waiting, it stays available, with a notice, so you can resolve them. It is meant for site administrators. Document owners who aren’t administrators normally use the email or the front-end page.

You can also approve or reject from the Pending Version Approval notice on the document’s own edit screen. Administrators and the document’s owner see Preview, Approve and Reject buttons there.

The front-end Pending Approvals page

The setup wizard can create a Pending Approvals page for you, or you can add the shortcode to any page yourself:

Please log in to view pending approvals. Log in

Visitors must log in. Logged-out visitors see a login prompt.
A document owner sees the held versions for documents they own. Administrators see every held version.
The table shows Document, Version, Change, Submitted By and Date, with Preview, Approve and Reject buttons. Reject asks for an optional reason.
To approve or reject here, an owner must also be able to edit the document in WordPress. An owner without editing rights should use the email link instead.
Only documents the visitor is allowed to see are listed. If nothing is waiting, the page says “No pending version approvals.”

The optional show_all="true" attribute is accepted, but administrators already see every pending version, so you normally don’t need it.

Version approval settings

These settings sit on Settings → Version Approval and appear once Enable Version Approval is ticked on the Features tab.

Setting	What it does	Default	Allowed values
Enable Version Approval (Features tab)	Holds new versions for owner approval	Off	On / off. Can only be turned on once an owner assignment or approver role exists.
Auto-Approve Owner Changes	Versions made by the document’s own owner go live without approval, and no email is sent	On	On / off
Email Notifications	Emails the document owner when a version needs approval	On	On / off. When off, versions are still held, so approve them from the admin or the front-end page.
Approval Link Expiry (Days)	How long the link in the approval email stays valid	30	1–365
Approver User Roles (User Management tab)	Roles whose members can publish versions without approval and can be recorded as approvers	None	Any WordPress roles

Approval emails

Email	Sent when	Sent to	Default subject
Version Approval Required	A version is held for approval and Email Notifications is on	The user assigned to the document’s owner title	`[Site name] Version Approval Required: {title}`
Version Change Rejected	A held version is rejected	The person who submitted the version	`[Site name] Version Change Rejected: {title}`

The approval email names the document, the proposed version and change type, who submitted it, and the description of changes. It has three buttons: Preview Changes, Approve Version and View in Admin. You can change both subject lines under Settings → Acknowledgements & Notifications → Email Subject Lines (Version Approval Request and Version Rejected). {title} is replaced with the document title. Your site name is always added in square brackets at the front. Email bodies are not editable in settings.

Multi-stage approval workflow (Pro)

🔒 Pro feature — requires the Pro plugin.

The Free plugin provides single-stage approval: one owner, one approval step. The Pro add-on adds approval chains, where a version must pass through several ordered stages before going live.

Example workflow: A new health and safety procedure requires sign-off from:

The Department Manager (stage 1)
The Safety Officer (stage 2)
The Executive Officer (stage 3)

You set chains up per document in the Approval Chain panel on the document edit screen. Version approval must be on. Each stage has a label and approvers: the Document Owner, an Owner Role, Named Users, or Any with role. Each stage also has a mode, Any one or All must, and an optional deadline in days. Each stage must finish before the next begins. Documents without a chain keep using the single-owner flow. On the Pending Approvals screen, the approve button for a document in a chain reads Approve (bypass chain).

On Free, the Version Approval tab mentions that multi-stage chains are available in Pro. Nothing else changes.

For details, see Multi-Stage Approval Workflow (Pro).

Document review sign-off

Many policies don’t change from year to year, but your auditor still wants proof that someone checked them. The Document Review sign-off lets a document’s owner formally record “this document has been reviewed and is still current” without creating a new version.

Turning it on

Go to Settings → Version Approval.
Tick Document Review Workflow and save. It is off by default. This setting doesn’t depend on Enable Version Approval.

Review dates

Each document’s review timing lives in its Compliance & Status panel:

Review Cycle (days) — how often the document should be reviewed. The default is 365 days, and you can enter 1–3,650. Choosing a Risk Rating suggests a cycle.
Next Review Date — when the next review is due. When it is set, the owner gets review reminder emails before this date.

Recording a review

Open the document. A Document Review box appears in the editor sidebar. It may be collapsed the first time you open a document.
The box shows Last reviewed: with the date and reviewer, and any note. If there is no review yet, it shows “No review recorded yet.”
Optionally add a Review note (optional), for example “Reviewed against current standards — no changes needed.”
Click Mark reviewed and current. You see “Review recorded. Reload to see updated status.”

Recording a review:

adds an entry (who, when and the note) to the document’s review history, which keeps the latest 50 reviews;
moves the Next Review Date forward by the document’s Review Cycle, counted from today;
if the reviewer must acknowledge this document themselves, records their acknowledgement automatically, because signing off the text counts as reading it. This acknowledgement shows source attestation in exports.

Who can record a review: the user assigned to the document’s owner title, and site administrators. Everyone else sees “Only the assigned document owner can record a review.”

Review reminders

Email	Sent when	Sent to	Default subject
Document Review Due	On each day in Review reminder schedule (days before due) (default 30, 7 and 1 days before), then once a day while the review is overdue	The user assigned to the document’s owner title	`[Site name] Review Due: {title}`

You control reminders with Enable Review Alerts (on by default) and Review reminder schedule (days before due) under Settings → Acknowledgements & Notifications. Leave the schedule blank to turn off the advance reminders. Documents with no owner assigned don’t receive reminders. Recording a review stops the overdue reminders, because it pushes the review date into the future.

Documents whose review date has passed count towards Documents past review cycle on the Compliance Overview (see Compliance Reporting & Attestation Exports).

Changelog visibility

The description you write for each version can be shown to staff or kept internal.

Go to Settings → Features → Changelog Description Visibility:

All document viewers (including public) — anyone who can see the document can see the change descriptions
Logged-in users only (recommended) — only logged-in users see them (default)
Editors and Administrators only — only editors and administrators see them

Version numbers and dates are shown in the document’s Version History regardless of this setting. Only the descriptions are affected. Showing descriptions to staff is recommended, because it tells them what changed and why, so they acknowledge an update with context rather than just clicking through it.

What happens to acknowledgements when a document is updated

With the default Re-Acknowledgement Trigger Level (Major changes only):

Change type	Result for existing acknowledgements
Patch	No change. Existing acknowledgements remain valid.
Minor	No change. Existing acknowledgements remain valid.
Major	Existing acknowledgements stop counting. Everyone in the audience must acknowledge the new version. About a minute later, they are sent a Re-acknowledgement Required email.

Set the trigger level to Minor and major changes or All changes under Settings → Acknowledgements & Notifications if you want smaller changes to require re-acknowledgement too.

When approval is on, re-acknowledgement starts when the version is approved, not when it is submitted. If the acknowledgement system is switched off under Settings → Features, no re-acknowledgement happens.

After a triggering update, that document’s compliance rate drops until staff acknowledge the new version. The Compliance Overview shows this, so you can see straight away who needs to read it again.

Version snapshot limit

The plugin keeps a full snapshot of earlier content for restore and comparison. By default, the 20 most recent snapshots per document are kept, and older ones are removed automatically each time a new snapshot is saved. Set the limit to 0 to keep every snapshot. The snapshot list in the editor shows up to the 50 most recent.

Note: This limit applies only to the content snapshots used for restore and comparison. The version history (changelog) and acknowledgement records are not affected by it.

To change the limit: Settings → Content Management → Version Snapshot Limit.

Who can do what

Task	Who
Add changelog entries, edit or delete history, view changes, restore snapshots, schedule updates	Anyone who can edit the document
Publish a version without approval	The document’s owner (with Auto-Approve Owner Changes on), members of Approver User Roles, and administrators using the override box
Approve or reject from the email	Whoever holds the email link (no login needed)
Approve or reject in the document editor	Administrators and the document’s owner
Use the Pending Approvals admin screen	Site administrators
Approve or reject on the front-end page	Administrators, and owners who can also edit the document
Record a document review	The document’s owner and site administrators
Change versioning and approval settings	Site administrators

Daily automation

Once a day, the plugin runs a review check that:

sends Document Review Due reminders (see above);
marks documents whose Next Review Date has passed as overdue, and clears that flag once a review pushes the date forward;
applies any scheduled update whose effective date has arrived but wasn’t applied on time.

Approval links, held versions and scheduled updates need no other action from you.

Limits and edge cases

One held version per document. If a second version is saved while one is waiting, the second replaces the first, and a new approval email is sent. The earlier email link stops working.
Edits without a changelog entry aren’t approved. See the note under Publishing a new version.
Restores bypass approval. A rollback goes live immediately.
No owner, no email. A held version on a document without an assigned owner sends no email. Approve it from Pending Approvals.
Turning approval off doesn’t release waiting versions. Resolve them on the Pending Approvals screen, which stays available.
Email link security. Approval links are single-use, expire after the configured number of days, and are rate-limited against repeated guessing.
Timestamps are stored in UTC. Changelog dates use your site’s date.

Troubleshooting

“Configure at least one approver role or document owner before enabling version approval.” You tried to turn on Enable Version Approval before anyone could approve. Assign a user to an owner title, or choose an approver role, on Settings → User Management, then try again.

The owner never received the approval email. Check that the document has a Document Owner set, that the owner title is assigned to a user with a valid email address, and that Email Notifications is on. If your site’s mail isn’t being delivered, approve from Policy Management → Pending Approvals instead.

“This approval link has expired. Please approve from the admin panel.” or “Invalid or expired approval token.” The link is older than the Approval Link Expiry, or a newer version replaced the one in the email. Approve from the admin or the front-end Pending Approvals page. “No pending version found for this document” means it has already been approved or rejected.

My edits went live without approval. You saved without a Description of Changes, you are the owner with Auto-Approve Owner Changes on, or you hold an approver role. Add a changelog entry to create a held version.

“You do not have permission to approve this version.” on the front-end page. Only the document’s owner (who must also be able to edit it) or an administrator can approve there. Use the email link or ask an administrator.

Worked example: an aged-care provider updates its medication policy

Riverbend Aged Care keeps its policies in the plugin. The Director of Nursing, Priya, holds the owner title “Clinical Policy Owner”, and the Medication Management Policy names that title as its owner. Version approval is on, with Auto-Approve Owner Changes on.

The quality coordinator, Sam (an Editor), rewrites the section on PRN medication. In Version & Changelog he chooses Major, writes “Rewritten PRN administration and documentation requirements”, and clicks Update. The New Version shows 3.0.0.
Staff keep seeing version 2.1.0. Priya receives Version Approval Required: Medication Management Policy.
She clicks Preview Changes to read the new wording, then Approve Version → Confirm approval. Version 3.0.0 goes live, and the changelog records Priya as the approver.
Because the change is Major, every nurse and carer in the audience must acknowledge again, and receives a re-acknowledgement email. The policy’s compliance rate on the Compliance Overview drops, then climbs as staff acknowledge.
Three months later, the Infection Control Policy reaches its review date. Nothing needs changing, so Priya opens it, writes “Reviewed against current guidelines — no change”, and clicks Mark reviewed and current. Its next review date moves forward a year, and the overdue reminders stop.

Was this helpful?