CSharp-Client-Library :: Version1.5

April 28, 2014, 1:01 am

≪ Previous: CloudSQL-Client-Libraries :: Version2.6

C# Library

The C# client libraries wraps the raw HTTP based API of Zoho Reports with easy to use methods for the C# .Net platform. This enables C# .Net developers to easily use Zoho Reports API.

Prerequisites:

It is recommend to go through the Zoho Reports API Documentation and the Prerequisites before using the C# client library code in your application.

Download C# Client Library:

Download the C# client library (dll) from the following links.

ZohoReports.dll (32-bit)
ZohoReports.dll (64-bit)

Add reference to your C# Projects using these .dll files. With this you will be able to perform Zoho Reports API operations using the available functions.

Methods Summary:

C# .Net developers need to create a ReportClient object to access the below functions. The sample code snippet is below.

IReportClient RepClient = new ReportClient("-----your authtoken-----");

The ReportClient constructor has a single argument called AuthToken. You can find more information on how to get a AuthToken here. Once the ReportClient object is created, you can invoke the below methods from your C# .Net programming language.

GetURI

public string GetURI(string userEmailId)

This function returns the URI for performing User Management API requests/operations

Parameters:

string userEmailId - The Primary Email Address of your Zoho Reports Account

Returns:

The URI for performing user specific API operations

GetURI

public string GetURI(string AdminEmailId, string DatabaseName)

This function returns the URI for performing Zoho Reports Database specific API operations.

Parameters:

string AdminEmailId - The Primary Email Address of your Zoho Reports Account.
string DatabaseName - The Zoho Reports Database Name

Returns:

The URI for performing Zoho Reports Database specific API operations

GetURI

public string GetURI(string AdminEmailId, string DatabaseName, string ViewName)

This function returns the URI for performing Zoho Reports View specific API operations.

Parameters:

string AdminEmailId - The Primary Email Address of your Zoho Reports Account.
string DatabaseName - The Zoho Reports Database Name
string ViewName - The Zoho Reports View Name. This could be a chart, pivot table, summary view, table, query table or dashboard created in Zoho Reports.

Returns:

The URI for performing Zoho Reports View specific API operations

Import Data

public Dictionary<string,string> ImportData(string TableURI, string ImportType, string CSVFilePath, Dictionary<string, string> ImportConfig)

This function is used to Import data from a local CSV/TSV/Txt file into Zoho Reports Online Reporting Database Table. This function is referring to Zoho Reports Import API.

Parameters:

string TableURI - The URI of the Table, into which the data has to be imported, got from the GetURI function
string ImportType - The Import Type for the import process. This can be taken from ZohoReportsConstants file (which has all the constant variables used in this Library).
string CSVFilePath - The file path of your data file
Dictionary ImportConfig - This parameter holds the import parameters such as ZOHO_ON_IMPORT_ERROR, ZOHO_DATE_FORMAT, etc. You can check out the list of import parameters here.

Returns:

The import summary with summary name as Key and summary value as Value

Add Row

public Dictionary <string,string> AddRow(string TableURI, Dictionary<string,string> ColumnValues, Dictionary<string,string> Config)

This function is used to Add a row to a Zoho Reports Table. The row data present in the ColumnValues Dictionary will be added as a row in the specified Zoho Reports Table. This function uses the HTTP Zoho Reports Add Row API.

Parameters:

string TableURI - The URI of the table, into which the data is to be added, got from the GetURI function
Dictionary ColumnValues - The Dictionary of Column Names and Values. The Values are added to the respective columns specified in the columnValues Dictionary.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Returns:

Added values with column name as Key and row value as Value

Update Data

public void UpdateData(string TableURI, Dictionary<string, string> ColumnValues, string Criteria, Dictionary<string, string> Config)

This function is used to Update Rows in a Zoho Reports Table which matches the specified criteria. If the criteria provided is null, then all the rows will be updated with the new values provided in ColumnValues Dictionary. This function uses the HTTP Zoho Reports Update Data API.

Parameters:

string TableURI - The URI of the table, in which the data is to be updated, got from the GetURI function
Dictionary ColumnValues - The Dictionary of Column Names and Values. The Values are updated to the respective columns specified in the columnValues Dictionary.
string Criteria - Criteria for updating rows. The rows matching the specified criteria alone will get updated. The criteria follows the SQL SELECT WHERE condition like format. More details on specifying Zoho Criteria is available in Applying Filters section.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Delete Data

public void DeleteData(string TableURI, string Criteria, Dictionary<string, string> Config)

This function is used to Delete the Rows in a Zoho Reports Table which matches the specified criteria. If the criteria provided is null, then all the rows will be deleted. This function uses the HTTP Zoho Reports Delete Data API.

Parameters:

string TableURI - The URI of the table, in which the data is to be deleted, got from the GetURI function
string Criteria - Criteria for deleting rows. The rows matching the specified criteria alone will get deleted. The criteria follows the SQL SELECT WHERE condition like format. More details on specifying Zoho Criteria is available in Applying Filters section.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Export Data As JSON

public string ExportDataAsJSON(string ViewURI, string Criteria, Dictionary<string, string> Config)

This function is used to Export the data from a Zoho Reports Table / Report in a JSON format. This function uses the HTTP Zoho Reports Export API.

Parameters:

string ViewURI - The URI of the view, from which the data is to be exported, got from the GetURI function
string Criteria - Criteria for exporting data. The rows matching the specified criteria alone will get exported. The criteria follows the SQL SELECT WHERE condition like format. More details on specifying Zoho Criteria is available in Applying Filters section.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Returns:

The JSON string which contains the exported data

Export Data As CSV

public string ExportDataAsCSV(string ViewURI, string Criteria, Dictionary<string, string> Config)

This function is used to Export the data from a Zoho Reports Table / Report in a CSV format. This function uses the HTTP Zoho Reports Export API.

Parameters:

string ViewURI - The URI of the view, from which the data is to be exported, got from the GetURI function
string Criteria - Criteria for exporting data. The rows matching the specified criteria alone will get exported. The criteria follows the SQL SELECT WHERE condition like format. More details on specifying Zoho Criteria is available in Applying Filters section.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Returns:

The CSV string which contains the exported data

Export Data As File

public void ExportData(string ViewURI, string Format, String OutputFileName, string Criteria, Dictionary<string, string> Config)

This function is used to export the Zoho Reports Table / Report / Dashboard data in the name of the specified file. This function uses the HTTP Zoho Reports Export API.

Parameters:

string ViewURI - The URI of the view, from which the data is to be exported, got from the GetURI function
string Format - The output format for exporting the data. The supported formats are CSV, XML, JSON, HTML, PDF, IMAGE.
string OutputFileName - The data will be exported to the specified output file in the local machine.
string Criteria - Criteria for exporting data. The rows matching the specified criteria alone will get exported. The criteria follows the SQL SELECT WHERE condition like format. More details on specifying Zoho Criteria is available in Applying Filters section.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Export Data As Stream

public void ExportData(string ViewURI, string Format, Stream outputStream, string Criteria, Dictionary<string, string> Config)

This function is used to export the Zoho Reports Table / Report / Dashboard data in the specified Output Stream. This function uses the HTTP Zoho Reports Export API.

Parameters:

string ViewURI - The URI of the view, from which the data is to be exported, got from the GetURI function
string Format - The output format for exporting the data. The supported formats are CSV, XML, JSON, HTML, PDF, IMAGE.
Stream OutputStream - The output stream to which the data has to be exported.
string Criteria - Criteria for exporting data. The rows matching the specified criteria alone will get exported. The criteria follows the SQL SELECT WHERE condition like format. More details on specifying Zoho Criteria is available in Applying Filters section.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Export Data As Dictionary

public Dictionary<string,object> ExportDataAsDictionary(string ViewURI, string Criteria, Dictionary<string, string> Config)

This function is used to export the Zoho Reports Table / Report data as C# Dictionary object. You can then parse this object to retrieve the resultant data. This function uses the HTTP Zoho Reports Export API.

Parameters:

string ViewURI - The URI of the view, from which the data is to be exported, got from the GetURI function
string Criteria - Criteria for exporting data. The rows matching the specified criteria alone will get exported. The criteria follows the SQL SELECT WHERE condition like format. More details on specifying Zoho Criteria is available in Applying Filters section.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Returns:

It returns Dictionary<string,object> containing the data. You can iterate this object to get the result. The sample resultant Dictionary will be as below.

Key<string>: column_order
Value<Object[]>: ["column1","column2",..,"columnN"]

Key<string>: rows
Value<Object[]>: [ [value11,value12,..,value1N],[value21,valuu22,..,value2N] ]

Export Data Using SQL As File

public void ExportDataUsingSQL(string ViewURI, string Format, String OutputFileName, string SQLQuery, Dictionary<string, string> Config)

This function is used to export the Table data got by executing the given SQL SELECT Query in your Zoho Reports database. This function uses the HTTP Zoho Reports Cloud SQL API Specification.

Parameters:

string ViewURI - The URI of the view, from which the data is to be exported, got from the GetURI function
string Format - The output format for exporting the data. The supported formats are CSV, XML, JSON, HTML, PDF, IMAGE.
string OutputFileName - The data will be exported to the specified output file in the local machine
string SQLQuery - The SQL SELECT Query which has to be executed to fetch the result set that is to be executed
Dictionary Config - The Dictionary for sending extra parameters, if any.

Export Data Using SQL As Stream

public void ExportDataUsingSQL(string ViewURI, string Format, Stream outputStream, string SQLQuery, Dictionary<string, string> Config)

This function is used to export the Table data got by executing the given SQL SELECT Query in your Zoho Reports database. The data will exported into the specified output stream. This function uses the Zoho Reports Cloud SQL API Specification.

Parameters:

string ViewURI - The URI of the view, from which the data is to be exported, got from the GetURI function
string Format - The output format for exporting the data. The supported formats are CSV, XML, JSON, HTML, PDF, IMAGE.
Stream OutputStream - The output stream to which the data has to be exported.
string SQLQuery - The SQL SELECT Query which has to be executed to fetch the result set that is to be executed
Dictionary Config - The Dictionary for sending extra parameters, if any.

Meta Data

public string GetDatabaseMetaData(string DatabaseURI, string MetaData, string format, Dictionary<string, string> Config)

This function is used to get the Zoho Reports Database Metadata in the specified format (XML / JSON). You can then parse this XML / JSON to retrieve the resultant data.

Parameters:

string DatabaseURI - The corresponding Zoho Reports Database URI got from the GetURI function
string MetaData - The metadata type which can be got from ZohoReportsConstants file.
string format - The response format for the metadata. The supported formats are XML and JSON.
Dictionary Config - The Dictionary for sending extra parameters, if any.

Returns:

The meta data will be returned as an XML / JSON (based on the specified format) which you can parse to get the meta data.

Get Copy DB Key

public string GetCopyDBKey(string DatabaseURI, Dictionary<string, string> Config)

This function is used to get the Copy Database Key. This key will be required in CopyDatabase function for copying the database.

Parameters:

string DatabaseURI - The corresponding Zoho Reports Database URI got from the GetURI function
Dictionary Config - The Dictionary for sending extra parameters, if any.

Returns:

The Copy Database Key for the specified database in the DatabaseURI

Copy Database

public long CopyDatabase(string DatabaseURI, string NewDBName, string NewDBDescription, bool WithData, string CopyDBKey, Dictionary<string,string> Config)

This function is used to copy the database in your Zoho Reports Account. The database will be copied, if the CopyDBKey is valid.

Parameters:

string DatabaseURI - The URI of the Zoho Reports Database to be copied, got from the GetURI function
string NewDBName - The Database Name for the newly copied database
string NewDBDescription - The Description for the newly copied database
bool WithData - If true, the database will be copied along with data, else the database will be copied without data
Dictionary Config - The Dictionary for sending extra parameters, if any.

Returns:

The Database ID for the newly copied database

Delete Database

public void DeleteDatabase(string AccountURI, string DatabaseName, Dictionary<string, string> Config)

This function is used to delete a database from your Zoho Reports Account.

Parameters:

string AccountURI - Your Zoho Reports Account URI got from the GetURI function
string DatabaseName - The name of the database to be deleted

Add User

public void AddUser(string AccountURI, string EmailIds, Dictionary<string, string> Config)

This function is used to Add one or more users to your Zoho Reports Account. The added users will be associated to the Administrator's Zoho Reports Account. This function does not Sign Up the user in Zoho, if the added user does not exists in Zoho. By default all the new users added will be set to Active state, and will be counted into Zoho Reports account user limit.

Parameters:

string AccountURI - Your Zoho Reports AccountURI got from GetURI function
string EmailIds - The Zoho primary email addresses of the users to be added, separated by comma (,)
Dictionary Config - The Dictionary for sending extra parameters, if any.

Remove User

public void RemoveUser(string AccountURI, string EmailIds, Dictionary<string, string> Config)

This function is used to Remove one or more users from your Zoho Reports Account. This action does not remove the user from Zoho, just removes the association of that user in your Zoho Reports account.

Parameters:

string AccountURI - Your Zoho Reports AccountURI got from GetURI function
string EmailIds - The Zoho primary email addresses of the users to be removed, separated by comma (,)
Dictionary Config - The Dictionary for sending extra parameters, if any.

Activate User

public void ActivateUser(string AccountURI, string EmailIds, Dictionary<string, string> Config)

This function is used to Activate one or more users in your Zoho Reports Account.

Parameters:

string AccountURI - Your Zoho Reports AccountURI got from GetURI function
string EmailIds - The Zoho primary email addresses of the users to be activated, separated by comma (,)
Dictionary Config - The Dictionary for sending extra parameters, if any.

De-Activate User

public void DeActivateUser(string AccountURI, string EmailIds, Dictionary<string, string> Config)

This function is used to Deactivate one or more users in your Zoho Reports Account.

Parameters:

string AccountURI - Your Zoho Reports AccountURI got from GetURI function
string EmailIds - The Zoho primary email addresses of the users to be de-activated, separated by comma (,)
Dictionary Config - The Dictionary for sending extra parameters, if any.

Set Web Proxy

public void SetWebProxy(string host, int port, string user, string password)

This function is used to set the proxy details if your network uses proxy.

Parameters:

