Skip to main content

Suspend & Approval / Prompts

Flows can be suspended until resumed or canceled event(s) are received. This feature is most useful for implementing approval steps.

Approval step diagram

An approval step is a normal script with Suspend until approval/resume enabled in the step's Run settings tab. This will suspend the execution of a flow until it has been approved through the resume endpoints or the approval page by and solely by the recipients of the secret URLs.

Suspending a flow in Windmill

Other ways to pause a workflow include:

  • Early stop/Break: if defined, at the end of the step, the predicate expression will be evaluated to decide if the flow should stop early.
  • Sleep: if defined, at the end of the step, the flow will sleep for a number of seconds before scheduling the next job (if any, no effect if the step is the last one).
  • Retry a step until it is successful.
  • Schedule the trigger of a script or flow.
  • Require approval on a tool of an AI agent, or give it the Ask a question tool.

An event can be:

  • a cancel
  • a pre-set number of approval that is met.

The approval step generates a unique URL for each required approval using wmill.getResumeUrls() (or wmill.get_resume_urls() in Python). The approval step works like a webhook mechanism - the flow remains suspended until the required number of approval events are received via HTTP requests to these generated URLs. Each approval event is an HTTP request to one of these URLs, which then resumes or cancels the flow execution.


Add approval script​

You can think of a scenario where only specific people can resume or cancel a Flow. To achieve this they would need to receive a personalized URL via some external communication channel (like e-mail, SMS or chat message).

When adding a step to a flow, pick Approval, and write a new approval script or pick one from WindmillHub. This will create a step where the option in tab "Advanced" - "Suspend" is enabled.

Adding approval step

Use wmill.getResumeUrls() in TypeScript or wmill.get_resume_urls() in Python from the wmill client to generate secret URLs.

Flow-level resume URLs (pre-approvals)​

By default, resume URLs are tied to a specific step. With flowLevel: true (TypeScript) or flow_level=True (Python), you can generate resume URLs for the parent flow instead. These "pre-approvals" can be consumed by any later suspend step in the same flow.

This is useful when you want to request approval early in the flow (e.g. in the first step) and have it automatically satisfy a suspend step that comes later:

// TypeScript
const urls = await wmill.getResumeUrls("approver1", true) // flowLevel = true
# Python
urls = wmill.get_resume_urls(approver="approver1", flow_level=True)

When a flow-level resume is received, the approval is stored at the flow level and matched when the worker checks for resumes at any subsequent suspend step.

Core​

Number of approvals/events required for resuming flow​

The number of required approvals can be customized. This allows flexibility and security for cases where you either require approvals from all authorized people or only from one.

Important: The flow will remain suspended and will not proceed to the next step until the exact number of required approval events is received. If fewer approvals than required are received, the flow stays suspended indefinitely (unless a timeout is configured).

Required approvals

Note that approval steps can be applied the same configurations as regular steps (Retries, Early stop/Break or Sleep).

Timeout​

Set a custom timeout after which the flow fails if no approval is received.

This timeout only applies to the approval step. A flow timeout also counts the time spent waiting here, and abandons the approval when reached, even with continue on disapproval/timeout set.

Approval Timeout

Approval page skin​

The approval page skin sets how a request is presented to approvers, on the approval page and in Slack and Microsoft Teams approval messages.

  • Detailed (default): the request along with the flow's details, meaning the approvers so far, the run's metadata, the flow arguments and the flow graph.
  • Minimal: only the request, meaning who requested it and when, the step's description, the form and the Approve / Reject buttons. It suits approvers who are not the flow's developers and only need to make a decision.

To pick a skin, open the approval step, go to the Run settings tab and, under Suspend until approval/resume, in the Core tab, set Approval page skin to Detailed or Minimal. Each approval step has its own skin, so two approval steps of the same flow can present their requests differently.

Approval page skin setting

In the flow's OpenFlow definition (YAML for the CLI and git sync, JSON for the API), the skin is the step's suspend.skin:

- id: approve_expense
summary: Approve the team offsite expense
value: ...
suspend:
required_events: 1
timeout: 1800
skin: minimal # or detailed, the same as leaving it out

Picking Detailed in the editor removes the key rather than writing detailed. A value your Windmill version doesn't know is read as detailed, so a flow written for a newer version still loads and runs.

In workflows as code, pass skin to the approval call, along with the description approvers see:

const approval = await waitForApproval({
skin: 'minimal',
description: `Expense of $${amount} for the team offsite`
});

What the minimal page shows​

