/advocated

• This repostory holds the original version of Advocated. The one based on Envoy. The new serverless one has replaced this and is now the current versiojn *

Advocated is a Developer Advocacy metrics collection application. It allows a Developer Advocate to record

• the meetups/conferences they went to
• the talks they delivered
• the blogs they published
• the press interviews they gave
• the expenses they spent

Advocated is built as an Offline-First web application. Data is stored in PouchDB in a web browser and synced to a Cloudant database at a later date. This allows data to be collected in the most remote of locations, even when there's no network connection.

Built with Envoy

Instead of replicating directly with Cloudant, Advocated has Cloudant Envoy baked in which means although it appears that each user has their own database (in a one-database-per-user design pattern), Envoy actually stores the data in a single database on the server side which makes it easier to query all the Advocates' data in one place.

Installing

Clone this repository and run npm install to fetch its dependencies. It needs 'admin' access to a Cloudant account so create an environment variable called COUCH_HOST containing the full URL of your Cloudant account e.g.

export COUCH_HOST="https://myusername:[email protected]"

Databases

This app uses several Cloudant databases:

• envoy - where all the user data is stored
• envoyusers - the collection of users who can authenticate
• teams - a collection of Slack teams
• groups - a collection of arbitrary groups of users for reporting purposes
• tokens - a collection of one-time authenticaton tokens

Teams

Advocated authenticates via a Slack "slash command". You can have as many Slack accounts as you like simply

• create a Cloudant database called 'teams'
• create a new Slack 'slash command' pointing to the POST <yoururl>/slack endpoint of your Advocated install - make a note of the token
• create a new incoming webhook in your Slack admin - make a note of the URL
• in Cloudant, create a new document in the "teams" database

{
  "_id": "<team_id>",
  "type": "team",
  "name": "Team Name",
  "slack": {
    "token": "<the token from the command>",
    "webhook": "<the webhook url>"
  }
}

You can obtain your team_id here.

Authentication

Authentication is via the Slack "slash command". It can also be simulated using curl

> curl -X POST -d 'token=<the token from the command>&user_id=<unique slack user id>&team_id=<unique slack team id>&text=woo&user_name=glynn.bird' 'http://localhost:6016/slack'
Thanks for advocating. Please visit this URL to enter the details <https://localhost:6016/?token=8e6d6729-fbd1-4ad5-93bb-e6f8c8db6bff#token.html>

Note: when running locally you may have to change "https" for "http" for the url to work.

Differences with version 1

Data location

In the first version of /advocated the users themselves were stored in the same database as the sessions, events, blogs etc. When using Envoy, this is not possible. Envoy stores its users in a 'envoyusers' database and the format of the JSON is different.

• teams - one document per Slack account
• envoyusers - one document per user
• advocated2 - the database containing all the sessions/events/blogs/etc for all users
• tokens - one document per issued login token.

HTML Templating

In the first version the HTML was generated server-side using Jade templates using a custom CSS stylesheet. The new version uses the MaterializeCSS framework and Mustache client-side templates.

Slack posting

In the first version, all new postings came through the Node.js app and were posted to Slack. In the new version, new postsings are saved to each users' PouchDB database. Only when the database is synced can the Slack posting be made. The server-side app listens to changes on the database where postings are stored and posts any changes that result in a new 'rev=1-*' document.