Zoho Creator (Deluge)

Automate Signing Tasks in Zoho Creator with Deluge

Zoho Sign provides the option to automate signing tasks by leveraging our own online scripting language, Deluge. Users can add logic to actions and trigger signing tasks and workflows automatically. For example, if you have a new user on-boarding application developed with Zoho Creator, and an employee enters the data and hits the submit button, an NDA document can be sent out to them immediately for signing. You can also write a custom function for other applications that supports Deluge to trigger the signing tasks.

Note:

Each document signature request generated through automation using a Zoho Sign Deluge task consumes an automation credit. Automation credits, proportionate to the number of licensed users, are provided to organizations on a monthly basis. If your organization runs out of automation credits, then each such subsequent document signature request generated will consume an API credit. API credits need to be purchased as add-ons. Learn more

This applies to custom functions, workflows, and all other automation achieved through Deluge across the various Zoho app integrations presently supported by Zoho Sign.

How it works?

  1. The Deluge Script Builder provides a drag-and-drop user interface to add Delugue scripts without requiring users to learn and remember Deluge Syntax and functions.
  2. You can create an application based on your requirements. For example, you could create a recruitment app or an inventory management app .

  3. In a recruitment app, logic can be used to automate signing tasks for NDA, social media policy, IT services policy, and more.

  4. For each logic, you can assign a signing task and send out a document for signing to employees. 

  5. Deluge will automate and simplify the whole process for you.

  6. The step-by-step instructions of Deluge Tasks for Zoho Sign are in this section of our help documentation.

Common Deluge Tasks for Zoho Sign

Sending a document for signature:

Sending a document for signature involves three steps: uploading the document, getting field types; and adding the recipients and the fields associated with the recipients.

Uploading the document:

  1. Upload the document.This document can either be stored as a Zoho Creator file field or in a third party URL from which it can be downloaded. 

  2. After getting the file object, use the uploadDocument task 

Code

file = getUrl(<path to file>);

res = zoho.sign.uploadDocument(file);

[OR]

res = zoho.sign.uploadDocument(input.File_field);

The response will contain a map with the status of either success or failure. In the case of success, it will return the details of the created document along with a request_id that you will need to perform further actions. There will also be a document_id that you need to specify which document to add fields to.

Getting field types

Zoho Sign supports many fields that can be added to a document. Each type of field has a unique field type_id that is specific to the user. You will need to retrieve the field types and IDs for your account. 

  1. Use the getFieldIds task to retrieve the field types and IDs. 

  2. The response will give the field types along with the corresponding field type IDs.

  3. This can be stored in a separate map that can be used while adding fields and sending out the document in the next step.

Code:

fieldIds = zoho.sign.getFieldIds();

fieldTypes = fieldIds.get("field_types");

fields = Map();

for each field in fieldTypes

{

fieldJson = field.toMap();

fields.put(fieldJson.get("field_type_name"), fieldJson.get("field_type_id"));

}

Adding the recipients

The final step is to specify the recipients to send the document to, along with the fields for the recipients. 

  1. Use the submitRequest task to perform this step. 

  2. Data regarding the recipient and fields needs to be passed as a map to this task.

The format of the data to be sent is shown below:

actions  - array with details of each recipient.

Each recipient object will contain:

action_id - the action_id stored from the previous call

fields - JSON object containing the details of all fields associated with the recipient, provided recipient is a signer

text_fields -array with all text based fields - Text, Company, Job Title, Full Name, Email

image_fields  - array with image fields - Signature 

date_fields - array with all date fields details

 

Data associated with each field:

document_id

page_no  - page on which field is starting from 0

field_name - the displayed name of the field

x_value - the x position of the field from the page bottom left corner

y_value - the y position of the field from the page bottom left corner

width  - width in % of page

height - height in % of page

field_type_id - the field_type_id from the previous call associated with the field type

 

is_mandatory

name_format ( only for full name field) - format of the name - FULL NAME/FIRSTNAME/LAST NAME

date_format (only for date field) - date format to be used for filling the date

text_property (for all text based fields and date fields) - contains text properties which include 

font

font_size

font_color - the Hex code of the color to be applied to the text

is_bold

is_italic

is_read_only (only for field of type "Text") - whether the field is read only

default_value (only for field of type "Text") - the default value for the field

 

Code

actionMap = Map();

actionMap.put("request_name","test_AddFields");

textFields = List();

textField1 = Map();

textField1.put("field_name", "Company");

textField1.put("is_mandatory", "true");

textField1.put("field_type_id", fields.get("Company"));

textField1.put("document_id", doc_id);

textFields.add(textField1);

fieldMap = Map();

fieldMap.put("fields",{"text_fields":textFields});

fieldMap.put("recipient_name", "John");

fieldMap.put("recipient_email","john@zylker.com");

fieldMap.put("action_type","SIGN");

fieldList= List();

fieldList.add(fieldMap);

actionMap.put("actions",fieldList);

submitMap = Map();

submitMap.put("requests", actionMap);

response = zoho.sign.submitRequest(, {"data":submitMap});

