OneBody UpdateAgent
===================

Ruby gem that pushes data from a membership data source to a remote OneBody instance via the REST API.

Download and Install
--------------------

Install [Ruby](http://ruby-lang.org) if you don't already have it.

Run the following command ("sudo" may be required in some environments):

    gem install onebody-updateagent -s http://gemcutter.org
    
Configuration
-------------

1. Run `update_onebody` at a terminal, then take note of where the example.yml config file resides.
2. Copy the example config file to a convenient location and edit appropriately.

Your "site" address will probably be something like "http://example.com" or
"http://yoursite.beonebody.com".

You can get your user api key from OneBody (you must be a super admin) by running the following
command (on the server):

    cd /path/to/onebody
    rake onebody:api:key EMAIL=admin@example.com
    
If your instance is hosted at <http://beonebody.com>, you may email <support@beonebody.com>
to get your api key.

Preparation
-----------

Using your membership management software, reporting solution, database utility, custom script, etc.,
export your people and family data to a single comma separated values (CSV) file, e.g. people.csv.

Duplicate family data should be present for each member of the same family.

The first row of the file is the attribute headings, and must match the attributes available:

* [Person Attributes](http://github.com/seven1m/onebody/tree/master/app/models/person.rb)
* [Family Attributes](http://github.com/seven1m/onebody/tree/master/app/models/family.rb)
  (prefix each attribute with "family_")

Not all attributes are required.

Optionally, if you have shell access to your hosted instance of OneBody, you can run
`rake onebody:export:people:csv` to export the current OneBody data (if you have any records in
the OneBody database) as a starting point.

Use the following attributes to track the identity/foreign keys from your existing membership
management database. Do *not* include "id" and "family_id" columns.
* legacy\_id
* legacy\_family\_id

There is an example csv file in this directory for reference.

Converters
----------

As of this writing, one Church Management System (ChMS) is supported via a Converter. The
Converter translates field names and data into the formats and locations expected by OneBody.

To use a converter, you must specify it in your config file. The example config file has these
settings disabled; simply remove the pound sign at the beginning of each line to enable the
use of the converter. Specify the name and any additional settings.

Usage
-----

To run UpdateAgent:

    update_onebody -c path/to/config.yml path/to/people.csv
    
If you plan to schedule UpdateAgent to run periodically without human intervention,
you'll want to at least use the `-y` switch, which assumes *yes* to any questions:

    update_onebody -c path/to/config.yml -y path/to/people.csv
    
You may also log all output:

    update_onebody -c path/to/config.yml -y -l path/to/updateagent.log path/to/people.csv