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.
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>Note: The CSV should contain the column names in the first row.
<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>
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 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 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.
- For more details on the supported JSON formats, refer here.
|
|
1.
It is no longer mandatory to pass the ZOHO_API_KEY parameter as part of
the query string in the URL. This will be deprecated soon. In case you
are using it, you can remove it. 2. Usage of Ticket in API requests is deprecated. Users are strongly recommended to use Auth Token instead of Ticket in your API requests, as support for Ticket will be removed in the near future. 3. Recommended to use Zoho Reports Login Email Address in the API URL instead of Zoho Username. |
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 |
|
Optional. Default value is CSV. Format of the file to be imported. Supported formats are:
|
|
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 - 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 |
|
|
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.
|
|
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* |
|
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>