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 find contacts by any field
contacts = AgileCRMWrapper::Contact.search("foo")
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 remove tags from a contact
contact.delete_tags(['foo', 'bar'])
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_property("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."
)

3. Working with Tags

List all tags
AgileCRMWrapper::Tag.all #=> [...]

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