Merge pull request #2149 from slackapi/docs-custom-functions

docs: replacement steps from apps with custom functions

docs/_config.yml

@@ -13,6 +13,8 @@ collections:
     output: false
   advanced:
     output: false
+  functions:
+    output: false
   steps:
     output: false
   deployments:
@@ -38,10 +40,12 @@ t:
     advanced: Advanced concepts
     start: Getting started
     reference: Reference
+    functions: Custom functions
     steps: Workflow steps
     deployments: Deployments
     contribute: Contributing
     deprecated: Deprecated
+    beta: Beta
   ja-jp:
     basic: 基本的な概念
     advanced: 応用コンセプト
@@ -52,6 +56,7 @@ t:
     reference: リファレンス
     contribute: 貢献
     deprecated: 非推奨
+    beta: Beta
 
 # Metadata
 repo_name: bolt-js

docs/_functions/creating.md

@@ -0,0 +1,20 @@
+---
+title: Creating custom functions
+lang: en
+slug: creating-custom-functions
+order: 1
+---
+
+<div class="section-content">
+Custom functions allow your app to create and process workflow steps that users can add in [Workflow Builder](https://api.slack.com/workflows). 
+
+We recommend using custom functions as a replacement for the [deprecated Workflow Steps from Apps](#steps).
+
+A custom function requires two components:
+
+* [A function definition in the app’s manifest](#defining-custom-functions)
+* [A listener to handle the function execution event](#listening-to-custom-functions)
+
+Read more about custom functions in the [Slack API documentation](https://api.slack.com/automation/functions/custom-bolt).
+
+</div>

docs/_functions/defining.md

@@ -0,0 +1,44 @@
+---
+title: Defining custom functions
+lang: en
+slug: defining-custom-functions
+order: 2
+---
+
+<div class="section-content">
+
+To make a custom function available for use in Workflow Builder, the app’s manifest must contain a function definition. 
+
+A function’s definition contains information about the function, including its `callback_id`, `input_parameters`, `output_parameters`, as well as display information.
+
+To learn more about defining a function, see the [Slack API documentation](https://api.slack.com/automation/functions/custom-bolt#define-function).
+
+</div>
+
+```json
+"functions": {
+    "sample_function": {
+        "title": "Sample function",
+        "description": "Runs sample function",
+        "input_parameters": {
+            "user_id": {
+                "type": "slack#/types/user_id",
+                "title": "User",
+                "description": "Message recipient",
+                "is_required": true,
+                "hint": "Select a user in the workspace",
+                "name": "user_id"
+            }
+        },
+        "output_parameters": {
+            "user_id": {
+                "type": "slack#/types/user_id",
+                "title": "User",
+                "description": "User that completed the function",
+                "is_required": true,
+                "name": "user_id"
+            }
+        }
+    }
+}
+```

docs/_functions/listening.md

@@ -0,0 +1,32 @@
+---
+title: Listening to custom function executions
+lang: en
+slug: listening-to-custom-functions
+order: 3
+---
+
+<div class="section-content"> 
+
+When your custom function is executed as a step in a workflow, your app will receive a [`function_executed`](https://api.slack.com/events/function_executed) event. The callback provided to the `function()` method will be run when this event is received.
+
+The callback is where you can access `inputs`, make third-party API calls, or set the output values that will be available to subsequent workflow steps by mapping values to the `outputs` object.
+
+Your app can call `complete()` to indicate that the function’s execution was successful, or `fail()` to signal that the function failed to complete.
+
+To learn more about listening to custom function executions, see the [Slack API documentation](https://api.slack.com/automation/functions/custom-bolt#listener).
+
+
+</div>
+
+```js
+app.function('sample_function', async ({ client, inputs, fail }) => {
+  try {
+    const { user_id } = inputs;
+    await complete({ outputs: { user_id } });
+  } catch (error) {
+    console.error(error);
+    fail({ error: `Failed to handle a function request: ${error}` });
+  }
+});
+```
+

docs/_functions/responding.md

@@ -0,0 +1,24 @@
+---
+title: Responding to interactivity
+lang: en
+slug: responding-to-interactivity
+order: 4
+---
+
+<div class="section-content">
+
+Interactive elements provided to the user, via message or modal, from within the `function()` method’s callback are associated with that unique `function_executed` event. This association allows for the completion of functions at a later time, like once the user has clicked a button.
+
+Incoming actions that are associated with a function have the same `inputs`, `complete`, and `fail` utilities as offered by the `function()` method.
+
+To learn more about responding to interactivity, see the [Slack API documentation](https://api.slack.com/automation/functions/custom-bolt#interactivity).
+
+</div>
+
+```js
+// If associated with a function, function-specific utilities are made available 
+app.action('approve_button', async ({ complete, fail }) => {
+  // Signal the function has completed once the button is clicked  
+  await complete({ outputs: { message: 'Request approved 👍' } });
+});
+```

docs/_includes/sidebar.html

@@ -64,11 +64,26 @@
     </ul>
   {% endif %}
 
+  <ul class="sidebar-section">
+    <a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#functions"
+      ><li class="title">{{ site.t[page.lang].functions }}
+      <span class="label-warning">
+        {{ site.t[page.lang].beta }}
+      </span>
+    </li></a>
+    {% assign functions_sections = site.functions | sort: "order" | where: "lang", page.lang %} {% for section in functions_sections
+    %}
+    <a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#{{ section.slug }}">
+      <li>{{section.title}}</li>
+    </a>
+    {% endfor %}
+  </ul>
+
   <ul class="sidebar-section">
     <a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#steps">
       <li class="title">
         {{ site.t[page.lang].steps }}
-        <span class="label-deprecated">
+        <span class="label-warning">
           {{ site.t[page.lang].deprecated }}
         </span>
       </li>

docs/_layouts/default.html

@@ -44,13 +44,28 @@ <h3 id="{{section.slug}}">{{ section.title }}</h3>
           {% endfor %}
         </div>
 
+        <div id="functions">
+          {% assign functions_sections = site.functions | sort: "order" | where: "lang", page.lang %} {% for section in
+          functions_sections %}
+          <div class="section-wrapper">
+            <h3 id="{{section.slug}}">{{ section.title }}
+              <span class="label-warning">
+                {{ site.t[page.lang].beta }}
+              </span>
+            </h3>
+            {{ section.content | markdownify }}
+            <hr />
+          </div>
+          {% endfor %}
+        </div>
+
         <div id="steps">
           {% assign workflow_steps = site.steps | sort: "order" | where: "lang", page.lang %} {% for section in
           workflow_steps %}
           <div class="section-wrapper">
             <h3 id="{{section.slug}}">
               {{ section.title }}
-              <span class="label-deprecated">
+              <span class="label-warning">
                 {{ site.t[page.lang].deprecated }}
               </span>
             </h3>

docs/_steps/workflow_steps_overview.md

@@ -7,9 +7,15 @@ order: 1
 
 <div class="section-content">
 
-**⚠️ Workflow Steps from Apps are a deprecated feature, not to be confused with workflows that are part of the next generation Slack platform. They are not interchangeable features. We encourage those who are currently publishing Workflow Steps from apps to consider the new [automation features](https://api.slack.com/automation) and [custom steps for bolt](https://api.slack.com/automation/functions/custom-bolt).**
+**⚠️ Workflow Steps from Apps are a deprecated feature.**
 
-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).
+**Workflow Steps from Apps are different than, and not interchangable with, Slack automation workflows. We encourage those who are currently publishing Workflow Steps from Apps to consider the new [Slack automation features](https://api.slack.com/automation), such as [custom functions for Bolt](#functions).**
+
+**Please [read the Slack API changelog entry](https://api.slack.com/changelog/2023-08-workflow-steps-from-apps-step-back) for more information.**
+
+---
+
+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).
 
 A workflow step is made up of three distinct user events:
 
@@ -19,6 +25,6 @@ A workflow step is made up of three distinct user events:
 
 All three events must be handled for a workflow step to function.
 
-Read more about workflow steps from apps in the [API documentation](https://api.slack.com/workflows/steps).
+Read more about Workflow Steps from Apps in the [API documentation](https://api.slack.com/legacy/workflows/steps).
 
 </div>

docs/assets/style.css

@@ -105,7 +105,7 @@ body {
   font-weight: 600;
 }
 
-.panel .sidebar-content ul.sidebar-section .label-deprecated {
+.panel .sidebar-content ul.sidebar-section .label-warning {
   line-height: 1em;
   vertical-align: middle;
   color: var(--white);
@@ -234,7 +234,7 @@ body {
   padding-bottom: 1em;
 }
 
-.tutorial .label-deprecated {
+.label-warning {
   line-height: 1em;
   vertical-align: middle;
   color: var(--white);