> For the complete documentation index, see [llms.txt](https://docs.notionapps.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.notionapps.com/automation/notionapps-automation-current-state-guide.md). # 📡 NotionApps Automation Current State Guide ## NotionApps Automation Current State Guide ### NotionApps Automation Current State Guide This guide is the current reference for the Automation, Workflow, Messaging, live demo, and template provisioning work added in the `feature/application-messaging-foundation` branch. Use it when an older guide mentions Workflow Foundation, Messaging Foundation, live demos, managed data, template provisioning, or operational screens and you need the current product-level interpretation. #### Current Product Language Public-facing product, pricing, and marketplace language should use **Automation (Beta Testing)** as the umbrella term. Automation includes three major capabilities: | Capability | Plain-language meaning | Typical use | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | Workflow | Moves work through steps, decisions, approvals, routes, retries, and operational queues. | "When this timecard is submitted, route it to the supervisor, wait for a decision, and send payroll the approved result." | | Messaging | Sends and receives messages, announcements, routed notifications, direct conversations, and workflow-aware replies. | "Let the supervisor and employee discuss this record privately, and let payroll broadcast a service announcement." | | Approval Management | Controls approval-specific runtime surfaces and approval setup. It unlocks decision screens, work queues, workflow approval routes, and approval admin operations. | "Let supervisors claim review work, approve or reject requests, and let Workflow continue after the decision." | Builder-facing documentation can still use **Workflow Foundation**, **Messaging Foundation**, and **Approval Management** where it describes the technical modules. Maker-facing documentation should normally say **Automation**, then explain that Workflow, Messaging, and Approval Management are the capabilities underneath it. #### Entitlements And Visibility Automation is entitlement-gated. * The builder Automation rail should only appear when the account/application has the proper entitlement. * Workflow, Messaging, and Approval Management can be controlled separately by admin entitlement settings. * Native automation and operational screens should not be available when the required entitlement is disabled. * Public pricing should describe this as **Automation (Beta Testing)** or **Automation Beta Testing**. * Advanced features should fail closed with clear, dismissible messages instead of runtime errors. The admin panel is the source of truth for enabling granular access. It should let an administrator control Workflow, Messaging, Approval Management, operational screens, live publish behavior, and related beta access in the same spirit as Workflow, Custom JavaScript, Custom CSS, custom fonts, and other premium controls. Approval Management is intentionally separate from Workflow and Messaging. Workflow can route the process, and Messaging can carry requests, replies, conversations, and announcements, but approval-specific screens and approval setup are controlled by Approval Management. The current granular Approval Management flags are: | Approval flag | What it controls | | ------------------ | ---------------------------------------------------------------------------------------------------------------- | | Decision screens | Whether makers can add and run focused approve/reject/hold screens. | | Work queues | Whether makers can add and run claim/review/complete queue screens. | | Workflow approvals | Whether workflow approval setup, approval routes, and approval-oriented guided tests can be created or executed. | | Admin operations | Whether admin approval support operations are available for the account or application. | #### Builder Experience The current builder experience is designed around plain-language setup first and power-user configuration second. Core builder areas: | Area | Purpose | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Automation Home | Shows the current required step only. New work starts with Outcome Builder; future setup, testing, repair, and management tools appear progressively. | | Recipes | Lets makers start with outcomes such as "notify after form submission" or "broadcast announcement." | | Route Map | Shows trigger, source, target, audience, workflow, messaging, and risk details before publishing. | | Debugging | Explains recent workflow runs, messages, and failures in maker language. | | Access | Explains missing entitlements and upgrade paths. | | Workflows | Opens the advanced workflow builder for routes, versions, simulation, and activity. Workflow Overview now uses the same outcome-first progressive path before exposing advanced workflow controls. | | Messaging | Opens the messaging builder. Messaging Overview now uses the same outcome-first progressive path before exposing channel, contract, publisher, subscriber, announcement, and activity tools. | | Approval Management | Opens the admin-facing approval access controls and supports approval-specific screen and route readiness. | Context-aware selectors should be used wherever a maker would otherwise need to remember raw IDs. Suggestions should include screens, hidden screens, forms, controls, data sources, workflows, channels, conversations, and saved IDs when relevant. Control suggestions should include the control type so the maker knows whether they selected a form, text input, button, relation, date field, or other component. #### Outcome-First Automation Model Automation should increasingly feel like: ``` The maker describes the business outcome, and NotionApps assembles the engine. ``` This applies to Workflow and Messaging. **Workflow** Workflow should guide makers from outcomes such as: * "When this form is submitted, notify the reviewer." * "When a request is approved, update the record and tell payroll." * "When an exception happens, create a queue item and escalate after 24 hours." The builder can then generate or recommend triggers, steps, waits, decisions, notifications, and data mappings. **Messaging** Messaging should guide makers from outcomes such as: * "Notify the right person when this happens." * "Broadcast an announcement to everyone." * "Start or continue a conversation around this item." * "Send an event to another system." The Messaging guided setup should then recommend the channel, topic, contract, publisher, subscriber, fields, payload example, and dry-run path. The low-level objects remain visible for advanced makers, but they should not be the first thing a normal maker has to understand. **Product Principle** The advanced objects are still important because they make the platform reliable and supportable. The UI should reveal them progressively: 1. Business outcome. 2. Detected intent and confidence. 3. Numbered business questions. 4. Generated object plan. 5. Context-aware source, destination, data source, recipient, timing, and message selection. 6. Guided creation of the workflow draft or approval setup. 7. Guided testing and activity review. 8. Advanced object editing only when needed. The home/overview screens should not present these as simultaneous panes for a new maker. They should show the current required step, then reveal the next step after the maker finishes the current one. **What NotionApps will build** belongs after an outcome exists. **Continue work**, **Guided path**, and **Manage / monitor** belong in a secondary tools area once the app has real automation, workflow, or messaging work to manage. Current implementation note: * Automation Home now has a unified outcome-first guide that sits above Workflow, Messaging, and Approval Management. * Automation Home uses a single-current-step progression: Outcome Builder, build-plan review, setup workspace, testing, repair when needed, and then management. * The maker-facing route explanation tells the builder what NotionApps will build in plain language before advanced objects are generated. * Proof steps show whether the recipe has been saved, previewed, generated, and verified in Activity. * Repair-first diagnostics tell the maker what to fix next and route them to Access, Recipes, Preview, Route Map, or Activity instead of leaving them with raw setup failures. * Workflow Overview now starts with Outcome Builder for new work and hides future workflow steps until the maker has enough context for them. * Makers type a plain-language sentence and receive examples/context suggestions. * The system classifies common outcomes: notification, approval, announcement, conversation, integration/webhook, follow-up record, and escalation. * Non-approval outcomes create saved workflow drafts using existing Workflow Foundation APIs. * Approval outcomes call the approval provisioning path so approval screens, workflow route, and validation are created by the existing Approval Management setup flow. * Generated objects remain editable in the advanced Workflow builder after creation. * Messaging Overview and Guided setup now follow the same outcome-first model. * Messaging Overview starts with the messaging outcome for new routes, then shows the route plan, source/destination questions, route creation, testing, and management states progressively. * Makers describe the route in business language, answer numbered source/destination/payload questions, review a generated route plan, and use one action to create or reuse the channel, save and publish the contract, attach the publisher, attach the subscriber, and dry-run the route when live publish is available. * Messaging route objects remain visible in the advanced Messaging builder after creation so support teams can inspect channels, contracts, publishers, subscribers, and activity without forcing normal makers to start there. #### Native Automation And Operational Screens Native screens make Workflow and Messaging visible inside the app runtime. They should use the same visibility and permission model as data screens, with advanced permission logic available where appropriate. Current screen families include: | Screen | What it does | | -------------------- | ----------------------------------------------------------------------------------------------------------------- | | Notification Center | Shows announcements, service messages, routed notifications, and workflow notices. | | Conversation | Supports direct and contextual conversations between authenticated app users. | | Work Queue | Lets a user claim, review, complete, escalate, or release work. Requires Approval Management work-queue access. | | Decision | Presents a focused approval/rejection/hold decision surface. Requires Approval Management decision-screen access. | | Operator Console | Shows operational events, workflow state, exceptions, and message activity. | | Workflow Status | Lets users see where work is in a route. | | Exception Resolution | Helps operators resolve failed or blocked workflow paths. | | Linked App Exchange | Supports handoff events between applications. | | Automation Launcher | Lets a maker expose safe launch actions in the runtime. | Conversation screens should remain generic. Timecard and inventory demos can use record-aware conversation IDs, but the screen itself should not be hard-coded to those applications. The desired model is: 1. Authenticated users can start direct conversations with other authenticated users. 2. Workflows can create or reuse contextual conversation IDs tied to a record, route, or run. 3. Broadcasts and announcements use announcement channels, not private conversation threads. 4. The UI groups conversations clearly so supervisors, employees, operators, and admins can find the right thread. #### Live Demo Operations Live demos are managed through the admin panel. A live demo should be treated as a public product asset, not as a direct pointer to a maker's mutable app. The recommended public demo mode is **Managed sandbox**: * A separate sandbox application is created. * A separate Notion data model is provisioned in the configured demo-owner workspace. * Seed data and personas are created for the demo. * Workflow, Messaging, and Approval Management access are copied and remapped when the source app requires them. * The sandbox app is published. * Validation and repair run before the demo can safely become public. Important admin fields: | Field | Plain-language meaning | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Public visibility | Whether the demo appears on the public Live Demos page. Keep hidden while validating. | | Sort order | Lower numbers appear first on the public page. | | Source mode | Whether the demo uses a managed sandbox or another source mode. Public automation demos should use managed sandbox. | | Managed data | Whether the demo has its own sandbox datastore ready. | | Max code requests before cleanup | The request threshold that tells admins when demo access state should be cleaned. | | Audit reason | A short reason recorded when changing, validating, repairing, or resetting a demo. | The live demo list/detail screen should stay usable at scale: * Demos appear in a searchable list. * Details open only after selecting a demo. * Settings stay readable and unsquashed. * Validate and Repair show clear status. * Hidden demos can be previewed by admins before becoming public. * Personas and code-generation state are visible from the admin detail view. #### Provisioning Health And Repair Provisioning health prevents broken demos and templates from becoming public. The validator should check: * Application record exists and belongs to the expected account. * Linked data sources are available. * Duplicate source/clone data families are not present. * Screens, versions, workflow references, and messaging references do not point to stale IDs. * Approval decision screens, work queues, and approval workflow routes have the required Approval Management access. * Screens are available for builder and live runtime. * Published live version exists. * User authentication sheet exists when the app requires login. * Date fields and cloned timestamps are valid. * Account snapshots and app ownership are coherent. Repair should be able to: * Remove stale references when safe. * Reconnect or normalize cloned references. * Normalize malformed date values and cloned timestamp metadata. * Repair account snapshots. * Re-run provisioning checks after repair. Public demos should not be visible unless provisioning health is ready. If health is not ready, the admin UI should explain the blocker and offer repair when repair is safe. #### Template Provisioning Template provisioning now needs the same level of safety as live demo provisioning. A marketplace template that depends on data, Workflow, Messaging, or native operational screens should not point directly at a maker-owned app or mutable maker-owned Notion workspace. The safer pattern is: 1. Admin selects a source application. 2. System creates managed Notion data under the approved template/demo owner workspace. 3. System clones the app against that managed data. 4. System copies and remaps screens, navigation, visibility, filters, data bindings, workflows, messaging channels, subscriptions, announcements, recipes, and required Approval Management access. 5. System creates or imports sample personas when needed. 6. System validates clone health and provisioning health. 7. Admin publishes the marketplace listing only after the publish assistant says it is ready. Clone should be blocked up front when the target account lacks required Automation entitlements, including Approval Management when the template contains decision screens, work queues, or workflow approval setup. A maker should never receive an advanced cloned app that looks complete but cannot run workflows, messages, approval surfaces, operational screens, or announcements. #### Current Reference Applications **Timecard Management** Timecard Management is the first complete Workflow + Messaging example. * Source app URI: `3zloxi` * Managed live demo URI: `4i6rgd` * Primary capabilities: timecard drafting, time entry, submission, supervisor review, approval/rejection/hold, payroll export, direct conversations, notifications, announcements, and personas. * Documentation: * Timecard Management Application Guide * Timecard Management Ground-Up Build Guide * Managed Sandbox Live Demo Provisioning UI Guide **Inventory Management** Inventory Management is the second full exercise of data + Automation. * Source app URI: `999vu7` * Managed live demo URI used during testing: `g381x1` * Primary capabilities: item catalog, stock balances, locations, requests, approval management, purchasing, audit/operator views, direct/group conversations, announcements, and notifications. * Provisioning health note: `g381x1` uses generated workflow routes. Automation Home preflight now inspects the actual generated workflows; active valid workflows report ready, paused workflows report review with names, and missing/invalid routes report blocked. * Documentation: * Inventory Management Application Requirements * Inventory Management Build Map * Inventory Management How-To Use Guide * Inventory Management Playwright Test Results **Service Request / Work Order Management** Service Request / Work Order Management is a proposed reference requirement for data + Automation. * Source app URI: not assigned yet. * Managed live demo URI: not assigned yet. * Primary capabilities: service request intake, work order dispatch, technician queues, SLA escalation, governed approvals, requester/technician conversations, notifications, announcements, exception recovery, and operator health. * Documentation: * Service Request / Work Order Management Application Requirements #### Pricing And Website Copy Pricing and marketing language should describe **Automation (Beta Testing)** as the premium area. Supporting copy should explain that Automation combines Workflow and Messaging. Recommended message: > Automation brings Workflow and Messaging together so teams can move work, route decisions, send notifications, manage conversations, and broadcast announcements directly inside their NotionApps applications. This keeps the packaging simple while still making the underlying engines clear. #### Documentation Rule Going Forward When adding or updating docs: 1. Use **Automation** for product and pricing language. 2. Use **Workflow** when describing process execution. 3. Use **Messaging** when describing channels, conversations, notifications, announcements, or routed message events. 4. Use **Approval Management** when describing approval queues, decision screens, approval setup, approval exceptions, or the entitlement that unlocks those surfaces. 5. Use **Workflow Foundation** and **Messaging Foundation** only when describing internals, entitlement flags, or implementation-specific admin controls. 6. Mention beta status as **Automation (Beta Testing)** in public-facing pricing or plan comparison material. 7. For templates and live demos, always document whether the app is source-owned, shared-source, or managed sandbox. 8. For managed sandbox demos/templates, document the provisioning health status and the repair path, including whether Approval Management access was required and copied.