NimbleApi
Ruby wrapper for the nimble api. The wrapper provides classes for Contacts and Contact.
References:
- http://nimble.readthedocs.org/en/latest/
- https://github.com/nimblecrm/omniauth-nimble
- https://github.com/nimblecrm/ruby-example (use this to fetch your 'refresh' token)
Configuration
The nimble api uses oauth for authorization. As such, you are required to obtain a client secret, token and registered callback url for each domain (including your localhost for testing) before starting to use this wrapper. Once you have obtained these keys, you will need to generate a refresh token. This allows you to access the API without needing to do the oauth dance to recreate your api client each time.
To use this wrapper, configure the NimbleApi with the following:
NimbleApi.configure do |c|
c.client_id = ENV['CLIENT_ID']
c.client_secret = ENV['CLIENT_SECRET']
c.refresh_token = ENV['REFRESH_TOKEN']
end
If you plan to use this with rails, create config/initializers/nimble.rb with this contents. Reminder that you will need a set of all three ENV variables for each callback url that you plan to deploy, including localhost for testing.
Usage
> require 'nimble-api'
# Configure with your id, secret and refresh token for your application
NimbleApi.configure do |c|
c.client_id = ENV['NIMBLE_CLIENT_ID']
c.client_secret = ENV['NIMBLE_CLIENT_SECRET']
c.refresh_token = ENV['NIMBLE_REFRESH_TOKEN']
end
# Create a nimble object
@nimble = NimbleApi()
# Create a person hash - email is required
@person = {
'first name' => 'Fred',
'last name' => 'Flintstone',
'email' => 'fred@bedrock.org',
'tags' => 'test'
}
# Use the hash to create a contact and save it to your Nimble account
fred = @nimble.contact.create @person
fred.save
# Attempt to save duplicate person throws error - checking is based on first email value
> fred.save
RuntimeError: fred@bedrock.org already exists!
# Update one element, or multiple
fred.update("parent company" => [{ "modifier"=>"","value"=>"Cogswell Cogs"}])
# Find a contact by their email address, best way to find a unique user
fred = @nimble.contact.by_email 'fred@bedrock.org'
# Find a contact by id
fred = @nimble.contact.fetch "54444842faed29141e5c7300"
# Find a contact by their first and last name, returns the first match - be careful!
fred = @nimble.contact.by_name 'Fred', 'Flintstone'
# Use convenience methods to display the id, email and fields
> fred.id
=> "54444842faed29141e5c7300"
> fred.email
=> "fred@bedrock.org"
> fred.fields
=> {"last name"=>[{"group"=>"Basic Info", ... "value"=>"Flintstone", "label"=>"last name"}],
"first name"=>[{"group"=>"Basic Info", ... "value"=>"Fred", "label"=>"first name"}],
"lead status"=>[{"group"=>"Lead Details", ... "value"=>"Not Qualified", "label"=>"lead status"}],
"email"=>[{"group"=>"Contact Info", ... "value"=>"fred@bedrock.org", "label"=>"email"}],
"source"=>[{"group"=>"Basic Info", ... "value"=>"m", "label"=>"source"}],
"parent company"=>[{ ... "value"=>"Cogswell Cogs", "label"=>"parent company"}]}
> fred.note "This is your note"
=> {"note"=>"This is your note", ... "note_preview"=>"This is your note" ...
> fred.task 'next week', 'Big Subject', 'little notes'
=> {"due_date"=>"2014-10-29T19:00:00+00:00", "updated"=>"2014-10-19T23:31:43+00:00", "tags"=>[], ....
> @nimble.contacts.list
=> {"meta"=>{"per_page"=>30, "total"=>238, "pages"=>8, "page"=>1}, "resources"=>[...]
> @nimble.contacts.list(fields: ['first name', 'last name', 'email'])
=> ... limited to just these fields
> @nimble.contacts.list(keyword: 'fred')
=> {"meta"=>{"per_page"=>30, "total"=>1, "pages"=>1, "page"=>1}, "resources"=>[ ... just one ... ]
> @nimble.contacts.list_ids( per_page:100, page: 2 )
=> {"meta"=>{"per_page"=>100, "total"=>396, "pages"=>4, "page"=>2}, "resources"=>[ ... 100 resources ... ]
Contacts
Provides list and list_ids, each taking params as described by the nimble api documentation http://nimble.readthedocs.org/en/latest/responses/#contact-list
Contact
Provides a Contact object which can perform a number of instance methods:
create
Create a new contact by providing a person definition with contact fields.
@nimble = NimbleApi()
person = {
'first name' => 'Fred',
'last name' => 'Flintstone',
'email' => 'fred@bedrock.org',
'tags' => 'test'
}
fred = @nimble.contact.create @person
save
Save the contact, results will populate @contact within the object
fred.save
fred.contact['fields'] # accesses returned field values
by_email
Find a contact by email address. Note that this will be the best way to locate unique contacts
by_name
Find a contact by first and last name. Be careful John Smith!
fetch, alias: get
Find a contact by id. Can also be called from an instance in order to refresh the contact data
id, email, fields
Convenience methods to access the contact id, first email address and fields hash
update
Update with new fields contents
fred.update("parent company" => [{ "modifier"=>"","value"=>"Cogswell Cogs"}])
fred.fetch
fred.fields['parent company'].first['value'].should eq 'Cogswell Cogs'
note
Adds a note for the contact
notes
Return notes
task
Add a task for the contact with due_date, subject and optional notes. The due_date parameter supports the Chronic parser (https://github.com/mojombo/chronic) so that you can use strings such as: 'tomorrow', 'next week', 'thursday'.