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

# 🔀 NotionApps Workflow How-To Guide

## NotionApps Workflow How-To Guide

### NotionApps Workflow How-To Guide

![Workflow lifecycle concept](https://firebasestorage.googleapis.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F4urhODnnDM3dMRty9kOg%2Fautomation-screen-workflow-status-builder-20260705.png?alt=media\&token=eaad7a58-d7af-4184-9a12-6e8044d4c354)

> Support visual: this image shows a workflow moving from trigger, to ordered steps, to wait/escalation branches, to run history. Use it to explain that Workflow is the engine that performs work and records what happened.

> Current state: Workflow is now documented as one engine inside **Automation (Beta Testing)**. Use Workflow when the application needs a process, route, decision, wait, retry, or operational queue. Use the NotionApps Automation Current State Guide for the latest packaging, entitlement, and provisioning language.

Workflow Foundation is the automation engine for one NotionApps application. It starts when an app event happens, runs one or more steps, records every run, and lets the builder inspect what happened.

Use this guide when you need to build or refine a workflow directly instead of starting from an Automation recipe.

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

Use this guide when you need exact workflow behavior: trigger selection, target selection, steps, publishing, simulation, activity review, and lifecycle controls. If a builder only knows the business outcome, start in Automation first and let the recipe generate the workflow. If an event needs to fan out to multiple subscribers, linked apps, announcements, or webhooks, pair Workflow with Messaging.

#### When To Use Workflow

Use Workflow when the app needs to do work after an event.

Good Workflow use cases:

* Send an email after a form is submitted.
* Show a confirmation message after a button click.
* Update a Notion record when a user completes an action.
* Create a follow-up task from submitted data.
* Wait for a period of time, then escalate.
* Branch based on a status, priority, or form value.
* Publish a Messaging event after a workflow step succeeds.
* Wait for a Messaging reply before continuing.

Use Messaging instead when the main problem is routing an event to many possible destinations, linked apps, webhooks, or announcement delivery.

Use Automation first when the goal matches a common recipe and you want guided setup.

#### Where To Find Workflow

Open the app builder and select **Automation > Workflows** or open **Workflows**directly when it appears as an advanced builder surface.

Approval routes may require one extra entitlement. Workflow Foundation is the process engine, but Decision screens, Work Queue screens, and workflow approval setup are controlled by Approval Management. If an approval screen is missing or an approval recipe cannot be generated, check Automation Access or ask an admin to enable Approval Management for the app.

Workflow contains these sections:

| Section  | Use it for                                                                                                                                    |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Overview | The progressive workflow home. New work starts with Outcome Builder; existing work shows setup, testing, validation, activity, or management. |
| Build    | Name, trigger, target, steps, guided configuration, save, publish.                                                                            |
| Data     | Payload paths, context paths, screens, controls, fields, and references.                                                                      |
| Simulate | Test a draft or active workflow with sample payload data.                                                                                     |
| Activity | Review workflow runs, step runs, errors, retries, and waiting runs.                                                                           |
| Settings | Lifecycle controls, status, ownership, pause, resume, disable, delete.                                                                        |
| Help     | Definitions and builder guidance.                                                                                                             |

#### Start In Automation When The Maker Knows The Outcome

Use **Automation** before opening Workflow when the maker can describe the business outcome but does not yet know the trigger, target, steps, payload paths, or messaging route.

Automation gives the maker:

* **Outcome Builder** where the maker types what they want in normal language and NotionApps creates the underlying workflow draft or approval setup.
* **Preflight checks** for Workflow entitlement, Messaging entitlement, Approval Management entitlement when approval screens/routes are involved, app context, generated objects, and testing visibility.
* **Plain-language setup** for trigger, destination, action, audience/fallback, data requirements, and payload mapping.
* **Guided testing** for preview, blocker review, object generation, real-user testing, and Activity verification.

Example:

```
Maker goal: "When the client intake form is submitted, email someone@notionapps.com."
Start in Automation.
Type the goal into Outcome Builder.
Answer the numbered questions.
Click Build this automation.
Open Workflows only if the Notify step needs advanced tuning.
```

Use Workflow directly when the builder already knows the exact trigger and steps or needs to edit advanced branching, conditions, waits, record updates, or notifications.

**What Outcome Builder Creates**

Outcome Builder creates real workflow objects, not just documentation.

For notification, follow-up record, announcement, conversation, integration, and escalation outcomes, it creates a saved workflow draft with the trigger and first set of steps already assembled. The maker can then open **Build**, inspect each step, save changes, publish, simulate, and review Activity.

For approval outcomes, Outcome Builder routes through the approval setup path. That means NotionApps provisions the approval workflow, approval pages, messaging support, and validation checks instead of asking the maker to hand-build those objects.

This keeps the workflow engine reliable while letting the maker start with a business sentence rather than a technical design.

**Workflow Overview Progressive Path**

Workflow Overview now follows the same self-serving pattern as Automation Home:

1. **Outcome Builder** is the only starting point for new workflow work.
2. **What NotionApps will build** appears after the maker has described or selected an outcome.
3. **Finish the setup workspace** appears when the draft exists but still needs trigger, data source, recipient, message, wait, or approval setup answers.
4. **Generate and test** appears when the workflow is ready to prove with simulation or real activity.
5. **No required action right now** appears when the workflow has generated objects or recent activity and the maker mainly needs monitoring tools.

The secondary tools area appears only after there is work to manage. Use it for **Continue work**, **Guided path**, and **Manage / monitor** actions. It should not compete with Outcome Builder on a brand-new workflow.

Repair-first information can move ahead of the normal path. If access, validation, provisioning, approval setup, or generated object health is blocked, Workflow Overview should show the fix path first and route the maker to the right screen.

#### Core Concepts

**Workflow**

A workflow is one automation definition for one app.

Example:

```
When the Client Intake screen is submitted, email the operations reviewer.
```

**Draft And Published Version**

Builders edit drafts. A published version is what live app events run.

Typical flow:

```
Edit draft -> Save draft -> Publish -> live app events run the published version
```

**Trigger**

The trigger is what starts the workflow.

Common triggers:

| Trigger                  | Use it when                                                    |
| ------------------------ | -------------------------------------------------------------- |
| Form or screen submitted | A user saves, submits, updates, or deletes data from a screen. |
| Button clicked           | A user clicks a specific button or screen action.              |
| Record created           | A connected Notion record is created.                          |
| Record updated           | A connected Notion record changes.                             |
| Scheduled                | Work should happen later or on a schedule.                     |
| Webhook received         | An external service starts the workflow.                       |
| Message received         | Messaging routes a message to the workflow.                    |

When the trigger is **Webhook received**, the builder shows the central intake endpoint, the app alias endpoint, the required token header, sample JSON, and a cURL example. Admins can monitor each inbound attempt in **Admin > Workflow Operations > Webhook intake**.

**Where It Happens**

This scopes the trigger.

| Scope       | Meaning                                          |
| ----------- | ------------------------------------------------ |
| Entire app  | Listen broadly across this app.                  |
| Screen      | Listen only on one screen.                       |
| Form        | Listen to a form-specific target when available. |
| Button      | Listen to one button/control.                    |
| Data source | Listen to one sheet/database.                    |
| Record      | Listen to one specific record.                   |

Most form submission workflows should choose **Screen** and then select the screen that owns the form.

**Target**

The target is the exact screen, form, button, data source, or record selected by the picker. The picker is context-aware. Start typing the friendly name. It will show available objects and save the correct ID behind the scenes.

Hidden/internal screens can appear because workflows can route users there in normal app behavior.

**Step**

A step is one action in the workflow.

Common step types:

| Step                   | Use it for                                       |
| ---------------------- | ------------------------------------------------ |
| Notify                 | Send an email or webhook notification.           |
| Create record          | Create a Notion record from event data.          |
| Update record          | Update a record using payload or context values. |
| Show message           | Show a toast/confirmation to the current user.   |
| Open screen            | Move the current user to another screen.         |
| Set control visibility | Show or hide a control.                          |
| Set control text       | Change text on a control.                        |
| Refresh screen data    | Reload screen data after a change.               |
| Wait                   | Pause for a period of time.                      |
| Condition/Branch       | Evaluate rules and route behavior.               |
| Publish message        | Send a structured Messaging event.               |
| Send message request   | Ask for a reply and wait.                        |
| Send message reply     | Reply to a request message.                      |
| Wait for message       | Pause until a related message arrives.           |

#### How Data Moves Through Workflow

Workflow data usually comes from:

* `payload`: data from the event that started the workflow.
* `context`: runtime information and output from earlier steps.
* `context.<step_id>`: output produced by a named step.

Common payload paths:

```
payload.record_id
payload.email
payload.user_email
payload.status
payload.priority
payload.name
payload.action_type
```

When a field asks for a path, start typing `payload` or `context`. The builder shows context-aware suggestions.

#### Native Automation Screens In Workflow Apps

Workflow can power native automation screens. These screens give users and owners a place to see work, decisions, runs, conversations, exceptions, notifications, launch actions, linked app exchanges, and operations.

Common workflow pairings:

| Workflow pattern                               | Native screen        |
| ---------------------------------------------- | -------------------- |
| A workflow creates a review task               | Work Queue           |
| A workflow waits for approval                  | Decision             |
| A workflow needs run visibility                | Workflow Status      |
| A workflow publishes or receives messages      | Conversation         |
| A workflow can fail and need manual repair     | Exception Resolution |
| A workflow creates announcements or notices    | Notification Center  |
| A workflow should be started manually by users | Automation Launcher  |
| A workflow participates in app-to-app handoff  | Linked App Exchange  |

For detailed setup and troubleshooting for each screen type, see the Native Automation And Operational Screen Guides.

Current setup rule:

```
Workflow creates or updates the work.
Messaging carries request/reply events when needed.
Native screens show the work in plain language.
```

For Conversation screens, the workflow should create or reuse one conversation/correlation value for the business object. For example, a timecard review workflow should use the timecard record id so the employee and supervisor see the same private discussion. Broadcasts should be published as announcements and viewed in Notification Center, not mixed into the private conversation.

Decision and Work Queue screens are Approval Management surfaces. They should only appear in Add Screen and in the live app when the app has Approval Management enabled with the matching granular flags.

When configuring a native screen:

1. Add the screen in the application builder.
2. Use the distinct screen icon and title to choose the right screen type.
3. Open **Source binding**.
4. Search for the source screen, form, workflow, channel, topic, conversation, or linked app by name.
5. Configure action routing with the **After-action screen** and **Target workflow** pickers when needed.
6. Use **Sample workflow run** to preview the screen with real run context.

Hidden screens may appear in the picker. That is expected when a workflow can open the screen even though it is not visible in navigation.

#### How To Build: Email After Form Submission

Goal:

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

**Step 1: Create Or Open A Workflow**

Open **Workflows** and click **New**, or open the workflow generated by Automation.

Name it:

```
Form submission email notification
```

**Step 2: Set The Trigger**

In **Build**, set:

| Field            | Value                                    |
| ---------------- | ---------------------------------------- |
| Trigger          | `Form or screen submitted`               |
| Where it happens | `Screen`                                 |
| Target           | Select the screen that contains the form |

If the workflow should run for all forms/screens, use **Entire app**. For most production workflows, choose a specific screen to avoid accidental extra runs.

**Step 3: Select The Notify Step**

Click the Notify step in the workflow canvas or step list.

If the workflow does not have a Notify step, add a step and choose **Notify**.

**Step 4: Configure Email Delivery**

Set:

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

Power-user config:

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

**Step 5: Add A Confirmation Message**

Add or select a **Show message** step.

Set:

```
Thanks. Your submission was received.
```

This improves the end-user experience. The email happens in the background, but the user sees immediate confirmation.

**Step 6: Save And Publish**

Click **Save draft**.

Fix any validation issues.

Click **Publish**.

**Step 7: Test**

Submit the form from the live app.

Open **Activity** and verify:

* A workflow run appears.
* The Notify step completed.
* The run completed.
* Email delivery is sent or simulated.

Local development note: email may be simulated locally. A simulated result means the workflow path worked, but no real email left the system.

#### How To Build: Button Updates The Current Record

Goal:

```
When a user clicks "Mark reviewed", update the current record and refresh the screen.
```

**Step 1: Create Workflow**

Name:

```
Mark record reviewed
```

**Step 2: Set Trigger**

| Field            | Value                         |
| ---------------- | ----------------------------- |
| Trigger          | `Button clicked`              |
| Where it happens | `Button`                      |
| Target           | Select `Mark reviewed` button |

**Step 3: Add Show Message Step**

Message:

```
Marking this record as reviewed.
```

**Step 4: Add Update Record Step**

Configure:

| Field       | Value                                           |
| ----------- | ----------------------------------------------- |
| Record id   | `payload.record_id`                             |
| Reviewed    | `true`                                          |
| Reviewed by | `payload.user_email`                            |
| Reviewed at | current timestamp or workflow context timestamp |

**Step 5: Add Refresh Screen Data Step**

This reloads the visible data after the record update.

**Step 6: Save, Publish, Test**

Click the button in the live app and confirm:

* The record changes.
* The screen refreshes.
* Activity shows a completed run.

#### How To Build: Create A Follow-Up Task From A Form

Goal:

```
When a vendor submits registration, create an internal follow-up task.
```

**Trigger**

| Field            | Value                      |
| ---------------- | -------------------------- |
| Trigger          | `Form or screen submitted` |
| Where it happens | `Screen`                   |
| Target           | `Vendor Registration`      |

**Create Record Step**

Map submitted data to the task database:

| Task field    | Source                  |
| ------------- | ----------------------- |
| Title         | `payload.vendor_name`   |
| Contact email | `payload.contact_email` |
| Status        | Static value: `New`     |
| Source record | `payload.record_id`     |
| Submitted by  | `payload.user_email`    |

**Notify Step**

| Field     | Value                                                                   |
| --------- | ----------------------------------------------------------------------- |
| Channel   | `Email`                                                                 |
| Recipient | `ops@example.com`                                                       |
| Subject   | `New vendor registration`                                               |
| Body      | `A vendor registration was submitted and a follow-up task was created.` |

Email is the default Notify channel. If an older or template-provisioned workflow is missing a stored `channel`, NotionApps treats the step as Email and writes `"channel": "email"` the next time the workflow is saved or published.

**Test**

Submit the vendor form. Confirm the task record appears and the notification step succeeds.

#### How To Build: Wait Then Escalate

Goal:

```
If no one handles a request within 24 hours, email the app owner.
```

**Trigger**

Use the event that starts the request:

```
Form or screen submitted
```

**Step 1: Notify Primary Owner**

Send email to the normal owner or manager.

**Step 2: Wait**

Set:

```
Wait hours: 24
```

**Step 3: Condition**

Check whether the request is still pending.

Example rule:

```
payload.status equals pending
```

If the status is still pending, continue to escalation.

**Step 4: Notify Escalation Recipient**

Send email to:

```
app-owner@example.com
```

Subject:

```
Request still pending after 24 hours
```

Body:

```
This request has not been handled. Please review it in NotionApps.
```

#### How To Build: Start Workflow From Messaging

Goal:

```
When Messaging receives task.assigned, start a workflow that emails the assignee.
```

**Workflow Trigger**

| Field            | Value              |
| ---------------- | ------------------ |
| Trigger          | `Message received` |
| Message channel  | `tasks`            |
| Message topic    | `task.assigned`    |
| Contract name    | `task_assignment`  |
| Contract version | `1.0.0`            |

**Notify Step**

Recipient:

```
payload.assignee_email
```

Subject:

```
New task assigned
```

Body:

```
A task was assigned to you in NotionApps.
```

**Messaging Subscriber**

In Messaging, create a subscriber:

| Field           | Value           |
| --------------- | --------------- |
| Subscriber type | `Workflow`      |
| Destination     | This workflow   |
| Channel         | `tasks`         |
| Topic           | `task.assigned` |

#### Simulation

Use **Simulate** before publishing when payload values matter.

Sample payload:

```json
{
  "record_id": "sample_record_123",
  "name": "Jordan Lee",
  "email": "jordan@example.com",
  "status": "pending",
  "priority": "high",
  "user_email": "builder@example.com"
}
```

Simulation helps you verify:

* Conditions evaluate as expected.
* Paths like `payload.email` exist.
* Record mappings use the right data.
* Notification fields are not empty.

Simulation may not send real email or call every external side effect in local development. Use Activity and live tests for final confirmation.

If the workflow was generated from Automation, run the Automation Guided testing preview before or alongside Workflow simulation. Automation preview checks cross-tool blockers such as entitlement, Messaging contracts, route generation, and destination availability. Workflow simulation checks the selected workflow path and step configuration.

#### Activity

Use **Activity** after a live test.

Look for:

* Run status.
* Trigger payload.
* Step statuses.
* Error messages.
* Retry/cancel options.
* Waiting run details.

Common statuses:

| Status      | Meaning                                      |
| ----------- | -------------------------------------------- |
| `queued`    | Waiting to run.                              |
| `running`   | Currently executing.                         |
| `waiting`   | Paused for a wait, reply, or external event. |
| `completed` | Finished successfully.                       |
| `failed`    | A step failed.                               |
| `cancelled` | Builder or admin cancelled the run.          |

#### Troubleshooting

**Workflow Does Not Run**

Check:

* Workflow is published.
* Trigger type is correct.
* Where it happens is not too narrow.
* Target is the correct screen/button/data source.
* Entitlement is enabled.
* The live app event actually occurred.
* For external events, Admin Workflow Operations shows the request in `Webhook intake`.

**Notify Step Fails**

Check:

* Channel is `Email` or `Webhook`.
* Recipients/endpoints are present.
* Body is not empty.
* Email provider is configured in the environment.
* Local development may simulate email.

**Target Picker Shows Unexpected Objects**

The picker includes hidden/internal screens because workflows can route users to those screens. Deleted screens should not appear. If a deleted screen appears, refresh app data and report it as a bug.

**Payload Path Is Missing**

Use **Data** to inspect available payload and context paths.

If the submitted form sends `payload.customer_email`, do not map `payload.email` unless the payload actually contains that field.

**Workflow Publishes But Does Nothing**

Check:

* Trigger is scoped correctly.
* Steps are connected in the expected order.
* Conditions are not preventing later work.
* A Wait step is not intentionally pausing the run.
* Activity shows step-level output.

#### Best Practices

* Use Automation recipes for common patterns.
* Use Workflow directly for advanced step editing.
* Scope triggers narrowly when possible.
* Name workflows by business outcome.
* Keep Notify body meaningful.
* Add a confirmation message for user-facing form/button workflows.
* Use Data suggestions instead of typing raw IDs.
* Use Simulate before publishing.
* Use Activity after live testing.
* Pause instead of deleting when you may need the workflow again.

#### Workflow Builder Checklist

Before publishing:

* Automation Preflight has no Workflow blockers when the workflow was created from a recipe.
* Automation Preflight has no Approval Management blockers when the workflow uses Decision screens, Work Queues, approval recipes, or workflow approval setup.
* Automation Guided testing preview has run when a maker used a recipe.
* Workflow has a clear name.
* Trigger is correct.
* Where it happens is intentional.
* Target is selected when needed.
* Every step has required fields.
* Notify steps have recipients and body.
* Record steps have required field mappings.
* Conditions reference real payload/context paths.
* Simulation has been run when data paths matter.
* Validation has no critical errors.
* Draft has been saved.
* Workflow has been published.
* Live Activity confirms behavior.