Published: July 29, 2020
Updated: August 11, 2020
Workflow Builder is a tool that gives the average Slack user the ability to create custom workflows using triggers that kick off a set of steps. Steps from apps is a new feature (currently in open beta) designed to allow any app, whether a third-party service or internal system, to power existing Slack workflows.
Workflow Builder requires a paid workspace. If you develop your app on a free workspace, please reach out to email@example.com to get a free trial of Slack Plus or Enterprise Grid to develop a Steps for your app.
To demonstrate what you can do with Steps from apps, I’m going to walk you through an example step. The step is called “Request copy review” and the technical implementation of the workflow presented in the blog post How to structure a Workflow Builder Step from an App.
This step can be used in many ways, across many types of workflows, but it is designed to take three inputs: a title, a description of the review needed, and the author of the task. In this tutorial you’ll be acting as both the developer and the workflow builder, in order to test your step. As a developer, you will be configuring steps. As a builder, you will create a workflow that runs automatically when triggered in a channel. That workflow will use the steps you configured earlier.
A builder, who may be a technical or non-technical user, creates a workflow in Slack. The builder will integrate our app’s step, “Request copy review”, into their workflow to integrate with the Task Manager app. They will configure which variables are passed from one step to another by configuring them in the step edit modal.
Once the workflow is configured, it will look like this:
When the workflow builder adds or edits your app's step within a workflow, you'll receive a
workflow_step_edit interactive payload and the app will respond with a call to
views.open to open a configuration view for the builder. Upon completion, your app will receive a
view_submission event to confirm the step's configuration, to which it will respond with a call to
workflow.updateStep with optional
Now that the workflow is configured, anyone can use the ⚡️shortcuts button to initiate the workflow and request a copy review on their project. This will kick off the form where they’ll add their project’s name and description which is then sent to our app. The workflow concludes with a confirmation that the task was created in Task Manager by sending a message to the channel where the workflow is configured.
When a user executes a workflow configured by a builder, your app will receive a
workflow_step_execute event, do some processing on the app side, and respond with a call to either
workflow.stepCompleted on success or
workflow.stepFailed if the step failed for any reason.
To make development simple, this guide uses Glitch, a tool that makes it easy to build basic apps. While Glitch is great for development, your server will not stay running when your app is idle. When your app is production-ready, we recommend hosting it somewhere else.
index.js file, you'll see the import of the Bolt package
(@slack/bolt), the instantiation of your app, and start-up of the app's server which listens to incoming events from Slack.
Let’s get started! First, you’ll need to set up an app on Slack. Go to Slack App Management page to create an app or click this button:
Next, go to Features > OAuth & Permissions to specify the Bot Token Scopes. Select
users.read:email. The scope
workflow.steps:execute will be added automatically after you opt into the Workflow Steps from Apps beta and configure your first step. If you are integrating Workflow Builder steps into an existing app, please be sure that it uses our granular permission model. For more information, read Installing with OAuth 2.0.
Now, go to Features > App Home. Make sure the Home Tab is checked. This app will update the user's app home with a running list of tasks created via the workflow. This feature is not required when building other Steps from Apps, and is specific to this tutorial.
Next, go to Features > Event Subscription to enable events. Then enter your Request URL. The
workflow_step_execute event will automatically be added to your subscription list after you opt into the Workflow Steps from Apps beta and configure your first step.
If you remixed the example Glitch code, your Request URL should be
https://your-project.glitch.me/slack/events. (Glitch generates a project name when you create a project. So you probably have a project name composed of two random words, such as
fluffy-umbrella. You can customize the project name as I did. If you're running on your own server, prepend the URL to
/slack/events.). In order to verify the URL using the challenge param, go to Basic Information to find the Signing Secret key, then copy and paste it to the
.env of your project.
Similarly, you will need to go to Features > Interactivity & Actions to tell Slack where to send interactive payloads. This is where your app will receive
workflows_step_edit. Use your Request URL,
https://_your-project_.glitch.me/slack/events then save.
Let’s install the app-once. Go to Install App and click to install the app to your workspace and follow the screen. Once the installation process with OAuth is finished, you should now have your OAuth access tokens on the screen.
Now, get ready with your Glitch project window in your browser, or IDE. This is where your environmental variables are stored. Copy the bot token, which begins with
xoxb, and paste it into your Glitch project's
Finally, you’ll need to opt into the Workflow Builder Steps from Apps beta. You can do this by going to Features > Workflow Steps in your app's settings.
In order for your steps to be visible in Workflow Builder to a builder, an admin will need to go to Settings & Permissions > Permissions tab > Workflow Builder Steps from Apps Beta > Expand and check the box there. Enabling this flag will show Steps from Apps from all Apps installed in the Workflow Builder Steps from Apps configuration tab.
Now that your app and workspace are opted into the beta, add a step to your app by going to your App settings > Workflow Steps > Steps and name your step “Copy Review Request” with a callback ID of
Now that the app is set up and configured, we’ll need to use it in a workflow so we can test that it works.
First, go to Workspace Settings > Tools > Workflow Builder and Create a new workflow. We’ll call this workflow “Request a Copy Review”
Start the workflow with a ⚡️shortcut and configure it to work with a channel of your choosing. Our channel is called #design-team.
Then, Add step > Create a form. This form should have three fields: Task title, Task description, and a Task Author. While Title and Description are text fields, Task Author needs "Select a person" as the question type.
Add the app’s step to the workflow. Use the Steps from Apps tab to find your step, Copy Review Request, as you configured it in your app. When you add your step to the workflow, this is the first time a
workflows_step_edit event will be dispatched to the app. If all is configured correctly, it should open a modal with three fields, the
inputs we’ve created in the example app:
Task description, and
Task Author. From there, configure Workflow Builder's variables to pass information from one step to another. Match the variables provided by the Form Step to these fields.
In the Task Author field, be sure to configure
Person who submitted form so Workflow Builder knows to pass a user to your app. Click on the variable to change the display option to
Add a Send a Message step to your workflow, to confirm the workflow is complete in channel. You can pull in variable text from other steps here, too.
To test your step, go to the ⚡️shortcuts button and try it out. The expected results are that the workflow creates a task in the Task Manager app, sends a message to confirm this to the channel, and updates your App's home tab with a list of the names of tasks created.
Great work! You now have a step set up for your app. We have a few more resources to help you continue on your journey with Workflow Builder Steps from Apps.