Kippino, the KPI bot
This is a Slack bot that asks people about KPIs
Check out the announcement post on our tech blog.
$ npm install $ ./node_modules/typescript/bin/tsc
To run the bot you'll need:
- if your spreadsheet is private: a Service Account auth JSON for the Google Spreadsheet API, follow these instructions to get one.
- the spreadsheet ID: it's the alphanumeric string after
https://docs.google.com/spreadsheets/d/in the URL of your Google Spreadsheet
- the token for your Slack bot: follow these instructions to get one for your bot
Then you can run the bot by passing the above with env vars:
$ AUTH_JSON=./xxx.json SLACK_TOKEN=XYZ SPREADSHEET_ID=ABC \ node build/index.js
AUTH_JSON variable is only required if your spreadsheet is private.
Remember to share read/write access on the spreadsheet to the service account email that you created.
Running without authentication
In case you're running the bot without authentication (i.e. without setting
you'll have to publish the spreadsheet to the web (File > Publish to the Web).
You can find more details here.
Running on Heroku
The Heroku deploy button currently only works for public spreadsheets that don't require authentication.
Never heard of Heroku? Here's how to install it: https://youtu.be/8lzdCWoiDbY
At start, the bot will create the
Data worksheets if they don't exist yet.
KPIs worksheet is where you put the KPIs you want to track. Each KPI must have the following attributes:
name: an alphanumeric unique identifier for the KPI
question: this is the text that gets used to create the question together with the period (for instance if the
How many customer signed upand the period is
May 1st, 2016, then the bot will ask
How many customer signed up on May 1st, 2016?)
owner-slack: the Slack username of the user that will be asked about this KPI (this may be different from the name that you see in the chat, you can look up the username on the Slack profile of the user)
frequency: how often to collect the value of this KPI (
since: the date (
YYYY-MM-DD) since you want to track this KPI - in case of weekly KPIs it must be the Monday of that week, in case of monthly KPIs it must be the 1st day of that month.
kippino-enable: set this to
yesif you want to enable this KPI.
Data worksheet is where Kippino puts the values collected from your team. Each data point has the following attributes:
timestamp: ISO formatted timestamp for when the value was captured
kpi: the KPI name
value: the KPI value
for: the date associated to the period that this value refers to (same convention used by the
source: the user that provided this value
The bot accepts the following commands:
helpprovides a brief description of the bot and the list of commands
sync KPIsreloads the list of KPIs (this is also done every hour)
sync usersreloads the list of Slack users (this is also done every hour)
list KPIslists the configured KPIs
pendinglists the users that have pending questions (i.e. the bot asked them for a KPI but they didn't respond yet)
You can run Kippino via Docker, there's already a pre-built docker image or you can build your own from the provided
$ docker run \ -v ./auth.json:/auth.json \ -e AUTH_JSON=/auth.json \ -e SLACK_TOKEN=xyz \ -e SPREADSHEET_ID=abc \ --name kippino measurence/kippino
Kubernetes / Google Container Service
You can easily deploy Kippino on a Kubernetes cluster with the following config. The authentication JSON and the Slack token should be configured as secrets.
--- apiVersion: extensions/v1beta1 kind: Deployment metadata: name: kippino labels: app: kippino spec: strategy: type: Recreate template: metadata: name: kippino labels: app: kippino spec: volumes: - name: kippino-google-auth secret: secretName: "kippino-google-auth" containers: - image: "measurence/kippino:latest" name: kippino volumeMounts: - name: "kippino-google-auth" mountPath: "/kippino-google-auth/" readOnly: true env: - name: SLACK_TOKEN valueFrom: secretKeyRef: name: kippino key: "slack-token" - name: SPREADSHEET_ID value: "XYZ" - name: AUTH_JSON value: "/kippino-google-auth/auth.json" resources: requests: cpu: 0.1 memory: "256Mi" limits: cpu: 0.1 memory: "256Mi"
Dealing with user timezone and online status
Currently the bot is quite stupid and it will start asking questions as soon as a new day starts in the bot timezone.
It will also keep waiting for an answer "forever", it doesn't keep "nudging" people until they respond.
Spreadsheet locale and number formatting
Make sure that your spreadsheet is configured in the US locale since the bot uses
parseFloat to parse numbers in the US format (using
. as decimal
Dates in the spreadsheet must be formatted as
For weekly KPIs, the
since field must be set to the Monday of the week you want to start collecting the KPI.