tracktor / zoho-crm

🗂 A gem to make working with Zoho CRM less painful

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: "[email protected]", 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" => "[email protected]",
  "First_Name" => "Mister",
  "Last_Name" => "World",
  "Phone" => "[phone]",
}
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" => "[email protected]",
  "First_Name" => "Mister",
  "Last_Name" => "World",
  "Phone" => "[phone]",
}
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.

zoho-crm's Issues

Find a field by its API name

Right now it's only possible to find a field by its name attribute. It would be really useful to be able to find a field by its api_name attribute.

Setting a static value for a model's field affects all instances of the model

If we set the static value of a model's field, then all instances of that model will use the static value:

User = Struct.new(:email)

class Contact < ZohoCRM::Model
  zoho_field(:email, as: "Email")
end

user = User.new("[email protected]")
contact1 = Contact.new(user)
contact2 = Contact.new(user)
contact2.email = "[email protected]"

contact1.field(:email).value_for(user) # => "[email protected]"
contact2.field(:email).value_for(user) # => "[email protected]"

In the example above, contact1.field(:email).value_for(user) should be [email protected].

Add a Ruby version restriction to the gemspec

Add a minimum ruby version requirement to the gemspec using required_ruby_version=:

spec.required_ruby_version = '>= 2.6.3'

Allow computable field labels

Right now the label of a field is specified when the field is created and its value is static:

field = ZohoCRM::Fields::Field.new(:full_name, label: "Full name (First name + Last name)")
puts field.label # => Full name (First name + Last name)

It would be better to be able to assign to the label an object that responds to #call and be able to compute it with #label_for – similar to the #value_for method.

Add type checking using Sorbet

Sorbet is a fast, powerful type checker designed for Ruby.

There is also a project to convert YARD docs to Sorbet signatures:

Sord: Generate Sorbet RBI files from YARD docs: