Skip to content

Commit 1f3f4ac

Browse files
misscodedseratch
misscoded
authored and
seratch
committed
docs > workflow steps section
1 parent 6d2ad37 commit 1f3f4ac

File tree

8 files changed

+308
-36
lines changed

8 files changed

+308
-36
lines changed

‎docs/_config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ url: https://slack.dev
1111
collections:
1212
basic:
1313
output: false
14+
steps:
15+
output: false
1416
advanced:
1517
output: false
1618
tutorials:
@@ -29,11 +31,14 @@ defaults:
2931
t:
3032
en:
3133
basic: Basic concepts
34+
steps: Workflow steps
3235
advanced: Advanced concepts
3336
start: Getting started
3437
contribute: Contributing
3538
ja-jp:
3639
basic: 基本的な概念
40+
# TODO: translate this title
41+
steps: Workflow steps
3742
advanced: 応用コンセプト
3843
start: Bolt 入門ガイド
3944
contribute: 貢献

‎docs/_includes/sidebar.html‎

Lines changed: 37 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<div class="sidebar-content">
22
<div class="logo">
33
<span class="icon">
4-
<img src="{{ site.url | append: site.baseurl }}/assets/bolt-py-logo.svg"/>
4+
<img src="{{ site.url | append: site.baseurl }}/assets/bolt-py-logo.svg" />
55
</span>
66

77
<span class="name">
@@ -13,23 +13,41 @@
1313
{% assign localized_base_url = page.lang | prepend: "/" | remove_first: "/en" %}
1414

1515
<span class="version">
16-
{% assign release = site.github.releases | sort: "created_at" | reverse | pop %}
17-
<a href="{{ release[0].html_url }}">{{ release[0].tag_name }}</a>
16+
{% assign release = site.github.releases | sort: "created_at" | reverse | pop %}
17+
<a href="{{ release[0].html_url }}">{{ release[0].tag_name }}</a>
1818
</span>
1919
</div>
2020

2121
<ul class="sidebar-section">
22-
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/tutorial/getting-started"><li class="title">{{ site.t[page.lang].start }}</li></a>
22+
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/tutorial/getting-started">
23+
<li class="title">{{ site.t[page.lang].start }}</li>
24+
</a>
2325
</ul>
2426

2527
<ul class="sidebar-section">
26-
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#basic"><li class="title">{{ site.t[page.lang].basic }}</li></a>
28+
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#basic">
29+
<li class="title">{{ site.t[page.lang].basic }}</li>
30+
</a>
2731
{% assign basic_sections = site.basic | sort: "order" | where: "lang", page.lang %}
28-
32+
2933
{% for section in basic_sections %}
30-
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#{{ section.slug }}">
31-
<li>{{section.title}}</li>
32-
</a>
34+
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#{{ section.slug }}">
35+
<li>{{section.title}}</li>
36+
</a>
37+
{% endfor %}
38+
</ul>
39+
40+
<ul class="sidebar-section">
41+
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#steps">
42+
<li class="title">{{ site.t[page.lang].steps }}</li>
43+
</a>
44+
{% assign workflow_steps = site.steps | sort: "order" | where: "lang", page.lang %}
45+
{% for step in workflow_steps %}
46+
{% if step.slug != "steps-overview" %}
47+
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#{{ step.slug }}">
48+
<li>{{step.title}}</li>
49+
</a>
50+
{% endif %}
3351
{% endfor %}
3452
</ul>
3553

@@ -39,19 +57,21 @@
3957
</a>
4058
{% assign advanced_sections = site.advanced | sort: "order" | where: "lang", page.lang %}
4159
{% for section in advanced_sections %}
42-
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#{{ section.slug }}">
43-
<li>{{section.title}}</li>
44-
</a>
60+
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/concepts#{{ section.slug }}">
61+
<li>{{section.title}}</li>
62+
</a>
4563
{% endfor %}
4664
</ul>
4765

