Choose where you’d like to start

Merge and Download Documents in Zoho Writer

Table of Contents

Description

The zoho.writer.mergeAndDownload task supplies values to the merge fields inserted to a document, and returns the new merged documents converted into a single file of specified format. The values of the merge fields are provided from a data source of type CSV or JSON.

This integration task is based on the Zoho Writer API - Merge document.

Note:
  • The merge fields inserted into the document should be the column headers of a CSV data source, or the keys in a JSON data source.
  • On average, it takes about a minute to index a file/folder after it is created or updated. This indexing time can increase if the queue size increases.  You will not get the expected result if you execute zoho.writer.mergeAndDownload task before the document you need to merge is indexed.

Syntax

<response> = zoho.writer.mergeAndDownload(<document_id>, <output_format>, <values_map>, <connection>);
where:
ParamsData typeDescription

<response>

FILE

The output file object that contains the new merged documents.

<document_id>

TEXT

The ID of the source document that will be merged with values.

The document ID can be obtained from the URL of the source document. The URL is in the following format:
https://writer.zoho.com/writer/open/<document_id>

<output_format>

TEXT

The format of the output file.

Allowed values:

  • pdf
  • docx

<values_map>

KEY-VALUE

The values that will be supplied to the merge fields. The values can be fetched only from CSV file or JSON file/text.

Note: The keys of this parameter should be specified as given in the Zoho Writer API. Applicable keys and values for CSV and JSON data as specified in Zoho Writer - Merge document API:

CSV:

  • Specify the file URL
    key: merge_data_csv_url
    value: The TEXT that represents the URL of the CSV file.
  • Specify values stored in a file object 
    key: merge_data_csv_content
    value: The FILE that contains the merge values.

JSON:

  • Specify the file URL
    key: merge_data_json_url
    value: The TEXT that represents the URL of the JSON file.
  • Specify values stored in a file object 
    key: merge_data_csv_content
    value: The FILE that contains the merge values.
  • Specify the text directly
    key: merge_data
    value: The TEXT/ KEY-VALUE that represents the JSON value. The key for the JSON value needs to be "data".

<connection>

TEXT

The link name of the connection.

Note:

  • In view of stopping new authtoken generation, a Zoho OAuth connection with appropriate scopes is mandatory in order for new integration tasks (created after the deadline specified in the post) to work as expected. Existing integration tasks will continue to work with or without the connections parameter until you manually delete the authtoken from accounts.
  • Add relevant scopes mentioned in Zoho Writer API while creating the connection.
  • Refer to this post for the list of Zoho services that support the connections page.
  • Learn more about connections

Example 1: Supply CSV content to the merge fields and download the new merged documents in .pdf format

The following script supplies the CSV data stored in the FILE variable - csv_content to the merge fields present in the specified documents, and stores the file to the variable - response in .pdf format.

 // Fetch the CSV data from the web and store it in the variable - csv_content
 csv_content =  invokeurl 
 [
 url : "http://insight.dev.schoolwires.com/HelpAssets/C2Assets/C2Files/C2ImportCalEventSample.csv"
 type : GET
 ];
 
 
 // Construct a KEY-VALUE variable to hold the merge data
 merge_values = Map();
 merge_values.put("merge_data_csv_content", csv_content);
 
 
 // Perform the Merge and Download task
 response = zoho.writer.mergeAndDownload("al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c", "pdf", merge_values, "writer_oauth_connection");

where:

response
The FILE response that represents the output file object.
"al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c"
The TEXT that represents the document ID of the source document.
"pdf"
The TEXT that represents the format of the output file.
merge_value
The KEY-VALUE variable that holds the merge data.
"writer_oauth_connection"
The TEXT that represents the name of the connection.
"merge_data_csv_content"
The TEXT key that represents the type of data source. Here, the data source is a FILE that contains CSV data.
csv_content
The FILE variable that holds the CSV data that will be supplied to the merge fields.
Note: The CSV data is fetched from the cloud using the invoke URL task. To learn more about the invokeUrl task, click here.

Example 2: Supply CSV data from a URL to the merge fields and download the new merged documents in .docx format

The following script supplies CSV values fetched from the specified URL to the merge fields present in the specified documents, and stores the file in the variable - response.

 // Construct a KEY-VALUE variable to hold the merge data and subject of the email
 merge_values = Map();
 merge_values.put("merge_data_csv_url", "http://insight.dev.schoolwires.com/HelpAssets/C2Assets/C2Files/C2ImportCalEventSample.csv");
 
 
 // Perform the Merge and Download task 
 response = zoho.writer.mergeAndDownload("al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c", "docx", merge_values, "writer_oauth_connection");

where:

