The new Slack platform is in beta. Your feedback is most welcome.

Forms

Build seamless data collection into your next-generation Slack app with forms, where information collected from a user can be mapped to the inputs of Workflow steps.

We'll be diving into how to add the OpenForm built-in function to a Workflow. Familiarizing yourself with our Functions and Workflows guides before continuing will help you ease into adding interactivity into your Workflow. 🚀

1. Add interactivity to your Workflow

First things first, let's take a look at the "Send a Greeting" Workflow function that comes with the Hello World sample app, available to you when you create a new Slack app.

Making your app interactive is the key to collecting user data. To accomplish this, an interactivity input parameter must be included as a Workflow property in the Workflow definition.

import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";

const GreetingWorkflow = DefineWorkflow({
  callback_id: "greeting_workflow",
  title: "Send a greeting",
  description: "Send a greeting to channel",
  input_parameters: {
    properties: {
      interactivity: {
        type: Schema.slack.types.interactivity,
      },
      channel: {
        type: Schema.slack.types.channel_id,
      },
    },
    required: ["interactivity"],
  },
});

Learn more about the interactivity type in our built-in types guide.

2. Add a form to your Workflow

Fantastic, you've completed adding the interactivity property into your Workflow. Now it's time to add OpenForm as a step in your Workflow.

A Workflow is a multi-step process, where some of the steps are automated; adding steps to your Workflows are what makes your app so seamless. For example, say you need to collect user data, send it to your information systems, then update a Slack channel with a link to a report. Each task will need to be configured as a step in your Workflow, allowing for user interactivity data to be passed to each step sequentially until this process is complete.

While some functions you use within your Workflow will be custom functions, Slack has a library of built-in functions that cover some of the most common tasks executed on our platform.

The OpenForm built-in function allows for the collection of user input which can be used when executing follow-on steps in a Workflow like sending messages, creating channels, or even pinning a message in a channel.

Add the OpenForm function as a step in your Workflow:

const inputForm = GreetingWorkflow.addStep(
  Schema.slack.functions.OpenForm,
  {
    title: "Send message to channel",
    interactivity: GreetingWorkflow.inputs.interactivity,
    submit_label: "Send message", // The text that will show as the button label in your app
    fields: {
      elements: [{
        name: "channel",
        title: "Channel to send message to",
        type: Schema.slack.types.channel_id,
        default: GreetingWorkflow.inputs.channel,
      }, {
        name: "message",
        title: "Message",
        type: Schema.types.string,
        long: true,
      }],
      required: ["channel", "message"],
    },
  },
);

// Add an extra step and send a message to a channel using user input
GreetingWorkflow.addStep(Schema.slack.functions.SendMessage, {
  channel_id: inputForm.outputs.fields.channel,
  message: inputForm.outputs.fields.message,
});

Forms haves two output parameters:

  • user_id: User ID of the person who filled out the form
  • fields: The same field names in the inputs that are returned as outputs with the values as those entered by the user

Output parameters store user interactivity data and can be used to pass information to follow-on steps in the Workflow.

The example above included an extra step, sending the users message to a specific channel that the user specified. Using the output parameter fields and selecting the desired output element by name i.e channel and message, the user's input data was passed into the second step of the Workflow.

Add as first step in Workflow
When using the OpenForm built-in function, it must be added as the first step in your Workflow.

Form elements have several properties you can customize depending on the element type:

Property Type Description
name String The internal name of the element
title String The label for the form element that the user sees. Maximum length is 25 characters
type Schema.slack.types.* The type of form field to display
default Same type as type (optional) Default value for this field

There are several Schema.slack.types available for use when defining a form element:

Type Description
string A string input field. If the optional parameter long is provided and set to true, this will render as a multi-line text box. Otherwise, it renders as a single-line text input field.
boolean A boolean rendered as a checkbox in the form.
timestamp A Unix timestamp, rendered as a date picker.
channel_id A channel picker
user_id The user_id

3. Add interactivity to the trigger's inputs

Lastly, let's add some momentum behind your Workflow and create a Link Trigger using a Trigger file. In the Trigger definition, add interactivity as an input value; this value holds context about the user interactivity that triggered the Trigger and passes it along to your Workflow.

In a separate file, define your Trigger in the following way:

import { Trigger } from "deno-slack-api/types.ts";
import GreetingWorkflow from "../workflows/greeting_workflow.ts";

const greetingTrigger: Trigger<typeof GreetingWorkflow.definition> = {
  type: "shortcut",
  name: "Send a greeting",
  description: "Send greeting to channel",
  workflow: "#/workflows/greeting_workflow",
  inputs: {
    interactivity: {
      value: "{{data.interactivity}}",
    },
    channel: {
      value: "{{data.channel_id}}",
    },
  },
};

export default greetingTrigger;

Lastly, run the following command to create the Trigger in your CLI:

slack trigger create --workflow "#/workflows/greeting_workflow" greeting_trigger.ts //add the callback_id of your workflow and Trigger file name

Viola! You've sucessfully learned how to bring interactivity to your Workflow. Keep the curiosity flowing and check out our Block Kit Interactactivity guide next, which covers bringing interactivity to custom functions.

Have 2 minutes to provide some feedback?

We'd love to hear about your experience with the new Slack platform. Please complete our short survey so we can use your feedback to improve.