Approvals

An approval is a gate. A page sits in a state, reviewers weigh in, and the page only moves on once their verdict crosses a threshold you configure. For the configuration UI, see the workflow builder.

Reviewers

A reviewer is a user, a group, or a variable that resolves to users or groups. You configure them once in the builder under the approval transition; from there they’re the preassigned reviewers.

The preassigned list is resolved into a concrete reviewer set the moment the page enters the approval state, not when the workflow is applied. Variables are evaluated against page, page-property, and space-variable values at that instant. Once resolved, the list is frozen on the workflow instance: changing a variable’s value, editing the variable on the page, or editing the reviewer list in the builder has no effect on a pending approval. To re-resolve, the page must leave the state and come back in.

Groups are the exception. A group reviewer is stored as a group, not as the list of its members, and membership is checked when somebody clicks Approve or Reject.

Group reviewers are evaluated at click time

Reviewer groups are not snapshotted with the rest of the reviewer list. Adding a user to a reviewer group while an approval is pending lets them act immediately; removing them takes the ability away. For a fixed reviewer set, name users directly instead of using a group.

Adding reviewers on the fly

When Allow adding reviewers on the fly is on, reviewers can be added and removed after the approval has started. By default anyone with edit permission on the page can manage reviewers; Only existing reviewers can add reviewers restricts that to users currently on the reviewer list. Preassigned reviewers cannot be removed — only on-the-fly additions can be taken back out.

Reviewers added this way are full reviewers and count toward Min. approvals and Min. rejections the same as preassigned ones. The person adding them chooses, per action, whether to send the new reviewer an email. If a removal pushes the remaining approvals over the threshold (or, under Require all reviewers approval, leaves no one outstanding), the workflow transitions immediately on removal.

Initially notify reviewers via email controls the one-shot email sent when a page enters the approval state. It goes to every preassigned reviewer, with groups and variables resolved to individual accounts. On-the-fly additions don’t trigger it — they have their own opt-in toggle in the add-reviewer dialog.

Thresholds

By default an approval requires one approval and one rejection — first response wins. Min. approvals and Min. rejections raise either bar. The thresholds are tracked independently and run as a race: with Min. approvals of 2 and Min. rejections of 1, a single rejection moves the page to the rejected state immediately, even if one approval is already in. Whichever threshold is reached first decides the transition.

Counting is by distinct user. Someone on the reviewer list twice — named directly and also a member of a reviewer group — counts as one vote. Group reviewers don’t contribute on their own; only the actual users behind them, when they click, do.

Require all reviewers approval replaces counting with unanimity. Every individually named reviewer and every member of every reviewer group must approve before the page transitions. Group membership is resolved on each click, so adding a person to a reviewer group while the approval is pending means that person must now approve too. A single rejection still moves the page to the rejected state — unanimity applies only to the approval direction. Because membership is live, deactivated users or users removed from all reviewer groups drop out of the set instead of blocking it.

Require comment on rejection is enforced in the UI: the reject dialog won’t submit without a comment.

Reminders

With an Email reminder configured, the first reminder is scheduled for the Send X after transition delay after the page enters the state. Reminders dispatch on an hourly tick, so a 30-minute delay fires at the next hour boundary rather than exactly 30 minutes in. Only reviewers still pending receive them.

If repetition is on, each reminder schedules the next one at the configured interval after itself. Otherwise the reminder fires once and clears. The schedule clears automatically when the approval completes, so nobody gets a reminder for a decision already made.

Approve and reject emails

Each approval transition can carry an email that fires on approval and another on rejection, sent the moment the workflow transitions. Recipients are resolved at send time: Author, owner, and last editor are read fresh from the page, so the right people get the email even if those roles changed during the review. Pending reviewers resolves to whoever was still pending on the just-completed approval. Variables in the recipient list are evaluated against current page and space values per send.

These emails fire as part of the transition and have no delay of their own. For deferred or scheduled emails, use a send-mail action on the destination state.

Editing a workflow mid-approval

The builder shows an orange unsaved-changes indicator the moment a workflow is in use. Saving while approvals are pending is allowed, but changes hit live instances asymmetrically. Anything read at click time — group memberships, comment requirements, threshold values, custom button labels, email contents and recipient rules — picks up the new value immediately. Anything snapshotted at state entry — the resolved preassigned reviewer list, the reminder schedule — keeps the old value until the page transitions out and back in.

Editing thresholds or adding a recipient to an approval email takes effect on every pending approval the next time someone clicks, but editing the reviewer list does not change who’s already been assigned. To reshape an approval that’s actively running, transition the affected pages back to a previous state and forward again, or reset the workflow.

Custom button labels

Under Advanced, Use custom labels for approve / reject buttons replaces the default Approve and Reject labels with anything that fits — Publish, Sign off, Send back. The labels are cosmetic. Reviewers see them on the buttons in the page sidebar and in approval emails, but the underlying transitions, thresholds, comments, history events, and analytics are identical. A “Publish” click still records as an approval and a “Send back” click still records as a rejection.