> 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/screens-and-components/types-of-screens/native-automation-and-operational-screen-guides/decision-screen.md). # 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.** ![Builder view of this screen with the configuration panel open](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FfPrIykeBGDZEQ8E87xep%2F00-builder-hero.jpg?alt=media) ## 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 | Value | | ------------------------------- | -------------------------------------------------------------- | | 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 | Requirement | Why it matters | | ------------------------------------------ | ------------------------------------------------------------ | | 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 ![Annotated builder screenshot: Automation source](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FhWnrvtJqiiRhoLQh9V8u%2F01-section-automation-source.jpg?alt=media) 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. | Listen scope | Best for | Common mistake | | ------------------------------ | ------------------------------------------------- | ----------------------------------------------------- | | 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 ![Annotated builder screenshot: Include sheets](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FD4SDKrB6pwdan33uiBHF%2F02-section-include-sheets.jpg?alt=media) 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 ## Topics that fill this screen and resume the workflow This inbox is not a Notion table. Cards appear when a workflow **Publish Message** uses a request topic with item type **decision** — usually `client.review.requested` or `supervisor.review.requested`. When the reviewer submits an outcome, Messaging publishes a **reply topic**. The waiting workflow only continues if **Wait for message** lists those exact names: | Outcome | Reply topic | | --------------- | ----------------------------------- | | Approve | `client.decision.approve` | | Request changes | `client.decision.changes_requested` | | Reject | `client.decision.reject` | Use the builder presets or **Use all client decision topics**. A homemade topic (`client.approved`, `review.done`) will not wake a Wait that lists the presets. Notification Center is the ping. Preference checkboxes can mute the notice; the Decision card still sits here. Named catalog: [Topics that perform work](https://docs.notionapps.com/automation/messaging-and-notifications#topics-that-perform-work). ![Annotated builder screenshot: Decision outcomes](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FnGmoMpatFKrpJcswn2R4%2F03-section-decision-outcomes.jpg?alt=media) 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. | Outcome | Default key | Default behavior | | --------------- | ------------------- | ------------------------------------------------------ | | 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 ![Annotated builder screenshot: App audience and notification prefs](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FClql8B8Y5hSzqWyk1sbn%2F04-section-app-audience-and-notification-prefs.jpg?alt=media) 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 ![Annotated builder screenshot: Template setup state](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FfngPgCsyo0Gi0yGqY481%2F05-section-template-setup-state.jpg?alt=media) 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 ![Annotated builder screenshot: Related context](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FHU1iJuDHaiogfO9loecN%2F06-section-related-context.jpg?alt=media) 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 ![Annotated builder screenshot: Visibility and access](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FYRn2pM8Mr2obD7cfYIOx%2F07-section-visibility-and-access.jpg?alt=media) 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 ![Annotated builder screenshot: Submission review](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2Fcbifwv292bnC4RIHDHt0%2F08-section-submission-review.jpg?alt=media) 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. | Review mode | Best for | Recommendation | | ----------------------------- | -------------------------------------------------- | ------------------------- | | 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 ![Annotated builder screenshot: Display and action policy](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FBghBOexNkwy5grsIRhQa%2F09-section-display-and-action-policy.jpg?alt=media) 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 ![Annotated builder screenshot: Available actions](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FiJYRvlMiNNGOCHkaI0ye%2F10-section-available-actions.jpg?alt=media) 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 ![Annotated builder screenshot: Preview scenario](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FM9cihiS19VN5umAcRK7Y%2F11-section-preview-scenario.jpg?alt=media) 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 ![Annotated builder screenshot: Empty state and sample data](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FEJKff2FeyN0kTOj8MlUT%2F12-section-empty-state-and-sample-data.jpg?alt=media) 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 | Setting | Recommended value | | --------------------------- | -------------------------------------------------------------- | | 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 * [ ] Run the workflow until a decision item appears under Active. * [ ] Confirm claim enables decision buttons. * [ ] Approve and verify the approved workflow branch. * [ ] Reject and Request changes with reasons; verify writeback status values. * [ ] Open Review and confirm Overview / Submission / Documents. * [ ] Confirm History shows completed decisions. ## 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.