diff --git a/docs/_config.yml b/docs/_config.yml index 1ed696b75..a8d7fa15c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -18,9 +18,6 @@ collections: tutorials: output: true permalink: /tutorials/:slug - future: - output: true - permalink: /future/:slug defaults: - scope: diff --git a/docs/_future/concepts.md b/docs/_future/concepts.md deleted file mode 100644 index 74c83aed1..000000000 --- a/docs/_future/concepts.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Slack developer beta -lang: en -slug: concepts -order: 0 -layout: future -permalink: /future/concepts ---- -# Slack developer beta concepts BETA - -
- -This page contains all the concepts that are necessary to allow you to use the next-gen Slack features in Python. - -

- -Our next-generation platform is currently in beta. Your feedback is most welcome - all feedback will help shape the future platform experience! -

-
diff --git a/docs/_future/deploy_your_app.md b/docs/_future/deploy_your_app.md deleted file mode 100644 index ed114a163..000000000 --- a/docs/_future/deploy_your_app.md +++ /dev/null @@ -1,16 +0,0 @@ ---- - -title: Deploy your app -lang: en -slug: deploy-your-app -order: 6 -layout: tutorial -permalink: /tutorial/deploy-your-app ---- -# Deploy your app BETA - -
-Instructions for deploying your next-generation Bolt Python application to third-party infrastructure are coming soon! Stay tuned. - -

Our next-generation platform is currently in beta. Your feedback is most welcome - all feedback will help shape the future platform experience!