Minimal approval page

  • Title: the approval step's summary, the field at the top of the step panel. Without one, the page uses the flow's summary, and otherwise "Approval request". In workflows as code, the title is the script's summary.
  • Under the title: the flow's summary when the title comes from the step, or the flow's path when the flow has no summary. Then who started the run, and when.
  • Description: the description the approval step returns (see Description), or the description option in workflows as code. A string is shown as plain text, and an object is rendered with rich display rendering, for example { "markdown": "..." }.
  • The step's form, then the Approve and Reject buttons. Hiding the cancel button removes Reject.
  • After a decision, the page reads Approved or Rejected. Someone opening the link once the run is no longer waiting on the request sees that it is closed.

When a step needs several approvals, the page lists who has already approved, and workspace members get a link to the run details. If the step requires approvers to be logged in, none of the above is shown until the viewer signs in as a user allowed to approve.

The page uses the skin of the approval step the run is waiting on. Once the run has moved past that step, finished or been rejected, the page keeps the skin of the last approval step the run went through, so a link opened late still shows the request as it was set up.

Slack and Teams messages​

Messages sent with the Slack and Teams approval helpers use the skin of the approval step that sends them. With Detailed, the messages list who created the run and when, the script path, the arguments and the flow ID, followed by your message. With Minimal:

  • Slack: the channel post reads "Approval requested" followed by your message, with a Review button. The modal it opens is titled "Approval request", shows the message and who requested it, and offers Approve and Reject. After a decision, the post reads "Approved" or "Rejected".
  • Teams: the card is titled "Approval request", with the message, who requested it, a "View in Windmill" link and Approve / Reject actions.

The resumeButtonText and cancelButtonText options of the TypeScript Slack helper still override the labels of the modal's buttons.

Deny with a reason​

An approver who denies from the approval page, or from a flow's approval panel on the run page, can give an optional reason. When calling the cancel URL directly, send it as reason in the JSON body, for example {"reason": "Budget exceeded"}. The reason is included in the step's error and, on Enterprise Edition, recorded in the audit log.

Continue on disapproval/timeout​

If set, instead of failing the flow and bubbling up the error, continue to the next step which would allow to put a branchone right after to handle both cases separately. If any disapproval/timeout event is received, the resume payload will be similar to every error result in Windmill, an object containing an error field which you can use to distinguish between approvals and disapproval/timeouts. Its name is SuspendedDisapproved or SuspendedTimedOut. With this option enabled, the next step reads a deny reason as resume.error.reason.

Continue on disapproval/timeout

Form​

You can add an arbitrary schema form to be provided and displayed on the approval page. Users opening the approval page would then be offered to fill arguments you can use in the flow.

Adding a form to an approval step is a Cloud & Enterprise Self-Hosted only feature.


In the Advanced menu of a step, go to the "Suspend/Approval" tab and enable the Add a form to the approval page button.

Add properties and define their Name, Description, Type, Default Value and Advanced settings.

Add argument

That will the be displayed on the approval page.

Fill argument

Use arguments​

The approval form argument values can be accessed in the subsequent step by connecting input fields to either resume["argument_name"] for a specific argument, or simply resume to obtain the complete payload.

Use argument

This is a way to introduce human-in-the-loop workflows and condition branches on approval steps inputs.

Prompts​

A prompt is simply an approval step that can be self-approved. To do this, include the resume url in the returned payload of the step. The UX will automatically adapt and show the prompt to the operator when running the flow. e.g:

import * as wmill from "windmill-client"

export async function main() {
const resumeUrls = await wmill.getResumeUrls("approver1")

return {
resume: resumeUrls['resume'],
default_args: {}, // optional
enums: {} // optional
}
}

Find this script on Windmill Hub.

In the video below, you can see a user creating an approval step within a flow including the resume url in the returned payload of the step. Then another user (who can only run the flow, being only "Viewer" in the folder of the flow), runs the flow and sees the prompt automatically shown when running the flow.


Default args​

As one of the return key of this step, return an object default_args that contains the default arguments of the form argument. e.g:

//this assumes the Form tab has a string field named "foo" and a checkbox named "bar"

import * as wmill from 'npm:windmill-client@^1.158.2';

export async function main() {
// if no argument is passed, if user is logged in, it will use the user's username
const resumeUrls = await wmill.getResumeUrls('approver1');

// send the resumeUrls to the recipient or see Prompt section above

return {
default_args: {
foo: 'foo',
bar: true
}
};
}

Find this script on Windmill Hub.

Dynamics enums​

As one of the return key of this step, return an object enums that contains the default options of the form argument. e.g:

//this assumes the Form tab has a string field named "foo"

import * as wmill from 'npm:windmill-client@^1.158.2';

export async function main() {
// if no argument is passed, if user is logged in, it will use the user's username
const resumeUrls = await wmill.getResumeUrls('approver1');

// send the resumeUrls to the recipient or see Prompt section above

return {
enums: {
foo: ['choice1', 'choice2']
}
};
}

Find this script on Windmill Hub.

That's a powerful way of having dynamic enums as flow inputs. As shown in the video below, you can have a dynamic list of choices as a first step of a flow. Just run the flow and see the list of choices.


