> 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/exception-resolution.md). # Exception Resolution ## Exception Resolution Screen > Current state: this native screen is part of **Automation (Beta Testing)**. It is entitlement-gated, reads NotionApps automation runtime state, and should be tested with safe failure cases before it is used in a customer-facing app. The **Exception Resolution** screen gives trusted users a place to recover automation work that did not complete normally. It is for failed steps, missing data, timed-out work, delivery problems, blocked routing, stale references, and other cases where automation can detect the problem but a person needs to decide what happens next. Think of this screen as a repair desk inside the app. It is not a normal Notion data screen. It does not simply list rows from a database. Instead, it reads NotionApps-owned runtime items such as workflow exceptions, failed automation items, messages, correlations, workflow runs, and recovery actions. Use this screen when the app needs to answer: ``` Something went wrong in the process. Who should see it? What context do they need? Can they safely resolve it, complete it, claim it, or escalate it? ``` ### Who This Guide Is For This guide is for makers configuring an Exception Resolution screen in the builder. It explains what each section of the screen configuration means, how the live screen behaves for users, and how to avoid unsafe or confusing recovery flows. Use this guide when: * You are adding an Exception Resolution screen to an app. * You are reviewing an advanced template that already includes one. * You want operators, supervisors, managers, or admins to recover failed automation without contacting NotionApps support. * You are troubleshooting why an exception does or does not appear. * You are deciding whether to expose an exception screen to end users, internal staff, or app owners only. ### What The Screen Is For The Exception Resolution screen is for exceptional automation states, not ordinary work. Good examples: * A workflow update failed because a required value was missing. * A message or notification could not be delivered. * A webhook payload arrived but did not include a customer, order, request, or record reference. * A workflow timed out waiting for an approval or reply. * A linked app handoff failed because the receiving app could not process the payload. * A workflow step could not find a record it expected to update. * A route produced a failed automation item that needs a person to review and close. Bad examples: * A normal task that someone needs to complete. Use **Work Queue** instead. * A normal approval decision. Use **Decision** or an Approval Inbox instead. * A normal conversation. Use **Conversation** instead. * A dashboard of overall workflow health. Use **Workflow Status** or **Operator Console** instead. * A fully automatic retry that does not need human judgment. Keep that inside the workflow logic. ### The Mental Model An Exception Resolution screen has three layers. | Layer | What it means | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Builder configuration | The maker decides what this screen listens to, who can access it, what context is visible, what actions are allowed, and how the screen behaves in preview. | | Automation runtime state | NotionApps creates or receives automation items, failed items, timeline entries, messages, and support references. The screen reads this state. | | Live user recovery | A trusted user opens the screen, reads the exception, reviews safe details, and takes the next allowed action. | The most important idea is this: ``` The screen does not fix anything by itself. It exposes the failed or blocked work so the right person can make a controlled recovery decision. ``` ### What Users See In The Live App In the live app, users see a normal app screen with a title, description, last updated time, short guidance, and a list of current exception work. For each exception item, the live screen may show: * The exception or failed work title. * Current status, such as `failed`, `waiting`, `claimed`, or `resolved`. * A plain-language summary. * Due date or waiting time when available. * Review details from the payload summary. * Support details, hidden behind a toggle, when technical references exist. * A timeline if the maker enabled timeline visibility. * Action buttons such as **Claim**, **Release**, **Complete**, **Mark resolved**, or **Escalate**, depending on the runtime path and screen configuration. The screen refreshes when the user pulls to refresh. The runtime also uses polling so the screen can pick up updated automation state. If the screen temporarily cannot reach NotionApps, it retries transient load failures before showing a friendly error. ### Default Actions The Exception Resolution screen is designed around recovery actions. | Action | What it means | When to use it | | ------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Claim | The current user takes ownership of the exception. | Use when more than one operator could work the same exception and you want to prevent duplicate handling. | | Release | The current user gives up ownership. | Use when the user claimed the item by mistake or another operator should take it. | | Complete / Mark resolved | The user says the exception has been handled. | Use after the missing data was corrected, the customer was contacted, the failed record was repaired, or the issue was verified as no longer active. | | Escalate | The user sends the exception to another person, route, workflow, or support path. | Use when the current user cannot safely resolve the issue alone. | In some places the builder configuration calls the primary resolution action **Mark resolved**, while the current live item action may appear as **Complete**. Treat both as the closing or resolution action for the exception. The important part is the action outcome: the exception should move out of active recovery once the issue has truly been handled. ### Before You Add This Screen Confirm these foundations first: | Requirement | Why it matters | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Automation entitlement is enabled | The screen is entitlement-gated and will not be usable without Automation access. | | Workflow Foundation is available | Exceptions usually come from workflow runs, workflow steps, failed updates, approval paths, or retry logic. | | The workflow actually creates exceptions or failed automation items | A workflow can fail in logs without producing something visible on this screen. | | The app has the right user identity setup | Visibility rules and role/user restrictions depend on knowing who the current user is. | | You know who should resolve the issue | Do not expose exception recovery to everyone by default. | | You have a safe test failure | Always test the screen with a controlled failure before publishing it to real users. | Messaging Foundation is optional, but useful when exceptions should create notifications, conversations, escalations, or support threads. ### Builder Screen Sections The builder configuration is divided into several sections. Each section controls a different part of the screen behavior. ### 1. Header And Screen Type At the top of the configuration panel, the builder shows the screen identity. You may see: * **Native app screen** * **Screen type** * **Exception Resolution** * The screen category, usually Automation or human work * The configured title and description * A summary explaining that the screen uses automation runtime state instead of Notion data controls #### What This Section Means This confirms that you are configuring a native automation screen. That matters because normal data-screen assumptions do not apply. A normal list or detail screen reads records from a Notion database. An Exception Resolution screen reads platform-owned state, such as failed workflow items and unresolved automation exceptions. #### What Makers Should Do Here Use this section as a sanity check: * Confirm the screen type is **Exception Resolution**. * Confirm the screen title describes the business recovery area. * Avoid generic names like `Errors` unless the app is very technical. * Prefer names like `Approval Recovery`, `Intake Exceptions`, `Failed Notification Review`, `Dispatch Recovery`, or `Webhook Repair Desk`. Good title examples: | Weak title | Better title | | ----------------- | ------------------------ | | Errors | Approval Recovery | | Exceptions | Intake Exceptions | | Workflow Problems | Dispatch Recovery Queue | | Failed Stuff | Payroll Exception Review | The title should help the user understand what kind of problem they are expected to resolve. ### 2. Automation Source The **Automation source** section is the most important part of the configuration. It controls what runtime activity belongs on this screen. The main field is **Listen scope**. #### Listen Scope Options | Listen scope | What it does | Best for | | ------------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Entire app | The screen listens across the whole app. | A broad operations repair desk where trusted users handle all app exceptions. | | Specific screen or form | The screen listens only to automation activity connected to one app screen or submitted form. | Form intake repair, request triage, or exceptions from a single submission path. | | Specific workflow | The screen listens only to one workflow. | A known recovery path, such as webhook intake, approval timeout, dispatch routing, or external update failure. | | Conversation or message thread | The screen focuses on one channel, topic, conversation, or correlation. | Message-driven exception recovery or support paths tied to a thread. | | Linked application | The screen focuses on exchange activity with another app. | App-to-app handoffs, partner workflows, vendor requests, or multi-app automation. | #### Entire App Choose **Entire app** when you want one general exception inbox for the application. Use this when: * The app is small or moderately complex. * One trusted team handles all automation recovery. * Exceptions from several workflows should land in one place. * You do not yet know which workflow will be the biggest source of exceptions. Be careful with this setting in large apps. It can collect unrelated exceptions and make the screen feel noisy. If users are confused by what appears, narrow the scope. #### Specific Screen Or Form Choose **Specific screen or form** when the exception belongs to one screen or form submission path. The related field is **Source screen or form**. Use this when: * The exception is caused by a form submission. * The user resolving the exception thinks in terms of the app screen, not the workflow name. * A hidden form creates workflow work in the background. * A request intake screen needs a matching recovery screen. The picker searches visible screens, hidden screens, and forms. Hidden screens can appear intentionally because workflows may route users to hidden screens even when they are not in the navigation menu. Example: ``` Source screen or form: Submit Service Request Exception screen title: Service Request Intake Exceptions ``` #### Specific Workflow Choose **Specific workflow** when the exception screen belongs to one automation route. The related field is **Workflow**. Use this when: * One workflow has a known failure mode. * A workflow needs a human repair step. * The screen should only show exceptions from one route. * You are documenting a template and want a clean, predictable recovery flow. The workflow picker searches Workflow Foundation workflows, legacy workflows, and generated workflows from automation recipes. It shows friendly names, statuses, and trigger details where available. Example: ``` Workflow: Vendor Insurance Approval Routing Exception screen title: Vendor Insurance Exceptions ``` #### Conversation Or Message Thread Choose **Conversation or message thread** when the exception is closely tied to a message route. Related fields may include: * **Messaging channel** * **Topic** * **Conversation or correlation** Use this when: * A failed message needs manual follow-up. * The exception should stay attached to a conversation. * A workflow waits for a reply and the timeout should be recoverable. * A support or approval conversation should carry the recovery context. Channels identify the broad messaging lane, such as `approvals`, `support`, or `dispatch`. Topics identify a business event within that lane, such as `approval.requested`, `message.failed`, or `dispatch.escalated`. Conversation or correlation references tie the exception to a specific thread or business object. #### Linked Application Choose **Linked application** when the exception belongs to app-to-app communication. Related fields may include: * **Linked application** * **Messaging channel** * **Topic** Use this when: * One app sends work to another app. * A partner, vendor, customer, or department app receives a request. * A linked app exchange fails. * You need a recovery screen for cross-app handoff issues. #### Practical Recommendation Start as narrow as the business process allows. Use **Entire app** only when the resolving team truly owns all exceptions. If only one workflow or intake form is involved, bind the screen to that workflow or form. Narrow screens are easier for makers to test and easier for users to understand. ### 3. Context-Aware Pickers Several fields use a context-aware picker instead of forcing makers to paste raw IDs. These pickers can suggest: * Screens and forms * Hidden screens * Controls and buttons * Data sources * Workflows * Workflow runs * Messaging channels * Topics * Conversations * Correlations * Linked apps * Recent messages * Generated recipe objects #### How The Picker Works Start typing a friendly name, status, trigger, channel, topic, screen name, or support reference. The picker shows matching options and saves the correct reference. When a known object is selected, the builder may show: * A friendly label * The object type * A support reference chip The support reference is mostly for debugging and support. Makers should choose by friendly names whenever possible. #### When To Paste A Custom Reference Custom advanced references are useful when: * Support gives you a specific workflow, run, conversation, or correlation ID. * The object exists but is not visible in the current suggestions. * You are repairing a template or advanced setup. Do not use custom references as the normal setup path for makers. If a maker has to paste IDs often, the app setup is probably too fragile or under-documented. ### 4. Template Setup State The **Template setup state** section appears when the app was created from, or can be compared against, a template provisioning run. It checks whether the current native screen was remapped correctly during template provisioning. You may see statuses like: | Status | Meaning | | --------------- | -------------------------------------------------------------------------------------------------------------- | | Provisioned | The screen binding was remapped for the cloned app. | | Needs review | The template setup exists, but this screen binding may need attention. | | No setup report | The app does not have a template provisioning report, or the screen was not created by a managed template run. | This section may also list binding details, such as: * Listen scope * Workflow reference * Channel * Topic * Source screen #### What Makers Should Do Here If the screen came from a template and says **Provisioned**, continue testing. If it says **Needs review**, do not assume the screen works. Open Automation Home, run repair or setup validation if available, then return to the screen and verify the source binding. If it says **No setup report**, that may be fine for hand-built apps. It is more concerning for a cloned advanced template where the screen should have been generated and remapped. #### Common Template Problem A template may include an Exception Resolution screen bound to a workflow from the original source app. After cloning, that reference must point to the cloned workflow, not the original workflow. The setup state is designed to help catch that class of problem before a live user sees an empty or broken recovery screen. ### 5. Related Context The **Related context** section summarizes what the builder can see in the current app. It may show counts for: * Screens and forms * Controls * Workflows * Channels #### What This Section Means This is not a runtime dashboard. It is a setup aid. It tells the maker whether the builder has enough context to make useful suggestions in the source binding, action routing, sample item, and preview fields. #### How To Use It Use this section to answer: * Are the expected screens and forms available? * Are workflows loaded? * Are messaging channels available? * Did generated recipe objects appear? * Is the builder missing context that should exist? If the counts look too low, refresh the builder, confirm the app has workflows or messaging enabled, and check whether the relevant objects were generated or published. ### 6. Visibility And Access The **Visibility and access** section controls who can see the Exception Resolution screen. This matters more for Exception Resolution than for many other screen types because exceptions may contain sensitive operational details. #### Visibility Rules Visibility rules work like data screen visibility rules. They are available when: * The app is private. * The app has a user database. * The builder has user fields available for filtering. Use visibility rules when access can be described through user properties. Examples: ``` Role is Supervisor Role is Operations Department is Dispatch Email is current app user ``` #### Visibility Connectors Visibility conditions can use connectors such as **AND** or **OR**. | Connector | Meaning | Example | | --------- | ------------------------------------ | ---------------------------------------------- | | AND | Every condition must be true. | User role is Supervisor AND Region is East. | | OR | At least one condition must be true. | User role is Supervisor OR User role is Admin. | Use **AND** when you are narrowing access. Use **OR** when several roles should independently qualify. #### Public Apps Public apps generally do not have the same identity context as private apps. If the app is public, the builder may show a note explaining that user database visibility rules require a private app with a user database. For an Exception Resolution screen, a public app should be treated carefully. Do not expose exception recovery publicly unless you have a very specific identity and access model. #### Allowed Role Names The **Allowed role names** field is an advanced allow list. Use it when only specific role names should open the screen. Example: ``` Supervisor, Operations, App Admin ``` This is useful when: * The user database has a clear role field. * You want simple role-based access. * You want access rules that are easy to review. Be exact with names. If the user record says `Ops Manager` but the allowed role says `Operations Manager`, the user may not match. #### Allowed Users The **Allowed users** field is an advanced named-user allow list. Use it for: * Specific emergency operators. * App owners. * A small named support team. * Temporary access during beta testing. Values may be email addresses or saved user references. Example: ``` owner@example.com, supervisor@example.com ``` #### Recommended Access Pattern For most apps: 1. Make the app private. 2. Use the user database to identify roles. 3. Give the Exception Resolution screen to operators, supervisors, or admins only. 4. Use allowed users only for narrow exceptions or support access. 5. Test as each persona before publishing. ### 7. Display And Action Policy The **Display and action policy** section controls how the screen explains itself and how much context the user sees. #### Screen Title The title appears at the top of the live app screen. Use a business-friendly title. Good examples: * `Intake Exceptions` * `Approval Recovery` * `Dispatch Recovery` * `Failed Notification Review` * `Payroll Exception Review` Avoid titles that sound like developer tools: * `Runtime Errors` * `Exception Objects` * `Failed Payloads` * `Debug Queue` #### Description The description appears below the title. It should tell the user what they are expected to do. Good examples: ``` Review failed intake work, correct missing information, and escalate anything that cannot be repaired safely. ``` ``` Use this screen to recover approval routing, notification, and record update failures. ``` Keep the description plain. The user should not need to understand workflow IDs, payloads, or runtime objects to know why the screen exists. #### Payload Visibility Payload visibility controls how much workflow or message data users can inspect. | Option | Meaning | Recommended use | | ---------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- | | Metadata only | Show only high-level metadata and hide most payload content. | Use for sensitive workflows or broad operator screens. | | Redacted preview | Show safe summary fields and hide sensitive or technical details. | Recommended default for most Exception Resolution screens. | | Full payload | Show the full payload. | Use only for trusted admins or controlled internal tools. | #### Recommended Payload Visibility Use **Redacted preview** by default. Choose **Metadata only** when the exception may include: * Tokens * Private notes * Personal information * Payroll or finance data * Healthcare or legal context * Customer messages that not every operator should see Choose **Full payload** only when: * The screen is restricted to trusted admins. * The payload is known to be safe. * The operator truly needs raw details to repair the issue. #### Density Density controls how compact the live screen feels. | Density | Best for | | ----------- | -------------------------------------------------------- | | Comfortable | Most users, mobile or tablet usage, lower volume queues. | | Compact | High-volume operator review where users scan many items. | Use **comfortable** unless operators explicitly need a denser view. #### Show Timeline The **Show timeline** setting controls whether the live screen displays workflow and automation history. When enabled, users can see related events such as: * Item created * Workflow step failed * Message sent * Action taken * Exception updated * Resolution recorded * Escalation recorded Timeline is useful because exception recovery often depends on what happened before the failure. Disable timeline when: * The screen is for a very simple recovery path. * The timeline creates confusion. * The timeline exposes internal information that users do not need. #### Require Claim Before Action The **Require claim before action** setting controls whether a user must take ownership before acting. Use this when: * More than one person can see the same exception. * You want to prevent duplicate handling. * Operators need a clear ownership trail. * A resolution should be auditable to one person. If enabled, the expected flow is: ``` Open exception -> Claim it -> Investigate or repair -> Complete / Mark resolved or Escalate ``` If disabled, users may act without claiming first. This is faster but less controlled. Recommended default: enable claim requirements for operational teams, especially if multiple people can access the screen. ### 8. Available Actions The **Available actions** section controls where actions route users or workflows after they click a recovery button. For Exception Resolution, common actions include: * Mark resolved * Escalate * Complete * Claim * Release The builder may show action configuration cards. Each card can include: * Action label * Action type * After-action screen * Target workflow, when the action can start or route to a workflow #### After-Action Screen The **After-action screen** controls where the user should go after the action finishes. Use this when: * After resolving an exception, the user should return to a queue. * After escalating, the user should open a conversation. * After completing repair, the user should open the original request. * After review, the user should see a status or audit screen. Examples: | Action | After-action screen | | ------------- | -------------------------------- | | Mark resolved | Workflow Status | | Escalate | Conversation | | Complete | Work Queue | | Claim | Same Exception Resolution screen | #### Target Workflow The **Target workflow** field appears for actions that can launch or route into workflow behavior, such as escalation. Use this when the action should trigger a structured follow-up. Examples: * Escalate to manager workflow * Notify support workflow * Create follow-up task workflow * Retry intake workflow * Start manual repair workflow #### Designing Safe Resolution Actions Do not make **Mark resolved** mean "retry everything blindly." A good resolution action should be safe and auditable. The user should understand what they are confirming. Good resolution meanings: * The missing field was corrected. * The customer was contacted. * The linked record was repaired. * The failed notification was manually sent. * The stale exception is no longer relevant. Risky resolution meanings: * Repeat an external charge. * Resend a message without checking recipients. * Update a record with unknown data. * Retry a webhook that may duplicate work. If an action can create side effects, route it through a workflow with validation instead of relying on a simple button. ### 9. Preview Scenario The **Preview scenario** section controls how the maker tests the screen in builder preview. These settings affect preview and testing. They do not force live users to see fake data. Live users see the real automation state for the app. #### Device Device controls the preview frame. | Device | Use it to check | | ------- | ----------------------------------------------------------- | | Desktop | Operator tables, timelines, and larger recovery workspaces. | | Tablet | Field manager, supervisor, or operations use. | | Mobile | Phone-first repair or approval paths. | Always test Exception Resolution on mobile if the resolving user might be away from a desk. #### Orientation Orientation controls portrait or landscape preview. Use landscape when: * Field teams rotate tablets. * The screen has wide detail rows. * Timeline and payload details need more horizontal space. #### Test Persona The test persona controls the kind of user the preview represents. Options include: | Persona | Meaning | | ---------- | ------------------------------------------------------- | | Requester | The person who submitted or watches a request. | | Technician | The person claiming or completing work. | | Supervisor | The person approving, rejecting, or escalating. | | Operator | The app owner or operations user monitoring exceptions. | | Admin | The builder or support user validating setup. | For Exception Resolution, the most common personas are **Operator**, **Supervisor**, and **Admin**. #### Preview State Preview state controls the condition being simulated. | Preview state | What to check | | ------------------- | --------------------------------------------------------------------- | | Live data | How the screen behaves with available runtime state or sample data. | | Empty | Whether the empty state is clear when no exceptions exist. | | Loading | Whether the loading state is understandable and actions are disabled. | | Error | Whether setup or access errors are clear. | | Waiting approval | Whether approval-related exception copy makes sense. | | Claimed by me | Whether ownership and next actions are clear. | | Claimed by other | Whether locked or unavailable actions make sense. | | Overdue | Whether urgency and escalation cues are visible. | | Conversation active | Whether related discussion appears correctly. | #### Test Mode | Test mode | Meaning | | ----------------- | ---------------------------------------------------------- | | Simulated preview | Uses sample state for design validation and screenshots. | | Live test | Uses real app context when validating an end-to-end route. | Use simulated preview while designing. Use live test before publishing. #### Preview Checklist Before publishing, confirm: * The primary action is visible without horizontal scrolling. * Payload details are readable on mobile. * Support details do not dominate the screen. * Timeline entries wrap cleanly. * Empty state explains what will appear later. * Error state tells the user what to do next. * Persona access matches the screen visibility rules. * Claim behavior matches how the team actually works. ### 10. Empty State And Sample Data The **Empty state and sample data** section controls what users see when there are no exceptions and what makers use for preview. #### Empty Title The empty title appears when no exception items match the screen. Good examples: * `No exceptions need attention` * `No intake exceptions are open` * `No recovery work is waiting` * `No failed approval work is open` Avoid: * `Nothing found` * `No records` * `No data` This is not a data table. The empty state should explain that no recovery work is currently needed. #### Empty Description The empty description should explain what would cause items to appear. Good example: ``` Failed workflow work appears here when an operator needs to review, repair, or escalate it. ``` Another good example: ``` If intake data is missing or a routing step fails, the recovery item will appear here for review. ``` #### Sample Item Sample item lets the maker preview the screen with a known object. It can reference: * App objects * Messages * Recipes * Workflow runs * Advanced references Use this when: * The app does not yet have a real exception. * You want predictable screenshots. * You are testing template setup. * You are validating mobile layout. #### Sample Workflow Run Sample workflow run loads recent runs for the selected workflow. Use this when: * The Exception Resolution screen is bound to one workflow. * You want preview data tied to a known failed or waiting run. * You are testing the workflow-status/timeline relationship. If no workflow is selected in Automation source, recent run suggestions may not load. #### Sample Conversation Or Thread Sample conversation or thread helps test recovery screens that involve messaging. Use this when: * Escalation opens a conversation. * The exception was created from a failed message. * The user needs discussion context before resolving. ### 11. Payload Details In The Live Screen The live screen tries to make payload details readable. It prefers friendly fields such as: * Employee * Employee email * Supervisor * Supervisor email * Date * Start time * End time * Hours * Status * Notes * Comment * Message * Reason * Decision Technical IDs are separated into **Support details** where possible. #### Why Support Details Are Collapsed Support details can include references such as: * Workflow ID * Workflow run ID * Conversation ID * Correlation ID * Message ID * Record ID * Screen ID * Source record ID These are useful for support and debugging, but most users should not have to read them. The screen collapses them so the operator sees the business problem first and the technical reference second. #### Payload Redaction Message If the item says the payload is redacted, users may see language indicating that sensitive or hidden fields were omitted. That is expected. It means the screen is intentionally hiding information that may be sensitive, unnecessary, or restricted. ### 12. Timeline When enabled, the timeline shows related automation events. Timeline entries can help the resolver understand: * What started the process. * Which step failed. * Whether a message was sent. * Whether another user already acted. * Whether the item was claimed. * Whether escalation or retry already happened. Timeline is especially useful for: * Approval timeouts * Failed notifications * Multi-step workflows * Linked app exchanges * Support escalation Timeline can be hidden if the recovery path is simple or if it exposes too much internal behavior. ### 13. Claiming And Ownership Claiming is how the screen prevents multiple people from handling the same exception at once. If an exception is unclaimed, a user may see **Claim**. If the current user claimed it, they may see **Release** and resolution actions. If another user claimed it, action behavior may be limited or the screen may indicate that someone else is handling it. #### When Claiming Should Be Required Require claim before action when: * Multiple operators share the same screen. * The exception may require investigation. * Duplicate resolution would be harmful. * You want a clear audit trail. #### When Claiming Can Be Optional Claiming can be optional when: * Only one user can see the screen. * The action is low-risk. * Exceptions are informational and easy to close. * The screen is used mainly by the app owner. ### 14. Escalation Escalation is for exceptions the current user cannot safely resolve. Escalation can route to: * Another screen * A workflow * A conversation * A notification path * A manager or support queue * A linked application handoff Good escalation examples: ``` Missing customer ID -> escalate to intake owner Failed notification -> escalate to support conversation Approval timeout -> escalate to backup approver workflow Linked app failure -> escalate to vendor operations screen ``` Escalation should include enough context for the next person to understand the problem without reopening the entire workflow history. ### 15. Common Configuration Patterns #### Broad Operations Repair Desk Use this when one operations team handles all exceptions in the app. | Setting | Recommended value | | --------------------------- | --------------------------- | | Listen scope | Entire app | | Visibility | Operators or admins only | | Payload visibility | Redacted preview | | Show timeline | On | | Require claim before action | On | | Escalate target | Support or manager workflow | #### Workflow-Specific Recovery Use this when a single workflow has a known failure mode. | Setting | Recommended value | | --------------------------- | ---------------------------------------------- | | Listen scope | Specific workflow | | Workflow | The workflow that creates the exception | | Title | Name the business process, not the workflow ID | | Payload visibility | Redacted preview | | Show timeline | On | | Require claim before action | Usually on | #### Form Intake Repair Use this when a submitted form may be missing or mismatching information. | Setting | Recommended value | | --------------------- | -------------------------------------------- | | Listen scope | Specific screen or form | | Source screen or form | The intake form | | Title | Intake Exceptions or Request Intake Recovery | | Payload visibility | Metadata only or redacted preview | | Escalate target | Conversation or intake owner workflow | #### Failed Message Recovery Use this when messaging is part of the failure. | Setting | Recommended value | | ------------------------ | ------------------------------------------------- | | Listen scope | Conversation or message thread | | Channel | The message channel, such as approvals or support | | Topic | The specific event topic | | Conversation/correlation | Use when tying to one thread | | Payload visibility | Metadata only or redacted preview | | Escalate target | Conversation or notification recovery workflow | #### Linked App Handoff Recovery Use this when one app sends work to another app. | Setting | Recommended value | | ------------------ | --------------------------------------- | | Listen scope | Linked application | | Linked application | The partner or destination app | | Channel/topic | The app-to-app exchange route | | Payload visibility | Redacted preview | | Show timeline | On | | Escalate target | Linked app exchange or operator console | ### 16. End-To-End Example: Missing Webhook Data Goal: ``` An external webhook starts a workflow. If the payload is missing required data, an operator reviews the exception and decides whether to repair, resolve, or escalate it. ``` Recommended setup: | Setting | Value | | --------------------------- | ----------------------------------------- | | Screen type | Exception Resolution | | Listen scope | Specific workflow | | Workflow | Webhook Intake Workflow | | Screen title | Webhook Intake Exceptions | | Payload visibility | Redacted preview | | Show timeline | On | | Require claim before action | On | | Escalate target | Support workflow or operator conversation | Workflow behavior: 1. Receive the webhook. 2. Validate required fields. 3. If required fields are missing, create an exception item. 4. Include a safe payload summary, missing field names, source event, and correlation reference. 5. Let an operator claim the exception. 6. Operator repairs the source data or escalates it. 7. Operator marks the exception resolved only after the issue is actually handled. ### 17. End-To-End Example: Approval Timeout Goal: ``` A manager did not approve a request before the deadline. An operations user reviews the timeout and escalates to another approver. ``` Recommended setup: | Setting | Value | | --------------------------- | ----------------------------------- | | Screen type | Exception Resolution | | Listen scope | Specific workflow | | Workflow | Approval Routing Workflow | | Screen title | Approval Recovery | | Payload visibility | Redacted preview | | Show timeline | On | | Require claim before action | On | | Escalate target | Backup Approver Escalation workflow | Workflow behavior: 1. Create the approval decision. 2. Wait for the decision. 3. If the wait expires, create an exception item. 4. Exception appears on the Exception Resolution screen. 5. Operator claims it. 6. Operator escalates to a backup approver or manually follows up. 7. Operator marks resolved after the approval route is repaired or closed. ### 18. End-To-End Example: Failed Notification Goal: ``` A workflow tried to notify a user, but delivery failed. A support operator reviews the failed notification and decides whether to resend, contact manually, or close. ``` Recommended setup: | Setting | Value | | ------------------ | ------------------------------ | | Screen type | Exception Resolution | | Listen scope | Conversation or message thread | | Channel | notifications or support | | Topic | notification.failed | | Payload visibility | Metadata only | | Show timeline | On | | Escalate target | Support Conversation screen | Workflow behavior: 1. Workflow attempts notification. 2. Delivery fails. 3. Workflow creates an exception with recipient and safe delivery metadata. 4. Operator reviews the details. 5. Operator escalates to support conversation or marks resolved after manual contact. ### 19. Testing Checklist Before publishing, run this checklist. #### Setup Checks * The app has Automation enabled. * The screen type is Exception Resolution. * The listen scope matches the intended business process. * The selected workflow, screen, channel, topic, or linked app is correct. * The title and description are clear to the intended resolver. * Payload visibility is no more permissive than necessary. * Timeline visibility is appropriate. * Claim policy matches how the team will work. * Allowed roles and users are correct. * The empty state explains what will appear later. #### Runtime Checks * Create a controlled failure. * Confirm the exception appears on the screen. * Confirm unrelated exceptions do not appear. * Confirm the right user can see the screen. * Confirm the wrong user cannot see the screen. * Confirm payload details are useful. * Confirm support references are collapsed. * Confirm sensitive fields are hidden. * Claim the item if claiming is required. * Complete or mark resolved and confirm it leaves active recovery. * Escalate and confirm the target screen or workflow receives the context. * Review Activity, workflow status, or timeline to confirm the action was recorded. #### Mobile Checks * The title wraps cleanly. * Details do not overflow. * Action buttons remain reachable. * Support details can be opened and closed. * Timeline entries remain readable. * Empty and error states are understandable. ### 20. Troubleshooting | Problem | Likely cause | What to do | | ------------------------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | No exceptions appear | The workflow failed but did not create an exception item, or the listen scope is too narrow. | Confirm the workflow creates exceptions or failed automation items. Check listen scope. | | Too many exceptions appear | The listen scope is too broad. | Bind the screen to a specific workflow, form, channel, or linked app. | | The wrong users see the screen | Visibility rules or allowed roles/users are too broad. | Review private app setup, user database fields, visibility filters, allowed roles, and allowed users. | | A valid user cannot see the screen | Role name mismatch, missing user database value, or overly strict AND rules. | Compare the user's record to the visibility and allow-list rules. | | Payload details are unreadable | The workflow did not provide a useful payload summary. | Update the workflow to include plain-language summary fields. | | Sensitive data is visible | Payload visibility is too permissive or redaction is incomplete. | Change to metadata only or redacted preview. Hide sensitive fields. | | Support references confuse users | Users are opening technical details they do not need. | Keep support details collapsed and improve the business summary. | | Escalate does nothing useful | No target workflow or after-action screen is configured. | Configure the escalation action route. | | Mark resolved/Complete is unsafe | The action closes the issue without enough validation. | Route the action through a workflow or require a manual verification step. | | The template screen is empty after cloning | The source binding may still point to the original app's objects. | Check Template setup state and run repair/setup validation. | | Preview data looks wrong | Sample item, workflow run, or persona does not match the screen source. | Select a sample object from the same workflow, form, channel, or app context. | | Timeline is missing | Show timeline is disabled or the runtime item has no timeline entries. | Enable timeline and confirm the workflow records events. | ### 21. Maker Best Practices Use plain business language. The user should see: ``` Vendor insurance approval could not be routed because the vendor contact is missing. ``` Not: ``` workflow_step_id 6a... failed with payload validation error ``` Keep technical references available, but secondary. Do not expose exception resolution to every app user. Use claim ownership when multiple people can handle the same work. Use redacted preview unless there is a clear reason to show full payloads. Create one broad exception screen only when one team owns all exceptions. Create workflow-specific exception screens when the app has several complex routes. Test with a real controlled failure, not only simulated preview. ### 22. Recommended Default Configuration For most makers, start here: | Setting | Recommended default | | --------------------------- | ------------------------------------------------------------------------------------------- | | Listen scope | Specific workflow, if known; otherwise Entire app | | Visibility | Operators, supervisors, or admins only | | Allowed roles | `Supervisor`, `Operations`, or `App Admin` | | Payload visibility | Redacted preview | | Density | Comfortable | | Show timeline | On | | Require claim before action | On | | Empty title | No exceptions need attention | | Empty description | Failed workflow work appears here when an operator needs to review, repair, or escalate it. | | Escalation | Route to a manager, support workflow, or conversation | ### 23. Simple Explanation For Makers Use this short explanation when training a maker: ``` The Exception Resolution screen is where trusted users repair automation problems. Bind it to the app, a workflow, a form, a message thread, or a linked app route. Limit who can see it, show only the safe details they need, and give them clear actions: claim the issue, fix or investigate it, mark it resolved, or escalate it. ``` ### 24. Final Readiness Test The screen is ready when a maker can say yes to all of these: * I know which business process creates these exceptions. * I know who is allowed to resolve them. * I know what information those users need. * I know what information should be hidden. * I know what each action does. * I tested a safe failure and saw it appear. * I resolved or escalated the test exception successfully. * The timeline or Activity agrees with the action taken. * A user who should not see the screen cannot access it. If any answer is no, keep the screen in testing until the setup is clear.