Workflow steps from apps provide an ability for Slack apps to create and process custom workflow steps. These steps from apps can be shared and used by anyone in Workflow Builder.
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.
Subscribing to the workflow_step_execute event also requires that your app request a permission scope called workflow.steps:execute. Add it in the OAuth & Permissions section, under Bot Token Scopes.
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:
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:
Here is the flow that occurs when a user adds your app's step in Workflow Builder:
workflow_step_edit payload.trigger_id from that payload to open a configuration view modal.view_submission payload.workflow_step object, and makes a call to workflows.updateStep.Let's dig into this flow a bit more.
workflow_step_edit payload At this point in the flow, an interaction payload will be sent to the interactive request URL configured above.
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 workflow_step_edit payload mentioned above will contain a trigger_id that can be used to open a special type of modal we call a configuration modal.
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:
type property in the modal view will be workflow_step instead of modal.title, submit or the close properties.After view_submission, the configuration step is completed.
Your app can acknowledge and close the modal view or show errors as usual, but you can’t use any other type of response_action.
workflows.updateStep 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 inputs and outputs:
inputs describes the data your app expects to receive when the workflow step is reached. You can use Handlebars {{variables}} in inputs to specify variables that are collected from users earlier in the workflow. You'll receive these variables directly in the view_submission from the configuration modal.outputs describes 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.Read the reference guides for inputs and outputs to learn more about how to construct them.
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.
Our guide to the Events API explains how to receive and handle event notifications, and workflow_step_execute is no different.
In response to receiving one of these events, your app should perform whatever processing it needs to do, using the inputs included in the workflow_step_execute event.
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.