✅Decision Screen
Current state: this native screen is part of Automation. 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 is a guided approval, rejection, or request-changes checkpoint where automation pauses until a person records a structured outcome.
Think of this screen as A controlled approval desk for one clear question that records one structured outcome.
Who This Guide Is For
This guide is for makers configuring a Decision screen in the app builder. It lists every builder option available on the screen and explains how to use each one.
Use this guide when:
A workflow needs Approve / Reject / Request changes.
Reviewers must inspect the real submission before deciding.
Only one reviewer should own the decision at a time.
What The Screen Is For
Use Decision when
A workflow needs Approve / Reject / Request changes.
Reviewers must inspect the real submission before deciding.
Only one reviewer should own the decision at a time.
Do not use it when
A general task list — use Work Queue.
Long discussion before deciding — pair with Conversation.
Run health dashboards — use Workflow Status or Operator Console.
What Users See In The Live App
Active / History / All segments (Active default).
Decision title, status, summary, and due date.
Review modal with Overview, Submission, and Documents tabs when configured.
Claim / Release when claim is required (default on).
Approve, Reject, and Request changes with optional reason and attachments.
Default listen scope
Entire app
Require claim before action
On
Default preview persona / state
Technician / Waiting approval
Empty title
No decisions are waiting
Empty description
Workflow decisions appear here when a route pauses for review.
Required Foundations
Automation screen entitlement
Decision appears in the Automation / Operational group.
Workflow
Primary foundation for this screen’s runtime state.
Private app + Users database (recommended)
Role/tenant visibility and audience policy need user fields.
Complete Builder Options Reference
The sections below follow the builder order. Every option is explained in prose so a maker can tell what the setting changes, how to configure it for a real approval flow, and which defaults or mistakes matter most before publishing.
Header and screen type
This opening section identifies the native screen and defines the basic language reviewers will see. Even though it is short, it sets the tone for the whole experience: a Decision screen should feel like one clear checkpoint with one clear question.
Screen type
What it does: Locks the screen into Decision behavior so the live app renders structured outcomes instead of a general task list or data table. How to use it: Leave the screen type as Decision once the screen is created. If the step is really open-ended work, use Work Queue; if it is only discussion, use Conversation. Why / recommended default: Decision is best when the workflow is waiting for a formal answer. Trying to stretch another screen type into approval behavior is a common source of confusing action labels and missing outcome logic.
Category
What it does: Places the screen in the native Automation or Operational grouping inside the builder. How to use it: Keep the built-in category and use app navigation to decide where reviewers discover the screen. Why / recommended default: This setting is mainly organizational, but it helps large apps keep approval desks separate from ordinary data screens.
Title
What it does: Sets the live title shown in navigation and at the top of the approval desk.
How to use it: Name the review job, such as Manager approval, Compliance review, or Client sign-off. Avoid internal workflow names that only makers understand.
Why / recommended default: Good titles reduce accidental approvals from the wrong desk. A common mistake is giving every screen a vague name like Review.
Description
What it does: Adds the helper sentence beneath the title so reviewers know what decision they are making. How to use it: Write one sentence that tells reviewers what to inspect and what outcome to record, such as "Review the submission, then approve, reject, or request changes." Why / recommended default: Clear description text is especially important when the same audience has several approval desks. It reduces hesitation and prevents guesswork.
Automation source
This section controls which workflow-generated decisions appear on the screen. The correct source is what makes the desk feel focused and trustworthy instead of becoming a mixed pile of unrelated approvals.
Entire app
A shared admin approval center
Pulling in too many unrelated decisions
Specific screen or form
One intake experience that always leads to review
Forgetting to update the binding after swapping forms
Specific workflow
One defined approval process
Pointing at the wrong workflow version
Conversation or message thread
Message-driven review flows
Expecting it to behave like a chat screen
Linked application
Cross-app approval handoffs
Using it when the approval is still local to one app
Listen scope
What it does: Decides the high-level runtime source the screen listens to for decision items. How to use it: Start with Specific workflow for most approval desks. Use Entire app only when trusted admins need one shared review center. Choose Specific screen or form when one intake surface is the natural source boundary. Why / recommended default: Specific workflow is the recommended default for most makers because it keeps the approval queue understandable. Overly broad scope is the most common reason a Decision desk feels noisy.
Source screen or form
What it does: Appears when the scope is Specific screen or form and binds the desk to that submission surface. How to use it: Pick the exact create or update form that triggers the approval step. Revisit this binding any time you replace or duplicate the intake screen. Why / recommended default: This is useful when business owners think in terms of "submissions from this form." The common mistake is assuming the binding will follow a renamed or rebuilt form automatically.
Workflow
What it does: Appears when the scope is Specific workflow and filters the desk to decisions emitted by that workflow. How to use it: Select the published workflow that contains the decision step. If the workflow has staging or archived versions, verify you picked the live one. Why / recommended default: This is the safest default for a clear approval desk. It makes debugging much easier when a decision does not appear or appears in the wrong place.
Messaging channel
What it does: Narrows decision-related activity to a specific messaging channel when the workflow and approval route also emit messages. How to use it: Set it only when your approval model depends on channel-bound messaging. Otherwise leave the Decision screen centered on workflow scope. Why / recommended default: Channel filters are powerful but easy to mismatch. Use them deliberately, not by habit.
Topic
What it does: Filters channel-driven activity to one topic inside that channel. How to use it: Use stable topic names and match them exactly to the route that creates the approval context. Why / recommended default: Topic mismatch is a common cause of empty screens. Consistent topic naming across environments prevents subtle drift.
Conversation or correlation
What it does: Limits the desk to one specific conversation thread or correlation context. How to use it: Use this only for a tightly scoped case review or a single-request follow-up experience. Leave it broader for a reusable approval desk. Why / recommended default: Hard-coding a correlation is usually too narrow for a general approval queue, so use it only when that narrowness is intentional.
Linked application
What it does: Binds the decision desk to a linked external NotionApps application when approvals are exchanged across apps. How to use it: Select the linked app only when the approval context really originates there. Most Decision screens stay on workflow scope inside the same app. Why / recommended default: Cross-app review can be powerful, but it adds another layer to troubleshoot. Do not choose this unless the architecture truly needs it.
Include sheets
This section lets you narrow a Decision desk to the sheets that matter. It is useful when one workflow handles several record types but only some of them should come to a particular reviewer group.
Included sheets
What it does: Limits visible decision items to the selected sheets. Leaving everything unchecked allows all eligible sheets in scope. How to use it: Check only the sheets that should feed this desk. If the same approver group handles multiple sources, leave them unchecked for a broader review center. Why / recommended default: Sheet filtering is helpful for routing, but it is also easy to forget during testing. A hidden sheet filter is a common reason reviewers insist approvals are missing.
Decision outcomes
This section is the heart of the screen. It defines the structured answers the reviewer can submit and how those answers behave, including whether a reason is required, whether attachments are allowed, and whether the source record should receive a Notion status writeback.
Approve
approved
Primary action, reason optional
Reject
rejected
Danger action, reason required
Request changes
changes_requested
Secondary action, reason required, attachments allowed
Approve
What it does: Records the positive decision outcome and submits the decision key approved.
How to use it: Keep Approve available whenever the workflow has a successful review branch. Verify the workflow branch expects the approved key or its mapped equivalent.
Why / recommended default: Approve should be the clearest action on the screen when acceptance is a normal path. A common mistake is relabeling the button in a way that no longer matches the workflow outcome logic.
Reject
What it does: Records a negative outcome using the rejected decision key.
How to use it: Keep Reject available when the workflow needs a formal stop or denial path. Make sure the corresponding workflow branch and any downstream notifications expect a rejected outcome.
Why / recommended default: Reject should be explicit, not hidden. Reviewers need a clean way to say "no" without using Request changes as a workaround.
Request changes
What it does: Records the changes_requested outcome so the workflow can loop back for edits instead of fully approving or rejecting.
How to use it: Keep this action when the process supports revision cycles. Pair it with a clear submission review setup and, when useful, a Conversation screen for back-and-forth clarification.
Why / recommended default: This action is valuable because it preserves nuance. The common mistake is leaving it enabled even when the workflow has no branch for changes requested, which makes the screen look capable of something the route cannot handle.
Require reason
What it does: Forces the reviewer to enter a comment before submitting a selected outcome. How to use it: Leave Require reason on for Reject and Request changes. Approve can stay optional unless policy or regulation requires written approval notes. Why / recommended default: Rejections and change requests should nearly always explain themselves. The common mistake is making reasons optional everywhere and losing the audit trail people need later.
Allow attachments
What it does: Lets the reviewer attach files to the selected outcome. How to use it: Enable attachments where evidence matters, especially on Request changes for annotated documents or screenshots. Only enable them on Approve or Reject when there is a real business need. Why / recommended default: Attachments are helpful, but they introduce more complexity. The default pattern of using them mainly for Request changes is usually the right balance.
Notion status value
What it does: Maps each outcome to a status value written back to the source record.
How to use it: Enter the exact source-record status value you want for each outcome, such as Approved by Client, Rejected, or Needs Revision. Populate every meaningful path rather than relying on memory or convention.
Why / recommended default: Explicit writeback mappings make the app and Notion stay aligned. The common mistake is assuming people will infer decision state from runtime history alone.
Attachment Notion field
What it does: Points outcome attachments to a files/uploads field on the source record when attachments are enabled. How to use it: Choose the files property that should store review evidence. Confirm that the field exists on the relevant sheet and is appropriate for long-term retention. Why / recommended default: If attachments matter, they should land somewhere predictable. The common mistake is enabling attachments but forgetting to point them at a usable record field.
Outcome labels and styles
What it does: Shows the maker-facing labels, keys, and styles for each outcome. How to use it: Keep labels short and business-readable, and make sure any workflow branching still matches the underlying decision keys. Treat styles as meaning cues: primary for forward progress, danger for hard stop, secondary for revision. Why / recommended default: These defaults are already sensible. Changing labels without checking workflow branch expectations is one of the easiest ways to create a subtle mismatch.
Writeback behavior
What it does: Applies the configured Notion status mapping after the decision is submitted.
How to use it: Prefer explicit mappings for all important outcomes, including changes_requested. Use fallback behavior only when you are maintaining older setups.
Why / recommended default: Explicit mapping is more predictable than legacy fallback. That predictability matters when other screens, filters, or notifications depend on the status field.
App audience and notification prefs
These controls are app-wide policy, but they matter for Decision because approvals often carry sensitive payloads and should only be visible to the right tenant and reviewer population.
Tenant mode
What it does: Decides whether decisions are isolated by tenant relation or treated more broadly. How to use it: Choose Relation for multi-tenant approval apps so reviewers only see decisions for their own client or company. Use Off only in genuinely single-tenant setups. Why / recommended default: Tenant isolation is usually the safer default. Decision desks often surface sensitive content, so getting this wrong is especially costly.
Tenant field
What it does: Selects the Users-sheet relation that represents tenant membership. How to use it: Point this at the same company, client, or workspace field used elsewhere in the app. Why / recommended default: Consistency across screens is more important than creative modeling. If this field differs from the rest of the app, reviewer visibility will feel random.
Role field
What it does: Identifies the field holding a user's role when it is not named Role.
How to use it: Leave blank for the default field name or set it to your custom role property.
Why / recommended default: Role-based access only works if the builder is reading the correct field. This is easy to overlook when importing or cloning user schemas.
Notification categories
What it does: Connects notification types to user preferences so people can control how approval-related notices reach them. How to use it: Add only the categories the approval flow actually sends, such as review requests or escalation notices, and map each one to a real preference field. Why / recommended default: Lean, real categories are easier to maintain. Too many categories create policy drift and make notification behavior harder to explain.
Add notification category
What it does: Adds another category row to the audience policy. How to use it: Create a new category only when you also have a sending route and a user preference to bind it to. Why / recommended default: Categories should represent actual user choices, not future possibilities.
Save audience policy
What it does: Saves tenant and category settings at the app level. How to use it: Save immediately after policy changes and before retesting approval visibility or notifications. Why / recommended default: Unsaved policy changes are a common source of false debugging, especially when several makers are testing with different personas.
Template setup state
This section tells you whether a cloned template or repaired demo still has healthy bindings behind the Decision screen.
Setup state indicator
What it does: Reports whether the native screen is provisioned, needs review, or has no setup report. How to use it: Treat Provisioned as healthy, treat Needs review as a signal to re-check workflow and review-tab bindings, and treat No setup report as normal for manual builds. Why / recommended default: This status can point you to configuration drift before users ever notice a broken approval desk.
Related context
This read-only panel helps you locate nearby forms, workflows, channels, and other screens that influence the decision experience.
Related context panel
What it does: Shows discovery counts and related objects connected to the current native screen. How to use it: Use it to find the right detail screen, documents screen, or after-action destination rather than recreating them from scratch. Why / recommended default: Discovery is safer than copying IDs around, especially in larger builder setups.
Visibility and access
This section controls who is allowed to open the Decision screen at all. Approval desks should be tighter than general task lists because the payload and outcome power are usually more sensitive.
Visibility rules
What it does: Applies rule-based screen visibility using the same private-app model as other screens. How to use it: Build conditions using stable fields such as role, team, tenant, or region. Keep the logic easy to read and test. Why / recommended default: Simpler access rules are easier to audit. A common mistake is opening the desk too broadly and relying on reviewers to self-select.
Allowed role names
What it does: Adds a direct role allow list for the approval desk.
How to use it: Use clear roles such as Manager, Approver, Admin when role gating is sufficient.
Why / recommended default: This is often the clearest and safest access model for approvals. The common mistake is accumulating similar role names until no one remembers which one actually unlocks the screen.
Allowed users
What it does: Grants access to specific people by email or user reference. How to use it: Use this sparingly for pilot reviewers, emergency approvers, or executive overrides. Why / recommended default: Per-person overrides are useful but hard to scale. They should supplement the role model, not replace it.
Submission review
Submission review is the pre-decision inspection experience inside the review modal. It is separate from after-action routing and is one of the most important parts of a trustworthy approval desk.
Overview fields + full record
Most governed approvals
Recommended default
Overview fields only
Fast, repetitive reviews
Good for simple approvals
Full record only (legacy)
Older setups that rely on the full submission view
Use only when needed
Review sheet
What it does: Chooses which sheet powers the Overview field picker. How to use it: Leave it blank to auto-detect when the decision items always come from one reliable source. Set it explicitly when you want the review configuration to stay stable across similar items. Why / recommended default: Explicit binding is safer in complex approvals. Auto-detect is convenient, but it can hide differences between item types.
Review mode
What it does: Decides whether reviewers see overview fields, the full submission, or both. How to use it: Choose Overview fields + full record for most regulated or high-confidence approval flows. Use Overview fields only when the review is simple and speed matters. Keep Full record only mainly for older compatibility cases. Why / recommended default: Overview fields + full record is the best default because it lets a reviewer scan first and drill in only when needed.
Overview fields
What it does: Defines the short list of fields shown in the Overview tab. How to use it: Include only the fields needed to answer the review question. Put the most decision-relevant facts first, such as amount, requester, due date, or risk flags. Why / recommended default: A tight overview reduces decision time. Including every field turns the summary tab into a second full form and defeats the point.
Submission screen override
What it does: Forces the Submission tab to open a specific detail screen instead of relying on auto-selection. How to use it: Bind the canonical review or detail screen that the approver should inspect. Why / recommended default: This is one of the most valuable safety settings for mature approval flows because it keeps the review experience predictable even after screens are renamed.
Documents screen override
What it does: Binds the Documents tab to a chosen document screen for the decision item. How to use it: Point it at the related documents or uploads experience reviewers actually need. Why / recommended default: This matters whenever attachments or supporting files are part of the approval standard. Forgetting it is a common reason the review modal feels incomplete.
Inbox modes
Decision screens still use inbox-style segmentation even though the action is structured. Makers should understand these modes because reviewers often use History to confirm that a decision was already made.
Active, History, and All
What it does: Separates actionable open decisions from completed history and the full combined audit list. How to use it: Tell reviewers to work from Active, check History when they need to confirm a completed outcome, and use All for support or audit work. Why / recommended default: The default live segment is Active because it keeps the desk focused. A common mistake is assuming a handled decision vanished when it simply moved to History.
Display and action policy
This section controls how much context reviewers see and whether ownership is enforced before a decision can be submitted. For Decision, this section is where safety defaults matter most.
Screen title override
What it does: Refines the live title for the approval desk.
How to use it: Use the business-friendly name reviewers already recognize, such as Client approval or Finance review.
Why / recommended default: Clear names reduce the risk of making the right decision in the wrong place.
Description
What it does: Sets the helper text shown under the title. How to use it: Tell reviewers exactly what they must do, for example "Inspect the request, then approve, reject, or request changes." Why / recommended default: Specific guidance helps occasional reviewers stay consistent without extra training.
Payload visibility
What it does: Controls how much runtime payload detail is visible during review. How to use it: Choose Metadata only for broad or external audiences, Redacted preview for most internal approval desks, and Full payload only for trusted operators or sensitive back-office reviewers who genuinely need it. Why / recommended default: Redacted preview is the usual default because it balances context and safety. Full payload should be intentional, not automatic.
Density
What it does: Changes how much visual space each item and detail block uses. How to use it: Keep Comfortable for most approval work where careful reading matters. Switch to Compact only for experienced, high-volume review teams. Why / recommended default: Comfortable spacing lowers reviewer error rates. Compact works best only after the process is mature.
Show timeline
What it does: Displays steps, messages, and audit events around the decision item. How to use it: Leave it On for most Decision screens so reviewers can see what happened before the item reached them. Why / recommended default: Timeline visibility reduces back-and-forth and improves auditability. Hiding it often makes borderline cases harder to judge.
Require claim before action
What it does: Requires the reviewer to claim the decision item before using Approve, Reject, or Request changes. How to use it: Leave this On for shared approval desks unless the screen is truly personal and already assigned to one person. Why / recommended default: The registry default for Decision is On, and that is the recommended default in almost every shared review workflow. The common mistake is turning it off too early and letting two reviewers act on the same item.
Available actions
These are the live actions reviewers see at the decision point. Together they should cover the full policy of the approval step without forcing the reviewer into side-channel workarounds.
Approve action
What it does: Submits the positive approval outcome. How to use it: Keep it enabled when the workflow can continue forward after a successful review. Pair it with an after-action screen such as Workflow Status if users need confirmation. Why / recommended default: Approve is the default forward path in most review flows. Make sure its label and workflow branch still match after any process rename.
Reject action
What it does: Submits the negative denial outcome. How to use it: Keep the default reason requirement so denials are explained. Route users to a follow-up screen only when there is a real post-rejection task. Why / recommended default: A documented rejection is safer than an undocumented one. The common mistake is treating reject like a shortcut instead of a governed outcome.
Request changes action
What it does: Sends the item back for revision with the changes_requested outcome.
How to use it: Keep the default reason requirement and attachment support when reviewers may need to explain missing information or mark up documents.
Why / recommended default: This action is most useful when the process expects iterative improvement. It is the right place for evidence-backed feedback, not a second version of Reject.
After-action screen
What it does: Sends the reviewer to another screen after a decision submits successfully. How to use it: Route to Workflow Status for confirmation, to Conversation when clarification usually follows, or to a confirmation screen when you want a clean finish. Why / recommended default: This is optional. Do not confuse it with Submission review, which happens before the outcome is chosen.
Target workflow
What it does: Provides the target workflow for actions that launch or escalate into another workflow. How to use it: Decision usually does not need this for normal Approve, Reject, or Request changes actions, but use it deliberately if you add escalation-style follow-up behavior. Why / recommended default: Leave it empty unless an action truly needs it. Unused workflow bindings make maintenance harder.
Preview scenario
Preview controls let you test not just layout but policy. For Decision, you should always check claimed and blocked states before publish because that is where shared-ownership mistakes show up.
Device and orientation
What it does: Changes the preview frame to desktop, tablet, or mobile in portrait or landscape. How to use it: Always inspect the review modal on mobile, even if most reviewers work on desktop. Why / recommended default: Mobile approval is common for managers and approvers. If the modal or action footer breaks there, the workflow will feel broken.
Test persona
What it does: Simulates who is using the desk. How to use it: Test with the real reviewer role, not only with Admin. The default preview persona is Technician, but you should switch to the actual approver persona your app uses. Why / recommended default: Admin previews hide permission mistakes. Persona testing is the fastest way to catch visibility errors before launch.
Preview state
What it does: Simulates runtime states such as Waiting approval, Claimed by me, Claimed by someone else, Empty, and Error. How to use it: Test Waiting approval, Claimed by me, and Claimed by someone else in particular. Why / recommended default: The default preview state is Waiting approval, which is the right starting point, but it does not reveal concurrency problems by itself.
Test mode
What it does: Switches between simulated preview and live runtime testing. How to use it: Use simulated mode for copy and layout, then verify a real workflow run in live test mode before publishing. Why / recommended default: Only a live decision test proves that outcome keys, writeback, and permissions all work together.
Empty state and sample data
Even an approval desk should have a calm idle state. Empty-state settings help users understand that there is simply nothing waiting, not that the review process failed.
Empty title
What it does: Sets the headline shown when no decision items match.
How to use it: Keep the default No decisions are waiting unless your reviewers use clearer team-specific language.
Why / recommended default: The default is strong because it sounds complete, not broken.
Empty description
What it does: Explains why the desk is empty and what users should expect next.
How to use it: Keep or adapt the default Workflow decisions appear here when a route pauses for review. Add a secondary hint only if your users truly need it.
Why / recommended default: Good empty copy prevents unnecessary support questions from reviewers who are new to the process.
Sample item, run, or conversation
What it does: Provides builder-only runtime references for realistic previewing and screenshots. How to use it: Use a representative approval item with documents, a real summary, and meaningful status values so the review modal reflects production conditions. Why / recommended default: Weak sample data can hide exactly the cases that make approvals fail in production, such as long titles, missing documents, or required reasons.
Recommended Default Setup
Listen scope
Specific workflow
Visibility
Manager, Supervisor, Approver, or Admin
Payload visibility
Redacted preview
Show timeline
On
Require claim before action
On
Submission review
Overview fields + full record with Submission screen bound
Decision outcomes
Approve / Reject / Request changes with Notion status mappings
Common Configuration Patterns
Manager approval
Specific workflow, claim on, redacted preview, after-action to Workflow Status.
Request-changes loop
Require reason on Reject and Request changes; bind Documents screen; optional Conversation for clarification.
Admin approval center
Entire app listen scope, Admin-only visibility, compact density.
Testing Checklist
Troubleshooting
Approve/Reject disabled
Claim is required and the item is unclaimed or owned by someone else.
Workflow does not continue
Outcome key does not match a workflow branch, or submit failed — check Workflow Status.
Wrong users can approve
Visibility / allowed roles are too broad — tighten roles and retest as requester.
Best Practices
Configure Decision for one clear user job.
Prefer the narrowest listen scope that still shows the right work.
Keep payload visibility conservative for broad audiences.
Test as an allowed user and a blocked user before publish.
Pair related screens (Decision + Conversation + Workflow Status + Notification Center) instead of overloading one screen.