string host - The host name or IP Address of your proxy host
int port - The port number for connecting your proxy
string user - The username for authenticating to your proxy
string password - The password for authenticating to your proxy

ZohoReportsConstants:

This C# client library has a sealed class called ZohoReportsConstants. This class has the list of constants used in this library. The available constants are below.

Constants used in GetDatabaseMetaData function:

ZOHO_CATALOG_LIST - To list the Zoho Reports databases for the specified user
ZOHO_CATALAOG_INFO - To fetch information about the tables & reports (view) present in the given reporting database in Zoho Reports.
ZOHO_DATATYPES - To get the list of datatypes supported by Zoho Reports
ZOHO_TABLETYPES - Various view types available in Zoho Reports

Constants used in ImportData function:

APPEND - Appends the data into the table
TRUNCATEADD - Deletes all existing rows in the table and adds the imported data as a new entry
UPDATEADD - Updates the row if the mentioned column values (in ZOHO_MATCHING_COLUMNS parameter) are matched, else a new entry will be added

Sample Program:

The below sample program illustrates how to invoke Zoho Reports API using Zoho Reports C# client library.

The program steps are classified as follow.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using ZReports;  // Namespace which contains classes for invoking Zoho Reports APIs

namespace MyZohoReportsClient
{
    class MyJob
    {

        /*
          Creating ReportClient object for invoking Zoho Reports APIs
        */
        public IReportClient getClient()
        {
            // Creating ReportClient Object using Auth Token
            // ReportClient class contains all the supported API operations as functions
            IReportClient RepClient = new ReportClient("---your_authtoken_here---");
            return RepClient;
        }

        /*
 
          The following method uses Zoho Reports IMPORT API to import the data from a local file into Zoho Reports Table. 
          This method illustrates importing data from the location "C:\workspace\mydata.csv" into the table named "MyTable1" in "MyDB" reporting database. 
          The usage of Import API is described below.
 

          IMPORT API:
          The IMPORT API allows you to import the data from your local file into Zoho Reports Table.

          Zoho Reports C# Library Function:
          ImportData(string tableURI, string ImportType, string FilePath, Dictionary<string,string> ImportConfig)

          Parameters:
             string tableURI
             This is the URI for the Zoho Reports Table into which the data has to be imported.
             Get the tableURI from GetURI(emailId,databaseName,tableName) function.
             The GetURI function will get your email address, the Zoho Reports Database Name and Zoho Reports Table Name as parameters.

             string ImportType
             This specifies how to import data. The Import type parameter can be set to APPEND, TRUNCATEADD or UPDATEADD. These constants can be set from ZohoReportsConstants class
             To know more about the Import Types, refer the Zoho Reports Import API Parameters section.

             string FilePath
             The location of the file which needs to be imported into Zoho Reports. The Import API will read the data from the file specified in this parameter and uploads the same
             into Zoho Reports Table.

             Dictionary<string,string> ImportConfig
             Dictionary to specify the additional Import Parameters. This Dictionary has the Parameter Name as Key and Parameter Value as Value.
 
          This ImportData function returns the Import Summary as a Dictionary

        */

        public void importData(IReportClient RepClient)
        {
            string tableURI = RepClient.GetURI("testuser@zoho.com", "MyDB", "MyTable1");
            Dictionary<string, string> ImportConfig = new Dictionary<string, string>();
            ImportConfig.Add("ZOHO_ON_IMPORT_ERROR", "ABORT");
            Dictionary<string, string> ImportRes = RepClient.ImportData(tableURI, ZohoReportsConstants.APPEND, "C:\\workspace\\mydata.csv",ImportConfig);
        }

        /*
 
          The following method uses Zoho Reports ADDROW API to add a single row into the Zoho Reports Table. 
          This method illustrates adding a single row to the table "MyTable1" in "MyDB" database. This table consists of a single column named "Region" 
          The usage of AddRow API is described below.
 

          ADDROW API:
          The ADDROW API allows you to add a single row into the specified Zoho Reports table.

          Zoho Reports C# Library Function:
          AddRow(string tableURI,Dictionary<string,string> ColumnValues,Dictionary<string,string> Config)

          Parameters:
             string tableURI
             This is the URI for the Zoho Reports Table into which the data has to be imported.
             Get the tableURI from GetURI(emailId,databaseName,tableName) function.
             The GetURI function will get your email address, the Zoho Reports Database Name and Zoho Reports Table Name as parameters.

             Dictionary<string,string> ColumnValues
             The Dictionary which has Zoho Reports Table Column Name as Key and Column Value as Value. 
             All the entries in the ColumnValues Dictionary will be added as a Row in the specified table in the tableURI

             Dictionary<string,string> Config
             Useful for sending additional parameters, if any. This Dictionary has the Parameter Name as Key and Parameter Value as Value.
 
          This AddRow function returns the added values as a Column Name vs. Column Value Dictionary

        */

        public void addRow(IReportClient RepClient)
        {
            string tableURI = RepClient.GetURI("testuser@zoho.com", "MyDB", "MyTable1");
            Dictionary<string, string> ColumnValues = new Dictionary<string, string>();
            ColumnValues.Add("Region", "South");
            Dictionary<string, string> addRowRes = RepClient.AddRow(tableURI, ColumnValues, config);
        }



        /*
 
          The following method uses Zoho Reports UPDATE API to update rows in Zoho Reports Table. 
          This method illustrates updating the value 'South' with 'North' for the column "Region" in the Zoho Reports table "MyTable1" in "MyDB" database.
          The usage of UpdateData API is described below.
 

          UPDATE API:
          The data present in a Zoho Reports Table can be updated using Zoho Reports UPDATE API.

          Zoho Reports C# Library Function:
          UpdateData(string tableURI, Dictionary<string,string> ColumnValues, string criteria, Dictionary<string,string> Config)

          Parameters:
             string tableURI
             This is the URI for the Zoho Reports Table into which the data has to be updated.
             Get the tableURI from GetURI(emailId,databaseName,tableName) function.
             The GetURI function will get your email address, the Zoho Reports Database Name and Zoho Reports Table Name as parameters.

             Dictionary<string,string> ColumnValues
             The Dictionary which has Zoho Reports Table Column Name as Key and Column Value as Value. 
             All the entries in the ColumnValues Dictionary will be updated in the specified table in the tableURI

             string criteria
             Criteria for updating data. The rows matching this criteria alone will get updated. 
             The criteria should follow the same format as that of the SQL WHERE clause.
             To know more about specifying criteria, refer the Applying Filters section in Zoho Reports API Documentation.

             Dictionary<string,string> Config
             Useful for sending additional parameters, if any. This Dictionary has the Parameter Name as Key and Parameter Value as Value.
 
          This UpdateData function will not return any object.
         */
        public void updateRow(IReportClient RepClient)
        {
            string tableURI = RepClient.GetURI("testuser@zoho.com", "MyDB", "MyTable1");
            Dictionary<string, string> ColumnValues = new Dictionary<string, string>();
            ColumnValues.Add("Region", "North");
            string criteria = "\"Region\"='South'";
            RepClient.UpdateData(tableURI, ColumnValues, criteria, null);
        }



        /*
 
          The below method uses Zoho Reports DELETE API to delete rows in Zoho Reports Table. 
          In this method, the rows matching value 'South' in column Region is deleted from the table MyTable1 in MyDB database.
          The usage of DeleteData API is described below.
 

          DELETE API:
          The data present in a Zoho Reports Table can be deleted using Zoho Reports DELETE API.

          Zoho Reports C# Library Function:
          DeleteData(string tableURI, string criteria, Dictionary<string,string> Config)

          Parameters:
             string tableURI
             This is the URI for the Zoho Reports Table into which the data has to be deleted.
             Get the tableURI from GetURI(emailId,databaseName,tableName) function.
             The GetURI function will get your email address, the Zoho Reports Database Name and Zoho Reports Table Name as parameters.
             string criteria
             Criteria for deleting data. The rows matching this criteria alone will get deleted. 
             The criteria should follow the same format as that of the SQL WHERE clause.
             To know more about specifying criteria, refer to the Applying Filters section in Zoho Reports API Documentation.

             Dictionary<string,string> Config
             Useful for sending additional parameters, if any. This Dictionary has the Parameter Name as Key and Parameter Value as Value.
 
          This DeleteData function will not return any object.

        */
        public void deleteRow(IReportClient RepClient)
        {
            string tableURI = RepClient.GetURI("testuser@zoho.com", "MyDB", "MyTable1");
            string criteria = "\"Region\"='South'";
            RepClient.DeleteData(tableURI, criteria, null);
        }



        /*
 
          The following method uses Zoho Reports EXPORT API to Export data from a Zoho Reports Table or Report. 
          This method illustrates exporting the data matching value 'West' in column "Region" from the Zoho Reports Table "MyTable1" in "MyDB" database.
          The usage of Export API is described below.
 

          EXPORT API:
          The data present in a Zoho Reports Table or Report can be exported using Zoho Reports EXPORT API.

          Zoho Reports C# Library Function:
          ExportDataAsObject(string tableOrReportURI, string criteria, Dictionary<string,string> Config)

          Parameters:
             string tableOrReportURI
             This is the URI for the Zoho Reports Table or Report from which the data has to be exported.
             Get the tableOrReportURI from GetURI(emailId,databaseName,tableNameOrReportName) function.
             The GetURI function will get your email address, the Zoho Reports Database Name and Zoho Reports Table Name as parameters.
             string criteria
             Criteria for exporting data. The rows matching this criteria alone will get exported. 
             The criteria should follow the same format as that of the SQL WHERE clause.
             To know more about specifying criteria, refer to the Applying Filters section in Zoho Reports API Documentation.

             Dictionary<string,string> Config
             Useful for sending additional parameters, if any. This Dictionary has the Parameter Name as Key and Parameter Value as Value.
 
          This ExportDataAsObject function will return an object which can be iterated to get the result.
         */
        public object export(IReportClient RepClient)
        {
            string tableURI = RepClient.GetURI("testuser@zoho.com", "MyDB", "MyTable1");
            Dictionary<string, object> resObj = RepClient.ExportDataAsDictionary(tableURI, "\"Region\"='West'", null);
            Object[] columns = (Object[])resObj["column_order"];
            Object[] rows = (Object[])resObj["rows"];
       }



        public static void Main(string[] s)
        {
            MyJob myJob = new MyJob();
            IReportClient rc = myJob.getClient();
            myJob.importData(rc);
            myJob.addRow(rc);
            myJob.updateRow(rc);
            myJob.deleteRow(rc);
            myJob.export(rc);
            Console.Read();
        }
    }
}

↧

JDBC-Driver :: Version10.1

May 13, 2014, 2:03 am

≫ Next: SSO-Integration :: Version1.7

≪ Previous: CSharp-Client-Library :: Version1.5

JDBC Driver for Zoho Reports CloudSQL

As CloudSQL enables users to execute SQL queries on structured data stored in Zoho Reports, it lends itself naturally to support Database Connectivity Standard like JDBC (Java Database Connectivity). Developers who are familiar using JDBC driver for connectivity to databases, can now use Zoho Reports CloudSQL JDBC driver to connect and execute the necessary SQL queries.

With the availablity of this JDBC driver, developers need not learn the Zoho Reports CloudSQL HTTP Web API to execute the SQL query. They just have know how to use the Zoho Reports JDBC driver and start interacting with the service, the same way as they would interact with a database using a JDBC standard driver.

JDBC Connection URL for Zoho Reports

JDBC Type Mapping with Zoho Reports Data types

Connecting Zoho Reports from Database Visualization Tools

DBVisualizer

Squirrel SQL Client

Zoho Reports JDBC Driver Download

Download the Zoho Reports JDBC Driver from the below link.

http://css.zohostatic.com/db/api/v4_m1/ZohoCloudSQLJDBC_1_0.zip

Javadocs

Javadocs of Zoho Reports JDBC Driver
Javadocs of JDBC interface (package java.sql)

Zoho Reports JDBC Driver

To use the JDBC Driver you need to have a zoho login email address and password. Currently you could only execute Select queries using the JDBC driver. Other SQL statements will be supported soon.

In JDBC, the DriverManager class manages the establishment of connections. DriverManager needs to be told which JDBC driver it should try to make connections with. The way to do this is to use Class.forName( ) on the class that implements java.sql.Driver interface.

Refer to the Zoho Reports JDBC Driver javadocs to know more about the same. Click to download Zoho Reports JDBC Driver.

JDBC Connection URL for Zoho Reports

https://reportsapi.zoho.com/api/<zoho_username_dbowner>/<databasename>?user=<zoho_username>&password=<zoho_password>

Sample

The following Java code snippet shows how you can register Zoho Reports CloudSQL JDBC driver, obtain a Connection, create a Statement and execute the query:

import java.sql.DriverManager;
import java.sql.Connection;
import java.sql.Statement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.Properties;	

public class ZohoReportsCloudSQL
{
       public static void main(String args[])
       {
              Connection con = null; 
              Statement stmt = null;
	      ResultSet rs = null;
	      try
	      {
                     Class.forName("com.zoho.cloudsql.jdbc.ZohoReportsDriver");
                     Properties conProps = new Properties();     
                     conProps.put("ZOHO_API_KEY","abcd");
                     // Zoho username to login to Zoho service
		     conProps.put("user","david");
	
                     // Zoho password to login to Zoho service
		    conProps.put("password","davidpwd");

      	             // Uncomment this incase you need proxy settings
                     /*
              	     // Proxy host name to connect the internet
      		     conProps.put("PROXYSERVER","proxy_hostname");
      		     // Proxy port to connect the internet
      		     conProps.put("PROXYPORT","proxy_port");
      		     // Proxy user name to connect the internet
      		     conProps.put("PROXYUSERNAME","proxy_username");
      		     // Proxy password to connect the internet
      		     conProps.put("PROXYPASSWORD","proxy_password");
	             */
	             
                     /* Important Note: Connection is single threaded in Zoho Reports */

		     // david is the owner of the database 'Sales'

		     con = DriverManager.getConnection("https://reportsapi.zoho.com/" + "api/david/Sales",conProps);
      	             stmt = con.createStatement();
		     String sql ="select * from <tablename>";
		     rs = stmt.executeQuery(sql);
	      }
	      catch(SQLException se)
	      {
      	             // handle any errors
		     System.out.println("SQLException: " + se.getMessage());
		     System.out.println("Zoho Reports Error code: " + se.getErrorCode());
	      }
	      catch(Exception e)
	      {
      	             // handle the exception
	      }
	      finally
              {
      	             if(rs != null)
		     {
      		            try
      		            {
              		           rs.close();
      		            }
      		            catch(SQLException sqlEx) { } // ignore
 		     }
		     if(stmt != null)
		     {
      		            try
              	            {
                      	           stmt.close();
      		            }
      		            catch (SQLException sqlEx) { } // ignore
		     }
		     if(con != null)
      	             {
      		            try
      		            {
              		           con.close();
      		            }
      		            catch (SQLException sqlEx) { } // ignore
		     }
              }
       }
}

