Approval Workflow

CompassDocs has a built-in editorial workflow so changes to published documents can be reviewed before they go live. Admins choose between two modes from Settings → Workspace.

The two modes

Strict (review required) — default

• An Editor’s changes to a published doc, or a request to publish a draft, become a pending change request in the review queue.
• Approvers and Admins review the queue and either approve (which applies the change live and snapshots a version) or reject it with a note.
• Editors can still freely create and edit drafts — only changes affecting live content need review.

Open (edit freely)

• Editors can publish and update live docs directly, with no review step.
• Approvers still handle suggestions from the review queue.

Switch modes at any time; it only affects how future changes are handled.

The review queue

Approvers and Admins get a Review queue in the sidebar (with a badge showing the number of open items). It gathers two kinds of work:

• Change requests — proposed edits/publishes awaiting approval (strict mode).
• Suggestions — notes from any signed-in user proposing an edit.

Each change request shows the proposed title and content; approving it updates the document, records a new version attributed to the original author, and notes who approved it. If the submitter attached a change note, the approved version keeps it (with “approved by …” appended). From 1.10.1 the version also stores the approver’s name, the submitter’s name and the change request as fields of its own, so a read-confirmation record can say who approved the version people confirmed without parsing the note. Each card opens Changes vs live: the proposed text rendered as a diff against the live document, with one sentence sizing the change (“Looks editorial: 14 words in one paragraph changed (1.1% since v12).”).

The same rules cover version restores and draft-branch merges: in strict mode an editor’s restore or merge on a published document lands in the queue as a change request, while approvers and admins apply theirs immediately.

Documents that require read confirmation. A change request that changes the text of such a document carries the submitter’s recommendation for its readers: editorial fix (keep their confirmations) or material change (ask everyone to re-confirm), with their reason. Approving applies that recommendation unless you decide otherwise; a request that carries none, or one whose reason no longer meets the reason rule, asks you before it is applied. The card says what approving does, in a chip beside Edit: Resets 42 confirmations (the submitter recommended a material change), Keeps 42 confirmations (editorial) (an editorial fix), Decision needed. 42 confirmations (no recommendation; approving opens the question), Metadata only. Confirmations unaffected (nothing in the text or the title differs from the live document) or Confirmations unaffected (the proposed text is the version people confirmed). Under the title, “Alex recommends: editorial fix. “fixed broken link to the expenses form”“ repeats the recommendation and its reason. Approve on a request that changes the text opens the same question the editor answers when saving, titled “Approve changes to a confirmed document?”, with the recommendation pre-selected and the note prefilled from the submitter’s reason; you may keep it or override it, what you leave in the note is the version note and the recorded reason (the request’s own note when you leave it empty), and the button says what will happen (Approve. Keep confirmations / Approve and ask 42 people to re-confirm). A metadata-only request approves without a question. Both the recommendation and the decision are recorded on the document’s History tab (“recommended by Alex, approved by Priya”), and the author’s notice says what happened: “Confirmations kept.” or “42 people asked to re-confirm.” For scripts, PATCH /api/change-requests/{id} takes ack_policy and ack_reason and needs change_request.decide on the document’s own space (see Change request decisions (API)).

Suggestions

Any signed-in user — including Viewers — can leave a “suggest an edit” note on a document. Suggestions don’t modify the doc; they land in the review queue for an Approver or Admin to triage (accept or dismiss). This is a low-friction way to capture fixes from people who don’t have edit rights.

Choosing a mode

• Use strict for regulated or high-stakes knowledge (policies, compliance, security runbooks) where a second set of eyes matters.
• Use open for fast-moving teams that trust their editors and value speed over gatekeeping.

Notifications (Webex, Teams, Slack, email)

Under Settings → Notifications, admins can register notification channels so workflow events land in your chat tools — or inboxes — the moment they happen:

• Change submitted for review — an editor’s change is waiting in the queue
• Change approved / Change rejected — a reviewer made the call
• Document published — a doc went live directly
• Suggestion left — a reader submitted feedback

Each channel can be scoped to specific spaces (leave unchecked for all), so #engineering only hears about Engineering docs.

Setup per platform:

• Webex: add the Incoming Webhooks app to a space and copy its URL.
• Microsoft Teams: in the channel, create a Workflow from the “Post to a channel when a webhook request is received” template and copy its URL (CompassDocs sends Adaptive Cards).
• Slack: create an Incoming Webhook for the channel.
• Email: configure the Email (SMTP) section on the same page (any relay works — Microsoft 365, Google Workspace, SES, Postmark…), then add an Email channel with comma-separated recipients.
• Anything else: choose Generic JSON and point it at your own receiver.

Paste the URL, pick the events, and hit Test to see a message appear. Deliveries run in the background (they never slow down a save), each hook shows its last delivery status, and webhook URLs are stored write-only since they embed the channel secret.