docs: document custom step usage #2198

WilliamBergamin · 2024-08-13T17:49:24Z

This PR aims to provide documentation for custom step usage in the bolt framework

Testing

Pull this branch
cd ./docs
npm install
npm start
http://localhost:3000/bolt-js/concepts/custom-steps

Requirements (place an `x` in each `[ ]`)

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

Co-authored-by: Fil Maj <[email protected]>

WilliamBergamin · 2024-08-13T17:50:05Z

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

@@ -0,0 +1,101 @@
+---


Will need help with the translation 🙏

codecov · 2024-08-13T17:53:49Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.59%. Comparing base (91b3519) to head (6779dbb).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2198   +/-   ##
=======================================
  Coverage   81.59%   81.59%           
=======================================
  Files          19       19           
  Lines        1646     1646           
  Branches      464      464           
=======================================
  Hits         1343     1343           
  Misses        194      194           
  Partials      109      109

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

srajiang

English bits look good to me, left one small comment. I've not tested with these instructs though, so I'll let someone else approve.

README.md

WilliamBergamin · 2024-08-13T19:40:54Z

Removed the existing docs/content/custom-functions documentation

Reason for this is that it included information that was not bolt specific and duplicated in api.slack.com. It also seems like overkill to have a dedicated sidebar section for custom steps

filmaj

Nice job! Left some suggestions.

docs/content/basic/custom-steps.md

filmaj · 2024-08-13T20:00:13Z

docs/content/basic/custom-steps.md

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


Suggested tweak to the introduction here:

Suggested change

Your app can listen to user actions, like button clicks, created from `custom steps` using the `action` method.

Your app's custom steps may create interactivity points for users, for example:

- Post a message with a button

- [Open a modal view](creating-modals)

If such interaction points originate from a custom step execution, the events sent to your app representing the end-user interaction with these points are considered to be _function-scoped interactivity events_. These interactivity events can be handled by your app using the same concepts we covered earlier, such as [Listening to actions](action-listening) or [Listening to views](view-submissions).

The one addition that function-scoped interactivity events have is they will contain data related to the `function_executed` event they were spawned from, such as custom step input data and access to `complete()` and `fail()` handlers to manage step control flow.

This is good 🙇 provides more information without duplicating documentation from api.slack.com

I had to adapt this slightly to because open modal views are not yet supported, but hopefully soon

docs/content/basic/custom-steps.md

zimeg

This is super solid! 🏆 🚀 I left a few comments on wording and a suggestion on introducing this ✨ as a concept ✨ but don't think those are blocking.

Removing ack from the function listener might be though! 😳 I'm finding this won't transpile when collected from the listener arguments...

I also agree with a lot of the suggestions from @filmaj and think this'll be good to merge once you think so!

zimeg · 2024-08-13T21:06:55Z

docs/content/basic/custom-steps.md

