NotionApps Workflow How-To Guide
NotionApps Workflow How-To Guide
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 Workflowsdirectly 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:
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:
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:
Outcome Builder is the only starting point for new workflow work.
What NotionApps will build appears after the maker has described or selected an outcome.
Finish the setup workspace appears when the draft exists but still needs trigger, data source, recipient, message, wait, or approval setup answers.
Generate and test appears when the workflow is ready to prove with simulation or real activity.
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:
Draft And Published Version
Builders edit drafts. A published version is what live app events run.
Typical flow:
Trigger
The trigger is what starts the workflow.
Common triggers:
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.
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:
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:
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:
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:
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:
Add the screen in the application builder.
Use the distinct screen icon and title to choose the right screen type.
Open Source binding.
Search for the source screen, form, workflow, channel, topic, conversation, or linked app by name.
Configure action routing with the After-action screen and Target workflow pickers when needed.
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:
Step 1: Create Or Open A Workflow
Open Workflows and click New, or open the workflow generated by Automation.
Name it:
Step 2: Set The Trigger
In Build, set:
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:
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:
Step 5: Add A Confirmation Message
Add or select a Show message step.
Set:
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:
Step 1: Create Workflow
Name:
Step 2: Set Trigger
Trigger
Button clicked
Where it happens
Button
Target
Select Mark reviewed button
Step 3: Add Show Message Step
Message:
Step 4: Add Update Record Step
Configure:
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:
Trigger
Trigger
Form or screen submitted
Where it happens
Screen
Target
Vendor Registration
Create Record Step
Map submitted data to the task database:
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
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:
Trigger
Use the event that starts the request:
Step 1: Notify Primary Owner
Send email to the normal owner or manager.
Step 2: Wait
Set:
Step 3: Condition
Check whether the request is still pending.
Example rule:
If the status is still pending, continue to escalation.
Step 4: Notify Escalation Recipient
Send email to:
Subject:
Body:
How To Build: Start Workflow From Messaging
Goal:
Workflow Trigger
Trigger
Message received
Message channel
tasks
Message topic
task.assigned
Contract name
task_assignment
Contract version
1.0.0
Notify Step
Recipient:
Subject:
Body:
Messaging Subscriber
In Messaging, create a subscriber:
Subscriber type
Workflow
Destination
This workflow
Channel
tasks
Topic
task.assigned
Simulation
Use Simulate before publishing when payload values matter.
Sample payload:
Simulation helps you verify:
Conditions evaluate as expected.
Paths like
payload.emailexist.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:
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
EmailorWebhook.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.