Setting Up Content Approval

Content approval lets some people write and edit pages and posts without being able to publish them. They send their work to a publisher, who publishes it, schedules it, or sends it back with a note. Every step is recorded.

This guide is for site administrators: it covers choosing who publishes, setting up the roles, and checking it works.

How it works

It all comes down to two permissions:

• publish wranglerpages for pages
• publish posts for posts (the items in every collection)

Someone who can edit pages but doesn't have publish wranglerpages is an editor: their new pages start as drafts, live pages open read-only with Edit a draft of this page, and they send their work for review with Submit for review. Someone who has it is a publisher: they can publish and take down pages, change live pages, and approve or send back what editors submit. Posts work the same way with publish posts.

Approval is off until you set it up. When content approval was added, every role that could update pages was given publish wranglerpages (and the same for posts), so nobody's access changed. You turn approval on by taking the publish permission away from the roles that should need approval.

Super admins can always do everything, and never need approval.

Before you start

You need to be able to edit roles and users (a super admin can). A few things are set up by a developer rather than in the admin. Check them first:

What	Why it matters
The editor role is allowed into the admin	Only roles listed in the site's admin_roles setting can open the admin. A new role you create isn't, until a developer adds it.
A queue worker is running	Approval emails are sent through the queue. Without a worker, nobody is told about submissions.
Laravel's scheduler is running	Scheduled publishing only happens if the site's scheduler runs every minute.

The quick way: one command

A developer can create both roles in one go:

php artisan textstem:approval-roles

This makes an editor role and a publisher role with the permissions in Steps 2 and 3, and the view-dashboard permission so both can use the dashboard. It reuses roles that already have those names and keeps their other permissions. It also lists what still needs doing: roles to add to admin_roles, editors who can still publish through another role, and other roles that publish without approval. Different names can be given with --editor= and --publisher=, and --dry-run shows the changes first.

After running it, carry on from Step 4. To set the roles up by hand instead, or to adjust them afterwards, follow the steps below.

Step 1: Decide who publishes

Write down who should be able to publish pages, who should be able to publish posts, and who should only send work for review. A common set-up:

Role	Pages	Posts
Editor	Writes and edits; needs approval	Writes and edits; needs approval
Publisher	Publishes, and approves editors' work	Publishes, and approves editors' work

Pages and posts are separate, so a role can publish posts but need approval for pages, or the other way round.

Step 2: Set up the editor role

Go to Admin → Roles and open the role (or click Create to make one). Tick the permissions editors need, and make sure the publish permissions are not ticked:

Area	Tick	Leave unticked
Pages	list wranglerpages, view wranglerpages, create wranglerpages, update wranglerpages	publish wranglerpages
Page blocks	list wranglercomponents, view wranglercomponents, create wranglercomponents, update wranglercomponents, delete wranglercomponents
Posts	list posts, view posts, create posts, update posts	publish posts
Supporting	list assets, view assets, create assets, update assets, list tags, view tags, list categories, view categories, view-dashboard

The block permissions matter: without them editors can open a draft but can't change its content. The supporting permissions let editors add images, pick tags and categories, and use the dashboard. Add delete wranglerpages or delete posts only if editors should be able to delete their own drafts. Deleting anything live needs the publish permission anyway.

Click Update. The change applies straight away to everyone with the role.

Step 3: Set up the publisher role

Open the publisher role and tick everything the editor role has, plus publish wranglerpages, publish posts, delete wranglerpages and delete posts. Click Update.

Step 4: Give people their roles

Go to Admin → Users, open each person, tick their role under Roles and click Update.

Check for a second role. Permissions add up across roles, so someone who has the editor role and also another role with publish wranglerpages is still a publisher. Make sure editors have no other role that can publish.

Step 5: Check it works

Use Impersonate on an editor's user page to see the admin as they do:

1. Create a page. Its Status shows as text rather than a menu, and there's a Submit for review button.
2. Submit it, with a note.
3. Open a live page. It's read-only, with Edit a draft of this page.
4. Leave impersonation.

Then, as a publisher, open the page you submitted: it shows who sent it and the Approve & publish, Approve & schedule and Request changes buttons. Publishers who use the dashboard can add the Waiting for review widget, which lists everything waiting for them; editors get Your work in review instead. If the dashboard doesn't open for someone, their role is missing the view-dashboard permission.

Optional settings

Two settings change how approval behaves. A developer sets them in the site's environment.

Setting	What it does	Default
Two-person rule (TEXTSTEM_APPROVALS_TWO_PERSON)	Publishers can't approve their own submissions; another publisher has to. Publishers can still edit and publish live content directly.	Off
Idle drafts (TEXTSTEM_APPROVALS_COPY_DAYS)	Drafts of live pages and posts that nobody has touched for this many days are cleared, after a warning email a week before. Drafts waiting for review or scheduled are never cleared. 0 keeps them for good.	90 days

Emails

Approval emails are sent in English:

• Every publisher (except the author) is emailed when something is submitted, and when a scheduled item couldn't be published at its time and went back to review.
• The author is emailed when their work is published, scheduled, or sent back with a note.
• The people who worked on a draft are emailed a week before it's cleared for being idle.

Troubleshooting

Problem	What to check
An editor can still publish	Their roles: one of them still has publish wranglerpages or publish posts. Super admins can always publish.
An editor can't sign in to the admin	Their role isn't in the site's admin_roles setting. Ask a developer to add it.
An editor can open a draft but not change its blocks	The role is missing the wranglercomponents permissions in Step 2.
A submitted page can't be changed	That's expected: what the publisher reviews is what was sent. The editor can Withdraw it to edit it again.
Nobody is emailed about submissions	The queue worker isn't running, or the site's mail isn't set up.
A scheduled page didn't go live	The scheduler isn't running. Or the live page changed after the draft was made, or the publisher who scheduled it can no longer publish: then it goes back to review with a note, and publishers are emailed.
A draft disappeared	It was idle for longer than the idle-drafts setting and was cleared. The live page wasn't affected.

For how approval works in detail, including what's recorded, see the developer guide to content approval.