Submit and approve

Every controlled document has one working draft. Nothing you type reaches readers until that draft goes through review and publishes as a new version. Use this page when you are ready to hand a draft to an approver, or when a review is waiting on your decision.

How a review is opened

A review is always addressed to one person. Opening one asks a named colleague to decide it, their name is recorded with the request, and only they can approve or send it back. You may name yourself — in a workspace where you are the only person who can publish, that is the normal way to work, and the request then waits on your own My work page, under Waiting on you.

Opening a review is a server verb — the same one for documents, registers and risks. On a packaged document screen it is the Request approval form, which asks who should approve before it will send. Elsewhere it is called programmatically: by the assistant when you ask it to send something for approval, by integrations, and by the automation layer when it is connected.

A review, however it was opened, is the same unit everywhere: a pinned copy, one named approver, one human decision, one ledger.

Three things block a submit:

• No approver named. A review with nobody on it is a request nobody can finish, so Alchex refuses it rather than opening one.

• An approver who could not publish it anyway. You can only name someone who holds the Owner rung on the record's team — see Who you can name.

• Unresolved required inputs, or an archived document. Fill the placeholders the template marked required; restore the document before submitting.

Opening a review takes an exact, immutable copy of the draft. That copy is what the approver reads, what the decision is recorded against, and what publishes — nothing typed afterwards can reach it.

That copy is also what gets checked. Approving a review runs the same publish checks a direct publish does, against those pinned bytes rather than against the draft as it stands at the moment you decide — so approving cannot issue something different from what you read. One of those checks refuses a document that still carries bracketed placeholders like [the approving role]; another refuses a workflow chip that names a field its record does not have, or a connected source the document's team does not hold. If either fires, the approval is not recorded and the message names what is still open. See Publishing.

A pending review does not lock the record. On every kind — a document, a register, a risk — editing simply continues while the decision is out, and that is safe by construction: the approver is deciding on the pinned copy, and nothing typed afterwards can reach it. What a pending review does hold still is the review's own ground: a document's type and code cannot change while it is under review, the record cannot be archived until the review closes, and a direct publish waits for the decision (or a withdraw) rather than going around it.

Who is notified

The person you named, and nobody else. They get an in-app notification whose Open button lands on My work, where the review is ready to read and decide. Other Owners of the team are not told, because the decision is not theirs.

If you named yourself, no notification is written — you know you just asked, and the review is already on your own My work page, under Waiting on you.

Four things about a document reach a person's inbox:

Both outcomes of a review reach the person who asked for it. A rejection carries the reason; an approval says which version it published as, so "it went out as 2.0" is something you are told rather than something you go and check. An Owner publishing their own draft directly is not notified — they are the one who did it.

The notice lands in the submitter's inbox within about half a minute of the decision, so a review you are waiting on is not something you have to sit and refresh.

All four sit under the Documents switch in Settings → Notifications — on until you turn it off. Worth knowing before you mute it: switching off Documents stops the notice, not the work. The review still needs deciding; you have only asked Alchex to stop telling you about it.

Nothing else about a document notifies. In particular an ordinary reply on a thread you are part of does not, so naming someone is how you actually reach them.

The same inbox also carries notices from registers, from risks you have been made the owner of and actions on them assigned to you, and from long reviews that finish after you have moved on. Each is its own kind of notice rather than one general one, so you can tell them apart by scanning rather than by opening them. The full list is on Your inbox.

Who may approve

The person the review names. Two things have to be true, and they are checked on the server inside the same transaction that applies the decision — never taken from anything the browser sends:

1. They hold the Owner rung on the record's team. In practice a team Owner, or a workspace Owner or Admin (who count as Owner on every team). Writers and Readers cannot decide a review.
2. They are the person it was submitted to. Holding the rung is not enough. Another Owner of the same team opening the review is told: "This review was sent to someone else to decide."

You can approve your own submission. If you named yourself, the review is yours to decide, and Alchex does not stand in the way. This is deliberate: in a workspace where one person is accountable for what publishes, requiring a second person would mean nothing could ever be approved.

If your organisation wants a second pair of eyes, that is a decision you make when you submit — name a colleague instead of yourself. Alchex records who asked and who decided on every review either way, so the trail shows which of the two happened.

Who you can name

Only people who could have published the record anyway: the Owners of its team, plus your workspace Owners and Admins. The Request approval form lists exactly those people, so the question is a menu rather than a guess, and in a one-person workspace the menu is you.

The reason is worth stating plainly, because the restriction looks arbitrary from the outside: approving a document publishes it. If anyone could be named, a Writer could send a draft to themselves, approve it, and publish without ever holding the right to publish. Naming an approver hands over a decision — so it can only be handed to someone who already had it.

Publishing without a review

There is one route that skips review entirely: the server's direct-publish verb, at the Owner rung. Administrative tooling and the automation layer call it; the app offers no publish button. It is recorded in the log as a self-publish, and Alchex refuses it while any review is pending — the review gets decided instead of published over.

Reading the review

While a review is pending, the record says so with one status line — a document's sits in its Document control section (In review — requested by …), and the other record types show the same line in their properties. The full story is the record's Activity trail. Review on the row under My work opens the record in the side panel with what the review changes marked, so you read it and decide without leaving your list — Approve and Send back sit on the same row. A document shows the submitted version against the published one; a document's first version shows whole, since there is nothing to compare it with. The full review surface described below opens from a review notification; on a document it takes over the whole document area, so the diff gets the full reading width, and it is also where you can approve or request changes.

