SalsaLabs bindings for Ruby

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