README.md in zoho_hub-0.3.0 vs README.md in zoho_hub-0.4.0
- old
+ new
@@ -1,19 +1,37 @@
# ZohoHub
[](https://travis-ci.com/rikas/zoho_hub)
[](https://badge.fury.io/rb/zoho_hub)
-Simple wrapper around Zoho CRM version2, using [OAuth 2.0 protocol](https://www.zoho.com/crm/help/developer/api/oauth-overview.html)
-for authentication.
+Simple wrapper around Zoho CRM version2, using
+[OAuth 2.0 protocol](https://www.zoho.com/crm/help/developer/api/oauth-overview.html) 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**
+## Table of Contents
+
+* [Installation](#installation)
+* [Setup](#setup-process)
+ 1. [Register your application](#1-register-your-application)
+ 2. [Configure ZohoHub with your credentials](#2-configure-zohohub-with-your-credentials)
+ 3. [Authorization request](#3-authorization-request)
+ 4. [Access token](#4-access-token)
+ 5. [Refresh token](#5-refresh-token)
+ 6. [BasicZohoHub flow](#6-basic-zohohub-flow)
+ 7. [BaseRecord and record classes](#7-baserecord-and-record-classes)
+* [Tips and suggestions](#tips-and-suggestions)
+* [Examples](#examples)
+ 1. [Setup auth token and request CurrentUser](#setup-auth-token-and-request-currentuser)
+* [Development](#development)
+* [Contributing](#contributing)
+* [License](#license)
+
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -33,41 +51,46 @@
### 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/developer/api/register-client.html.
-This will give you a **Client ID** and a **secret**, that you'll use in step 2.
+This will give you a **Client ID** and a **secret**, that you'll use in
+[step 2](#2-configure-zohohub-with-your-credentials).
#### 1.1 Zoho Accounts URL
Registration and authorization requests are made to Zoho's domain-specific Accounts URL which
varies depending on your region:
+* China: https://accounts.zoho.com.cn
* EU: https://accounts.zoho.eu
+* India: https://accounts.zoho.in
* US: https://accounts.zoho.com
-* China: https://accounts.zoho.com.cn
-ZohoHub uses the EU Account URL by default, but this can be overriden in a `ZohoHub.configure`
-block via the `api_domain` method (see step 2.)
+ZohoHub uses the EU Account URL by default, but this can be overriden in a `ZohoHub.configure` block
+via the `api_domain` method ([step 2](#2-configure-zohohub-with-your-credentials).)
#### 1.2 Authorized Redirect URI
Per Zoho's API documentation, providing a **redirect URI** is optional. Doing so allows a user of
your application to be redirected back to your app (to the **redirect URI**) with a **grant token**
upon successful authentication.
-If you don't provide a **redirect URI**, you'll need to use the [self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#plink2)
-for authorization (see 3.2 below.)
+If you don't provide a **redirect URI**, you'll need to use the
+[self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#self-client) for
+authorization (see [3.2](#32-self-client-authorization).)
+---
+
### 2. Configure ZohoHub with your credentials
> **Note:** Treat these credentials like an important password. It is *strongly* recommended to not
> paste them anywhere in plain text. Do *not* add them to version control; keep them out of your
> code directly by referencing them via environment variables. Use something like the dotenv gem or
> encrypted credentials in Rails to keep them as secret and secure as possible.
-You need to have a configuration block like the one below (in rails add a `zoho_hub.rb` in your
+You need to have a configuration block like the one below (in Rails add a `zoho_hub.rb` in your
`config/initializers` directory):
```ruby
ZohoHub.configure do |config|
config.client_id = 'YOUR_ZOHO_CLIENT_ID' # obtained in 1.
@@ -76,10 +99,12 @@
config.api_domain = 'https://accounts.zoho.com' # can be omitted if in the EU
# config.debug = true # this will be VERY verbose, but helps to identify bugs / problems
end
```
+---
+
### 3. 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**. Successful
authorization will provide a **grant token** which will be used to generate **access** and
@@ -92,11 +117,12 @@
```ruby
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":
+If you request this generated URL you should see a screen like this one, where you have to click on
+"Accept":
You will then be redirected to the **redirect URI** you provided with additional query parameters
as follows (the value after `code=` is the **grant token**):
@@ -107,11 +133,12 @@
#### 3.2 Self-Client Authorization
If you don't have a **redirect URI** or you want your application to be able to authorize with Zoho
programmatically (without a user required to be present and click the "Accept" prompt), Zoho
-provides a [self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#plink2)
+provides a
+[self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#self-client)
for authentication which will provide a **grant token**.
#### 3.3 More on scopes
You can change the default scope (what data can be accessed by your application). This is the list
@@ -129,31 +156,35 @@
```ruby
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"
```
-Refer to [Zoho's API documentation on scopes](https://www.zoho.com/crm/help/developer/api/oauth-overview.html#plink5) for detailed information.
+Refer to
+[Zoho's API documentation on scopes](https://www.zoho.com/crm/help/developer/api/oauth-overview.html#scopes)
+for detailed information.
#### 3.4 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.
+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:
```ruby
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"
```
+---
+
### 4. Access token
See Zoho's API documentation for generating an initial **access token**:
https://www.zoho.com/crm/help/developer/api/access-refresh.html
@@ -161,15 +192,18 @@
`Authorization: Zoho-oauthtoken {access_token}` (without the braces.)
To use an **access token** with ZohoHub, pass it to the `ZohoHub.setup_connection` method as the
`access_token` parameter.
+---
### 5. Refresh token
TODO
+---
+
### 6. Basic ZohoHub flow
Once ZohoHub has been configured with your credentials (section 2) and you have a fresh **access
token**, setup a ZohoHub connection:
@@ -184,12 +218,15 @@
```ruby
# request a (paginated) list of all Lead records
ZohoHub.connection.get 'Leads'
```
-A successful request will receive a response like the sample here: https://www.zoho.com/crm/help/developer/api/get-records.html.
+A successful request will receive a response like the sample here:
+https://www.zoho.com/crm/help/developer/api/get-records.html.
+---
+
### 7. BaseRecord and record classes
At this point, ZohoHub is starting to do some of the heavy lifting, but using `ZohoHub.connection`
still gets tedious after just a handful of requests. But we can improve that by allowing ZohoHub
to build our record classes or by manually defining them ourselves.
@@ -206,42 +243,48 @@
inherits from `ZohoHub::BaseRecord`. For example, to build a class for the Leads module:
```ruby
# lead.rb
-class Lead < BaseRecord
+class Lead < ZohoHub::BaseRecord
...
end
```
Specify this module's fields as attributes:
```ruby
# lead.rb
-class Lead < BaseRecord
+class Lead < ZohoHub::BaseRecord
attributes: :id, :first_name, :last_name, :phone, :email, :source, # etc.
end
```
-Define an `initialize` method to populate attributes:
+Now you can issue requests more easily with your record class, e.g.:
```ruby
-def initialize(params)
- attributes.each do |attr|
- zoho_key = attr_to_zoho_key(attr)
+# Request a (paginated) list of all Lead records
+Lead.all
- send("#{attr}=", params[zoho_key] || params[attr] || DEFAULTS[attr])
- end
-end
+# Get the Lead instance with a specific ID
+Lead.find('78265000003433063')
```
-Now you can issue requests more easily with your record class, e.g.:
+And even create new Lead entries in Zoho:
```ruby
-# request a (paginated) list of all Lead records
-Lead.all
+lead = Lead.new(
+ first_name: 'First name',
+ last_name: 'Last name',
+ phone: '+35197736281',
+ email: 'myemail@gmail.com',
+ source: 'Homepage'
+)
+
+# Creates the new lead
+lead.save
```
## Tips and suggestions
* Using a tool such as Postman or curl to issue HTTP requests and verify responses in isolation
@@ -250,14 +293,98 @@
learn how the code works and test aspects of setup and Zoho's API in isolation.
* [The Zoho API Documentation](https://www.zoho.com/crm/help/developer/api/overview.html) is your
friend - especially the sample HTTP requests and responses in the various sections under "Rest
API" on the left.
* If you're manually implementing your record classes (rather than using the reflection mechanism),
- the files in `/lib/zoho_hub/deprecated_and_only_for_reference_records/` can help you get started.
-* Requests can be issued to Zoho CRM's [Sandbox](https://help.zoho.com/portal/kb/articles/using-sandbox)
+ the files in `/examples/models/` can help you get started.
+* Requests can be issued to Zoho CRM's
+ [Sandbox](https://help.zoho.com/portal/kb/articles/using-sandbox)
by configuring `https://crmsandbox.zoho.com/crm` (or regional equivalent) as the `api_domain`.
+## Examples
+
+### Setup auth token and request CurrentUser
+
+> This example assumes use of the dotenv gem and is written directly into
+> ZohoHub's root directory (rather than using ZohoHub as a gem) for simplicity.
+
+1. Edit `bin/console` to comment out refreshing the token and setting up the connection:
+
+```ruby
+# bin/console
+
+...
+# puts 'Refreshing token...'
+# token_params = ZohoHub::Auth.refresh_token(ENV['ZOHO_REFRESH_TOKEN'])
+# ZohoHub.setup_connection(token_params)
+...
+```
+
+2. [Register your application](#1-register-your-application) to obtain a **client ID** and
+**secret**. (Leave the [Zoho API Credentials page](https://accounts.zoho.com/developerconsole) open;
+you'll need it in step 5.)
+3. Determine your [Zoho Accounts URL](#11-zoho-accounts-url).
+4. Add your registration and account URL information to a `.env` file:
+
+```
+# .env
+
+ZOHO_CLIENT_ID=YOUR_CLIENT_ID
+ZOHO_SECRET=YOUR_SECRET
+ZOHO_API_DOMAIN=YOUR_ZOHO_ACCOUNTS_URL
+```
+
+5. On the [Zoho API Credentials page](https://accounts.zoho.com/developerconsole) from step 1, click
+the three vertical dots and select `Self client`.
+6. Paste this into the `Scope` field: `ZohoCRM.users.ALL`, choose an expiration time, and click
+`View Code`; this is your **Grant token**.
+7. Run the ZohoHub console from your terminal: `bin/console`
+8. Issue a token request with the **grant token** (notice the quotes around the token value):
+
+```ruby
+ZohoHub::Auth.get_token('paste_your_grant_token_here')
+```
+
+This should return a response with an **access token**, e.g.:
+
+```ruby
+=> {:access_token=>"ACCESS_TOKEN_VALUE",
+ :expires_in_sec=>3600,
+ :api_domain=>"https://www.zohoapis.com",
+ :token_type=>"Bearer"
+ }
+```
+
+exit the console with `exit`.
+
+9. Add the access token to your `.env` file:
+
+```
+# .env
+
+ZOHO_CLIENT_ID=YOUR_CLIENT_ID
+ZOHO_SECRET=YOUR_SECRET
+ZOHO_API_DOMAIN=YOUR_ZOHO_ACCOUNTS_URL
+ZOHO_ACCESS_TOKEN=YOUR_ACCESS_TOKEN
+```
+
+10. Edit `bin/console` to add a new `setup_connection` after the previously commented out one:
+
+```ruby
+# bin/console
+
+...
+# ZohoHub.setup_connection(token_params)
+
+ZohoHub.setup_connection(access_token: ENV['ZOHO_ACCESS_TOKEN'])
+...
+```
+
+11. Start the console again: `bin/console`.
+
+12. Issue a request for the current user: `ZohoHub.connection.get 'users?type=CurrentUser'`
+
## 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.
@@ -268,6 +395,7 @@
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](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).