zoho_crm 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9bd1f8b70b42d52cb21a3ed0b73fe988882479c0
+  data.tar.gz: 7684fee1463608e80503fd1b488a118084342a1b
+SHA512:
+  metadata.gz: ff4963206663ad171ecb658de505c8d653587a2cae99bf1a193dd30bdd15f7e16bf50305370e659369fc0682747566f5f7ff3c097a4c4e00c4a5882229c02594
+  data.tar.gz: f5cd1b38f1b8e6b0f59aa052c9795a74ac7a4376ed2cfab95c71a68eeecd2fc712303295230c05c44cf8f0fafb9e94922d9cf7fe64d93564a5c12d57d8f4d682

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in zoho_crm.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Ciaran Lofts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,274 @@
+# ZohoCrm
+
+zoho_crm is a basic gem to interact with the Zoho API. Methods are only available for the Leads and Contacts Zoho modules. Communication is through instantiation of the main class **ZohoCRM::Client** which requires the user to have a Zoho username and password.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'zoho_crm'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install zoho_crm
+
+## Usage
+
+Instantiate a client:
+
+```ruby
+client = ZohoCrm::Client.new("zoho@email.com", "myzohopassword")
+```
+
+Generate a token:
+
+```ruby
+auth_token = client.authenticate_user
+```
+
+Now that we have a client and an authentication token, we can interact with the Zoho API.
+
+The methods for the Contacts module are as follows:
+
+```ruby
+client.retrieve_contacts(auth_token, from_index, to_index)
+```
+
+The maximum number of records returned in one request is 200. For example, to retrieve the fist 200 contacts the method would be:
+
+```ruby
+client.retrieve_contacts("my_zoho_api_token", 1, 200)
+```
+
+Which returns a response in JSON format.
+
+**data** is required to be supplied in the following format:
+
+```ruby
+data = {
+          first_name: "Roger",
+          last_name: "Jones",
+          email: "roger@jones.com"
+        }
+```
+**id** is the Zoho Contact ID which is part of the JSON response returned by the **retrieve_contacts** method.
+
+```ruby
+client.new_contact(auth_token, data)
+```
+
+Up to 200 new Contacts can be added in batches using the **multiple_new_contacts** method.
+
+```ruby
+client.multiple_new_contacts(auth_token, data)
+```
+
+Where **data** is an array of hashes
+
+```ruby
+data = [
+          {email: "matt@craigs.com", first_name: "Matt", last_name: "Craigs"},
+          {email: "roger@jones.com", first_name: "Roger", last_name: "Jones"}
+       ]
+```
+
+```ruby
+client.update_contact(auth_token, data, id)
+```
+
+To update an individual Contact.
+
+Only the fields being updated need to be supplied in **data**. The other fields will remain untouched.
+
+Up to 100 Contacts can be updated in batches using the **update_multiple_contacts** method.
+
+```ruby
+client.update_multiple_contacts(auth_token, data)
+```
+
+Where **data** is an array of hashes and the **ID** of the Contact must be given.
+The **ID** is in the response from the **retrieve_contacts** method.
+
+```ruby
+data = [
+          {id: "1234001", email: "matt@craigs.com", first_name: "Matt", last_name: "Craigs"},
+          {id:"1234002", email: "roger@jones.com", first_name: "Roger", last_name: "Jones"}
+       ]
+```
+
+```ruby
+client.delete_contact(auth_token, id)
+```
+
+Zoho requires **last_name** for Contacts. zoho_crm supported field names for the Contacts module are:
+
+```ruby
+data = {
+          first_name: "Roger",
+          last_name: "Jones",
+          title: "CFO",
+          department: "Leveraged Loans",
+          phone: "1234",
+          mobile: "1234",
+          home_phone: "1234",
+          other_phone: "1234",
+          email: "roger@jones.com",
+          mailing_street: "Welland Mews",
+          mailing_city: "Welland Town",
+          mailing_state: "Wellandville"
+          mailing_zip: "ABC123"
+          mailing_country: "Welland Republic"
+          description: "a description"
+        }
+```
+
+Limitations of these fields can be found at https://www.zoho.com/crm/help/api/modules-fields.html#Contacts
+
+The methods for the Leads module are as follows:
+
+```ruby
+client.retrieve_leads(auth_token, from_index, to_index)
+```
+
+The maximum number of records returned in one request is 200. For example, to retrieve the fist 200 leads the method would be:
+
+```ruby
+client.retrieve_leads("my_zoho_api_token", 1, 200)
+```
+
+Which returns a response in JSON format.
+
+**data** is required to be supplied in the following format:
+
+```ruby
+data = {
+          first_name: "Roger",
+          last_name: "Jones",
+          email: "roger@jones.com"
+        }
+```
+**id** is the Zoho Lead ID which is part of the JSON response returned by the **retrieve_leads** method.
+
+```ruby
+client.new_lead(auth_token, data)
+```
+
+Up to 200 new Leads can be added in batches using the **multiple_new_leads** method.
+
+```ruby
+client.multiple_new_leads(auth_token, data)
+```
+
+Where **data** is an array of hashes
+
+```ruby
+data = [
+          {email: "matt@craigs.com", first_name: "Matt", last_name: "Craigs", company: "Welland Capital"},
+          {email: "roger@jones.com", first_name: "Roger", last_name: "Jones", company: "Welland Capital"}
+       ]
+```
+
+```ruby
+client.update_lead(auth_token, data, id)
+```
+
+To update an individual Lead.
+
+Only the fields being updated need to be supplied in **data**. The other fields will remain untouched.
+
+Up to 100 Leads can be updated in batches using the **update_multiple_leads** method.
+
+```ruby
+client.update_multiple_leads(auth_token, data)
+```
+
+Where **data** is an array of hashes and the **ID** of the Lead must be given.
+The **ID** is in the response from the **retrieve_leads** method.
+
+```ruby
+data = [
+          {id: "1234001", email: "matt@craigs.com", first_name: "Matt", last_name: "Craigs", company: "Welland Capital"},
+          {id:"1234002", email: "roger@jones.com", first_name: "Roger", last_name: "Jones", company: "Welland Capital"}
+       ]
+```
+
+```ruby
+client.delete_lead(auth_token, id)
+```
+
+Zoho requires **last_name** and **company** for Leads. The zoho_crm supported field names for the Leads module are:
+
+```ruby
+data = {
+          first_name: "Roger",
+          last_name: "Jones",
+          title: "CFO",
+          company: "Welland Capital",
+          phone: "1234",
+          mobile: "1234",
+          email: "roger@jones.com",
+          street: "Welland Mews",
+          city: "Welland Town",
+          state: "Wellandville"
+          zip: "ABC123"
+          country: "Welland Republic"
+          description: "a description"
+        }
+```
+
+Limitations of these fields can be found at https://www.zoho.com/crm/help/api/modules-fields.html#Leads
+
+The fields for both the Contacts and Leads modules can be obtained with the following method:
+
+```ruby
+client.get_fields(auth_token, module_name)
+```
+
+Which returns a response in JSON format.
+
+Where **module_name** is either:
+
+```ruby
+"Contacts"
+```
+
+or
+
+```ruby
+"Leads"
+```
+
+If custom fields have been added to either the Contacts or Leads modules by a Zoho user then this will be indicated in the response from the **get_fields** method.
+
+Provided a Zoho user has added custom fields, these can be populated using the **new_contact** , **new_lead** , **update_contact** and **update_lead** methods.
+
+These can be added to **data** with the custom field name as a hash key in lower snake case. For example, if a Zoho user add custom fields **Gender** and **Football Team** then **data** would be:
+
+```ruby
+data = {
+          gender: "Undisclosed",
+          football_team: "Welland FC"
+        }
+```
+
+N.B. It appears that zoho will only let 10 concurrent auth tokens be generated for each account. These auth tokens can be deleted manually in the 'My Account' section on Zoho.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/cjlofts/zoho_crm/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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "zoho_crm"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/zoho_crm/version.rb