4866
<ul class="sidebar-section">
4967
{% assign tutorials = site.tutorials | where: "lang", page.lang | where_exp: "tutorial", "tutorial.order > 0" %}
5068
{% for tutorial in tutorials %}
51-
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/tutorial/{{ tutorial.slug }}">
52-
<li class="title">{{tutorial.title}}</li>
53-
</a>
69+
<a href="{{ site.url | append: site.baseurl | append: localized_base_url }}/tutorial/{{ tutorial.slug }}">
70+
<li class="title">{{tutorial.title}}</li>
71+
</a>
5472
{% endfor %}
55-
<a href="https://github.com/SlackAPI/bolt-python/blob/master/.github/contributing.md"><li class="title">{{ site.t[page.lang].contribute }}</li></a>
73+
<a href="https://github.com/SlackAPI/bolt-python/blob/master/.github/contributing.md">
74+
<li class="title">{{ site.t[page.lang].contribute }}</li>
75+
</a>
5676
</ul>
57-
</div>
77+
</div>

‎docs/_layouts/default.html‎

Lines changed: 31 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,38 +15,50 @@
1515

1616

1717
<div class="content">
18-
<div class="mainheader">
19-
{% include header.html %}
20-
</div>
18+
<div class="mainheader">
19+
{% include header.html %}
20+
</div>
2121

22-
<div id="basic">
22+
<div id="basic">
2323
{% assign basic_sections = site.basic | sort: "order" | where: "lang", page.lang %}
2424
{% for section in basic_sections %}
25-
<div class="section-wrapper">
26-
<h3 id="{{section.slug}}">{{ section.title }}</h3>
25+
<div class="section-wrapper">
26+
<h3 id="{{section.slug}}">{{ section.title }}</h3>
2727

28-
{{ section.content | markdownify }}
28+
{{ section.content | markdownify }}
2929

30-
<hr>
31-
</div>
30+
<hr>
31+
</div>
3232
{% endfor %}
33+
</div>
34+
35+
<div id="steps">
36+
{% assign workflow_steps = site.steps | sort: "order" | where: "lang", page.lang %} {% for section in
37+
workflow_steps %}
38+
<div class="section-wrapper">
39+
<h3 id="{{section.slug}}">{{ section.title }}</h3>
40+
{{ section.content | markdownify }}
41+
<hr />
3342
</div>
43+
{% endfor %}
44+
</div>
3445

35-
<div id="advanced">
36-
{% assign advanced_sections = site.advanced | sort: "order" | where: "lang", page.lang %}
37-
{% for section in advanced_sections %}
38-
<div class="section-wrapper">
39-
<h3 id="{{section.slug}}">{{ section.title }}</h3>
46+
<div id="advanced">
47+
{% assign advanced_sections = site.advanced | sort: "order" | where: "lang", page.lang %}
48+
{% for section in advanced_sections %}
49+
<div class="section-wrapper">
50+
<h3 id="{{section.slug}}">{{ section.title }}</h3>
4051

41-
{{ section.content | markdownify }}
52+
{{ section.content | markdownify }}
4253

43-
<hr>
44-
</div>
45-
{% endfor %}
54+
<hr>
4655
</div>
56+
{% endfor %}
57+
</div>
4758
</div>
4859

4960
</div>
5061
{% include analytics.html %}
5162
</body>
52-
</html>
63+
64+
</html>

