Published: July 29, 2020
Updated: September 29, 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 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 feedback@slack.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 inputs and outputs.
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.
To get started, remix our Task Manager app, which uses the Bolt for JavaScript SDK under the hood.
🎏🍴 Remix (fork) the Glitch repo
In the 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, and users.read:email. The scope workflow.steps:execute will be added automatically after you 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.
Let’s install the app. 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 .env file.
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. In order to verify the events 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. Then enter your Request URL. The workflow_step_execute event will automatically be added to your subscription list after you configure your first step.
There will be a banner prompting you to reinstall your app to accept the new workflow.steps:execute scope.
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.).
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.
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 copy_review.
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. Uncheck the Send submitted responses to... box as we will configure the workflow to send a message confirmation to the channel where the workflow was started.
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 title, 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 email so the app can post new tasks back to that user's App Home.
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.