The response will contain a map that with the status as success if the document was sent successfully. If there is an error, the status will be failure, and the message key will give details about the error.

Use a Zoho Sign template to send out a document:

Zoho Sign templates help you to create a document once, then add fields and reuse them whenever needed. You just need to give the recipient details and any other Pre-fill fields that you have set up when using the template. This is especially useful when you send the same documents through Deluge. You don't need to upload the files and set up fields again.

Note: This feature is available only in Professional and Enterprise Editions.

There are three steps that you need to use a Zoho Sign template through Deluge.

  1. Get the list of templates in Zoho Sign (optional)

  2. Get the details of the required Zoho Sign template

  3. Send a document using the Zoho Sign template

Get the list of templates in Zoho Sign

This task will be helpful if you need to get the list of templates in your application. However, if you would always be using the same template for creating documents, this step can be skipped.

Use the getTemplates task to fetch the list of all templates created in the Zoho Sign account. This returns an object with the list of all Zoho Sign templates under the templates key. Each template will have a template_id, which will be needed in the subsequent steps. When you choose which template to use, store the template_id of that template. 

Code

response= zoho.sign.getTemplates();

{
"code": 0,
"message": "Template list retrieved successfully",
"page_context": {
"sort_column": "template_name",
"has_more_rows": false,
"start_index": 1,
"total_count": 1,
"sort_order": "ASC",
"row_count": 1
},
"templates": [
"{\"owner_email\":\"john@zylker.com\",\"created_time\":1521109119330,\"email_reminders\":true,\"document_ids\":[{\"document_name\":\"Zoho Sign.pdf\",\"document_size\":59808,\"document_order\":\"0\",\"total_pages\":1,\"document_id\":\"32076000000002005\"}],\"notes\":\"\",\"reminder_period\":1,\"owner_id\":\"32076000000002003\",\"description\":\"\",\"template_name\":\"Template1\",\"modified_time\":1521110073225,\"is_deleted\":false,\"expiration_days\":15,\"is_sequential\":false,\"template_id\":\"32076000000002011\",\"request_type_name\":\"Others\",\"owner_first_name\":\"John\",\"request_type_id\":\"32076000000000135\",\"owner_last_name\":\"Mathews\",\"actions\":[{\"ishost\":false,\"verify_recipient\":false,\"role\":\"CEO\",\"action_id\":\"32076000000002014\",\"action_type\":\"SIGN\",\"private_notes\":\"\",\"recipient_email\":\"john@zylker.com\",\"signing_order\":-1,\"recipient_name\":\"John Mathews\",\"recipient_phonenumber\":\"\",\"recipient_countrycode\":\"\"}]}"
],
"status": "success"

}

Fetch template details

  1. When you know which template you would like to use along with its template_id, fetch the details of that particular template. These will help you in assigning the required email addresses to the placeholder roles in the template. 

  2. This will also help you fill in the required Pre-fill fields that are in the template. 

  3. Use the getTemplateById task to fetch the details from the template Id.

  4. The response will contain the details of the template. It will include the details of the recipients who are part of the template as well as the pre-fill fields that are configured. 

There is a templates object that has an action list. This will contain as many elements as the recipients configured as part of the template.

There is also a document_fields list. Each document in the template is associated with an object. Each of these objects will contain fields list with the pre-fill fields that are part 

Sample response:


{
   "code": 0,
   "message": "Template list retrieved successfully",
   "page_context": {
      "sort_column": "template_name",
      "has_more_rows": false,
      "start_index": 1,
      "total_count": 1,
      "sort_order": "ASC",
      "row_count": 1
   },
   "templates": [
      "{\"owner_email\":\"john@zylker.com\",\"created_time\":1521109119330,\"email_reminders\":true,\"document_ids\":[{\"document_name\":\"Zoho Sign.pdf\",\"document_size\":59808,\"document_order\":\"0\",\"total_pages\":1,\"document_id\":\"32076000000002005\"}],\"notes\":\"\",\"reminder_period\":1,\"owner_id\":\"32076000000002003\",\"description\":\"\",\"template_name\":\"Template1\",\"modified_time\":1521110073225,\"is_deleted\":false,\"expiration_days\":15,\"is_sequential\":false,\"template_id\":\"32076000000002011\",\"request_type_name\":\"Others\",\"owner_first_name\":\"John\",\"request_type_id\":\"32076000000000135\",\"owner_last_name\":\"Mathews\",\"actions\":[{\"ishost\":false,\"verify_recipient\":false,\"role\":\"CEO\",\"action_id\":\"32076000000002014\",\"action_type\":\"SIGN\",\"private_notes\":\"\",\"recipient_email\":\"john@zylker.com\",\"signing_order\":-1,\"recipient_name\":\"John Mathews\",\"recipient_phonenumber\":\"\",\"recipient_countrycode\":\"\"}]}"
   ],
   "status": "success"
}