• The header answers "what am I deciding". The version step (v7 → v8 · replaces v7 for all readers), who requested the review and when, the fingerprint the decision will record, and the submitter's summary note. Counters for added, removed and edited blocks sit beside them — click one to focus on just that kind of change.
• The change index lists every change under the section heading it belongs to, with a short excerpt. Click an entry to jump straight to it in the document.
• Only changes is on by default: untouched passages collapse into a Show N unchanged blocks line you can expand in place, while the headings of changed sections stay visible so you keep your bearings. Turn the toggle off to read the document in full.
• Every changed block is labeled Added, Removed or Edited. Edited text shows the old wording struck through next to the new. Tables and other structured blocks show an explicit Was / Now pair instead of a word-by-word diff.
• Step change-by-change with the ↑/↓ arrows in the toolbar, or the J and K keys.

Reviewing an uploaded file. An uploaded file publishes the moment it is uploaded — it has no draft to submit, so this route is voluntary rather than the way its editions reach readers. When you do ask for one, a document whose content is a file has no line-by-line comparison to show, so the review shows the submitted file itself, exactly as it was submitted — alongside who submitted it, when, its fingerprint, and the name of the file it replaces. Approve and request changes work the same way. The editorial-or-material question is not asked — a file has no editorial half-step, so the next whole edition is minted for you and the confirm button names it. What you read is provably what publishes: the approval is pinned to that file's fingerprint. See External documents.

Deciding: approve, request changes, withdraw

The decision actions stay visible in the review header the whole time.

Approving an authored document is one click — there is no confirmation step. Every approval publishes the next version (v7 → v8) — nobody is asked for a number. Every approval is an editorial change by default; when the substance moved, tick Material change on the review surface first. The number is the same either way: what the tick records is that readers should re-read this one. (An uploaded file has no such toggle — see above.) If the submitted copy still carries unfilled [bracketed] placeholders, the surface says so up front and holds the approve button until they are resolved — see Publishing.

Approving is not reversible as a step — to undo it you publish a further version. Once a document has published, it can no longer be deleted at all; Archive retires it and keeps every version, approval and comment. See Publishing.

What publishes is what was submitted, and only that. If somebody kept typing while the decision was being made — which they are free to do — those words are not in that version. They are not lost either: the draft is never rewound to what published, so anything written during the review is still sitting in it, ready for the next round. Submitting and deciding also no longer depend on a separate editing service being reachable, so "try again shortly" is not an answer either of them can give any more.

Reviewing a second round

When an author addresses your comments and submits again, the review screen opens on the new submitted copy. The conversation from the earlier round is not attached to the review — it lives in the document's own Comments panel, in time order with everything else ever said about the document, so checking whether a point you raised was addressed is a matter of reading the panel beside the new copy.

My work

My work in the sidebar is your own page: one table with three tabs across its top, like the sheets of a workbook — Waiting on you, Actions (the risk actions assigned to you) and Sent by you — each with its count; pick a tab and the table below shows that list. Its sidebar count is the number of reviews waiting on you and nothing else. The first tab, Waiting on you, is where the page opens and the one place decisions are made. It lists every pending review submitted to you — including the ones you submitted to yourself. Each row carries Approve, Send back (with an optional note) and View changes, so a decider clears everything from one page. To decide several at once, tick their rows and right-click: Approve asks once and then decides each, and Send back takes one note for all of them; a review you may not decide offers neither, and anything the server refuses is listed as skipped at the bottom of the list; a small panel button on the row opens the record itself, read-only, beside the queue, for when the change only makes sense against the rest of the document; a document's View changes opens the document's full comparison, where the same decision buttons are available beside the diff. The "a review awaits you" notifications land here.

The "Sent by you" tab lists the reviews you raised that are still waiting on somebody else, with the column that matters: who is holding it, and since when. That is the half the page was missing — a review you send to a colleague is not yours to decide, so it used to appear in no list you could open, and a request could sit for days with its author unable to see it or find out where it went. There are no Approve or Send back buttons on these rows, because those are not yours to press. There is Withdraw, on the row and in the right-click menu (tick several to withdraw them together); it asks first, then pulls the request back, and it is also how you unblock a document, since publishing waits on an open review.

A review you sent to yourself appears once, under Waiting on you, with buttons — it is work, not a status, so it is not repeated under Sent by you.

A review addressed to a colleague never appears under Waiting on you, even if you hold the same rung they do: you would not be able to decide it, so offering you a button would only be a refusal waiting to happen.

A review can be handed to an additional person through the server's assign verb. Because a name is what makes a review decidable, adding one hands over the decision too — so the same restriction applies as at submit: you can only add someone who holds the Owner rung on the record's team.

Automation can also open a review — a recurrence asking for a fresh sign-off submits exactly like a person and is recorded as what it is; deciding still always takes a person. When the requester is a document's scheduled run, the row says so: a line under the record names the document whose run is waiting on your decision, and right-clicking the row offers Open the procedure — because approving or sending back is also what resumes that run. Person-filed reviews carry no such line.

A waiting review can also be nudged: a reminder notice that names the record and nothing else — no sender, because the nudge is about the work. Reminders and every other review notice share the Reviews switch under Settings → Notifications.

Everything submitted to you, across every record type, is listed under Waiting on you on My work. Each row names the record, its type, who asked and when; opening the row takes you to the record itself, where the usual decision rules apply. When the review is decided or withdrawn, the row leaves the list — the record's own activity keeps the permanent trail. A decision a process is waiting on also shows in the team's Activity, pinned above the stream until it is made.

Document states

While a document is in review, its type and code are locked — other records cite it by those. A rename is allowed and applies from the version after the one under review.

Related: comments, publishing, versions, permissions.