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:
- For each document signature request generated through automation using Zoho Sign Deluge tasks, 5 complimentary Zoho Sign credits or Zoho Sign credits will be consumed depending on your Zoho Sign subscription plan. Complimentary credits, proportionate to the number of licensed users, are provided to organizations on a monthly basis in the Enterprise plan.
- If your organization runs out of complimentary credits, then each such subsequent document will consume Zoho Sign credits which need to be purchased as add-ons.
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?
- The Deluge Script Builder provides a drag-and-drop user interface to add Deluge scripts without requiring users to learn and remember Deluge Syntax and functions.
- You can create an application based on your requirements. For example, you could create a recruitment app or an inventory management app .
- In a recruitment app, logic can be used to automate signing tasks for NDA, social media policy, IT services policy, and more.
- For each logic, you can assign a signing task and send out a document for signing to employees.
- Deluge will automate and simplify the whole process for you.
- 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
- Use a Zoho Sign template to send out a document
- Checking the status of already sent documents
- Downloading files associated with the already sent documents
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:
- 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.
- 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.
- Use the getFieldIds task to retrieve the field types and IDs.
- The response will give the field types along with the corresponding field type IDs.
- 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.
- Use the submitRequest task to perform this step.
- 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.
- Get the list of templates in Zoho Sign (optional)
- Get the details of the required Zoho Sign template
- 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:
- 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.
- This will also help you fill in the required Pre-fill fields that are in the template.
- Use the getTemplateById task to fetch the details from the template Id.
- 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]
- }
Access your files securely from anywhere
Zoho CRM Training Programs
Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.
Zoho DataPrep Personalized Demo
If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.
- Zoho Workerly Home
- Forums
- Connect With Us:
- Zoho Recruit Home
- Forums
- Connect With Us:
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.
New to Zoho Survey?
Zoho Sheet Resources
Zoho Forms Resources
New to Zoho Sign?
Zoho Sign Resources
Sign, Paperless!
New to Zoho TeamInbox?
Zoho TeamInbox Resources
New to Zoho ZeptoMail?
Zoho DataPrep Resources
Design. Discuss. Deliver.
New to Zoho Workerly?
New to Zoho Recruit?
New to Zoho CRM?
New to Zoho Projects?
New to Zoho Sprints?
New to Zoho Assist?
New to Bigin?
Related Articles
Witness signing
Available in all paid plans Witness signing is a procedure involving a witness to observe the document signing and proceed to sign the same document to confirm they witnessed the document signing. Witness signing helps in verifying the document's ...Signing documents from SMS and email
In addition to signing documents directly from the Zoho Sign dashboard, recipients can also access documents from their email inbox and their SMS inbox. Signing documents from email From your email inbox, click the email that contains the document ...Signing documents in bulk in Zoho Sign
Available only in Enterprise Edition The bulk sign option allows the signer to sign multiple documents in one go for the documents that have been created within the same organization, given that all the documents that are to be signed have repetitive ...Sign Creator Integration
Scenario: I have an NDA document that needs to be sent to all the visitors who are attending an event. Is it possible to send the document using templates, and also track the status of those documents through Zoho Creator? For this scenario, we will ...Zoho Sign integration with Pipedrive
Available only in Enterprise edition Zoho Sign now integrates with Pipedrive, customer relationship management software that helps small and medium businesses to manage their sales pipeline. This integration can help sales team to directly send ...
New to Zoho LandingPage?
Zoho LandingPage Resources