‎docs/_steps/adding_editing_workflow_step.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Adding or editing workflow steps
3+
lang: en
4+
slug: adding-editing-steps
5+
order: 3
6+
---
7+
8+
<div class='section-content'>
9+
10+
When a builder adds (or later edits) your step in their workflow, your app will receive a [`workflow_step_edit` event](https://api.slack.com/reference/workflows/workflow_step_edit). The `edit` callback in your `WorkflowStep` configuration will be run when this event is received.
11+
12+
Whether a builder is adding or editing a step, you need to send them a [workflow step configuration modal](https://api.slack.com/reference/workflows/configuration-view). This modal is where step-specific settings are chosen, and it has more restrictions than typical modals—most notably, it cannot include `title​`, `submit​`, or `close`​ properties. By default, the configuration modal's `callback_id` will be the same as the workflow step.
13+
14+
Within the `edit` callback, the `configure()` utility can be used to easily open your step's configuration modal by passing in the view's blocks with the corresponding `blocks` argument. To disable saving the configuration before certain conditions are met, you can also pass in `submit_disabled` with a value of `True`.
15+
16+
To learn more about opening configuration modals, [read the documentation](https://api.slack.com/workflows/steps#handle_config_view).
17+
18+
</div>
19+
20+
```python
21+
def edit_handler(ack, step, configure):
22+
ack()
23+
24+
blocks = [
25+
{
26+
"type": "input",
27+
"block_id": "task_name_input",
28+
"element": {
29+
"type": "plain_text_input",
30+
"action_id": "name",
31+
"placeholder": {
32+
"type": "plain_text",
33+
"text": "Add a task name",
34+
},
35+
},
36+
"label": {
37+
"type": "plain_text",
38+
"text": "Task name",
39+
},
40+
},
41+
{
42+
"type": "input",
43+
"block_id": "task_description_input",
44+
"element": {
45+
"type": "plain_text_input",
46+
"action_id": "description",
47+
"placeholder": {
48+
"type": "plain_text",
49+
"text": "Add a task description",
50+
},
51+
},
52+
"label": {
53+
"type": "plain_text",
54+
"text": "Task description",
55+
},
56+
},
57+
]
58+
59+
configure(blocks=blocks)
60+
61+
ws = WorkflowStep(callback_id="add_task", config={
62+
"edit": edit_handler,
63+
"save": save_handler,
64+
"execute": execute_handler,
65+
})
66+
67+
app.step(ws)
68+
```

‎docs/_steps/creating_workflow_step.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Creating workflow steps
3+
lang: en
4+
slug: creating-steps
5+
order: 2
6+
---
7+
8+
<div class='section-content'>
9+
10+
To create a workflow step, Bolt provides the `WorkflowStep` class.
11+
12+
When instantiating a new `WorkflowStep`, pass in the step's `callback_id` and a configuration object.
13+
14+
The configuration object contains three keys: `edit`, `save`, and `execute`. Each of these keys must be a single callback or a list of callbacks. All callbacks have access to a `step` object that contains information about the workflow step event.
15+
16+
After instantiating a `WorkflowStep`, you can pass it into `app.step()`. Behind the scenes, your app will listen and respond to the workflow step’s events using the callbacks provided in the configuration object.
17+
18+
</div>
19+
20+
```python
21+
from slack_bolt import App, WorkflowStep
22+
23+
# Initiate the Bolt app as you normally would
24+
app = App(
25+
token=os.environ.get("SLACK_BOT_TOKEN"),
26+
signing_secret=os.environ.get("SLACK_SIGNING_SECRET")
27+
)
28+
29+
# Define the step's configuration
30+
ws_config = {
31+
"edit": edit_handler,
32+
"save": save_handler,
33+
"execute": execute_handler,
34+
}
35+
36+
# Create a new WorkflowStep instance
37+
ws = WorkflowStep(callback_id="add_task", config=ws_config)
38+
39+
app.step(ws)
40+
```

‎docs/_steps/executing_workflow_steps.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Executing workflow steps
3+
lang: en
4+
slug: executing-steps
5+
order: 5
6+
---
7+
8+
<div class="section-content">
9+
10+
When your workflow step is executed by an end user, your app will receive a [`workflow_step_execute` event](https://api.slack.com/events/workflow_step_execute). The `execute` callback in your `WorkflowStep` configuration will be run when this event is received.
11+
12+
Using the `inputs` from the `save` callback, this is where you can make third-party API calls, save information to a database, update the user's Home tab, or decide the outputs that will be available to subsequent workflow steps by mapping values to the `outputs` object.
13+
14+
Within the `execute` callback, your app must either call `complete()` to indicate that the step's execution was successful, or `fail()` to indicate that the step's execution failed.
15+
16+
</div>
17+
18+
```python
19+
def execute_handler(step, complete, fail):
20+
inputs = step["inputs"]
21+
22+
outputs = {
23+
"task_name": inputs["task_name"]["value"],
24+
"task_description": inputs["task_description"]["value"],
25+
}
26+
27+
error = {
28+
"message": "Just testing step failure!"
29+
}
30+
31+
# if everything was successful
32+
complete(outputs=outputs)
33+
34+
# if something went wrong
35+
fail(error=error)
36+
37+
ws = WorkflowStep(callback_id="add_task", config={
38+
"edit": edit_handler,
39+
"save": save_handler,
40+
"execute": execute_handler,
41+
})
42+
43+
app.step(ws)
44+
```

0 commit comments

Comments
 (0)