diff --git a/docs/_future/app_manifests.md b/docs/_future/app_manifests.md index d3bff50e0..2bc421f7e 100644 --- a/docs/_future/app_manifests.md +++ b/docs/_future/app_manifests.md @@ -71,7 +71,7 @@ module.exports = Manifest({ ### Manifest properties {#manifest-properties} -The properties in the Manifest are: +The properties in the manifest are: |Property|Type|Has Bolt support?|Description| |---|---|---|---| @@ -82,19 +82,19 @@ The properties in the Manifest are: | `longDescription` | String | ✅ Yes | (Optional) A more detailed description of your application | | `icon` | String | ❌ No | A relative path to an image asset to use for the app's icon. Your app's profile picture that will appear in the Slack client | | `backgroundColor` | String | ✅ Yes | (Optional) A six digit combination of numbers and letters (the hexadecimal color code) that make up the color of your app background e.g., "#000000" is the color black | -| `botScopes` | Array | ✅ Yes | A list of [scopes](/scopes), or permissions, the app's Functions require | -| `functions` | Array | ✅ Yes | (Optional) A list of all Functions your app will use | -| `workflows` | Array | ✅ Yes | (Optional) A list of all Workflows your app will use | +| `botScopes` | Array | ✅ Yes | A list of [scopes](/scopes), or permissions, the app's functions require | +| `functions` | Array | ✅ Yes | (Optional) A list of all functions your app will use | +| `workflows` | Array | ✅ Yes | (Optional) A list of all workflows your app will use | | `outgoingDomains` | Array | ✅ Yes | (Optional) If your app communicates to any external domains, list them here. Note that the outgoing domains are only restricted if the workspace has Admin approved apps on e.g., myapp.tld | -| `events` | Array | ✅ Yes | (Optional) A list of all Event structures that the app is expecting to be passed via [Message Metadata](/metadata/using) | +| `events` | Array | ✅ Yes | (Optional) A list of all event structures that the app is expecting to be passed via [Message Metadata](/metadata/using) | | `types` | Array | ✅ Yes | (Optional) A list of all [custom types](https://api.slack.com/future/types/custom) your app will use | -| `datastores` | Array | ❌ No | (Optional) A list of all [Datastores](https://api.slack.com/future/datastores) your app will use. This is currently only available for non-Bolt next-generation apps. You can learn more [here](/bolt-js/future/getting-started#next-gen). | +| `datastores` | Array | ❌ No | (Optional) A list of all [datastores](https://api.slack.com/future/datastores) your app will use. This is currently only available for non-Bolt next-generation apps. You can learn more [here](/bolt-js/future/getting-started#next-gen). | | `features` | Object | ✅ Yes | (Optional) A configuration object of your app features | -You will come back to the Manifest every time you create a new workflow, since all workflows for your app need to be added to the Manifest in order to use them. +You will come back to the manifest every time you create a new workflow, since all workflows for your app need to be added to the manifest in order to use them. --- ### Next steps {#next-steps} -Now that you're acquainted with the Manifest, you can dive into the world of [built-in functions](/bolt-js/future/built-in-functions) and [custom functions](/bolt-js/future/custom-functions)! +Now that you're acquainted with the manifest, you can dive into the world of [built-in functions](/bolt-js/future/built-in-functions) and [custom functions](/bolt-js/future/custom-functions)! diff --git a/docs/_future/built_in_functions.md b/docs/_future/built_in_functions.md index 10a9876e6..2f5571fb5 100644 --- a/docs/_future/built_in_functions.md +++ b/docs/_future/built_in_functions.md @@ -9,7 +9,7 @@ permalink: /future/built-in-functions # Built-in functions BETA
-Slack provides built-in functions you can use alongside your [custom functions](/bolt-js/future/custom-functions) in a Workflow. Built-in functions are essentially Slack-native actions, like creating a channel or sending a message, that work hand-in-hand with your functions. +Slack provides built-in functions you can use alongside your [custom functions](/bolt-js/future/custom-functions) in a workflow. Built-in functions are essentially Slack-native actions, like creating a channel or sending a message, that work hand-in-hand with your functions.

Please note that some built-in functions may be restricted due to Workspace permission settings. Reach out to a Workspace owner if these aren't available to you.

@@ -17,13 +17,13 @@ Slack provides built-in functions you can use alongside your [custom functions]( --- -### Using with Workflows {#workflows} +### Using with workflows {#workflows} -Built-in functions need to be imported from the standard library built into the SDK — all built-in functions are children of the `Schema.slack.functions` object. Just like custom Functions, built-ins are then added to steps in a Workflow using the `addStep` method. That's it! +Built-in functions need to be imported from the standard library built into the SDK — all built-in functions are children of the `Schema.slack.functions` object. Just like custom functions, built-ins are then added to steps in a workflow using the `addStep` method. That's it! Built-in functions define their own inputs and outputs, as detailed for each built-in below. -Here's an example of a Workflow that sends a message using the `SendMessage` built-in function: +Here's an example of a workflow that sends a message using the `SendMessage` built-in function: ```javascript const { DefineWorkflow, Schema } = require('@slack/bolt'); @@ -38,7 +38,7 @@ SampleWorkflow.addStep(Schema.slack.functions.SendMessage, { module.exports = { SampleWorkflow }; ``` -Read the full documentation for [Workflows](/bolt-js/future/workflows) to learn how to build out Workflows. +Read the full documentation for [workflows](/bolt-js/future/workflows) to learn how to build out workflows. --- diff --git a/docs/_future/custom_functions.md b/docs/_future/custom_functions.md index 8b30c470f..370ba3650 100644 --- a/docs/_future/custom_functions.md +++ b/docs/_future/custom_functions.md @@ -9,10 +9,10 @@ permalink: /future/custom-functions # Custom functions BETA
-On the next-generation platform, you can build **custom functions**, reusable building blocks of automation that are deployed to our infrastructure and accept inputs, perform some calculations, and provide outputs. Functions can be used as steps in [Workflows](/bolt-js/future/workflows)—and Workflows are invoked by [Triggers](/bolt-js/future/triggers). +On the next-generation platform, you can build **custom functions**, reusable building blocks of automation that are deployed to our infrastructure and accept inputs, perform some calculations, and provide outputs. Functions can be used as steps in [workflows](/bolt-js/future/workflows)—and workflows are invoked by [triggers](/bolt-js/future/triggers). To create a function, we need to do the following: -- [define the function](#define) in the Manifest; +- [define the function](#define) in the manifest; - [implement the function](#implement) in its respective source file;
@@ -56,11 +56,11 @@ const SampleFunctionDefinition = DefineFunction({ module.exports = { SampleFunctionDefinition }; ``` -Note that we import `DefineFunction`, which is used for defining our function, and also `Schema`, which has information on supported [Built-in types](https://api.slack.com/future/types). +Note that we import `DefineFunction`, which is used for defining our function, and also `Schema`, which has information on supported [built-in types](https://api.slack.com/future/types). -Just like [Workflows](/bolt-js/future/workflows), Custom functions have a unique `callback_id` and also require a `title`. Additionally, you can set inputs and outputs just like you can with Workflows. +Just like [workflows](/bolt-js/future/workflows), custom functions have a unique `callback_id` and also require a `title`. Additionally, you can set inputs and outputs just like you can with workflows. -Here's all the fields you can use when defining a Custom function: +Here's all the fields you can use when defining a custom function: | Field | Expected value | | ---- | ------------------ | @@ -71,7 +71,7 @@ Here's all the fields you can use when defining a Custom function: | `output_parameters` | An object which describes one or more output parameters that will be returned by your function. This object follows the exact same pattern as `input_parameters`: top-level properties of the object define output parameter names, with the property values further describe the type and description of each individual output parameter. | The value for properties in `input_parameters` and `output_parameters` needs to be an object with further sub-properties: - * `type`: The type of the input parameter. This can be a [Built-in type](https://api.slack.com/future/types) or a [Custom type](https://api.slack.com/future/types/custom) that you define. + * `type`: The type of the input parameter. This can be a [built-in type](https://api.slack.com/future/types) or a [custom type](https://api.slack.com/future/types/custom) that you define. * `description`: A string description of the parameter. If you want to set a property as required, list its name in its respective input or output properties as a `required` property. @@ -92,7 +92,7 @@ input_parameters: { Functions can (and generally should) declare inputs and outputs. -Inputs are declared in the `input_parameters` property, and outputs are declared in the `output_parameters` property. Each can contain either [Built-in types](https://api.slack.com/future/types) or [Custom types](https://api.slack.com/future/types/custom) that you define. +Inputs are declared in the `input_parameters` property, and outputs are declared in the `output_parameters` property. Each can contain either [built-in types](https://api.slack.com/future/types) or [custom types](https://api.slack.com/future/types/custom) that you define. While, strictly speaking, input and output parameters are optional, they are a common and standard way to pass data between functions and nearly any function you write will expect at least one input and pass along an output. @@ -102,7 +102,7 @@ Once your function is defined in its own file in `manifest/functions`, the next --- -### Implementing a Function Listener {#implement} +### Implementing a function listener {#implement} Implement functions in just a few steps: @@ -120,7 +120,7 @@ To do this, create a file in `listeners/functions` directory for your function l // For more information about functions: https://api.slack.com/future/functions const { SlackFunction } = require('@slack/bolt'); -// Get our Function Definition from the manifest! +// Get our function Definition from the manifest! const { SampleFunctionDefinition } = require('../../manifest/functions/sample-function'); // Here is the work we want to do! @@ -138,14 +138,14 @@ const helloWorld = async ({ event, complete }) => { } }; -// Let's create a new Slack Function with helloWorld as its handler +// Let's create a new Slack function with helloWorld as its handler const helloWorldFunc = new SlackFunction(SampleFunctionDefinition.id, helloWorld); module.exports = { helloWorldFunc }; ``` The `hello-world.js` file declares a function handler, `helloWorld`, that takes in inputs from the `event`, which is the payload received when your function is being executed. It executes logic within the handler to return a message with a random greeting. This message is the function's output. In addition to the function handler, a new `SlackFunction` instance is declared that actually links the `helloWorld` handler to `SampleFunctionDefinition` through the function's ID: ```js -// Let's create a new Slack Function with helloWorld as its handler +// Let's create a new Slack function with helloWorld as its handler const helloWorldFunc = new SlackFunction(SampleFunctionDefinition.id, helloWorld); ``` @@ -162,7 +162,7 @@ module.exports.register = (app) => { ``` -Lastly, in order to make sure this handler is triggered, make sure the Function listeners are registered in your `listeners/index.js` file: +Lastly, in order to make sure this handler is triggered, make sure the function listeners are registered in your `listeners/index.js` file: ```js // listeners/index.js const functions = require('./functions'); @@ -172,8 +172,8 @@ module.exports.registerListeners = (app) => { }; ``` #### 3. Add the function as a step in your workflow -To actually call the defined function, `SampleFunctionDefinition`, don't forget to add your function to a workflow! When you're finished defining and implementing your functions, the next step is to add them to [Workflows](/bolt-js/future/workflows). Once added as a step in a Workflow, your Function will run when that Workflow is invoked by a [Trigger](/bolt-js/future/triggers). +To actually call the defined function, `SampleFunctionDefinition`, don't forget to add your function to a workflow! When you're finished defining and implementing your functions, the next step is to add them to [workflows](/bolt-js/future/workflows). Once added as a step in a workflow, your function will run when that workflow is invoked by a [trigger](/bolt-js/future/triggers). --- ### Next steps -You've learned about built-in and custom functions - now it's time to jump into [Workflows](/bolt-js/future/workflows) and learn about how they work with Functions. 🎉 +You've learned about built-in and custom functions - now it's time to jump into [workflows](/bolt-js/future/workflows) and learn about how they work with functions. 🎉 diff --git a/docs/_future/deploy_your_app.md b/docs/_future/deploy_your_app.md index 8ceaf52f1..955cbcbbc 100644 --- a/docs/_future/deploy_your_app.md +++ b/docs/_future/deploy_your_app.md @@ -23,11 +23,11 @@ In this guide, you will find the steps needed to prepare and deploy your app to Before you can deploy a Bolt app to Heroku, you'll need a working Bolt app. If you haven't created one yet, [go ahead and make one](/bolt-js/future/getting-started#create-app)! If you already have an app and want features of the next-generation platform, check out the [Bolt for JavaScript setup guide](/bolt-js/future/setup-existing-app). -Additionally, you will need to have at least one Trigger created for your application to confirm that your application has successfully deployed to Heroku. If you haven't created one yet, you can learn about [the different types of Triggers](/bolt-js/future/triggers#types) and [how to create a Trigger](/bolt-js/future/triggers#create) for tapping into your Workflows. +Additionally, you will need to have at least one trigger created for your application to confirm that your application has successfully deployed to Heroku. If you haven't created one yet, you can learn about [the different types of triggers](/bolt-js/future/triggers#types) and [how to create a trigger](/bolt-js/future/triggers#create) for tapping into your workflows. > 💡 List your application's existing triggers by running `slack triggers list` in your project directory and selecting a workspace where it is installed! -With your app and Trigger created, you can now use the `slack run` command to make sure your app starts successfully and appropriately responds to Triggers from your machine. +With your app and trigger created, you can now use the `slack run` command to make sure your app starts successfully and appropriately responds to triggers from your machine. Since we're deploying to Heroku, having a Heroku account will also be useful. If you don't have one, [create one here](https://signup.heroku.com/). @@ -108,7 +108,7 @@ To specify the start command of your app for Heroku, [a special file called `Pro The contents of this file will vary depending on if your app connects with [Socket Mode](https://api.slack.com/apis/connections/socket) or uses public HTTP endpoints to handle requests. To check whether Socket Mode is enabled for your application, you can either: -* Check your app's [Manifest](/bolt-js/future/app-manifests) to see if `socketModeEnabled: true`, or +* Check your app's [manifest](/bolt-js/future/app-manifests) to see if `socketModeEnabled: true`, or * Visit the "Socket Mode" section on your app's [App Config page](https://api.slack.com/apps) to check if Socket Mode has been enabled: The toggle for connecting with Socket Mode on the App Config page is enabled @@ -208,7 +208,7 @@ For this, we will use the "Web URL" found from `heroku info` to update the **Req At this step your app should be live, listening for messages, events, or whatever else you have coded up! Go ahead and jump into a workspace with your app to test things out! 🚀 -Now would be a terrific time to try tripping your Trigger to test that your Workflows are executing as expected - however, make sure to confirm that you're not running the app locally! A successfully deployed Heroku app is one that is not running locally and will still fully execute your Trigger and all functionality associated with it. +Now would be a terrific time to try tripping your trigger to test that your workflows are executing as expected - however, make sure to confirm that you're not running the app locally! A successfully deployed Heroku app is one that is not running locally and will still fully execute your trigger and all functionality associated with it. ### Inspecting the activity logs {#activity-logs} @@ -252,7 +252,7 @@ $ git commit -am "Add mystery to the greeting message" $ git push -u heroku main ``` -After the "Build succeeded!" and "Verifying deploy... done." messages appear, your app will have this newfound functionality! You can now test your Trigger again to verify the new change. +After the "Build succeeded!" and "Verifying deploy... done." messages appear, your app will have this newfound functionality! You can now test your trigger again to verify the new change. --- diff --git a/docs/_future/getting_started_future.md b/docs/_future/getting_started_future.md index e27e1d447..5aab626e7 100644 --- a/docs/_future/getting_started_future.md +++ b/docs/_future/getting_started_future.md @@ -10,66 +10,67 @@ permalink: /future/getting-started # Getting started BETA
-This guide will walk you through introducing you to the [next-generation platform](/bolt-js/future/getting-started#next-gen). It will also cover how to get started with your next-gen platform experience with Bolt for JavaScript by setting up the Slack CLI and also installing the required dependencies. -
- ---- -### What is the next-generation platform? {#next-gen} +This guide will walk you through getting started with next-generation developing Slack apps. This new platform enables creation of modular, shareable, and remixable building blocks within your apps that make it easier than ever to connect and reuse functionality. -

Our next-generation platform is currently in beta. [Your feedback is most welcome](/bolt-js/future/feedback) - all feedback will help shape the future platform experience!

+You can learn more about the next-generation platform on Slack's [official introduction page](https://api.slack.com/future). +
-The next-generation platform is an exciting new way to develop apps for Slack! It is focused on 2 components: -1. **Flexible functionality**: You can now create modular, shareable, and remixable building blocks within your apps that make it easier than ever to connect and reuse functionality. The primary components of this new functionality are [built-in](/bolt-js/future/built-in-functions) and [custom functions](/bolt-js/future/custom-functions), [workflows](/bolt-js/future/workflows), and [triggers](/bolt-js/future/triggers). -2. **Quick setup**: With our next-generation developer tools, you can quickly build secure, scalable apps. One of the tools is the [Slack CLI](https://api.slack.com/future/tools/cli), which allows faster development by allowing you to create and scaffold apps all from the command line. Another tool are [app manifests](/bolt-js/future/app-manifests), which are configuration files for your apps that can be shared and reused to quickly set up applications. +> 💡 Currently, the new Slack Platform beta is only available for workspaces on a paid plan. -#### Limitations +--- +### Limitations {#limitations} -Today, Bolt for JavaScript supports app development using next-gen platform features like Functions and Workflows and tools such as the Slack CLI alongside all current generally available Slack Platform features. +Bolt for JavaScript supports app development using next-gen platform features like functions and workflows, development tooling through the [Slack CLI](https://api.slack.com/future/tools/cli), and all generally available [Slack Platform](https://api.slack.com/start/overview) features. -We do not yet support deployment to secure and managed Slack infrastructure or Datastores API [Datastores](https://api.slack.com/future/datastores) functionality. +#### Bolt for JavaScript does not yet support: +- [Deployment](https://api.slack.com/future/deploy) of your next-gen app to secure and managed Slack infrastructure +- The Datastores API [datastores](https://api.slack.com/future/datastores) and related datastores functionality -If you'd like to deploy your app with Slack infrastructure, consider building your next-generation application with the Deno Slack API. You can get started with that [here](https://api.slack.com/future/get-started). +> ⚠️ If you'd like to deploy your app with Slack infrastructure, consider building your next-generation application with the Deno Slack API. You can get started with that [here](https://api.slack.com/future/get-started). --- +### Setting up {#setting-up} -### Setting up the CLI {#setting-up-cli} +The next-generation experience for Bolt for JavaScript requires: +- [The Slack CLI](/bolt-js/future/getting-started#installing-the-slack-cli) +- [Node](/bolt-js/future/getting-started#installing-node) +- A workspace on a paid plan with an [Accepted Beta Terms of Service](/bolt-js/future/getting-started#accept-tos). -To build a next-generation app with Bolt for JavaScript, you'll first need to get the Slack CLI set up on your machine. You can follow the [Quickstart Guide](https://api.slack.com/future/quickstart) to get instructions on how to manually or automatically install it based on your operating system. +If you already have these dependencies set up, you can skip to the next section. -Since we won't be using Deno to build or setup an existing next-generation app, you can skip any instructions related to installing Deno or creating an app using a Deno template. Once you've logged into the CLI using `slack login` and verified your login using `slack auth list`, you can proceed with the instructions in this guide. +#### Installing the Slack CLI {#installing-the-slack-cli} -> 💡 When logging into a workspace using the CLI, we recommend using a workspace where you won't disrupt real work getting done. Currently the new Slack Platform beta is only available for workspaces on a paid plan. +Follow the [Quickstart Guide](https://api.slack.com/future/quickstart) to get instructions on how to manually or automatically install the Slack CLI based on your operating system. You can skip any instructions related to installing Deno or creating an app using a Deno template. ---- - -### Install dependencies {#install-dependencies} +Once you've logged into the CLI using `slack login` and verified your login using `slack auth list`, you can proceed with the instructions in this guide. -Once the CLI is set up, make sure your machine has the most recent version of [Node](https://nodejs.org/en/) installed. Depending on what operating system your machine uses, you can either install Node through a package manager (such as [Homebrew](https://brew.sh/) for Mac) or directly from the website. +#### Installing Node {#installing-node} ---- +Make sure your machine has the most recent version of [Node](https://nodejs.org/en/) installed. Depending on what operating system your machine uses, you can either install Node through a package manager (such as [Homebrew](https://brew.sh/) for Mac) or directly from the website. -### Accept the Beta Terms of Service {#accept-tos} +#### Accept the Beta Terms of Service {#accept-tos} -In order to use the next-generation platform features, you'll need to accept a Terms of Service for Slack Platform Beta. To do so, go to the Workspace Settings of the workspace you'll be developing with, then go to the Permissions tab. Find the "Slack Platform Beta" heading, then select the checkbox that says "I have read and agree to the Slack Platform Beta Service Terms" and save the section. Once you have accepted, the section will look like this: - -![Beta Terms of Service](../assets/beta-tos-future.png "Beta Terms of Service") +In order to use the next-generation platform features, you'll need to accept a Terms of Service (TOS) for Slack Platform Beta in your Workspace Settings [here](https://slack.com/admin/settings#hermes_permissionfs). > 💡 You must be an admin of your workspace to be able to access the Workspace Settings and accept the Terms of Service. +If the TOS has been accepted, you will see this view under the "Slack Platform Beta" section when navigating to the above link: -Congratulations! You're now ready to start building using the [next-generation Platform](/bolt-js/future/getting-started#next-gen). 🎉 You can now proceed with either creating a new app by following the instructions below or [setting up an existing app](/bolt-js/future/setup-existing-app). +![Beta Terms of Service](../assets/beta-tos-future.png "Beta Terms of Service") + +Congratulations! You're now ready to start building using the [next-generation platform](/bolt-js/future/getting-started#next-gen). 🎉 You can now proceed with creating a new app by following the instructions below or explore how to [set up an existing app](/bolt-js/future/setup-existing-app). --- ### Create a new app {#create-app} -Before you start developing with Bolt, you'll want to create a Slack app. +To start, you'll need to create a Slack app. -To create the app, you'll run the following command: +Create a starter next-generation app with the CLI: ``` slack create my-app -t slack-samples/bolt-js-starter-template -b future ``` -This command creates an app through the CLI by cloning a specified template. In this case, the template is the [Bolt for JavaScript Starter Template](https://github.com/slack-samples/bolt-js-starter-template/tree/future) on the `future` branch. This starter template includes a "Hello World" example that demonstrates how to use [built-in](/bolt-js/future/built-in-functions) and [custom](/bolt-js/future/custom-functions) Functions, [Triggers](/bolt-js/future/triggers), and [Workflows](/bolt-js/future/workflows). +This command creates an app through the CLI by cloning a specified template. In this case, the template is the [Bolt for JavaScript Starter Template](https://github.com/slack-samples/bolt-js-starter-template/tree/future) on the `future` branch. The application will take a few moments to set up and clone the repository. Once the app is successfully created, you should see a message like this: ``` @@ -88,21 +89,34 @@ The application will take a few moments to set up and clone the repository. Once 🔔 If you leave the workspace, you won’t be able to manage any apps you’ve deployed to it. Apps you deploy will belong to the workspace even if you leave the workspace ``` -Your app has now been created in the `my-app` directory! This application can be used as a template for you to build your own next-generation Bolt for JavaScript app with. However, if you'd like to test the "Hello World" example included in your template, read on! 📖 +At this point, your app is now ready to go in the `my-app` directory! + +The starter template your app is based off of includes a "Hello World" example that demonstrates how to use the three main building blocks of next-generation Slack apps: [built-in](/bolt-js/future/built-in-functions) and [custom](/bolt-js/future/custom-functions) functions, [triggers](/bolt-js/future/triggers), and [workflows](/bolt-js/future/workflows). + +**At a quick glance:** +1. **Functions** define the actions of your app +2. **Workflows** group **functions** into ordered steps +3. **Triggers** invoke **workflows** + +If you'd like to test the "Hello World" example included in your template and see how functions, workflows, and triggers all tie together, read on! 📖 + +> 💡 This application can be the starting point for you to build your own app features. Explore on your own and dive into the code [here](https://github.com/slack-samples/bolt-js-starter-template/tree/future), or continue your journey by learning about [app manifests](/bolt-js/future/app-manifests), and how to add more [functions](/bolt-js/future/built-in-functions), [workflows](/bolt-js/future/workflows), and [triggers](/bolt-js/future/triggers) to your app! --- ### Set up your trigger {#setup-trigger} -As mentioned, this app comes with preexisting functionality - it uses Functions, Workflows and a Trigger set up to kick things off. Let's run a command to initialize that Trigger via the CLI. +Your app comes with a sample [workflow](https://github.com/slack-samples/bolt-js-starter-template/blob/future/manifest/workflows/sample-workflow.js) that uses a [function](https://github.com/slack-samples/bolt-js-starter-template/blob/future/manifest/functions/sample-function.js). + +Kick off this workflow using the trigger defined in [this trigger configuration file](https://github.com/slack-samples/bolt-js-starter-template/blob/future/triggers/hello-world-trigger.json). We can run a command via the CLI to initialize this trigger so that we can run the workflow. First, make sure you're in the project directory in your command line: `cd my-app` -Then, run the following command to create a Trigger: +Then, run the following command to create a trigger: ``` -slack triggers create --trigger-def "triggers/hello-world-trigger.json" +slack trigger create --trigger-def "triggers/hello-world-trigger.json" ``` -The above command will create a trigger for the selected workspace. Make sure to select the workspace you want and that it is appended by `(dev)`. This will create a dev instance of your app. Once the trigger is successfully created, you should see an output like this: +The above command will create a link trigger belonging to the selected workspace. Make sure to select the workspace you want and that it is appended by `(dev)`. This will create a dev instance of your app. Once the trigger is successfully created, you should see an output like this: ``` ⚡ Trigger created @@ -111,28 +125,26 @@ The above command will create a trigger for the selected workspace. Make sure to Trigger Name: Sample Trigger URL: https://slack.com/shortcuts/[ID]/[Some ID] ``` -The provided URL will be what you use to run your Trigger. Copy this URL and save it somewhere; you'll need it for later. +Copy this URL and paste it in your selected workspace as a message in a public channel. We'll be using the trigger to kick off our workflow later. --- ### Run your app {#run-your-app} -Now that your app and Trigger are successfully created, let's try running it! - -Run `slack run` to start up the app. Executing `slack run` starts a local development server, syncing changes to your workspace's development version of your app. +Now that your app and trigger are successfully created, you can run `slack run` to start up the app. Executing `slack run` starts a local development server, syncing changes to your workspace's development version of your app. You'll be prompted to select a workspace to install the app to—select the development instance of your workspace (you'll know it's the development version because the name has the string `(dev)` appended). > 💡 If you don't see the workspace you'd like to use in the list, you can `CTRL + C` out of the `slack run` command and run `slack auth login`. This will allow you to authenticate in your desired workspace to have it show up in the list for `slack run`. -Once the app is successfully run, you'll see output in your Terminal to indicate it's running, similar to what you would see with any other Bolt for JavaScript app. You can search for the `⚡️ Bolt app is running! ⚡️` message to make sure that your app has successfully started up. +You'll see output in your Terminal to indicate it's running, similar to what you would see with any other Bolt for JavaScript app. You can search for the `⚡️ Bolt app is running! ⚡️` message to make sure that your app has successfully started up. ### Trigger your app's workflow {#trigger-workflow} -With your app running, access your workspace and paste the URL from the Trigger you created in the previous step into a message in a public channel. +With your app running, access your workspace and navigate to the message you sent containing the link trigger URL in [this previous step](/bolt-js/future/getting-started#setup-trigger). -> 💡 App Triggers are automatically saved as a channel bookmark under "Workflows" for easy access. +> 💡 App triggers are automatically saved as a channel bookmark under "Workflows" for easy access. -Send the message and click the "Run" button that appears. A modal will appear prompting you to enter information to greet someone in your Slack workspace. Fill out the requested information. +Click the "Run" button that appears on the message. A modal will appear prompting you to enter information to greet someone in your Slack workspace. Fill out the requested information. ![Hello World modal](../assets/hello-world-modal.png "Hello World modal") @@ -145,5 +157,7 @@ The full app flow can be seen here: ### Next steps {#next-steps} -Now we have a working instance of a next-generation app in your workspace and you've seen it in action! You can explore on your own and dive into the code yourself here or continue your learning journey by diving into [App Manifests](/bolt-js/future/app-manifests) or looking into adding more [Functions](/bolt-js/future/built-in-functions), [Workflows](/bolt-js/future/workflows), and [Triggers]() to your app! +Now we have a working instance of a next-generation app in your workspace and you've seen it in action! You can explore on your own and dive into the code yourself [here](https://github.com/slack-samples/bolt-js-starter-template/tree/future) or continue your learning journey by diving into [app manifests](/bolt-js/future/app-manifests) or looking into adding more [functions](/bolt-js/future/built-in-functions), [workflows](/bolt-js/future/workflows), and [triggers](/bolt-js/future/triggers) to your app! + +

Our next-generation platform is currently in beta. [Your feedback is most welcome](/bolt-js/future/feedback) - all feedback will help shape the future platform experience!

diff --git a/docs/_future/request_time_off_tutorial.md b/docs/_future/request_time_off_tutorial.md index 45252f425..7601133b9 100644 --- a/docs/_future/request_time_off_tutorial.md +++ b/docs/_future/request_time_off_tutorial.md @@ -60,11 +60,11 @@ You can now explore the `my-app` directory! --- ### Set up your trigger {#setup-trigger} -This app comes with preexisting functionality - Functions, Workflows and a Trigger set up to kick things off. Let's run a command to initialize that Trigger via the CLI. +This app comes with preexisting functionality - functions, workflows and a trigger set up to kick things off. Let's run a command to initialize that trigger via the CLI. First, make sure you're in the project directory in your command line: `cd my-app` -Then, run the following command to create a Trigger: +Then, run the following command to create a trigger: ``` slack triggers create --trigger-def "triggers/link-shortcut.json" ``` @@ -78,12 +78,12 @@ The above command will create a trigger for the selected workspace. Make sure to Trigger Name: Take Your Time URL: https://slack.com/shortcuts/[ID]/[Some ID] ``` -The provided URL will be what you use to run your Trigger. Copy this URL and save it somewhere; you'll need it for later. +The provided URL will be what you use to run your trigger. Copy this URL and save it somewhere; you'll need it for later. --- ### Run your app {#run-your-app} -Now that your app and Trigger are successfully created, let's try running it! +Now that your app and trigger are successfully created, let's try running it! Run `slack run` to start up the app. Executing `slack run` starts a local development server, syncing changes to your workspace's development version of your app. @@ -94,9 +94,9 @@ You'll be prompted to select a workspace to install the app to—select the Once the app is successfully run, you'll see output in your Terminal to indicate it's running, similar to what you would see with any other Bolt for JavaScript app. You can search for the `⚡️ Bolt app is running! ⚡️` message to make sure that your app has successfully started up. ### Trigger your app's workflow {#trigger-workflow} -With your app running, access your workspace and paste the URL from the Trigger you created in the previous step into a message in a public channel. +With your app running, access your workspace and paste the URL from the trigger you created in the previous step into a message in a public channel. -> 💡 App Triggers are automatically saved as a channel bookmark under "Workflows" for easy access. +> 💡 App triggers are automatically saved as a channel bookmark under "Workflows" for easy access. Send the message and click the "Run" button that appears. A modal will appear prompting you to enter information to request time off. To test your app properly, we recommend entering your own Slack username in the "Manager" field. @@ -188,7 +188,7 @@ TimeOffWorkflow.addStep(ApprovalFunction, { This step passes in a custom `ApprovalFunction` as well as inputs from the form in the first workflow step: `manager`, `start_date`, and `end_date`. It also passes in the `employee` ID by using the `interactivity` property's `interactor` ID, which comes from the initial definition of the `TimeOffWorkflow`. -Once the function step is executed, that will be the end of the workflow! All remaining functionality, such as notifying the requester whether their request was approved or denied, will be executed using the `ApprovalFunction` and its related action handlers. The `ApprovalFunction` definition and implementation will be covered in the [Functions](#functions) section below. +Once the function step is executed, that will be the end of the workflow! All remaining functionality, such as notifying the requester whether their request was approved or denied, will be executed using the `ApprovalFunction` and its related action handlers. The `ApprovalFunction` definition and implementation will be covered in the [functions](#functions) section below. The final workflow file will look like this: ```js @@ -250,25 +250,25 @@ TimeOffWorkflow.addStep(ApprovalFunction, { module.exports = { TimeOffWorkflow }; ``` -To explore more about Workflows and dive into creating new ones, visit the guide [here](/bolt-js/future/workflows). +To explore more about workflows and dive into creating new ones, visit the guide [here](/bolt-js/future/workflows). --- -### Link Triggers {#link-triggers} +### Link triggers {#link-triggers} -All workflows are invoked by triggers. We used a Trigger Config file defined at `triggers/link-shortcut.json`, and a CLI command to initialize it for our app. The next-gen platform supports many different kinds of triggers, and for this application, we use a simple [link trigger](https://api.slack.com/future/triggers/link). +All workflows are invoked by triggers. We used a trigger config file defined at `triggers/link-shortcut.json`, and a CLI command to initialize it for our app. The next-gen platform supports many different kinds of triggers, and for this application, we use a simple [link trigger](https://api.slack.com/future/triggers/link). Try adding this URL as a bookmark to a channel or posting it in a message somewhere public! -To learn more about Triggers and create new ones, visit the guide [here](/bolt-js/future/triggers). +To learn more about triggers and create new ones, visit the guide [here](/bolt-js/future/triggers). --- ### Functions {#functions} -Functions are building blocks of automation that accept inputs, perform some calculations, and provide outputs. Functions are added as steps in [Workflows](/bolt-js/future/workflows). +Functions are building blocks of automation that accept inputs, perform some calculations, and provide outputs. Functions are added as steps in [workflows](/bolt-js/future/workflows). There are two types of functions: [built-in functions](/bolt-js/future/built-in-functions), which are Slack native actions defined in the Schema, such as sending messages, and [custom functions](/bolt-js/future/custom-functions), which are not built-in and are defined by the developer. -In the Request Time Off application, we use one custom function, `ApprovalFunction`, which we passed into our Time Off Workflow as the second step after a requester submits time off information. At this point, our custom function will take that information and then send it to the manager to approve or deny. +In the Request Time Off application, we use one custom function, `ApprovalFunction`, which we passed into our Time Off workflow as the second step after a requester submits time off information. At this point, our custom function will take that information and then send it to the manager to approve or deny. Our `ApprovalFunction` is defined in `manifest/functions/approval.js`. Custom functions are defined using `DefineFunction`. ```js @@ -438,7 +438,7 @@ The full `request-approval.js` function will look like this: // listeners/functions/request-approval.js const { SlackFunction } = require('@slack/bolt'); -// Get our Approval Function from the manifest! +// Get our Approval function from the manifest! const { ApprovalFunction } = require('../../manifest/functions/approval'); // Here is the work we want to do! @@ -506,7 +506,7 @@ const notifyApprover = async ({ event, client, complete }) => { } }; -// Let's register a new Slack Function with notifyApprover as its handler +// Let's register a new Slack function with notifyApprover as its handler const requestApprovalFunc = new SlackFunction(ApprovalFunction.id, notifyApprover); // Get our action handlers @@ -556,7 +556,7 @@ Once this has been added in, when submitting a new time off request within your [Modals](https://api.slack.com/block-kit/surfaces/modals) can be created by calling the `views.open` method. The method requires you to pass a valid [view payload](https://api.slack.com/reference/block-kit/views). -To open or update a modal from a Slack Function [interactivity handler](https://api.slack.com/future/view-events), you will also need to pass the `interactivity_pointer` within the `interactivity` object you received from your event payload in your `views.open` method. +To open or update a modal from a Slack function [interactivity handler](https://api.slack.com/future/view-events), you will also need to pass the `interactivity_pointer` within the `interactivity` object you received from your event payload in your `views.open` method. To get started with creating a modal, add a new [Action](#action) that will be triggered when the "Open Modal" button is selected. Create a new file in `listeners/functions/actions` called `open-modal-action.js`: ```js @@ -668,4 +668,4 @@ By adding the `.view()` handler, you'll now be able to execute its logic when su --- ### Conclusion {#conclusion} -Congratulations on setting up your next-generation Request Time Off app! 🎉 Now that you understand its inner workings and have added in your own additional button that launches a modal, you can work on adding more to the application or jump on the learning track and start reading about [App Manifests](/bolt-js/future/app-manifests). +Congratulations on setting up your next-generation Request Time Off app! 🎉 Now that you understand its inner workings and have added in your own additional button that launches a modal, you can work on adding more to the application or jump on the learning track and start reading about [app manifests](/bolt-js/future/app-manifests). diff --git a/docs/_future/setup_existing_app.md b/docs/_future/setup_existing_app.md index c94229c68..00d88e4c7 100644 --- a/docs/_future/setup_existing_app.md +++ b/docs/_future/setup_existing_app.md @@ -54,11 +54,11 @@ module.exports = Manifest({ }); ``` -

`runOnSlack` is a required property of the manifest if you intend to use next-generation platform features - Functions, Workflows, Triggers. +

`runOnSlack` is a required property of the manifest if you intend to use next-generation platform features - functions, workflows, triggers. It means that your app will run on your own hosting solution and not on Slack and currently must be set to `false`

-Bolt will handle merging properties defined in this `Manifest()` and in any `manifest.json` in the project, but we encourage you to begin to migrate other features into code. Check out our more detailed guide on [App Manifests](/bolt-js/future/app-manifests). +Bolt will handle merging properties defined in this `Manifest()` and in any `manifest.json` in the project, but we encourage you to begin to migrate other features into code. Check out our more detailed guide on [app manifests](/bolt-js/future/app-manifests). --- @@ -91,12 +91,12 @@ Run the Slack CLI command `slack run` to start your app in local development. The CLI will create and install a new development app for you with its own App ID, allowing you to keep your testing changes separate from your production App). It will also start your app in local development mode (SocketMode) and turn logging on. -Now you're ready to start adding [Functions](/bolt-js/future/built-in-functions) and [Workflows](/bolt-js/future/workflows) to your app! +Now you're ready to start adding [functions](/bolt-js/future/built-in-functions) and [workflows](/bolt-js/future/workflows) to your app! --- ### Updating your app configuration {#update-app} -You have probably made changes to your app’s manifest (adding a Function or a Workflow, for example). To sync your production app’s configuration with the changes you’ve made in development: +You have probably made changes to your app’s manifest (adding a function or a workflow, for example). To sync your production app’s configuration with the changes you’ve made in development: * Authenticate the Slack CLI with your desired production workspace using `slack login`. * Head over to `./slack/apps.json` and make sure an entry exists for your workspace with the current `app_id` and `team_id` of the workspace. @@ -119,4 +119,4 @@ You have probably made changes to your app’s manifest (adding a Function or a --- ### Conclusion {#conclusion} -Congratulations on migrating your app to the your next-generation Slack Platform! 🎉 You can continue your journey by learning about [App Manifests](/bolt-js/future/app-manifests) or looking into adding [Functions](/bolt-js/future/built-in-functions) and [Workflows](/bolt-js/future/workflows) to your app! \ No newline at end of file +Congratulations on migrating your app to the your next-generation Slack Platform! 🎉 You can continue your journey by learning about [app manifests](/bolt-js/future/app-manifests) or looking into adding [functions](/bolt-js/future/built-in-functions) and [workflows](/bolt-js/future/workflows) to your app! \ No newline at end of file diff --git a/docs/_future/triggers.md b/docs/_future/triggers.md index b61c47a43..6f999701f 100644 --- a/docs/_future/triggers.md +++ b/docs/_future/triggers.md @@ -11,39 +11,39 @@ permalink: /future/triggers
Triggers are but one of the three building blocks that make up next-generation Slack apps. You will encounter all three as you walk the path of building your Slack app: -1. Functions are what define the actions of your app -2. Workflows are made up of Functions -3. Triggers are how Workflows are executed (⬅️ you are here) +1. Functions define the actions of your app +2. Workflows group functions into ordered steps +3. Triggers invoke workflows (⬅️ you are here) -Since Triggers kick off Workflows, you need to have a Workflow before you can create a Trigger. Acquaint yourself with the [documentation on Workflows](/bolt-js/future/workflows), then head back here. We'll wait! +Since triggers kick off workflows, you need to have a workflow before you can create a trigger. Acquaint yourself with the [documentation on workflows](/bolt-js/future/workflows), then head back here. We'll wait! -Once you've created a Workflow, you can dive into the guide below! +Once you've created a workflow, you can dive into the guide below!
--- -### Create a Trigger {#create} +### Create a trigger {#create} -Triggers can be added to Workflows in two ways: +Triggers can be added to workflows in two ways: -* [**You can add Triggers with the CLI.**](#create_cli) These static Triggers are created only once. You create them with the Slack CLI, attach them to your app's Workflow, and that's that. +* [**You can add triggers with the CLI.**](#create_cli) These static triggers are created only once. You create them with the Slack CLI, attach them to your app's workflow, and that's that. -* [**You can add Triggers at runtime.**](#create_runtime) These dynamic Triggers are created at any step of a Workflow so they can incorporate data acquired from other Workflow steps. +* [**You can add triggers at runtime.**](#create_runtime) These dynamic triggers are created at any step of a workflow so they can incorporate data acquired from other workflow steps. -#### Create a Trigger with the CLI {#create_cli} +#### Create a trigger with the CLI {#create_cli} -**1. Create a Trigger File** +**1. Create a trigger file** -Triggers created with the CLI are designed using Trigger Files. The Trigger File you create will supply the information about how you want your Trigger to work. **For Bolt for JavaScript apps, you will need to create JSON trigger files.** +Triggers created with the CLI are designed using trigger files. The trigger file you create will supply the information about how you want your trigger to work. **For Bolt for JavaScript apps, you will need to create JSON trigger files.** -The specifics of the Trigger File's structure will depend on what [type of Trigger](#types) you want to use. +The specifics of the trigger file's structure will depend on what [type of trigger](#types) you want to use. -The Hello World app from the Bolt for JavaScript starter template uses a Link Trigger, which is one of several [Trigger types](#types). You can view its Trigger File [here](https://github.com/slack-samples/bolt-js-starter-template/blob/future/triggers/hello-world-trigger.json). +The Hello World app from the Bolt for JavaScript starter template uses a link trigger, which is one of several [trigger types](#types). You can view its trigger file [here](https://github.com/slack-samples/bolt-js-starter-template/blob/future/triggers/hello-world-trigger.json). **2. Run the** `trigger create` **command** -Use the `trigger create` command to create your desired Trigger by pointing to a Trigger File. +Use the `trigger create` command to create your desired trigger by pointing to a trigger file. ```bash slack trigger create --trigger-def "path/to/trigger.json" @@ -54,13 +54,13 @@ slack trigger create --trigger-def "path/to/trigger.json"

**Slack CLI built-in documentation**
Use `slack trigger --help` to easily access information on the `trigger` command's flags and subcommands.

-#### Create a Trigger at runtime {#create_runtime} +#### Create a trigger at runtime {#create_runtime} -The logic of a runtime Trigger lies within a Function's code. The specific payload is dependent on the [type of Trigger](#types) you use. +The logic of a runtime trigger lies within a function's code. The specific payload is dependent on the [type of trigger](#types) you use. -Within your `manifest/functions` folder, you'll have the Functions that are the steps making up your Workflow. Within this folder is where you can create a Trigger within the relevant `.js` file. +Within your `manifest/functions` folder, you'll have the functions that are the steps making up your workflow. Within this folder is where you can create a trigger within the relevant `.js` file. -The `create` method for runtime Triggers takes the form of `client.workflows.triggers.create()`. Within that method you can leverage `inputs` acquired in previous steps (i.e. with Functions) within the Workflow. +The `create` method for runtime triggers takes the form of `client.workflows.triggers.create()`. Within that method you can leverage `inputs` acquired in previous steps (i.e. with functions) within the workflow. ```js const triggerResponse = await client.workflows.triggers.create({ @@ -75,28 +75,28 @@ const triggerResponse = await client.workflows.triggers.create({ }); ``` -The response will have a property called `ok`. If `true`, then the Trigger was created, and the `trigger` property will be populated. +The response will have a property called `ok`. If `true`, then the trigger was created, and the `trigger` property will be populated. -Your response will include a `trigger.id`; be sure to store it! You will use that to `update` or `delete` the Trigger if need be. +Your response will include a `trigger.id`; be sure to store it! You will use that to `update` or `delete` the trigger if need be. -#### Development and production Triggers +#### Development and production triggers -The Triggers you create when you're running your app locally in a development environment (with the `slack run` command) will not work when you [deploy your app](/bolt-js/future/deploy-your-app). You'll need to `create` any Triggers again with the CLI. +The triggers you create when you're running your app locally in a development environment (with the `slack run` command) will not work when you [deploy your app](/bolt-js/future/deploy-your-app). You'll need to `create` any triggers again with the CLI. --- -### Update a Trigger {#update} +### Update a trigger {#update} -Make an update to a preexisting Trigger by using the `slack trigger update` command. Provide the same payload you used to create the trigger *in its entirety*, in addition to the Trigger ID. +Make an update to a preexisting trigger by using the `slack trigger update` command. Provide the same payload you used to create the trigger *in its entirety*, in addition to the trigger ID. ```bash slack trigger update --trigger-id Ft123ABC --trigger-def "path/to/trigger.json" ``` --- -### Delete a Trigger {#delete} +### Delete a trigger {#delete} -You can delete a Trigger with the `slack trigger delete` command. +You can delete a trigger with the `slack trigger delete` command. ```bash slack trigger delete --trigger-id FtABC123 @@ -105,22 +105,22 @@ slack trigger delete --trigger-id FtABC123 ### Trigger types {#types} -There are four types of Triggers, each one having its own specific implementation. To learn more about each trigger, visit the linked pages below. +There are four types of triggers, each one having its own specific implementation. To learn more about each trigger, visit the linked pages below. | Trigger Type | Use case | |----------------------------------|---------------------------------------------------------------| -| [Link Triggers](https://api.slack.com/future/triggers/link) | Invoke a Workflow from anywhere in Slack | -| [Scheduled Triggers](https://api.slack.com/future/triggers/scheduled) | Invoke a Workflow at specific time intervals | -| [Event Triggers](https://api.slack.com/future/triggers/event) | Invoke a Workflow when a specific event happens in Slack | -| [Webhook Triggers](https://api.slack.com/future/triggers/webhook) | Invoke a Workflow when a specific URL receives a POST request | +| [Link triggers](https://api.slack.com/future/triggers/link) | Invoke a workflow from anywhere in Slack | +| [Scheduled triggers](https://api.slack.com/future/triggers/scheduled) | Invoke a workflow at specific time intervals | +| [Event triggers](https://api.slack.com/future/triggers/event) | Invoke a workflow when a specific event happens in Slack | +| [Webhook triggers](https://api.slack.com/future/triggers/webhook) | Invoke a workflow when a specific URL receives a POST request | --- ### Manage access {#manage-access} -A newly created Trigger will only be accessible to others inside a workspace once its creator has granted access. +A newly created trigger will only be accessible to others inside a workspace once its creator has granted access. -To manage what user (or many users) have access to run your Triggers, you'll use the `slack trigger access` command. +To manage what user (or many users) have access to run your triggers, you'll use the `slack trigger access` command. To learn more about this, visit the guide [here](https://api.slack.com/future/triggers#manage-access). @@ -128,6 +128,6 @@ To learn more about this, visit the guide [here](https://api.slack.com/future/tr ### Conclusion {#conclusion} -And that's the end of our triumphant trek learning about Triggers! +And that's the end of our triumphant trek learning about triggers! -If you want to see Triggers in action with their pals, the Function and the Workflow, check out our sample [Hello World](https://github.com/slack-samples/bolt-js-starter-template/tree/future) app. For a more complex example, you can take a look at our [Request Time Off](https://github.com/slack-samples/bolt-js-request-time-off) app and its end-to-end [tutorial](/bolt-js/future/request-time-off-tutorial). +If you want to see triggers in action with their pals, the function and the workflow, check out our sample [Hello World](https://github.com/slack-samples/bolt-js-starter-template/tree/future) app. For a more complex example, you can take a look at our [Request Time Off](https://github.com/slack-samples/bolt-js-request-time-off) app and its end-to-end [tutorial](/bolt-js/future/request-time-off-tutorial). diff --git a/docs/_future/workflows.md b/docs/_future/workflows.md index cd9d42745..89e9d3e01 100644 --- a/docs/_future/workflows.md +++ b/docs/_future/workflows.md @@ -9,14 +9,14 @@ permalink: /future/workflows # Workflows BETA
-A Workflow is a set of processing steps that are executed in order. Each step in a Workflow is either a [custom function](/bolt-js/future/custom-functions) that you define or a [built-in function](/bolt-js/future/built-in-functions) that's part of `slack`. +A workflow is a set of processing steps that are executed in order. Each step in a workflow is either a [custom function](/bolt-js/future/custom-functions) that you define or a [built-in function](/bolt-js/future/built-in-functions) that's part of `slack`. Workflows can be configured to run without any user input, or they can [wait for input via form](https://api.slack.com/future/forms) before continuing.
--- -### Defining Workflows {#defining-workflows} +### Defining workflows {#defining-workflows} Workflows are defined in the `manifest/workflows` directory and implemented in your app's [manifest](/bolt-js/future/app-manifests). @@ -43,7 +43,7 @@ The `callback_id` is a unique string that identifies this particular component o | `input_parameters` | Optional input parameters, covered in ["Defining input parameters"](/bolt-js/future/workflows#defining-input-parameters) | `output_parameters` | An object which describes one or more output parameters that will be returned by your function. This object follows the exact same pattern as `input_parameters`: top-level properties of the object define output parameter names, with the property values being an object that further describes the type and description of individual output parameters. -Once you've defined your Workflow, you'll now have access to it's `addStep` method, which is how you can call Built-in and Custom functions. The `addStep` method takes two arguments: first, the function you want to call, and second, any inputs you want to pass to that function. We'll see examples of how to do both in the following sections. +Once you've defined your workflow, you'll now have access to it's `addStep` method, which is how you can call built-in and custom functions. The `addStep` method takes two arguments: first, the function you want to call, and second, any inputs you want to pass to that function. We'll see examples of how to do both in the following sections. ### Using built-in functions in a workflow {#workflow-builtin-functions} @@ -56,7 +56,7 @@ To use a [built-in function](/bolt-js/future/built-in-functions), like `SendMess const { Schema } = require('@slack/bolt'); ``` -#### 2. Call the function with your Workflow's `addStep` method: {#add-step} +#### 2. Call the function with your workflow's `addStep` method: {#add-step} ```javascript // Example: taking the string output from a function and passing it to SendMessage @@ -66,7 +66,7 @@ SayHelloWorkflow.addStep(Schema.slack.functions.SendMessage, { }); ``` -Here's an example of adding a step that calls a Built-in function: +Here's an example of adding a step that calls a built-in function: ```javascript SayHelloWorkflow.addStep(Schema.slack.functions.SendMessage, { channel_id: "C1234567", @@ -74,7 +74,7 @@ SayHelloWorkflow.addStep(Schema.slack.functions.SendMessage, { }); ``` -Here's an example of a step that calls a Custom function with a callback ID of `my_function_callback_id`: +Here's an example of a step that calls a custom function with a callback ID of `my_function_callback_id`: ```javascript SayHelloWorkflow.addStep("#/functions/my_function_callback_id", { some_input: 12345 @@ -106,9 +106,9 @@ module.exports = Manifest({ ### Using OpenForm in a workflow {#using-forms} -The only Built-in function that has an additional requirement is [`OpenForm`](https://api.slack.com/future/functions#open-a-form). When creating a Workflow that will have a step to open a form, your workflow needs to include a required `interactivity` input parameter and the call to `OpenForm` must be the **first** step in the Workflow. +The only built-in function that has an additional requirement is [`OpenForm`](https://api.slack.com/future/functions#open-a-form). When creating a workflow that will have a step to open a form, your workflow needs to include a required `interactivity` input parameter and the call to `OpenForm` must be the **first** step in the workflow. -Here's an example of a basic Workflow definition using `interactivity`: +Here's an example of a basic workflow definition using `interactivity`: ```javascript const SayHelloWorkflow = DefineWorkflow({ @@ -133,13 +133,13 @@ Visit [this guide](https://api.slack.com/future/forms) for more details and code To use a [custom function](/bolt-js/built-on-slack/custom-functions) that you define: -#### 1. Import the function in your workflow file where you are defining the Workflow: {#import} +#### 1. Import the function in your workflow file where you are defining the workflow: {#import} ```javascript import { SomeFunction } from "../functions/some_function"; ``` -#### 2. Call your Function, storing its output in a variable. Here you may also pass input parameters from the Workflow into the Function itself: {#call-function} +#### 2. Call your function, storing its output in a variable. Here you may also pass input parameters from the workflow into the function itself: {#call-function} ```javascript import { SomeFunction } from "../functions/some_function"; @@ -171,13 +171,13 @@ const myFunctionResult = SomeWorkflow.addStep(SomeFunction, { module.exports = { SomeWorkflow }; ``` -#### 3. Use your Function in follow-on steps. For example: {#use-function} +#### 3. Use your function in follow-on steps. For example: {#use-function} ```javascript // Example: taking the string output from a function and passing it to SendMessage SomeWorkflow.addStep(Schema.slack.functions.SendMessage, { channel_id: SomeWorkflow.inputs.channelId, - message: myFunctionResult.outputs.exampleOutput, // This comes from your Function definition + message: myFunctionResult.outputs.exampleOutput, // This comes from your function definition }); ``` @@ -214,7 +214,7 @@ module.exports = { SayHelloWorkflow }; ``` -Below in the Manifest, the `SayHelloWorkflow` is imported and passed in: +Below in the manifest, the `SayHelloWorkflow` is imported and passed in: ```javascript // manifest/manifest.js const { Manifest } = require('@slack/bolt'); @@ -228,17 +228,17 @@ module.exports = Manifest({ }); ``` -The above example uses the [Built-in function `SendDm`](https://api.slack.com/future/functions) to send a direct message. There are many other Built-in functions available to use, and you can also include [Custom functions](/bolt-js/future/custom-functions) that you define. +The above example uses the [built-in function `SendDm`](https://api.slack.com/future/functions) to send a direct message. There are many other built-in functions available to use, and you can also include [custom functions](/bolt-js/future/custom-functions) that you define. -To invoke a Workflow, you need to create a [Trigger](/bolt-js/future/triggers). +To invoke a workflow, you need to create a [trigger](/bolt-js/future/triggers). --- ### Defining input parameters {#defining-input-parameters} -Workflows can pass information into both Functions and other Workflows that are part of its Workflow steps. To do this, we define what information we want to bring into the Workflow via its `input_parameters` property. +Workflows can pass information into both functions and other workflows that are part of its workflow steps. To do this, we define what information we want to bring into the workflow via its `input_parameters` property. -A Workflow's `input_parameters` property has two sub-properties: `required`, which is how you can ensure that a Workflow only executes if specific input parameters are provided, and `properties`, where you can list the specific parameters that your Workflow accounts for. Any [Built-in type](https://api.slack.com/future/types) or [Custom type](https://api.slack.com/future/types/custom) can be used. +A workflow's `input_parameters` property has two sub-properties: `required`, which is how you can ensure that a workflow only executes if specific input parameters are provided, and `properties`, where you can list the specific parameters that your workflow accounts for. Any [built-in type](https://api.slack.com/future/types) or [custom type](https://api.slack.com/future/types/custom) can be used. #### Adding an input parameter to a workflow {#workflow-adding-input-parameters} @@ -301,7 +301,7 @@ const SomeWorkflow = DefineWorkflow({ }); ``` -If a Workflow is invoked and the required input parameters are not provided, the Workflow will not execute. +If a workflow is invoked and the required input parameters are not provided, the workflow will not execute. > 🗣 Got 2 minutes to provide some feedback? Fill out our [Developer Survey](/bolt-js/future/feedback) and let us know what we're doing well—and what you'd like to see us improve. @@ -309,4 +309,4 @@ If a Workflow is invoked and the required input parameters are not provided, the ### Onward -Once you have defined a Workflow, you're ready to [create a Trigger](/bolt-js/future/triggers) that invokes it. +Once you have defined a workflow, you're ready to [create a trigger](/bolt-js/future/triggers) that invokes it. diff --git a/docs/_steps/workflow_steps_overview.md b/docs/_steps/workflow_steps_overview.md index 33d49a2ab..778f41142 100644 --- a/docs/_steps/workflow_steps_overview.md +++ b/docs/_steps/workflow_steps_overview.md @@ -7,7 +7,7 @@ order: 1
-**⚠️ Workflow Steps from Apps are a legacy feature, not to be confused with Workflows that are part of the next-gen beta. They are not interchangeable features. We encourage those who are currently publishing Workflow Steps from apps to join the beta - you can learn more about getting started with it [here](/bolt-js/future/getting-started).** +**⚠️ Workflow Steps from Apps are a legacy feature, not to be confused with workflows that are part of the next-gen beta. They are not interchangeable features. We encourage those who are currently publishing Workflow Steps from apps to join the beta - you can learn more about getting started with it [here](/bolt-js/future/getting-started).** Workflow Steps from apps allow your app to create and process custom workflow steps that users can add using [Workflow Builder](https://api.slack.com/workflows).