Rubyzoho

= rubyzoho {<img src="https://travis-ci.org/amalc/rubyzoho.png?branch=master" alt="Build Status" />}[https://travis-ci.org/amalc/rubyzoho] {<img src="https://gemnasium.com/amalc/rubyzoho.png" alt="Dependency Status" />}[https://gemnasium.com/amalc/rubyzoho] {<img src="https://codeclimate.com/github/amalc/rubyzoho.png" />}[https://codeclimate.com/github/amalc/rubyzoho] {<img src="https://coveralls.io/repos/amalc/rubyzoho/badge.png?branch=master" alt="Coverage Status" />}[https://coveralls.io/r/amalc/rubyzoho] {<img src="https://badge.fury.io/rb/rubyzoho.svg" alt="Gem Version" />}[http://badge.fury.io/rb/rubyzoho] {<img src="https://img.shields.io/gem/dt/rubyzoho.svg" alt="Downloads" />}[https://rubygems.org/gems/rubyzoho]

Abstracting Zoho's API into a set of Ruby classes, with reflection of Zoho's fields using a more familiar ActiveRecord lifecycle, but without ActiveRecord. Current focus is on Zoho CRM.

<b>Release notes are at the \end of this page.</b>

== Install gem install rubyzoho

== Configure

=== Rails Put the following in an initializer (e.g. <tt><RAILS_ROOT>/config/initializers/zoho.rb</tt>):

require 'ruby_zoho'

RubyZoho.configure do |config|
  config.api_key = '<< API Key from Zoho>>'
  # config.crm_modules = ['Accounts', 'Contacts', 'Leads', 'Potentials'] # Defaults to free edition if not set
  # config.crm_modules = ['Quotes', 'SalesOrders', 'Invoices'] # Depending on what kind of account you've got, adds to free edition modules
  # config.ignore_fields_with_bad_names = true # Ignores field with special characters in the name (Release 1.8)
  # Currently only Quotes are supported
end

You can reduce the number of API calls made during development and production by adding

config.cache_fields = true

to the initializer. You can also limit the number of modules in use, so if you're only using 'Leads' for instance, set the gem to only load field data from 'Leads' by setting

  config.crm_modules = ['Leads']

and only meta data from 'Leads' will be loaded.

In Test or Continous Integration(CI) environments, one strategy is not to initialize the gem at all, so for example,

 RubyZoho.configure do |config|
   config.api_key = '<< API Key from Zoho>>'
   config.crm_modules = ['Accounts']
   config.cache_fields = true if Rails.env.development?
 end unless Rails.env.test?

and wrap the code calling the API in a <tt>begin ... rescue</tt> block.

=== Ruby Make sure the following block is executed prior to making calls to the gem.

require 'ruby_zoho'

RubyZoho.configure do |config|
  config.api_key = '<< API Key from Zoho>>'
  # config.crm_modules = ['Accounts', 'Contacts', 'Leads', 'Potentials'] # Defaults to free edition if not set
  # config.crm_modules = ['Quotes', 'SalesOrders', 'Invoices'] # Depending on what kind of account you've got, adds to free edition modules
  # config.ignore_fields_with_bad_names = true # Ignores field with special characters in the name (Release 1.8)
  # Currently only Quotes are suported
end

Please be aware that Zoho limits API calls. So running tests repeatedly will quickly exhaust your daily allowance. See below for some optimizations during development and testing.

== Use RubyZoho attempts to follow the ActiveRecord lifecycle, i.e. new, save, update and delete. See examples below. (<b>N.B. Fields cannot have special characters in them.</b>)

To get a list of supported attributes for a Zoho CRM contact:

require 'ruby_zoho'

c = RubyZoho::Crm::Contact.new
c.attr_writers  # => List of updatable attributes
c.fields # => Array of all fields

Attributes are reflected from the current API instance of Zoho, dynamically on initialization of the API, when the RubyZoho.configure block is called. This includes custom fields.

Another example:

l = RubyZoho::Crm::Lead.new
l.attr_writers  # => List of updatable attributes
l.fields # => Array of all fields

To retrieve an existing record:

l = RubyZoho::Crm::Lead.find_by_email('email@domain.com')

Returns one or more records matching the query. The find_by_<attribute> follows ActiveRecord style reflections, so if the attribute is present in the API, it can be queried. There is currently a single attribute limitation imposed by the Zoho API. Note, what is returned is an Array class which is also Enumerable. Use +.each+, +.map+, +.first+, +.last+, etc to navigate through the result set.

Equality is the only match currently supported.

To get a list of all accounts:

a = RubyZoho::Crm::Account.all
a.each do |account|
  pp account.account_name
end

Or for all task subjects:

t = RubyZoho::Crm::Task.all
pp t.collect { |task| task.subject }  # => ['Subject 1'], ['Subject 2'], ... ['Subject n']

Or for all quotes:

q = RubyZoho::Crm::Quote.all
q.each do |quote|
  pp quote.subject
  pp quote.quote_name
end

To get the first quote: q.first

Or the last one: q.last

Since the result is Enumerable: q.map { |m| m.last_name } works.

To sort a result set: r = RubyZoho::Crm::Contact.all sorted = r.sort {|a, b| a.last_name <=> b.last_name } pp sorted.collect { |c| c.last_name } # => ['Name 1', ['Name 2'], ... ['Name n']]

To find by ID, note well, ID is a string: leads = RubyZoho::Crm::Lead.all l = RubyZoho::Crm::Lead.find_by_leadid(leads.last.leadid)

To create a new record:

c = RubyZoho::Crm::Contact.new(
  :first_name => 'First Name',
  :last_name => 'Last Name',
  :email => 'email@domain.com',
  etc.
)
c.save
r = RubyZoho::Crm::Contact.find_by_email('email@domain.com')
r.first.contactid # => Has the newly created contact's ID

To add a contact to an existing account:

a = RubyZoho::Crm::Account.find_by_account_name('Very Big Account')
c = RubyZoho::Crm::Contact.new(
  :first_name => 'First Name',
  :last_name => 'Last Name',
  :email => 'email@domain.com',
  :account_name => a.first.account_name,
  :accountid => a.first.accountid  # accountid instead of account_id because of Zoho's convention
  etc.
)
c.save

To update a record (<b>Note, that the attribute is :id</b>): l = RubyZoho::Crm::Lead.find_by_email('email@domain.com') RubyZoho::Crm::Lead.update( :id => l.first.leadid, :email => 'changed_email@domain.com' )

Custom fields are like any other field or method in Ruby: a = RubyZoho::Crm::Account.find_by_account_name('Very Big Account') pp a.custom_field # => 'Custom field content'

Or: c = RubyZoho::Crm::Contact.new( :first_name => 'First Name', :last_name => 'Last Name', :email => 'email@domain.com', :account_name => a.first.account_name, :accountid => a.first.accountid, # accountid instead of account_id because of Zoho's convention :custom_field_2 => 'Custom text' ) pp c.save # Reflects back the new Zoho record ID, and various create and modify times and users

To attach a file to a record (Tested for +Accounts+, +Contacts+, +Leads+, +Potentials+ and +Tasks+ only): l = RubyZoho::Crm::Lead.find_by_email('email@domain.com') l.attach_file(file_path, file_name) # Can only be attached to a pre-existing record

To grab any attachments from a record: attachments = RubyZoho.configuration.api.related_records('Contacts', 'contact_id', 'Attachments') RubyZoho.configuration.api.download_file('Contacts', attachments.first[:id])

Classes (Zoho modules) currently supported are: RubyZoho::Crm::Account RubyZoho::Crm::Contact RubyZoho::Crm::Lead RubyZoho::Crm::Potential RubyZoho::Crm::Task RubyZoho::Crm::Quote RubyZoho::Crm::User

== Error Handling Errors, i.e. situations where the Zoho API either returns an http code something other than 200 or where the Zoho API sends back an explicit error code which <b>isn't</b> in the set

['4422', '5000']

a standard Ruby +RuntimeError+ exception is raised with the Zoho's API message.

== Optimizations for Development and Testing Set <tt>config.cache_fields = true</tt> in the configuration block. This caches \module field lists and is useful during development and testing, to reduce total API calls during start up. Defaults to false. We <b>do not</b> recommend use of this in production. The gem will need write access to its own directory for this to work.

RubyZoho.configure do |config|
  # Other stuff for initialization
  config.cache_fields = true
end

== Idiosyncractic Behavior From freedictionary.com id·i·o·syn·cra·sy ( d - -s ng kr -s ). n. pl. id·i·o·syn·cra·sies. 1. A structural or behavioral characteristic peculiar to an individual or group.

The Zoho API is definitely opinionated. And we have yet to be able plumb the depths of its views. If it behaves unexpectedly, try the Zoho forums before opening an issue here. It just may be the way the API works...

An example of this is retrieving related records. You would think that since a Task can be related to an Account or a Potential etc. that you should be able to retrieve it by either the related \module's record id, which is stored with the Task. But no, can't be done.

== Bugs and Enhancements Please open an issue on GitHub. Or better yet, send in a pull request with the fix or enhancement!

=== Known Bugs or Issues

1. If you're having trouble with updating custom fields, be sure to check the permission of the user that created the custom field.
2. Only text fields can be updated as custom fields. At this point it isn't clear what to send the Zoho API to have it accept anything else. Please send in a PR if you figure it out.

=== Roadmap (Ranked)

1. AR style master/detail updates e.g. where +a+ is an account. a << RubyZoho::Crm::Contact.new( :last_name => 'Last Name', :first_name => 'First Name' )
2. Get related records using AR style syntax, e.g. pp a.contacts to get c