LogBot is a Slack bot integration designed to effortlessly capture a log of productivity in your Slack team.
Slack administrators assign members various roles, such as Staff
or Intern
, and each role can be assign a trigger. A trigger describes a series of questions that LogBot asks users, and which human responses are acceptable, and what is calculated to be logged for productivity hours.
When the conditions are true (e.g., "every Friday at 4pm", "every day at 3pm granted users have logged in at least once during the day"), LogBot asks each user associated to the role a simple question (as described by the trigger) and captures the output of the user.
Administrators can then query LogBot of the logs for certain users or roles, and then assess the productivity of those users based on what the user has logged. LogBot returns back a CSV of data via a temporary one-click URL.
- Begin by installing Node.js on your system. You can download Node.js here.
- Install dependencies by running
npm install
- Start LogBot by running
npm start
.
A configuration file for LogBot settings is needed, config.json
. Place this file in the log-bot
root directory. Here's a sample:
{
"botToken": "xoxb-xxxxxxx-xxxxxxxxxxxx",
"triggerFile" : "triggers.json",
"datastoreDirectory" : "res",
"server" : {
"ip" : "xxx.xxx.xxx.xxx",
"port" : 3000
}
}
botToken
Your auth token for the bot you have created on SlacktriggerFile
Where your trigger file is located. Can be an absolute path, otherwise is it relative to thelog-bot
root directory. If you want to place this file alongside that ofconfig.json
, then just leave this astriggers.json
datastoreDirectory
A relative or absolute path for where LogBot can store data.server
The serverip
andport
which LogBot hosts its data server from the machine it is run on.
A trigger configuration describes possible triggers. The JSON file can be commented with //
comments inside this JSON file to help keep your file organised.
There is a commented example triggers.json
that you can read through and model your own triggers from.
There are two required root fields in the trigger file:
workDay
A number to describe the typical working hours expected in your team in a working day.triggers
An object containing keys for each of your various triggers.
Each key inside the triggers
object is the unique name of that trigger. A trigger's unique name can only contain alphanumeric, spaces, dashes and underscore characters. A trigger will typically contain four keys:
question
The initial question to prompt to the user when the trigger is fired.helpText
An optional help text, usually to provide help on which answers are acceptable for the question askedresponses
An object containing response/action bindings (see below)conditions
Conditions which the fire trigger
Inside the responses
object should contain key/value bindings to regular expressions (key) and the appropriate action (value) LogBot takes when the regular expression is matched against user responses.
If the action is a string, it should represent either a mathematical expression that will return the number of hours to log, or signal LogBot to reask the question. You can use workDay
in the expression calculated, $1
to use the answer the user has entered captured by the regular expression, or $!
to make LogBot re-ask the trigger from its initial question. For example:
"\d" : "$1", // Use the integer captured by the regular expression
// "\d" for the hours logged
"yes|y" : "5 * workDay", // Where the user responds "yes" or "y", use five
// mulitplied by one workDay for the hours logged
"no|n" : "$!" // Where the user responds "no" or "n", ask the
// question again
If the action is an object, then a follow-up question is asked, each with its own question
, helpText
and responses
keys/values. Note that LogBot will keep asking questions until the question is resolved to a string-based action (i.e., to a concrete hour duration it can use to log the hours worked).
At present, two conditions are currently supported:
time
, a cron-formatted time value for when the trigger is fired.loggedInToday
, resolving to eithertrue
orfalse
, to check whether the user the trigger is being applied to has signed in to Slack at least once.
The time
is mandatory and should be present in every trigger you write.
As a Slack administrator user, you will have the ability to create new roles, assign other Slack users to roles, and assign roles various triggers, using an SQL-esque DSL. Admin users can interact with LogBot by issuing these commands via sending it an IM.
Note that when communicating with LogBot, Role and Trigger names must be encapsulated with double quotes. Users must be referenced using Slack's @someone
syntax.
Note that when creating roles, a role name can only contain alphanumeric, spaces, dashes and underscore characters.
Use the HELP
command to see what LogBot knows.
ADD ROLE "Intern Staff"
Creates a new role named "Intern Staff"ASSIGN @freddy ROLE "Intern Staff"
Assigns the user who's tag is@freddy
the newly created role "Intern Staff"GET ROLES FOR @freddy, @frankey, @jerry
Gets roles for@freddy
,@frankey
and@jerry
DROP ROLE "Intern Staff"
Will remove theIntern Staff
role, and in this case@freddy
will be unassigned his roleGET ALL ROLES
Get every role that LogBot knows of
GET LOG FOR @freddy
Will generate the download link for@freddy
's logsGET LOGS FOR "Intern Staff", "Full Time Staff"
Will generate the download link for these rolesGET ALL LOGS
Will generate the download link for every log available
GET ALL TRIGGERS
Get every trigger that is availableGET TRIGGER FOR "Intern Staff"
Will return the triggers associated to the roleIntern Staff
FIRE ALL TRIGGERS NOW
Will fire every trigger registered right now, regardless of when they're supposed to be triggered
As a standard Slack user, your interaction with LogBot is very limited. Like Slackbot, LogBot will ignore what you say. The only time LogBot will listen to you is when a trigger fires and asks you a question, of which you have at least six hours to respond.
Have an idea to extend this project or discover a bug? Feel free to contribute or raise an issue!
To extend the code base, use the following steps:
- Fork this repo,
- checkout a new feature or fix branch:
feature/<my-feature-name>
,fix/<issue>
etc., - commit your changes. A good guide to commit messages can be found here,
- and create a pull request.
- Prioritise environment variables over
config.json
- Add some screenshots or videos of the bot in use
Copyright © 2015 Alex Cummaudo. Licensed under the MIT license.