And below is the flow YAML used for this example:

summary: ""
value:
modules:
- id: a
value:
type: rawscript
content: >-
import * as wmillClient from "windmill-client"


export async function main() {
// Constant array, but could come from dynamic source
const customers: string[] = [
"New York",
"Los Angeles",
"Chicago",
"Houston",
"Phoenix",
"Philadelphia",
"San Antonio",
"San Diego",
"Dallas",
"San Jose"
];

const resumeUrls = await wmillClient.getResumeUrls("approver1");

// Remove duplicates and sort the customers array in alphabetical order
const sortedCustomers = Array.from(new Set(customers)).sort();

return {
resume: resumeUrls['resume'],
enums: {
"Customers to send to": sortedCustomers
},
default_args: {
"Customers to send to": sortedCustomers
}
}
}
language: bun
input_transforms: {}
is_trigger: false
continue_on_error: false
suspend:
required_events: 1
timeout: 1800
hide_cancel: false
resume_form:
schema:
properties:
Customers to send to:
items:
type: string
type: array
description: ""
required: []
order:
- Customers to send to
summary: Approval step with dynamic enum
- id: b
summary: Use the selected arguments
value:
type: rawscript
content: |-
# import wmill


def main(x):
return x
language: python3
input_transforms:
x:
type: javascript
expr: resume["Customers to send to"]
is_trigger: false
same_worker: false
schema:
$schema: https://json-schema.org/draft/2020-12/schema
properties: {}
required: []
type: object

Description​

You can add a description to give clear instructions that support the whole range of rich display rendering (including markdown).

import * as wmill from "windmill-client@^1.158.2"

export async function main(approver?: string) {
const urls = await wmill.getResumeUrls(approver)
// send the urls to their intended recipients


// if the resumeUrls are part of the response, they will be available to any persons having access
// to the run page and allowed to be approved from there, even from non owners of the flow
// self-approval is disablable in the suspend options
return {
...urls,
default_args: {},
enums: {},
description: {
render_all: [
{
markdown: "# We have located the secret vault with thousands of H100"
},
{
map: { lat: -30, lon: 10, markers: [{lat: -30, lon: 0, title: "It's here"}]}
},
"Just kidding"
]
}
// supports all formats from rich display rendering such as simple strings,
// but also markdown, html, images, tables, maps, render_all, etc...
// https://www.windmill.dev/docs/core_concepts/rich_display_rendering
}
}

Description

Hide cancel button on approval page​

By enabling this option, the cancel button will not be displayed on the approval page to force more complex patterns using forms with enums processed in ulterior steps.

Hide cancel approval settings

Hide cancel approval page

Alternatively, adding the cancel url as a result of the step will also render a cancel button, providing the operator with an option to cancel the step. e.g:

import * as wmill from "windmill-client"

export async function main() {
const urls = await wmill.getResumeUrls("approver1")

return {
resume: urls['resume'],
cancel: urls['cancel'],
}
}

Permissions​

Customizing permissions of approval steps is a Cloud & Enterprise Self-Hosted only feature.

Secret resume URLs skip these checks

The options in this section are checked when an approver answers on the Windmill approval page as a signed-in user. They are not checked when the step is resumed or canceled through its secret resume URL: holding the URL is the authorization. This includes the buttons of interactive Slack messages and Microsoft Teams cards, which resume the flow through that URL, so anyone who can see the message in the channel can approve or reject the step, whatever the options below say. Post Slack and Teams approval requests only to a channel whose members are allowed to approve.

Require approvers to be logged in​

By enabling this option, only users logged in to Windmill can approve the step.

Approval Logged In

Disable self-approval​

The user who triggered the flow will not be allowed to approve it. This restriction is enforced both on the approval page and on the flow resume API endpoint for signed-in users, preventing flow owners from bypassing approval requirements programmatically. It does not apply to secret resume URLs.

Disable self-approval

Require approvers to be members of a group​

By enabling this option, only logged in users who are members of the specified group can approve the step.

Require approvers to be members of a group

You can also dynamically set the group by connecting it to another node's output.

Approval group dynamic

Get the users who approved the flow​

The input approvers is an array of strings, one per resume event. Each entry is the approver passed to getResumeUrls(approver) when the flow was resumed through the resume or cancel URL it returned. Resumed another way, including through the approvalPage link, it is the resuming user's username. With no user, it is "anonymous". For an answer given with the buttons of an interactive Teams card, it is the approver passed to requestInteractiveTeamsApproval, or "anonymous" when none was passed, not the Teams user who clicked. The resumes input holds every resume payload in arrival order, and resume the last one.

To get the list of users, just have the step after the approval step return the approvers key. For example by taking an input connected to the approvers key.

The step could be as simple as:

export async function main(list_of_approvers) {
return list_of_approvers
}

With input list_of_approvers taking as JavaScript expression approvers.

Slack approval step​

The Windmill Python and TypeScript clients both have a helper function to request an interactive approval on Slack. An interactive approval is a Slack message that can be approved or rejected directly from Slack without having to go back to the Windmill UI.


The following hub scripts can be used:

If you define a form on the approval step, the form will be displayed in the Slack message as a modal.

Approval form slack

The wording of the message follows the approval step's skin. Slack limits how much text the message's button can carry, so a long message is shortened to fit.

Both of these scripts are using the Windmill client helper function:

wmill.request_interactive_slack_approval(
slack_resource_path="/u/username/my_slack_resource",
channel_id="admins-slack-channel",
message="Please approve this request",
approver="approver123",
default_args_json={"key1": "value1", "key2": 42},
dynamic_enums_json={"foo": ["choice1", "choice2"], "bar": ["optionA", "optionB"]},
)

Where dynamic_enums can be used to dynamically set the options of enum form arguments and default_args can be used to dynamically set the default values of form arguments.

If multiple approvals are required you can use the client helper directly and send approval requests to different channels:

import wmill

def main():
# Send approval request to customers
wmill.request_interactive_slack_approval(
'u/username/slack_resource',
'customers',
)

# Send approval request to admins
wmill.request_interactive_slack_approval(
'u/username/slack_resource',
'admins',
)

Microsoft Teams approval step​

The Windmill TypeScript client exposes helper functions to request a approval on Microsoft Teams. The interactive approval is a Teams message that can be approved or rejected directly from Teams without having to go back to the Windmill UI where as the non-interactive approval will be a simple link that will open the approval page in the Windmill UI in your browser.


The following hub scripts can be used:

If you define a form on the approval step, the form will be displayed in the Teams message as a modal. The card shows the form fields as:

Field typeIn the Teams card
BooleanToggle
String with enum values, or values from dynamicEnumsJsonDropdown
Other stringText field
Number or integerNumber field

Fields of other types, such as objects or arrays, are not shown in the card. Approvers can fill them in on the Windmill approval page, which the card links to. When the step has a form, hiding the cancel button also removes the card's reject button.

The card's buttons skip the step's permission options.

Approval form teams

The wording of the interactive card follows the approval step's skin.

Both of these scripts are using the Windmill client helper function:

await wmill.requestInteractiveTeamsApproval({
teamName: "Windmill",
channelName: "General",
message: "Please approve this request",
approver: "approver123",
defaultArgsJson: { key1: "value1", key2: 42 },
dynamicEnumsJson: { foo: ["choice1", "choice2"], bar: ["optionA", "optionB"] },
});

Where dynamic_enums can be used to dynamically set the options of enum form arguments and default_args can be used to dynamically set the default values of form arguments.

If multiple approvals are required you can use the client helper directly and send approval requests to different channels (same as the Slack example above).

Tutorial: a Slack approval step conditioning flow branches​

The answer to the arguments of an approval page can be used as an input to condition branches in human-in-the-loop workflows.

Here is a basic example we will detail below.


This flow:

  1. Receives a refund request form a user.
  2. Asks on Slack via an approval step what action to take.
  3. The answer is a condition to branches that lead either a refund, a refusal or a deeper investigation.
Fork and try the flow

An automated trigger version of this flow is available on Windmill Hub.

For the sake of the example, we made this flow simple with a manual trigger. Two input were used: "User email" and "Order number", both strings.

Flow inputs

Then, we picked an approval step on the Hub to Request Interactive Slack Approval. With inputs:

  • "slackResourcePath": the path to your Slack resource.
  • "channel": Slack channel to publish message, as string.
  • "text: Refund request by _${flow_input["User email"]}_ on order ${flow_input["Order number"]}..

This will allow the user to approve or reject the refund request directly from Slack without having to go back to the Windmill UI.

Slack inputs

In the Advanced settings of the step, for "Suspend/Approval". We added the following properties to the form.

Form settings

Form settings

Form settings 2

This will lead to the following approval page and slack form:

Approval page

Approval form slack

This approval page will generate two keys you can use for further steps: resume["Action"] and resume["Message"]. resume is the resume payload.

Those are the keys you can use as predicate expressions for your branches.

Branches predicate expressions

With Branch one, the first branch whose predicate expression is true will execute.


The content of each branch is of little importance for this tutorial as it depends each operations and tech stack. For the example we used two Hub scripts: Send Email with Gmail and Send Message to Channel with Slack.

Example of arguments used for Gmail and Slack scripts:

Gmail inputs


Slack inputs

Automated trigger version​

You could use the Mailchimp Mandrill integration to trigger this flow manually by an email reception.


This flow can be found and forked on Windmill Hub.

Guides​