CiviNorth

CiviNorth is a Drupal module that integrates the Represent OpenNorth website service with CiviCRM.

The project is hosted here:
http://drupal.org/project/civinorth
My original blog about it is here:
http://homeofficekernel.blogspot.ca/2013/01/democratic-activists-engage…

This page provides basic documentation for developers about how it works and how to set it up, as of today (Mar 29, 2013).

What it does

It really just does three things.

  1. It populates and updates contacts of a special contact type for politicians ("representatives") with all the existing MPs, MPPs, City councillors, or whatever you're using. This is triggered as a manual task.
  2. During the cron, it populates a specific fieldset of ordinary contacts (i.e. the people being represented, the plebs) with the name of their consituency, (based on their CiviCRM address field), and/or a link to their representative (the one that got created in thing 1., above).
  3. It provides a piece of javascript that allows clever real-time lookups when a site visitor is filling out a webform that uses the "right" fields via the civicrm webform module.

You don't have to use all these functions, but I don't know why you wouldn't (okay, maybe not the last one in some cases).

Installation Generalities

  1. You can add this to an existing CiviCRM installation or a fresh one. Installation as usual, just installing it will do nothing on it's own (no tables or install scripts, for example).
  2. If you already have fields in use for representative data, you can use them for this module.
  3. There's a fair amount of manual setup in CiviCRM and configuration of this module before anything useful can happen.

Installation Steps

Yes, a wizard to help with new setups would be nice! In the meantime, here's the manual method.

  1. Install the module as usual. It doesn't create any tables. It keeps some configuration stuff in the drupal variables table, but all the data lives in CiviCRM. Yes, it should be an extension, and will be in it's next iteration!
  2. In CiviCRM, create a new Individual contact subtype to hold your representatives (i.e. your MPs, MPPs, etc.). You can recycle an existing one if that's what it already contains - though you'll have to merge the records later.
  3. Create a new fieldset only for that Representative contact subtype called Opennorth Data, which will hold interesting stuff from OpenNorth about that representative (e.g. name, a link to their picture, etc.). Don't put any fields in here, they'll get auto-populated by civinorth.
  4. Still in CiviCRM, either identify an existing fieldset, or create a new one, that will hold individual contact representation data (i.e. which constituency they live in, and who their representative is).
  5. In that fieldset, create three special fields for:
    • Status (a number from 0 to 3)
    • Status note (type Note)
    • Last automated update (of type Date)

    These will get populated by civinorth for its own use and for your edification about it's activities.

  6. Now you create additional fields for the data you want. These fields are NOT automatically created, because you have to decide which of the OpenNorth available fields you want to have populated (there are many). Normally, for each 'boundary set', you will want two fields – one for a text field naming the boundary (e.g. your federal riding), and a second one as a relationship field that points to the Representative contact record (i.e. of the kind you created in step 2.).
  7. Now go to the CiviNorth configuration page in config -> services.
  8. You'll see that there are two fieldsets and one Individual subtype in CiviCRM that CiviNorth needs to match up with what you just identified and/or created.
  9. After you've done that and saved it, on the same page you'll now see that you can match up your fields in the Individual Contact Representation fieldset with the data provided by OpenNorth. You'll also want to manually match up those three administrative-type fields.
  10. You should now be able to go to the config -> reports and see a CiviNorth entry where you can see how many of your contacts are in what state. Use the Update link to update your representative subtype contacts, and the Cron link to manually update the representation data for your individual contacts.