Approval workflows: steps, transitions and approvals

Who this is for. Site builders setting up review for a team, and developers who need to know what a workflow does to the save buttons and to publishing. After this page you can design a workflow, assign it to the right records and predict what each user is allowed to do.

The pieces

Assigning a workflow

Workflows apply to seven record types: blog posts, global components, FAQ pages, FAQ questions, pages, product category descriptions and product descriptions. Books and custom entity records cannot have one.

An assignment is made at one of three scopes, and the most specific wins:

1. One record. For a translated record the assignment is held on the group's parent record, so every language version shares one workflow.
2. One site and one record type, for types whose records can be shared between sites, such as product descriptions.
3. A whole record type, across the account.

When nothing matches, the workflow marked Default applies, if there is one.

What a workflow changes when saving

With a workflow assigned, the save actions described on Revisions and the active revision change: "Save and activate" disappears, "Create branch" appears, and a version becomes active only when its branch reaches the last step. The platform refuses anything else with these messages:

A branch with no step yet, because it is new or was saved before the workflow was added, can always be edited.

Who may apply a transition

The platform checks these in order and stops at the first that passes:

1. the transition's "Who can transition directly" is Everyone;
2. the user is an administrator;
3. the user is in one of the advance groups;
4. every approval group named in "Who must approve the transition?" has recorded its approval on this branch. Then anyone may apply it.

Who may apply a transition and who must approve it are separate lists. Approval groups do not move the branch; they make it movable.

What applying a transition does

• It is refused unless the branch is at the transition's source step. A new branch, with no step yet, must start with a transition out of the first step.
• The branch moves to the target step. The groups in that step's "Notify groups" are notified in the admin and, when "Send notifications via email" (Workflows.sendEmailNotifications, on by default) is on, by email. The subject reads "Approval required: record type name has been transitioned to step step".
• If the target is the workflow's last step by position, the branch's latest revision becomes the record's active revision. The record's published date is not touched.
• If the transition goes backward, to a step with a lower position, every approval recorded on the branch is cleared.

A worked two-step approval

A page needs review by the Editors group and sign-off from Legal and Brand before a change goes live. The workflow has three steps, in position order:

And three transitions:

With the workflow assigned to the page, or to all pages:

1. An author edits the page and saves. The save goes into a new branch; with no step recorded yet, it can be edited.
2. The author applies Submit. Everyone may apply it, so it goes through, and the branch moves to Review. From now on only the Editors group can change content in the branch, and Legal and Brand are notified, in the admin and by email.
3. Legal and Brand each approve the branch. Each group records one approval; a second approval from the same group adds nothing.
4. Someone applies Approve. With both approvals recorded, any user may apply it, not only members of Legal or Brand: the approvals open the transition, and who applies it is a separate question.
5. The branch reaches Live, the last step. Its latest revision becomes the page's active revision. The page's published date does not change: if the page was already published, visitors now see the new version; if it was not, it stays a 404 until someone publishes it (see Published, active and draft: the two gates).
6. If a reviewer applies Send back instead, the branch returns to Draft and both approvals are cleared. Once the author resubmits, Legal and Brand must approve again.