Slack integration

Slack is an instant messaging and collaboration platform.

There are two ways to build interactions between Slack and Windmill: run code on Windmill by a Slack command or use the Slack API directly from Windmill. In this guide, we'll cover both approaches.

Action on Windmill from Slack

The goal here is to be able to invoke a Windmill Script from Slack, by using /windmill command.

First, you need to be a workspace admin. Then you should go to

Workspace Settings Page

and select the "Slack Command" tab. On there, click "Connect to Slack".

Self-hosted

The Slack integration is done through OAuth. On self-hosted instances, integrating an OAuth API will require Setup OAuth and SSO.

Slack will ask you to allow Windmill to access your workspace. Click "Allow".

note

At the time of writing, Slack cautions that Windmill is not an approved app. We are working on getting the app approved but you can safely ignore it for now.

You can connect multiple Windmill workspaces to the same Slack workspace. Only one Windmill workspace can accept the /windmill commands from a given Slack workspace. This feature is mostly useful for the error handler.

Using commands on Slack

Once you allow access, you will be redirected to the Slack settings in Windmill. We'll create a command handler Script first, so let's click "Create a script to handle Slack command".

You will be navigated to the Script editor. Give your script a name (e.g. slack_command_handler), a short summary (e.g. "Slack command handler"). You'll get to this template:

export async function main(response_url: string, text: string) {
	const x = await fetch(response_url, {
		method: 'POST',
		body: JSON.stringify({ text: `ROGER ${text}` })
	});
	const username = await Deno.env.get('WM_USERNAME');
	console.log(`user = ${username}`);
}

After the Script is deployed, navigate back to the

Slack settings

Choose the "Script" option for adding a command handler and select your newly created Script.

Congratulations! You've just created a Slack command handler. Now you can use the /windmill command in your Slack workspace to trigger the Script. Try it out with /windmill foo and you should get back ROGER foo. Go ahead and customize the Script to your needs.

In addition to response_url, the script/flow can use the following parameters, simply by having them as inputs with the proper name:

channel_id
user_name
user_id
command
trigger_id
api_app_id

You won't be able to have Slack interact with your resources and variables before adding them to the slack group that was automatically created by Windmill after you set up your Slack workspace on Windmill. Tutorial below.

How to let Slack use your resources and variables:

To give the permission, go to "Resources" (and "Variables") menu, click on Share, Group and pick slack.

One simplier way to handle permissions is to host resources and variables on a folder that is part of the group slack.

Handle multiple commands

We cover in a subsequent article how to manage multiple commands & human-in-the-loop steps from your slackbot using branches, a text parser and approval steps.

Tutotial - Handler of multiple Slack commands

Create a flow with a parser & branches that will handle multiple Slack commands.

Monitor who ran the command

You can see who ran the /windmill command by going to the

Runs page

on Windmill. The runs will be permissioned through the g/slack global group.

You can also monitor and permission it from within the script leveraging the contextual variable WM_USERNAME that will get the value of the Slack user.

For example our script:

export async function main(response_url: string, text: string) {
	const x = await fetch(response_url, {
		method: 'POST',
		body: JSON.stringify({ text: `ROGER ${text}` })
	});
	// This part:
	const username = await Deno.env.get('WM_USERNAME');
	console.log(`user = ${username}`);
}

will console.log user = username, username being the Slack username.

Slack approval steps

Approval steps are a way to suspend a flow until specific event(s) are received, such as approvals or cancellations. You can use them to handle approvals from Slack.

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:

• Python: Request Interactive Slack Approval
• TypeScript: Request Interactive Slack Approval

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

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

Python

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"]},
)

Bun

await wmill.requestInteractiveSlackApproval({
    slackResourcePath: "/u/username/my_slack_resource",
    channelId: "admins-slack-channel",
    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:

Python

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',
    )

Bun

import * as wmill from "windmill-client"

export async function main() {
  await wmill.requestInteractiveSlackApproval({
    slackResourcePath: "/u/username/slack_resource",
    channelId: "customers"
  })
  await wmill.requestInteractiveSlackApproval({
    slackResourcePath: "/u/username/slack_resource",
    channelId: "admins"
  })
}

For more details on approval steps and their features, check out the Approval steps documentation.

Suspend & Approval / Prompts

Suspend a flow until specific event(s) are received, such as approvals or cancellations.

Action on Slack from Windmill

The second way to make Slack and Windmill interact is through scripts triggered from Windmill to the Slack API. In other words, our goal here is to allow Windmill Scripts acting on Slack on your behalf.

Lets navigate to the Resources page page and click "Add a resource/API".

info

You can read more about Resources in the documentation here.

Select the slack Resource Type from the "OAuth APIs" list and by clicking "Connect", you will be redirected to the Slack account associated with your browser. Click "Allow" to let Windmill access your Slack workspace. Once that's done, you will be redirected back to Windmill, where you can name your Slack Resource and Save it.

note

On self-hosted instances, integrating an OAuth API will require Setup OAuth and SSO.

Your connection is made! Now you can trigger the Slack API from Windmill.

For example, try this script to send a message to a channel.

import { WebClient } from 'https://deno.land/x/slack_web_api@1.0.0/mod.ts';
type Slack = {
	token: string;
};

export async function main(text: string, channel: string, slack: Slack) {
	const web = new WebClient(slack.token);

	await web.chat.postMessage({
		channel,
		text
	});
}

Have messages published on Windmill's behalf

Using the resource created above, Slack will behave on your behalf (under your name).

To have messages published on Windmill's behalf, use the Slack resource created in the Action on Windmill from Slack section.

What's next?

Also, explore more Slack scripts, flows and apps on Windmill Hub.

Error handlers

Slack is an efficient way to be notified of errors on a Windmill run, whole workspace or instance. Windmill provides an integration for error handling on Slack.

More details on Error handling page.

Critical alerts

Slack can be used to receive critical alerts from Windmill. This feature is available in the Enterprise Edition.

Critical alerts are generated under the following conditions:

• Job is re-run after a crash
• License key does not renew
• Workspace error handler fails
• Number of running workers in a group falls below a specified threshold
• Number of jobs waiting in queue is above a threshold for more than a specified amount of time

To set up critical alerts to Slack:

1. Configure SMTP in the instance settings
2. Connect your instance to Slack in the instance settings
3. Specify the Slack channel where alerts should be sent

You can also set up worker group-specific alerts to receive notifications when the number of running workers in a group falls below a specified threshold. This can be configured in the worker group config.

note

Instance-wide critical alerts are only visible to users with the superadmin or devops roles. For workspace-specific alerts, users need to have admin privilege over that workspace.

Critical alerts

Get a notification for critical events such as everytime a job is re-run after a crash.