Merge and Sign in Zoho Writer
Description
The zoho.writer.mergeAndSign task merges your document and sends it to recipients for signature collection. This task is based on the Zoho Writer Merge and Sign API.
Syntax
<response> = zoho.writer.mergeAndSign(<document_id>, <merge_detail>, <filename>, <signerList>, <option_settings>, <connection>)
where:
Params | Data type | Description |
<response> | KEY-VALUE | The response returned by Zoho Writer. It provides the merged document's details such as the merge data, along with the status of the merge. |
<document_id> | TEXT | The ID of the document to be merged and sent for signature. The document ID can be obtained from the URL of the document which needs to be merged and sent for sign. The URL is formatted as follows: |
<merge_detail> | KEY-VALUE | Specify how your input for the merge will be. It can be JSON, CSV file, or a URL. |
<filename> | String | A unique name for the signed document. |
<signerList> | [ | The recipients to whom the document will be sent for signature, in-person signing, or viewing and approval in the form of a JSON Array.
You can also set the language for the notification email that will be sent to signers. You can authenticate and provide private notes to recipients.
Supported languages: Chinese(zh), Dutch(nl), English(en), French(fr), German(de), Italian(it), Japanese(ja), Polish(pl), Portuguese(pt), Russian(ru), Spanish(es), Swedish(sv).
You can refer to a sample JSON Array here.
Note: If this parameter is not passed, we will apply the values configured in the template settings. |
<optional_settings> | KEY-VALUE | The optional parameters you can send to merge and sign data according to your preference. |
<connection> | TEXT | The connection's link name. Note:
|
You can provide the merge_detail
Key | Value | Description |
---|---|---|
merge_data | JSONObject | Pass a String value through data key as JSON Array. |
merge_data_csv_content | File | Provide the required CSV content in your API request body. |
merge_data_json_content | File | Provide the required JSON content in your API request body. |
merge_data_csv_url | URL | Provide the required CSV URL in your API request body. |
merge_data_json_url | URL | Provide the required JSON URL in your API request body. |
signerList parameter values:
Parameter | Type | Possible Values | Default Value |
recipient_n | string | recipient_1, recipient_2, ... , recipient_10 Note: You can send up to 10 recipients | john@zylker.com |
action_type | string | approve/sign/view/in_person_sign | sign |
language | string | zh/ nl / en / fr / de / it / ja / pl / pt / ru / es / sv | This option is available only for Zoho Sign Premium Plan users. For Free Plan users, the notification email will be sent in their account language by default. |
optional_settings parameter values:
Parameter | Data Type | Description |
sign_in_order | Boolean (true/false) | Specify whether the signing order should be maintained as entered. |
message | String | Add a message for the signer. |
set_expire | Number | Specify when the merged documents which are sent for sign need to be expired. |
reminder_period | Number | Specify when reminder emails should be sent to signers. |
common_attachments | File | Specify the attachments that need to be sent to all the recipients in common. Maximum files allowed: 3 Maximum file size allowed: 3 MB Supported file formats: DOCX / DOC / RTF / PDF / ZIP / HTML / TXT / PNG / JPEG / GIF / JPG |
unique_attachments | { (OR) } | Using this parameter, you can send a different or unique attachment to each recipient. It can be sent in either one of the following ways: 1. Field Containing Attachment URLs: If you want to map the attachment file paths to a spreadsheet/CSV file. (OR) 2. Folder Containing Attachments: If you want to map the attachment file paths to a particular folder. |
test_mode | Boolean (true/false) | Using this parameter, you can test the Merge APIs without consuming any credit points. The output file will contain a watermark as it is used only for testing purposes. Test mode limit: 50 merges/day for an org. |
Example
The following script merges a document and sends it for approval to a user and once approved sends it for signature collection in the defined order.
document_id = "po5uobda049e029d44b13a9956f6d2cedc67b"; fields = Map(); fields.put("InvoiceNo","12345"); fields.put("InvoiceDate","27 May 2022"); fields.put("InvoiceAmount","$100"); data_map = Map(); data_map.put("data", fields) merge_details = Map(); merge_details.put("merge_data", data_map); filename = "Invoice data"; signerList = List(); signerObj1 = Map(); signerObj1.put("recipient_1","john@zylker.com"); signerObj1.put("action_type","approve"); //approve|sign|view signerObj1.put("language","en"); signerObj2 = Map(); signerObj2.put("recipient_2","amelia@zylker.com"); signerObj2.put("action_type","sign"); //approve|sign|view signerObj2.put("language","fr"); signerList.add(signerObj1); signerList.add(signerObj2); commonAttachmentFile1 = invokeurl [ url :"<https://example.com/download/publicdocument>" type :GET ]; option_settings = Map(); option_settings.put("sign_in_order","true"); option_settings.put("message", "Please find the document to be signed here"); option_settings.put("set_expire", "30"); option_settings.put("reminder_period", "15"); option_settings.put("common_attachments", commonAttachmentFile1); option_settings.put("test_mode", "true"); response = zoho.writer.mergeAndSign(document_id, merge_details, filename, signerList, option_settings, "writer_oauth_connection"); info response;
Usecase
Scenario 1: Send a document for signing
Consider a scenario where you need to send an offer letter for signature with all the fields configured. HR merges and creates the offer letter and sends it to the candidate for signing.
document_id = "po5uobda049e029d44b13a9956f6d2cedc67b"; fields = Map(); fields.put("Date","27 May 2022"); fields.put("Recipients_name","Mikeal"); fields.put("Position","Support Engineer"); data_map = Map(); data_map.put("data", fields) merge_details = Map(); merge_details.put("merge_data", data_map); String filename = "Offer Letter"; signerList = List(); signerObj1 = Map(); signerObj1.put("recipient_1","Hr-operations@zylker.com"); signerObj1.put("action_type","approve"); //approve|sign|view signerObj1.put("language","en"); signerObj2 = Map(); signerObj2.put("recipient_2","mikeal@test.com"); signerObj2.put("action_type","sign"); //approve|sign|view signerObj2.put("language","fr"); signerList.add(signerObj1); signerList.add(signerObj2); option_settings = Map(); option_settings.put("sign_in_order","true"); option_settings.put("message", "Kindly read all the details in the document properly and accept it by signing"); option_settings.put("set_expire", "30"); option_settings.put("reminder_period", "15"); response = zoho.writer.mergeAndSign(document_id, merge_details, filename, signerList, option_settings, "writer_oauth_connection"); info response;
Scenario 2: Collect signatures in a specific order
Consider a scenario where you need multiple people to sign a purchase order. Sales person creates the order and sends it to sales manager for approval. Once it is signed by the manager, it is sent to the client.
document_id = "po5uobda049e029d44b13a9956f6d2cedc67b"; fieldsList = List(); fieldsmap1 = Map(); fieldsmap1.put("Purchsed_Date","27 May 2022"); fieldsmap1.put("Product_name","Samsung series s8"); fieldsmap1.put("Price","50000"); fieldsmap2 = Map(); fieldsmap2.put("Purchsed_Date","30 May 2022"); fieldsmap2.put("Product_name","Apple 15 pro max"); fieldsmap2.put("Price","10000"); fieldsList.add(fieldsmap1); fieldsList.add(fieldsmap2); data_map = Map(); data_map.put("data", fields) merge_details = Map(); merge_details.put("merge_data", data_map); String filename = "Sales Invoice"; signerList = List(); signerObj1 = Map(); signerObj1.put("recipient_1","approval-manager@zylker.com"); signerObj1.put("action_type","approve"); //approve|sign|view signerObj1.put("language","en"); signerObj2 = Map(); signerObj2.put("recipient_2","client-manager@test.com"); signerObj2.put("action_type","sign"); //approve|sign|view signerObj2.put("language","en"); signerList.add(signerObj1); signerList.add(signerObj2); option_settings = Map(); option_settings.put("sign_in_order","true"); option_settings.put("message", "Details regarding latest purchase order"); option_settings.put("reminder_period", "15"); response = zoho.writer.mergeAndSign(document_id, merge_details, filename, signerList, option_settings, "writer_oauth_connection"); info response;
Response Format
{ "merge_report_data_url": "http://writer.zoho.com/writer/api/v1/merge/job/po5uobda049e029d44b13a9956f6d2cedc67b/data", "merge_report_url": "http://writer.zoho.com/writer/v1/mailmerge/job/po5uobda049e029d44b13a9956f6d2cedc67b", "records": [ { "InvoiceNo": "12345", "InvoiceDate": "27 May 2022", "InvoiceAmount": "$100", "download_link": "{url}", "sign_request_id":12345****", "status": "inprogress" } ] }
Related Links
- Zoho Writer integration tasks
- Connections
- Zoho Writer - Merge and Sign API document
- Zoho Writer API - Possible error responses