@@ -0,0 +1,5 @@
+module ZohoCrm
+  class Client
+    VERSION = "1.0.0"
+  end
+end

data/lib/zoho_crm.rb

@@ -0,0 +1,196 @@
+require 'zoho_crm/version'
+require 'httparty'
+
+module ZohoCrm
+  RateLimitExceeded = Class.new(StandardError)
+  class Client
+
+    AUTH_URL = "https://accounts.zoho.com/apiauthtoken/nb/create?SCOPE=ZohoCRM/crmapi&"
+    GET_LEADS = "https://crm.zoho.com/crm/private/json/Leads/getRecords?"
+    GET_CONTACTS = "https://crm.zoho.com/crm/private/json/Contacts/getRecords?"
+    NEW_LEAD = "https://crm.zoho.com/crm/private/xml/Leads/insertRecords?"
+    NEW_CONTACT = "https://crm.zoho.com/crm/private/xml/Contacts/insertRecords?"
+    UPDATE_LEAD = "http://crm.zoho.com/crm/private/xml/Leads/updateRecords?"
+    UPDATE_CONTACT = "http://crm.zoho.com/crm/private/xml/Contacts/updateRecords?"
+    DELETE_LEAD = "http://crm.zoho.com/crm/private/xml/Leads/deleteRecords?"
+    DELETE_CONTACT = "http://crm.zoho.com/crm/private/xml/Contacts/deleteRecords?"
+    GET_FIELDS = "https://crm.zoho.com/crm/private/json/"
+    NEW_CONTACTS = "https://crm.zoho.com/crm/private/xml/Contacts/insertRecords?"
+    NEW_LEADS = "https://crm.zoho.com/crm/private/xml/Leads/insertRecords?"
+    UPDATE_CONTACTS = "https://crm.zoho.com/crm/private/xml/Contacts/updateRecords?"
+    UPDATE_LEADS = "https://crm.zoho.com/crm/private/xml/Leads/updateRecords?"
+
+    def initialize(username, password)
+      @username = username
+      @password = password
+    end
+
+    def authenticate_user
+      token_url = AUTH_URL + "EMAIL_ID=#{@username}&PASSWORD=#{@password}"
+      response = HTTParty.post(token_url)
+      response_body = response.body
+      auth_info = Hash[response_body.split(" ").map { |str| str.split("=") }]
+      auth_info["AUTHTOKEN"]
+    end
+
+    def retrieve_contacts(auth_token, from_index, to_index)
+      all_contacts = GET_CONTACTS + "authtoken=#{auth_token}&scope=crmapi&fromIndex=#{from_index}&toIndex=#{to_index}"
+      response = HTTParty.get(all_contacts)
+      raise_api_exception(response)
+    end
+
+    def retrieve_leads(auth_token, from_index, to_index)
+      all_leads = GET_LEADS + "authtoken=#{auth_token}&scope=crmapi&fromIndex=#{from_index}&toIndex=#{to_index}"
+      response = HTTParty.get(all_leads)
+      raise_api_exception(response)
+    end
+
+    def new_contact(auth_token, data)
+      xml_data = format_contacts(data)
+      formatted_data = escape_xml(xml_data)
+      new_contact = NEW_CONTACT + "authtoken=#{auth_token}&scope=crmapi&xmlData=#{formatted_data}"
+      response = HTTParty.post(new_contact)
+      raise_api_exception(response)
+    end
+
+    def new_lead(auth_token, data)
+      xml_data = format_leads(data)
+      formatted_data = escape_xml(xml_data)
+      new_lead = NEW_LEAD + "authtoken=#{auth_token}&scope=crmapi&xmlData=#{formatted_data}"
+      response = HTTParty.post(new_lead)
+      raise_api_exception(response)
+    end
+
+    def update_contact(auth_token, data, id)
+      xml_data = format_contacts(data)
+      formatted_data = escape_xml(xml_data)
+      update_contact = UPDATE_CONTACT + "authtoken=#{auth_token}&scope=crmapi&newFormat=1&id=#{id}&xmlData=#{formatted_data}"
+      response = HTTParty.put(update_contact)
+      raise_api_exception(response)
+    end
+
+    def update_lead(auth_token, data, id)
+      xml_data = format_leads(data)
+      formatted_data = escape_xml(xml_data)
+      update_lead = UPDATE_LEAD + "authtoken=#{auth_token}&scope=crmapi&newFormat=1&id=#{id}&xmlData=#{formatted_data}"
+      response = HTTParty.put(update_lead)
+      raise_api_exception(response)
+    end
+
+    def delete_contact(auth_token, id)
+      delete_contact = DELETE_CONTACT + "authtoken=#{auth_token}&scope=crmapi&id=#{id}"
+      response = HTTParty.delete(delete_contact)
+      raise_api_exception(response)
+    end
+
+    def delete_lead(auth_token, id)
+      delete_lead = DELETE_LEAD + "authtoken=#{auth_token}&scope=crmapi&id=#{id}"
+      response = HTTParty.delete(delete_lead)
+      raise_api_exception(response)
+    end
+
+    def get_fields(auth_token, module_name)
+      name = module_name.capitalize
+      fields = GET_FIELDS + name + "/getFields?authtoken=#{auth_token}&scope=crmap"
+      response = HTTParty.get(fields)
+      raise_api_exception(response)
+    end
+
+    def multiple_new_contacts(auth_token, data)
+      xml_data = format_multiple_contacts(data)
+      formatted_data = escape_xml(xml_data)
+      new_contacts = NEW_CONTACTS + "newFormat=1&authtoken=#{auth_token}&scope=crmapi&xmlData=#{formatted_data}"
+      response = HTTParty.post(new_contacts)
+      raise_api_exception(response)
+    end
+
+    def multiple_new_leads(auth_token, data)
+      xml_data = format_multiple_leads(data)
+      formatted_data = escape_xml(xml_data)
+      new_leads = NEW_LEADS + "newFormat=1&authtoken=#{auth_token}&scope=crmapi&xmlData=#{formatted_data}"
+      response = HTTParty.post(new_leads)
+      raise_api_exception(response)
+    end
+
+    def update_multiple_contacts(auth_token, data)
+      xml_data = format_multiple_contacts(data)
+      formatted_data = escape_xml(xml_data)
+      update_contacts = UPDATE_CONTACTS + "authtoken=#{auth_token}&scope=crmapi&version=4&xmlData=#{formatted_data}"
+      response = HTTParty.post(update_contacts)
+      raise_api_exception(response)
+    end
+
+    def update_multiple_leads(auth_token, data)
+      xml_data = format_multiple_leads(data)
+      formatted_data = escape_xml(xml_data)
+      update_leads = UPDATE_LEADS + "authtoken=#{auth_token}&scope=crmapi&version=4&xmlData=#{formatted_data}"
+      response = HTTParty.post(update_leads)
+      raise_api_exception(response)
+    end
+
+    private
+
+    def format_contacts(info)
+      data = "<Contacts><row no='1'>"
+      info.each do |key, value|
+        data += "<FL val='" + zohoify_key(key) + "'>" + value + "</FL>"
+      end
+      data += "</row></Contacts>"
+    end
+
+    def format_leads(info)
+      data = "<Leads><row no='1'>"
+      info.each do |key, value|
+        data += "<FL val='" + zohoify_key(key) + "'>" + value + "</FL>"
+      end
+      data += "</row></Leads>"
+    end
+
+    def format_multiple_contacts(info)
+      data = "<Contacts>"
+      row_num = 1
+      info.each do |record|
+        data += "<row no='#{row_num}'>"
+        record.each do |key, value|
+          data += "<FL val='" + zohoify_key(key) + "'>" + value + "</FL>"
+        end
+        data += "</row>"
+        row_num += 1
+      end
+      data += "</Contacts>"
+    end
+
+    def format_multiple_leads(info)
+      data = "<Leads>"
+      row_num = 1
+      info.each do |record|
+        data += "<row no='#{row_num}'>"
+        record.each do |key, value|
+          data += "<FL val='" + zohoify_key(key) + "'>" + value + "</FL>"
+        end
+        data += "</row>"
+        row_num += 1
+      end
+      data += "</Leads>"
+    end
+
+    def zohoify_key(key)
+      key.to_s.gsub("_", " ").split.map(&:capitalize).join(' ')
+    end
+
+    def escape_xml(data)
+      URI.escape(data)
+    end
+
+    def raise_api_exception(response)
+      if response["response"].nil?
+        response
+      elsif response["response"]["error"].nil?
+        response
+      else
+        raise RateLimitExceeded, "You've 'literally' exceeded your API rate limit" if response["response"]["error"]["message"] == "You crossed your license limit"
+      end
+    end
+
+  end
+end

data/zoho_crm.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'zoho_crm/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "zoho_crm"
+  spec.version       = ZohoCrm::Client::VERSION
+  spec.authors       = ["Ciaran Lofts"]
+  spec.email         = ["ciaran@wishpond.com"]
+
+  spec.summary       = %q{Light wrapper for the ZohoCRM API allowing users to interact with the Contacts and Leads modules}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  end
+
+  spec.add_dependency 'httparty'
+  spec.add_development_dependency 'bundler', "~> 1.9"
+  spec.add_development_dependency 'rake', "~> 10.0"
+  spec.add_development_dependency 'rspec'
+
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: zoho_crm
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ciaran Lofts
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-09-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- ciaran@wishpond.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/zoho_crm.rb
+- lib/zoho_crm/version.rb
+- zoho_crm.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Light wrapper for the ZohoCRM API allowing users to interact with the Contacts
+  and Leads modules
+test_files: []