ZohoHub

Simple wrapper around Zoho CRM version2, using OAuth 2.0 protocol for authentication.

This gem reads your Module configuration and builds the corresponding classes for you, using some reflection mechanisms. You should then be able to use simple classes with an API close to ActiveRecord, to do CRUD operations.

NOTE: this gem is WIP, please try to use it and open an issue if you run into limitations / problems

Installation

Add this line to your application's Gemfile:

gem 'zoho_hub'

And then execute:

$ bundle

Or install it yourself as:

$ gem install zoho_hub

Setup process

1. Register your application

If you want to access your Zoho CRM account from your application you first need to create your application as described here: https://www.zoho.com/crm/help/api/v2/#oauth-request.

TODO TODO - explain "Authorized redirect URIs"

This will give you a Client ID and a secret, that you'll use in the next step.

2. Configure ZohoHub with your credentials

You need to have a configuration block like the one below (in rails add a zoho_hub.rb in your config/initializers dir):

ZohoHub.configure do |config|
  config.client_id    = 'YOUR_ZOHO_CLIENT_ID' # obtained in 1.
  config.secret       = 'YOUR_ZOHO_SECRET'    # obtained in 1.
  config.redirect_uri = 'YOUR_ZOHO_OAUTH_REDIRECT_URL'
  # config.debug      = true # this will be VERY verbose, but helps to identify bugs / problems
end

Note: if you don't know what the redirect_url is then TODO TODO TODO TODO TODO

2. Authorization request

In order to access data in Zoho CRM you need to authorize ZohoHub to access your account. To do so you have to request a specific URL with the right scope and access_type.

To get the right URL you can use this simple line of code:

ZohoHub::Auth.auth_url
# => "https://accounts.zoho.eu/oauth/v2/auth?access_type=offline&client_id=&redirect_uri=&response_type=code&scope=ZohoCRM.modules.custom.all,ZohoCRM.settings.all,ZohoCRM.modules.contacts.all,ZohoCRM.modules.all"

If you request this generated URL you should see a screen like this one, where you have to click on "Accept":

You can change the default scope (what data can be accessed by your application). This is the list provided as the default scope:

ZohoCRM.modules.custom.all
ZohoCRM.settings.all
ZohoCRM.modules.contacts.all
ZohoCRM.modules.all

To get the URL for a different scope you can provide a scope argument:

ZohoHub::Auth.auth_url(scope: ['ZohoCRM.modules.custom.all', 'ZohoCRM.modules.all'])
# => "https://accounts.zoho.eu/oauth/v2/auth?access_type=offline&client_id=&redirect_uri=&response_type=code&scope=ZohoCRM.modules.custom.all,ZohoCRM.modules.all"

2.1 Offline access

By design the access tokens returned by the OAuth flow expire after a period of time (1 hour by default), as a safety mechanism. This means that any application that wants to work with a user's data needs the user to have recently gone through the OAuth flow, aka be online.

When you request offline access the Zoho API returns a refresh token. Refresh tokens give your application the ability to request data on behalf of the user when the user is not present and in front of your application.

By default ZohoHub::Auth.auth_url will request offline access

You can force "online" access by using #auth_url with a access_type argument:

ZohoHub::Auth.auth_url(access_type: 'online')
# => "https://accounts.zoho.eu/oauth/v2/auth?access_type=online&client_id=&redirect_uri=&response_type=code&scope=ZohoCRM.modules.custom.all,ZohoCRM.settings.all,ZohoCRM.modules.contacts.all,ZohoCRM.modules.all"

3. Generate Access Token

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.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rikas/zoho_hub.

License

The gem is available as open source under the terms of the MIT License.