> 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/customize-app/types-of-screens/automation-screens/decision.md). # Decision ## Decision Screen > Current state: this native screen is part of **Automation (Beta Testing)**. It is entitlement-gated, uses NotionApps runtime state instead of ordinary Notion data controls, and should be tested with realistic workflow or messaging activity before a maker relies on it in production. The **Decision** screen turns a workflow checkpoint into a live app review experience. It is for moments where automation must pause until a person chooses an outcome such as approve, reject, or request changes. Think of this screen as **a controlled approval desk for one clear question**. It should help the right person understand what is happening and what they can safely do next without reading raw JSON, copying internal IDs, or opening backend logs. ### Who This Guide Is For This guide is for makers configuring a **Decision** screen in the app builder. It explains the purpose of the screen, what users see after publication, what each builder section means, and how to avoid confusing or unsafe setups. Use this guide when: * A workflow needs a human approve/reject/checkpoint step. * Reviewers must see context before choosing an outcome. * A maker needs to decide between Decision, Work Queue, and Conversation. * You need claim behavior so only one reviewer owns a decision. ### What The Screen Is For Use Decision when the user is answering a specific workflow question. The screen should make the requested decision obvious, show safe review details, and record a structured outcome that the workflow can use. Good examples: * Approve or reject an expense request. * Review a membership application. * Approve content before publication. * Request changes to a submitted form. * Approve a vendor, refund, schedule change, or access request. Bad examples: * A general list of tasks. Use Work Queue. * A free-form discussion before deciding. Use Conversation alongside Decision. * A dashboard of workflow health. Use Workflow Status or Operator Console. * A normal record edit form. Use a data form screen. * A launchpad for manual automations. Use Automation Launcher. ### The Mental Model A **Decision** screen has three layers. | Layer | What it means | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | Builder configuration | The maker chooses the source, access rules, display rules, actions, preview state, and empty copy. | | Automation runtime state | NotionApps creates or receives workflow, messaging, queue, notification, exchange, or operator state that belongs to the screen. | | Live user experience | A user opens the app, sees only the allowed state, and either reviews it, acts on it, or uses it as context. | The key idea is: ``` A Decision screen should answer one clear question and record one structured outcome. ``` ### What Users See In The Live App In the live app, users see review guidance, the current decision item, safe details, ownership status, and decision buttons. If claim is required, decision buttons stay disabled until the reviewer claims the item. A live **Decision** screen can show: * Decision title and status. * Summary and due date when available. * Review details from the payload summary. * Support details hidden behind a toggle. * Claim review button when unclaimed. * Release review button when claimed by the current user. * Approve, Reject, and Request changes buttons. * Recorded outcome when the item is completed. The current runtime treats Decision as stricter than Work Queue by default. Claim is enabled by default so a reviewer explicitly owns the decision before submitting an outcome. ### Required Foundations And Entitlements Decision requires Workflow Foundation. The workflow must create or expose a decision item, wait for a decision outcome, and continue down the matching branch. Messaging is optional but useful for reminders, comments, and decision notifications. | Requirement | Why it matters | | -------------------------------------- | ---------------------------------------------------------------------- | | Automation screen entitlement | Decision appears in the Automation group. | | Workflow Foundation | The decision item and outcome are workflow-owned. | | A workflow wait/decision step | Without a waiting decision, the screen has nothing meaningful to show. | | Private app/user database, recommended | Reviewer access is usually role-based. | ### Builder Configuration Sections The builder page for every native automation screen has the same major sections. The controls are shared, but the meaning changes depending on the screen type. Read the section notes below before publishing the screen, because most configuration mistakes come from choosing a broad listen scope, exposing too much payload detail, or giving the wrong users action access. #### Header And Screen Type The top of the configuration panel identifies the screen as a **Native app screen** and shows the saved screen type. This matters because native automation screens do not read Notion rows directly. They read NotionApps runtime state: workflow runs, queue items, decisions, messages, notifications, exceptions, linked app exchanges, and operator summaries. The title and description shown here are the same words users see in the live app unless the screen is using a template preview state. For **Decision**, the maker should name the screen for the user job, not for the internal system. Use names like **Approval Review**, **Manager Decision**, **Request Review**, **Supervisor Approval**. Avoid names that expose implementation details such as workflow IDs, route IDs, channel names, or support references. #### Automation Source Automation source is the most important section. It decides which runtime events this screen listens to. If the source is too broad, users may see unrelated work. If it is too narrow, the screen may look empty even though automation is running. For Decision, the source should normally point to the workflow or form that creates the decision. Broad app-wide decisions can become confusing because unrelated approval questions may appear together. | Listen scope | How to use it for Decision | | ------------------------------ | -------------------------------------------------------------------------------------- | | Entire app | Use only for admin review centers that intentionally collect many decision types. | | Specific screen or form | Use when a submitted form creates the approval item. | | Specific workflow | Best default for one approval process. | | Conversation or message thread | Use when a message route creates a decision or the decision is tied to a conversation. | | Linked application | Use when a linked app request requires approval in this app. | Makers should normally start with the narrowest scope that still matches the business job. Use **Entire app** for owner dashboards and shared team inboxes. Use **Specific workflow**, **Specific screen or form**, **Conversation or message thread**, or **Linked application** when the screen belongs to one process. #### Template Setup State This section reports whether a managed template or demo provisioning run remapped this screen correctly. If the screen came from a cloned app, provisioning should connect the cloned screen to the cloned workflows, channels, topics, linked apps, and generated objects. A healthy screen usually shows **Provisioned**. **Needs review** means the app may still open, but the screen should not be trusted until the binding is checked or Automation Home repair is run. **No setup report** is normal for apps that were built manually rather than cloned from a template. For **Decision**, review this section after cloning a template, repairing a demo, changing a workflow, renaming a messaging channel, or replacing a form. The screen may still exist visually after those changes, but it can become pointed at old runtime objects unless provisioning remaps it. #### Related Context Related context is the builder's sanity check. It summarizes how many screens/forms, controls, workflows, and messaging channels are available to the screen picker. Hidden screens can appear here on purpose. A workflow may route a user to a hidden screen, or a native screen may listen to a hidden form that is not shown in navigation. Deleted screens should not be selected. For this screen, related context is especially useful for: * Finding the workflow that produces the decision. * Selecting an after-action confirmation screen. * Checking whether a related conversation exists for request changes. * Confirming hidden review screens are available for routing. #### Visibility And Access Visibility and access uses the same visibility model as normal data screens when the app is private and has a user database. That means makers can use user-record fields such as role, team, department, email, or plan to decide who sees the screen. The advanced allow lists are tighter controls: allowed role names limits access to matching role values, and allowed users limits access to specific emails or saved user references. For operational screens, prefer explicit roles such as Admin, Supervisor, Operations, or Support instead of broad end-user access. Recommended access for **Decision**: * Approval screens should usually be private. * Use role visibility for Manager, Supervisor, Reviewer, Admin, or Approver roles. * Use allowed users for named emergency reviewers. * Avoid showing Decision screens to requesters unless they are expected to review their own item. #### Display And Action Policy This section controls the words, density, payload exposure, timeline visibility, and claim policy. It is where a maker turns a technical automation surface into a usable live app screen. | Setting | What it means for Decision | Recommended default | | --------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- | | Screen title | Names the approval checkpoint. | Manager Review or Approval Review | | Description | Tells reviewers what they are deciding. | Review the details, then approve, reject, or request changes. | | Payload visibility | Controls how much submitted context reviewers see. | Redacted preview; full payload only for trusted reviewers. | | Density | Controls card spacing. | Comfortable. | | Show timeline | Shows approval request, claim, outcome, and workflow events. | On. | | Require claim before action | Requires reviewer ownership before submitting a decision. | On. | Payload visibility has three levels: | Level | Meaning | When to use it | | ---------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Metadata only | Shows status, title, timestamps, and safe runtime metadata without record details. | Use for broad audiences, customer-facing status, and screens where the payload contains private data. | | Redacted preview | Shows selected safe details and hides sensitive or technical fields. | Use for most operational and human-work screens. | | Full payload | Shows the fullest runtime payload available to the screen. | Use only for trusted internal operators or support-style screens. | #### Available Actions Available actions are the commands users can run from the live screen. Some screens are read-only. Others can claim work, complete work, submit decisions, reply to a conversation, acknowledge notifications, dismiss notices, escalate, or launch a workflow. Actions can optionally route the user to another screen afterward, and some actions can target a workflow. | Action | Runtime action type | What it does | | --------------- | ------------------- | --------------------------------------------------------- | | Approve | `decision.submit` | Submits an approved decision outcome. | | Reject | `decision.submit` | Submits a rejected decision outcome. | | Request changes | `decision.submit` | Submits a changes\_requested outcome. | | Claim review | `claim` | Appears when claim is required and the item is unclaimed. | | Release review | `release` | Appears when the current user owns the review. | Keep the decision labels short and unmistakable. If the workflow needs more outcomes, add them intentionally and map each outcome to a workflow branch. Use a Conversation screen for long discussion instead of turning decision labels into paragraphs. #### Preview Scenario Preview scenario is for builder validation, screenshots, and automated tests. It does not force live users into fake data. Use it to inspect desktop, tablet, and mobile layouts; portrait and landscape; requester, technician, supervisor, operator, and admin personas; and runtime states such as empty, loading, error, waiting approval, claimed by me, claimed by another user, overdue, or conversation active. For **Decision**, preview these states before publishing: * Waiting approval, to confirm unclaimed review copy. * Claimed by me, to verify decision buttons activate. * Claimed by another user, to verify buttons lock correctly. * Overdue, to verify escalation or urgency copy. * Empty, to verify no reviews waiting feels complete. * Mobile, to confirm approve/reject buttons do not wrap poorly. #### Empty State And Sample Data Empty state and sample data controls what users see when no matching runtime state exists. A good empty state tells the user whether they are finished, waiting for someone else, or missing setup. Sample item, sample workflow run, and sample conversation are builder-only references used to preview a known object before production traffic exists. Good empty-state copy for **Decision** should answer: * Does no decisions waiting mean the reviewer is done? * Should the reviewer check another screen? * Would a requester understand why they cannot see this screen? ### Common Configuration Patterns Most Decision screens map one workflow checkpoint to one reviewer group. #### Manager Approval A manager approves or rejects a submitted request. Recommended configuration: * Listen scope: Specific workflow. * Visibility: Manager or Supervisor role. * Require claim before action: on. * Payload visibility: redacted preview. * After-action screen: Workflow Status or request detail. #### Request Changes Loop The reviewer can send the request back for edits. Recommended configuration: * Decision outcomes: approved, rejected, changes\_requested. * Messaging: optional conversation for clarification. * After-action screen: Conversation or detail screen. * Timeline: on. #### Admin Approval Center Admins handle multiple approval processes from one place. Recommended configuration: * Listen scope: Entire app. * Access: Admin only. * Density: compact. * Payload visibility: redacted preview or full for trusted admins. ### Testing Checklist Before publishing or handing this screen to a customer, test the following. * [ ] Run the workflow until it creates a decision item. * [ ] Verify the reviewer can see the decision. * [ ] Verify the requester cannot see reviewer-only decisions unless intended. * [ ] Claim the decision and confirm decision buttons enable. * [ ] Approve and confirm workflow follows the approved branch. * [ ] Reject and confirm workflow follows the rejected branch. * [ ] Request changes and confirm the revision path or message is created. * [ ] Check completed decision state after outcome is recorded. ### Troubleshooting #### Approve and reject buttons are disabled What it usually means: Claim is probably required and the current user has not claimed the review. What to check: * Check Require claim before action. * Claim the review as the current user. * Verify the item is not claimed by someone else. * Check whether the item is already completed. #### Decision does not continue the workflow What it usually means: The outcome may not match the workflow branch or action handling failed. What to check: * Check workflow branch names. * Confirm decision payload values. * Review Workflow Status for the run. * Confirm idempotency did not block duplicate clicks. #### Wrong users can approve What it usually means: Visibility and allowed roles are too broad. What to check: * Add role-based visibility. * Use allowed users for named approvers. * Check private app user database fields. * Test as requester and as reviewer. ### Best Practices * Use Decision for a clear approval question. * Require claim before action when more than one reviewer can act. * Keep approval labels short. * Show enough context to decide, but hide sensitive payload fields. * Pair with Conversation when reviewers need discussion. * Always test each outcome branch. ### Recommended Default Setup Use this as a safe first configuration when the maker is unsure. * Listen scope: Specific workflow. * Visibility: Supervisor or Approver role. * Payload visibility: Redacted preview. * Show timeline: on. * Require claim before action: on. * Actions: Approve, Reject, Request changes. * Preview state: Waiting approval and Claimed by me.