docs: document custom step usage

README.md

@@ -45,29 +45,33 @@ Apps typically react to a collection of incoming events, which can correspond [E
 request, there's a method to build a listener function.
 
 ```js
+// Listen for an action from a Block Kit element (buttons, select menus, date pickers, etc)
+app.action(actionId, fn);
+
+// Listen for dialog submissions
+app.action({ callback_id: callbackId }, fn);
+
+// Listen for slash commands
+app.command(commandName, fn);
+
 // Listen for an event from the Events API
 app.event(eventType, fn);
 
+// Listen for a custom step execution from a workflow
+app.function(callbackId, fn)
+
 // Convenience method to listen to only `message` events using a string or RegExp
 app.message([pattern ,] fn);
 
-// Listen for an action from a Block Kit element (buttons, select menus, date pickers, etc)
-app.action(actionId, fn);
-
-// Listen for dialog submissions
-app.action({ callback_id: callbackId }, fn);
+// Listen for options requests (from select menus with an external data source)
+app.options(actionId, fn);
 
 // Listen for a global or message shortcuts
 app.shortcut(callbackId, fn);
 
-// Listen for slash commands
-app.command(commandName, fn);
-
 // Listen for view_submission modal events
 app.view(callbackId, fn);
 
-// Listen for options requests (from select menus with an external data source)
-app.options(actionId, fn);
 ```
 
 ## Making things happen
@@ -83,6 +87,8 @@ Most of the app's functionality will be inside listener functions (the `fn` para
 | `respond` | Function that responds to an incoming event **if** it contains a `response_url` (actions, shortcuts, view submissions, and slash commands). `respond` returns a promise that resolves with the results of responding using the `response_url`.
 | `context` | Event context. This object contains data about the event and the app, such as the `botId`. Middleware can add additional context before the event is passed to listeners.
 | `body` | Object that contains the entire body of the request (superset of `payload`). Some accessory data is only available outside of the payload (such as `trigger_id` and `authorizations`).
+| `complete` | Function used to signal the successful completion of a custom step execution. This tells Slack to proceed with the next steps in the workflow. This argument is only available with the `.function` and `.action` listener when handling custom workflow step executions.
+| `fail` | Function used to signal that a custom step failed to complete. This tells Slack to stop the workflow execution. This argument is only available with the `.function` and `.action` listener when handling custom workflow step executions.
 
 
 The arguments are grouped into properties of one object, so that it's easier to pick just the ones your listener needs (using

docs/content/basic/custom-steps.md

@@ -0,0 +1,103 @@
+---
+title: Listening and responding to custom steps
+lang: en
+slug: /concepts/custom-steps
+---
+
+Your app can use the `function()` method to listen to incoming [custom step requests](https://api.slack.com/automation/functions/custom-bolt). Custom steps are used in Workflow Builder to build workflows. The method requires a step `callback_id` of type string. This `callback_id` must also be defined in your [Function](https://api.slack.com/concepts/manifests#functions) definition. Custom steps must be finalized using the `complete()` or `fail()` listener arguments to notify Slack that your app has processed the request.
+
+* `complete()` requires one argument: an `outputs` object. It completes your custom step **successfully** and provides an object containing the outputs of your custom step as per its definition.
+* `fail()` requires **one** argument: `error` of type string. It completes your custom step **unsuccessfully** and provides a message containing information regarding why your custom step failed.
+
+You can reference your custom step's inputs using the `inputs` listener argument.
+
+```js
+// This sample custom step formats an input and outputs it
+app.function('sample_custom_step', async ({ ack, inputs, complete, fail, logger }) => {
+  try {
+    await ack();
+    const { message } = inputs;
+
+    await complete({
+        outputs: { 
+            message: `:wave: You submitted the following message: \n\n>${message}` 
+        }
+    });
+  } catch (error) {
+    logger.error(error);
+    await fail({ error: `Failed to handle a function request: ${error}` });
+  }
+});
+```
+
+<details>
+  <summary>
+  Listening to custom step actions
+  </summary>
+  Your app can listen to user actions, like button clicks, created from `custom steps` using the `action` method.
+
+  Actions can be filtered on an `action_id` of type string or RegExp object. `action_id`s act as unique identifiers for interactive components on the Slack platform.
+
+  Your app can skip calling `complete()` or `fail()` in the `function()` listener if the custom step creates an `action` that waits for user interaction. However, in the `action()` method, your app must invoke `complete()` or `fail()` to notify Slack that the custom step has been processed.
+
+  You’ll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge that the request was received from Slack. This is discussed in the [acknowledging requests section](/concepts/acknowledge).
+
+```js
+/** This sample custom step posts a message with a button */
+app.function('sample_function', async ({ ack, client, inputs, fail, logger }) => {
+  try {
+    await ack();
+    const { user_id } = inputs;
+
+    await client.chat.postMessage({
+      channel: user_id,
+      text: 'Click the button to signal the function has completed',
+      blocks: [
+        {
+          type: 'section',
+          text: {
+            type: 'mrkdwn',
+            text: 'Click the button to signal the function has completed',
+          },
+          accessory: {
+            type: 'button',
+            text: {
+              type: 'plain_text',
+              text: 'Complete function',
+            },
+            action_id: 'sample_button',
+          },
+        },
+      ],
+    });
+  } catch (error) {
+    logger.error(error);
+    await fail({ error: `Failed to handle a function request: ${error}` });
+  }
+});
+
+/** Your listener will be called every time a block element with the action_id "sample_button" is triggered */
+app.action('sample_button', async ({ ack, body, client, complete, fail, logger }) => {
+  try {
+    await ack();
+
+    const { channel, message, user } = body;
+    // Functions should be marked as successfully completed using `complete` or
+    // as having failed using `fail`, else they'll remain in an 'In progress' state.
+    await complete({ outputs: { user_id: user.id } });
+
+    await client.chat.update({
+      channel: channel.id,
+      ts: message.ts,
+      text: 'Function completed successfully!',
+    });
+  } catch (error) {
+    logger.error(error);
+    await fail({ error: `Failed to handle a function request: ${error}` });
+  }
+});
+```
+
+Learn more about responding to interactivity, see the [Slack API documentation](https://api.slack.com/automation/functions/custom-bolt#interactivity).
+
+</details>

docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/basic/custom-steps.md

@@ -0,0 +1,101 @@
+---
+title: Listening and responding to custom steps
+lang: ja-jp
+slug: /concepts/custom-steps
+---
+
+Your app can use the `function()` method to listen to incoming [custom step requests](https://api.slack.com/automation/functions/custom-bolt). The method requires a step `callback_id` of type string. This `callback_id` must also be defined in your [Function](https://api.slack.com/concepts/manifests#functions) definition. Custom steps must be finalized using the `complete()` or `fail()` listener arguments to notify Slack that your app has processed the request.
+
+* `complete()` requires one argument: an `outputs` object. It completes your custom step **successfully** and provides an object containing the outputs of your custom step as per its definition.
+* `fail()` requires **one** argument: `error` of type string. It completes your custom step **unsuccessfully** and provides a message containing information regarding why your custom step failed.
+
+You can reference your custom step's inputs using the `inputs` listener argument.
+
+```js
+// This sample custom step formats an input and outputs it
+app.function('sample_custom_step', async ({ ack, inputs, complete, fail, logger }) => {
+  try {
+    await ack();
+    const { message } = inputs;
+
+    await complete({
+        outputs: { 
+            message: `:wave: You submitted the following message: \n\n>${message}` 
+        }
+    });
+  } catch (error) {
+    logger.error(error);
+    await fail({ error: `Failed to handle a function request: ${error}` });
+  }
+});
+```
+
+<details>
+  <summary>
+  Listening to custom step actions
+  </summary>
+  Your app can listen to user actions, like button clicks, created from `custom steps` using the `action` method.
+
+  Actions can be filtered on an `action_id` of type string or RegExp object. `action_id`s act as unique identifiers for interactive components on the Slack platform.
+
+  Your app can skip calling `complete()` or `fail()` in the `function()` listener if the custom step creates an `action` that waits for user interaction. However, in the `action()` method, your app must invoke `complete()` or `fail()` to notify Slack that the custom step has been processed.
+
+  You’ll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge that the request was received from Slack. This is discussed in the [acknowledging requests section](/concepts/acknowledge).
+
+```js
+/** This sample custom step posts a message with a button */
+app.function('sample_function', async ({ ack, client, inputs, fail, logger }) => {
+  try {
+    await ack();
+    const { user_id } = inputs;
+
+    await client.chat.postMessage({
+      channel: user_id,
+      text: 'Click the button to signal the function has completed',
+      blocks: [
+        {
+          type: 'section',
+          text: {
+            type: 'mrkdwn',
+            text: 'Click the button to signal the function has completed',
+          },
+          accessory: {
+            type: 'button',
+            text: {
+              type: 'plain_text',
+              text: 'Complete function',
+            },
+            action_id: 'sample_button',
+          },
+        },
+      ],
+    });
+  } catch (error) {
+    logger.error(error);
+    await fail({ error: `Failed to handle a function request: ${error}` });
+  }
+});
+
+/** Your listener will be called every time a block element with the action_id "sample_button" is triggered */
+app.action('sample_button', async ({ ack, body, client, complete, fail, logger }) => {
+  try {
+    await ack();
+
+    const { channel, message, user } = body;
+    // Functions should be marked as successfully completed using `complete` or
+    // as having failed using `fail`, else they'll remain in an 'In progress' state.
+    await complete({ outputs: { user_id: user.id } });
+
+    await client.chat.update({
+      channel: channel.id,
+      ts: message.ts,
+      text: 'Function completed successfully!',
+    });
+  } catch (error) {
+    logger.error(error);
+    await fail({ error: `Failed to handle a function request: ${error}` });
+  }
+});
+```
+
+</details>