-
Notifications
You must be signed in to change notification settings - Fork 393
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add support for Workflow Steps from Apps #597
Merged
misscoded
merged 11 commits into
slackapi:feat-workflow-steps
from
misscoded:feat-workflow-steps
Sep 3, 2020
Merged
Changes from 18 commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
67a41b6
WorkflowStep class + associated types
misscoded b97878a
add support for configure() > submit_disabled + external_id arg
misscoded 87a5612
adjust configure() + update() to conditionally include user-provided …
misscoded 7f67ab8
update workflow step documentation to reflect api changes
misscoded 0fed495
create ViewWorkflowStepClosedAction interface
misscoded dde364c
WorkflowStep tests + adjust class types
misscoded a5c89c1
remove doc reference to optional callback_id override
misscoded d2b0690
adjust utility configs, add blocks type, make validTypes const
misscoded 20dbe29
merge in main, less version bumps for types and web-api
misscoded 50286b6
bump version to reflect merge
misscoded f9e1c55
Merge branch 'feat-workflow-steps' into feat-workflow-steps
misscoded File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
--- | ||
title: Adding or editing workflow steps | ||
lang: en | ||
slug: adding-editing-steps | ||
order: 3 | ||
beta: true | ||
--- | ||
|
||
<div class='section-content'> | ||
|
||
When a builder adds (or later edits) your step in their workflow, your app will receive a `workflow_step_edit` action. The callback assigned to the `edit` property of the `WorkflowStep` configuration object passed in during instantiation will run when this action occurs. | ||
|
||
Whether a builder is adding or editing a step, you need to provide them with a special `workflow_step` modal — a workflow step configuration modal — where step-specific settings are chosen. Since the purpose of this modal is tied to a workflow step's configuration, it has more restrictions than typical modals—most notably, you cannot include `title`, `submit`, or `close` properties in the payload. By default, the `callback_id` used for this modal will be the same as that of the workflow step. | ||
|
||
Within the `edit` callback, the `configure()` utility can be used to easily open your step's configuration modal by passing in an object with your view's `blocks`. To disable configuration save before certain conditions are met, pass in `submit_disabled` with a value of `true`. | ||
|
||
To learn more about workflow step configuration modals, [read the documentation](https://api.slack.com/reference/workflows/configuration-view). | ||
|
||
</div> | ||
|
||
```javascript | ||
const ws = new WorkflowStep('add_task', { | ||
edit: async ({ ack, step, configure }) => { | ||
await ack(); | ||
|
||
const blocks = [ | ||
{ | ||
'type': 'input', | ||
'block_id': 'task_name_input', | ||
'element': { | ||
'type': 'plain_text_input', | ||
'action_id': 'name', | ||
'placeholder': { | ||
'type': 'plain_text', | ||
'text': 'Add a task name' | ||
} | ||
}, | ||
'label': { | ||
'type': 'plain_text', | ||
'text': 'Task name' | ||
} | ||
}, | ||
{ | ||
'type': 'input', | ||
'block_id': 'task_description_input', | ||
'element': { | ||
'type': 'plain_text_input', | ||
'action_id': 'description', | ||
'placeholder': { | ||
'type': 'plain_text', | ||
'text': 'Add a task description' | ||
} | ||
}, | ||
'label': { | ||
'type': 'plain_text', | ||
'text': 'Task description' | ||
} | ||
}, | ||
]; | ||
|
||
await configure({ blocks }); | ||
}, | ||
save: async ({ ack, step, update }) => {}, | ||
execute: async ({ step, complete, fail }) => {}, | ||
}); | ||
``` |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
--- | ||
title: Creating a workflow step | ||
lang: en | ||
slug: creating-steps | ||
order: 2 | ||
beta: true | ||
--- | ||
|
||
<div class='section-content'> | ||
|
||
To create a new workflow step, Bolt provides the `WorkflowStep` class. | ||
|
||
When instantiating a new `WorkflowStep`, pass in the step's `callback_id`, which is defined in your app configuration, and a step configuration object. | ||
|
||
The configuration object for a `WorkflowStep` contains three properties: `edit`, `save`, and `execute`. Each of these properties must either hold a value of a single callback or an array of callbacks. All callbacks have access to a `step` object that contains information about the workflow step event, as well as one or more utility functions. | ||
|
||
After instantiating your workflow step, pass it the instance 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. | ||
|
||
</div> | ||
|
||
```javascript | ||
const { WorkflowStep } = require('@slack/bolt'); | ||
|
||
const ws = new WorkflowStep('add_task', { | ||
edit: async ({ ack, step, configure }) => {}, | ||
save: async ({ ack, step, update }) => {}, | ||
execute: async ({ step, complete, fail }) => {}, | ||
}); | ||
|
||
app.step(ws); | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
--- | ||
title: Saving the step configuration | ||
lang: en | ||
slug: saving-steps | ||
order: 4 | ||
beta: true | ||
--- | ||
|
||
<div class='section-content'> | ||
|
||
When the workflow step's configuration has been saved (using the step configuration modal from the `edit` callback), your app will listen for the `view_submission` event. The method assigned to the `save` property of the `WorkflowStep` configuration object passed in during instantiation will run when this event occurs. | ||
|
||
Once the configuration for the workflow step has been determined, builders often use that configuration to craft the custom outputs and behavior that occurs when the end user executes the step. | ||
|
||
Within the `save` callback, the `update()` method can be used to save the builder's step configuration by passing in the following arguments: `inputs`, `outputs`, `step_name` and `step_image_url`. | ||
|
||
`inputs` is an object representing the data your app expects to receive from the user upon workflow step execution. To use variables that were collected earlier in the workflow, you can include handlebar-style syntax (`{{ variable }}`). During the workflow step's execution, those variables will be replaced with their actual runtime value. | ||
|
||
`outputs` is an array of objects containing data that your app will provide upon the workflow step's completion. Outputs can then be used in subsequent steps of the workflow. | ||
|
||
`step_name` and `step_image_url` are available for a more customized look and feel of your workflow step. | ||
|
||
To learn more about how to structure these parameters, [read the documentation](https://api.slack.com/reference/workflows/workflow_step). | ||
|
||
</div> | ||
|
||
```javascript | ||
const ws = new WorkflowStep('add_task', { | ||
edit: async ({ ack, step, configure }) => {}, | ||
save: async ({ ack, step, update }) => { | ||
await ack(); | ||
|
||
const { values } = view.state; | ||
const taskName = values.task_name_input.name; | ||
const taskDescription = values.task_description_input.description; | ||
|
||
const inputs = { | ||
taskName: { value: taskName }, | ||
taskDescription: { value: taskDescription } | ||
}; | ||
|
||
const outputs = [ | ||
{ | ||
type: 'text', | ||
name: 'taskName', | ||
label: 'Task name', | ||
}, | ||
{ | ||
type: 'text', | ||
name: 'taskDescription', | ||
label: 'Task description', | ||
} | ||
]; | ||
|
||
await update({ inputs, outputs }); | ||
}, | ||
execute: async ({ step, complete, fail }) => {}, | ||
}); | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reminder ::
@slack/types
and@slack/web-api
need to be updated to appropriate versions prior to merge