Workflow Builder: Steps from apps
Use steps from apps to send data to external services, create tasks in project management systems, or update tickets.
Follow our guide to learn how to build your own steps, custom tailored to your organization’s needs.
A workflow is a multi-step process, where some of the steps are automated by Slack. Workflows are available for end-users in various locations in Slack.
Workflow Builder offers a simple set of tools to create workflows. There's no code involved, so anyone can create workflows by creating a flow of workflow steps.
In addition to the built-in steps, Slack apps can create and share their own custom steps from apps.
Users can add these steps to their workflows in Workflow Builder. The app then handles execution of that step in a workflow.
The app will receive appropriate context from the workflow, such as user inputs from earlier steps.
This feature will only work for apps using our newest granular permission model. Learn more about how to create a new Slack app.
First, you'll need a Slack app. If you don't have one, you may want to read more about how they work. If you just want to create one here and now, let's just get started.
Whether you have an existing app or a freshly minted one installed to your development workspace, you'll want to go to your app's settings for the next step.
There are some settings changes required for your app to create and use workflow steps.
The first thing you'll need to do, if you haven't already, is to enable interactivity in your app.
Go to the Interactivity & Shortcuts section and flip the switch to 'on'. You'll need to fill in the Request URL field with a URL capable of handling interaction payloads. You'll start receiving those payloads from use of your app's steps.
The next step involves subscribing to an event and adding a permission scope, and you can add these yourself as explained below. They will, however, also be automatically added to your app's settings when creating your first workflow step later in this guide.
You'll need to subscribe to an Events API type called
workflow_step_execute. This event will notify your app when a step it created has been used. Add it under the Event Subscriptions section of your app's settings.
Your app will need to be re-authenticated anywhere it is already installed after you add a new scope. Otherwise, users will not see your steps in the step library.
Please note: Organizations with admin-approved apps turned on will need to approve any re-authentication. Otherwise, only the user will be asked to go through the re-authentication flow – there will be no additional work for the administrator.
In your app's settings, click on the Workflow Steps section. Select the toggle to opt-in, and start creating workflow steps for your app.
You'll see a Steps section, listing any steps you've already created in your app. Each app can create up to 10 steps. Click the Add Step button, you'll see a modal appear with fields to configure your app's new step:
- Step name - a descriptive name which is shown to the configuring user in Workflow Builder.
- Callback ID - a string that will act as a unique identifier for this specific workflow step. It will be sent back to you with each action involving your step.
Click Save and you've created your first workflow step from your app!
Now your app's step will be available in Workflow Builder for users in workspaces where:
- Your app is installed.
- An owner or admin has enabled the steps from apps feature in the workspace or Enterprise Grid org's settings.
Here is the flow that occurs when a user adds your app's step in Workflow Builder:
- User inserts your app's step to a workflow, your app receives a
- App uses the
trigger_idfrom that payload to open a configuration
- User completes configuration modal and submits. Your app receives a
- App creates a
workflow_stepobject, and makes a call to
- Step is successfully added to the user's workflow.
Let's dig into this flow a bit more.
Read our guide to handling interaction payloads to understand how to receive and parse them. You can find a reference guide to the fields included in the
workflow_step_edit type payload here.
The process for opening and handling this type of modal is very similar to the process for regular modals, and all existing blocks are available to use in these modals. There are a few differences however:
typeproperty in the modal
- Apps cannot specify
- A configuration modal view can be updated as long as it remains open, but you cannot push new views to modal view stack.
- Configuring users will see an option to Insert a variable below any plain-text input blocks in your configuration modal. This allows the configuring user to specify that the value for any given field should be equal to the value of something collected from an end-user in an earlier workflow step. See below for more about variables.
view_submission, the configuration step is completed.
Use the information collected from the configuration modal to form the arguments needed to call the Web API method
workflows.updateStep. This method will confirm and save the configuration for your app's step within this particular workflow.
Two important fields are
inputsdescribes the data your app expects to receive when the workflow step is reached. You can use Handlebars
inputsto specify variables that are collected from users earlier in the workflow. You'll receive these variables directly in the
view_submissionfrom the configuration modal.
outputsdescribes the data your app will provide when the workflow step is completed. Subsequent steps in the workflow after your app's step will be able to use these output fields as variables.
Once you've made the API call, the user's workflow will now be saved with your app's step nestled inside. Let's move on to what happens when someone uses that newly created workflow.
When configuring your app, you subscribed to the
workflow_step_execute event. This event will be sent to your every time a workflow containing one of your app's steps is used.
In response to receiving one of these events, your app should perform whatever processing it needs to do, using the
inputs included in the
Once completed, your app should indicate whether the workflow step was successful or not. Make a call to the Web API method
workflows.stepCompleted to indicate a successful outcome. A call to
workflows.stepFailed should come after a failed attempt to complete the step. You can also check the
Activity tab in Workflow Builder to inspect every run of your workflow. Any error messages for
workflows.stepFailed will also appear there.
Well done - you've now stepped through all the steps needed to step up your workflow step game!
Once your step has been added to a workflow, configuring users will have an option to customize your step through an Edit button in Workflow Builder.
Clicking that Edit button dispatches another
workflow_step_edit payload to your interactive request URL, and the user’s previously configured inputs.
- There is a minor, visual issue with validation errors under input blocks.
- A step library for builders to browse in and find steps to add to their workflows.
- Previewing of steps in Block Kit Builder.
- Improved messaging to builders where an app step they've used in a workspace has stopped working. This can happen as a result of an app uninstall, step removal, or an import of a workflow into a workspace without the required app installed.