Skip to main content

Workflow steps

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

Workflow steps combine the utility of Workflow Builder with the custom functionality of your choosing. Not to be confused with legacy Steps from Apps, workflow steps are functions that you add to an app (via the app manifest or Workflow Steps page in your app's settings) that can then be used as steps in Workflow Builder. You have the flexibility to create an app that contains workflow steps using the Deno SDK, the Bolt SDK, or entirely on your own, sans Slack tooling. This guide will talk through the differences in tooling to create workflow steps, how to manage your apps with workflow steps, and distribution options.

SDKs for building apps with workflow steps​

The following Slack SDKs support custom workflow steps.

SDKLanguage(s) supportedHostingMore information
Deno SDKTypeScriptSlack-hostedThe Deno SDK is optimized for workflows, so it enables you to build steps, build workflows with your own steps, Slack steps, and connector steps, as well as utilize Slack datastores. Deno SDK apps are hosted on Slack.
Bolt SDKJava, JavaScript, PythonSelf-hostedThe Bolt SDK supports steps and are self-hosted.

Managing your app​

Slack offers two options for app management.

Slack CLI​

Bolt app creation and management with the CLI is in beta and under active development.

If your app is created with the Slack CLI, we recommend using the Slack CLI to manage it. Apps built with Deno SDK and Bolt SDK are compatible with the Slack CLI.

➡️ Follow this quickstart guide to get started with the Slack CLI for a Deno app.

➡️ Create a Bolt app.

App settings​

If your app is created manually, we recommend that you continue to manage it on your app's configuration page.

Make your app org-ready​

Adding workflow steps to your app requires it to be an org-ready app. To learn what this means and how to prepare your app in the app settings, refer to our guide on org-ready apps.

Create a new step​

To add workflow steps to your app in the app settings, first select your app from the list here, then navigate to App Manifest and add the following event subscription, then save your changes:

    "settings": {
        ...
        "event_subscriptions": {
            "bot_events": [
                "function_executed"
            ]
        },
    }

Once that is taken care of, navigate to Workflow Steps in the left nav menu. Click Add Step and heed any immediate warnings that may pop up, such as adding bot scopes and enabling your app for org-wide distribution. Then name your step, define its callback_id, and add any desiredinput_parameters and output_parameters. You will see the step reflected in this screen as well as in the app manifest. Navigate to App Manifest to see your newly created workflow step.

A step called "Update report" with a callback_id of update_report and two required input parameters, report_date and report_update, is reflected in the manifest like this:

    "functions": {
        "update_report": {
            "title": "Update report",
            "description": "",
            "input_parameters": {
                "report_date": {
                    "type": "slack#/types/date",
                    "title": "Report Date",
                    "description": "",
                    "is_required": true,
                    "name": "report_date"
                },
                "report_update": {
                    "type": "string",
                    "title": "Report Update",
                    "description": "",
                    "is_required": true,
                    "name": "report_update"
                }
            },
            "output_parameters": {}
        }
    }

While steps can be defined in the app settings manifest editor like this, you must implement a function listener in code to determine what happens when the step is invoked.

Implement function logic​

Once you've added your custom steps to your app manifest, you must implement the logic for how they will execute. This varies based on how you choose to write your app logic. Regardless of how the custom steps are implemented, they must finish by calling either the functions.completeSuccess method or the functions.completeError method.

In Bolt, complete and fail are utility methods you can call at the completion of a function. Reference the Custom steps for Bolt apps guide.

In Deno, you will return either an error or completed object, along with the outputs. See the Custom functions for workflow apps guide for reference.

App distribution​

Distribution works differently for Slack apps that contain workflow steps when the app is within a standalone (non-Enterprise Grid) workspace versus within an Enterprise Grid organization.

  • Within a standalone workspace: Slack apps that contain workflow steps can be installed on the same workspace and used within that workspace. We do not support distribution of workflow steps to other standalone workspaces (also known as public distribution).
  • Within an organization: Slack apps that contain workflow steps should be org-ready (enabled for private distribution) and installed on the organization level. They must also be granted access to at least one workspace in the organization for the steps to appear in Workflow Builder.

Apps containing workflow steps cannot be distributed publicly or submitted to the Slack Marketplace. We recommend sharing your code as a public repository in order to share workflow steps.

To protect your organization, external users (those outside your organization connected through Slack Connect) cannot use a workflow that contains connector steps or workflow steps built by your organization.This may manifest in a home_team_only warning.

Refer to this help center article for more details.

Next steps​

Curious about building your own?

➡️ Read more about building workflow steps with the Deno SDK here.

 ✨ Then check out a step-by-step tutorial for this functionality.

➡️ Read more about building workflow steps with the Bolt SDK here.

 ✨ Then check out the following tutorials: