Slack Integration¶

machine-access-control (MAC) offers a Slack integration for logging and control.

Setup¶

To set up the Slack integration:

Create a new Slack app
1. Create your new app “from scratch”.
2. Set a meaningful name, such as machine-access-control and create the app in your Workspace.
3. In the left menu, navigate to OAuth & Permissions.
4. In the “Scopes” pane, under “Bot Token Scopes”, click “Add an OAuth Scope” and add scopes for app_mentions:read, canvases:read, canvases:write, channels:read, chat:write, groups:read, groups:write, incoming-webhook, users.profile:read, and users:read.
In your workspace, create a new private channel for admins to interact with MAC in, and MAC to post status updates to.
In the left menu, navigate to Install App. Click on the button to install to your workspace. When prompted for a channel for the app to post in, select the private channel that you created in the previous step.
On the next screen, Installed App Settings, copy the Bot User OAuth Token and set this as the SLACK_BOT_TOKEN environment variable for the MAC server.
Go back to the main settings for your app and navigate to Socket Mode under Settings on the left menu; toggle on Enable Socket Mode. For Token Name, enter socket-mode-token and click Generate. Copy the generated token and set it as the SLACK_APP_TOKEN environment variable for the MAC server. If you need to retrieve this token later, it can be found in the App-Level Tokens pane of the Settings -> Basic Information page.
Go back to the main settings for your app and navigate to Basic Information under Settings on the left menu; in the App Credentials pane click Show in the Signing Secret box and then copy that value; set it as the SLACK_SIGNING_SECRET environment variable for the MAC server.
Go back to the main settings for your app and navigate to Event Subscriptions under Features on the left menu; click the toggle in the upper left of the panel to Enable Events; under Subscribe to bot events add a subscription for app_mention.

Configuration¶

Set Environment Variables as described in Setup, above.
If you don’t already have one, create a private channel for the people who will be allowed to control MAC (i.e. clear Oopses and lock-out/unlock machines).
Invite your bot user to that channel by at-mentioning the bot username.
In that channel, click on the channel name to pull up the channel information tab, and copy the Channel ID (a string beginning with “C”) from the bottom of that panel. Set this as the SLACK_CONTROL_CHANNEL_ID environment variable.
If you don’t already have one, create a public channel for the bot to post Oops/maintenance notices in. Invite the bot to that channel via an at-mention. Get the Channel ID and set it as the SLACK_OOPS_CHANNEL_ID environment variable. Users in this channel will also be able to check machine status.

Usage¶

The slack bot is controlled by mentioning its name (@your-bot-name) along with a command and optional arguments, in the SLACK_CONTROL_CHANNEL_ID channel (or, for the status command, any channel that the bot is in).

Using an example bot name of @machine-access-control, the supported commands are:

@machine-access-control status - List all machines and their current status. This command is the only one that is usable from channels other than the control channel.
@machine-access-control oops <machine-name> - Set Oops’ed status on the machine with name machine-name. This takes effect immediately, even if the machine is currently in use. You can use either the machine name or its alias (if configured).
@machine-access-control lock <machine-name> - Set maintenance lock-out status on the machine with name machine-name. This takes effect immediately, even if the machine is currently in use. You can use either the machine name or its alias (if configured).
@machine-access-control clear <machine-name> - Clear all Oops and/or maintenance lock-out states on the machine with name machine-name. You can use either the machine name or its alias (if configured).

Note: If a machine has an alias configured in machines.json, the bot’s responses will use the alias instead of the machine name for better readability.

In addition, changes to all machines’ Oops and maintenance lock-out states will be posted as messages in the SLACK_OOPS_CHANNEL_ID channel.

Override Login Notifications¶

When a user with oops_override authorization performs an override login on an oopsed or locked-out machine, a notification is posted only to the SLACK_CONTROL_CHANNEL_ID channel with the format:

Override login on <machine name> by <user name>.

No notification is posted to the SLACK_OOPS_CHANNEL_ID channel for override events. This prevents confusing “un-oops” or “unlock” messages from appearing in the public channel when repair members are testing machines. When the override user removes their card, a logout message is posted to the control channel with an (override session) suffix.

Second Relay Messaging¶

For machines configured with a second relay, Slack admin-channel messages include additional context about the accessory:

RFID login by an operator authorized for both relays:

RFID login on <machine> by authorized user <user>; <accessory> authorized

RFID login by a primary-only operator (second relay denied):

RFID login on <machine> by authorized user <user>; <accessory> NOT authorized — relay off

RFID login when unauthorized_warn_only is set on the second relay:

RFID login on <machine> by authorized user <user>; <accessory> WARN-ONLY override — relay on

RFID login when always_enabled is set on the second relay:

RFID login on <machine> by authorized user <user>; <accessory> always-enabled — relay on

The token <accessory> resolves to second_relay.alias if set, otherwise the literal second relay. For second-relay-equipped machines, RFID logout messages append the text ; both relays off to the admin-channel message. Control-channel lock, unlock, oops, and unoops messages include (both relays) in the message text; the public oops-channel messages are unchanged.

Single-relay machine messages are unchanged.