scholastica / agilecrm-wrapper

Ruby wrapper for Agile CRM API.

AgileCRMWrapper

This project is a ruby client that wraps the AgileCRM REST API. Note: This is not an official project, you're welcome to use it but don't expect the AgileCRM team to support it.

At present, only operations related to the contact and note resources are supported. Need something added? Make a feature request in the issues tab. Pull requests are always welcome.

Installation

Add this line to your application's Gemfile:

gem 'agilecrm-wrapper'

And then execute:

$ bundle

Usage

To begin using this gem, Initialize the library using a configuration block including your agile API key, email, and domain, like this:

AgileCRMWrapper.configure do |config|
  config.api_key = 'XXXXXXXXXXX'
  config.domain = 'my-agile-domain'
  config.email = '[email protected]'
end

1. Working with Contacts

GET operations return one or more AgileCRMWrapper::Contact objects. These are just Hashie::Mash objects with a few utility methods sprinkled on. You can access any of the Contact fields returned by AgileCRM's REST API, see here for what that entails. Example:

contact = AgileCRMWrapper::Contact.find(123)
contact.tags       #=> ["tag", "your", "it"]
contact.id         #=> 123
contact.properties #=> [{ type: 'SYSTEM', name: "email", value: "[email protected]" }]

To retrieve a list of contacts

AgileCRMWrapper::Contact.all

To get an individual contact by ID

AgileCRMWrapper::Contact.find(123)

To find contacts by email

contact = AgileCRMWrapper::Contact.search_by_email("[email protected]")
# or pass multiple emails as seperate arguments or an array
contacts = AgileCRMWrapper::Contact.search_by_email(
"[email protected]", "[email protected]"
)

To create a new contact

AgileCRMWrapper::Contact.create(
  tags: ["tag", "your", "it"],
  first_name: "Justin",
  last_name: "Case",
  email: "[email protected]",
  my_custom_field: "im a custom field!"
)

To update a single contact

contact.update(first_name: "Foo", last_name: "Bar", tags: ["new_tag"])

Note, tags specified in update will simply be added to the existing list of tags.

To delete a single contact

# perform operation directly
AgileCRMWrapper::Contact.delete(123)
# or
AgileCRMWrapper::Contact.find(123).destroy

Convenient access to properties hash values

contact.get_property("email")            #=> "[email protected]"
contact.get_propety("my_custom_field")   #=> "im a custom field!"
contact.get_property("unkown_attribute") #=> nil

2. Working with Notes

To create a new note

AgileCRMWrapper::Note.create(
  subject: "My Note",
  description: "My notes's description.",
  contact_ids: ["123"]
)

To add a Note to a Contact using Email-ID

AgileCRMWrapper::Note.add_by_email(
  email: "[email protected]",
  subject: "My Note",
  description: "My notes's description."
)

Contributing

1. Fork it ( https://github.com/nozpheratu/agilecrm-wrapper/fork )
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 a new Pull Request