Published: July 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 (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 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 event 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 workflow.steps:execute, users:read, and users.read:email. 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.
Next, go to Features > Event Subscription to enable events. Then enter your Request URL and add the workflow_step_execute event to your subscription list.
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. 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 .env file.
Also in the Slack app config page, get your Signing Secret key at Settings > Basic information, then copy and paste it to the .env too.
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 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. Use the builder's variables to pass information from one step to another. In the Task Author field click on the variable to change the display option to email.
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. Match the variables provided by the Form Step to these fields.
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.