+app.function('sample_custom_step', async ({ ack, inputs, complete, fail, logger }) => {
+  try {
+    await ack();


Suggested change

app.function('sample_custom_step', async ({ ack, inputs, complete, fail, logger }) => {

try {

await ack();

app.function('sample_custom_step', async ({ inputs, complete, fail, logger }) => {

try {

Removing the ack here since this isn't provided for function executions

I prefer to keep it in the docs, there are a number of issues opened related to calling ack before executing custom logic

Keeping this in hopes that it will help developers avoid a bug 🙏

We can remove it in a follow up PR as well 🤔

I believe the function_executed events are actually different from other events and can't use ack at all!

Within JavaScript code this is undefined within the listener so this call will error 😬 It's not so clear from this picture but the hover hint is hinting at this in a TypeScript project:

zimeg · 2024-08-13T21:07:12Z

docs/content/basic/custom-steps.md

+app.function('sample_function', async ({ ack, client, inputs, fail, logger }) => {
+  try {
+    await ack();


Suggested change

app.function('sample_function', async ({ ack, client, inputs, fail, logger }) => {

try {

await ack();

app.function('sample_function', async ({ client, inputs, fail, logger }) => {

try {

zimeg · 2024-08-13T21:27:34Z

docs/content/basic/custom-steps.md

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


Suggested change

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.

Your app can use the `function()` listener 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.

Adding a custom step starts with a definition in [the app manifest](https://api.slack.com/concepts/manifests#functions) and a `function()` listener listening for the `callback_id` of that function. Upon function execution the listener is called and can run whatever code, but must finish with either the `complete()` or `fail()` listener argument to end the step:

Hoping to set a bit more context for custom steps in just the first paragraph! Also wanting to frame the following one as more instruction instead of reference, but feel free to change it or ignore 🙏

Also not certain about the "method" vs "listener" naming!

The rest of the documentation uses the method terminology instead of the listener

I think its better to be consistent and stick to method

We can send a follow up PR to update all the terms 👍

docs/content/basic/custom-steps.md

zimeg · 2024-08-13T21:33:40Z

docs/content/custom-functions/defining-custom-functions.md

-```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"
-            }
-        }
-    }
-}
-```


IMO it'd be nice to include this as <details> in the docs so the inputs and complete.outputs in the examples have context, but not necessary 🤔

And then I'm not sure if that'd also mean referencing function_runtime settings and the function_executed event 😓

Good idea 💯 done ✅

Co-authored-by: Fil Maj <[email protected]>

…mplate (#2202)

Co-authored-by: Eden Zimbelman <[email protected]>

…olt-js into document-custom-steps

docs/content/basic/custom-steps.md

zimeg

Awesome saucesome! 😋 Thanks for addressing the feedback! 🚀

misscoded and others added 15 commits January 24, 2024 16:37

[WIP] Add function listener support

a050256

[WIP] Add foundation of CLI hooks support

188813c

[WIP] Add support for interactivity

f31d8df

[WIP] Add attachFunctionToken opt-out option

3faab87

[WIP] Revert CLI hook support within Bolt

b46f470

Incorporate PR comments

1b79873

Add CustomFunction test + adjust naming

630f188

Update error description

caec4b1

Bump the @slack/web-api version to v6.12.0

247b4c7

v3.17.1-customFunctionBeta.0

11a42c0

chore: merge w main

e933eda

chore: merge w main

87730ef

Fixes and polish for stable release (#2128)

bea900d

Co-authored-by: Fil Maj <[email protected]>

chore: merge main

b10bbb0

docs: document custom step usage

e3ac1eb

WilliamBergamin added the docs M-T: Documentation work only label Aug 13, 2024

WilliamBergamin requested review from filmaj, misscoded and zimeg August 13, 2024 17:49

WilliamBergamin self-assigned this Aug 13, 2024

WilliamBergamin commented Aug 13, 2024

View reviewed changes

srajiang reviewed Aug 13, 2024

View reviewed changes

README.md Outdated Show resolved Hide resolved

Remove old docs

717028f

Improve readme based on feedback

f15413a

WilliamBergamin changed the base branch from main to feat-functions August 13, 2024 19:46

Merge branch 'feat-functions' into document-custom-steps

60261d0

filmaj suggested changes Aug 13, 2024

View reviewed changes

zimeg requested changes Aug 13, 2024

View reviewed changes

This was referenced Aug 13, 2024

docs: document custom step usage slackapi/bolt-python#1125

Merged

chore: purge the "workflow step" terminology #2199

Merged

misscoded and others added 14 commits August 14, 2024 08:02

[Bug] Fix chained function actions (#2200)

23ef516

Update docs/content/basic/custom-steps.md

3aa9f34

Co-authored-by: Fil Maj <[email protected]>

Update docs/content/basic/custom-steps.md

5132ad4

Co-authored-by: Fil Maj <[email protected]>

Update docs/content/basic/custom-steps.md

7f14da1

Co-authored-by: Fil Maj <[email protected]>

Remote functions: typescript integration test with bolt-ts-starter-te…

90ce812

…mplate (#2202)

Improve based on feedback

0451502

Merge branch 'main' into feat-functions

0110bf2

Merge branch 'feat-functions' into document-custom-steps

960d18e

Update docs/content/basic/custom-steps.md

d73f717

Co-authored-by: Eden Zimbelman <[email protected]>

Update I18

5fa091a

Merge branch 'document-custom-steps' of https://github.com/slackapi/b…

70240f9

…olt-js into document-custom-steps

Add the definition in a dropdown

56ab543

Improve example

44da1d1

Update I18 version

b353056

WilliamBergamin requested review from zimeg and filmaj August 14, 2024 17:58

zimeg reviewed Aug 14, 2024

View reviewed changes

docs/content/basic/custom-steps.md Outdated Show resolved Hide resolved

Base automatically changed from feat-functions to main August 14, 2024 18:22

filmaj approved these changes Aug 14, 2024

View reviewed changes

WilliamBergamin and others added 2 commits August 14, 2024 15:22

Remove ack from example

34fefa2

Merge branch 'main' into document-custom-steps

6779dbb

WilliamBergamin requested a review from zimeg August 14, 2024 19:26

zimeg approved these changes Aug 14, 2024

View reviewed changes

WilliamBergamin merged commit 9839f0c into main Aug 14, 2024
17 checks passed

WilliamBergamin deleted the document-custom-steps branch August 14, 2024 19:36

zimeg added this to the 3.21.1 milestone Aug 16, 2024

Jrc356 mentioned this pull request Sep 6, 2024

[Snyk] Upgrade @slack/bolt from 3.19.0 to 3.21.1 Jrc356/avokudos#39

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document custom step usage #2198

docs: document custom step usage #2198

WilliamBergamin commented Aug 13, 2024 •

edited

Loading

WilliamBergamin Aug 13, 2024

codecov bot commented Aug 13, 2024 •

edited

Loading

srajiang left a comment

WilliamBergamin commented Aug 13, 2024

filmaj left a comment

filmaj Aug 13, 2024

WilliamBergamin Aug 14, 2024

zimeg left a comment

zimeg Aug 13, 2024

WilliamBergamin Aug 14, 2024

zimeg Aug 14, 2024

zimeg Aug 13, 2024

zimeg Aug 13, 2024

zimeg Aug 13, 2024

WilliamBergamin Aug 14, 2024

zimeg Aug 13, 2024

zimeg Aug 13, 2024

WilliamBergamin Aug 14, 2024

zimeg left a comment

-  Your app can listen to user actions, like button clicks, created from `custom steps` using the `action` method.
+  Your app's custom steps may create interactivity points for users, for example:
+- Post a message with a button
+- [Open a modal view](creating-modals)
+If such interaction points originate from a custom step execution, the events sent to your app representing the end-user interaction with these points are considered to be _function-scoped interactivity events_. These interactivity events can be handled by your app using the same concepts we covered earlier, such as [Listening to actions](action-listening) or [Listening to views](view-submissions).
+The one addition that function-scoped interactivity events have is they will contain data related to the `function_executed` event they were spawned from, such as custom step input data and access to `complete()` and `fail()` handlers to manage step control flow.

-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.
+Your app can use the `function()` listener 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.
+Adding a custom step starts with a definition in [the app manifest](https://api.slack.com/concepts/manifests#functions) and a `function()` listener listening for the `callback_id` of that function. Upon function execution the listener is called and can run whatever code, but must finish with either the `complete()` or `fail()` listener argument to end the step:

docs: document custom step usage #2198

docs: document custom step usage #2198

Conversation

WilliamBergamin commented Aug 13, 2024 • edited Loading

Testing

Requirements (place an x in each [ ])

Choose a reason for hiding this comment

codecov bot commented Aug 13, 2024 • edited Loading

Codecov Report

srajiang left a comment

Choose a reason for hiding this comment

WilliamBergamin commented Aug 13, 2024

filmaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zimeg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zimeg left a comment

Choose a reason for hiding this comment

WilliamBergamin commented Aug 13, 2024 •

edited

Loading

Requirements (place an `x` in each `[ ]`)

codecov bot commented Aug 13, 2024 •

edited

Loading