openaustralia / jacaranda

a watchful tree and slack messenger to keep you informed of the use of PlanningAlerts


Jacaranda

A watchful tree and extensible Slack messenger to keep you informed of how your civic tech projects are being used.

Not everything that can be counted counts, and not everything that counts can be counted. (Albert Einstine, on the wall of his study in Princeton. Quoted in Can We Know Better?, Robert Chambers, 2017)

This project is an attempt to get useful information about how a project is used, to the people who maintain, run, and build it.

While working on PlanningAlerts we’ve noticed that:

  • We don’t have an accurate idea of the impact of PlanningAlerts, how many people are using it, or the rate a which this is changing; and
  • We feel more energised in our work when we get feedback about it’s use and impact.

Jacaranda is an experiment to see the impact of regular feedback on the people developing PlanningAlerts. It aims to keep you more informed of the use and impact of PlanningAlerts; to remind you of the effort you’ve put in to achieve this; and to do this in an quick and unobtrusive way.

Jacaranda collects information about people using PlanningAlerts and the work we do to make it better for them. It then sends a short fortnightly message to our Slack channel to give us a sense of how things are going.

Image of slack message from Jacaranda

This is a very basic start. We’ve interested to see how getting these messages impacts us and what we do with the information.

PlanningAlerts message

Currently Jacaranda tells you about:

  • the number of people who signed up for PlanningAlerts in the last fortnight;
  • the difference between this number and the figure for the previous fortnight;
  • the number of people who have unsubscribed in the last fortnight;
  • the difference between this number and the figure for the previous fortnight;
  • the number of commits pushed to the project in the last fortnight; and,
  • the total number of people now signed up to PlanningAlerts.

While the number of users isn’t a great measure of PlanningAlerts’ impact, it’s a start to see how the feedback works for us. Feel free to change the text or the information in presents to what you think will have a better impact.

Caveats

The time frames that this claims to show subscribers for aren’t accurate because they're displayed as it they were recorded in local time, but they're actually counted in UTC.

Right To Know message

Currently Jacaranda tells you about:

  • The number of new requests in the last fortnight
  • The number of annotations in the last fortnight
  • The number of requests that were successful in the last fortnight

Quickstart

Ensure you have Ruby + Bundler installed, then run:

bash git clone https://github.com/openaustralia/jacaranda.git cd jacaranda bundle

Then run the scraper with:

bash bundle exec ruby scraper.rb

And run the tests with:

bash bundle exec rspec

Usage

This scraper requires these environment variables:

  • MORPH_SLACK_CHANNEL_WEBHOOK_URL to post the message to a channel in Slack. You can get a URL by adding an Incoming Webhook customer integration in your Slack org.
  • MORPH_LIVE_MODE determines if the scraper actually posts to the Slack channel #townsquare and save to the database

When developing locally, you can add these environment variables to a .env file so the scraper loads them when it runs:

bash MORPH_SLACK_CHANNEL_WEBHOOK_URL="https://hooks.slack.com/services/XXXXXXXXXXXXX" MORPH_LIVE_MODE=false

Create a .env file using the supplied example by running:

cp .env.example .env

Then edit to taste.

Running the scraper on morph.io

You can also run this as a scraper on Morph.

To get started see the documentation

You can optionally set MORPH_RUNNERS to choose what runners are executed. Go to the settings page of the scraper, and set the value to be a comma separated list of runners:

RightToKnow,PlanningAlerts

Contributing

Adding new runners to Jacaranda

Jacaranda has a very simple model for adding new runners.

Runners pull information from (sometimes multiple) sources, and posts a message into Slack.

To add a new runner, create a file in lib/runners/ and define the following class:

``` ruby

lib/runners/my_service.rb

module MyService # A new runner for my new service class Runner < Jacaranda::BaseRunner class << self def build [ 'My text here.' ] end end end end ```

Then run the scraper:

bash MORPH_LIVE_MODE=false bundle exec ruby scraper.rb --runners MyService

