From 8c77f918d857f01a2b608e5952944bf7587d028f Mon Sep 17 00:00:00 2001 From: William Bergamin Date: Fri, 9 Aug 2024 19:48:34 +0000 Subject: [PATCH] chore: update project for app settings configuration first (#17) * chore: update project for app settings configuration first * clean up instuctions * Improve based on feedback * update based on feedback --- README.md | 93 +++++++++++++++++++++++++++--------------------- requirements.txt | 1 - 2 files changed, 52 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 32e8734..b298561 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,71 @@ # Bolt for Python Jira Functions -This is a Bolt for Python app used to interact with Jira Server. +This is a Bolt for Python app used to interact with Jira Server through custom +functions for use in +[Workflow Builder](https://api.slack.com/start#workflow-builder). + +## Setup Before getting started, make sure you have a development workspace where you have permissions to install apps. If you don’t have one setup, go ahead and [create one](https://slack.com/create). -## Installation +### Developer Program -### Install the Slack CLI +Join the [Slack Developer Program](https://api.slack.com/developer-program) for +exclusive access to sandbox environments for building and testing your apps, +tooling, and resources created to help developers build and grow. -To use this template, you need to install and configure the Slack CLI. -Step-by-step instructions can be found in our -[Quickstart Guide](https://api.slack.com/automation/quickstart). +## Installation ### Create a Slack App -```zsh -# Clone this project onto your machine -slack create my-app -t slack-samples/bolt-python-jira-functions - -# Change into the project directory -cd my-app - -# Set up virtual environment -python3 -m venv .venv -source .venv/bin/activate - -# Install dependencies -pip install -r requirements.txt -``` +1. Open [https://api.slack.com/apps/new](https://api.slack.com/apps/new) and + choose "From an app manifest" +2. Choose the workspace you want to install the application to +3. Copy the contents of [manifest.json](./manifest.json) into the text box that + says `*Paste your manifest code here*` (within the JSON tab) and click _Next_ +4. Review the configuration and click _Create_ +5. Click _Install_ button and _Allow_ on the screen that follows. You'll then be + redirected to the App Settings dashboard. ### Environment Variables Before you can run the app, you'll need to store some environment variables. 1. Rename `.example.env` to `.env` -2. Follow these +2. Open your apps setting page from this list, click **OAuth & + Permissions** in the left hand menu, then copy the Bot User OAuth Token. You + will store this in your environment as `SLACK_BOT_TOKEN`. +3. Click ***Basic Information** from the left hand menu and follow the steps in + the App-Level Tokens section to create an app-level token with the + `connections:write` scope. Copy this token. You will store this in your + environment as `SLACK_APP_TOKEN`. +4. Follow these [Jira Instruction](https://confluence.atlassian.com/adminjiraserver0909/configure-an-incoming-link-1251415519.html) to create an external application and get the `Client ID` (`JIRA_CLIENT_ID`) and `Client secret` (`JIRA_CLIENT_SECRET`) values. -3. Populate the other environment variable value with proper values. - -### Running Your Project Locally +5. Populate the other environment variable value with proper values. -You'll know an app is the development version if the name has the string -`(local)` appended. +### Local Project ```zsh -# Run Bolt server -slack run +# Clone this project onto your machine +git clone https://github.com/slack-samples/bolt-python-jira-functions.git -INFO:slack_bolt.App:Starting to receive messages from a new connection -``` +# Change into this project directory +cd bolt-python-jira-functions + +# Setup your python virtual environment +python3 -m venv .venv +source .venv/bin/activate + +# Install the dependencies +pip3 install -r requirements.txt -To stop running locally, press ` + C` to end the process. +# Start your local server +python3 app.py +``` #### Linting @@ -67,7 +78,7 @@ ruff format ruff check --fix ``` -## Testing +#### Testing For an example of how to test a function, see `tests/functions/test_create_issue.py`. @@ -78,12 +89,17 @@ Run all tests with: pytest tests/ ``` -## Project Structure +## Using Steps in Workflow Builder + +With your server running, your function is now ready for use in +[Workflow Builder](https://api.slack.com/start#workflow-builder)! Add it as a +custom step in a new or existing workflow, then run the workflow while your app +is running. -### `.slack/` +For more information on creating workflows and adding custom steps, read more +[here](https://slack.com/help/articles/17542172840595-Create-a-new-workflow-in-Slack). -Contains `apps.dev.json` and `apps.json`, which include installation details for -development and deployed apps. +## Project Structure ### `manifest.json` @@ -106,8 +122,3 @@ group each listener based on the Slack Platform feature used, so `/listeners/views` handles [View submissions](https://api.slack.com/reference/interaction-payloads/views#view_submission) and so on. - -### `slack.json` - -Used by the CLI to interact with the project's SDK dependencies. It contains -script hooks that are executed by the CLI and implemented by the SDK. diff --git a/requirements.txt b/requirements.txt index 043e198..1c642e3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,3 @@ -slack-cli-hooks==0.0.2 slack-bolt==1.19.0rc1 requests==2.32.3 Flask==3.0.3