Find out and have your say about what's being built and knocked down in your area.
Ruby HTML JavaScript CSS
Failed to load latest commit information.
app Add @JasonThomasData to list of contributors 🎉 Jul 21, 2016
bin Springify binstubs Aug 4, 2015
config Refactor email_confirmable completely back into the application Jun 22, 2016
db Save writeit ID with reply Apr 4, 2016
doc Initial commit of rails app skeleton Jan 24, 2010
experiments/metrics Original version of sign up form worked better (with 90% confidence) Oct 5, 2012
lib Refactor email_confirmable completely back into the application Jun 22, 2016
public Remove images from public directory Jun 18, 2015
spec Use the factory Jun 23, 2016
tmp/cache Force the existence of the tmp/cache directory Apr 22, 2011
vendor/assets Move a vendor script to the vendor director for better organisation Jan 5, 2016
.autotest Autotest configuration to add integration tests into the autotest cycle Jan 25, 2010
.env Add example configuration for writeit Apr 4, 2016
.env.test Move feature flag to configuration Aug 25, 2015
.gitignore Set morph.io API using .env Aug 21, 2015
.rspec rails g rspec:install Feb 9, 2013
.ruby-version Merge branch 'master' into design/initial Jan 3, 2014
.travis.yml On Travis update bundler to workaround an issue on Ruby 2.1 Mar 22, 2016
Capfile Update deprecated require line Aug 24, 2015
Gemfile Add autoprexfer to cover css properties that need it, e.g. flexbox Jun 9, 2016
Gemfile.lock Add autoprexfer to cover css properties that need it, e.g. flexbox Jun 9, 2016
Guardfile Make guard run all integration tests when a view is changed Nov 6, 2015
LICENSE Move the README to a more common layout and include more details Dec 30, 2013
Procfile Use the full argument to be explicit Feb 2, 2015
Procfile.production Revert "Use dotenv to load the environment when launching the worker" Nov 10, 2015
README.md Add a bit more explanation and a helpful link May 2, 2016
Rakefile Remove now unused configuration module Aug 21, 2015
config.ru Framework updated to Rails 3 Jan 28, 2011

README.md

PlanningAlerts

Find out and have your say about development applications in your area.

This is the code for the web application side of things written using Ruby on Rails. The original code from PlanningAlerts.com, which this app is based on, was written using PHP.

If you're interested in contributing a scraper read our step-by-step guide to writing scrapers on our scraping platform, morph.io.

PlanningAlerts is brought to you by the OpenAustralia Foundation. It was adapted for Australia by Matthew Landauer and Katherine Szuminska, and is based on the UK site PlanningAlerts.com, built by Richard Pope, Mikel Maron, Sam Smith, Duncan Parkes, Tom Hughes and Andy Armstrong.

Development

Build Status Coverage Status Code Climate

Install Dependencies

Checkout The Project

  • Fork the project on Github
  • Checkout the project

Install Ruby Dependencies

  • Install bundler and foreman - gem install bundler foreman
  • Install dependencies - bundle install

Setup The Database

  • Create your own database config file - cp config/database.yml.example config/database.yml
  • Update the config/database.yml with your root mysql credentials
  • If you are on OSX change the socket to /tmp/mysql.sock
  • Set up the databases - rake db:setup
  • Generate Thinking Sphinx configuration - bundle exec rake thinking_sphinx:configure

Run The Tests

  • Run the test suite - rake

Scraping and sending emails in development

Step 1 - Scrape DAs

  • Register on morph.io and get your api key.
  • Create a .env.local file and set your MORPH_API_KEY
  • Run - rake planningalerts:applications:scrape['marrickville']

Step 2 - Setup an Alert

  • Start servers - foreman start
  • Hit the home page - http://localhost:3000
  • Enter an address e.g. 638 King St, Newtown NSW 2042
  • Click the "Email me" link and setup an alert
  • Open MailCatcher and click the confirm link: http://localhost:1080/

Step 3 - Send email alerts

  • Run - rake planningalerts:applications:email
  • Check the email in your browser: http://localhost:1080/
  • To resend alerts during testing, just set the last_sent attribute of your alert to nil

Configuring PlanningAlerts so people can write to their local councillors

