After-Hours Shift Manager

Slack bot for managing after-hours on-call shifts at Sea Haven Industries. Employees can pick up, drop, and swap shifts directly from Slack. Changes automatically update 3CX queue routing via the integrated ring scheduler.

How It Works

A recurring weekly schedule assigns employees to after-hours phone duty. Weekend shifts are split into Day (8am-5pm) and Night (5pm-8am). Any unassigned shift shows as Available in Slack with a pickup button. When someone picks up or drops a shift for today, the 3CX queue is updated immediately. Future changes take effect when the ring scheduler runs at 8am daily and 5pm on weekends.

The weekly schedule post is updated live when shifts change, and the previous week's post is automatically deleted when the new one goes out.

The bot also has an About page: open the bot in Slack and click its Home tab to see what it does, the full command list, and the latest "What's New" (see Releases & Versioning).

Slack Commands

Command	Description
/oncall	Show this week's schedule
/oncall next	Show next week's schedule
/oncall pick <date>	Pick up an available shift
/oncall drop <date>	Drop your shift (marks it available) — blocked within 24h of shift start; swap or ask an admin instead
/oncall swap <date> @person	Request a swap — the other person gets an Accept/Decline DM and the shift only moves once they accept
/oncall register <ext>	Link your Slack account to your phone extension
/oncall roster	Show all employees and their link status
/oncall pay	Show last week's bonus pay summary
/oncall rate	Show current shift pay rates
/oncall rate default <amount>	Set the default per-shift rate
/oncall rate <ext> <amount>	Set a per-person shift rate
/oncall help	Show help

Admin Commands

Available to users listed in admin_users in the CONFIG record:

Command	Description
/oncall admin override <date> <ext>	Assign a shift to an extension
/oncall admin open <date>	Mark a shift as open
/oncall admin clear <date>	Remove override (revert to weekly)
/oncall admin roster add <ext> <name>	Add an employee to the roster
/oncall admin roster remove <ext>	Remove an employee
/oncall admin roster rename <ext> <name>	Rename an employee

Dates accept: today, tomorrow, monday-sunday, 4/5, 2026-04-05

Architecture