Following methods can also be used to obtain the connection:

DriverManager.getConnection("https://reportsapi.zoho.com/api/david/Sales?" +
"david","davidpwd");

DriverManager.getConnection("https://reportsapi.zoho.com/api/david/Sales?" +
"user=david&password=davidpwd");

Jars to be kept in CLASSPATH for JDBC Driver

All the jars from 'lib' directory within the JDBC Driver Zip need to be kept in CLASSPATH for JDBC driver.

JDBC Type Mapping with Zoho Reports Data types

The following table provides the mapping between the Zoho Reports data types and the JDBC SQL types. Use this mapping to process the data fetched from Zoho Reports in your Java code.

Zoho Reports Data type	JDBC SQL Type
Plain Text	VARCHAR
Multi Line Text	LONGVARCHAR
Email	VARCHAR
Auto Number	BIGINT
Number	BIGINT
Positive Number	BIGINT
Decimal Number	DOUBLE
Currency	DOUBLE
Percent	DOUBLE
Date	TIMESTAMP
Decision Box	BIT

Connecting Zoho Reports from Database Visualization Tools

Zoho Reports JDBC Driver supports connecting Zoho Reports from the following Database Visualizations tools.

DBVisualizer
Squirrel SQL Client

DbVisualizer tool

You can connect to Zoho Reports from the DbVisualizer tool by following the steps below.

Step 1: Create a New Driver Name

Click Tools > Driver Manager from the toolbar menu. The Driver Manager dialog will open.
In the Driver Settings options, specify the name for the New Driver in the Name field (say, ZohoReportsDriver)
In the URL Format field enter the URL in the format https://reportsapi.zoho.com/api/<zoho_user_email_address>/<zoho_database_name>.
Provide the Driver Class name of Zoho Reports JDBC driver (com.zoho.cloudsql.jdbc.ZohoReportsDriver) used for connecting Zoho Reports.
In the Driver File Paths group option, on the User Specified tab click the File icon to add JAR files. Browse and add all relevant jar file for Zoho Reports JDBC driver.
Close the wizard.

Step 2: Creating New Database Connection

Click Create new database connection icon in Databases list window. It will prompt to select Use Wizard or No Wizard.
Choose Use Wizard option. New Connection Wizard will open.
Enter the connection alias name for the new database connection and then click Next.

Select the appropriate database driver (ZohoReports Driver) from the drop down and then click Next button.

In the Database URL field, specify the URL of the database to be connected as follow.
Format: https://reportsapi.zoho.com/api/<zoho_user_email_address>/<zoho_database_name>
Example: https://reportsapi.zoho.com/api/david@zoho.com/Sales
Specify Zoho Login Email Address and password for authentication and then click Finish.
Click Finish to complete the creation of the new connection.

Connections Overview

The Connection Overview will list all the database connections configured in the tool, on selecting the Connections object in the Databases Objects Tree. To connect to your Zoho Reports account, double click the Zoho Reports connection. All the databases in your account along with the table will be listed.

Executing a SQL SELECT Query

Follow the below steps to execute a SQL SELECT query in your Zoho Reports database.

Click Create a new SQL commander tab icon from the toolbar.
Choose database name from the Database drop down.
Specify SQL SELECT Query in QUERY area and run the query.
Only SQL SELECT queries can be used to access Zoho Reports from the tool.

Squirrel SQL Client

You can also connect to Zoho Reports from the Squirrel SQL client. To connect to a Zoho Reports database from Squirrel SQL client, you need to provide two set of information i.e., the driver definition and the alias. The driver definition specifies the JDBC driver to use and the alias specifies the connection parameters.

Steps for Creating New Driver Definitio
Create a new driver definition to specify the JDBC driver by following the steps below.

Click Windows > View Drivers from the toolbar menu.
>Click the Create a New Driver (+) icon in the driver List window. The Add Driver wizard will open.
Specify the Name for the driver in the Name field (say, ZohoReportsDriver).
In the Example URL field, enter the URL format https://reportsapi.zoho.com/api/<zoho_user_email_address>/<zoho_database_name>
Specify https://zohoreportsapi.wiki.zoho.com/JDBC-Driver.html in the Website URL, which allows you to store a link.
Open Extra Class Path tab and click Add. You will find option to add JAR files.
To ensure it is added properly, click the List Drivers button. The class name found in the class path of the Zoho Report's JDBC driver will be listed in the Class Name drop down.
>Click OK.

Steps for Adding Alias

Alias holds all configurations to connect to a database. Create new alias for Zoho Reports to specify the connection parameters by following the steps below.

Click Windows > Aliases from the toolbar menu.
Click the Create a New Alias (+) icon in the Aliases List window. The Add Alias wizard will open.
Specify the alias name for the database connection in the Name field.
Select the driver for this alias from the Driver drop down.
In the URL field, specify the URL of the database to be connected as follow.
Format: https://reportsapi.zoho.com/api/<zoho_user_email_address>/<zoho_database_name>
Example: https://reportsapi.zoho.com/api/david@zoho.com/Sales
Specify the Zoho Username and Password. This is optional. You could save the user credentials by specifying here for further data upload.
The Test button will allow you to ensure that the parameters you have entered are correct by attempting to connect to your alias.
Click OK to save the alias definition.

Connecting to Zoho Reports Database

Follow the steps below to connect to a database in Zoho Reports

The newly created alias will be listed in the Aliases List Window. Right-click on alias Name and then click Connect.
The connection will be established to your Zoho Reports account and the Object Tree will display the structure of the reporting database in Zoho Reports.

Executing a SQL SELECT Query

SQL SELECT Query can be executed from the SQL tab as said below.

Open the SQL tab.
Specify the required SQL SELECT query to execute in your Zoho Reports database.
Click Run SQL icon in the session Window toolbar to execute the query.>
Only SQL SELECT queries can be executed in Zoho Reports from the tool.

Next: Zoho Reports CloudSQL Client Libraries

↧

SSO-Integration :: Version1.7

February 4, 2015, 5:39 pm

≫ Next: Zoho-Reports-API :: Version13.1

≪ Previous: JDBC-Driver :: Version10.1

SSO API is only available for White Label customers of Zoho Reports. If you want to know about SSO Integration, email support@zohoreports.com

Single Sign On Integration

Zoho Reports offer a full-fledged white label (private label) solution. As a part of it, it supports Single Sign on (SSO) with your website / application. Using the below mentioned procedure, it would be possible for you to implement a loosely coupled login mechanism for the white labeled Zoho Reports solution, that works with almost ANY authentication system that you currently are using. This would involve program changes in your website/application (code to be written at your end). This page outlines the various steps to setup, perform unit/integration testing and to go live with Zoho's third party SSO integration.

Setup Phase

