Synergy is a bot mostly for interacting with LiquidPlanner. Her primary purpose is to remind a user that they haven't got a timer running. During business hours, she will pester her user if a timer isn't running, escalating from one form of contact to another. She can be told to lay off. Synergy can respond to commands via SMS and other channels, too.
No warranty is expressed or implied.
Installation and Usage
Install all the prereqs. This is mostly easily done with Carton.
$ carton install
You need to set up a configuration file in YAML or JSON format. Look at the example file to see what config options are expected, because they're not documented yet. Run the program like this, more or less:
$ carton exec perl synergy -c /path/to/config/file.json
(Caveat: this is as of early August 2020. The Slack API changes pretty frequently, and in weird ways, so your mileage may vary.)
If you want to make your own Synergy clone:
- Go to https://api.slack.com/rtm, scroll all the way to the bottom, click "Create a classic app." Synergy is built on top of Slack's Real-Time Messaging API, which uses a websocket connection. Slack is now discouraging this for new apps, which is too bad because eventually I suspect they'll get rid of it and we'll have to rewrite hunks of Synergy again.
- On the app page, click "Bots," then "Add a legacy bot user." Give it a name.
- Maybe: update scopes. Important: you must do this from the "OAuth &
Permissions" page, not the bot user page. Go there, click "add an OAuth
scope" (not "Update Scopes"), and add what you need. At time of writing,
Synergy only needs the
usergroups:writescope, for exactly one thing: the VictorOps reactor uses it to update the oncall Slack usergroup. If you're not messing with that code, you shouldn't need to add this.
- Once the app is installed, the OAuth & Permissions page should have two
tokens. The "bot user access token" (starts with
xoxb-) is used for the slack channel's
api_key. The "OAuth Access Token" (starts with
xoxp-, and is probably longer) is the
There may be other, slightly more obscure things, but the above should be enough to get you up and running.
Commands for Everyone
(Warning: this section is probably out of date, especially after the v2 rewrite.)
page USER: This will send an SMS to the user, who must be the master user. Anyone can use this command.
page USER: MESSAGE: This will send the message as an SMS to the user, who must be the master user. Anyone can use this command.
task for USER: DESC: This will create a new task for the named user and report the URL. Anyone can use this command. Because of the LiquidPlanner auth system, one LP user is used to make every task, meaning that the "created by" field becomes less reliable. The user who asked for the command is noted in the task's initial description.
remind USER [ at TIME | in DURATION ] [with page]?: REMINDER: This command schedules a message to be send to the given user on the current channel. It doesn't check that the user is present now or later. It can be told to send a page, too.
alerts: This lists all active alerts in Circonus.
ack ALERTID for TIME: This acks the identified alert for a while.
oncall: This lists who is on call in Circonus.
oncall add USER [ USER... ]: Add users to the list of on call users.
oncall remove USER [ USER... ]: Remove users from the list of on call users.
oncall set USER [ USER... ]: Totally replace the contents of the on call group.
Commands for the Master User
Because LiquidPlanner doesn't for a token that can manipulate aspects of other users' timers, these commands only work for the user whose credentials are used for LiquidPlanner. In the future, this could be tweaked to allow many sets of credentials to be stored.
status: Synergy will tell you whether you've got a timer running.
commit: MESSAGE: Synergy will commit your current timer's time and add a comment given in your message. If it ends with "DONE", that will be removed and the task will be marked complete. Otherwise, time timer will start running again from zero.
stop timer: Synergy will stop your timer, leaving its time in place.
abort timer: Synergy will stop your timer and clear your timer.
chill [ for DURATION | until TIME ]: This tells Synergy not to nag you until later.
showtime: This tells Synergy to cancel any grace period. In the future, this will be used to start nagging outside of normal business hours.
show's over: This tells Synergy that you're done for the day, and not to nag you until the next business day.