Note: The --runners option is used only in development. Morph will run the scraper with no arguments.

*Note: You can use the --list-runners option to get a list of all runners Jacaranda knows about.

You'll see output something like this:

``` These are the runners we will execute:

MyService

[MyService] We have not posted an update during this fortnight. [MyService] Not posting to Slack. [MyService] Not recording the message in the database.

My text here. ```

That's it.

While displaying some static text is a nice start, you'll want to call out to your app to pull information in:

``` ruby

lib/runners/my_service.rb

module MyService # A new runner for my new service class Runner < Jacaranda::BaseRunner class << self def build [ MyService::Website.statustext(period: lastfortnight), ] end end end end ```

We're using a built-in helper method called last_fortnight to give us a date range for the last fortnight:

ruby last_fortnight # => [ Mon, 31 Jul 2017, Tue, 01 Aug 2017, ... ]

We pass this as the period parameter to the status_text method on the Website class.

Both the MyApp class and status_text method don't exist yet. Let's add them:

``` ruby

lib/runners/my_service.rb

MyApp stats from MyApp

module MyService class Website class << self def status_text(period:) [ ':tada:', count('requests:new', period: period), 'new requests were made through My Service in the last fortnight.' ].join(' ') end

  def count(query, period)
    start  = period.first
    finish = period.last

    # Make a call out to your service here ...
  end
end

end end ```

The status_text method is very simple – it accepts a time period it needs to produce text for, and returns a string of text.

Typically there is a count method used to get hit some endpoint or scrape some pages, and generate aggregate statistics. The exact implementation is up to you! Check out the PlanningAlerts and RightToKnow runners to see some more complex use cases.

Image credit

The Jacaranda Slack avatar is cropped from a photograph of the Jacaranda trees on Gowrie St, Newtown, Sydney by Flickr user murry. Thanks murry for making it available under a creative commons license.

Contributors equivalentideas auxesis

Last run completed successfully .

Console output of last run

Injecting configuration and compiling...  -----> Ruby app detected -----> Compiling Ruby -----> Using Ruby version: ruby-2.3.1 -----> Installing dependencies using bundler 1.15.2  Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment  Warning: the running version of Bundler (1.15.2) is older than the version that created the lockfile (1.15.3). We suggest you upgrade to the latest version of Bundler by running `gem install bundler`.  Fetching gem metadata from https://rubygems.org/........  Fetching version metadata from https://rubygems.org/..  Fetching dependency metadata from https://rubygems.org/.  Fetching https://github.com/openaustralia/scraperwiki-ruby.git  Fetching i18n 0.7.0  Using json 1.8.3  Fetching minitest 5.9.0  Fetching thread_safe 0.3.5  Installing i18n 0.7.0  Installing minitest 5.9.0  Installing thread_safe 0.3.5  Fetching addressable 2.4.0  Using bundler 1.15.2  Fetching unf_ext 0.0.7.1  Fetching dotenv 2.1.1  Installing addressable 2.4.0  Installing dotenv 2.1.1  Fetching multipart-post 2.0.0  Installing multipart-post 2.0.0  Fetching httpclient 2.6.0.1  Fetching mime-types 2.5  Installing unf_ext 0.0.7.1 with native extensions  Installing httpclient 2.6.0.1  Installing mime-types 2.5  Fetching net-http-digest_auth 1.4  Fetching net-http-persistent 2.9.4  Installing net-http-persistent 2.9.4  Fetching mini_portile2 2.1.0  Installing net-http-digest_auth 1.4  Fetching pkg-config 1.1.7  Installing mini_portile2 2.1.0  Installing pkg-config 1.1.7  Fetching ntlm-http 0.1.1  Fetching webrobots 0.1.1  Installing ntlm-http 0.1.1  Fetching sqlite3 1.3.10  Installing webrobots 0.1.1  Installing sqlite3 1.3.10 with native extensions  Fetching tzinfo 1.2.2  Installing tzinfo 1.2.2  Fetching faraday 0.9.2  Installing faraday 0.9.2  Fetching rest-client 1.6.7  Installing rest-client 1.6.7  Fetching nokogiri 1.6.8  Installing nokogiri 1.6.8 with native extensions  Fetching activesupport 4.2.7.1  Installing activesupport 4.2.7.1  Fetching sawyer 0.7.0  Installing sawyer 0.7.0  Fetching unf 0.1.4  Installing unf 0.1.4  Fetching octokit 4.3.0  Installing octokit 4.3.0  Fetching domain_name 0.5.24  Installing domain_name 0.5.24  Fetching http-cookie 1.0.2  Installing http-cookie 1.0.2  Fetching sqlite_magic 0.0.3  Installing sqlite_magic 0.0.3  Using scraperwiki 3.0.1 from https://github.com/openaustralia/scraperwiki-ruby.git (at morph_defaults@fc50176)  Fetching mechanize 2.7.3  Installing mechanize 2.7.3  Bundle complete! 17 Gemfile dependencies, 31 gems now installed.  Gems in the groups development and test were not installed.  Bundled gems are installed into ./vendor/bundle.  Bundle completed (28.19s)  Cleaning up the bundler cache.  Warning: the running version of Bundler (1.15.2) is older than the version that created the lockfile (1.15.3). We suggest you upgrade to the latest version of Bundler by running `gem install bundler`. -----> Detecting rake tasks   -----> Discovering process types  Procfile declares types -> scraper Injecting scraper and running... These are the runners we will execute: PlanningAlerts RightToKnow [PlanningAlerts] We have posted an update during this fortnight. [RightToKnow] We have posted an update during this fortnight.

