Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Phorest Rotations

Named rotations for a Slack workspace. Each rotation has people in order, a schedule, a reminder message and, optionally, a Slack group (for example @support-on-call) that always points at whoever is on duty.

At the scheduled time the bot posts the reminder in a channel. It skips anyone who is away according to their Slack status and moves the turn on. A web dashboard shows every rotation and is where most settings are changed.

What it does

  • Reminders post on a daily or weekly schedule, in any timezone. Weekly rotations can post on several days of the week, and can repeat every 1 to 52 weeks.
  • Automatic skipping: before each reminder, the app checks each person's Slack status. If it says OOO, holiday, sick, or has an away emoji (such as 🌴), that person is passed over and keeps their place in the queue.
  • Skip turn (in the reminder and on the dashboard) moves on to the next person. The reminder is updated in place, so the channel does not fill up.
  • Slack group (optional): a Slack user group with a handle such as @support-on-call. Its member is updated to the person on duty at every handover.
  • Owners: the person who creates a rotation owns it. Only the owner can change its settings, message, people, order or Slack group, delete it, or transfer it to someone else. Anyone signed in can post a reminder now or skip a turn.
  • Dashboard (http://localhost:3000): sign in with Slack, see every rotation, search, filter to "Owned by me", drag to reorder, add or remove people, make someone's turn, change the schedule, edit the message with a live preview, post now, skip, pause, transfer or delete.
  • Slack commands: /rotation creates a rotation, /rotation edit <name> edits one (owner only), /rotation list lists them.

How it works

Each rotation keeps an ordered list of people and a pointer to whoever is on duty. When a reminder posts, the pointer moves to the next person, so the message names the person on duty and the one after them. Skipping someone who is away happens at posting time: the scheduler walks the queue from the current person and stops at the first person Slack does not show as away. Passed-over people stay in place.

The scheduler runs every minute. It also keeps each Slack group pointed at the current person.

Signing in with Slack uses Slack's OpenID Connect flow. The signed-in Slack user ID is what the app compares with a rotation's owner, so ownership works across the dashboard and Slack commands.

Setup

1. Create the Slack app

Go to https://api.slack.com/apps, choose Create New App → From a manifest, select the Phorest workspace, and paste the manifest below. Then review and create the app.

{
  "display_information": { "name": "Phorest Rotations", "description": "Named rotations with reminders and a dashboard" },
  "features": {
    "bot_user": { "display_name": "Phorest Rotations", "always_online": true },
    "slash_commands": [
      { "command": "/rotation", "description": "Create, edit or list rotations", "usage_hint": "[edit <name> | list]", "should_escape": false }
    ]
  },
  "oauth_config": {
    "redirect_urls": ["http://localhost:3000/auth/slack/callback"],
    "scopes": {
      "bot": ["commands", "chat:write", "channels:read", "groups:read", "users:read", "usergroups:read", "usergroups:write"]
    }
  },
  "settings": {
    "interactivity": { "is_enabled": true },
    "org_deploy_enabled": false,
    "socket_mode_enabled": true,
    "token_rotation_enabled": false
  }
}

If you deploy the dashboard somewhere else, add that address too, ending in /auth/slack/callback. Redirect URLs must match exactly, and Slack saves them only after you click Save URLs.

2. Collect the values for .env

  • App-level token (Basic Information → App-Level Tokens → Generate, scope connections:write): starts with xapp-.
  • Bot token (Install App → Install to workspace): starts with xoxb-. Reinstalling the app can issue a new one, so update .env afterwards.
  • Signing secret, Client ID and Client Secret (Basic Information → App Credentials).
  • Team ID (optional, starts with T): restricts sign-in to one workspace.

Never commit or paste these values anywhere public.

3. Configure and run

  1. Copy .env.example to .env and fill in the values.
  2. Run npm install.
  3. Run npm start. You should see "Dashboard on http://localhost:3000" and "Rotation app running (Socket Mode)". Stop it with Ctrl+C.
  4. In each channel where reminders should post, type /invite @Phorest Rotations.

Slack needs the redirect address to be reachable with the same spelling as in the app settings. For testing outside your own machine, a tunnel such as cloudflared tunnel --url http://localhost:3000 works. Set DASHBOARD_URL in .env to the tunnel address and add the matching redirect URL in Slack.

Using it

Creating a rotation. Either run /rotation in Slack or click New rotation on the dashboard. You become the owner. Choose a name, a channel, the people in turn order, the schedule (weekly or daily, days, repeat every N weeks, time and timezone), and the message. Keep the Slack group option on if people should mention a handle instead of one person.

The message. Use {person} for the person on duty and {next} for the person after them. Names become @mentions in Slack. The dashboard shows a live preview.

Changing a rotation. Owners can use the dashboard or /rotation edit <name>. Everyone else sees it as "View only."

Transferring ownership. The owner picks someone in the Transfer ownership section. The new owner is then the only one who can change the rotation.

Posting and skipping. Anyone signed in can press Post now or Skip turn, on the dashboard or on the reminder.

Settings you may want to change

  • Away words and emoji: src/availability.js, the DEFAULT_WORDS and DEFAULT_EMOJI lists. Words match whole words, so "Oooh" does not count as OOO.
  • Timezones in the dropdown: src/timezones.js.
  • Status cache: Slack statuses are cached for five minutes, so a change can take up to five minutes to count.
  • Slack directory: the people and channel lists come from Slack and are cached in data/directory.json. Press Refresh on the dashboard to reload them. Slack rate-limits these calls, so avoid repeated presses.

Data

Rotations are saved in data/rotations.json (or the path in DATA_FILE), and the Slack directory cache in data/directory.json. Both are created on first run and are not committed to git. Back up data/rotations.json to keep your rotations.

Permissions

The app asks Slack for:

  • commands, to provide /rotation
  • chat:write, to post and update reminders
  • channels:read and groups:read, to list channels for the forms
  • users:read, for names, photos and status
  • usergroups:read and usergroups:write, to keep a Slack group pointed at the person on duty

Sign-in asks only for the OpenID profile, which gives the name, photo and workspace of the person signing in. The app does not read messages or channel history.

Tests

Run npm test. The unit tests cover rotation logic, schedules (including every-N-weeks), availability, skipping, ownership and the Slack group settings. Two HTTP tests in test/access.test.js need express, which is installed by npm install.

Files

  • src/index.js: starts Slack, the scheduler and the dashboard; sets up the Slack group update.
  • src/slack.js: /rotation command, create form, Skip button.
  • src/edit.js: /rotation edit form (owner only).
  • src/service.js: shared operations, turn resolution, posting, Slack group sync.
  • src/rotations.js: pure rotation logic (turn order, schedules, message templates, handles).
  • src/availability.js: reads Slack status and decides who is away.
  • src/reminder.js: builds the reminder message and Skip button.
  • src/auth.js: Sign in with Slack and sessions.
  • src/dashboard.js and src/public/index.html: the web dashboard and its API.
  • src/timezones.js: timezone list for the forms.
  • src/store.js: JSON file storage.
  • test/: unit and HTTP tests.

Known limits

  • If everyone is away, the reminder still goes to the current person and says so.
  • The "Next up" line shows the next person in order, even if they are away. They are skipped when their turn comes.
  • Rotations created before owners were introduced have no owner, so any signed-in person can change them until one is set.
  • Sessions are kept in memory, so signing in again is needed after the server restarts.
  • The Slack /rotation command does not set up a Slack group yet. Use the dashboard for that.
  • Slack's rate limits apply to the Refresh button, which reloads the people and channel lists.
  • Test in a private channel first. Reminders are real Slack messages.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages