zoho-crm

A gem to make working with Zoho CRM less painful.

Requirements

This gem requires Ruby version 2.6 or greater.

Installation

Add this line to your application's Gemfile:

gem "zoho-crm"

And then execute:

$ bundle install

Usage

Quickstart

ZohoCRM::Model

require "zoho_crm"

class ZohoUser < ZohoCRM::Model
  zoho_module "Contact"
  zoho_field :email, as: "Email_Address"
  zoho_field :full_name do |user|
    "#{user.first_name} #{user.last_name}"
  end
end

user = User.new(email: "john.smith@example.com", first_name: "John", last_name: "Smith")
zoho_user = ZohoUser.new(user)
json = zoho_user.as_json

---

ZohoCRM::API

require "zoho_crm"

ZohoCRM::API.configure do |config|
  config.region = "eu"
  config.sandbox = true

  config.client_id = ENV["ZOHO_CRM_API_CLIENT_ID"]
  config.client_secret = ENV["ZOHO_CRM_API_CLIENT_SECRET"]
  config.redirect_url = ENV["ZOHO_CRM_REDIRECT_URI"]
  config.scopes = %w[
    ZohoCRM.modules.all
  ]
end

oauth_client = ZohoCRM::API::OAuth::Client.new
api_client = ZohoCRM::API::Client.new(oauth_client)

# OAuth authorization flow... (see the example app)

# Get a record
api_client.show("12345", module_name: "Contacts")

# Create a new record
contact_attributes = {
  "Email" => "hello.world@example.com",
  "First_Name" => "Mister",
  "Last_Name" => "World",
  "Phone" => "+33 6 12 34 56 78",
}
api_client.create(contact_attributes, module_name: "Contacts")

# Update a record
api_client.update("12345", {"First_name" => "John"}, module_name: "Contacts")

# Insert or Update a record (Upsert)
contact_attributes = {
  "Email" => "hello.world@example.com",
  "First_Name" => "Mister",
  "Last_Name" => "World",
  "Phone" => "+33 6 12 34 56 78",
}
api_client.upsert(contact_attributes, module_name: "Contacts", duplicate_check_fields: ["Email"])

# Delete a record
api_client.destroy("12345", module_name: "Contacts")

For a more complete example, look at the example application.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

The default Rake task is setup to run the test suite then lint the code:

$ rake

Dependencies

Development dependencies are in the gem specification — see the zoho-crm.gemspec file. If you need to add a dependency, add it to that file. Do not add any gem to the Gemfile.

spec.add_development_dependency "faker", "~> 1.9"

Code style

The standard gem is used to enforce coding style. A Rake task is available to check the code style:

$ rake standard

There is also a Rake task to fix code style offenses:

$ rake standard:fix

Tests

Tests are written using RSpec. You can run the test suite using the dedicated Rake task:

$ rake spec

Documentation

The API documentation is generated using YARD:

$ rake yard

The documentation files will be generated under the doc/ directory. You can browse the documentation by opening doc/index.html in a browser.

Releasing a new version

To release a new version of the gem, follow these steps:

1. Bump the version number in lib/zoho_crm/version.rb
2. Update the Changelog. Make sure the link to the release on GitHub contains the correct version even though it doesn't exist yet.
3. Commit the changes with the following commit template:

   Release version x.x.x
   

4. Push the new commit on GitHub
5. Create a new release on Github:
   1. The name of the new tag should have the following format: vx.x.x
   2. The name of the release should be the same as the tag
   3. The description of the release should be the content of the last section of the Changelog.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Tracktor/zoho-crm.