isabella232 / ckanext-twitter

A CKAN plugin to post tweets when datasets are created and updated.

ckanext-twitter

Sends a tweet every time a dataset is created or updated in the database.

Setup

1. Clone the repository into the virtual env's src folder:

cd /usr/lib/ckan/default/src/
git clone https://github.com/NaturalHistoryMuseum/ckanext-twitter.git

2. Activate the virtual env:

. /usr/lib/ckan/default/bin/activate

3. Run setup.py:

cd /usr/lib/ckan/default/src/ckanext-twitter
python setup.py develop

4. Add 'twitter' to the list of plugins in your config file:

ckan.plugins = ... twitter

5. Install the requirements from requirements.txt:

cd /usr/lib/ckan/default/src/ckanext-twitter
pip install -r requirements.txt

Configuration

There are a number of options that can be specified in your .ini config file. The only required options are the twitter credentials. Everything else has a sensible default set.

Twitter Credentials [REQUIRED]

ckanext.twitter.consumer_key = YOUR-CONSUMER-KEY
ckanext.twitter.consumer_secret = YOUR-CONSUMER-SECRET
ckanext.twitter.token_key = YOUR-TOKEN-KEY
ckanext.twitter.token_secret = YOUR-TOKEN-SECRET

All of these can be obtained by creating a single-user app at apps.twitter.com. They can be found on the "keys and access tokens" tab when viewing your app.

Tweet Templates

Tweets are generated using Jinja2 and a set of parsers to extract/shorten common pieces of information from the package dictionary. These templates can be overwritten in the config.

The default for ckanext.twitter.new (the option for the 'new dataset' tweet template) is:

New dataset: "{{ title }}" by {{ author }} ({%- if records != 0 -%} {{ records }} records {%- else -%} {{ resources }} resource {%- endif -%}).

And the default for ckanext.twitter.updated is:

Updated dataset: "{{ title }}" by {{ author }} ({%- if records != 0 -%} {{ records }} records {%- else -%} {{ resources }} resource {%- endif -%}).

If your config is created dynamically using Jinja2, you will have to wrap any custom template in {% raw %}{% endraw %} tags and add a newline after it, e.g.:

ckanext.twitter.new = {% raw %}{{ title }} by {{ author }} ({{ records }} records) has just been published!{% endraw %}

ckanext.twitter.consumer_key = {{ twitter.consumer_key }}
ckanext.twitter.consumer_secret = {{ twitter.consumer_secret }}
ckanext.twitter.token_key = {{ twitter.token_key }}
ckanext.twitter.token_secret = {{ twitter.token_secret }}

Token values will come from a simplified package dictionary where any collection values (i.e. lists and dictionaries) have been replaced with the number of items, the author list has been significantly shortened, and any long strings will be shortened to fit into the tweet character limit (currently set at 140). Some example keys:

owner_org
private
num_tags
id
metadata_created
metadata_modified
author
type
num_resources
records
name
isopen
notes
title
organization

Other options

Name	Description	Default
ckanext.twitter.debug	Is in debug mode; overrides global debug flag if specified	False
ckanext.twitter.hours_between_tweets	Number of hours between tweets about the same dataset (to prevent spamming)	24
ckanext.twitter.disable_edit	If true, users will not be able to edit the tweet about their dataset before it is posted (though they can still decide not to post it)	False

Testing

None of the tests should actually post any tweets to Twitter.

They will test authentication, but nothing should be posted.

To run the tests, use nosetests inside your virtualenv. The --nocapture flag will allow you to see the tweets being printed to the console instead of posted to twitter (as the tests are mostly run in debug mode) but will also print a lot of statements about database manipulation.

nosetests --ckan --with-pylons=/path/to/your/test.ini --where=/path/to/your/install/directory/ckanext-twitter --nologcapture --nocapture