Data

Downloaded 9 times by equivalentideas auxesis lukepint

To download data sign in with GitHub

Download table (as CSV) Download SQLite database (25 KB) Use the API

rows 10 / 56

date_posted text runner
2016-08-29
700 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 6% down from the fortnight before. You shipped 26 commits in the same period. There are now 36.8 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2016-09-12
705 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 3% up from the fortnight before. You shipped 1 commits in the same period. There are now 37.4 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2016-09-26
746 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 6% up from the fortnight before. You shipped 13 commits in the same period. There are now 38 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2016-10-10
728 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 0% down from the fortnight before. There are now 38.6 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2016-10-25
745 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 5% up from the fortnight before. There are now 39.3 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2016-11-09
743 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 1% less than the fortnight before. 180 people left :scream_cat: That’s 4% more than the fortnight before. You shipped 27 commits in the same period. There are now 39.9 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2016-11-25
678 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 10% less than the fortnight before. 177 people left :scream_cat: That’s 3% less than the fortnight before. There are now 40.5 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2016-12-10
745 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 9% more than the fortnight before. 175 people left. That’s 1% less than the fortnight before. You shipped 3 commits in the same period. There are now 41.1 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2016-12-24
639 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 14% less than the fortnight before. 189 people left. That’s 7% more than the fortnight before. There are now 41.6 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner
2017-01-11
552 people signed up for PlanningAlerts last fortnight :revolving_hearts: That’s 2% less than the fortnight before. 94 people left. That’s 37% less than the fortnight before. You shipped 69 commits in the same period. There are now 42.2 thousand PlanningAlerts subscribers! :star2:
PlanningAlerts::Runner

Statistics

Average successful run time: 1 minute

Total run time: 8 days

Total cpu time used: 11 minutes

Total disk space used: 1.7 MB

History

  • Auto ran revision cb5ec88e and completed successfully .
    nothing changed in the database
  • Auto ran revision cb5ec88e and completed successfully .
    nothing changed in the database
  • Auto ran revision cb5ec88e and completed successfully .
    2 records added in the database
  • Auto ran revision cb5ec88e and completed successfully .
    nothing changed in the database
  • Auto ran revision cb5ec88e and completed successfully .
    nothing changed in the database
  • ...
  • Created on morph.io

Show complete history

Scraper code

Ruby

jacaranda / scraper.rb