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
• 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.

---

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.

Create a Slack app

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.

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 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.

Prepare your app for Workflow Builder

Here is the flow that occurs when a user adds your app's step in Workflow Builder:

1. User inserts your app's step to a workflow, your app receives a workflow_step_edit payload.
2. App uses the trigger_id from that payload to open a configuration view modal.
3. User completes configuration modal and submits. Your app receives a view_submission payload.
4. App creates a workflow_step object, and makes a call to workflows.updateStep.
5. Step is successfully added to the user's workflow.

Let's dig into this flow a bit more.

Receiving 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

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:

• The type property in the modal view will be workflow_step instead of modal.
• Apps cannot specify title, submit or the close properties.
• 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.

Receiving the view_submission payload

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.

Preparing arguments for 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.

Handle usage of workflows containing your app's steps

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!

---

Editing 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.

---

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.