> 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/create-your-first-approval-workflow.md).

# ✅ Create your first approval workflow

## Create your first approval workflow

### Create your first approval workflow

#### Create your first approval workflow

**Create your first approval workflow**

**Create your first approval workflow**

**Create your first approval workflow**

This guide walks through one complete approval workflow from a normal data page to a working reviewer experience. Use it when you want a self-service path that does not require backend inspection, manual database edits, or someone explaining hidden setup.

The example is a purchase request. An employee creates a purchase request, clicks Submit, a reviewer sees the request on a Decision screen, the reviewer approves or rejects it, and the requester can see the final status.

![Purchase Requests list used as the source data page.](https://content.gitbook.com/content/5ZqDXcVVffWUqEIZVhmn/blobs/TPnKnb1KBF1SpUpl5Mmn/assets/approval-management/procurement-approval-desk/07-purchase-requests-list.jpg)

*Start with a normal data page. Automation begins from a real user action on real records.*

**Before you start**

You need one data page with enough fields for a reviewer to make a decision.

Use these fields for the first build:

| Field          | Type                | Why it matters                                                                    |
| -------------- | ------------------- | --------------------------------------------------------------------------------- |
| Request title  | Text                | Appears in screens and messages.                                                  |
| Requester      | User or email       | Tells the workflow who started the request.                                       |
| Department     | Select              | Gives business context.                                                           |
| Vendor         | Text                | Helps the reviewer understand the purchase.                                       |
| Amount         | Number or currency  | Often controls review priority.                                                   |
| Reason         | Long text           | Explains why approval is needed.                                                  |
| Needed by      | Date                | Helps the reviewer prioritize.                                                    |
| Reviewer       | User, role, or team | Tells the workflow who should decide.                                             |
| Status         | Select              | Shows Draft, Submitted, Waiting for review, Approved, Rejected, or Needs changes. |
| Decision notes | Long text           | Records why the reviewer decided.                                                 |

**Step 1: Confirm the user can create a request**

Open the request page and make sure users can add a new item. A workflow cannot save a bad form. The user should know what to fill out, which fields are required, and what happens after Submit.

![Purchase request form with the fields reviewers need.](https://content.gitbook.com/content/5ZqDXcVVffWUqEIZVhmn/blobs/ahcWj3VTBrYy2kd32oGn/assets/approval-management/procurement-approval-desk/08-purchase-requests-new-request-form.jpg)

*Collect enough context so the reviewer can decide without asking the maker what the record means.*

**Step 2: Add the submit behavior**

The submit action should do two things:

1. Save the request.
2. mark the request as Submitted or Waiting for review.

Write down the exact status value the button writes. Submitted and Waiting for review are different values. If the workflow listens for one value and the app writes another, the workflow will not start.

**Step 3: Start the approval wizard**

This step creates the approval route. It does not replace the need to add the reviewer screens in the next step. The wizard tells NotionApps what should happen; the Automation screens give reviewers a place to do the work.

1. Open **Automation** from the builder rail.
2. Choose **Approval workflow**.
3. Set **When this happens** to the real submit action on the Purchase Requests page.
4. Choose the submitted status value that the app actually writes. For example, choose **Submitted** only if the button writes **Submitted**. Choose **Waiting for review** only if the button writes **Waiting for review**.
5. Choose the reviewer. For the first build, use the **Reviewer** field, a specific approver role, or a real reviewer user.
6. Choose **Decision** as the reviewer destination. This means the approval should be decided on a Decision screen. You will create or confirm that Decision screen in Step 4.
7. Choose **Work Queue** if reviewers need an inbox of requests to review. For most real apps, this is recommended because reviewers usually need a list, not only a direct link to one request. You will create or confirm that Work Queue screen in Step 4.
8. Add **Workflow Status** if the requester should track progress from a separate status screen. This is optional for the first build.
9. Write the reviewer message: Purchase request {{Request title}} for {{Amount}} is waiting for your review.
10. Write the requester message: Your purchase request was submitted and is waiting for review.
11. Map **Approve** to the final status **Approved**.
12. Map **Reject** to the final status **Rejected**.
13. Decide what **Request changes** should do. A simple first build can set the record to **Needs changes** and notify the requester.
14. Add exception handling for missing reviewer, missing amount, missing reason, failed message, and permission issue.
15. Save the approval setup.

![Approval workflow setup with trigger, destination, message, validation, and test controls.](https://content.gitbook.com/content/5ZqDXcVVffWUqEIZVhmn/blobs/kPhC9GrOLlzI30v2hkd5/assets/approval-management/maker-builder/03-procurement-approval-desk-approval-workflow-setup.jpg)

*The critical controls are When this happens, submitted status, reviewer, destination screen, messages, validation, repair, and test request.*

**Step 4: Create the approval inbox**

Do this before validation and before the first live test. If the inbox does not exist, reviewers will not have a clear place to find approval work.

Create this screen from **Screens -> New Screen -> Automation**:

| Screen to create        | Screen group | Screen type | Who uses it                                       | Why it exists                                   |
| ----------------------- | ------------ | ----------- | ------------------------------------------------- | ----------------------------------------------- |
| Purchase Approval Inbox | Automation   | Work Queue  | Reviewer, manager, procurement approver, or admin | Shows all approval requests waiting for review. |

Create the approval inbox:

1. Open **Screens** in the builder.
2. Select **New Screen**.
3. Choose the **Automation** screen group.
4. Select **Work Queue**.
5. Name the screen **Purchase Approval Inbox**.
6. Open **Source binding**.
7. Choose **Specific workflow** when this inbox should only show purchase approvals.
8. Search for the purchase approval workflow by friendly name and select it.
9. Open **Visibility**, **Permissions**, or the screen access settings.
10. Make the screen visible to the reviewer role, such as **Manager**, **Procurement Approver**, or **Admin**.
11. Hide the screen from requesters if requesters should only submit requests and view their own status.
12. Add the screen to the reviewer navigation menu so reviewers can find it without knowing a direct link.

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

**Step 5: Create the Decision screen**

This step is required. The approval workflow can route a request, and the Work Queue can list the request, but the reviewer still needs a Decision screen to approve, reject, or request changes. Do not move to validation or live testing until this screen exists.

Create this screen from **Screens -> New Screen -> Automation**:

| Screen to create           | Screen group | Screen type | Who uses it                                  | Why it exists                                                        |
| -------------------------- | ------------ | ----------- | -------------------------------------------- | -------------------------------------------------------------------- |
| Purchase Approval Decision | Automation   | Decision    | The reviewer who opens or claims one request | Shows one request with Approve, Reject, and Request changes actions. |

Create the Decision screen:

1. Open **Screens** in the builder.
2. Select **New Screen**.
3. Choose the **Automation** screen group.
4. Select **Decision**.
5. Name the screen **Purchase Approval Decision**.
6. Open **Source binding**.
7. Choose **Specific workflow**.
8. Select the same purchase approval workflow used by the inbox.
9. Configure the decision summary so the reviewer sees the fields needed to make a decision: requester, vendor, amount, department, business reason, needed-by date, status, and any attachments or supporting notes.
10. Confirm the available actions are clear: **Approve**, **Reject**, and **Request changes**.
11. If more than one reviewer can see the same request, enable claim-before-action so two reviewers cannot decide the same request at the same time.
12. Save the screen.

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

**Step 6: Connect the approval screens to the workflow**

1. Open **Automation -> Workflows**.
2. Select the purchase approval workflow.
3. Confirm the workflow creates a review item or decision item for the reviewer.
4. Confirm the review item opens **Purchase Approval Decision**, or confirm the Decision screen is bound to the same workflow.
5. Confirm the Work Queue screen is bound to the same workflow so new requests appear in **Purchase Approval Inbox**.
6. Save the workflow draft.

At this point, the workflow has an engine and a user interface. The requester submits from the data screen. The reviewer finds work in the Work Queue. The reviewer decides one request on the Decision screen.

**Step 7: Validate after the screens exist**

Run Validate only after the workflow and approval screens have been created or confirmed. Treat blockers as publish blockers. Do not assume a manual test will solve a validation blocker.

A ready approval workflow should confirm:

* The trigger is connected to the real submit action.
* The submitted status matches what the app writes.
* A reviewer can be resolved.
* The Work Queue screen exists and is bound to the approval workflow.
* The Decision screen exists and is bound to the approval workflow.
* The requester can see a status or message.
* Messages have useful business language.
* Exceptions have somewhere visible to appear.

![Validation ready state for an approval workflow.](https://content.gitbook.com/content/5ZqDXcVVffWUqEIZVhmn/blobs/J4yDDbTlZPwWWYg09Of3/assets/approval-management/maker-builder/04-procurement-approval-desk-validation-ready.jpg)

*Validation should make the setup understandable before a customer sees it.*

**Step 8: Run a live test as both people**

Use this test request:

* Request title: Laptop replacement for field team
* Vendor: Approved vendor
* Amount: 500
* Reason: Existing field laptop is failing and blocks customer visits.
* Reviewer: the Supervisor role or a real reviewer user
* Status before submit: Draft

Now test it:

1. Preview as the requester.
2. Create the request.
3. Click **Submit**.
4. Confirm the source record shows **Submitted** or **Waiting for review**.
5. Switch preview to the reviewer.
6. Open **Purchase Approval Inbox** from the reviewer navigation menu.
7. Confirm the submitted request appears in the inbox. If it does not appear, stop and check the workflow trigger, submitted status value, reviewer mapping, and Work Queue source binding.
8. Open the request from the inbox.
9. Confirm **Purchase Approval Decision** opens for that request.
10. Confirm the reviewer can understand the request without reading raw JSON. The screen should show amount, reason, vendor, requester, needed-by date, and any other decision context.
11. Click **Approve**.
12. Switch back to the requester.
13. Confirm the request is **Approved**.
14. Open **Automation -> Activity** and confirm the workflow followed the approved path.
15. Open **Exception Resolution**.
16. Confirm there are no unexpected failures.
17. Repeat the test with **Reject** and **Request changes** before using the workflow with real users.

![Submitted purchase request state.](https://content.gitbook.com/content/5ZqDXcVVffWUqEIZVhmn/blobs/9kTTAksELrXcFcxvTwCj/assets/approval-management/procurement-approval-desk/10-purchase-requests-submitted-state.jpg)

*The requester should see a visible submitted or waiting state immediately after Submit.*

![Reviewer request detail with decision context.](https://content.gitbook.com/content/5ZqDXcVVffWUqEIZVhmn/blobs/XliweGY8zGVBlyfbNYId/assets/approval-management/procurement-approval-desk/12-approval-inbox-request-detail.jpg)

*The reviewer should see enough business context to decide confidently.*

**If it does not work**

| Symptom                                        | Most likely cause                                                        | What to check                                                                                |
| ---------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Submit saves the request but nothing routes    | Trigger is not connected to the submit action.                           | Open When this happens and select the real button or form submission.                        |
| Manual status change works but Submit does not | Workflow listens to status only; user button does not write that status. | Confirm the button writes the exact submitted status.                                        |
| Reviewer does not see the item                 | Recipient, scope, or permission issue.                                   | Check reviewer field, role membership, Decision screen access, and source record visibility. |
| Reviewer can see but cannot decide             | Decision actions are missing or blocked.                                 | Check approve/reject mappings and field permissions.                                         |
| Requester never sees result                    | Outcome is not mapped back to status or message.                         | Map Approved, Rejected, and Needs changes back to the source record.                         |
| A failure is invisible                         | Exception Resolution is missing or not connected.                        | Add Exception Resolution and retest.                                                         |

**Definition of done**

The first approval workflow is done when the requester can submit from the app, the reviewer can decide from a Decision screen, the requester sees the result, validation is clean, and the maker can explain the whole flow from visible screens.Wizard-first approval path

The easiest approval workflow starts from the outcome, not from raw workflow settings. Use this pattern when training a new maker.

1. Open **Automation**.
2. Choose the approval or outcome-guided setup path.
3. Describe the desired result in plain language. Example: “When an employee submits a purchase request, send it to the selected reviewer and show the requester the decision.”
4. Select the source form or screen. Use the friendly screen name from the suggestions.
5. Select who should decide. This can be a role, selected person, manager field, or other app-aware recipient, depending on the app setup.
6. Confirm what the approver should see. Include the record fields that help the approver decide.
7. Confirm what happens after approval, rejection, or changes requested.
8. Let NotionApps create the route.
9. Save the route and run validation.
10. Test as the requester and as the approver.

The maker should not need to understand raw route IDs for the first setup. Advanced settings remain available, but the normal path should answer business questions: who starts it, who decides, what they see, what happens next, and how everyone knows the result.Wizard-first approval path

The easiest approval workflow starts from the outcome, not from raw workflow settings. Use this pattern when training a new maker.

1. Open **Automation**.
2. Choose the approval or outcome-guided setup path.
3. Describe the desired result in plain language. Example: “When an employee submits a purchase request, send it to the selected reviewer and show the requester the decision.”
4. Select the source form or screen. Use the friendly screen name from the suggestions.
5. Select who should decide. This can be a role, selected person, manager field, or other app-aware recipient, depending on the app setup.
6. Confirm what the approver should see. Include the record fields that help the approver decide.
7. Confirm what happens after approval, rejection, or changes requested.
8. Let NotionApps create the route.
9. Save the route and run validation.
10. Test as the requester and as the approver.

The maker should not need to understand raw route IDs for the first setup. Advanced settings remain available, but the normal path should answer business questions: who starts it, who decides, what they see, what happens next, and how everyone knows the result.

**Wizard-first approval path**

The easiest approval workflow starts from the outcome, not from raw workflow settings. Use this pattern when training a new maker.

1. Open **Automation**.
2. Choose the approval or outcome-guided setup path.
3. Describe the desired result in plain language. Example: “When an employee submits a purchase request, send it to the selected reviewer and show the requester the decision.”
4. Select the source form or screen. Use the friendly screen name from the suggestions.
5. Select who should decide. This can be a role, selected person, manager field, or other app-aware recipient, depending on the app setup.
6. Confirm what the approver should see. Include the record fields that help the approver decide.
7. Confirm what happens after approval, rejection, or changes requested.
8. Let NotionApps create the route.
9. Save the route and run validation.
10. Test as the requester and as the approver.

The maker should not need to understand raw route IDs for the first setup. Advanced settings remain available, but the normal path should answer business questions: who starts it, who decides, what they see, what happens next, and how everyone knows the result.