{

Code:

template_id = <your template id>;

response = zoho.sign.getTemplateById(template_id);

prefill_fields = List();

if(response.get("status")contains("success"))

{
recipients = response.get("templates").get("actions");

document_fields = response.get("templates").get("document_fields");

for each document in document_fields

{

prefill_fields.addall(document.get("fields"));

}

}

Send a document using the Zoho Sign template

This is the final step, where you can assign the recipients to whom the template must be sent and any other pre-fill fields that have been configured. The actions list and the fields list will be useful for this step.Use the createUsingTemplate task for this step. The template_id of the required template is also needed here.

The parameters for this task will have the following structure:

The parameters need to be added in a map with the key data and values containing the below mentioned values.

  • actions: a List containing the details of all the roles associated with the template. Each action Map needs to contain :
  • recipient_name - name of the recipient
  • recipient_email - the email id of the recipient
  • action_id - the value of actions_id returned in the actions array for the previous getTemplateById result
  • role - The role name specified in the template
  • action_type - SIGN/VIEW whether the person is a signer or receives a copy - as specified in the template
  • field_data - contains the data of the pre fill fields added to the template
  • field_text_data - a map containing the field name and value associated with it for all the text fields that are added under pre fill
  • field-boolean_data - a map containing the field name and the true/false value for all the check box fields that are added under pre fill
  • is_quicksend - a boolean. If true it will send the template other wise the document will be saved as a draft and needs to be manually sent from Zoho Sign's web user interface

Code:

Assume that the template has one pre-fill field called textField_1 and has two recipients added.

actionMap = Map();
fieldTextData = Map();
fieldTextData.put("TextField_1", "Document to Review");
actionMap.put("field_data",{"field_text_data":fieldTextData});
eachActionMap1 = Map();
eachActionMap1.put("recipient_name","James");
eachActionMap1.put("recipient_email","james@zoho.com");
eachActionMap1.put("action_type","SIGN");
eachActionMap1.put("action_id","32076000000002014");
eachActionMap1.put("role","Reviewer");
eachActionMap1.put("verify_recipient","false");
eachActionMap2 = Map();
eachActionMap2.put("recipient_name","Tony");
eachActionMap2.put("recipient_email","tony@zoho.com");
eachActionMap2.put("action_type","SIGN");
eachActionMap2.put("action_id","32076000000014006");
eachActionMap2.put("role","Manager");
eachActionMap2.put("verify_recipient","false");
fieldList = List();
fieldList.add(eachActionMap1);
fieldList.add(eachActionMap2);
actionMap.put("actions",fieldList);
submitMap = Map();
submitMap.put("templates",actionMap);
parameters = Map();
parameters.put("is_quicksend","true");
parameters.put("data",submitMap);
response = zoho.sign.createUsingTemplate(32076000000002011, parameters);

The response will contain a map with the status as success if the document was sent successfully. If there was an error, the status will say failure and the message key will give details about the error.

Get document status:

Make use of the get document details API along with the OAuth access token in the header to get the details of the document including status.

The response format

{
"code": 0,
"requests":
{
"request_status": "inprogress",
"notes": "Hi\nA note\nMr. Tester\nHow ar eyouuu ?",
"owner_id": "2000000002002",
"description": "",
"request_name": "Leave a note test",
"modified_time": 1522746018025,
"action_time": 1522746018310,
"is_deleted": false,
"expiration_days": 1,
"is_sequential": true,
"sign_submitted_time": 1522746018310,
"owner_first_name": "V********",
"sign_percentage": 33.34,
"expire_by": 1522866540000,
"is_expiring": true,
"owner_email": "v******@***.com",
"created_time": 1522746018025,
"document_ids": [
{
"document_name": "Employee NDA.pdf",
"document_size": 26591,
"document_order": "0",
"total_pages": 2,
"document_id": "2000000492171"
}
],
"self_sign": false,
"in_process": false,
"request_type_name": "Others",
"request_id": "2000000492177",
"request_type_id": "2000000000135",
"owner_last_name": "",
"actions": [
{
"verify_recipient": false,
"action_id": "2000000492180",
"action_type": "SIGN",
"private_notes": "",
"recipient_name": "S**********",
"recipient_email": "s*******@***.com",
"signing_order": 0,
"allow_signing": true,
"action_status": "UNOPENED",
"recipient_phonenumber": "",
"recipient_countrycode": ""
}
]
},
"message": "Document has been retrieved",
"status": "success"
}

Code:

resp = invokeurl

[

url :"https://sign.zoho.com/api/v1/requests/[Request id]"

type :GET

headers:headers

];

if(resp.get("status").contains("success"))

{
docStatus = resp.get("requests").get("request_status");

}

Download files associated with the already sent documents:

Once documents have been signed and completed, you can download the signed document and store it in your application or with a CRM record or elsewhere. The downloadDocument deluge task will help you with this. You need to have the request_id of the document to use this task. If there are multiple documents, you will receive a zip file with all the documents through this.

Code:

if(docStatus.contains("completed"))

{

response = zoho.sign.downloadDocument(request_id);

//upload the document to FileUpload field in Zoho Creator

insert into docs[input.FileUpload = response]

}

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohosign.com