SalsaLabs bindings for Ruby

Gem
Version Build Status Dependency Status Code Climate

salsa_labs can fetch data from the Salsa Labs API.

Installation

Add this line to your application's Gemfile:

gem 'salsa_labs'

And then execute:

$ bundle

Or install it yourself as:

$ gem install salsa_labs

Usage

By default, you can store your API credentials as the environment variables SALSA_LABS_API_EMAIL and SALSA_LABS_API_PASSWORD to avoid the need to re-enter your password multiple times. Otherwise you will need to pass your credentials into the SalsaLabs::ApiClient or appropriate fetching method as you call it.

SalsaLabs::ApiClient is a general-purpose object for performing GET requests from the Salsa API.

# Create a client
client = SalsaLabs::ApiClient.new({email: '[email protected]', password: 'myPassword'})

# Perform arbitrary requests from Salsa API. If not already authenticated, client will do so automatically.
client.fetch('getObjects.sjs', {object: 'Supporter'})
# => Returns XML output of all supporters returned by API.

# Pass filter criteria to #fetch to retrieve a more focused result set.
# Filtering can be necessary if your result set exceeds allowed API limits.
# This query pulls all supporters with an address in Washington, D.C.
client.fetch('getObjects.sjs', {object: 'Supporter', State: 'DC'})

You can get a list of API calls and information about Salsa database objects here: https://help.salsalabs.com/entries/23537918-Getting-data-from-Salsa

Currently specific functionality exists to work with Action campaigns(SalsaLabs::Action), Supporters (SalsaLabs::Supporter), and the join table Supporter Actions (SalsaLabs::SupporterAction), but more objects will be added later.

# Fetch all actions from Salsa. First argument is filter criteria, second argument is credentials if you are not storing them as environment variables.
actions = SalsaLabs::Action.fetch({}, {})
# => Array of SalsaLabs::Action objects.

# Examine the Action.
actions.first.attributes
# => {'title' => 'My Action Title', 'organization_key' => '90210', action_key => '1234'}

SalsaLabs::Action#attributes returns a hash corresponding to all the attributes returned by the API, so it should accommodate custom fields and/or new fields added later by SalsaLabs. All attribute names are downcased.

Dependencies

Ruby 1.9 is required.

Credits

The salsa_labs gem was created and is maintained by Allison Sheren and Geoff Harcourt.

Development is generously sponsored by Velocity, in support of their work with progressive organizations.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

The salsa_labs gem is Copyright 2013-2014 Velocity. It is free software, and may be redistributed under the terms of the MIT license, specified in the LICENSE file.