-
diff --git a/docs/_future/getting_started_future.md b/docs/_future/getting_started_future.md deleted file mode 100644 index d33658314..000000000 --- a/docs/_future/getting_started_future.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Getting started -order: 1 -slug: getting-started-future -lang: en -layout: tutorial -permalink: /tutorial/getting-started-future ---- -## Getting started BETA - -
-This guide will cover how to get started with your next-gen platform using Bolt for Python, by setting up the Slack CLI and installing the required dependencies. - -Find out about the next-generation platform on Slack's official introduction page. -
- ---- - -### Limitations - -Bolt for Python supports app development using next-gen platform features like Functions, Workflows and tools such as the Slack CLI alongside all current generally available Slack Platform features. - -#### We do not yet support - -- Deployment to secure and managed Slack infrastructure. -- Datastores API Datastores functionality. - -> πŸ’‘ If you'd like to deploy your app with Slack infrastructure, consider building your next-generation application with the Deno Slack API. You can get started with that here. - ---- - -### Setting up {#setting-up} - -#### Slack CLI {#setting-up-cli} - -To build a next-generation app with Bolt for Python, you'll need to get the Slack CLI. - -Install the Slack CLI by following this Quickstart. Since we won't be using Deno to build our next-generation app, you can skip any instructions related to installing Deno or creating an app using a Deno template. Once you've logged into the CLI using `slack login` and verified your login using `slack auth list`, you can proceed with the instructions in this guide. - -#### Dependencies {#setting-up-dependencies} - -Once the CLI is set up, make sure your machine has the most recent version of Python installed. You can install Python through a package manager (such as Homebrew for macOS) or directly from the website. - ---- - -### Create a new app {#create-app} - -Before you start developing with Bolt, you'll want to create a Slack app. - -To create the app, you'll run the following command: - -```bash -slack create my-app -t slack-samples/bolt-python-starter-template -b future -``` - -This command creates an app through the CLI by cloning a specified template. In this case, the template is the Bolt for Python Starter Template on the `future` branch. This starter template includes a "Hello World" example that demonstrates how to use built-in and custom Functions, Triggers and Workflows. - -Once the app is successfully created, you should see a message like this: - -```text -✨ my-app successfully created - -🧭 Explore your project's README.md for documentation and code samples, and at any time run slack help to display a list of available commands - -πŸ§‘β€πŸš€ Follow the steps below to try out your new project - -1️⃣ Change into your project directory with: cd my-app - -2️⃣ Develop locally and see changes in real-time with: slack run - -3️⃣ When you're ready to deploy for production use: slack deploy - -πŸ”” If you leave the workspace, you won’t be able to manage any apps you’ve deployed to it. Apps you deploy will belong to the workspace even if you leave the workspace -``` - ---- - -### Set up your trigger {#setup-trigger} - -As mentioned, this app comes with pre-existing functionality - it uses Functions, Workflows and a Link Trigger that will allow users in Slack to initiate the functionality provided by the app. Let's run a command to initialize that Link Trigger via the CLI. - -First, make sure you're in the project directory in your command line: `cd my-app` - -Then, run the following command to create a Trigger: - -```bash -slack triggers create --trigger-def "triggers/sample-trigger.json" -``` - -The above command will create a Link Trigger for the selected workspace. Make sure to select the workspace you want. Once the trigger is successfully created, you should see an output like this: - -```bash -⚑ Trigger created - Trigger ID: [ID] - Trigger Type: shortcut - Trigger Name: Sample Trigger - URL: https://slack.com/shortcuts/[ID]/[Some ID] -``` - -The provided URL can be pasted into Slack; Slack will unfurl it into a button that users can interact with to initiate your app's functionality! Copy this URL and save it somewhere; you'll need it for later. - ---- - -### Run your app {#run-your-app} - -Now that your app and Trigger are successfully created, let's try running it! - -```bash -# install the required project dependencies -pip install -r requirements.txt - -# start a local development server -slack run -``` - -Executing `pip install -r requirements.txt` installs all the project requirements to your machine. - -Executing `slack run` starts a local development server, syncing changes to your workspace's development version of your app. - -You'll be prompted to select a workspace to install the app to—select the development instance of your workspace (you'll know it's the development version because the name has the string `(dev)` appended). - -> πŸ’‘ If you don't see the workspace you'd like to use in the list, you can `CTRL + C` out of the `slack run` command and run `slack auth login`. This will allow you to authenticate in your desired workspace to have it show up in the list for `slack run`. - -You'll see an output in your Terminal to indicate your app is running, similar to what you would see with any other Bolt for Python app. You can search for the `⚑️ Bolt app is running! ⚑️` message to make sure that your app has successfully started up. - -### Trigger your app's workflow {#trigger-workflow} - -With your app running, access your workspace and paste the URL from the Trigger you created in the [previous step](/bolt-python/tutorial/getting-started-future#setup-trigger) into a message in a public channel. - -> πŸ’‘ App Triggers are automatically saved as a channel bookmark under "Workflows" for easy access. - -Send the message and click the "Run" button that appears. A modal will appear prompting you to enter information to greet someone in your Slack workspace. Fill out the requested information. - -![Hello World modal](https://slack.dev/bolt-js/assets/hello-world-modal.png "Hello World modal") - -Then, submit the form. In the specified channel submitted in the form, you should receive a message from the app tagging the submitted user. The message will also contain a randomly generated greeting and the message you wrote in the form. - -The full app flow can be seen here: -![Hello World app](https://slack.dev/bolt-js/assets/hello-world-demo.gif "Hello World app") - ---- - -### Next steps {#next-steps} - -Now we have a working instance of a next-generation app in your workspace and you've seen it in action! You can explore on your own and dive into the code yourself here or continue your learning journey by diving into [App Manifests](/bolt-python/future/concepts#manifests) or looking into adding more [Functions](/bolt-python/future/concepts#functions), [Workflows](/bolt-python/future/concepts#manifest-workflows), and [Triggers](#setup-trigger) to your app! diff --git a/docs/_future/listening_responding_functions.md b/docs/_future/listening_responding_functions.md deleted file mode 100644 index b7c13c692..000000000 --- a/docs/_future/listening_responding_functions.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Listening & responding to functions -lang: en -slug: functions -order: 5 -layout: future ---- - -
- -Your app can use the `function()` method to listen to incoming function requests. The method requires a function `callback_id` of type `str`. This `callback_id` must also be defined in your [Function](/bolt-python/future/concepts#manifest-functions) definition. Functions must eventually be completed with the `complete()` function to inform Slack that your app has processed the function request. `complete()` requires **one of two** keyword arguments: `outputs` or `error`. There are two ways to complete a Function with `complete()`: - -* `outputs` of type `dict` completes your function **successfully** and provides a dictionary containing the outputs of your function as defined in the app's manifest. -* `error` of type `str` completes your function **unsuccessfully** and provides a message containing information regarding why your function was not successful. - -
- -
-Refer to the module document to learn the available listener arguments. -```python -# The sample function simply outputs an input -@app.function("sample_function") -def sample_func(event: dict, complete: Complete): - try: - message = event["inputs"]["message"] - complete( - outputs={ - "updatedMsg": f":wave: You submitted the following message: \n\n>{message}" - } - ) - except Exception as e: - complete(error=f"Cannot submit the message: {e}") - raise e -``` -
- -
- -

Function Interactivity

- - -
- -The `function()` method returns a `SlackFunction` decorator object. This object can be used by your app to set up interactive listeners such as [actions](/bolt-python/concepts#action-respond) and [views](/bolt-python/concepts#view_submissions). These listeners listen to events created during the handling of your `function` event. Additionally, they will only be called when a user interacts with a block element that has the following attributes: - -* It was created during the handling of a `function` event. -* The `action_id` matches the interactive listeners `action_id`. - -These listeners behave similarly to the ones assigned directly to your app. The notable difference is that `complete()` must be called once your function is completed. - -
- -```python -# Your listener will be called when your function "sample_function" is triggered from a workflow -# When triggered a message containing a button with an action_id "approve_button" is posted -@app.function("sample_function") -def sample_func(event: dict, complete: Complete): - try: - client.chat_postMessage( - channel="a-channel-id", - text="A new button appears", - blocks=[ - { - "type": "actions", - "block_id": "approve-button", - "elements": [ - { - "type": "button", - "text": { - "type": "plain_text", - "text": "Click", - }, - "action_id": "sample_action", - "style": "primary", - }, - ], - }, - ], - ) - except Exception as e: - complete(error=f"Cannot post the message: {e}") - raise e - -# Your listener will be called when a block element -# - Created by your "sample_func" -# - With the action_id "sample_action" -# is triggered -@sample_func.action("sample_action") -def update_message(ack, body, client, complete): - try: - ack() - if "container" in body and "message_ts" in body["container"]: - client.reactions_add( - name="white_check_mark", - channel=body["channel"]["id"], - timestamp=body["container"]["message_ts"], - ) - complete() - except Exception as e: - logger.error(e) - complete(error=f"Cannot react to message: {e}") - raise e -``` - -
diff --git a/docs/_future/manifest.md b/docs/_future/manifest.md deleted file mode 100644 index 26b77f28a..000000000 --- a/docs/_future/manifest.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Manifest -lang: en -slug: manifest -order: 2 -layout: future ---- - - -
- -Your project should contain a `manifest.json` file that defines your app's manifest. This is where you'll configure your application name and scopes, declare the functions your app will use, and more. -Refer to the App Manifest and Manifest Property documentation to learn -about the available manifest configurations. - -Notably, the App Manifest informs Slack of the definitions for: - -* [Functions](/bolt-python/future/concepts#manifest-functions) -* [Workflows](/bolt-python/future/concepts#manifest-workflows) - -`manifest.json` is located at the top level of our example projects, along with a `triggers` folder containing -`*_trigger.json` files that define the triggers -for your app. - -
-.
-β”œβ”€β”€ ...
-β”œβ”€β”€ manifest.json             # app manifest definition
-β”œβ”€β”€ triggers                  # folder with trigger files
-β”‚   β”œβ”€β”€ sample_trigger.json   # trigger definition
-β”‚   └── ...
-└── ...
-
- -
- -#### Linting, prediction & validation - -Syntax and formatting checks are required to efficiently edit your `manifest.json`. Multiple IDEs are able to support -this, namely: Visual Studio Code, Pycharm, Sublime Text (via LSP-json) and many more. - -To get **manifest prediction & validation** in your IDE, include the following line in your `manifest.json` file: - -```json -{ - "$schema": "https://raw.githubusercontent.com/slackapi/manifest-schema/main/manifest.schema.json", - ... -} -``` - -Using the Slack CLI you can validate your `manifest.json` against the Slack API with: - -```bash -slack manifest validate -``` - -
- -
-Refer to our template project to view a full version of manifest.json. -```json -{ - "$schema": "https://raw.githubusercontent.com/slackapi/manifest-schema/main/manifest.schema.json", - "_metadata": { - "major_version": 2, - }, - "display_information": { - "name": "Bolt Template App TEST" - }, - "features": { - "app_home": { - "home_tab_enabled": false, - }, - "bot_user": { - "display_name": "Bolt Template App TEST", - "always_online": false - } - }, - "oauth_config": { - "scopes": { - "bot": [ - "chat:write", - ] - } - }, - "settings": { - "socket_mode_enabled": true, - }, - "functions": {}, - "types": {}, - "workflows": {}, - "outgoing_domains": [] -} -``` -
- -
- - -

Common Manifest Types

- - -
-
- - - - - - - - - - - - - - - - - -
parameters
object
propertiespropertiesdefines the properties
requiredlist[string]defines the properties required by the function
- - - - - - - - - - - - - - - - - -
properties
dictionary
keystringdefines the property name
valuepropertydefines the property
- - - - - - - - - - - - - - - - - -
property
object
typestringdefines the property type
descriptionstringdefines the property description
-
- -```json -"$comment": "sample parameters object" -"*_parameters":{ - "properties": { - "property_0_name": { - "type": "string", - "description": "this is my first property" - }, - "property_1_name": { - "type": "integer", - "description": "this is my second property" - } - }, - "required": [ - "property_0_name" - ] -} -``` - -
-
diff --git a/docs/_future/manifest_functions.md b/docs/_future/manifest_functions.md deleted file mode 100644 index 7c1f7aa0b..000000000 --- a/docs/_future/manifest_functions.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Manifest functions -order: 3 -slug: manifest-functions -lang: en -layout: future ---- - -
-Your app can [invoke Functions](/bolt-python/future/concepts#functions) defined and created by you (Custom Functions). In order for this to work, Slack must know they exist. Define them in your [App Manifest](/bolt-python/concepts#manifest) also known as `manifest.json` in your project. The next time you `slack run` your app will inform Slack they exist. - - - - - - - - - - - - - - - - - -
functions
dictionary
keystringdefines the function's callback_id
valuefunctiondefines the function
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
function
object
titlestringdefines the title
descriptionstringdefines the description
input_parametersparametersdefines the inputs
output_parametersparametersdefines the outputs
- -
- -
-Refer to our template project to view a full version of manifest.json. -```json - "functions": { - "sample_function": { - "title": "Sample function", - "description": "A sample function", - "input_parameters": { - "properties": { - "message": { - "type": "string", - "description": "Message to be posted" - } - }, - "required": [ - "message" - ] - }, - "output_parameters": { - "properties": { - "updatedMsg": { - "type": "string", - "description": "Updated message to be posted" - } - }, - "required": [ - "updatedMsg" - ] - } - } - } -``` -
diff --git a/docs/_future/manifest_workflows.md b/docs/_future/manifest_workflows.md deleted file mode 100644 index 76aa17db5..000000000 --- a/docs/_future/manifest_workflows.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Manifest workflows -order: 4 -slug: manifest-workflows -lang: en -layout: future ---- - -
- -Your app can use Functions by referencing them in Workflows. Your Custom Functions and the Built-in Functions can be used as steps in Workflow definitions. - -Workflows are invoked by Triggers. You will need to set up a Trigger in order to use your defined workflows. Triggers, Workflows, and Functions work together in the following way: - -Trigger β†’ Workflow β†’ Workflow Step β†’ Function - -Your App Manifest, found at `manifest.json`, is where you will define your workflows. - - - - - - - - - - - - - - - - - -
workflows
dictionary
keystringdefines the workflow's id
valueworkflowdefines the function
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
workflow
object
titlestringdefines the title
descriptionstringdefines the description
input_parametersparametersdefines the inputs
stepslist[parameters]defines the steps
- - - - - - - - - - - - - - - - - - - - - - -
step
object
idstringdefines the order of the steps
function_idstringidentifies the function to evoke
inputsdict[string:string]defines the inputs to provide to the function
- -
- -
-Refer to our template project to view a full version of manifest.json. -```json - "workflows": { - "sample_workflow": { - "title": "Sample workflow", - "description": "A sample workflow", - "input_parameters": { - "properties": { - "channel": { - "type": "slack#/types/channel_id" - } - }, - "required": [ - "channel" - ] - }, - "steps": [ - { - "id": "0", - "function_id": "#/functions/sample_function", - "inputs": { - "message": "{{inputs.channel}}" - } - }, - { - "id": "1", - "function_id": "slack#/functions/send_message", - "inputs": { - "channel_id": "{{inputs.channel}}", - "message": "{{steps.0.updatedMsg}}" - } - } - ] - } - } -``` -
- -
- - -

Built-in functions

- - -
-Slack provides built-in functions that can be used by a Workflow to accomplish simple tasks. You can add these functions to your workflow steps in order to use them. - -- Send message -- Open a form -- Create channel - -Refer to the built-in functions document to learn about the available built-in functions. -
- -```json - "$comment": "A step to post the user name to a channel" - "steps": [ - { - "id": "0", - "function_id": "slack#/functions/send_message", - "inputs": { - "channel_id": "{{inputs.channel}}", - "message": "{{inputs.user_name}}" - } - } - ] -``` - -
diff --git a/docs/_future/setup_existing_app.md b/docs/_future/setup_existing_app.md deleted file mode 100644 index 2e93253bf..000000000 --- a/docs/_future/setup_existing_app.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Setup an existing app -order: 7 -slug: setup-existing-app -lang: en -layout: tutorial -permalink: /tutorial/setup-existing-app ---- - -## Setup an existing app BETA - -
-If you would like to setup an existing Slack app written with the beta tools from the next-generation platform, this guide is for you! -
- -To get started with a new Bolt for Python application take a look at this [Getting Started guide](/bolt-python/tutorial/getting-started-future) instead. - ---- - -### Prerequisites {#prerequisites} - -Before we get started, make sure you've followed the [Setting Up step](/bolt-python/tutorial/getting-started-future#setting-up) of the [Getting Started guide](/bolt-python/tutorial/getting-started-future) to install required dependencies. - ---- - -### Set up your app to work with the Slack CLI {#setup-with-cli} - -Update your project's version of Bolt (sometimes found in requirements.txt) to the latest `*.dev*` distribution and reinstall your dependencies: `pip install -r requirements.txt` - -```text -# with pip -pip install slack-bolt==*.dev* - -# in requirements.txt -slack-bolt==*.dev* -``` - -Then, add a `slack.json` file to your local project root containing the contents of our [template slack.json](https://github.com/slack-samples/bolt-python-starter-template/blob/future/slack.json). - ---- - -### Add your manifest {#manifest-in-code} - -Head to [your app's App Config Page](https://api.slack.com/apps) and navigate to Features > App Manifest. Download a copy of your app manifest in the JSON file format. - -Add this `manifest.json` to your project root. This represents your project's existing configuration. To get **manifest prediction & validation** in your IDE, include the following line in your `manifest.json` file: - -```json -{ - "$schema": "https://raw.githubusercontent.com/slackapi/manifest-schema/main/manifest.schema.json", - ... -} -``` - -To learn more about the `manifest.json` take a look at the [Manifest concept](/bolt-python/future/concepts#manifest). - ---- - -Now let's run the Slack CLI command `slack manifest` to generate your manifest. It should contain at least these settings: - -```bash -{ - "_metadata": { - "major_version": 2 - }, - "oauth_config": { - "token_management_enabled": true - }, - "settings": { - "interactivity": { - "is_enabled": true - } - }, - "org_deploy_enabled": true -} -``` - -You can also run this command to validate your App's configuration with the Slack API: - -```bash -slack manifest validate -``` - ---- - -### Run your app! {#tada} - -Run the Slack CLI command `slack run` to start your app in local development. - -The CLI will create and install a new development app for you with its own App ID, allowing you to keep your testing changes separate from your production App). - -Now you're ready to start adding [Functions](/bolt-python/future/concepts#functions) and [Workflows](/bolt-python/future/concepts#manifest-workflows) to your app! - ---- - -### Updating your app configuration {#update-app} - -You have probably made changes to your app’s manifest (adding a Function or a Workflow, for example). To sync your production app’s configuration with the changes you’ve made locally in your manifest: - -1. Authenticate the Slack CLI with your desired production workspace using `slack login`. -2. In your project, head over to `./slack/apps.json` and make sure an entry exists for your workspace with the current `app_id` and `team_id` of the workspace. - - ```bash - { - "apps": { - "": { - "name": "", - "app_id": "A041G4M3U00", - "team_id": "T038J6TH5PF" - } - }, - "default": "" - } - ``` - -3. Run `slack install` and select your app. Select your workspace from the list prompt to install. - ---- - -### Conclusion {#conclusion} - -Congratulations on migrating your app to the next-generation Slack Platform! πŸŽ‰ You can continue your journey by learning about [Manifests](/bolt-python/future/concepts#manifest) or looking into adding [Functions](/bolt-python/future/concepts#functions) and [Workflows](/bolt-python/future/concepts#manifest-workflows) to your app! diff --git a/docs/_includes/sidebar.html b/docs/_includes/sidebar.html index 5e9fa141d..970cf3869 100644 --- a/docs/_includes/sidebar.html +++ b/docs/_includes/sidebar.html @@ -41,30 +41,6 @@ {% endfor %} - -