Provide the following information to the Zoho Reports team:
- IP addresses of your test and production setups
- The login and logout page URLs of your website (these will process login and logout requests coming from Zoho Reports; needed for your test and production setups too)
- Domain/sub-domain names (CNAME mapping) for test and production setups. CNAME map your test/production sub-domains to customer-reports.zoho.com
- Fill the following Zoho Creator form to design your custom page - https://creator.zoho.com/zohodbhelp/domain-rebranding/#Form:DomainProperties
After submitting the above information to the Zoho Reports team, we will send you an API key to be used you. (this is a different API key than the one provided at http://api.zoho.com/)

APIs

URL Format

Assuming your domain URL is reports.finepick.com.

<form method="POST" action="https://reports.finepick.com/sso" target="_self">
<input type= "hidden" name ="apikey" value="[your apikey]">
<input type ="hidden" name ="operation" value ="signup"> 
<input type ="hidden" name ="email" value ="[email id of the user to signup]"> 
<input type ="hidden" name ="full_name" value ="[Full Name of the user]"> 
<input type ="submit" name ="Sign Up" value ="submit"> 
</form>

Important: You need to send an HTTPS POST request to Zoho Reports for user Sign Up API.

Input Parameters for Sign Up API

Parameter	Description
operation	Value is "signup"
email	Email Id of the user to sign up
full_name [optional]	Full Name of the user
apikey	Your API key

Response for Sign Up API:

Both Success & Failure responses are present in JSON format.

Return Value	Description
result	success/failure If API call is success, then success value is present in the result attribute; else failure value.
zuid	ID generated by the Zoho system. Unique per user email address. This needs to be stored against the user for whom sign up API is called. This will be useful for any communication / trouble shooting at a later stage.
ticket	this is used by the user to access the reports present in the Zoho Reports. This needs to be passed to Zoho as part of the URL.
cause	This attribute is present in the response, only in case of failure.

Sample Success Response

{
 "ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259",
    "result":"success",
    "zuid":5471
}

Sample Failure Response

{
   "result":"failure",
   "cause":"Invalid APIKey"
}

Assuming your domain URL is reports.finepick.com.

URL Format

<form method="POST" action="https://reports.finepick.com/sso" target="_self">
<input type= "hidden" name ="apikey" value="[your apikey]">
<input type ="hidden" name ="operation" value ="signin"> 
<input type ="hidden" name ="email" value ="[email id of the user to signin]"> 
<input type ="submit" name ="Sign In" value ="submit"> 
</form>

Important: You need to send an HTTPS POST to Zoho Reports for user Sign In API.

Input Parameter for Sign In API

Parameter	Description
operation	Value is "signin"
apikey	Your API key
email	Email address of the user to sign in

Response for Sign in API:
Both success & failure responses are present in JSON format.

Return Value	Description
result	success/failure If the API call is successful, then success value is present in the result attribute; else failure value.
zuid	ID generated by the Zoho system. Unique per user email address. This needs to be stored against the user for whom sign in API is being called. This will be useful for any communication / trouble shooting at a later stage.
ticket	This is used by the user to access the reports present in the Zoho Reports. This needs to be passed to Zoho as part of the URL.
cause	This attribute present in the response, only in case of failure

Sample Success Response

{
   "ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259",
   "result":"success",
   "zuid":5471 
}

Sample Failure Response

{
   "result":"failure",
   "cause":"Invalid APIKey" 
}

Sign Out API

URL Format:

https://reports.finepick.com/ZDBCustomDomainLogin.ma?ZDBACTION=signout

Important: You need to do a HTTP 301 Redirection to the above URL once the sign out process(clearing your application credential) completed in your server/application. Above URL will sign out from Zoho Reports and will redirect to your login page.

Workflow Test Scenarios

This section outlines steps that are to be tried after the unit tests have been successfully completed.

Pre-Requisites:

Make sure that the domain name is mapped to the corresponding Zoho Reports environment (customer-reports.zoho.com). For this particular documentation, we will assume that this domain mapping is https://reports.finepick.com Replace this with your own mapping URL.
Zoho Reports environment is located at customer-reports.zoho.com

Test Login Flow

Invoke the Sign Up or Sign In API above and get a ticket.
Invoke the white label URL with the ticket as the only argument. Example: https://reports.finepick.com?ticket=[obtained ticket]
The user identified by the ticket can operate till the ticket is logged off or all cookies are cleared (in which case step 2 should be followed again).

Test Logout Flow

After logging in using the steps above, invoke the Sign out API from your server/application to Zoho Reports server.
Try using the same ticket to visit your white label domain - you should be redirected to the registered login page of your website.

Test Login as Another user functionality
This step requires that you register 2 different email addressed using the Sign up API.

Test the login flow as the first User
Then use the ticket for User 2 and visit the site (using the same steps outlined in Test Login flow). - Domain will ignore the second ticket when one session is already active - so you will still see the session as user 1.

Integration Test Scenarios

Website driven Login flow

User logs in to the main website.
User clicks on a link that leads to the white-label site.
White-label site requires login credentials of the user - which are not found in the current session
So Zoho Reports routes the request to the registered login URL with a parameter called serviceurl that will contain the full URL where the request should be routed after login (e.g., https://finepick.com/login?serviceurl=https://reports.finepick.com)
Since user is already logged in, finepick.com performs the sign in or sign up API call, depending on whether finepick.com already has the zuid for the user or not.
With the newly generated ticket, finepick.com routes the user's browser to the service URL (in this example, https://reports.finepick.com)/ along with the single parameter called "ticket" (the routed url is https://reports.finepick.com?ticket=[generated ticket])
Now white label site recognizes the user.

White label driven Login flow

User visits the white label domain directly.
If no login credentials for the user is found, then Zoho Reports will route the user the registered login url with a parameter called serviceurl. Serviceurl contains the full URL where the request should be routed to after login (for eg. https://finepick.com/login?serviceurl=https://reports.finepick.com)
The login page of finepick.com, collects and processes the user's login credentials based on the data stored in finepick.com
After succesfully logging the user into finepick.com, if the service URL is a white label URL, the server should invoke the Sign in or Sign up API for the current logged in user, and obtain a zoho ticket
After successfully obtaining the zoho ticket, the user's browser should be forwarded to the url denoted by service url (in this example, https://reports.finepick.com)/ along with the single parameter called "ticket" (the routed url is https://reports.finepick.com?ticket=[generated ticket])
Now the white label site (Zoho Reports) recognizes the user.

Website Logout Flow:

When the user clicks on the logout URL in the website, the website should call the Zoho Reports signout API and invalidate the ticket.
The signout API call is a must!

White -label Logout Flow:

When the user logs out from the reports site, he will be routed to the logout URL of the main site with the serviceurl parameter pointing to the community URL
Zoho will automatically clear all cookies and session information about the user from Zoho's end.

Other Terms & Conditions:

Before going live, it is mandatory for you to include Zoho's Terms and Conditions indicating that the community is hosted on Zoho and indicate Zoho's Terms & Conditions URL. The exact wordings will be given by your account manager.
A full demo of the integration needs to be provided to the Zoho team.

↧

Zoho-Reports-API :: Version13.1

February 7, 2015, 6:16 pm

≫ Next: SSO Integration :: Version2.4

≪ Previous: SSO-Integration :: Version1.7

Zoho Reports API

Zoho Reports offers a powerful REST style API (Application Programming Interface) that can be used by Independent Software Vendors, Developers and System Integrators to build powerful reporting and analytical capabilities into their applications. Its a HTTP based Web API, that responds to requests in XML or JSON format making it programming-language-neutral, thus enabling application development/integration in any programming language (Java, Python, .Net, C, C++, PHP, etc) you know.

With Zoho Reports API developers can easily push or pull data into or from Zoho Reports (data integration) for powerful reporting and analysis. You can add powerful business intelligence capabilities to your product/application, build add-ons to analyze data from third-party business applications (eg., Google Adwords, Google Analytics, CRM systems etc., ) that you use and do much more. Infact Zoho Reports API is used by many Zoho Applications (Zoho CRM, Zoho Creator, Zoho Sheet, Zoho Projects....) for seamlessly providing Reporting and Analytical features based on Zoho Reports to their users.

Zoho Reports API allows you to:

Add data into a table in Zoho Reports database
Modify data in the Zoho Reports database
Bulk Add/Update data into a table via CSV file.
Bulk Update with criteria support.
Bulk Delete with criteria support.
Export data and Reports in various formats such as CSV, JSON, PDF,HTML,IMAGE
Fetch data from the database using SQL Select query.

This API documentation is organized with the following sections:

Prerequisites

This section lists the prerequisites that need to be satisfied before you use API.

API Specification

Provides the complete API language specification including the request and the response formats of various supported operations

Supported Actions/Operations

Provides the complete list of actions that are supported by Zoho Reports API

Client Libraries

Client libraries are programming language wrappers over the raw Zoho Reports HTTP Web APIs. This enables developers to easily use Zoho Reports API in the corresponding programming language. Currently we support the following language libraries:

Zoho CloudSQL Support

Zoho CloudSQL is a middleware technology that allows customers to interact with their business data stored in Zoho through familiar SQL language. Users can access the data in the Zoho cloud using SQL on both other cloud applications as well as through traditional on-premises software.

Zoho Reports is the first service to support CloudSQL as an API extension. Refer to the following links for more details:

Pricing

Pricing model for using Zoho Reports API will be announced in the near future. For any clarification or information in this regard, please mail us to support@zohoreports.com

↧

SSO Integration :: Version2.4

February 14, 2015, 7:25 pm

≫ Next: DeleteData-java :: Version2.9

≪ Previous: Zoho-Reports-API :: Version13.1

SSO API is only available for White Label customers of Zoho Reports. If you want to know about SSO Integration, email support@zohoreports.com

Single Sign On Integration

Setup Phase

Provide the following information to the Zoho Reports team:
- IP addresses of your test and production setups
- The login and logout page URLs of your website (these will process login and logout requests coming from Zoho Reports; needed for your test and production setups too)
- Domain/sub-domain names (CNAME mapping) for test and production setups. CNAME map your test/production sub-domains to customer-reports.zoho.com
- Fill the following Zoho Creator form to design your custom page - https://creator.zoho.com/zohodbhelp/domain-rebranding/#Form:DomainProperties
After submitting the above information to the Zoho Reports team, we will send you an API key to be used you. (this is a different API key than the one provided at http://api.zoho.com/)

APIs

URL Format

Assuming your domain URL is reports.finepick.com.

form method="POST" action="https://reports.finepick.com/sso" target="_self"
input type= "hidden" name ="apikey" value="[your apikey]"
input type ="hidden" name ="operation" value ="signup" 
input type ="hidden" name ="email" value ="[email id of the user to signup]" 
input type ="hidden" name ="full_name" value ="[Full Name of the user]" 
input type ="submit" name ="Sign Up" value ="submit" 
/form

Important: You need to send an HTTPS POST request to Zoho Reports for user Sign Up API.

Input Parameters for Sign Up API

Parameter	Description
operation	Value is "signup"
email	Email Id of the user to sign up
full_name [optional]	Full Name of the user
apikey	Your API key

Response for Sign Up API:

Both Success & Failure responses are present in JSON format.

Return Value	Description
result	success/failure If API call is success, then success value is present in the result attribute; else failure value.
zuid	ID generated by the Zoho system. Unique per user email address. This needs to be stored against the user for whom sign up API is called. This will be useful for any communication / trouble shooting at a later stage.
ticket	this is used by the user to access the reports present in the Zoho Reports. This needs to be passed to Zoho as part of the URL.
cause	This attribute is present in the response, only in case of failure.

Sample Success Response

{
 "ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259",
    "result":"success",
    "zuid":5471
}

Sample Failure Response

{
   "result":"failure",
   "cause":"Invalid APIKey"
}

Assuming your domain URL is reports.finepick.com.

URL Format

form method="POST" action="https://reports.finepick.com/sso" target="_self"
input type= "hidden" name ="apikey" value="[your apikey]"
input type ="hidden" name ="operation" value ="signin" 
input type ="hidden" name ="email" value ="[email id of the user to signin]" 
input type ="submit" name ="Sign In" value ="submit" 
/form

Important: You need to send an HTTPS POST to Zoho Reports for user Sign In API.

Input Parameter for Sign In API

Parameter	Description
operation	Value is "signin"
apikey	Your API key
email	Email address of the user to sign in

Response for Sign in API:
Both success & failure responses are present in JSON format.

Return Value	Description
result	success/failure If the API call is successful, then success value is present in the result attribute; else failure value.
zuid	ID generated by the Zoho system. Unique per user email address. This needs to be stored against the user for whom sign in API is being called. This will be useful for any communication / trouble shooting at a later stage.
ticket	This is used by the user to access the reports present in the Zoho Reports. This needs to be passed to Zoho as part of the URL.
cause	This attribute present in the response, only in case of failure

Sample Success Response

{
   "ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259",
   "result":"success",
   "zuid":5471 
}

Sample Failure Response

{
   "result":"failure",
   "cause":"Invalid APIKey" 
}

Sign Out API

URL Format:

https://reports.finepick.com/ZDBCustomDomainLogin.ma?ZDBACTION=signout

Workflow Test Scenarios

This section outlines steps that are to be tried after the unit tests have been successfully completed.

Pre-Requisites:

Make sure that the domain name is mapped to the corresponding Zoho Reports environment (customer-reports.zoho.com). For this particular documentation, we will assume that this domain mapping is https://reports.finepick.com Replace this with your own mapping URL.
Zoho Reports environment is located at customer-reports.zoho.com

Test Login Flow

Invoke the Sign Up or Sign In API above and get a ticket.
Construct the URL as below and invoke the same,
https://reports.finepick.com/oauthorize?zacode=[obtained_ticket]&state=https://reports.finepick.com/ZDBHome.cc
The user identified by the ticket can operate till the ticket is logged off or all cookies are cleared (in which case step 2 should be followed again).

Test Logout Flow

After logging in using the steps above, invoke the Sign out API from your server/application to Zoho Reports server.
Try using the same ticket to visit your white label domain - you should be redirected to the registered login page of your website.

Test Login as Another user functionality
This step requires that you register 2 different email addressed using the Sign up API.

Test the login flow as the first User
Then use the ticket for User 2 and visit the site (using the same steps outlined in Test Login flow). - Domain will ignore the second ticket when one session is already active - so you will still see the session as user 1.

Integration Test Scenarios

Website driven Login flow

User logs in to the main website.
User clicks on a link that leads to the white-label site.
White-label site requires login credentials of the user - which are not found in the current session
So Zoho Reports routes the request to the registered login URL with a parameter called serviceurl that will contain the full URL where the request should be routed after login (e.g., https://finepick.com/login?serviceurl=https://reports.finepick.com)
Since user is already logged in, finepick.com performs the sign in or sign up API call, depending on whether finepick.com already has the zuid for the user or not.
With the newly generated ticket, finepick.com routes the user's browser to the service URL (in this example, https://reports.finepick.com/oauthorize?zacode=[obtained_ticket]&state=https://reports.finepick.com/ZDBHome.cc)
Now white label site recognizes the user.

White label driven Login flow

User visits the white label domain directly.
If no login credentials for the user is found, then Zoho Reports will route the user the registered login url with a parameter called serviceurl. Serviceurl contains the full URL where the request should be routed to after login (for eg. https://finepick.com/login?serviceurl=https://reports.finepick.com)
The login page of finepick.com, collects and processes the user's login credentials based on the data stored in finepick.com
After succesfully logging the user into finepick.com, if the service URL is a white label URL, the server should invoke the Sign in or Sign up API for the current logged in user, and obtain a zoho ticket
After successfully obtaining the zoho ticket, the user's browser should be forwarded to the url denoted by service url (in this example,https://reports.finepick.com/oauthorize?zacode=[obtained_ticket]&state=https://reports.finepick.com/ZDBHome.cc)
Now the white label site (Zoho Reports) recognizes the user.

Website Logout Flow:

When the user clicks on the logout URL in the website, the website should call the Zoho Reports signout API and invalidate the ticket.
The signout API call is a must!

White -label Logout Flow:

When the user logs out from the reports site, he will be routed to the logout URL of the main site with the serviceurl parameter pointing to the community URL
Zoho will automatically clear all cookies and session information about the user from Zoho's end.

Other Terms & Conditions:

Before going live, it is mandatory for you to include Zoho's Terms and Conditions indicating that the community is hosted on Zoho and indicate Zoho's Terms & Conditions URL. The exact wordings will be given by your account manager.
A full demo of the integration needs to be provided to the Zoho team.

↧

DeleteData-java :: Version2.9

June 21, 2015, 10:41 pm

≫ Next: ExportDataUsingSQL-java :: Version3.5

≪ Previous: SSO Integration :: Version2.4

DeleteData.java

The following sample code is for deleting data from a table. In this example data matching the criteria.

("Region" = 'West') and ("Product Category" = 'Stationary')

are deleted from the "Sales" table.

Before trying it out

Take a copy of the Store Sales database.
Change the configurations in Config.java

public class DeleteData
{
    private ReportClient rc = Config.getReportClient();

    public void deleteData() throws Exception
    {
        String uri = rc.getURI(Config.LOGINEMAILID,Config.DATABASENAME,"Sales");
        rc.deleteData(uri,getCriteria(),null);
        System.out.println("Data matching the criteria" + getCriteria() + "successfully deleted");
    }


    private static String getCriteria()
    {
        return "("Region" = 'West') and ("Product Category" = 'Stationary')";
    }

    public static void main(String[] args) throws Exception
    {
        DeleteData del = new DeleteData();

        del.deleteData();
    }
}

↧

ExportDataUsingSQL-java :: Version3.5

June 21, 2015, 10:41 pm

≫ Next: MetaData-java :: Version3.4

≪ Previous: DeleteData-java :: Version2.9

ExportDataUsingSQL.java

The following sample code exports/fetches data from Zoho Reports using a SQL SELECT query. This is done using Zoho Reports CloudSQL, which enables you to use SQL select query to fetch data from any of your Zoho Reports database.

In this example we are fetching the rows from the "Sales" table matching the " Region" as 'East" using a SELECT query.

Before trying it out

Take a copy of the Store Sales database.
Change the configurations in Config.java

import java.io.*; 
import com.adventnet.zoho.client.report.*;

public class ExportDataUsingSQL
{
    private ReportClient rc = Config.getReportClient();

    public void exportData() throws Exception
    {
        String uri = rc.getURI(Config.LOGINEMAILID,Config.DATABASENAME);
        String sql = "select "Customer Name",Sales,Cost,Profit from Sales where Region = 'East'";
        File expFile = new File("ExportedDataUsingSQL.csv");
        System.out.println("Exporting data using sql." + sql);
        rc.exportDataUsingSQL(uri,"CSV",expFile,sql,null);
        System.out.println("Data successfully exported to  " + expFile.getAbsolutePath());
    }


    public static void main(String[] args) throws Exception
    {
        ExportDataUsingSQL exp = new ExportDataUsingSQL();

        //call EXPORT API with the same logged in session
        exp.exportData();

    }
}

↧

MetaData-java :: Version3.4

June 21, 2015, 10:41 pm

≫ Next: SQL-Query-Entity-Mapping :: Version2.7

≪ Previous: ExportDataUsingSQL-java :: Version3.5

Zoho Reports Metadata

Currently you can obtain the Zoho Report's metadata using the JDBC Driver. Follow the below links to get started.

Sample:

The following code snippet shows the list of databases created by the demouser in Zoho Reports.

import java.util.*;
import java.sql.*;
import java.net.URLEncoder;
import java.io.*;
public class Zoho_GetCatalogs
{
private static final String APIKEY= "bfc2f00820f07f1be4fe97594c590b42";//<your key>
private static final String USEREMAILID= "abc@zoho.com";//<your login email address>
private static final String PASSWORD = "demouser";//<your password
private static final String DB_NAME= "DEMODB";//<your db name>
private static final String TABLE_NAME="demotable";//<your table name>
public static void main(String args[]) throws Exception
{
Connection conn = null;
Statement stmt = null;
ResultSet catalogs = null;
try
{
Class.forName("com.zoho.cloudsql.jdbc.ZohoReportsDriver");
Properties conProps = new Properties();
conProps.put("ZOHO_API_KEY",APIKEY);
conProps.put("user",USEREMAILID);
conProps.put("password",PASSWORD);
conn = DriverManager.getConnection("https://reports.zoho.com/api"
+ "/" + URLEncoder.encode(USER,"UTF-8")
+ "/" + URLEncoder.encode(DB_NAME,"UTF-8"),
conProps);
DatabaseMetaData dmd = conn.getMetaData();
catalogs = dmd.getCatalogs();
if(catalogs != null)
{
while(catalogs.next())
{
System.out.println(catalogs.getObject("TABLE_CAT"));
}
}
}
catch(Exception e)
{
e.printStackTrace();
}
finally
{
if (catalogs != null){try { catalogs.close(); } catch (Exception e){ e.printStackTrace();}}
if (stmt != null){try { stmt.close(); } catch (Exception e){ e.printStackTrace();}}
if (conn != null){try { conn.close(); } catch (Exception e){ e.printStackTrace();}}
}
}
}

Loading into third party tools:

This document describes the way to get connected with your Zoho Reports database via thrid party tools that support JDBC drivers. To know more about JDBC drivers, kindly visit this page:http://java.sun.com/j2se/1.4.2/docs/guide/jdbc/index.html

The following would be required to setup the connection (write to us at support@zohoreports.com, if you need any assistance)

Load the drivers: Generally the connection wizard will have an option to load the drivers. For Zoho Reports, you have to select the files (ZohoReportsAPIClient.jar, ZohoReports_CloudSql_1_0.jar, csv.jar, commons-codec-1.3.jar, commons-httpclient-3.0.1.jar, commons-logging-api.jar)
JDBC Driver: Specify com.zoho.cloudsql.jdbc.ZohoReportsDriver
Database URL: https://reports.zoho.com/api/<username>/<db_to_connect> (ex: https://reports.zoho.com/api/demouser/SalesDB)
UserID: your Zoho Reports' username
Password: your Zoho Reports' password
ZOHO_API_KEY: <YOUR_ZOHO_API_KEY>.
You may have to specify the proxy information (PROXYSERVER, PROXYPORT, PORTUSERNAME, PROXYPASSWORD) if you are connecting through proxy server.

↧

SQL-Query-Entity-Mapping :: Version2.7

June 21, 2015, 10:41 pm

≫ Next: MySQL-SQL-Syntax :: Version3.4

≪ Previous: MetaData-java :: Version3.4

SQL Query Entity Mapping

To construct and execute an SQL Query you need to first identify the entities on which the SQL Query will operate upon. The basic entities that are essential for constructing an SQL query includes Database, Tables and Columns.

The following section describes the mapping in Zoho Reports that maps to these basic entities required for SQL querying. You need to use this mapping to construct your SQL queries for execution.

In Zoho Reports the mapping of the entities would be the following:

SQL Query Entity	Zoho Reports mapping
Database	Mapped to each Reporting Database in Zoho Reports
Table	Mapped to Tables and Query Tables in a database in Zoho Reports
Column	Mapped to Columns of a Table or Query Table in a database in Zoho Reports

Sample:

Following is an example of a CloudSQL query executed on Zoho Reports:

Entities involved in Zoho Reports:

Database Name in Zoho Reports: "Super Store Sales"
Table Name: Sales
Columns Involved: Customer Name, Sales, Cost and Region

SQL SELECT Query:

select "Customer Name",Sales,Cost,"Profit (Sales)" from Sales where Region = 'East'

The above query will fetch the records from the Sales table in Super Store Sales database in Zoho Reports, which are from the Region 'East'.

Next: Zoho Reports CloudSQL - API Specification

↧

MySQL-SQL-Syntax :: Version3.4

June 21, 2015, 10:41 pm

≫ Next: Home-page---Dashboard-of-Charts :: Version6.5

≪ Previous: SQL-Query-Entity-Mapping :: Version2.7

MySQL - Supported SQL syntax and Functions in Zoho Reports

Zoho Reports supports MySQL SELECT query syntax and in-built functions in CloudSQL. Following are the MySQL syntax which are supported in Zoho Reports.

Supported MySQL SELECT Query Syntax:

Following are the conventions used in the SELECT syntax definition:

CONVENTIONS	MEANING	EXAMPLE
Square Brackets [ ]	Indicates that the enclosed arguments are optional in the syntax	DIGITS [. PRECISION ]
Braces followed by plus sign ( )+	Indicates that the enclosed arguments can occur more than once	( DIGIT )+
Braces followed by star sign ( )*	Indicates that the enclosed arguments can occur zero or more times	SELECT column_name ( , column_name)* FROM table_name
Question Mark ?	Indicates that the Question mark "?" preceded by an argument is optional. Equivalent to Square Brackets[ ]	<INTEGER> ( "." <INTEGER> )?
Vectical Line \|	Vertical Line indicates choices	(DISTINCT \| ALL \| UNIQUE )
UPPER CASE	Uppercase text indicates case-insensitive filenames or directory names, commands, command keywords, initializing parameters, data types.	SELECT column_name FROM table_name
lower case	Lowercase text indicates database objects like table name, column names etc.	DELETE FROM table_name WHERE condition

SELECT Syntax:

SELECT [ DISTINCT | ALL ] ( ( column_clause ( "," column_clause )* ) | "*" ) [ FROM table_expression_clause ]
[ where_clause ] [ group_by_clause ] [ having_clause ] [ order_by_clause ] [ limit_clause ]

column_clause	( expression \| table_name.* \| table_name.columnname \| table_name.column_name \| column_name ) [ [ AS ] alias_name ]
table_expression_clause	( table_name ) [ AS alias_name ] ( "," ( table_name ) [ AS alias_name ])* [join_clause ]
where_clause	WHERE (<Left Where Expression>(= \| < \| > \| <= \| >= \| != \| LIKE \| NOT LIKE \| BETWEEN) <Right Where Expression>) ( (OPERATOR ) (<Left Where Expression> (= \| < \| > \| <= \| >= \| != \| LIKE \| NOT LIKE \| BETWEEN) <Right Where Expression>)* OPERATOR includes AND/OR
group_by_clause	GROUP BY expression ( "," expression )*
having_clause	HAVING condition
order_by_clause	ORDER BY (order_item_clause) ( "," order_item_clause )*
limit_clause	LIMIT (value \| ALL) [ "," value ]
join_clause	table_name INNER JOIN table_name ON join_condition \| table_name {LEFT \| RIGHT} [OUTER] JOIN table_name ON join_condition
order_item_clause	(expression \| column name) [ ASC \| DESC ]

UNION Syntax:

<SELECT Query Statement> (UNION [ALL | DISTINCT] <SELECT Query Statement>)+

Reference: MySQL SELECT Query syntax documentation

Next: Supported built-in Functions in MySQL

↧

Home-page---Dashboard-of-Charts :: Version6.5

June 21, 2015, 10:41 pm

≫ Next: AddRow-java :: Version5

≪ Previous: MySQL-SQL-Syntax :: Version3.4

Home Page Implementation

The home page (refer image above) of the "Personal Finance" application has the following tabs along with the "Home" tab,

Reports
Expense Details
Income Details

Add New Income and Expense Forms:

There are two buttons viz., "Add New Income" and "Add New Expense" in the right hand side top corner of the page. They are used to add New Income and Expense details into the application.

On clicking the "Add New Income" link a dialog as given below would be shown to submit the income details. The dialog is implemented in Python

On submitting the details, the data gets stored into the IncomeDetails class object in Google Data store. Also the data gets added into Zoho Reports in the table IncomeDetails in the database Personal Finance using the Add Row API wrapped inside the Google AppEngine Client Library. The code snippet for this action is given below. (click here to download the full code)

    # construction of Zoho Reports connection URL
    rc = self.getReportClient(self.rc)
    uri = rc.getURI(Config.LOGINNAME,Config.DATABASENAME, Config.INCOMETABLENAME)
    entityInst = IncomeDetails()
  
    # container to store the column values for the new row
    columnValues = {}
    for col in IncomeDetails._selCols:
       columnValues[col]= self.request.get(col).strip()
       setattr(entityInst,col, \
		ExpenseDetails.strToPropTypeConvFunc(col, columnValues[col]))

   # write the new row to google data store
   entityInst.put()
   # write the new row to Zoho DB
   rc.addRow(uri,columnValues)

On clicking the "Add New Expense" link a dialog as given below would be shown to submit the expense details.

On submitting the details, the data gets stored into the ExpenseDetails class object in Google Data store. Also the data gets added into Zoho Reports in the table ExpenseDetails using the Add Row API wrapped inside the Google AppEngine Client Library. (click here to download the full code)

Dashboard in the Home Screen:

The home page dashboard embeds 4 charts generated in Zoho Reports:

Income trend for the last 12 months
Expense trend for the last 12 months
Income split up for the last 3 months (Interactive chart)
Expense Split up for the last 3 months (Interactive Chart)

These charts are generated as Chart Views(?) using the data in IncomeDetails and ExpenseDetails tables in Zoho Reports. The charts created are embedded into this home page using the Embed option (invoke "Publish-> Embed in Website/Blogs" menu item) in Zoho Reports.

Income and Expense Trend charts are similar in the manner they are built:

"Date" of transaction (ie., date of money earned or spent) on the X-Axis
Actual "Amount" involved in Y-Axis.
Data is plotted for the last 12 months. This is achieved by applying the "Last 12 months" filter.
The chart type is Line chart.

The other 2 charts are about the Income and Expense split up for the last 3 months:

"Category" of Income/Expense in the X-Axis
"Amount" earned/spent on Y-Axis with filter of "Last 3 months" applied.

Also refer to the Zoho Reports - Personal Finance database used to generate the above reports.

Next: Reports tab - Creating & Embedding reports from Zoho Reports

↧

AddRow-java :: Version5

July 6, 2015, 11:48 pm

≫ Next: Share :: Version6.9

≪ Previous: Home-page---Dashboard-of-Charts :: Version6.5

AddRow.java

The following is the sample code for adding a row to a table in a database in Zoho Reports. In this example a row is added to the table "Sales".

Before trying it out

Take a copy of the Store Sales database.
Change the configurations in Config.java

public class AddRow
{
private ReportClient rc = Config.getReportClient();

public void addRow() throws Exception
{
String uri = rc.getURI(Config.LOGINEMAILID,Config.DATABASENAME,"Sales");
Map result = rc.addRow(uri,getRowValues(),null);
System.out.println("Successfully added the row to " + uri);
System.out.println(" The response is " + result);
}

private static HashMap getRowValues()
{
SimpleDateFormat dtFmt = new SimpleDateFormat("yyyy/MM/dd HH:mm:ss");
HashMap rowValsMap = new HashMap();
rowValsMap.put("Date",dtFmt.format(new Date()));
rowValsMap.put("Region","EAST");
rowValsMap.put("Product Category","Sample_Grocery");
rowValsMap.put("Product","Sample_Meat");
rowValsMap.put("Customer Name","John");
rowValsMap.put("Sales","2303");
rowValsMap.put("Cost","1000");
return rowValsMap;
}

public static void main(String[] args) throws Exception
{
AddRow row = new AddRow(); //call ADDROW API with the same logged in session row.addRow(); row.addRow(); } }

↧

Share :: Version6.9

July 10, 2015, 12:11 am

≫ Next: Zoho---Reports---API---Home :: Version9.9

≪ Previous: AddRow-java :: Version5

Sharing

1. It is mandatory to use HTTPS in all API requests instead of HTTP request. HTTP is not supported

2. Always use https://reportsapi.zoho.com as the API request URL.

With the Zoho Reports Share API, you can share the views (tables/reports/dashboards) created in Zoho Reports with users. The Share API also allows you to the revoke sharing permission granted. It is recommended that you go through the documentation on How sharing works in Zoho Reports, before using the API for better understanding.

Note: Sharing permissions can be updated by calling 'Share' again (over riding the existing share permissions).

Share - Sample URL

https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB?ZOHO_ACTION=SHARE
&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML
&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0

Note

It is recommended to use Zoho Reports Login Email Address in the API URL instead of Zoho Username.

Data sent as POST parameters (URL Encoded)

Parameter

Possible Values

Description

Remarks

ZOHO_VIEWS

Table1,View1,View2,My View

List of views which are to be shared. Multiple views can be shared by providing them separated by comma

Note: ZOHO_VIEWS is encoded in URL encoding format. Value without encoding is given below:

ZOHO_VIEWS=Table1,View1,View2,My View

Mandatory parameter

ZOHO_EMAILS

user1@finepick.com, user2@finepick.com

User email addresses as comma separated values to whom the views need to be shared.

Note: ZOHO_EMAILS is encoded in URL encoding format. Value without encoding is given below:

ZOHO_EMAILS=user1@finepick.com,user2@finepick.com

Mandatory parameter

POST parameters for fine-grained permissions (At least one parameter is required from the below)

Parameter	Allowed Values	Default value	Description
ZOHO_READ	true or false	false	Read Access to the view
ZOHO_EXPORT	true or false	false	Export permission for a view
ZOHO_VUD	true or false	false	Permission to view underlying data in a Chart / Pivot / Summary view
ZOHO_DRILLDOWN	true or false	false	Permission to drill down in a Chart
ZOHO_ADDROW	true or false	false	Permission to add a row in the table
ZOHO_UPDATEROW	true or false	false	Permission to update a row in the table
ZOHO_DELETEROW	true or false	false	Permission to delete a row in the table
ZOHO_DELETEALLROWS	true or false	false	Permission to delete all rows in the table
ZOHO_IMPORT_APPEND	true or false	false	Permission to import data into the table using APPEND option
ZOHO_IMPORT_ADDORUPDATE	true or false	false	Permission to import data into the table using ADD or UPDATE option i.e new rows will be appended and existing rows will be updated based on the matching columns provided in IMPORT action
ZOHO_IMPORT_DELETEALLADD	true or false	false	Permission to import data into the table using the option: deleting all the existing records and adding the new records
ZOHO_SHARE	true or false	false	Permission to share the table / view to others

Other Parameters

Parameter	Allowed Values	Default Value	Description	Remarks
ZOHO_CRITERIA	Filter Criteria should be specified in the format as given in the example below. It is similar to a WHERE clause in SQL languages. Read More		ZOHO_CRITERIA: This parameter allows you to apply a filter criteria while sharing a view to users. The specified criteria will be applied on the reports shared, there by filtering the data viewed, when the report is accessed by the shared user. Refer the below link to use ZOHO_CRITERIA: https://zohoreportsapi.wiki.zoho.com/Applying-Filters.html
ZOHO_INHERIT_PARENT_CRITERIA	true or false	false	This is valid only for reports(not tables). If true, then its parent tables' criteria is also taken into account while sharing
ZOHO_INVITE_MAIL	true or false	false	Whether to send an invitation mail on sharing	For White Label Customers: If this parameter is set to 'true', use your white label domain URL instead of reportsapi.zoho.com in the Share API request.
ZOHO_MAIL_SUBJECT			Required only if ZOHO_INVITE_MAIL is true
ZOHO_MAIL_MESSAGE
ZOHO_INVITE_MAIL_CCME	true or false	false	Whether to CC the invitation mail to you on sharing	This parameter is valid only if ZOHO_INVITE_MAIL is true

Share - Sample Success Response

XML

<?xml version="1.0" encoding="UTF-8" ?>
<response uri="/api/abc@zoho.com/EmployeeDB" action="SHARE">
<result>success</result>
</response>

JSON

{
  "response";
   {
 "uri": "/api/abc@zoho.com/EmployeeDB",
      "action": "SHARE",
      "result": "success"
   }
}

Remove Share

Sample URL

https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB?ZOHO_ACTION=REMOVESHARE
&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML
&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0

Data Sent as POST parameters (URL Encoded):

Parameter	Allowed Values	Default Value	Description	Remarks
ZOHO_VIEWS	Table1,View1,View2,My View		Views whose sharing need to be removed. Multiple views can be passed using comma separator. Note: ZOHO_VIEWS is encoded in URL encoding format. Value without encoding is given below: ZOHO_VIEWS=Table1,View1,View2,My View	Any one of these two parameter is a mandatory Parameter
ZOHO_ALLVIEWS	true or false	false	If true passed to this parameter it will remove the sharing for all the views which are shared to the corresponding users (users identified by the email addresses passed in the parameter ZOHO_EMAILS)	Any one of these two parameter is a mandatory Parameter
ZOHO_EMAILS	user1@finepick.com, user2@finepick.com		User email addresses as comma separated values to whom the sharing need to be removed for the specified views Note: ZOHO_EMAILS is encoded in URL encoding format. Value without encoding is given below: ZOHO_EMAILS=user1@finepick.com,user2@finepick.com	Mandatory Parameter

Remove Share - Sample Success Response

XML

<?xml version="1.0" encoding="UTF-8" ?>
<response uri="/api/abc@zoho.com/EmployeeDB" action="REMOVESHARE">
<result>success</result>
</response>

JSON

{
  "response";
   {
 "uri": "/api/abc@zoho.com/EmployeeDB",
      "action": "REMOVESHARE",
      "result": "success"
   }
}

With the Zoho Reports Database Owner API, you can add / remove the multiple database owners for a database. It is recommended that you go through the documentation on How multiple database owners works in Zoho Reports, before using the API for better understanding.

Add Database Owner - Sample URL

https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB?ZOHO_ACTION=ADDDBOWNER
&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML
&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0

Data sent as POST parameters (URL Encoded)

Parameter	Possible Values	Description	Remarks
ZOHO_EMAILS	user1@finepick.com, user2@finepick.com	User email addresses as comma separated values to whom database ownership need to be provided Note: ZOHO_EMAILS is encoded in URL encoding format. Value without encoding is given below: ZOHO_EMAILS=user1@finepick.com,user2@finepick.com	Mandatory parameter

Other Parameters:

Parameter	Allowed Values	Default Value	Description	Remarks
ZOHO_INVITE_MAIL	true or false	false	Whether to send an invitation mail on sharing	For White Label Customers: If this parameter is set to 'true', use your white label domain URL instead of reportsapi.zoho.com in the Share API request.
ZOHO_MAIL_SUBJECT			Required only if ZOHO_INVITE_MAIL is true
ZOHO_MAIL_MESSAGE

Add Database Owner - Sample Success Response

XML

<?xml version="1.0" encoding="UTF-8" ?>
<response uri="/api/abc@zoho.com/EmployeeDB" action="ADDDBOWNER">
<result>success</result>
</response>

JSON

{
  "response";
   {
 "uri": "/api/abc@zoho.com/EmployeeDB",
      "action": "ADDDBOWNER",
      "result": "success"
   }
}

Remove Database Owner - Sample URL

https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB?ZOHO_ACTION=REMOVEDBOWNER
&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML
&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0

Data sent as POST parameters (URL Encoded)

Parameter	Possible Values	Description	Remarks
ZOHO_EMAILS	user1@finepick.com, user2@finepick.com	User email addresses as comma separated values to whom database ownership need to be removed Note: ZOHO_EMAILS is encoded in URL encoding format. Value without encoding is given below: ZOHO_EMAILS=user1@finepick.com,user2@finepick.com	Mandatory parameter

Other Parameters:

Parameter	Allowed Values	Default Value	Description	Remarks
ZOHO_INVITE_MAIL	true or false	false	Whether to send a mail on sharing removal	For White Label Customers: If this parameter is set to 'true', use your white label domain URL instead of reportsapi.zoho.com in the Share API request.
ZOHO_MAIL_SUBJECT			Required only if ZOHO_INVITE_MAIL is true
ZOHO_MAIL_MESSAGE

Remove Database Owner - Sample Success Response

XML

            <?xml version="1.0" encoding="UTF-8" ?>
<response uri="/api/abc@zoho.com/EmployeeDB" action="REMOVEDBOWNER">
<result>success</result>
</response>

JSON

            {
  "response";
   {

 "uri": "/api/abc@zoho.com/EmployeeDB",
      "action": "REMOVEDBOWNER",
      "result": "success"
   }
}

↧

Zoho---Reports---API---Home :: Version9.9

November 14, 2015, 12:16 am

≫ Next: Adding-Single-Row :: Version4.9

≪ Previous: Share :: Version6.9

Zoho Reports API

Zoho Reports API offers wide range of functions to help developers build & manage powerful reporting and analytical capabilities for their business application needs. You can add powerful business intelligence capabilities to your product/application, build add-ons to analyze data from third-party business applications (eg., Google Adwords, Google Analytics, CRM systems etc., ) that you use and do much more. Infact Zoho Reports API is used by many Zoho Applications (Zoho CRM, Zoho Creator, Zoho Projects...) for seamlessly providing Reporting and Analytical features based on Zoho Reports to their users.

Easy to use programming language wrappers called "Client Libraries" are provided to conveniently use the Zoho Reports API from within your familiar programming language like Java, C#, Python and Google Apps

This API documentation is organized with the following sections:

Prerequisites

The section explains the prerequisites for using the API. Kindly go through all the links before proceeding to next sections.

Zoho Reports User Account

AuthToken

Reporting Database

API Specification

Covers detailed API specification and common terminologies used. It is important to understand the API specification clearly before referring to the actual API methods.

Request Format

Response Format

Error Handling

Common Parameters

Data API

This section lists the APIs which can be used to perform data addition, bulk import, deletion and updates into your Zoho Reports data tables. This also provides APIs to Export your tables, reports & dashboards in PDF, Excel, JSON, HTML, Image and CSV formats.

Add Row

Bulk Import (can be used to create a new table too)

Update Row(s)

Delete Row(s)

Export

Applying Filter Criteria

Modeling & Metadata API

This section lists all the modeling and metadata APIs. Modeling APIs can be used to add, delete & rename columns in a Zoho Reports table. It also offers APIs to copy objects (databases, reports and formulas) from one database to another present in the same account or across different accounts.

Metadata APis can be used to fetch information about the reporting databases,tables, reports and dashboards created in Zoho Reports.

Modeling

Add Column

Delete Column

Rename Column

Copy Database ^new

Delete Database ^new

Copy Reports ^new

Copy Formula ^new

Metadata

Database Metadata

Get View Name ^new

Get Database Name ^new

Get Info ^new

Sharing & Collaboration API

This section provides APIs for sharing & collaboration. You can share views (reports & dashboards) created in Zoho Reports with fine grained permission control to users through APIs. You can also manage sharing as well as remove sharing through APIs.

Share View(s)

Remove Sharing

Add Database Owner

Remove Database Owner

Embed API

With this API you can embed reports & dashboards created in Zoho Reports into your Web pages/applications programmatically. This offers great possibilities to developers for creating dynamic reporting content embedded within their websites & applications seamlessly.

Get View URL ^new

Get Embed URL ^new

User Management API

This section lists the User Management APIs for managing users in the Zoho Reports Administrator account.

Add User

Remove User

Activate User

Deactivate User
Get Share Info

Single Sign-On API (for White Label customers)

This section lists the APIs which can be used only by White Label customers (full rebranding) to easily implement single sign-on in their application for seamless user management .

Sign Up

Sign In

Sign Out

Client Libraries

This section discusses about the Built-In Client Libraries, which are "easy to use" wrappers around the raw HTTP based Zoho Reports API, that could be used in your programming language of choice & convenience

Java

Python

C#

Google App Engine

Zoho CloudSQL

Zoho CloudSQL is a middleware technology that allows customers to interact with their business data stored in Zoho Reports through familiar SQL language. Users can access the data in Zoho Reports using SQL SELECT queries.

Zoho Reports CloudSQL Implementation

Zoho Reports JDBC Driver

More about Zoho CloudSQL

API Usage Limits & Pricing

Zoho Reports API usage will be measured based on units consumed & frequency of API calls.
The API Units and frequency calculations are described in this section. API units allowed are scoped by each of the pricing plans.

API Units
API Frequency Limits
API Units Pricing

Contact Us
For any technical assistance in using Zoho Reports API, feel free to get in touch with our 24X7 Customer Support.
Email Address: support@zohoreports.com
Toll-free Number: 1-(888)-900-9646

↧

Adding-Single-Row :: Version4.9

November 14, 2015, 12:16 am

≫ Next: Importing-Bulk-Data :: Version8.7

≪ Previous: Zoho---Reports---API---Home :: Version9.9

Adding a Single Row

1. It is mandatory to use HTTPS in all API requests instead of HTTP request. HTTP is not supported

2. Always use https://reportsapi.zoho.com as the API request URL.

This API allows you to add a single row into a specified table.

Sample Request

A sample request for adding a row to the "EmployeeDetails" table inside the database "EmployeeDB"

URL
https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB/EmployeeDetails?ZOHO_ACTION=ADDROW
&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0

Data Sent as POST parameters (URL Encoded)
&Name=Gary&Date Of Birth=12-Jun-1980&Country=USA&Salary=10000

Specifying the action

In the query string of the URL, the ZOHO_ACTION parameter should be ADDROW. For other mandatory query string parameters such as ZOHO_OUTPUT_FORMAT, refer this link.

Note: Value of ZOHO_ACTION parameter should be in the same case(UPPER CASE) as given in this document.

Data for the Row

The column values for the row should be passed as POST parameters in <columnname>=<value> format. (The parameters should be in application/x-www-form-urlencoded format).

<columnname> - Refers to the name of the column in the table to which the value is added
<value> - Refers to the corresponding value to be added for this column

Sample Success Response

The following code snippets provides the response in JSON and XML formats for the sample refered above.

JSON Format

{
"response":
{
"url": "/api/abc@zoho.com/EmployeeDB/EmployeeDetails",
"action": "ADDROW",
"result":
{
"column_order":["Name","Date Of Birth","Salary","Country"],
"rows":[
//All the columns in the row , including formula columns
["Gary","12-Jun-1980",10000,"USA"]
}
}
}

XML Format

<?xml version="1.0" encoding="UTF-8" ?>
<response url ="/api/abc@zoho.com/EmployeeDB/EmployeeDetails"action="ADDROW">
<result>
<!-- All the columns in the row , including formula columns -->
<row>
<column name="Name">Gary</column>
<column name="Date Of Birth">12-Jun-1980</column>
<column name="Basic">10000</column>
<column name="Country">USA</column>
</row>
</result>
<response>

↧

Importing-Bulk-Data :: Version8.7

November 14, 2015, 12:16 am

≫ Next: Updating-Data :: Version5

≪ Previous: Adding-Single-Row :: Version4.9

Importing Bulk Data

1. It is mandatory to use HTTPS in all API requests instead of HTTP request. HTTP is not supported

2. Always use https://reportsapi.zoho.com as the API request URL.

With the Zoho Reports API, you can add/update data in bulk. The data to be added/updated should be in CSV or JSON file formats.

Note:

The data should be sent via a https POST request
The parameters and the file should be encoded in multi-part/form-data format.(The format used by html forms that contain file type fields used for uploading files)

Importing Data

To import data you need to send an HTTPS POST request using the following URL format.

https://reportsapi.zoho.com/api/<zoho-login_email_address>/<database_name>/<table_name>?ZOHO_ACTION=IMPORT&authtoken=<your_auth_token>&ZOHO_OUTPUT_FORMAT=<XML/JSON>&ZOHO_ERROR_FORMAT=<XML/JSON>&ZOHO_API_VERSION=1.0

Data Sent as POST parameters.

The additional control parameters and the file should be encoded in multi-part/form-data format (The format used by html forms that contain file type fields used for uploading files).
Samples
The following code snippet illustrates importing data from a CSV file into Zoho Reports with POST parameters along with additional control parameters submitted from the HTML form. <html>

<html>
<body>
<form name="ZohoDBImportForm" ENCTYPE="multipart/form-data"method="post"action="https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB/EmployeeDetails?
ZOHO_ACTION=IMPORT&ZOHO_API_VERSION=1.0&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_OUTPUT_FORMAT=XML">
<input type="file" name="ZOHO_FILE" value="Browse"><br> 
ZOHO IMPORT TYPE : <input type="text"name="ZOHO_IMPORT_TYPE" value="APPEND"><br> 
ZOHO AUTO IDENTIFY : <input type="text" name="ZOHO_AUTO_IDENTIFY" value="true"><br> 
ZOHO CREATE_TABLE : <input type="text" name="ZOHO_CREATE_TABLE" value="false" ><br> 

ON IMPORT ERROR : <input type="text" name="ZOHO_ON_IMPORT_ERROR" value="ABORT"><br> 
<input type="submit" name="submit" value="Upload"> 
</body>
</html>

Note: The CSV should contain the column names in the first row.

The following code snippet illustrates importing data from a JSON file into Zoho Reports with POST parameters along with additional control parameters submitted from the HTML form.

<html>
<body>
<form name="ZohoDBImportForm" ENCTYPE="multipart/form-data"method="post"action="https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB/EmployeeDetails?
ZOHO_ACTION=IMPORT&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_OUTPUT_FORMAT=JSON&ZOHO_API_VERSION=1.0">
<input type="file" name="ZOHO_FILE" value="Browse"><br>
ZOHO IMPORT FILE TYPE : <input type="text" name="ZOHO_IMPORT_FILETYPE" value="JSON"><br>
ZOHO IMPORT TYPE : <input type="text" name= "ZOHO_IMPORT_TYPE" value="APPEND"><br>
ZOHO AUTO IDENTIFY : <input type="text" name="ZOHO_AUTO_IDENTIFY" value="true"><br>
ZOHO CREATE TABLE : <input type="text" name="ZOHO_CREATE_TABLE" value="false" ><br>
ON IMPORT ERROR : <input type="text" name="ZOHO_ON_IMPORT_ERROR" value="ABORT"><br>
<input type="submit" name="submit" value="Upload">
</body>
</html>

Note:

You can import any type of JSON array with single or multiple objects.
In case you import file with multiple JSON objects separated by comma (not enclosed with square brackets), then the first object alone will be imported.
JSON object containing simple values without keys are not supported.
Refer to the supported JSON formats section, for more details on the JSON format that can be imported into Zoho Reports.

Specifying the action

In the query string of the url , the ZOHO_ACTION parameter should be "IMPORT". For other mandatory query string parameters such as ZOHO_OUTPUT_FORMAT, refer this link.

Note: Value of ZOHO_ACTION parameter should be in the same case(UPPER CASE) as given in this document.

Parameters for specifying the Import Options

These parameters are used to specify the various options when importing. Some of these parameters are mandatory and are highlighted and marked with star " * " .

Parameter	Possible Values	Description
ZOHO_FILE*	The file to import
ZOHO_IMPORT_FILETYPE	CSV/JSON	Optional. Default value is CSV. Format of the file to be imported. Supported formats are: CSV JSON
ZOHO_CREATE_TABLE	true/false.	Optional. Default is false. In case it is true, then the table is created if the table referred in the URL doesn't exist in the specified database. In case its false, no table is created even if the table refered in the URL does not exist in the database.
ZOHO_SELECTED_COLUMNS	List of comma separated column names. E.g.,: Name, Department	Optional. Specify the columns to be imported into the Zoho Reports table from the data being uploaded. Note: Incase of JSON files you need to specify the column names capturing the full JSON tree heirrachy eg., employee.Name, employee.Department
ZOHO_IMPORT_TYPE*	APPEND TRUNCATEADD UPDATEADD	APPEND - Appends the data into the table. TRUNCATEADD - Deletes all exisiting rows in the table and adds the imported data as new entry. UPDATEADD - Updates the row if the mentioned column values are matched, else a new entry will be added
ZOHO_MATCHING_COLUMNS**	List of comma separated column names. E.g.,: Name,Department	Should be passed only when the ZOHO_IMPORT_TYPE is UPDATEADD. The values in the columns to be matched will be used for comparision to check whether data row(s) being imported matches with an existing row(s) in the table. The existing rows in the table that match will be updated with values from data imported. The remaining rows are appended to the table as new rows.
ZOHO_IMPORT_JSON_RETCOLNAMES	true/false.	Optional. Default value is false. This parameter is applicable only for importing JSON files. This defines how the columns names are to be constructed from the JSON file. If set to true, then the final key attribute alone will be considered as column name. If set to false, then the column name will be constructed by appending all the parent attributes separated by dot (.). This will result in column names which captures the full JSON tree hierarchy eg., employee.Name, employee.Department
ZOHO_DATE_FORMAT	Format of the date. E.g., dd-MMM-YYYY	Optional The format of date value. Specify this incase any date field is being imported and its format cannot be auto recognized by Zoho Reports.
ZOHO_AUTO_IDENTIFY*	true/false	Used to specify whether to auto identify the CSV format.
ZOHO_SKIPTOP	<number>	Optional Number of rows that are to be skipped from the top in the CSV file being imported.
ZOHO_THOUSAND_SEPARATOR	0/1/2/3	Optional. Default is 0. This parameter controls the action to be taken in case there is a thousand separator in the data. 0 - COMMA 1 - DOT 2 - SPACE 3 - SINGLE QUOTE
ZOHO_DECIMAL_SEPARATOR	0/1	Optional. Default is 0. This parameter controls the action to be taken in case there is a decimal separator in the data. 0 - DOT 1 - COMMA
ZOHO_ON_IMPORT_ERROR*	ABORT SKIPROW SETCOLUMNEMPTY	This parameter controls the action to be taken incase there is an error during import. ABORT - Incase of any error, abort the whole import. SKIPROW - In case of any error, skip that specific row(s) which has the problem and continue importing the rest. SETCOLUMNEMPTY - In case of any error, set the value of the errored column for the row to empty and continue importing.

CSV Format Details

These parameters need to be specified if the ZOHO_AUTO_IDENTIFY is set to false.

Parameter	Possible Values	Description
ZOHO_COMMENTCHAR	<character>	Comment Character. If the character mentioned is found at the beginning of the row, the csv row will be skipped.
ZOHO_DELIMITER	0 / 1 / 2 / 3	Delimiter which separates the values in the file. 0 - if the delimiter is COMMA 1 - if the delimiter is TAB 2 - if the delimiter is SEMICOLON 3 - if the delimiter is SPACE
ZOHO_QUOTED	0 / 1 / 2	The Text Qualifier. 0 - None 1 - SINGLE QUOTE 2 - DOUBLE QUOTE

JSON Format Details

The following parameters need to be specified while importing data from JSON file.

Sample Success Response

JSON

The following is a sample response in JSON format in case of successful import.

{
 " response":
{"uri": "/api/abc@zoho.com/EmployeeDB/EmployeeDetails",
"action": "IMPORT",
"result":
{
"importSummary":
{
"totalColumnCount":3,
"selectedColumnCount":3,
"totalRowCount":50,
"successRowCount":48,
"warnings":0,
"importOperation": "created",
"importType": "APPEND"
},
"columnDetails":
{
"Name": "Plain Text",
"Date Of Birth": "Date",
"Salary": "Number"
},
"importErrors": "[Line: 5 Field: 3] a1213 -WARNING: Invalid Number value"
}
}
}

XML

The following is a sample response in XML format in case of successful import.

<?xml version="1.0" encoding="UTF-8" ?>

<response uri="/api/abc@zoho.com/EmployeeDB/EmployeeDetails" action="IMPORT">
<result>
<importSummary>
<totalColumnCount>3 </totalColumnCount>
<selectedColumnCount>3</selectedColumnCount>
<totalRowCount>50</totalRowCount>
<successRowCount>48</successRowCount>
<warnings>0</warnings>
<importOperation>created</importOperation><importType>APPEND</importType>
</importSummary>
	
<columnDetails>
<column datatype="Plain Text">Name </column>
<column datatype="Date">Date Of Birth</column>
<column datatype="Number">Salary</column>
</columnDetails>
	

<!-- The first 100 errors are alone sent -->
<importErrors>
[Line: 5 Field: 3] a1213 -WARNING: Invalid Number value
</importErrors>
	

</result>
</response>

↧

Updating-Data :: Version5

November 14, 2015, 12:16 am

≫ Next: Deleting-Data :: Version5.4

≪ Previous: Importing-Bulk-Data :: Version8.7

Updating Data

1. It is mandatory to use HTTPS in all API requests instead of HTTP request. HTTP is not supported

2. Always use https://reportsapi.zoho.com as the API request URL.

The data present in a table can be updated using this API.

Sample

A sample request that updates the salary to 10000 and perks to 6000 and deduction to Empty (no value) for all employees of the finance department.

URL
https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB/EmployeeDetails?ZOHO_ACTION=UPDATE&ZOHO_OUTPUT_FORMAT=XML
&ZOHO_ERROR_FORMAT=XML&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0
Data Sent as POST parameters.
Salary=10000&Deduction=&Perks=6000&ZOHO_CRITERIA=("Department"='Finance')

ZOHO_CRITERIA is encoded in URL encoding format. Value without encoding is given below:

ZOHO_CRITERIA=("Department" = 'Finance')

Specifying the action

In the query string of the URL , the ZOHO_ACTION parameter should be "UPDATE". For explanation about other mandatory query string parameters such as ZOHO_OUTPUT_FORMAT, refer this link.

Note: Value of ZOHO_ACTION parameter should be in the same case(UPPER CASE) as given in this document.

Specifying the data to be updated

Pass the columns whose values you would like to update in a <columnname>=<value> format. (The parameters should be in application/x-www-form-urlencoded format).

<columnname> - Refers to the name of the column in the table whose value is to be updated
<value> - Refers to the corresponding value to be updated in the column

For specifying empty (null) values, the parameter should be sent with empty values. In the example above, the Deduction value is taken to be empty.

Criteria

If the ZOHO_CRITERIA parameter is not sent, then all the rows are updated. If criteria is sent the rows matching the criteria alone are updated. For more details about the format for the criteria view this link.

Sample Success Response

The following code snippets provides the response in XML and JSON formats for the sample referred above.

XML

<?xml version="1.0" encoding="UTF-8" ?>
<response uri="/api/abc@zoho.com/EmployeeDB/EmployeeDetails" action="UPDATE">
<criteria>&quot;Department&quot; = &apos;Finance&apos;</criteria>
<result> 		
<updatedColumns>
<column>Salary</column>
<column>Deduction</column>
<column>Perks</column>
</updatedColumns>
<updatedRows>4</updatedRows>
</result>
</response>

JSON

{
"response":
{
"uri": "/api/abc@zoho.com/EmployeeDB/EmployeeDetails",
"action": "UPDATE",
"criteria": "\"Department\" = 'Finance'",
"result":
{
"updatedColumns":["Salary","Deduction","Perks"],
"updatedRows":"4"
}
}
}

↧

Deleting-Data :: Version5.4

November 14, 2015, 12:16 am

≫ Next: Export :: Version7.5

≪ Previous: Updating-Data :: Version5

Deleting Data

1. It is mandatory to use HTTPS in all API requests instead of HTTP request. HTTP is not supported

2. Always use https://reportsapi.zoho.com as the API request URL.

The data present in a table can be deleted using this API.

Sample

A sample request that deletes the records of all the employees in finance department.

URL
https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB/EmployeeDetails?ZOHO_ACTION=DELETE
&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML
&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0   	
Data Sent as POST parameters.	
&ZOHO_CRITERIA=("Department"='Finance')

ZOHO_CRITERIA is encoded for the URL format. The values without encoding is given below:

ZOHO_CRITERIA=("Department" = 'Finance')

Specifying the action

In the query string of the URL, the ZOHO_ACTION parameter should be "DELETE". For explanation about other mandatory query string parameters such as ZOHO_OUTPUT_FORMAT, refer this link.

Note: Value of ZOHO_ACTION parameter should be in the same case(UPPER CASE) as given in this document.

Criteria

If the ZOHO_CRITERIA parameter is not sent, then all the rows are deleted. If criteria is sent then the rows matching the criteria alone are deleted. Please view this link for more details about the format for ZOHO_CRITERIA.

Sample Success Response

The following code snippets provides the response in XML and JSON formats for the sample refered above.

XML

<?xml version="1.0" encoding="UTF-8" ?> 
<response uri="/api/abc@zoho.com/EmployeeDB/EmployeeDetails" action="DELETE">
<criteria>&quot;Department&quot; = &apos;Finance&apos;</criteria>
<result>
<message>Deleted rows</message> 
<deletedrows>4</deletedrows>
</result>
</response>

JSON

{
"response":
{
"uri": "/api/abc@zoho.com/EmployeeDB/EmployeeDetails",
"action": "DELETE",
"criteria": "\"Department\" = \'Finance\'",
"result":
{
"message": "Deleted rows",
"deletedrows":"4"
}
}
}

↧

Export :: Version7.5

November 14, 2015, 12:16 am

≫ Next: Applying-Filters :: Version6.7

≪ Previous: Deleting-Data :: Version5.4

Export

1. It is mandatory to use HTTPS in all API requests instead of HTTP request. HTTP is not supported

2. Always use https://reportsapi.zoho.com as the API request URL.

Using this API users can export/pull data from tables or reports (pivots, charts etc.,) in different formats.

Sample

Exports the records of all the employees in the finance department in CSV Format.

URL
https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB/EmployeeDetails?ZOHO_ACTION=EXPORT
&ZOHO_OUTPUT_FORMAT=CSV&ZOHO_ERROR_FORMAT=XML
&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0

Additional Control Parameters Sent as POST parameters

&ZOHO_CRITERIA=("Department"='Finance')&ZOHO_DELIMITER=0

ZOHO_CRITERIA is encoded for the url format. Value without encoding is below:

ZOHO_CRITERIA=("Department" = 'Finance')

Query String Parameters

In the query string of the URL include the following parameters

ZOHO_ACTION parameter should be "EXPORT".

Note: Value of ZOHO_ACTION parameter should be in the same case(UPPER CASE) as given in this document.
ZOHO_OUTPUT_FORMAT should be the required format. The supported formats are
- CSV
- XML
- JSON
- HTML
- PDF
- IMAGE (applicable only for Charts)

For explanation about other mandatory query string parameters such as ZOHO_ERROR_FORMAT, refer to this link.

Criteria

If the ZOHO_CRITERIA parameter is not sent, then all the rows are exported. If criteria is sent the rows matching the criteria alone are exported. For more details about the format for the criteria refer this link.

Response Formats

CSV Format

To export in CSV format, in query parameters, the value for ZOHO_OUTPUT_FORMAT should be CSV

Additional parameters (preferably to be sent in the body of the POST request).

Parameter	Possible Values	Description
ZOHO_OUTPUT_FORMAT	CSV
ZOHO_DELIMITER	Value between 0 - 3 0 - COMMA 1 - TAB 2 - SEMICOLON 3 - SPACE	The delimiter character used for separating the fields in a row in the CSV.
ZOHO_RECORD_DELIMITER	Value between 0 - 2 0 - DOS 1 - UNIX 2 - MAC	The record delimiter (newline character) to use.
ZOHO_QUOTED	Value between 0 - 1 0 - SINGLE 1 - DOUBLE	The quote character to use for quoting the values.
ZOHO_INCLUDE_HEADER	true / false	true - To include the column names in the first row of the CSV exported. false - To not include the column names in the CSV exported.
ZOHO_SHOW_HIDDENCOLS	true / false	Controls where the columns that have been hidden in the table/report have to be exported. true - To include the hidden columns of the table/report in the data exported false - To not include the hidden columns of the table/report in the data exported.

Sample Success Response:

The following is a sample Export of data in a Table, in CSV format:

"Name","Department","Date Of Birth"
"John","Finance","12 May 1972"
"Joan","Admin","15 June 1975"

JSON Format

To export in JSON format, in query parameters, the value for ZOHO_OUTPUT_FORMAT should be JSON

Additional parameters (preferably to be sent in the body of the POST request).

Parameter

Possible Values

Description

ZOHO_SHOW_HIDDENCOLS

true / false

Controls where the columns that have been hidden in the table/report have to be exported.

true - To include the hidden columns of the table/report in the data exported

false - To not include the hidden columns of the table/report in the data exported.

ZOHO_CALLBACK_FUNCTION

Name of the json callback function

Processes JSON response elsewhere in the JavaScript code on the page

Sample Success Response:

The following is a sample Export of data in a Table, in JSON format:

{ 
	"response":
{
"uri": "/api/abc@zoho.com/EmployeeDB/EmployeeDetails",
"action": "EXPORT",
"result":
{
"column_order":["Name","Department","Date Of Birth"],
"rows":[
["John","Finance","12 May 1972"],
["Joan","Admin","15 June 1975"]
]
}
}
}

XML Format

To export in XML format, in query parameters, the value for ZOHO_OUTPUT_FORMAT should be XML

Additional parameters (preferably to be sent in the body of the POST request).

Parameter

Possible Values

Description

ZOHO_SHOW_HIDDENCOLS

true / false

Controls where the columns that have been hidden in the table/report have to be exported.

true - To include the hidden columns of the table/report in the data exported

false - To not include the hidden columns of the table/report in the data exported.

Sample Success Response:

The following is a sample Export of data in a Table, in XML format

<?xml version="1.0" encoding="UTF-8" ?>
<response uri="/api/abc@zoho.com/EmployeeDB/EmployeeDetails" action="EXPORT">
<result>
<rows>
<row>
<column name="Name">Gary</column>
<column name="Date Of Birth">12-Jun-1980</column>
<column name="Basic">10000</column>
<column name="Country">USA</column>
</row>
<row>
<column name="Name">John</column>
<column name="Date Of Birth">12-Jun-1981</column>
<column name="Basic">10000</column>
<column name="Country">Canada</column>
</row>
<row>
<column name="Name">Joan</column>
<column name="Date Of Birth">12-Jun-1982</column>
<column name="Basic">10000</column>
<column name="Country">Mexico</column>
</row>
</rows>
</result>
</response>

HTML Format

To export in HTML format, in query parameters, the value for ZOHO_OUTPUT_FORMAT should be HTML

Additional parameters (preferably to be sent in the body of the POST request).

Parameter

Possible Values

Description

ZOHO_SHOW_HIDDENCOLS

true / false

Controls where the columns that have been hidden in the table/report have to be exported.

true - To include the hidden columns of the table/report in the data exported

false - To not include the hidden columns of the table/report in the data exported.

PDF Format

To export in PDF format, in query parameters, the value for ZOHO_OUTPUT_FORMAT should be PDF

Additional parameters (preferably to be sent in the body of the POST request).

Parameter	Possible Values	Description
ZOHO_PAPERSIZE	Value between 0 - 5 0 - LETTER 1 - LEGAL 2 - TABLOID 3 - A3 4 - A4 5 - AUTO	The size of the paper.
ZOHO_SHOW_TITLE	Value between 0 - 2 0 - AT TOP 1 - AT BOTTOM 2 - NONE	Controls the title positioning.
ZOHO_SHOW_DESC	Value between 0 - 2 0 - AT TOP 1 - AT BOTTOM 2 - NONE	Controls the description positioning.
ZOHO_EXPORT_LANGUAGE	Value between 0 - 4 0 - ENGLISH 1 - EUROPEAN 2 - CHINESE 3 - JAPANESE 4 - KOREAN Default - ENGLISH	PDF will be rendered using the specified language
ZOHO_PAPERSTYLE	Portrait / Landscape
ZOHO_SHOW_HIDDENCOLS	true / false	Controls where the columns that have been hidden in the table/report have to be exported. true - To include the hidden columns of the table/report in the data exported false - To not include the hidden columns of the table/report in the data exported.
ZOHO_SELECTED_COLUMNS	List of comma separated column names	Controls the column names that need to be exported. If it is not given then all the columns, in the table/report, are exported.
Margin Settings:
ZOHO_TOPMARGIN	Decimal values between 0 to 1	The margin in inches for that edge. Can be decimal between 0 to 1 (like 0.5).
ZOHO_BOTTOMMARGIN
ZOHO_LEFTMARGIN
ZOHO_RIGHTMARGIN
Header/Footer Settings:
ZOHO_HEAD_LEFT	Value between 0 - 5 0 - Leave it blank 1 - Include Title 2 - Current Date/Time 3 - Include Page number in the format "Page #" 4 - Include page number in the format "Page # Of #" 5 - CUSTOM - Include custom text in footer	The header or footer value that needs to be generated for each page at that particular position.
ZOHO_HEAD_RIGHT
ZOHO_HEAD_CENTER
ZOHO_FOOT_LEFT
ZOHO_FOOT_RIGHT
ZOHO_FOOT_CENTER
Custom Header/Footer value
ZOHO_HEAD_LEFT_TEXT	Custom text.	If any of the header/footer setting is 5 (.ie, CUSTOM) then the corresponding custom value/text should be passed.
ZOHO_HEAD_RIGHT_TEXT
ZOHO_HEAD_CENTER_TEXT
ZOHO_FOOT_LEFT_TEXT
ZOHO_FOOT_RIGHT_TEXT
ZOHO_FOOT_CENTER_TEXT

IMAGE Format

To export in IMAGE format, in query parameters, the value for ZOHO_OUTPUT_FORMAT should be IMAGE. You can only export Charts in Image format.

Additional parameters (preferably to be sent in the body of the POST request).

Parameter	Possible Values	Description
ZOHO_WIDTH	<number>	The width of the image .
ZOHO_HEIGHT	<number>	The height of the image
ZOHO_TITLE	true / false	Controls whether the title of the report is to be added to the image. true - Include the title. false - Do not include title.
ZOHO_DESCRIPTION	true/false	Controls whether the description of the report is to be added to the image. true - Include the description. false - Do not include description.
ZOHO_SHOWLEGEND	true / false	Controls whether the legend is to be included in the image generated. true - Include the legend in the image. false - Do not include the legend in the image.
ZOHO_IMAGE_FORMAT	png / jpg	The format of the exported image. It could be either in PNG or JPG formats.

JSON Callbacks - JSONP:

Zoho Reports API supports Callback function for handling API responses asynchronously. This is supported in Export API calls, when the output format is chosen as JSON.

The Export API method call, with JSON output format, supports an additional parameter called ZOHO_CALLBACK_FUNCTION to enable callback. Using the Callback function, developers can invoke the Export API request inside the <script> tag and process the JSON response using the CALLBACK function elsewhere in the JavaScript code on the page.

Example:

1. Define the callback function

2. Invoke the api request with output format as JSON and ZOHO_CALLBACK_FUNCTION=sampleFunction

When the page is loaded, the response will be returned as,

sampleFunction( 
{ 
"response":
{
"uri": "/api/abc@zoho.com/EmployeeDB/EmployeeDetails",
"action": "EXPORT",
"result":
{
column_order:["Name","Department","Date Of Birth"],
rows:[
["John","Finance","12 May 1972"],
["Joan","Admin","15 June 1975"]
]
}
}
} );

Export Using SQL:

Zoho Reports has implemented the Zoho CloudSQL technology as an extension to its HTTP Web API. Using the Zoho Reports HTTP API, users can query the database by providing SQL queries.

Refer to the documentation on Zoho Reports CloudSQL for more details on how to use SQL SELECT query to fetch data from Zoho Reports.

↧

Applying-Filters :: Version6.7

November 14, 2015, 12:16 am

≫ Next: Request-Format :: Version8.6

≪ Previous: Export :: Version7.5

Applying Filters

Zoho Reports API allows you to apply filter criteria while you execute the various actions. When you apply a criteria, the action will be performed only on the data that matches the filter criteria given.

You can apply criteria as part of the following API actions:

The filter criteria has to be passed as a parameter, named ZOHO_CRITERIA, to the action request. This should be part of the body of the POST request.

Format

The filter criteria that is passed as part of the request, should follow the same format as that of the SQL SELECT WHERE clause. The generalized format of a simple criteria is given below:

(<column name/SQL expression/SQL function calls> <relational operator> <value/column name/SQL expression/SQL function calls>)

Example:

(("Department"='Finance' and "Salary" < 9000) or ("Department"='Admin' and "Salary" < 8000))

Description:

The criteria follows the SQL SELECT WHERE condition like format. You could also use SQL in-built functions as part of the criteria. These built-in functions should be the functions supported by any of Oracle, MS SQL Server, MySQL, DB2, Sybase, ANSI SQL, Informix and PostgreSQL databases.

column name	Refers to the name of the column in table or query table on which you are applying a criteria
SQL Expression	You could provide any valid SQL Expression. The above expression subracts the value in the "Cost" column from value in the "Sales" column. You could use any of the Arithmetic operator supported in an SQL SELECT WHERE clause. Supported Arithmetic Operators: +, -, *, /
SQL Function call	Oracle, MS SQL Server, MySQL, DB2, Sybase, ANSI SQL, Informix and PostgreSQL databases Eg.: year(date_column) = 2008 Note: All supported in-built function from different databases will be documented soon.
relational operator	This could be any of the relational operators supported in an SQL SELECT WHERE clause. Supported Relational Operators: = != < > <= >= LIKE NOT LIKE IN NOT IN BETWEEN
value	Refers to the exact value to match Eg.: "Department" = 'Finance" here 'Finance' is a literal value to match.

Notes for Criteria formation:

You can combine any number of criteria defined in the above specified format using Logical Operators like AND and OR to form complex criteria, the same way as in SQL SELECT WHERE clause. Also use Braces '()' to group the criteria for ordering.
Enclose string literals (ie values) in single quotes.
Enclose column names in double quotes.
- Eg.: ("Date Of Birth" = '2007-01-31 00:00:00')
Currency symbols (or) percent symbol can't be used in criteria
- Eg.: currency_column = 75.66 is valid
- Eg.: percent_column = 100 is valid
- currency_column = 75.66$ (or) percent_column = 100% is not valid

Refer to the SQL SELECT WHERE clause documentation of any database that we support, to know more on how to construct the filter criteria.

Sample

A sample delete request that deletes all the rows that match the criteria "Department"= 'Finance' is given below.

URL:

https://reportsapi.zoho.com/api/abc@zoho.com/EmployeeDB/EmployeeDetails?ZOHO_ACTION=DELETE
&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML
&authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0

Data Sent as POST parameters.

ZOHO_CRITERIA=("Department"='Finance

ZOHO_CRITERIA is encoded for the url format. Unencoded value is provided below.

ZOHO_CRITERIA=("Department" = 'Finance')

↧

Prerequisites The section explains the prerequisites for using the API. Kindly go through all the links before proceeding to next sections. Zoho Reports User Account AuthToken Reporting Database	API Specification Covers detailed API specification and common terminologies used. It is important to understand the API specification clearly before referring to the actual API methods. Request Format Response Format Error Handling Common Parameters

Data API This section lists the APIs which can be used to perform data addition, bulk import, deletion and updates into your Zoho Reports data tables. This also provides APIs to Export your tables, reports & dashboards in PDF, Excel, JSON, HTML, Image and CSV formats. Add Row Bulk Import (can be used to create a new table too) Update Row(s) Delete Row(s) Export Applying Filter Criteria	Modeling & Metadata API This section lists all the modeling and metadata APIs. Modeling APIs can be used to add, delete & rename columns in a Zoho Reports table. It also offers APIs to copy objects (databases, reports and formulas) from one database to another present in the same account or across different accounts. Metadata APis can be used to fetch information about the reporting databases,tables, reports and dashboards created in Zoho Reports. Modeling Add Column Delete Column Rename Column Copy Database ^new Delete Database ^new Copy Reports ^new Copy Formula ^new Metadata Database Metadata Get View Name ^new Get Database Name ^new Get Info ^new

Sharing & Collaboration API This section provides APIs for sharing & collaboration. You can share views (reports & dashboards) created in Zoho Reports with fine grained permission control to users through APIs. You can also manage sharing as well as remove sharing through APIs. Share View(s) Remove Sharing Add Database Owner Remove Database Owner	Embed API With this API you can embed reports & dashboards created in Zoho Reports into your Web pages/applications programmatically. This offers great possibilities to developers for creating dynamic reporting content embedded within their websites & applications seamlessly. Get View URL ^new Get Embed URL ^new

User Management API This section lists the User Management APIs for managing users in the Zoho Reports Administrator account. Add User Remove User Activate User Deactivate User Get Share Info	Single Sign-On API (for White Label customers) This section lists the APIs which can be used only by White Label customers (full rebranding) to easily implement single sign-on in their application for seamless user management . Sign Up Sign In Sign Out

Client Libraries This section discusses about the Built-In Client Libraries, which are "easy to use" wrappers around the raw HTTP based Zoho Reports API, that could be used in your programming language of choice & convenience Java Python C# Google App Engine	Zoho CloudSQL Zoho CloudSQL is a middleware technology that allows customers to interact with their business data stored in Zoho Reports through familiar SQL language. Users can access the data in Zoho Reports using SQL SELECT queries. Zoho Reports CloudSQL Implementation Zoho Reports JDBC Driver More about Zoho CloudSQL

API Usage Limits & Pricing Zoho Reports API usage will be measured based on units consumed & frequency of API calls. The API Units and frequency calculations are described in this section. API units allowed are scoped by each of the pricing plans. API Units API Frequency Limits API Units Pricing	Contact Us For any technical assistance in using Zoho Reports API, feel free to get in touch with our 24X7 Customer Support. Email Address: support@zohoreports.com Toll-free Number: 1-(888)-900-9646