> 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-how-to-guide.md).

# ⚙️ NotionApps Automation How-To Guide

## NotionApps Automation How-To Guide

### NotionApps Automation How-To Guide

![Automation route map concept](https://content.gitbook.com/content/5ZqDXcVVffWUqEIZVhmn/blobs/DxhQc0b6wKhbev9QV4Ax/assets/automation-wizard-e2e/00-automation-home-wizard-catalog.png)

> Support visual: this image shows the Automation home as the builder's plain-language front door. Recipes, route maps, generated objects, and status indicators sit together so a maker can understand what will happen before anything is published.

> Current state: public product and pricing language should call this capability **Automation (Beta Testing)**. Automation is the umbrella over Workflow and Messaging. For the latest entitlement, live demo, template provisioning, managed sandbox, and repair behavior, see the NotionApps Automation Current State Guide.

Automation is the builder-facing home for recipes, routes, Workflow Foundation, Messaging Foundation, diagnostics, and access checks. It exists so a maker can start with a business outcome instead of deciding whether to use Workflow, Messaging, contracts, publishers, subscribers, or advanced identifiers first.

Use this guide when you want to build an automation from intent, understand the Automation pages, generate the underlying objects, or troubleshoot why a recipe did not behave as expected.

For the complete cross-tool explanation, examples, support playbooks, and entitlement model, see the Automation, Workflow, and Messaging Support Handbook.

#### How To Use This Guide

Read the first sections if you are new to Automation. Start with the recipe walkthroughs if you already know the outcome you want. Use the troubleshooting and access sections when a builder sees a disabled button, a missing menu item, or a route that did not run.

The examples intentionally use plain names like "Client Intake" and `someone@notionapps.com`. In a real app, replace those with the actual screen, form, user database property, role, or email address that appears in the context-aware picker.

#### Who This Guide Is For

This guide is for app builders and app owners who want to say things like:

* "When this form is submitted, email this person."
* "When a user clicks this button, request approval."
* "Broadcast this announcement to everyone using the app."
* "When no one replies after 24 hours, escalate."
* "When an external system sends an event, create a record."
* "Show me what will happen before I publish."

If you are an advanced builder, Automation is still useful because it generates valid Workflow and Messaging configuration for you. You can then open the advanced Workflow or Messaging pages to inspect and refine the generated objects.

#### The Simple Mental Model

Automation now follows a progressive path. The maker should see only the current required step, not every possible setup panel at once:

```
Describe the business outcome
-> let NotionApps match the recipe
-> review what NotionApps will build
-> answer the source, destination, data, recipient, timing, or message questions that are still missing
-> create the workflow, approval setup, or messaging route
-> test the result
-> manage or monitor the generated objects only after there is real automation work to manage
```

Automation does not replace Workflow Foundation or Messaging Foundation. It sits above them.

* Workflow Foundation performs multi-step work.
* Messaging Foundation routes structured events, announcements, requests, replies, linked-app handoffs, and webhooks.
* Automation gives makers a plain-language recipe layer over both.

#### Outcome Builder

The preferred starting point is now **Outcome Builder**.

Outcome Builder is designed for makers who know what the business should do, but do not know whether that requires Workflow, Messaging, Approval Management, an announcement route, a conversation binding, a webhook, or a generated test.

Outcome Builder is the only visible starting point for a new automation path. Future steps are hidden until the maker finishes the current step. This is intentional. The home screen should not ask a maker to understand route maps, generated objects, preflight diagnostics, advanced workflow steps, messaging contracts, publishers, subscribers, or activity logs before they have named the business result.

Instead of asking the maker to start with technical primitives, Outcome Builder asks:

```
What do you want this app to do?
```

The maker can type a sentence such as:

```
When an employee submits a timecard, route it to their supervisor, open a private conversation, and notify payroll after approval.
```

NotionApps then:

1. Matches the sentence to the closest business outcome.
2. Shows a confidence label so the maker knows whether the match is obvious or should be reviewed.
3. Asks numbered follow-up questions only for the missing business details.
4. Uses the current app context to suggest friendly screens, forms, buttons, data sources, workflows, and roles when available.
5. Shows **What NotionApps will build** only after an outcome exists.
6. Creates the underlying automation object when the maker clicks **Build this automation**.
7. Reveals testing, activity, and advanced management tools only after there is something to test or manage.

The maker does not need to know screen IDs, workflow IDs, payload paths, channels, contracts, or subscribers to start. Those details remain available after generation for advanced tuning and support.

**Supported Outcome Starters**

Outcome Builder currently recognizes common business outcomes such as:

| Outcome                                              | What NotionApps assembles                                                                                                 |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Notify the right person when work is submitted       | Saved workflow draft with the selected trigger, confirmation message, Notify step, recipient, and end step.               |
| Route a request for approval                         | Approval workflow setup through the approval provisioning path, including approval pages, workflow route, and validation. |
| Broadcast a service announcement to everyone         | Saved workflow draft that publishes to the announcements channel.                                                         |
| Start a work conversation                            | Saved workflow draft that publishes a conversation message tied to the triggering event.                                  |
| Let an external system call or receive from this app | Saved workflow draft using webhook intake or webhook notification delivery.                                               |
| Create a follow-up record                            | Saved workflow draft with a Create record step and optional owner notification.                                           |
| Escalate when nobody responds                        | Saved workflow draft with Notify, Wait, Escalate, and End steps.                                                          |

**What The Maker Sees**

The home screen should show one current step at a time:

1. **Outcome Builder**: the first screen for new work. The maker types the business result or chooses a suggested outcome.
2. **What NotionApps will build**: appears after the outcome exists. It explains the workflow, messaging, approval, screen binding, guided test, and repair objects that may be created.
3. **Finish the setup workspace**: appears when a draft or route exists but still needs source, destination, data, recipient, timing, or message answers.
4. **Generate and test**: appears after setup is ready and before the automation has proven activity.
5. **No required action right now**: appears when generated objects or recent activity already exist.

Secondary tools such as **Continue work**, **Guided path**, and **Manage / monitor** appear only after there is automation work to manage. They should not compete with the current required step on a brand-new setup.

Repair-first diagnostics may still interrupt the normal path. When access, payload, preview, destination setup, or generated object health is blocked, the home screen should show the repair step first and route the maker to the correct screen.

This is the simple promise:

```
Maker describes the business outcome.
NotionApps assembles the engine.
Maker reviews, tests, and publishes.
```

**Why This Matters**

The maker should not have to know whether the final result is a workflow step, messaging route, approval setup, announcement, publisher, subscriber, or contract. Automation translates the business request into a route, explains what it is about to build, and then asks the maker to prove the behavior with guided tests.

The advanced objects still exist because they make NotionApps supportable. They are exposed after the guided path has done the first draft, not as the first thing a normal maker must understand.

**Walkthrough: Build A Simple Notification**

Use this walkthrough when a maker wants the most common automation: notify someone after a form or screen submission.

1. Open the app builder.
2. Select **Automation**.
3. Use the first visible home step. In Automation Home or Workflow Overview, this should be **Outcome Builder** for new work.
4. In **Tell NotionApps what should happen**, type:

```
When the intake form is submitted, notify someone@notionapps.com.
```

5. Confirm that the detected pattern is **Notify the right person**.
6. For **Where should this start?**, choose the friendly form or screen name from the picker.
7. For **Who should receive it?**, enter the email address, role, or recipient description.
8. For **What should people see?**, enter the message that should appear in the notification.
9. Review **What NotionApps will build**. It should explain the trigger, recipient, confirmation, and workflow end state.
10. Click **Build this automation**.
11. Open **Build** to review the generated workflow draft.
12. Click **Save draft** if you changed anything.
13. Click **Publish** when validation is clean.
14. Use **Simulate** or submit the real form as a test user.
15. Open **Activity** to confirm that a run was created and completed.

**Walkthrough: Build An Approval Path**

Use this when a request should be claimed, reviewed, approved, rejected, or sent back.

The exact build order matters:

1. Build the normal data/form screen where the requester submits the record.
2. Build or generate the approval workflow.
3. Create the Work Queue Automation screen for the reviewer inbox.
4. Create the Decision Automation screen for approve, reject, and request-changes actions.
5. Bind both Automation screens to the approval workflow.
6. Set screen visibility and navigation for the requester and approver roles.
7. Create a test request and verify the full route.
8. Publish only after the test passes.

This order prevents the most common approval setup mistake: creating a workflow that can run, but forgetting to give the reviewer a clear screen where the request can be found and decided.

1. In **Tell NotionApps what should happen**, type:

```
Route this request to a manager for approval.
```

2. Confirm that the detected pattern is **Route work for approval**.
3. Choose the form or screen that submits the request.
4. Add a plain-language test title or message.
5. Click **Build this automation**.
6. NotionApps runs the approval setup path instead of creating only a generic workflow draft.
7. Review the approval setup status, pages, message channel readiness, and validation details.

**Create The Approval Inbox Before Testing**

The workflow is the engine, but reviewers still need a screen inside the live app where they can see and act on approval work. Do not skip this step.

The approval setup wizard may ask for a reviewer destination such as Decision or Work Queue. That choice tells NotionApps what kind of approval experience the route should use. The maker still needs to create or confirm the actual Automation screens in the app.

First create the reviewer inbox:

| Screen                     | Builder choice                             | Purpose                                          |
| -------------------------- | ------------------------------------------ | ------------------------------------------------ |
| Procurement Approval Inbox | **New Screen -> Automation -> Work Queue** | Shows approvers the requests waiting for review. |

Configure the Work Queue screen:

1. Open **Screens** in the builder.
2. Click **New Screen**.
3. Choose the **Automation** group.
4. Select **Work Queue**.
5. Name the screen `Procurement Approval Inbox`.
6. Open **Source binding**.
7. Choose **Specific workflow** when the queue should only show procurement approvals.
8. Search for and select the generated procurement approval workflow by its friendly name.
9. Open **Permissions** or screen visibility.
10. Make the screen visible only to the approver role, such as `Manager`, `Procurement Approver`, or `Admin`.
11. Add the screen to navigation for approvers.
12. Hide it from requesters if requesters should only submit and track their own requests.

This is the reviewer inbox. It answers: "What approval work is waiting for me?"

**Create The Decision Screen Before Testing**

Now create the Decision screen. This is required for a real approval experience. Do not move to validation or test requests until this screen exists.

| Screen                        | Builder choice                           | Purpose                                                                       |
| ----------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------- |
| Procurement Approval Decision | **New Screen -> Automation -> Decision** | Shows one selected request with Approve, Reject, and Request changes actions. |

Configure the Decision screen:

1. Click **New Screen** again.
2. Choose the **Automation** group.
3. Select **Decision**.
4. Name the screen `Procurement Approval Decision`.
5. Open **Source binding**.
6. Choose **Specific workflow**.
7. Select the same procurement approval workflow.
8. In display settings, show the fields an approver needs, such as requester, vendor, amount, department, reason, needed-by date, and current status.
9. Confirm the actions read as Approve, Reject, and Request changes.
10. If one approver should own each request, enable claim-before-action on the Work Queue or Decision screen.

This is the decision surface. It answers: "What am I approving, and what action should I take?"

Connect the screens to the workflow:

1. Open **Automation -> Workflows**.
2. Select the generated approval workflow.
3. Confirm the workflow creates a review item or decision item for the approver.
4. Confirm the review item opens the `Procurement Approval Decision` screen or uses the Decision screen as the approval surface.
5. Confirm the approved, rejected, and request-changes paths update the submitted record or notify the requester.

Now test the route:

1. Click **Create test request** from the approval setup panel, or submit the real request form as a requester.
2. Switch to an approver test user.
3. Open **Procurement Approval Inbox**.
4. Confirm the request appears in the inbox.
5. Open the request.
6. Confirm the `Procurement Approval Decision` screen shows a plain-language summary, not raw JSON.
7. Click Approve, Reject, or Request changes.
8. Open **Automation -> Activity** and confirm the workflow followed the selected path.
9. Open **Exception Resolution** or the approval activity screen and confirm no unexpected failures were recorded.
10. Repeat the test for Reject and Request changes.
11. Publish only after the test request reaches the correct reviewer path and the requester sees the expected result.

**Walkthrough: Build A Timed Escalation**

Use this when work should not sit forever.

1. Type:

```
If nobody responds within 24 hours, escalate the request to operations.
```

2. Confirm that NotionApps detected **Wait, then escalate**.
3. Choose where the automation starts.
4. Enter the recipient or escalation owner.
5. Enter the wait time in hours.
6. Enter the message that should be sent first.
7. Click **Build this automation**.
8. Open **Build** and confirm the generated steps are Notify, Wait, Escalate, End.
9. Adjust the wait duration or escalation recipient if needed.
10. Publish and test with a shorter wait duration before using it in production.

**When To Use Outcome Builder Instead Of Recipes**

Use Outcome Builder when the maker starts with a business sentence:

* "Notify someone when this is submitted."
* "Route this to my manager for approval."
* "Start a private conversation about this record."
* "Tell everyone about a service issue."
* "Create a record when an external system calls us."
* "Escalate if nobody responds."

Use **Recipes** directly when the maker already knows the exact pattern they want and only needs to configure the fields.

Use **Workflows** or **Messaging** directly only when the maker is intentionally editing advanced generated objects.

#### Where To Find Automation

Open an application in the builder and select **Automation**.

The Automation screen has a compact icon rail. Hover or focus each icon to see the full label and description.

The main sections are:

| Section   | Use it for                                                                                                                                   |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Home      | Start from the current required step. New work starts with Outcome Builder; existing work shows setup, testing, repair, or management.       |
| Recipes   | Choose and configure common business outcomes.                                                                                               |
| Route map | Preview trigger, data, destinations, blockers, and generated objects.                                                                        |
| Debugging | Read workflow and messaging activity in builder language.                                                                                    |
| Access    | Understand entitlement and plan limitations.                                                                                                 |
| Workflows | Open the advanced Workflow Foundation builder. Its Overview also starts with a progressive outcome-first path.                               |
| Messaging | Open the advanced Messaging Foundation builder. Its Overview now starts with a progressive outcome-first path before exposing route objects. |

#### What The Status Dots Mean

The compact Automation rail shows entitlement status dots near the top.

* Green Workflow dot: Workflow Foundation is available for this app.
* Red Workflow dot: Workflow Foundation is not available or is blocked.
* Green Messaging dot: Messaging Foundation is available for this app.
* Red Messaging dot: Messaging Foundation is not available or is blocked.

If an expected section is disabled, open **Access** and review the current entitlement source and scope.

#### Preflight Checks And Repair

Preflight checks still matter, but they should not make the home screen feel like a dashboard before the maker has an outcome. In the current progressive model, preflight and repair information appears when it is the next required action or when a route has enough context to evaluate.

Preflight answers:

* Is Automation available through Workflow Foundation, Messaging Foundation, or both?
* Does the selected recipe require Workflow, Messaging, or both?
* Does the app have screens, forms, controls, and data sources that can appear in friendly pickers?
* Has at least one recipe been saved for this app?
* Have route objects already been generated?
* Is there enough Activity visibility to debug a test run?

Each check shows one of three states:

| State   | Meaning                                                                 |
| ------- | ----------------------------------------------------------------------- |
| Ready   | This part is available and does not need attention.                     |
| Set up  | This part can be configured next.                                       |
| Blocked | Access or required configuration prevents the route from becoming live. |

When a check needs action, the button opens the right place: Access, Recipes, Workflows, Messaging, Route map, Debugging, or Generate objects. Makers should use these buttons instead of hunting through advanced tools.

Example:

```
Preflight says Messaging route support is blocked.
Open Access.
Confirm Messaging entitlement level and scope.
Enable the required level, then return to Automation.
```

#### Plain-Language Setup

The progressive path and Recipes page include a **Plain-language setup** guide. It walks the maker through the selected recipe in the order a business user expects:

1. Choose the business outcome.
2. Pick when this happens.
3. Pick who or what receives it.
4. Describe the result.
5. Confirm data requirements.
6. Map the data without JSON.
7. Save the recipe.

Use this guide to keep builders out of raw IDs, contracts, and payload JSON until they truly need advanced control.

Good builder language:

```
When the Client Intake form is submitted, notify someone@notionapps.com with the client name, email, and request type.
```

Avoid making the builder start with:

```
publisher.source_target_id = 6a...
subscriber.target_id = wf_...
payload_mapping[2].source_path = payload.fields.email
```

Those saved IDs still exist for runtime reliability and support, but the setup flow should keep them secondary.

#### Guided Testing

Automation also includes guided testing once the setup has enough information to test. On Home, testing appears as the current required step only after setup is ready. Route map and Activity remain available for deeper inspection.

Use it before beta testing or live rollout:

1. Run a no-send preview.
2. Fix blockers in plain language.
3. Generate the route objects.
4. Test as the real app user.
5. Verify what happened in Activity.

This is the recommended beta-readiness loop:

```
Preflight is clean
-> setup guide is complete
-> preview has no blockers
-> objects are generated
-> real user performs the trigger
-> Activity shows the expected workflow run/message/announcement
```

If a test fails, do not start by editing JSON. Open **Debugging** and read the plain-language explanation first. Then open Workflow or Messaging only when the diagnosis points to a generated object that needs refinement.

#### Recommended Recipes

Automation recommends recipes based on the app's current structure and access.

Examples:

* If the app has screens/forms, Automation may recommend "Form submitted -> notify someone."
* If Messaging announcements are enabled, Automation may recommend "Broadcast announcement."
* If external API access is enabled, Automation may recommend webhook or API intake patterns.

You can dismiss a recommendation when it is not relevant. If you later want it back, click **Reset dismissed recipes** in the Recommended recipes panel.

#### Recipe Anatomy

A recipe has four plain-language pieces.

**When This Happens**

This is the trigger. Examples:

```
Client Intake form is submitted
Request Approval button is clicked
External API publishes a message
Workflow sends an approval request
```

The trigger field is context-aware. Start typing a form, screen, button, control, data source, workflow, channel, topic, or route name. Suggestions include hidden screens when those screens can be reached through normal workflow or messaging paths.

**Destination**

This is who or what receives the result. Examples:

```
someone@notionapps.com
Manager approval workflow
Every app screen
Webhook subscriber
Operations app
```

**Action**

This is the business outcome in plain language. Examples:

```
Send an email notification
Show a confirmation message
Create a follow-up record
Publish an approval request
Broadcast a service announcement
```

**Audience Or Fallback**

This is the recipient default or backup route. Examples:

```
App owner
Support team
Everyone using this app
record.manager_email
```

#### Native Automation Screens

Automation can create or use native app screens that show automation state directly inside the live application. These screens are different from ordinary data screens. Ordinary data screens read Notion records. Native automation screens read workflow, messaging, announcement, queue, and operational runtime state.

Available native automation screen types:

| Screen type          | Use it when                                                                        |
| -------------------- | ---------------------------------------------------------------------------------- |
| Work Queue           | Users need a task inbox for approvals, follow-up work, exceptions, or assignments. |
| Decision             | A workflow pauses for a human approval, rejection, or request-changes decision.    |
| Workflow Status      | App owners or users need to see run progress, waits, retries, and outcomes.        |
| Conversation         | A workflow, message, or support path needs a private per-record discussion.        |
| Exception Resolution | Failed automation needs manual review and recovery.                                |
| Notification Center  | Announcements and routed notifications should remain visible after the banner.     |
| Automation Launcher  | Users should manually start approved workflows or service requests.                |
| Linked App Exchange  | Two applications exchange requests, replies, or payloads.                          |
| Operator Console     | Owners need a high-level operational view of runs, queue depth, and failures.      |

For step-by-step setup instructions, examples, and troubleshooting for each screen type, see the Native Automation And Operational Screen Guides.

When adding a screen, the picker uses different icons for each screen type. This helps builders scan quickly instead of seeing the same automation or messaging icon repeated.

Automation and Operational screen groups are entitlement-gated. Builders should not see these screen types unless the application has the required effective feature access. If a builder expects the group and it is missing, open **Access** first and verify Workflow, Messaging, native Automation screens, and Operational screens are enabled for the subscription plan, account, or application.

**Configure A Native Screen Without Raw IDs**

Open the native screen in the builder and use **Source binding**.

1. Choose **Listen scope**.
2. If the scope is **Entire app**, no source ID is required.
3. If the scope is **Specific screen or form**, search for the screen or form by friendly name.
4. If the scope is **Specific workflow**, search for the workflow by name, trigger, status, or ID.
5. If the scope is **Conversation or message thread**, search for channels, topics, recent conversations, or correlation IDs.
6. If the scope is **Linked application**, search for linked app routes.

Hidden screens may appear in suggestions. That is intentional. A screen can be hidden from navigation and still be reachable when a workflow or message route sends a user there.

Conversation screens should be configured as private business conversations, not broad chat rooms. A form submission, approval, support request, or timecard should create or reuse one conversation or correlation value. The screen opens the active conversation automatically when it can, and shows a compact switcher only when the user has more than one available conversation. Use Notification Center for broadcasts to all users.

**Configure Native Screen Actions**

Native screens can expose actions such as Claim, Complete, Approve, Reject, Acknowledge, Dismiss, Escalate, or Launch workflow. When an action needs a destination, use the context-aware picker:

* **After-action screen**: search for the screen users should see after the action.
* **Target workflow**: search for the workflow the action should start or escalate to.

The builder saves the correct ID behind the scenes. Makers should choose friendly names and only paste IDs when support or an advanced runtime case requires it.

**Test With Simulation Context**

Use **Empty state and simulation** to preview a native automation screen.

* **Sample item** can reference an app object, message, recipe, channel, workflow, or runtime ID.
* **Sample workflow run** loads recent runs after a workflow is selected.
* Custom runtime IDs can still be pasted when the event has not happened yet.

**Conversation Screen Setup Rule**

Use this rule whenever an Automation recipe creates a Conversation screen:

```
One record or workflow run = one conversation.
Replies stay with that conversation.
Announcements go to Notification Center.
```

Recommended participant fields in messages:

```
employee_email
supervisor_email
requester_email
reviewer_email
recipient_email
assignee_email
```

Those fields help the runtime show a private conversation to the right people without asking makers to manage raw access-control IDs.

#### How To Build: Email Someone When A Form Is Submitted

Goal:

```
When a form is submitted, send a native outbound email to someone@notionapps.com.
```

Use this path when the final delivery should be an email. Native email delivery belongs to Workflow Foundation's Notify step. Messaging can create the event, but Workflow's notification step is the email sender.

**Step 1: Open Automation**

Open the app in the builder and select **Automation**.

**Step 2: Choose The Recipe**

Open **Recipes** and choose:

```
Form submitted -> notify someone
```

**Step 3: Configure The Plain-Language Flow**

Set:

| Field                | Value                                                       |
| -------------------- | ----------------------------------------------------------- |
| When this happens    | Select the submitted form or the screen that owns the form. |
| Destination          | `someone@notionapps.com`                                    |
| Action               | `Send an email notification`                                |
| Audience or fallback | `someone@notionapps.com` or `App owner`                     |

If the picker shows screens instead of a separate form object, choose the screen that contains the form. Current live app form submission events are commonly matched through the screen.

**Step 4: Configure Guided Destination Setup**

Set:

| Field                     | Value                         |
| ------------------------- | ----------------------------- |
| Who or what receives this | `Specific email`              |
| Recipient value or path   | `someone@notionapps.com`      |
| Fallback                  | Optional, such as `App owner` |

**Step 5: Review Payload Mapping**

In **Contract auto-builder**, select fields that should be available to the generated workflow. For a notification, useful fields are:

* Submitted record id.
* Submitter name.
* Submitter email.
* Request type.
* Status or priority.

If a field contains an email address, set its type to **Email**.

**Step 6: Save The Recipe**

Click **Save recipe**.

Saving records the recipe intent and configuration. It does not guarantee live delivery until the generated objects are created and published.

**Step 7: Generate Objects**

Click **Generate objects**.

This creates or updates the underlying Workflow/Messaging objects needed by the recipe. In this example, the generated object should include a Workflow with a form or screen submission trigger and a Notify step.

**Step 8: Open Workflows**

Open **Workflows** from Automation.

Find the generated workflow. It may be named something like:

```
Form submitted -> notify someone
```

**Step 9: Confirm The Workflow Trigger**

In Workflow **Build**, confirm:

| Field            | Expected value                                      |
| ---------------- | --------------------------------------------------- |
| Trigger          | `Form or screen submitted`                          |
| Where it happens | `Screen` or `Form`, if you want one specific source |
| Target           | The specific form/screen                            |

If **Where it happens** is `Entire app`, the workflow can run for submissions across the app. That is valid, but broader than most notification workflows.

**Step 10: Confirm The Notify Step**

Select the Notify step and confirm:

| Field     | Value                                                               |
| --------- | ------------------------------------------------------------------- |
| Channel   | `Email`                                                             |
| Recipient | `someone@notionapps.com`                                            |
| Subject   | `New form submission`                                               |
| Body      | `A form was submitted in NotionApps. Please review the new record.` |

Email is the default Notify channel. If a cloned or older workflow step shows Email in the dropdown but the raw JSON does not yet include `channel`, NotionApps now validates it as email and writes `"channel": "email"` when the workflow is saved or published.

Power-user configuration should look like this:

```json
{
  "channel": "email",
  "recipients": ["someone@notionapps.com"],
  "subject": "New form submission",
  "body": "A form was submitted in NotionApps. Please review the new record."
}
```

**Step 11: Save And Publish**

Click **Save draft**, then **Publish**.

**Step 12: Test From The Live App**

Submit the form as an end user.

Open Workflow **Activity** and confirm a run appears.

Expected result:

* Run status is completed if the email sends successfully.
* If local development simulates email, Activity may show delivery as simulated.
* If the run fails, Activity should show a safe explanation.

#### How To Build: Button Click Requests Approval

Goal:

```
When a user clicks Request Approval, ask a manager to decide.
```

Use this when a button needs to start a structured process.

Recommended recipe:

```
Button clicked -> request approval
```

Plain-language setup:

| Field                | Example                                     |
| -------------------- | ------------------------------------------- |
| When this happens    | `Request Approval button`                   |
| Destination          | `Manager approval workflow`                 |
| Action               | `Send a notification and wait for decision` |
| Audience or fallback | `record.manager_email` or `App owner`       |

Generated objects may include:

* A Workflow triggered by a button click.
* A Messaging channel/topic such as `approvals/approval.requested`.
* A request message contract.
* A Workflow wait or reply path.
* An escalation path if no reply arrives.
* Approval Management surfaces such as a Decision screen, Work Queue, or approval setup metadata when the route needs a human approval experience.

Review the route map before publishing. Make sure the manager recipient can be resolved from the record or fallback.

#### How To Build: Broadcast A Service Announcement

Goal:

```
Show a service announcement on every live app screen.
```

Use this for maintenance notices, policy changes, reminders, or urgent app-wide messages.

Recommended recipe:

```
Broadcast announcement
```

Plain-language setup:

| Field                | Example                        |
| -------------------- | ------------------------------ |
| When this happens    | `Admin publishes announcement` |
| Destination          | `Every app screen`             |
| Action               | `Show maintenance notice`      |
| Audience or fallback | `Everyone using this app`      |

Announcement details:

| Field     | Example                                                     |
| --------- | ----------------------------------------------------------- |
| Title     | `Scheduled maintenance`                                     |
| Message   | `The app will be unavailable tonight from 9-10 PM Eastern.` |
| Severity  | `info`, `warning`, or `critical`                            |
| CTA label | `Learn more`                                                |
| CTA URL   | Optional help page                                          |

Generated objects may use Messaging announcements. Open **Messaging > Announcements** if you need to edit schedule, severity, CTA, or active state.

#### How To Build: External API Creates A Record

Goal:

```
When an external system sends an event, validate the payload and create a record.
```

Use this when another service needs to send data into NotionApps.

Recommended recipe:

```
External API/webhook -> create record
```

Plain-language setup:

| Field                | Example                              |
| -------------------- | ------------------------------------ |
| When this happens    | `External API publishes a message`   |
| Destination          | `Record creation workflow`           |
| Action               | `Validate payload and create record` |
| Audience or fallback | `Operations owner`                   |

Payload mapping should include realistic external fields:

```
customer_name
customer_email
order_id
status
source_system
```

Generated objects may include:

* Messaging channel.
* Messaging contract.
* Webhook/API publisher.
* Workflow subscriber.
* Workflow create-record step.

Review both **Messaging Activity** and **Workflow Activity** during testing.

#### Route Map

Use **Route map** before publishing.

It answers:

* What starts the automation?
* What data is expected?
* What route will receive it?
* What Workflow steps will run?
* What Messaging channel/topic is involved?
* What object IDs are generated or reused?
* What is blocked by entitlement or validation?
* What warnings should be fixed before live use?
* What guided test step should happen next?

For support, copy the support bundle from Route map when available. It contains the recipe intent, generated IDs, payload preview, readiness checklist, and route details.

The Route map now pairs the technical preview with the Guided testing panel. A maker should be able to answer:

```
What did I configure?
What will NotionApps generate?
What must I fix?
How do I prove the route works?
```

#### Debugging

Use **Debugging** when something did not run.

Filter by:

* All activity.
* Messages only.
* Workflows only.
* Status.
* Search text.

Common explanations:

| Symptom                   | Likely cause                                            | What to check                                        |
| ------------------------- | ------------------------------------------------------- | ---------------------------------------------------- |
| No workflow run appears   | Trigger or target is too narrow or wrong.               | Workflow Build trigger, Where it happens, Target.    |
| Email does not arrive     | Notify step is incomplete or local dev simulates email. | Channel, recipients, body, Activity delivery status. |
| Message has no subscriber | No destination is listening.                            | Messaging Publishers/Subscribers and channel/topic.  |
| Route is blocked          | Entitlement does not allow the recipe.                  | Automation Access.                                   |
| Payload field is missing  | Mapping expects a field not sent by the trigger.        | Contract auto-builder and Workflow Data.             |

#### Access And Entitlements

Open **Access** when a recipe is unavailable or a generated object cannot be published.

Common levels:

| Level                  | Meaning                                                     |
| ---------------------- | ----------------------------------------------------------- |
| `builder_draft_only`   | Builders can configure drafts but live delivery is limited. |
| `intra_app_enabled`    | Same-app workflows, messages, and announcements.            |
| `inter_app_enabled`    | Linked app handoffs.                                        |
| `external_api_enabled` | External API and webhook routes.                            |
| `admin_enabled`        | Admin operations and elevated support.                      |

Use the lowest entitlement that supports the route.

Approval routes have one more check. If the recipe creates or uses a Decision screen, Work Queue, or workflow approval setup, the app also needs Approval Management entitlement. Admins can grant this at the plan, account, or application level and can control these approval flags separately:

* Decision screens.
* Work queues.
* Workflow approval setup.
* Approval admin operations.

If Workflow and Messaging are enabled but approval recipes still fail, open **Access** and check Approval Management before changing workflow JSON or messaging channels.

#### Best Practices

* Start with a recipe whenever the business outcome is common.
* Use specific targets when the automation should run for one form, screen, or button.
* Leave target as Entire app only when broad behavior is intentional.
* Use friendly names in picker fields; raw IDs are for support and power users.
* Include realistic payload examples before testing.
* Use Route map before publishing.
* Use Activity after testing.
* Keep one automation per business outcome.
* Rename generated workflows so app owners can recognize them later.
* Prefer Workflow Notify for native email delivery.
* Prefer Messaging Announcements for in-app service messages.
* Prefer Messaging when an event needs routing, subscribers, linked apps, or webhooks.
* Use native automation screens when workflow or messaging state should be visible inside the app.
* Use Approval Management when the app needs approval queues, claim/release behavior, approve/reject/hold decisions, or workflow approval setup.
* Choose native screen sources and action destinations from context-aware pickers instead of typing raw IDs.
* Expect hidden screens in suggestions when those screens can be opened by routes.

#### Builder Checklist

Before publishing:

* Preflight checks show no blockers.
* Plain-language setup steps are complete.
* Guided testing has at least run preview.
* The recipe title describes the business outcome.
* Trigger is specific enough.
* Destination is correct.
* Recipient or fallback is configured.
* Payload fields match the actual form/screen/control data.
* Route map has no critical blockers.
* Generated Workflow is saved.
* Generated Workflow is published.
* Generated Messaging objects are active when used.
* Native automation screens have the correct listen scope when used.
* Native screen action destinations point to the intended screen or workflow.
* Native screen simulation uses a realistic item, message, or run when configured.
* A live test has been run.
* Activity shows the expected result.