People use PlanningAlerts to provide official submissions to planning applications, but sometimes the official process doesn’t work well, or they have questions and need a response. In Australia we elect local councillors to represent us in local government decision making—these are good people to speak to in these cases and many others. Through PlanningAlerts people can send public messages to their councillors about planning applications and councillors can reply.

Developers will find a detailed explanation of how the feature works in this section. Administrators will be most interested in how to add councillors for an authority.

Four conditions must be met for the option to write to councillors to be available for an application:

  1. the global feature flag must be toggled on;
  2. a reply address must be configured for councillors to email their responses to;
  3. the feature must be enabled on the authority that the application belongs to; and,
  4. there must be councillors associated with the authority for people to write to.

You will also need to configure the app to accept replies from councillors.

Global feature flag

You can toggle the availability of the writing to councillors feature on or off for the entire site with the environment variable COUNCILLORS_ENABLED. The feature is globally enabled when the value of ENV["COUNCILLORS_ENABLED"] is "true". This flag is useful if you need to turn the feature off globally.

We set this in the .env file in production. You can control setting in development by creating your own .env.local file which includes:

COUNCILLORS_ENABLED=true

Set the reply address for accepting responses

You need to specify an email address for councillors to send their replies to. If you’re using the ‘Wizard of Oz’ setup, the councillor replies will come in to this address. If you’re using the WriteIt integration, then the WriteIt answer notification emails will be sent there.

Set this address using the EMAIL_COUNCILLOR_REPLIES_TO environment variable in .env or .env.local in your local development setup:

EMAIL_COUNCILLOR_REPLIES_TO=lovely@email.org.au

Enable the feature for an authority

You can toggle the ‘writing to councillors’ options on or off for all applications under an authority. By default it is off.

Control this setting at the admin page for the authority (e.g. /admin/authorities/1/edit). Check or uncheck the "Write to councillors enabled" option.

You can see which authorities have the feature enabled at the Authorities admin page (/admin/authorities).

Adding councillors for an authority

If you'd like to add new councillors for a planning authority, there are a number of steps that you need to take across a few different online services.

Firstly, make sure the data for your councillors is available from the australian_local_councillors_popolo repository. Follow it’s instructions for adding new councillor data there.

If you're using WriteIt then the next step is to refresh the data source in WriteIt so it knows about the coucillors you've added to the popolo data. Check that your refresh was successful by confirming that you now have the option to write to your newly added councillors in the WriteIt frontend.

Run the morph.io scraper that copies the councillor’s images for use in PlanningAlerts. Wait for it to finish running before continuing so that the councillors images are available for PlanningAlerts.

Now visit the authority admin page and click the “Load Councillors” button. Any new councillors for this authority will be added, and existing councillors will be updated.

Finally, check the list of your new and/or updated councillors on the authority’s admin page. If you're happy with the result then enable writing to councillors for this authority.

Accepting councillor replies

Not only can people write to their councillors using PlanningAlerts, but councillors can also reply!

When someone writes to their local councillor, the councillor receives an email with the message. To reply, they simply reply to the email. The reply is then posted below the original comment on PlanningAlerts, and the commenter is notified. Replies are featured in alert emails like normal comments.

You can choose between two different methods for loading replies into PlanningAlerts: The ‘Wizard of Oz’ setup, which requires administrators to watch an email inbox and manually enter replies; or, by integrating with a WriteIt site, which will accept replies and have them automatically posted on PlanningAlerts.

Default Wizard of Oz method

While the back and forth of writing to councillors appears to be automatic to users, by default there is no magic. Behind the scenes administrators need to manually collect replies from an email inbox and add them to people’s comments.

By default, the reply address on the email sent to councillors will be the address you set with ENV["EMAIL_COUNCILLOR_REPLIES_TO"]. You can follow the instructions above for setting the reply address if you haven’t yet.

When a councillor replies to an email with someone’s message, like normal email, the reply will go to the inbox of the reply address. You will need to keep an eye on this inbox for incoming replies.

When a councillor reply email arrives you will need to manually add it to PlanningAlerts. To add a reply, first find the comment it is responding to on the comments index page or page for the application it is associated with. If you are logged in as an Admin, there will be a link “Add reply” on the bottom of the comment.

On the ‘Add reply’ page fill in the form with the details of the reply: the comment_id of the comment it is responding to, the name of the councillor, the full text of the email received, and the time it was received (in UTC time). Hit the “Create reply” button. The original commenter will be notified of the reply via email and the reply will be posted with the comment on the application page.

