Skip to main content

Approval Steps in Flows

Flows can be suspended until resumed or cancelled event(s) are received. This feature is most useful to implement approval steps but can be used for other purposes as well.


If you look for ways to pause a workflow, you might be interested in:

  • 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). Sleeping is passive and does not consume any resources.
  • Retry a step a step until it comes successful.
  • Schedule the trigger of a script or flow.

An approval step 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 those secret urls. Use wmill.getResumeUrls() in Typescript or wmill.get_resume_urls() in Python from the wmill client to generate those URLs.

An event can be:

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

For the moment we receive the approval steps in the form of an HTTP request. For each event, a single URL is generated. It is not unique to each user to whom it is sent.

Add Approval Script

Adding approval step

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).

Important thing to remember is that the number of required approvals can be customized. This allows some flexibility for cases where you either require approvals from all authorized people or only from one.

Required approvals

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

Example with Gmail

Add Gmail Resource

Lets start with adding a Gmail Resource. On the Resources page, click "Add a resource/API", select the gmail OAuth API and click "Sign in with Google".


As Google is an OAuth provider, you will be redirected to select your Google account. To make the Approval Script work, you need to sign in and allow Windmill to send e-mails on your behalf.

Connect the Gmail API

Save the Gmail Resource

Reusing Script from Windmill Hub

Let's create a Flow as described in the getting started section. Our first step will be an Approval Script from Windmill Hub, so click the + sign in the left pane and select "Approval (Script)".

Add Approval step

Once the step is added, you'll be presented with some pre-made Scripts from the Hub. Select the one named "Suspend/resume a flow by sending approval URL via email (gmail)".

Reuse Gmail script from Hub

Make sure to fill required fields: for gmail_auth, select your newly added Gmail resource and define email addresses in the approver_emails input.

Enter Script arguments

Run the Flow

The Flow is now ready for testing, let's click "Test flow" in the top-right corner.

Running the Flow

You can notice that after the first step, the Flow is suspended and is waiting for approval. An e-mail should have been sent to the email addresses you specified. It contains a link to a webpage that looks like the following:

Waiting for approval

Let's approve and resume the Flow and see that it has successfully ran the second step as well.

Finished flow

Condition branches on approval steps inputs

In the default URL approval steps there is a text box where users can enter a string. This input can be the condition of further branches or scripts.

Approval text box

Currently, you need to create an intermediary step that should return 'resume: "The resume payload"'

Use an intermediary step

Once executed, this step will return an output called message with the actual message as a string. Use it as a condition expression for your branch one.

Message output

You're ready to execute the flow! Let the user enter the message + approve and you're good to execute the branch based on it!.

Approval message

The branch is executed