Workflow Builder: Steps from apps
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.
- What are steps from apps?
- Getting started with steps from apps
- Handling edits of workflow steps
- Step tracking
- Known issues
- Coming soon
What are steps from apps?
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.
Getting started with steps from apps
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.
Configure your app
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.
Create a workflow step
In your app's config, click on the Workflow Steps section. Select the toggle to opt-in — this will automatically add a few settings (such as permission scopes and event subscriptions) so that you can start creating workflow steps.
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 Workflow Builder user.
- Callback ID - a string that will act as a unique identifier for this particular step. It will be sent back to you with each action involving your step.
Click Save and you've created your app's first workflow step!
Your app's step will now be available to Workflow Builder 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.
Prepare your app for Workflow Builder
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
workflow_step_edit
payload. - App uses the
trigger_id
from that payload to open a configurationview
modal. - User completes configuration modal and submits. Your app receives a
view_submission
payload. - App creates a
workflow_step
object, and makes a call toworkflows.updateStep
. - Step is successfully added to the user's workflow.
Good news: the Bolt frameworks for Javascript, Python, and Java handle all these details for you, which makes creating a step as easy as dancing a jig.
If you're already using one of these frameworks and you've got a step running, you can skip to keeping track of the workflows the use your steps.
Otherwise, if you'd like to implement the flow yourself, let's dig in.
Receiving the 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.
Opening configuration modal
When someone building a workflow inserts your app's step, they will need a way to pass along information entered by end-users in earlier steps. We can use what we call a configuration modal to enable this.
Each field in your configuration modal should allow the builder to define the source for all input data that your app requires. The builder will be able to insert Handlebars-like {{variables}}
into any plain-text field to auto-populate output data from previous steps.
The configuration modal can also be used to configure data that doesn't come from end-users, but is defined only by the Workflow Builder user.
This type of modal can be used in much the same way as regular modals. The workflow_step_edit
payload mentioned above will contain a trigger_id
that is needed to open the modal.
Most existing Block Kit components can be used to define the configuration modal view
object.
There are a few differences between the use of regular modals and configuration modals:
- The
type
property in the modalview
will beworkflow_step
instead ofmodal
. - When the
submit_disabled
property is set totrue
the submit button will be disabled until the user has completed one or more inputs. - Apps cannot specify
title
,submit
or theclose
properties. - A configuration modal view can be updated as long as it remains open, but you cannot push new views to the 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.
Saving the configuration data using Bolt
When a configuration modal is submitted, your app will be sent a view_submission
interaction payload.
If you're using Bolt, you can easily acknowledge and process this payload by using the save
callback in the WorkflowStep
class:
The update
function will make a call to the workflows.updateStep
Web API method. This method stores the configuration of your app's step for a specified workflow.
There are a couple of arguments that the update
function requires - input
and output
.
inputs
is a key-value map of objects describing data required by your app's step. Input values can contain Handlebars{{variables}}
, which are used to include values from the outputs of some earlier step in the workflow.outputs
is an array of objects that describe the data your app's step will return when completed. Subsequent steps in the workflow after your app's step will be able to use these outputs as variables.
Read the reference guides for input
objects and output
objects to learn their full structure.
Saving configuration data manually
If you're not using Bolt, your app can manually acknowledge and close the modal view and show errors as usual. You can’t use any other type of response_action
with configuration modals.
Then 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.
The 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.
Handle usage of workflows containing your app's steps
When you switched on the Workflow Steps feature in your app, you were automatically subscribed to the workflow_step_execute
event. This event will be sent to your app every time a workflow containing one of the app's steps is used.
Using Bolt, you can listen for and respond to this event by adding an execute
callback to your WorkflowStep
class:
The event payload will include inputs
that contain any values that your step requires. These inputs come from earlier in the workflow, or from something entered in the configuration modal when the workflow step was being inserted.
You can process information from the payload or use any other relevant data to complete the step. Your app can make API calls, publish to a database, switch a lightbulb on, refresh a user's App Home, or do anything else that is relevant to the step.
That said, within the execute
callback your app must either call complete()
to indicate that step execution was successful, or fail()
to indicate that step execution failed.
The complete
function expects an outputs
object, the shape of which is dictated by the outputs
array sent earlier in the WorkflowStep.save
callback. Use the name
from each object in that array as keys, mapped to the calculated value for each output.
Handling workflow execution manually
If you're not using Bolt, read our guide to the Events API. This guide explains how to receive and handle event notifications, which includes workflow_step_execute
.
Non-Bolt apps also need to manually indicate the outcome of the step execution. 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 check the Activity
tab in Workflow Builder to inspect every run of your workflow. Any error messages for failed runs will appear there.
Well done - you've now stepped through all the steps needed to step up your workflow step game!
Handling edits of workflow steps from apps
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.
Step tracking
Count your steps by subscribing to four new events—workflow_published
, workflow_unpublished
, workflow_deleted
, and workflow_step_deleted
.
These events notify your app when another workflow including a step powered by your app has been published, unpublished, or deleted—and when one of the steps powered by your app is removed from a workflow.
Use these events to keep track of which workflows make use of your steps.
Known issues
- There is a minor, visual issue with validation errors under input blocks.
Coming soon
- 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.