Every approval in Appmint is a workflow with a waiting stage that names who decides, and two outcome stages: one that says yes (status approved) and one that says no (rejected). Asking creates a task on that workflow; the people on its waiting stage see it in their Approvals tray and by email, and deciding moves it to an outcome. Two such workflows come with every org:
| Workflow | What waits | Who decides (as shipped) | Reminder | Starts |
|---|---|---|---|---|
publish-approval "Publishing approval" | publishing a page, post, crm_form or sf_product | anyone with the ContentAdmin, Publisher or Owner role | the Owner is added after 2 days | switched off |
access-approval "Access request approval" | a person asking for a screen or menu item their role doesn't include | ConfigAdmin or Owner | the Owner is added after 3 days | on |
The first person on the stage to decide decides (required: 1). AI employees ask for approval the same way, on ai-employee-approval: see Review what an AI employee did. For what publishing does to a page, see Publish, unpublish, preview and restore a page. For building a stage workflow of your own with deadlines, see Stage workflow with SLA timers.
Ask first
- Publishing review, an access request, or both?
- Which content must be reviewed? The shipped workflow reviews pages, posts, forms and products together. Say if only some should wait.
- Who reviews? By role (anyone holding it), a group, or named people. How many must agree, and is it one level or two (an editor, then the owner)?
- When should it chase? After how long, and who is added when nobody has answered.
- For a decision: which request, and the person's own answer. The AI never decides an approval for anyone.
Steps
1. Workflow: read the approval workflows
call_appengine GET /workflow/definition?name=publish-approval (and access-approval). Note its sk, enabled, collections and its stages. Then, per kind of content, GET /workflow/publishing/<datatype> (page, post, crm_form, sf_product): { "required": true, "workflow": {…} } when publishing it waits on a review now, required: false when it goes straight out.
access-approval is made the first time anyone asks for access; staff can make it ahead with POST /approval/setup. publish-approval exists switched off in every org that has it; if it is missing, POST /workflow/definition/from-template/publish-approval makes it, still off.
Hands on: each workflow's sk and its stages.
Check: in Studio, Workflow (/workflow) › Definitions lists both, with Enabled on or off.
2. Workflow: who reviews, how many, and when it chases
Each stage that decides carries these fields:
| Field | What it does |
|---|---|
assignRule.type | roles (everyone holding one of roles, directly or through a group), group (a group's members), users (users: emails), relative (the requester's supervisor, manager, department-head or location-manager, from employee records), field (an email at a path on the record) |
assignRule.mode, assignRule.required | any with required: N: N of the stage's people must approve, in any order, one each. all: everyone on the stage. |
assignRule.fallbackRoles | Who decides when the rule finds nobody. With none, the Owner. |
rejectPolicy | any-rejects (default): one decline ends it at the no outcome. when-unreachable: only once enough approvals can no longer come. |
allowAdminOverride | Default on: an Owner or ConfigAdmin who isn't on the stage may decide for it, giving a reason that is kept on the task. Off: only the stage's people. |
escalations[] | The chase: escalateAfter + units (minutes, hours, days), escalateRule (who is added, the same shape as assignRule) or escalateTo (emails), notificationTemplate (approval-reminder, approval-reminder-notification). Each tier counts from the moment the one before it fired. |
notificationTemplate | What the stage's people get when it reaches them: approval-requested (email) and approval-requested-notification (tray). |
The person who asked is never one of the deciders: the rule leaves them out.
For two levels, put a second deciding stage between the first and the outcomes (type: "intermediate", its own assignRule). Approval on the first moves it to the second; only the last one lands on the yes outcome.
Change it with PATCH /workflow/definition/<sk> and { "stages": [ …every stage… ] }.
stagesis replaced whole. Send every stage back, keeping eachid, and keep both outcome stages: atype: "done"stage withmodelStatus: "approved"and one withmodelStatus: "rejected". Without both, nothing can be decided (not-a-decision). Their names are free.- To review only some content, change
collections(PATCHwith{ "collections": ["page"] }). Every type listed waits once the workflow is on.
Hands on: the saved stages.
Check: GET /workflow/definition/<sk> reads back what the person asked for, in Studio the definition shows Who decides on the waiting stage and its SLA Escalation Tiers.
3. Workflow: switch publishing review on
Stop: from now on, nobody's Publish puts a page, post or form live until a reviewer says yes, and every request emails the reviewers. Show the person who reviews, how many must agree, what it reviews and when it chases. Wait for a yes.
PATCH /workflow/definition/<sk> with { "enabled": true }. To switch it off again, { "enabled": false }: requests already waiting stay open and can still be decided.
Check: GET /workflow/publishing/page answers required: true. In Studio the workflow's Enabled box is ticked.
4. Approvals: asking
Publishing. Build Studio's Publish, a post's publish and a CRM form's publish ask first. The same question over the API: POST /approval/ask with { "target": { "kind": "record", "operation": "publish", "datatype": "page", "id": "<id>" }, "request": { "reason": "…" } }.
decision | Means |
|---|---|
allowed | No review for this type. Publish as usual. |
pending | A request is open: taskId, approvers, escalatesAt. Don't publish. |
already-pending | One for this record is already open. Don't ask again. |
When the yes comes, the engine publishes it as it is saved at that moment: a page or post gets its live copy, a form or product is marked published. Edits made while it waits go out with it. Publishing through POST /repository/publish/… doesn't ask (see the publish page).
Access. A person who opens a screen or menu item their role doesn't allow sees Ask for access with a reason to pick. The request is always for the person signed in: POST /approval/ask with { "target": { "kind": "screen", "path": "/automation" }, "request": { "reason": "Covering for someone", "label": "Automation" } } (kind: "menu" for a menu item). It answers pending with requestId, taskId and approverNames, or already-pending. The person can withdraw it while it waits: POST /approval/request/<requestId>/cancel.
The reasons offered come from Settings (/settings) › Approval reasons: "Why someone asks" and "Why an approver declines" (GET /approval/reasons reads them).
| Step | Who is told |
|---|---|
| Asked | the deciders: approval-requested email and tray line; the asker: approval-received |
| Withdrawn | the deciders: approval-cancelled |
| A reminder tier fires | the people it adds (or those who haven't acted): approval-reminder |
| Handed on | the new people: approval-requested |
| Decided | the asker: approval-approved or approval-rejected, with the note |
Stop: asking emails the deciders. Say who, before asking on someone's behalf.
Hands on: the taskId. Check: the asker sees it in Approvals › My requests, the deciders in Waiting on you.
5. Approvals: deciding
GET /approval/tray lists what waits on the signed-in person (waitingOnMe: id, title, payload with who asked and why, required, approvals so far), their own open requests (myRequests) and their tray lines (notices). GET /approval/task/<taskId> reads one, for anyone it involves or an admin, with mayDecide.
Stop: each decision is the person's. Show the request: what it is, who asked and why, and for an access request what it would open. Wait for their answer on that request.
| Action | Call | Notes |
|---|---|---|
| Approve | POST /approval/task/<taskId>/approve with { "note": "…" } | An access request must say how: "grant": { "via": "role", "name": "ContentAdmin" } or { "via": "group", "name": "<group>" }. |
| Decline | POST /approval/task/<taskId>/reject with { "note": "…" } | Pick the note from the decline reasons when it fits. |
| Hand on | POST /approval/task/<taskId>/reassign with { "assignTo": ["<email>"] } | Staff in this org only, never the asker (No one in this team signs in as …). |
| Escalate now | POST /approval/task/<taskId>/escalate | Runs the stage's next reminder tier now; answers who was added. |
What the answers mean:
{ "waitingOn": […], "approvedBy": […], "required": 2 }withoutgranted: counted, not finished. It waits on the others. A second approval by the same person still counts once.{ "next": { "name", "assignTo" } }: it moved to the next level.{ "granted": "the ContentAdmin role" }or"published": done, and the asker is told.403 override-reason-required: the person isn't on the stage but is an Owner or ConfigAdmin. Send"overrideReason": "<why>"only if they give one; it counts as one approval and is kept on the task (tested).403 This is not waiting on you,403 own-request(nobody decides their own access request),403 ai-employee(an AI employee can't decide),409 Already approved/Already rejected.400 grant-required,grant-invalid(no such group),grant-refused: access is never given through the Owner, Customer, Guest, System or AI roles, a root role, or a group carrying one.
Staff decide in Approvals (/approvals, ?tab=mine|notices|decided, ?task=<taskId> opens one): Approve, Decline, Grant through a role or group, a comment, Reassign, Escalate. Decided (GET /approval/history) lists what they decided and the answers to their own requests.
Decide an approval through Approvals, never by moving its task on a workflow board. A board move to an outcome is refused for these (decide-through-approvals), because only Approvals grants the access, runs the publish and tells the asker.
Hands on: the decision and what it did. Check: publishing: the badge says Published and the live copy is there (see the publish page). Access: the person's user now has the role or is in the group, and their request shows Approved with the grant. Declined: the asker's request shows Declined with the note.
When it's done
Tell the person:
- whether publishing review is on, for which content, who reviews, how many must agree and when it chases;
- for each request: who asked, who decided, the answer and note, and what it did (published, the role or group granted);
- who was emailed at each step.
Open Approvals (/approvals).
What it can't do yet
- Products aren't asked in Studio. Publishing review lists
sf_product, but the product screens publish without asking; onlyPOST /approval/askmakes a product wait. - The waiting status is written onto the record. Read from the code: while it waits and once decided, the stage's status is copied onto the record's own
data.status(pending, thenapprovedorrejected), because the workflow lists that type. On a product that replaces its stock status (available,sold-out…); on a form, its status. Check both after a decision. - Escalate past the last tier adds nobody. On a stage whose reminder tiers have all fired, or that has none, Escalate reports success, adds nobody and sends the request again to whoever hasn't acted (tested on a stage with no tiers:
added: []). - One-off access. Access is always a role or a group, and stays until someone removes it. There is no expiry.
- Ask for someone else. An access request is always for the person signed in.
- Review only one kind of change. Publishing review is all or nothing per record type: every publish of a listed type waits.
- Time off and payroll have their own approval rules in their apps; they show in the same tray but are decided by those apps' levels.
Don'ts
- Don't switch publishing review on without a yes, and don't switch it off to get one page out.
- Don't decide, or "approve them all", for the person. Each request, their answer.
- Don't send an
overrideReasonthe person didn't give. - Don't move an approval's task on a board, and don't edit a task's
approvals(the engine refuses both). - Don't replace
stageswithout both outcome stages. - Don't publish through the API to get round a review.