"docx"
The TEXT that represents the format of the output file.
"merge_data_csv_url"
The TEXT key that represents the type of the data source. Here, the data source is a URL that contains CSV data.
"http://insight.dev.schoolwires.com/HelpAssets/
C2Assets/C2Files/C2ImportCalEventSample.csv"
The TEXT that represents the URL of the data source.

Example 3: Supply JSON content in TEXT format to the merge fields and protect the downloaded .docx file with a password

The following script supplies JSON values held by the variable - json_text to their respective merge fields, and protects the downloaded .docx file with the password - mergedFile2019.

 // Assign the JSON data in TEXT format to the variable - json_text
 json_text = "{\"data\":[{\"Name\":\"Shawn\",\"Age\":\"20\"},{\"Name\":\"Kate\",\"Age\":\"29\"}]}";
 
 
 // Construct a KEY-VALUE variable to hold the merge data
 merge_values = Map();
 merge_values.put("password", "mergedFile2019");
 merge_values.put("merge_data", json_text);
 
 
 // Perform the Merge and Download task 
 response = zoho.writer.mergeAndDownload("al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c", "docx", merge_values, "writer_oauth_connection");

where:

"merge_data"
The TEXT key that represents the type of data source. Here, the data source is JSON data in TEXT format.
json_text
The TEXT variable that holds the JSON data that will be supplied to the merge fields. Here, the JSON array value needs to be associated with the key "data".
password
The TEXT key that holds the password with which the output file will be protected.

Example 4: Supply JSON content in KEY-VALUE format to the merge fields and download the new merged documents in .docx format

The following script will take the JSON values in Key-Value format from the variable - Content to merge them with their respective merge fields and download the new merged documents in .docx format.

// Assign the JSON data in Key-Value format to the variable - Content 
Content = Map(); 
Content.put("Name","Shawn"); 
Content.put("Age","20"); 
 
// Construct a KEY-VALUE variable to hold the merge data
merge_values = Map(); 
merge_values.put("merge_data", {"data":Content}); 
 
// Perform the Merge and Download task  
response = zoho.writer.mergeAndDownload("bc296XXXXXXXXXXXXXXXXXXXXXXXXXXXa563a", "pdf", merge_values, "writer_oauth_connection");

where:

"merge_data"
The TEXT key that represents the type of data source. Here, the data source is JSON data in KEY-VALUE format.
Content
The KEY_VALUE variable which holds the data that will be supplied to the merge fields. Here, the JSON array value needs to be associated with the key "data".

Example 5: Upload the merged and downloaded file to Zoho Workdrive

The following example uploads the merged file to workdrive:

 csv_content =  invokeurl 
 [
 url : "http://insight.dev.schoolwires.com/HelpAssets/C2Assets/C2Files/C2ImportCalEventSample.csv"
 type : GET
 ];
 
 merge_values = Map();
 merge_values.put("merge_data_csv_content", csv_content);
 
 response = zoho.writer.mergeAndDownload("al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c", "pdf", merge_values, "writer_oauth_connection");
 
 
 // Upload the merged pdf file to Zoho Workdrive using integration task 
 upload_response = zoho.workdrive.uploadFile(response, "690xuXXXXXXXXXXXXXXXXXXXXXXXXXXX5b399", "fileName", false, "workdrive_oauth_connection");

where:

upload_response
The KEY-VALUE that represents the details of the file uploaded to Zoho Workdrive.
response
The FILE that represents the merged and downloaded file that will be uploaded to Zoho Workdrive.
Note: The zoho.workdrive.uploadFile integration task uploads a file to the specified Zoho Workdrive folder. Click here to learn more.

Response Format

Success Response

  • The success response will be returned in the following format:

      fileName.pdf

Failure Response

  • The failure response for empty merge data will be returned in the following format:

      {
      "error": {
      "documentation_url": "https://www.zoho.com/writer/help/api/v1/general-errors.html",
      "message": "Merge data not found. Please try again with proper merge data.",
      "errorcode": "1837"
      }
      }

  • The failure response for improper document ID will be returned in the following format:

      {
      "error": {
      "message": "Request URL not configured properly. Please check and try again",
      "documentation_url": "https://www.zoho.com/writer/help/api/v1/general-errors.html",
      "response_generated_time": 1563961624177,
      "request_url": "https://writer.zoho.com/api/v1/documents//collaboration",
      "errorcode": "R2008"
      }
      }

  • The failure response when you try to merge values to a document that you do not have permission will be returned in the following format:

      {
      "error": {   "message": "Permission denied. You are not authorized to perform this operation.",   "documentation_url": "https://www.zoho.com/writer/help/api/v1/general-errors.html",   "response_generated_time": 1563961602526,   "request_url": "https://writer.zoho.com/api/v1/documents/al296XXXXXXXXXXXXXXXXXXXXXXXX6964add/collaboration",   "errorcode": "R5010"   }   }

Related Links

Get Started Now

Execute