Integrating with WriteIt

PlanningAlerts can automatically post replies from councillors by integrating with WriteIt to send messages and receive answers. This means that no action is required by administrators for councillor replies to be loaded.

Basic setup

To send people’s comments to councillors via a WriteIt instance, PlanningAlerts needs to know some things about that instance:

  • the URL of the WriteIt app you’re using;
  • the location of your ‘site’ within that app;
  • your username for the WriteIt app; and,
  • your API key.

If you want to use the version of WriteIt publicly hosted by Fundación Ciudadano Inteligente then sign up for an account and create your own ‘site’ over there. On the API page for your WriteIt site you’ll find the information you need.

The information about the WriteIt instance you will be working with is stored as environment variables. In production these should be in a .env file. Use .env.local in your local development environment.

# WriteIt configuration
WRITEIT_BASE_URL=http://writeit.ciudadanointeligente.org
WRITEIT_URL=/api/v1/instance/1234/
WRITEIT_USERNAME=yourusername
WRITEIT_API_KEY=xxxxxxxxxxxxyourapikeyxxxxxxxxxxxxxxxxxx
Adding your councillor data to WriteIt

You’ve already loaded your councillors into PlanningAlerts, now you need to load them into WriteIt.

You can add ‘recipients’ to your WriteIt site by adding a new ‘data source’. On the ‘Data Sources’ page for your WriteIt site add a new ‘Popolo URL’ for each of the councillor popolo files at github.com/openaustralia/australian_local_councillors_popolo, e.g. :

https://raw.githubusercontent.com/openaustralia/australian_local_councillors_popolo/master/nsw_local_councillor_popolo.json

When you add the ‘data source’ WriteIt loads in all Popolo People objects available. You will be able to send messages to the people who have an email address.

Every time you want to add new councillors or change their details, you need to load that data into WriteIt in addition to loading the changes into PlanningAlerts. On the Writeit ‘data sources’ page you can “fetch new data” to update your available ‘recipients’.

It’s always a good idea to check that your update worked as expected by seeing if you have the option to write to one of the newly added councillors in WriteIt.

Sending messages via WriteIt

PlanningAlerts decides how to send a comment after it is confirmed by the user. If you’ve configured the integration to a WriteIt site, comments to councillors will automatically be sent via the WriteIt API.

Automatically fetching replies with the Writeit reply webhook

When a councillor receives a message that has been sent via WriteIt, the reply email address is a special WriteIt email address, not your configured reply address. When they reply to the email, the content of their email is automatically added as an answer to the original message on WriteIt.

You can add the PlanningAlerts WriteIt reply webook to your Writeit site to automatically load these replies into PlanningAlerts.

On the Wehbooks settings page for your WriteIt site, add the webhook URL for your PlanningAlerts setup as a new webhook URL, e.g.:

http://planningalerts.com/comments/writeit_reply_webhook

Now, when a new reply is created on your WriteIt site, WriteIt will post data about it to the webhook URL you set.

Your PlanningAlerts app will then fetch the full answer from WriteIt and create a new reply.

Manually loading replies from Writeit

If for some reason the webhook isn’t configured, or something else goes wrong, you can manually load replies from your WriteIt site.

Navigate to the admin page for a comment, e.g. /admin/comments/123. Use the “Load replies from WriteIt” button to load in new replies to that comment. PlanningAlerts will fetch any answers from the API for your WriteIt site and create new replies and associate them with the comment.

Deployment

The code is deployed using Capistrano. To deploy to production run:

bundle exec cap --set-before stage=production deploy

This command is defined in config/deploy.rb.

Sometimes you want to deploy an alternate branch, for instance when deploying to the test stage. In this case you'll need to set the branch variable after recipies are loaded by using the --set argument instead of --set-before, e.g.

bundle exec cap --set-before stage=test --set branch=a-branch-i-want-to-test deploy

View more available Capistrano commands with:

bundle exec cap --tasks

Contributing

  • Fork the project on GitHub.
  • Make a topic branch from the master branch.
  • Make your changes and write tests.
  • Commit the changes without making changes to any files that aren't related to your enhancement or fix.
  • Send a pull request against the master branch.

Credits

Our awesome contributors can be found on the PlanningAlerts site.

License

GPLv2, see the LICENSE file for full details.