How-to library · Developer docs

How-to library

Task-shaped pages: a title that starts with a verb, the situation in a few lines, the steps, the working code in both engines, and why this way rather than another. Found from a search, done, and left.

How-to Content modelling

Set up an approval workflow before publishing

Published

A workflow is steps and transitions assigned to a content type or one record. Once assigned, every save goes into a branch; approval groups must all approve a gated transition; reaching the last step activates the revision. Publishing stays separate.

Context

Context. Legal and Brand must sign off before a page goes live. The platform has a full approval workflow that almost nobody switches on: a workflow is a set of steps and transitions, assigned to a content type or to one record. Once assigned, an author cannot save a plain new version; every save goes into a branch that sits in a step, collects approvals and comments, and is moved by transitions. Supported: pages, posts, FAQ pages and questions, global components, product and category descriptions.

Steps

  1. Create the groups if they do not exist: Editors, Legal, Brand.
  2. Create the workflow with three steps: Draft (everyone may edit), Review (only Editors may edit; notify Legal and Brand), Live (the last step).
  3. Add transitions: Submit from Draft to Review, open to everyone; Approve from Review to Live, not open to everyone, approval groups Legal and Brand; Send back from Review to Draft, open to everyone.
  4. Assign the workflow to Pages (or to one page for a trial). Authors now save into branches; reviewers approve; when both approvals are present anyone can apply Approve, which activates the branch's latest revision.
  5. Set the published date as before: activation does not publish.

Template code

Template code 
{* an editor-only notice on the page, for signed-in users, when changes await review *}
{if $_currentUser->isLoggedIn() && $page->hasAssignedWorkflow() && $page->getBranches()->count() > 0}
  {$_response->preventCaching()}
  <div class="editor-note">This page has {$page->getBranches()->count()} branch(es) in review; visitors see the active version.</div>
{/if}
{% if _currentUser.isLoggedIn() and page.hasAssignedWorkflow() and page.getBranches()|length > 0 %}
  {% do _response.preventCaching() %}
  <div class="editor-note">This page has {{ page.getBranches()|length }} branch(es) in review; visitors see the active version.</div>
{% endif %}

Why this and not that

Not a "draft" convention agreed by email: drafts are per author and invisible to reviewers; a branch is shared, commented and logged. Not a transition with no approval groups and "everyone" switched off: it is open to everyone in practice. Moving a branch backwards clears its approvals, and once a branch reaches the last step no more versions can be added to it. Emails go to the target step's notification groups unless the module's email setting is off.

Go deeper
GuideRevisions and the active revision GuideOne table, four types

Was this page helpful?

Your answer goes to the docs team.