Automate Signing Tasks in Zoho Creator with 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:
  1. 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.
  2. 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?
  1. 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.
  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
  1. Sending a document for signature
  2. Use a Zoho Sign template to send out a document
  3. Checking the status of already sent documents
  4. 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:
  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: 
  1. file = getUrl(<path to file>);
  2. res = zoho.sign.uploadDocument(file);
  3. [OR]
  4. 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:
  1. fieldIds = zoho.sign.getFieldIds();
  2. fieldTypes = fieldIds.get("field_types");
  3. fields = Map();
  4. for each field in fieldTypes
  5. {
  6. fieldJson = field.toMap();
  7. fields.put(fieldJson.get("field_type_name"), fieldJson.get("field_type_id"));
  8. }

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: 
  1. actionMap = Map();
  2. actionMap.put("request_name","test_AddFields");
  3. textFields = List();
  4. textField1 = Map();
  5. textField1.put("field_name", "Company");
  6. textField1.put("is_mandatory", "true");
  7. textField1.put("field_type_id", fields.get("Company"));
  8. textField1.put("document_id", doc_id);
  9. textFields.add(textField1);
  10. fieldMap = Map();
  11. fieldMap.put("fields",{"text_fields":textFields});
  12. fieldMap.put("recipient_name", "John");
  13. fieldMap.put("recipient_email","john@zylker.com");
  14. fieldMap.put("action_type","SIGN");
  15. fieldList= List();
  16. fieldList.add(fieldMap);
  17. actionMap.put("actions",fieldList);
  18. submitMap = Map();
  19. submitMap.put("requests", actionMap);
  20. 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: 
  1. response= zoho.sign.getTemplates();
  2. {
  3. "code": 0,
  4. "message": "Template list retrieved successfully",
  5. "page_context": {
  6. "sort_column": "template_name",
  7. "has_more_rows": false,
  8. "start_index": 1,
  9. "total_count": 1,
  10. "sort_order": "ASC",
  11. "row_count": 1
  12. },
  13. "templates": [
  14. "{\"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\":\"\"}]}"
  15. ],
  16. "status": "success"
  17. }
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:
  1. {
  2.    "code": 0,
  3.    "message": "Template list retrieved successfully",
  4.    "page_context": {
  5.       "sort_column": "template_name",
  6.       "has_more_rows": false,
  7.       "start_index": 1,
  8.       "total_count": 1,
  9.       "sort_order": "ASC",
  10.       "row_count": 1
  11.    },
  12.    "templates": [
  13.       "{\"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\":\"\"}]}"
  14.    ],
  15.    "status": "success"
  16. }
  17. {

Code:
  1. template_id = <your template id>;
  2. response = zoho.sign.getTemplateById(template_id);
  3. prefill_fields = List();
  4. if(response.get("status")contains("success"))
  5. {
  6. recipients = response.get("templates").get("actions");
  7. document_fields = response.get("templates").get("document_fields");
  8. for each document in document_fields
  9. {
  10. prefill_fields.addall(document.get("fields"));
  11. }
  12. }

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.
  1. actions: a List containing the details of all the roles associated with the template. Each action Map needs to contain:
  2. recipient_name - name of the recipient
  3. recipient_email - the email id of the recipient
  4. action_id - the value of actions_id returned in the actions array for the previous getTemplateById result
  5. role - The role name specified in the template
  6. action_type - SIGN/VIEW whether the person is a signer or receives a copy - as specified in the template
  7. field_data - contains the data of the pre fill fields added to the template
  8. 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
  9. 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
  10. 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.
  1. actionMap = Map();
  2. fieldTextData = Map();
  3. fieldTextData.put("TextField_1", "Document to Review");
  4. actionMap.put("field_data",{"field_text_data":fieldTextData});
  5. eachActionMap1 = Map();
  6. eachActionMap1.put("recipient_name","James");
  7. eachActionMap1.put("recipient_email","james@zoho.com");
  8. eachActionMap1.put("action_type","SIGN");
  9. eachActionMap1.put("action_id","32076000000002014");
  10. eachActionMap1.put("role","Reviewer");
  11. eachActionMap1.put("verify_recipient","false");
  12. eachActionMap2 = Map();
  13. eachActionMap2.put("recipient_name","Tony");
  14. eachActionMap2.put("recipient_email","tony@zoho.com");
  15. eachActionMap2.put("action_type","SIGN");
  16. eachActionMap2.put("action_id","32076000000014006");
  17. eachActionMap2.put("role","Manager");
  18. eachActionMap2.put("verify_recipient","false");
  19. fieldList = List();
  20. fieldList.add(eachActionMap1);
  21. fieldList.add(eachActionMap2);
  22. actionMap.put("actions",fieldList);
  23. submitMap = Map();
  24. submitMap.put("templates",actionMap);
  25. parameters = Map();
  26. parameters.put("is_quicksend","true");
  27. parameters.put("data",submitMap);
  28. 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:
  1. {
  2. "code": 0,
  3. "requests":
  4. {
  5. "request_status": "inprogress",
  6. "notes": "Hi\nA note\nMr. Tester\nHow ar eyouuu ?",
  7. "owner_id": "2000000002002",
  8. "description": "",
  9. "request_name": "Leave a note test",
  10. "modified_time": 1522746018025,
  11. "action_time": 1522746018310,
  12. "is_deleted": false,
  13. "expiration_days": 1,
  14. "is_sequential": true,
  15. "sign_submitted_time": 1522746018310,
  16. "owner_first_name": "V********",
  17. "sign_percentage": 33.34,
  18. "expire_by": 1522866540000,
  19. "is_expiring": true,
  20. "owner_email": "v******@***.com",
  21. "created_time": 1522746018025,
  22. "document_ids": [
  23. {
  24. "document_name": "Employee NDA.pdf",
  25. "document_size": 26591,
  26. "document_order": "0",
  27. "total_pages": 2,
  28. "document_id": "2000000492171"
  29. }
  30. ],
  31. "self_sign": false,
  32. "in_process": false,
  33. "request_type_name": "Others",
  34. "request_id": "2000000492177",
  35. "request_type_id": "2000000000135",
  36. "owner_last_name": "",
  37. "actions": [
  38. {
  39. "verify_recipient": false,
  40. "action_id": "2000000492180",
  41. "action_type": "SIGN",
  42. "private_notes": "",
  43. "recipient_name": "S**********",
  44. "recipient_email": "s*******@***.com",
  45. "signing_order": 0,
  46. "allow_signing": true,
  47. "action_status": "UNOPENED",
  48. "recipient_phonenumber": "",
  49. "recipient_countrycode": ""
  50. }
  51. ]
  52. },
  53. "message": "Document has been retrieved",
  54. "status": "success"
  55. }
Code:
  1. resp = invokeurl
  2. [
  3. url :"https://sign.zoho.com/api/v1/requests/[Request id]"
  4. type :GET
  5. headers:headers
  6. ];
  7. if(resp.get("status").contains("success"))
  8. {
  9. docStatus = resp.get("requests").get("request_status");
  10. }

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:
  1. if(docStatus.contains("completed"))
  2. {
  3. response = zoho.sign.downloadDocument(request_id);
  4. //upload the document to FileUpload field in Zoho Creator
  5. insert into docs[input.FileUpload = response]
  6. }

    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 CRM Training
        Redefine the way you work
        with Zoho Workplace
        Start your free trial

          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 CRM Training

            Create, share, and deliver

            beautiful slides from anywhere.

            Get Started Now


              Zoho Sign now offers specialized one-on-one training for both administrators and developers.

              BOOK A SESSION










                                        Zoho Pagesense Resources

                                            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.


                                              Zoho Survey Resources
                                                Features
                                                Survey Templates
                                                Integrations
                                                Community
                                                iOS Mobile Surveys
                                                Pricing
                                                Android Mobile Surveys
                                                Insurvey Blogs
                                                Insight Blogs
                                                Tips & Tricks


                                                Manage your brands on social media
                                                Access Zoho Social


                                                  Zoho Desk Resources

                                                  • Desk Community Learning Series


                                                  • Digest


                                                  • Functions


                                                  • Meetups


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner


                                                  • Word of the Day


                                                    Zoho Marketing Automation

                                                      Zoho Sheet Resources

                                                       

                                                          Zoho Forms Resources


                                                            Features

                                                            Form Templates

                                                            Customers

                                                            Mobile Forms

                                                            Pricing

                                                            Integrations

                                                            Blogs

                                                            Ebooks

                                                            Tips & Tricks

                                                            Community

                                                            Terms of Use

                                                            Secure your business
                                                            communication with Zoho Mail
                                                            Get started


                                                            Mail on the move with
                                                            Zoho Mail mobile application
                                                            Go Mobile

                                                              Stay on top of your schedule
                                                              at all times
                                                              Get started


                                                              Carry your calendar with you
                                                              Anytime, anywhere
                                                              Get started


                                                                Latest Announcements


                                                                    Zoho Sign Resources

                                                                      What's new
                                                                      Help Guide
                                                                      Solutions Guide
                                                                      API
                                                                      Blogs
                                                                      FAQ's
                                                                      Legal Guide
                                                                      Forums
                                                                      Webinars

                                                                      Sign, Paperless!

                                                                      Sign and send business documents on the go!

                                                                      Get Started Now


                                                                          Zoho SalesIQ Resources


                                                                              Zoho TeamInbox Resources



                                                                                    Latest Feature Updates

                                                                                      Zoho DataPrep Resources



                                                                                        Zoho DataPrep Demo

                                                                                        Get a personalized demo or POC

                                                                                        REGISTER NOW


                                                                                          Design. Discuss. Deliver.

                                                                                          Create visually engaging stories with Zoho Show.

                                                                                          Get Started Now






                                                                                                    Latest Feature Updates



                                                                                                            Latest Feature Updates

                                                                                                              • 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 ...
                                                                                                                Bootcamp
                                                                                                                Community
                                                                                                                Pricing
                                                                                                                Webinars
                                                                                                                What's New
                                                                                                                Integrations
                                                                                                                Contact Support
                                                                                                                Contact Sales
                                                                                                                Wherever you are is as good as
                                                                                                                your workplace
                                                                                                                Workplace on mobile

                                                                                                                  Resources

                                                                                                                  Videos

                                                                                                                  Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                                                                                  eBooks

                                                                                                                  Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                                                                                  Webinars

                                                                                                                  Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                                                                                  CRM Tips

                                                                                                                  Make the most of Zoho CRM with these useful tips.



                                                                                                                    Zoho Show Resources