• Runtime: Python 3.12 on AWS Lambda (arm64)
• Data: DynamoDB single-table (afterhours-shifts)
• IaC: AWS SAM (template.yaml) with shared Lambda Layer
• Slack: Slack Bolt framework with /oncall slash command
• 3CX Integration: Queue routing updated directly via 3CX Queue XAPI
• Secrets: AWS Secrets Manager (afterhours-shift-manager/*)

Lambda Functions

Function	Trigger	Purpose
afterhours-shift-manager	API Gateway (POST /slack/events)	Slack bot — handles /oncall commands and interactive buttons
afterhours-weekly-post	EventBridge (Monday 7am ET)	Posts weekly schedule to Slack, sends pay report email
afterhours-roster-sync	EventBridge (daily 6am ET)	Syncs employee roster from 3CX
afterhours-ring-scheduler	EventBridge (daily 8am ET + weekend 5pm ET)	Updates 3CX queue routing based on who's on shift
afterhours-release-notifier	Invoked by the Deploy workflow's release job on minor/major releases	Posts a "What's New" announcement to the shift channel

Project Layout

src/
  slack-bot/         Slack Bolt Lambda (handler + app); ships CHANGELOG.md for App Home
  weekly-post/       Monday schedule + pay post
  roster-sync/       Daily 3CX roster sync
  ring-scheduler/    3CX queue routing updates
  release-notifier/  Posts release announcements to Slack
  shared/            Lambda Layer (schedule, blocks, changelog, 3CX client, secrets)
scripts/             changelog CLI + CI guard + in-package copy sync
tests/               pytest suite (mirrors src/, one dir per Lambda + shared)

DynamoDB Schema

Single table with PK / SK keys:

PK	SK	Description
ROSTER	<extension>	Employee: name, extension, slack_user_id
WEEKLY	<DayName>	Default weekly schedule: extension, name
OVERRIDE	<YYYY-MM-DD>	Date override from pickup/drop (or OPEN)
SWAP	<YYYY-MM-DD>	Pending/verified swap request: requester, target, status, expires_at (TTL)
SCHEDULE_POST	<channel_id>	Current schedule message timestamp
PAY	<YYYY-MM-DD>	Weekly pay record (Monday date key)
CONFIG	CONFIG	Settings: shift_rate, fallback_extension, admin_users

Weekend day-shift rows use a -DAY suffix on the SK (e.g. OVERRIDE / 2026-04-05-DAY). The table has TTL enabled on expires_at so abandoned pending swaps self-clean.

Swap flow: /oncall swap writes a pending SWAP record and DMs the target Accept/Decline buttons; it does not reassign the shift. On Accept, the override is written, 3CX is repointed if it's the active shift, and the record is marked verified. On Decline (or once the shift has started) the request is dropped and the shift stays with the original owner.

Secrets Manager

Secret	Description
afterhours-shift-manager/slack-bot-token	Slack bot OAuth token (xoxb-...)
afterhours-shift-manager/slack-signing-secret	Slack app signing secret
afterhours-shift-manager/3cx-domain	3CX FQDN (e.g. company.3cx.us)
afterhours-shift-manager/3cx-client-id	3CX OAuth2 client ID
afterhours-shift-manager/3cx-client-secret	3CX OAuth2 client secret

Deployment

Merges to main are automatically deployed via GitHub Actions using reusable SAM workflows from the Sea Haven org.

For manual deploys:

sam build
sam deploy

Releases & Versioning

The bot is versioned with SemVer, driven entirely by CHANGELOG.md — it is the single source of truth for both the version number and the human-readable notes. There is no separate tagging tool.

To cut a release, in your feature PR add a new ## vX.Y.Z — Month D, YYYY section at the top of CHANGELOG.md (plain language, written for on-call staff), bumping per SemVer, then run python scripts/sync_changelog.py to update the in-package copy. The Changelog Guard PR check enforces that the bump is a clean single SemVer step above the latest tag and that the two copies match.

On the deploy-then-merge path, once the merge's Deploy succeeds, the Deploy workflow's release job (needs: deploy) tags the new version, publishes a GitHub Release with the notes, and — for minor and major bumps only (patches stay silent) — invokes afterhours-release-notifier to post a "What's New" message in the shift channel. The App Home tab ("About" page on the bot) always shows the current version's notes, read from the CHANGELOG that ships in the slack-bot package.

The release job lives inside the Deploy workflow (gated on needs: deploy) rather than a separate workflow_run-triggered workflow. A push-to-main run is a trusted context, so checking out and running repo code with write/OIDC is safe — whereas workflow_run is flagged by CodeQL for untrusted checkout. Gating on needs: deploy still guarantees we never announce a version that isn't live.

One-time setup (per environment): after the first deploy creates the ReleaseNotifyInvokeRole, copy its ARN from the ReleaseNotifyInvokeRoleArn stack output into the repo variable RELEASE_NOTIFY_INVOKE_ROLE_ARN (Settings → Secrets and variables → Actions → Variables). Until it's set, releases still tag and publish but skip the Slack announcement (with a warning).

Convention note (deliberate deviation). The Sea Haven handbook says internal SAM stacks generally need no versioning and that tags are applied manually. This bot is versioned by owner choice (it has staff-facing release notes) and tagged automatically by the Deploy workflow's release job. This is intentional — not drift.

Testing

Unit tests use pytest with all external boundaries mocked — DynamoDB / SES / Secrets Manager via moto, 3CX HTTP via responses, Slack via fakes, and time via freezegun. No test touches the network or real AWS.

python -m venv .venv && source .venv/bin/activate
pip install -r tests/requirements.txt              # test-only deps
pip install -r src/slack-bot/requirements.txt \
            -r src/weekly-post/requirements.txt \
            -r src/shared/requirements.txt          # runtime deps the imports need
pytest

Each Lambda has its own app.py, so the per-package conftest.py loads each one under a unique module name (importlib mode) to avoid collisions. CI runs the same suite on every PR via the org ci-python-sam workflow (run-tests: true).

See SETUP.md for full deployment and Slack app creation instructions.