mirror of
https://github.com/Sea-Haven-Industries/afterhours-shift-manager.git
synced 2026-09-30 19:33:12 +00:00
4d0cdb5cfb
Slack Bolt app on Lambda for managing on-call shifts. Employees can pick up, drop, and swap shifts via /oncall commands. Changes update 3CX ring group 800 routing in real time for same-day shifts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
# After-Hours Shift Manager — Setup Guide
|
||
|
||
## 1. Create a Slack App
|
||
|
||
1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch**
|
||
2. Name: `After-Hours Shift Manager`, pick your workspace
|
||
3. Under **OAuth & Permissions**, add these **Bot Token Scopes**:
|
||
- `chat:write` — post messages to channels
|
||
- `commands` — register slash commands
|
||
- `chat:write.public` — post to channels the bot isn't in
|
||
4. Under **Slash Commands**, create a new command:
|
||
- Command: `/oncall`
|
||
- Request URL: `(fill in after deploy — see step 4)`
|
||
- Short Description: `Manage after-hours on-call shifts`
|
||
- Usage Hint: `[schedule | pick <date> | drop <date> | swap <date> @person | register <ext> | roster | help]`
|
||
5. Under **Interactivity & Shortcuts**, toggle **ON**:
|
||
- Request URL: same URL as the slash command (the `/slack/events` endpoint)
|
||
6. **Install to Workspace** — approve the permissions
|
||
7. Copy the **Bot User OAuth Token** (`xoxb-...`) and **Signing Secret** (under Basic Information)
|
||
|
||
## 2. Store Secrets in SSM Parameter Store
|
||
|
||
```bash
|
||
aws ssm put-parameter \
|
||
--name "/afterhours-shift-manager/slack-bot-token" \
|
||
--type SecureString \
|
||
--value "xoxb-YOUR-BOT-TOKEN"
|
||
|
||
aws ssm put-parameter \
|
||
--name "/afterhours-shift-manager/slack-signing-secret" \
|
||
--type SecureString \
|
||
--value "YOUR-SIGNING-SECRET"
|
||
|
||
# Channel ID where the bot will post weekly schedules
|
||
# (right-click channel in Slack → Copy link → the ID is the last segment)
|
||
aws ssm put-parameter \
|
||
--name "/afterhours-shift-manager/channel-id" \
|
||
--type SecureString \
|
||
--value "C0XXXXXXX"
|
||
```
|
||
|
||
## 3. Deploy the Stack
|
||
|
||
```bash
|
||
# Build and deploy
|
||
sam build
|
||
sam deploy --guided --stack-name afterhours-shift-manager --region us-east-1
|
||
|
||
# Note the SlackBotApiUrl output — you'll need it for step 4
|
||
```
|
||
|
||
## 4. Set the Slack Request URL
|
||
|
||
After deploy, copy the `SlackBotApiUrl` from the SAM output. Go back to your Slack app settings:
|
||
|
||
- **Slash Commands** → edit `/oncall` → set **Request URL** to the output URL
|
||
- **Interactivity & Shortcuts** → set **Request URL** to the same URL
|
||
|
||
## 5. Seed the Schedule
|
||
|
||
```bash
|
||
python scripts/seed_schedule.py
|
||
```
|
||
|
||
This populates the DynamoDB table with the employee roster and default weekly schedule.
|
||
|
||
## 6. Invite the Bot & Register Users
|
||
|
||
1. Create a channel (e.g. `#after-hours-shifts`) and invite the bot: `/invite @After-Hours Shift Manager`
|
||
2. Each employee links their Slack account by running:
|
||
```
|
||
/oncall register 114
|
||
```
|
||
(using their own extension number)
|
||
|
||
## 7. Update the 3CX Scheduler (optional)
|
||
|
||
To have the 3CX scheduler read overrides from DynamoDB (so Slack-driven changes apply to future dates automatically), deploy the updated 3CX scheduler from the `feature/dynamodb-shift-integration` branch. See that branch's changes for details.
|
||
|
||
Without this step, the Slack bot still works — it invokes the 3CX scheduler Lambda directly for same-day changes. Future-date overrides would only take effect if the scheduler reads DynamoDB.
|
||
|
||
## Commands Reference
|
||
|
||
| Command | Description |
|
||
|---|---|
|
||
| `/oncall` | Show this week's schedule |
|
||
| `/oncall next` | Show next week's schedule |
|
||
| `/oncall pick <date>` | Pick up a shift |
|
||
| `/oncall drop <date>` | Drop your shift (marks it open) |
|
||
| `/oncall swap <date> @person` | Hand your shift to someone else |
|
||
| `/oncall register <ext>` | Link your Slack to your extension |
|
||
| `/oncall roster` | Show all employees and their link status |
|
||
| `/oncall help` | Show help |
|
||
|
||
Dates can be: `today`, `tomorrow`, `monday`–`sunday`, `4/5`, `2026-04-05`
|