Choose where you’d like to start

​

Merge and Send Documents in Zoho Writer

Table of Contents

Description

The zoho.writer.mergeAndSend task supplies values to the merge fields inserted to a document, and sends the new merged documents individually to the specified email ID. 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 and Email.

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.mergeAndSend task before the document you need to merge is indexed.

Syntax

<response> = zoho.writer.mergeAndSend(<document_id>, <output_format>, <email_id>, <values_map>, <connection>);
where:

 

ParamsData typeDescription

<response>

KEY-VALUE

The response returned by Zoho Writer. It represents the merge fields data of 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 output format of the new documents that will be sent through email.

Allowed values:

  • inline - The merged document is sent in the email body.
  • pdf - The merged document is sent as an email attachment in .pdf format.
  • docx - The merged document is sent as an email attachment in .docx format.

<email_id>

TEXT

The email address of the recipient to whom the individual documents will be sent.

<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 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_json_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".

Optional keys:

  • Specify the subject of the email
    key: subject
    value: The TEXT value associated with this key specifies the subject of the email that needs to be sent.

<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 email the new merged documents

The following script supplies the CSV data stored in the FILE variable - csv_content to the merge fields present in the specified documents, and sends the new merged documents to the email address - shawn@zylker.com:

 // 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 and subject of the email
 merge_values = Map();
 merge_values.put("subject", "Merge and send Deluge task");
 merge_values.put("merge_data_csv_content", csv_content);
 
 
 // Perform the Merge and Send task 
 response = zoho.writer.mergeAndSend("al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c", "inline", "shawn@zylker.com", merge_values, "writer_oauth_connection");

where:

response
The KEY-VALUE response returned by Zoho Writer. It represents the merge fields data of the new merged documents.
"al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c"
The TEXT that represents the document ID of the source document.
"shawn@zylker.com"
The TEXT that represents the email address of the recipient to whom the new documents will be sent.
merge_value
The KEY-VALUE variable that holds the merge data, and the subject of the email that will be sent.
"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 email the new merged documents

The following script supplies CSV values fetched from the specified URL to the merge fields present in the specified documents, and sends the new merged documents to the email address - shawn@zylker.com:

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

where:

"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 email the new merged documents

The following script supplies JSON values held by the variable - json_text to their respective merge fields, and sends the new documents to the email address - shawn@zylker.com:

 // 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 and subject of the email
 merge_values = Map();
 merge_values.put("subject", "Merge and send Deluge task");
 merge_values.put("merge_data", json_text);
 
 
 // Perform the Merge and Send task 
 response = zoho.writer.mergeAndSend("al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c", "inline", "shawn@zylker.com", merge_values, "writer_oauth_connection");

where:

"merge_data"
The TEXT key that represents the type of the 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".

Response Format

Success Response

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

      {
      "merge_report_data_url": "https://docs.zoho.com/writer/api/v1/merge/job/f0b49XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXde0e1/data",
      "merge_report_url": "https://docs.zoho.com/writer/v1/mailmerge/job/f0b49XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXde0e1",
      "records": [
      {
      "Event Description": "Department meeting",
      "Category": "2",
      "All Day Event": "N",
      "Contact Phone": "814-555-5179",
      "Last Date To Register": "9/2/2011",
      "Start Time": "3:00:00 PM",
      "Event Title": "Social Studies Dept. Meeting",
      "Contact": "Chris Gallagher",
      "Contact Email": "cgallagher@schoolwires.com",
      "Maximum": "25",
      "Start Date": "9/5/2011",
      "No End Time": "Y",
      "End Date": "9/5/2011",
      "Registration": "N",
      "End Time": "",
      "Location": "High School",
      "Mandatory": "N",
      "status": "inprogress"
      },
      {
      "Event Description": "Curriculum Meeting",
      "Category": "2",
      "All Day Event": "N",
      "Contact Phone": "814-555-5179",
      "Last Date To Register": "9/2/2011",
      "Start Time": "6:00:00 PM",
      "Event Title": "Curriculum Meeting",
      "Contact": "Chris Gallagher",
      "Contact Email": "cgallagher@schoolwires.com",
      "Maximum": "25",
      "Start Date": "9/5/2011",
      "No End Time": "N",
      "End Date": "9/5/2011",
      "Registration": "N",
      "End Time": "8:00:00 PM",
      "Location": "High School",
      "Mandatory": "N",
      "status": "inprogress"
      }
      ]
      }

Failure Response

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

      {
      "error": {
      "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 when you try to share a document that is not owned or co-owned by you 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"
      }
      }

  • The failure response for incorrect email address will be returned in the following format:

      {
      "error": {
      "parameter_name": "recipient_email",
      "message": "Invalid parameter values found. Please try again with supported values.",
      "documentation_url": "https://www.zoho.com/writer/help/api/v1/general-errors.html",
      "response_generated_time": 1564637379763,
      "request_url": "https://writer.zoho.com/writer/api/v1/documents/al296XXXXXXXXXXXXXXXXXXXXXXXXXXXb4add/merge/email",
      "errorcode": "R2000"
      }
      }

  • 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