> For the complete documentation index, see [llms.txt](https://docs.notionapps.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.notionapps.com/automation/approval-workflows.md).

# Approval Workflows

## Approval Workflows

### Approval Workflows

#### Approval Workflows

**Approval Workflows**

**Approval Workflows**

An approval workflow routes a submitted record to someone who can approve, reject, request changes, or escalate it. Use approval workflows for purchase requests, timecards, refunds, budget exceptions, access requests, content reviews, policy reviews, and any process where a person must make a decision.

![Approval workflow setup controls.](https://content.gitbook.com/content/5ZqDXcVVffWUqEIZVhmn/blobs/rejdqrxvGQLyYof5HL31/assets/automation-wizard-e2e/02-approval-workflow-destination.png)

*Approval setup should make the starting event, reviewer, decision destination, and requester result visible.*

**Approval screen naming**

In the builder, approval review experiences are built from the actual native screen names makers can add to an app:

* Decision - the reviewer opens one item and chooses an outcome.
* Work Queue - a team sees multiple requests to claim, assign, prioritize, or complete.
* Workflow Status - the requester tracks what happened after submitting.
* Notification Center - recipients see alerts and reminders.
* Conversation - requester and reviewer discuss missing information.
* Exception Resolution - makers diagnose failures.

**Required pieces**

A customer-ready approval workflow needs:

* A request page where the user creates or edits the source record.
* A real submit action or submitted status that starts the workflow.
* A reviewer rule that resolves to a real user, role, team, owner, requester, reviewer, or selected user field.
* A Decision screen for reviewer action.
* A Work Queue when a team handles many approval items.
* A Workflow Status or source status field for the requester.
* Messages that explain what happened.
* Exception handling for missing reviewer, missing required data, failed delivery, and permission issues.
* A live test that proves the request appears for the reviewer.

**Step-by-step setup**

Use this order for a first approval workflow. The screens are part of the setup; they are not an optional afterthought.

1. Create or confirm the request page. This is the normal data or form screen where the requester creates the record.
2. Make required fields obvious to the requester. The reviewer should receive enough context to decide without asking the maker what the record means.
3. Add a Submit action the user will actually click.
4. Make sure Submit writes the submitted status the workflow will listen for. For example, if the button writes **Submitted**, the workflow should listen for **Submitted**.
5. Open **Automation** and choose **Approval workflow**.
6. Set **When this happens** to the real Submit action or exact status change.
7. Choose the reviewer rule. Use a reviewer field, role, team, manager field, selected user, or fixed approver depending on the app.
8. Choose **Decision** as the primary reviewer destination. This tells NotionApps the reviewer needs an approve/reject/request-changes decision surface.
9. Add **Work Queue** when multiple reviewers or a team need a shared list. Most production approval apps should use a Work Queue because reviewers need an inbox.
10. Add **Workflow Status** if requesters need a separate status screen.
11. Write the reviewer message.
12. Write the requester confirmation.
13. Map Approve, Reject, and Needs changes to source record statuses.
14. Add exception handling.
15. Create the Work Queue Automation screen for the reviewer inbox. Name it something obvious, such as **Approval Inbox** or **Purchase Approval Inbox**. Bind it to the approval workflow.
16. Create the Decision screen. Name it something obvious, such as **Approval Decision** or **Purchase Approval Decision**. Bind it to the same approval workflow. This step is required for approve, reject, and request-changes actions.
17. Set visibility so requesters see requester screens and reviewers see reviewer screens.
18. Add the Work Queue to the reviewer navigation menu.
19. Validate.
20. Create a test request.
21. Preview as requester and reviewer.

**Do not skip the approval screens**

The approval workflow is the engine, but it is not the full user experience. A reviewer needs screens inside the app. Add them before the first test request.

Create these screens from **Screens -> New Screen -> Automation**:

| Screen to add     | Screen type | Bind it to                 | Who should see it                            |
| ----------------- | ----------- | -------------------------- | -------------------------------------------- |
| Approval Inbox    | Work Queue  | The approval workflow      | Reviewers, managers, or approval teams       |
| Approval Decision | Decision    | The same approval workflow | The reviewer opening or claiming one request |

The Work Queue answers: **What approval requests are waiting for me?**

The Decision screen answers: **What am I approving, and what action should I take?**

If these screens are missing, the workflow may still exist, but the maker will not have a clear reviewer experience to test.

**Create the Decision screen as its own step**

Do not assume the approval wizard creates a visible reviewer screen just because you selected Decision as the destination. The destination choice tells the route what kind of review experience to use. The maker still needs to create or confirm the actual **Decision** Automation screen in the app.

Create it from **Screens -> New Screen -> Automation -> Decision**. Bind it to the same approval workflow as the Work Queue. Make it visible to the reviewer role. Test it before publishing.

**Reviewer experience checklist**

The reviewer should be able to answer these questions without calling the maker:

* What request am I reviewing?
* Who submitted it?
* Why is it needed?
* What amount, dates, priority, or risk should I consider?
* What decision buttons are available?
* What happens if I approve?
* What happens if I reject?
* Where can I ask for clarification?

**Requester experience checklist**

The requester should see:

* The request was submitted.
* Who or what team is reviewing it when that information is appropriate.
* The current status.
* Any request for changes.
* The final result.

**Troubleshooting**

| Symptom                                   | Likely cause                                  | Fix                                                                                        |
| ----------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Submit does nothing                       | Trigger is wrong or status mismatch exists.   | Reconnect When this happens to the real Submit action and exact status value.              |
| Reviewer sees nothing                     | Recipient, scope, or permission issue.        | Check reviewer rule, role membership, Decision screen access, and source data permissions. |
| Item appears but no decision buttons work | Outcome mapping is missing.                   | Map decision actions to source record status and messages.                                 |
| Requester never sees the result           | Source record is not updated after decision.  | Map Approved, Rejected, and Needs changes back to the record.                              |
| Failure is invisible                      | Exception screen is missing or not connected. | Add Exception Resolution and retest.                                                       |

**Related pages**

* Create your first approval workflow
* Decision and approval work queues
* Submit Button Troubleshooting

**Current approval setup behavior**

````
Approval setup now participates in the same outcome-first Automation flow as Workflow and Messaging. A maker can describe the approval result first, and NotionApps uses the approval provisioning path when the outcome requires approval-specific screens or approval routing.

Start with business language such as:

```
Route this request to a manager for approval and let the requester see the decision.
```

NotionApps then guides the maker through the approval setup:

1. **Detect the approval outcome.** The builder recognizes approval, review, decide, reject, hold, claim, or manager-review language.
2. **Ask for the missing business details.** The maker chooses the request source, reviewer path, destination screen, decision behavior, and test record details.
3. **Create the approval route.** NotionApps uses the approval provisioning path to create or validate the approval workflow, decision surface, work queue, and related route objects.
4. **Run validation.** The maker should confirm that the approval setup is valid before publishing.
5. **Test as real personas.** Submit a request as the requester, review it as the approver, and confirm that the final status and Activity trail are clear.

Approval Management is separate from Workflow and Messaging entitlement. Workflow can move the process forward, and Messaging can carry comments or notifications, but approval-specific surfaces such as Decision screens, Work Queues, and approval setup require Approval Management access.

**What proof should look like**

A complete approval test should show all of these results:

| Step                       | Proof                                                                         |
| -------------------------- | ----------------------------------------------------------------------------- |
| Request submitted          | The request record is created or updated.                                     |
| Approval routed            | The item appears for the intended reviewer, queue, or role.                   |
| Decision captured          | Approve, reject, hold, or request-changes action records the outcome.         |
| Workflow continues         | The next workflow step runs or waits as configured.                           |
| User can understand status | Requester, reviewer, and builder can see the state from a screen or Activity. |

If any proof step is missing, use the repair-first guidance in Automation before publishing live.Current approval setup behavior

Approval setup participates in the same outcome-first Automation flow. The maker describes the approval result and NotionApps creates or guides the approval route.

Example outcome:

> Route this request to a manager for approval and let the requester see the decision.

The builder should help the maker answer these questions:

1. What starts the approval?
2. Which record should be reviewed?
3. Who decides?
4. What fields should the approver see?
5. What statuses should be written back?
6. Should the requester receive a notification or message?
7. What should happen if the approval cannot be routed?

Approval Management is its own entitlement. Workflow and Messaging can make approvals more powerful, but approval access itself should be controlled separately so teams can enable exactly the capability they purchased or are testing.

| Approval moment    | What the maker should see                                                     |
| ------------------ | ----------------------------------------------------------------------------- |
| Request submitted  | A clear status, such as Submitted or Waiting for review.                      |
| Approval routed    | The reviewer sees the request in an approval or decision screen.              |
| Decision captured  | Approved, rejected, or needs changes is written back to the record.           |
| Workflow continues | Optional Workflow steps can notify, escalate, or hand work to another screen. |
| User checks result | The requester can understand the outcome without asking an admin.             |
````

**Current approval setup behavior**

Approval setup participates in the same outcome-first Automation flow. The maker describes the approval result and NotionApps creates or guides the approval route.

Example outcome:

> Route this request to a manager for approval and let the requester see the decision.

The builder should help the maker answer these questions:

1. What starts the approval?
2. Which record should be reviewed?
3. Who decides?
4. What fields should the approver see?
5. What statuses should be written back?
6. Should the requester receive a notification or message?
7. What should happen if the approval cannot be routed?

Approval Management is its own entitlement. Workflow and Messaging can make approvals more powerful, but approval access itself should be controlled separately so teams can enable exactly the capability they purchased or are testing.

| Approval moment    | What the maker should see                                                     |
| ------------------ | ----------------------------------------------------------------------------- |
| Request submitted  | A clear status, such as Submitted or Waiting for review.                      |
| Approval routed    | The reviewer sees the request in an approval or decision screen.              |
| Decision captured  | Approved, rejected, or needs changes is written back to the record.           |
| Workflow continues | Optional Workflow steps can notify, escalate, or hand work to another screen. |
| User checks result | The requester can understand the outcome without asking an admin.             |