esignlive for Microsoft Dynamics CRM

Transcription

1 esignlive for Microsoft Dynamics CRM Integrator's Guide Product Release: 2.0 Date: March 09, 2018 esignlive 8200 Decarie Blvd, Suite 300 Montreal, Quebec H4P 2P5 Phone: MYESIGN Fax: (514) Web:

2 esignlive Phone: MYESIGN 8200 Decarie Blvd, Suite 300 Fax: (514) Montreal, Quebec H4P 2P5 Canada Remember to visit our Web site at: and our Resource Center at: Silanis Technology Inc. All rights reserved. Information in this document is subject to change without notice, and does not represent a commitment on the part of Silanis Technology. The software and associated files described in this document are furnished under the software license agreement, and can be used or copied only in accordance with the terms of the agreement. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information and retrieval systems, for any purpose other than the purchaser s personal use, without express written permission of Silanis Technology Incorporated. Written and Produced in Canada. Protected by United States patents 5,606,609; 6,751,632; 6,912,660; 6,931,420; 7,340,608; 8,307,218; and 9,665,737; Canadian patents 2,340,780; 2,345,148; and 2,428,665; European patents 1,116,110; 1,153,352; 1,238,321; 1,270,179; 1,376,311; and 1,393,144; and Australian patents AU 2,002,215,782; and AU 2,003,204,747. Patents pending in the United States, Canada, Europe, and other countries. ApproveIt is a registered trademark of Silanis Technology Incorporated in the United States and/or other countries. esignlive, e-witness, e-sign Enterprise, e-sign Desktop, e-vault Manager, Process Reviewer, LCD Tablet Process Navigator, Notification Manager, e-vault Manager Administration Console, e-vault Manager Console, Electronic Evidence, and When e-signatures matter to your business are trademarks of Silanis Technology Incorporated. Excel, Microsoft, Office, Outlook, Windows, Windows NT, and Word are registered trademarks of Microsoft Corporation. Adobe and Acrobat Reader are registered trademarks of Adobe Systems Incorporated. SignatureGem is a trademark of Topaz Systems Incorporated. THE CONTENT AND RELATED GRAPHICS PUBLISHED HEREIN COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. SILANIS TECHNOLOGY RESERVES THE RIGHT TO CHANGE ANY AND ALL INFORMATION CONTAINED HEREIN AT ANY TIME WITHOUT NOTICE.

3 CONTENTS esignlive for Microsoft Dynamics CRM v2.0: Integrator's Guide 1 Introduction 1 Document Purpose 1 Document Audience 1 Document Organization 1 Overview for Integrators 1 Using the Microsoft Dynamics CRM API 2 Creating Packages Programmatically 3 Introduction 3 Creating a Custom Button on a CRM Form 3 Step 1: Create the Source HTML and JavaScript 4 Step 2: Import the Web Resource into Dynamics Step 3: Insert the Web Resource into an Entity Form 5 Creating a Custom Button on the Ribbon 7 Prerequisites 7 Action 8 Adding a Document to a Package 8 Adding a Convention to a Package 10 Sending a Package Automatically 11 Automation Using esignlive Conventions 13 Positioning esignlive Fields via Text Tags 14 Positioning Fields via PDF Form Fields 14 Prerequisites 14 Action 14 Positioning Fields at Static Positions 16 Positioning Fields via Text Anchors 17 Auto-Populating Data via Field Mappings 20 Inserting CRM Signer Data into esignlive Fields 20 Inserting CRM Related-Entity Data into esignlive Fields 21 Updating CRM Fields with esignlive Data (Writeback) 22 Auto-Populating Fields 24 Updating esignlive Fields Silanis Technology Inc. iii

4 Updating esignlive Fields via the User Interface 24 Updating esignlive Fields Programmatically 25 Updating CRM Fields (Writeback) 26 Updating CRM Fields via the User Interface 26 Updating CRM Fields Programmatically 26 Using Custom Entities 28 Creating a Package Using a Custom Entity 28 Adding a Sub-Grid to Display Associated Packages 29 Obtaining esignlive Package Status Notifications 32 Setting Up Notifications 32 Actions Triggered by a New Notification 33 Support for the API 34 Connecting to an Organization 34 Creating a Record 35 Updating a Record 35 Deleting a Record 36 Associating an Entity Record to Another 36 Modifying the Site Map Menu 38 XML Content 39 HTML Example Silanis Technology Inc. iv

5 esignlive for Microsoft Dynamics CRM v2.0: Integrator's Guide Introduction This page discusses the following introductory topics: Document Purpose (below) Document Audience (below) Document Organization (below) Overview for Integrators (below) Using the Microsoft Dynamics CRM API (on the next page) Document Purpose This guide describes how to integrate version 2.0 of esignlive for Microsoft Dynamics CRM with Microsoft Dynamics CRM. Specifically, the guide describes how to: (1) execute certain actions programmatically; (2) customize esignlive for Microsoft Dynamics CRM for your environment. Document Audience This document's intended audience is: Microsoft Dynamics CRM Administrators, or advanced users who have a detailed knowledge of the setup and advanced configuration abilities of Microsoft Dynamics CRM Microsoft Dynamics CRM developers who are comfortable with JavaScript, and who want to develop customizations using the automation abilities of the Microsoft Dynamics CRM API. Document Organization The other main sections of this guide discuss: Creating Packages Programmatically (on page 3) Automation Using esignlive Conventions (on page 13) Using Custom Entities (on page 28) Obtaining esignlive Package Status Notifications (on page 32) Support for the API (on page 34) Modifying the Site Map Menu (on page 38) HTML Example (on page 40) Overview for Integrators Version 2.0 of esignlive for Microsoft Dynamics CRM supports Microsoft Dynamics CRM online. esignlivefor Microsoft Dynamics CRM v2.0 offers the following new feature. Whenever the status of a package changes, esignlive adds a new record to the esignlive Notification entity. This triggers a set of actions that includes updating the package's status in Microsoft Dynamics CRM, etc Silanis Technology Inc. 1

6 Using the Microsoft Dynamics CRM API All entities for esignlive for Microsoft Dynamics CRM v2.0 can be modified using the Microsoft Dynamics CRM API. That API can be accessed through the organization service " url/{organization/organization.svc". Integrators can use the API to perform the following operations: Create, update, and delete Convention records Create, update, and delete new Signer Label records Create, update, and delete new Text Tag records Associate Conventions to Templates Associate Conventions to Packages Associate Signer Labels to Signers within a Package or Template Create, update, and delete Field Mapping records Enable or disable auto-prepare settings for a Package or a Template Enable or disable insert settings for a Package or a Template Activate or deactivate Conventions For more information, please consult the Microsoft Dynamics CRM API website Silanis Technology Inc. 2

7 Creating Packages Programmatically Introduction esignlivefor Dynamics CRMcan automate the preparation ofesignlivepackages via a Custom Button. Before you can create such a button, you must first create a relationship between the relevant package (esl_package) and the source Entity (e.g. an account). TIP: For more about creating relationships, consult Microsoft TechNet at After you've satisfied the above prerequisite, you can create a Custom Button in either of the following ways: Creating a Custom Button on a CRM Form (below) Creating a Custom Button on the Ribbon (on page 7) And after you've created a Custom Button, you may want to take the automation process further by doing one or more of the following: Adding a Document to a Package (on page 8) Adding a Convention to a Package (on page 10) Sending a Package Automatically (on page 11) Creating a Custom Button on a CRM Form To create a Custom Button on a CRM form, perform the following steps: Step 1: Create the Source HTML and JavaScript (on the next page) Step 2: Import the Web Resource into Dynamics 365 (on the next page) Step 3: Insert the Web Resource into an Entity Form (on page 5) Silanis Technology Inc. 3

8 Step 1: Create the Source HTML and JavaScript NOTE: The HTML Example (on page 40) section of this guide provides HTML and JavaScript code that creates two HTML buttons, each of which can be used to create a package using data from an account record. You must first write the required HTML and JavaScript code. This will create the button's visual element as well as its functionality. The following library parameters are required in the JavaScript function form: 1. Dynamics 365 provides script to initialize the client context. <script src="../../clientglobalcontext.js.aspx" typee="text/javascript"></script> 2. JQuery v This version is included with Dynamics <script src="../../esl_/scripts/jquery.js" type="text/javascript"></script> 3. Module to support XrmServiceToolkit. <script src="../../esl_/scripts/json.js" type="text/javascript"></script> 4. XrmServiceToolkit is a JavaScript library that can be used for JavaScript Development under the platform for Microsoft Dynamics CRM 2011/2013/2015 environments. See: The dependencies are: JQuery and json2. <script src="../../esl_/scripts/xrmservicetoolkit.js" typee="text/javascript"></script> Step 4 provides many shortcuts to create JavaScript web requests to Dynamics CRM. You can use JavaScript directly, or you can use jquery.ajax. Use the following code to position two buttons at the top of the web resource: <ul> <li><button id="btncreate"> <img src="../../esl_/images/packagecreateicon.png" alt="create Package" /><span>create</span> </button></li> <li><button id="btncreate2"> <img src="../../esl_/images/packagecreateicon.png" alt="create Package with template" /><span>create2</span> </button></li> </ul> jquery is used to link each button to the appropriate JavaScript function. After the Web Resource is ready, it can be imported and tested in Dynamics 365. Step 2: Import the Web Resource into Dynamics 365 After the code from Step 1 is created, it must be imported as a Web Resource into Dynamics 365 in order to be placed on a CRM form. To import the relevant Web Resource into Dynamics 365: 1. From the Microsoft Dynamics CRM menu, select Settings > Customizations > Customize the System. 2. From the ribbon in the Solution window that appears, select Web Resources from the Newdrop-down menu. 3. In the Web Resource New window, complete the Name field Silanis Technology Inc. 4

9 4. In the Type field, either paste the HTML source that you have written, or select a pre-existing file (e.g. HTML Example (on page 40)) and click Choose File. 5. Click Save and then Publish. The Web Resource becomes available to the entire system. Step 3: Insert the Web Resource into an Entity Form After importing the Web Resource, it must be inserted into an Entity form (in this example, an account). To insert the Web Resource into an Entity form: 1. From the Microsoft Dynamics CRM menu, select Settings > Customizations > Customize the System. 2. From the side menu of the Solution window, select the entity form to customize, e.g. Entities > Account > Forms. 3. Click New > Main Form Silanis Technology Inc. 5

10 4. Click the Insert tab. In this example, a One Column tab was inserted before the Summary Section to ensure the buttons appear at the top of the form. 5. From the Insert tab ribbon, click One Column. A Tab section is created in the Insert pane. 6. From the ribbon, click Web Resource. The Add Web Resource dialog box appears. 7. From the Web Resource field, select the web resource file you created in Step 2: Import the Web Resource into Dynamics 365 (on page 4). 8. Complete the Name and Label fields. 9. If the HTML Example (on page 40) sample was used, the following buttons are inserted at the top of the form: Clicking Create creates a package. If a primary contact is assigned to the account, it will be added to the package as a signer. Clicking Create2 also creates a package. The code attempts to find a saved template named template01. NOTE: To decrease the volume of JavaScript, this example uses jquery. For more information, see jquery's online documentation. In the above example, the library XrmServiceToolkit.js helps shorten the JavaScript code. This library can be updated. If you want to add animation, or to block the User Interface during the code's execution, use the following code: Silanis Technology Inc. 6

11 function ShowProcessing (message) { if (typeof message!= "string") { message = "Working..."; var $div = $("#containerloadingprogress"); if ($div.length === 0) { $div = parent.$("#containerloadingprogress"); var $message = $div.find("#loadingtext"); if ($message.length === 0) { $message = $("<div />", { "id": "loadingtext", "style": "position:absolute;top:58%;left:50%" ); $div.append($message); $message.text(message); $div.show(); ; function HideProcessing () { ///<summary> /// Hide the loader after the preocess is over. ///</summary> var $div = $("#containerloadingprogress"); if ($div.length === 0) { $div = parent.$("#containerloadingprogress"); $div.hide(); ; Creating a Custom Button on the Ribbon TIP: (1) Information about customizing the ribbon can be found in the Customize commands and the ribbon section of Microsoft's online library; (2) you can also use a third-party extension, such as the Ribbon Workbench 2016 extension from develop1: Prerequisites When you are creating the relevant JavaScript code, the following libraries are recommended to help shorten the code's volume: esl_/scripts/jquery.js esl_/scripts/json.js esl_/scripts/xrmservicetoolkit.js If you are using the suggested Ribbon Workbench 2016 application, you can create a solution that contains the entity with which to associate the action button Silanis Technology Inc. 7

12 Action To create a Custom Button on the ribbon: 1. From the Ribbon Workbench 2016 menu, click Customization. The following window appears. 2. From the Toolbox menu, click and drag the Button icon to the Form section of the top menu. 3. In the Properties: Control pane, complete the fields. The value entered in the Label field is mirrored by the Button icon. 4. From the Form section of the top menu, click New. The Actions window appears. 5. Complete the fields with the parameters listed in the prerequisites above. The Custom Javascript Action field can be completed with your company's customized Javascript code. 6. This field will call parameters to pass to this function. Adding a Document to a Package WARNING: The system supports a maximum of: (1) 150 pages per document; (2) 10 MB per document (for better performance, we recommend under 5 MB per document). If you want to add a document to a package, the following code can be: (1) added to the sample; (2) invoked when required Silanis Technology Inc. 8

13 //// Use this function to retrieve a list of notes for the current record. //// //// parameters: //// packageid : package to link to //// note : json object //// { //// id: "guid of the note", //// name: "text to display, should be the filename" //// function querycrmrelateddocuments(id) { var select = "?$top- =100&$select=AnnotationId,Subject,FileName,FileSize,ModifiedOn,OwnerId,ObjectId&$expand=OwnerId,ObjectId"; select += "&$filter=objectid/id eq guid'" + id + "' and IsDocument eq true"; var list = []; XrmServiceToolkit.Rest.RetrieveMultiple("AnnotationSet", select, function(results) { $(results).each(function(index, data) { list.push({ "name": data.filename, "id": data.annotationid ); ); //Now the list is populated, you can call 'addnotetopackage', function(e) { //Handle errors, function() { /// handle when done, like hiding "busy" animation, true); //// Use this function to bind an existing note/attachment to a package. //// //// parameters: //// packageid : package to link to //// note : json object //// { //// id: "guid of the note", //// name: "text to display, should be the filename" //// function addnotetopackage(packageid, note) { var document0 = { esl_name: note.name, esl_description: note.name, Silanis Technology Inc. 9

14 ; esl_documentorder: 0, esl_filename: "note://" + note.id XrmServiceToolkit.Rest.Create( document0, "esl_documentset", function (result) { XrmServiceToolkit.Rest.Associate( packageid, "esl_packageset", result.documentid, "esl_documentset", "esl_package_document", function () { ///Handle success, function (e0) { ///Handle any errors, for example >>, false); alert(e0.message);, function (e0) { ///Handle any errors, for example >>, false); alert(e0.message); Adding a Convention to a Package If you want to add a Convention to a package, the following code can be: (1) added to the sample; (2) invoked when required. //// Use this function retrieve a convention of CRM. //// //// parameters: //// name : name of convention to lookup //// successcallback : function(data) { which expect to receive a convention data //// { //// id: convention id, //// name: name of the convention, //// function getconventionbyname(name, successcallback) { XrmServiceToolkit.Rest.RetrieveMultiple( "esl_conventionset", "?$top=1&$select=esl_conventionid,esl_name&$filter=esl_name eq '" + name + "'", function (result) { var convention = { Silanis Technology Inc. 10

15 ; id: result[0].esl_conventionid, name: result[0].esl_name // Handle success successcallback(convention);, function(e) { //Handle any errors, function () {, true); Then adding the convention to the package using this function: //// Use this function to bind an existing note/attachment to a package. //// //// parameters: //// packageid : package to link to //// note : json object //// { //// id: "guid of the note", //// name: "text to display, should be the filename" //// function addconventiontopackage(packageid, conventionid) { XrmServiceToolkit.Rest.Associate( conventionid, "esl_conventionset", packageid, "esl_packageset", "esl_convention_package", function () { ///Handle success, function (e0) { ///Handle any errors, for example >> alert(e0.message);, false); Sending a Package Automatically If you want to send a package automatically, the following code can be: (1) added to the sample; (2) invoked when required. function SendPackage (packageid) { var crmobject = { esl_request: "SendPackage", esl_parameter1: packageid // the package Id is required ; XrmServiceToolkit.Rest.Create(crmObject, Silanis Technology Inc. 11

16 "esl_plugincommandset", function (data) { //Handle succerss // 'data' would contain an json object of type 'esl_plugincommand', function (e) { //Handle error 'e', true); Silanis Technology Inc. 12

17 Automation Using esignlive Conventions An esignlive is defined by the fact that it contains one or more of the following types of objects: Text Tags A Text Tag is an object that can insert an esignlive field (e.g., Street Address) at particular positions in multiple documents for multiple signers. Field Mappings A Field Mapping is an object that enables the following features: o Insert This feature copies a value of a Microsoft Dynamics CRM field (e.g., Street Address) into a corresponding field of an esignlive document when a package is being prepared. That data can then be retrieved from the signed document. The data in question can be either data about a signer, or data about a Microsoft Dynamics CRM "related entity". NOTE: The relevant esignlive field must exist before you can insert a Microsoft Dynamics CRM value into it. You can create the required esignlive field by using a Text Tag. o Writeback This feature copies a value of an esignlive field (e.g., Street Address) into a corresponding Microsoft Dynamics CRM field. Using it, data entered by signers during the Signing Ceremony can be written back into Microsoft Dynamics CRM fields, based on Field Mappings defined when the package is completed. NOTE: The Writeback feature is disabled by default. A Convention can be defined by users with esignlive Template Admin permissions. esignlive Conventions can be used to perform the following kinds of tasks: Positioning esignlive Fields via Text Tags (on the next page) Auto-Populating Data via Field Mappings (on page 20) Auto-Populating Fields (on page 24) Silanis Technology Inc. 13

18 Positioning esignlive Fields via Text Tags A selected Convention's Text Tag can be used to insert an esignlive field at particular positions in multiple documents for multiple signers. In fact, three types of Text Tags can be used for this purpose: Prerequisites (below) Positioning Fields at Static Positions (on page 16) Positioning Fields via Text Anchors (on page 17) WARNING: Before creating any of the above Text-Tag types, ensure that each Signer Label has at least one Text Tag of type Signature (Full Name, Initials, Capture, or Mobile Capture). If a Signer Label doesn t have any Text Tags, the esignlive package created with that label could be corrupted. Positioning Fields via PDF Form Fields The following procedure illustrates how to use the PDF Form Field Text Tag to insert esignlive fields in multiple documents for multiple signers. Prerequisites The PDF Form Fields already have fixed positions in the relevant PDF (esignlive fields will be placed in those PDF Form Fields). Action To use PDF Form Fields to insert an esignlive field in multiple documents for multiple signers: 1. Verify that the relevant PDF document has at least one PDF Form Field. 2. Create a new Convention, and save it. 3. In the Signer Label section of Convention Details, click In the New esignlive Signer Label page, provide a Signer Label name Silanis Technology Inc. 14

19 5. Click Save. 6. Click the active name to create a Text Tag in the Signer Label. 7. In the Text Tag section, select PDF Form Field from the drop-down list. 8. If needed, modify the Text Tag name, and complete the Form Field Name. 9. In the Text Tag Details section, select the Output Field type from the drop-down list (e.g., signature, auto-fill signed date, input text field). 10. Click Save Silanis Technology Inc. 15

20 11. Create a new esignlive package. 12. In the Convention section of Advanced Options, click Lookup and choose the previously created Convention. 13. Add documents and signers to the package. 14. Double-click each signer, and assign a Signer Label to each signer from the Lookup option. NOTE: If at this step you choose a Signer Label created above, the field created above will appear for that signer. 15. Click Prepare to open the Designer. Verify that the signature and signing date defined above have been properly inserted at the positions of the pre-existing PDF Form Fields. You can then close the Designer, and click Send to send the package. Positioning Fields at Static Positions The following procedure illustrates how to use the Static Position Text Tag to insert esignlive fields at static positions (fixed X-Y coordinates) in multiple documents for multiple signers. To insert an esignlive field at a static position in multiple documents for multiple signers: 1. Create a new Convention, and save it. 2. In the Signer Label section of Convention Details, click In the New esignlive Signer Label page, provide a Signer Label name. 4. Click Save. 5. Click the active name to create a Text Tag in the Signer Label. 6. In the Text Tag section, select Static Position from the drop-down list, and give the Text Tag a name. 7. Type values for the Text Tag's Top Offset and Left Offset. NOTE: This step specifies the field's fixed position on a page. The next step specifies the page on which the esignlive field will appear. 8. Specify the Page number on which the Text Tag should appear. NOTE: Pages are counted sequentially from the first to the last document in the package. 9. Specify the Width and Height of the esignlive field to be created. 10. In the Text Tag Details section, select the Output Field type from the drop-down list (e.g., signature, auto-fill signed date, input text field). 11. Click Save Silanis Technology Inc. 16

21 12. Create a new esignlive package. 13. In the Convention section of Advanced Options, click Lookup and choose the previously created Convention. 14. Add documents and signers to the package. 15. Double-click each signer, and assign a Signer Label to each signer from the Lookup option. NOTE: If at this step you choose the Signer Label created above, the field created above will appear for that signer. 16. Click Prepare to see the Designer. Verify that the field defined in the Convention has been inserted properly in each document for each relevant signer. After you're satisfied with the results, you can close the Designer, and then click Send to send the package. Positioning Fields via Text Anchors The following procedure illustrates how to use the Text Anchor Text Tag to insert esignlive fields in multiple documents for multiple signers. Fields will be inserted at the positions of the Text Anchors. TIP: Text Anchors are available for both Microsoft Word documents and PDF documents. To use Text Anchors to insert an esignlive field in multiple documents for two signers: 1. Create a new Convention, and save it. 2. In the Signer Label section of Convention Details, click In the New esignlive Signer Label page, provide a Signer Label name. 4. Click Save. 5. Click the active name to create a Text Tag in the Signer Label Silanis Technology Inc. 17

22 6. In the Text Tag section, select Text Anchor from the drop-down list, and give the Text Tag a name. 7. In the Text Anchor Details section, complete the Text field with the exact string to be searched for in the uploaded documents. NOTE: If the exact text string cannot be found in an uploaded document, esignlive will trigger an error and then delete the document from the package. 8. Add the Character Index within the Text Anchor. It will be used to calculate the position of the field. 9. Add the Occurrence of the search string. For example, a value of 2 will skip the first two occurrences of the anchor text, and use the third occurrence to calculate the position. 10. In the Position section, specify a Top Offset and Left Offset for the field's position relative to the relevant anchor text. Each offset can be positive, negative, or zero. 11. In the Field Dimension section, specify the Width and Height of the desired esignlive field. 12. In the Text Tag Details section, select the Output Field type from the drop-down list (e.g., signature, auto-fill signed date, input text field). 13. Click Save. 14. Repeat Steps 3-13 for the second signer. The following image illustrates how the resultant Signature Blocks may appear at the end of this procedure. 15. Create another Text Anchor for the signing date, with the Text Anchor being the first occurrence of DATE. 16. Create a Signer Label for the second signer, and within it create two Text Tags. The first is for the signature, using WITNESS SIGNATURE as the anchor text. The second is for the signing date, using the second occurrence of DATE. 17. Create a new esignlive package. 18. In the Convention section of Advanced Options, click Lookup and choose the previously created Convention. 19. Add documents and signers to the package Silanis Technology Inc. 18

23 20. Double-click each signer, and assign a Signer Label to each signer from the Lookup option. NOTE: If at this step you choose the Signer Label created above, the field created above will appear for that signer. 21. Click Prepare to open the Designer. Verify that the Signature Blocks and signing dates defined above have been properly inserted. You can then close the Designer, and click Send to send the package Silanis Technology Inc. 19

24 Auto-Populating Data via Field Mappings A Field Mapping is an object that enables the following features: Insert - This feature copies a value of a Microsoft Dynamics CRM field (e.g., Street Address) into a corresponding field of an esignlive document when a package is being prepared. That data can then be retrieved from the signed document. The data in question can be either data about a signer, or data about a Microsoft Dynamics CRM "related entity". NOTE: The relevant esignlive field must exist before you can insert a Microsoft Dynamics CRM value into it. You can create the required esignlive field by using a Text Tag. Writeback This feature copies a value of an esignlive field (e.g., Street Address) into a corresponding Microsoft Dynamics CRM field. Using it, data entered by signers during the Signing Ceremony can be written back into Microsoft Dynamics CRM fields, based on Field Mappings defined when the package is completed. NOTE: The Writeback feature is disabled by default. The rest of this section describes: Inserting CRM Signer Data into esignlive Fields (below) Inserting CRM Related-Entity Data into esignlive Fields (on the next page) Updating CRM Fields with esignlive Data (Writeback) (on page 22) Inserting CRM Signer Data into esignlive Fields The following procedure illustrates how to insert into esignlive documents CRM data from a signer's record (e.g., data about a CRM user, contact, or lead). In particular, it describes how to insert into an esignlive package the address of a Microsoft Dynamics CRM contact who is also a signer. To insert a CRM contact s address into an esignlive package: Creating a Convention 1. Click the esignlive Convention tab. 2. Click New. 3. Enter a name for the new Convention, and click Save. Creating a Field Mapping 1. On the Field Mapping related list, click +, and give a name to the mapping. 2. In the Mapping Type drop-down list, select Signer. 3. In the esignlive Document Field Reference section, provide an esignlive Field Name. 4. Click Save. 5. On the Dynamics CRM Entity Field section, choose the desired entity. In this case, the entity is Contact. A list of the contact s fields appears on the right. 6. Choose the field to be mapped to an esignlive field (e.g., the contact's City) Silanis Technology Inc. 20

25 7. Click Add Field Reference. 8. Ensure that the Insert option box is checked when the field is added. This enables the system to insert data from the Microsoft Dynamics CRM entity s field into the esignlive documents. 9. Click Save to save the field mapping. 10. Repeat Steps 5-9 to create a new field mapping for each address field (City, Zip Code, etc.). 11. Click Activate. Creating and Auto-Populating a Package 1. Create an esignlive package (giving it a name). 2. Click Save. 3. Optionally, choose Account as Related Object Type. 4. In the Convention section of Advanced Options, click Lookup and choose the Convention created previously 5. Add documents to the package, and add the contact as a signer. 6. Click Prepare. The Designer appears in a dialog box. 7. Add a Signature Block for the contact. 8. To display more options, click the gear icon on the right side of the Signature Block. Then click the + sign to add fields. 9. The list of available fields appears. Click text field to add a text field. 10. To display more options, click the gear icon on the right side of the text field. Then click Settings to see the field settings. 11. Give a name to the Convention Field Names, which are displayed on the left side of the Designer. Then click Save. 12. Repeat Steps 7-11 for each of the Convention's fields. 13. When finished, close the overlay and click Send. The package will be sent. When the package is complete, its signed documents should contain the contact's address. Thanks to this procedure, that address in esignlive documents will have been auto-populated directly from Microsoft Dynamics CRM. Inserting CRM Related-Entity Data into esignlive Fields The following procedure illustrates how to insert into esignlive documents CRM data from a record linked to an esignlive package entity. In particular, it describes how to insert an address from an Account record into an esignlive package. To insert a Microsoft Dynamics CRM Account s address into an esignlive package: Creating a Convention 1. Click the esignlive Convention tab. 2. Click New. 3. Enter a name for the new Convention, and then click Save Silanis Technology Inc. 21

26 Creating a Field Mapping 1. On the Field Mapping related list, click +, and give a name to the mapping. 2. In the Mapping Type drop-down list, select Related Entity. 3. In the esignlive Document Field Reference section, give the esignlive field name. 4. Click Save. 5. In the Dynamics CRM Entity Field section, choose the desired object. In this case, the entity is Account. A list of the Account s fields appears to the right. 6. Choose the field to be mapped (e.g., the Account's City). 7. Click Add Field Reference. 8. Ensure that the Insert option box is checked when the field is added. This will enable the system to insert data from the Microsoft Dynamics CRM object s field into the esignlive documents. 9. Click Save to save the field mapping. 10. Repeat Steps 5-9 to create a new field mapping for each address field (City, Zip Code, etc.). 11. Click Activate. Creating and Auto-Populating a Package 1. Create an esignlive package (giving it a name). 2. Click Save. 3. From the Related Entity drop-down menu, select Account. 4. Click Lookup to choose the Account record 5. In the Convention section of Advanced Options, click Lookup and choose the Convention created previously. 6. Add documents to the package, and add signers to the package. 7. Click Prepare. The Designer page appears. Add your Signature Blocks. 8. To display more options, click the gear icon on the right side of the Signature Block. Then click the + sign to add fields. 9. Click Settings to see the field settings. The list of available fields appears. 10. Click Text Field to add a text field. 11. To display more options, click the gear icon on the right side of the text field. 12. Type the name of the desired Convention field name. These field names are displayed on the left side of the overlay. Then click Save. 13. Repeat Steps 9-12 for each Convention field. 14. Close the Designer. Then click Send to send the package. When the package is complete, its signed documents should contain the Account's address. With this procedure, the address in esignlive documents will be auto-populated directly from Microsoft Dynamics CRM. Updating CRM Fields with esignlive Data (Writeback) A Field Mapping's Write Back feature can update data in Microsoft Dynamics CRM fields from esignlive documents Silanis Technology Inc. 22

27 For example, suppose that: (1) a signer notices during the Signing Ceremony that his address is wrong in an esignlive package document; (2) the signer corrects his address in that document. If that esignlive address is mapped to a field of a Microsoft Dynamics CRM related entity, and the Write Back option has been checked for that mapping, when the esignlive package is complete, the updated address will be written into the Microsoft Dynamics CRM field. NOTE: The data to be written back into Microsoft Dynamics CRM must be entered during the Signing Ceremony. To update a CRM field with data from an esignlive document when the associated package is completed: 1. Select the Write Back option for the associated Field Mapping. 2. When the esignlive package is complete, verify that the data updated during the Signing Ceremony appears in the associated Microsoft Dynamics CRM field Silanis Technology Inc. 23

28 Auto-Populating Fields After an esignlive Convention has been defined, users who create packages manually can use the Convention to automate certain tasks. Instead of having to perform those tasks manually, having them performed automatically saves users time. Specifically, users can automatically: Position esignlive fields in multiple documents for multiple signers via Text Tags Update esignlive fields with CRM data via Field Mappings (the Insert feature) Update CRM fields with esignlive data via Field Mappings(the Writeback feature) The following sections describe how to do these things: Updating esignlive Fields (below) Updating CRM Fields (Writeback) (on page 26) Updating esignlive Fields The Insert feature copies a value of a CRM field (e.g., First Name) into a corresponding field of an esignlive document when a package is being prepared. That data can then be retrieved from the signed document. The data in question can be either data about a signer, or data about a CRM "related entity". There are two ways of auto-populating esignlive documents with Microsoft Dynamics CRM data: Updating esignlive Fields via the User Interface (below) Updating esignlive Fields Programmatically (on the next page) Updating esignlive Fields via the User Interface To employ the User Interface to automatically insert data from the Microsoft Dynamics CRM database into an input field in an esignlive document: 1. Creating a Convention (on page 20). 2. Creating a Field Mapping (on page 20), and copy its esignlive Field Name into a buffer. 3. Create a Signer Label, and under this label create two Text Tags as follows: a. Create a Text Tag of type Signature. b. Still under that label, create a second Text Tag of type Input Text Field. Additional options appear. c. Paste the name copied in Step 2 into the esignlive Field Name. d. Save the Text Tag Silanis Technology Inc. 24

29 The Convention automatically creates a Signature Block, and attaches input text to this block. The Convention then retrieves the data from the CRM entity's field that was defined in the Field Mapping, and inserts it in the input field. 4. To use your new Convention, create an esignlive package. On the Advanced Options section, link your Convention to the package. 5. Optionally, select Auto-Prepare with Text Tags. 6. Add documents and signers to the package, and assign a Signer Label to each signer. 7. If you didn't select Auto-Prepare with Text Tags above, click Prepare to prepare the package. 8. When finished, click Send. The application will then: (1) create both a Signature Block and an input field attached to that block; (2) retrieve the data from the field of the Microsoft Dynamics CRM entity defined on the Field Mapping; (3) insert that data into the input field of the esignlive document. At the end of this procedure, you should see all inserted Microsoft Dynamics CRM data in the created package. Updating esignlive Fields Programmatically To use a program to automatically insert data from the Microsoft Dynamics CRM database into an input field in an esignlive document: 1. Write code that will: (a) create the package; (b) attach to the package a suitable Convention, suitable documents, suitable signers, etc. NOTE: If your Convention contains Text Tags, fields will automatically be created and positioned inside esignlive documents. 2. Add the following JavaScript code to the esl_packageparametersettings Web resource file. Your code should resemble the following example: <Package> <autoprepare="true"> <insert="true"> <template="my-template"> <writeback="true"> <autosend="true"> <inpersonsigning="true"> <reviewaftercompletion="true"> <enforcesigningorder="true"> </Package> 3. Click New esignlive Package, or create a Custom Button (for a custom entity) that runs the code. When that button is clicked, you should see all inserted Microsoft Dynamics CRM data in the created package Silanis Technology Inc. 25

30 Updating CRM Fields (Writeback) A Field Mapping's Write Back feature can automatically update data in Microsoft Dynamics CRM fields from esignlive documents. For example, suppose that: (1) a signer notices during the Signing Ceremony that his address is wrong in an esignlive package document; (2) the signer corrects his address in that document. If that esignlive address is mapped to a field of a Microsoft Dynamics CRM related entity, and the Write Back option has been checked for that mapping, when the esignlive package is complete, the updated address is written into the Microsoft Dynamics CRM field. There are two ways of updating Microsoft Dynamics CRM fields with data from esignlive documents: Updating CRM Fields via the User Interface (below) Updating CRM Fields Programmatically (below) NOTE: For both of these methods, the data to be written back into Microsoft Dynamics CRM must be entered during the Signing Ceremony. Updating CRM Fields via the User Interface To employ the User Interface to update a Microsoft Dynamics CRM field with data from an esignlive document when the associated package is completed: 1. Select the Write Back option for the associated Field Mapping. 2. When the esignlive package is complete, verify that the data updated during the Signing Ceremony appears in the associated Microsoft Dynamics CRM field. Updating CRM Fields Programmatically To use a program to update a CRM field with data from an esignlive document when the associated package is completed: 1. Write code that will: (a) create the package; (b) attach to the package a suitable Convention, suitable documents, suitable signers, etc. NOTE: If your Convention contains Text Tags, fields will automatically be created and positioned inside esignlive documents. 2. Add the following JavaScript code to the esl_packageparametersettings Web resource file. Your code should resemble the following example: <Package> <autoprepare="true"> <insert="true"> <template="my-template"> <writeback="true"autosend="true"> <inpersonsigning="true"> <reviewaftercompletion="true"> <enforcesigningorder="true"> </Package> Silanis Technology Inc. 26

31 3. Click the New esignlive Package button, or create a Custom Button (for a custom entity) that runs the code. When that button is clicked after the esignlive package is complete, the data that was updated during the Signing Ceremony will appear in the associated Microsoft Dynamics CRM field Silanis Technology Inc. 27

32 Using Custom Entities Microsoft Dynamics CRM permits users to create specialized Custom Entities. Administrators can use these entities to perform the following procedures: Creating a Package Using a Custom Entity (below) Adding a Sub-Grid to Display Associated Packages (on the next page) Creating a Package Using a Custom Entity You can create an esignlive package using the record of an existing Custom Entity. The following procedure describes how to do so by adding a button to the Custom Entity. When that button is clicked, the system will create a new package from the Custom Entity record. To create an esignlive package from an existing Custom Entity: 1. Ensure that in your Microsoft Dynamics CRM organization, the Ribbon Workbench for adding buttons is installed. 2. Log in to Microsoft Dynamics CRM as an Administrator. 3. Navigate to Settings > Customization. A new page appears. 4. Click Ribbon WorkBench. 5. Select the unmanaged solution that contains your Custom Entity, and click OK. A new page appears. 6. Select the Custom Entity from the ENTITIES list. The upper part of the screen may change. 7. In the Solution Elements tab, right-click Commands, and then click Add New Silanis Technology Inc. 28

33 8. Under Actions, click the search icon, and then click Add. 9. Select Javascript Function Action as the rule, and click OK. 10. Enter SDK.Silanis.Automation.CreatePackage in the Function Name field. 11. Click the search button in the Library field. 12. Select the esignlive Package Automation Web resource, and click OK. 13. Under Actions, click OK. 14. In the Toolbox section, click Button, then drag and drop it to the Form ribbon. 15. Specify esl.account.command0.command as the Command, and provide an Id and Label Text. The Label Text you specify will appear on your new button in the Form ribbon. 16. Click Publish. The new button becomes available in the Custom Entity, and clicking it will create a new package. Adding a Sub-Grid to Display Associated Packages You may want to add a package sub-grid to a Custom Entity in order to display the esignlive packages associated with that entity. If so, perform the following procedure. To add a package sub-grid to a Custom Entity: 1. Log in to Microsoft Dynamics CRM as an Administrator. 2. Navigate to Settings > Customization. A new page appears. 3. Click either Customize the System or Solutions. NOTE: If you click Solutions, the solution you select must: (1) contain your Custom Entity; (2) be unmanaged. A new page appears Silanis Technology Inc. 29

34 4. From the menu, expand Entities, and select the relevant Custom Entity. 5. Select Forms. 6. Double-click the form where you want to add the sub-grid. A new page appears. 7. From the top menu, click the Insert tab. 8. Select the Sub-Grid option. A new dialog box appears. 9. In the Set Properties panel: Type the Schema name for the sub-grid control. In the Label field, type the display name of the sub-grid. 10. In the Data Source panel: Ensure that records are selected with the Only Related Records option. The views related to the Custom Entity are displayed under the Entity drop-down list. Select the esignlivepackages view. 11. In the Additional Options panel: Select the Required View from the View Selector options. Select the Off option in the View Selector. 12. Click Set. The sub-grid is added to the form's tab location (see Step 7). 13. Click the Home tab, and then click Save Silanis Technology Inc. 30

35 14. Click Publish. A package sub-grid is added to the Custom Entity's form (see Step 6) Silanis Technology Inc. 31

36 Obtaining esignlive Package Status Notifications Whenever the status of an esignlive package changes, a notification is sent to Microsoft Dynamics CRM. This section describes: Setting Up Notifications (below) Actions Triggered by a New Notification (on the next page) Setting Up Notifications esignlive sends a notification regarding package status to subscribed services. The service URL is provided in the Callback URL in the esignlive Account entity record. The URL provides an exposed service that can be invoked by esignlive. Here is an example of the Callback URL: To configure Microsoft Dynamics CRM for callback notifications: 1. Specify a suitable Callback URL in the esignlive Account entity record. 2. Save that record. 3. Click Set Callback URL. After this step has been performed, esignlive adds a notification record to the esignlive Notification entity whenever the status of an esignlive package changes Silanis Technology Inc. 32

37 Actions Triggered by a New Notification When a new record is added to the esignlive Notification entity, it triggers the following actions. Invoke action: The ESLNotificationPostCreate plugin in the Silanis.Crm.Esl.Connector assembly is executed. It implements the other actions in this list. Update package status: In the record of the Dynamic CRM esignlive Package entity, the status of the package is updated from the Status field in the notification record. When a package is completed, a notification with Package_Complete status is added to the esignlive Notification entity. Update signer status: esignlive obtains the status of each signer in the package, and then updates: (1) the package's Signer Status field; (2) each signer s Signer Status field. Upload signed documents to Dynamics CRM and SharePoint: Completed signed documents are uploaded to the esignlive Package entity of Microsoft Dynamics CRM (and to Microsoft SharePoint, if SharePoint is enabled). TIP: For more information about using esignlive Notifications in Microsoft Dynamics CRM, see esignlive Notifications Silanis Technology Inc. 33

38 Support for the API All entities can be modified using the Microsoft Dynamics CRM API. The API in Microsoft Dynamics CRM can be accessed through the organization service called organization.svc. By navigating to Settings > Customizations > Developer Resources, integrators can use the API to perform the following operations: Create, update, and delete Convention records Create, update, and delete new Signer Label records Create, update, and delete new Text Tag records Associate Conventions to Templates Associate Conventions to Packages Associate Signer Labels to Signers within a Package or Template Create, update, and delete Field Mapping records Enable or disable auto-prepare settings for a Package or a Template Enable or disable insert settings for a Package or a Template Activate or deactivate Conventions TIP: For more information, consult the Microsoft Dynamics CRM API website. This section describes the following: Connecting to an Organization (below) Creating a Record (on the next page) Updating a Record (on the next page) Deleting a Record (on page 36) Associating an Entity Record to Another (on page 36) Connecting to an Organization Description/Purpose ServiceProxy: Provides an authenticated WCF channel to the organization service Parameters Uri: The URI of the organization service HomeRealmUri: This parameter is set to a non-null value when a second ADFS instance is configured as an identity provider to the ADFS instance to which Microsoft Dynamics CRM 2011 has been configured for claims authentication. The parameter value is the URI of the WS-Trust metadata endpoint of the second ADFS instance. ClientCredentials: The logon credentials of the client DeviceCredentials: The Windows Live ID device credentials. Returned values URI of the organization service Refer to the following code snippet for the connection setup. This connects to a specific organization in Microsoft Dynamics CRM Silanis Technology Inc. 34

39 Creating a Record Description/Purpose Parameters Returned values ServiceProxy.Create: Creates a new record Entity: An entity instance that contains the properties to set in the newly created record. E.g. Account, Lead, etc. GUID of the newly created record To create a new entity record, refer to the following code snippet. Records can be created into any of the entities in Microsoft Dynamics CRM. Updating a Record Description/Purpose Parameters ServiceProxy.Update: Updates an existing entity Entity: An entity instance that contains the properties to set in the newly created record. E.g. Account, Lead, etc. Returned values To update a field value, refer to the following code snippet: Silanis Technology Inc. 35

40 Deleting a Record Description/Purpose Parameters ServiceProxy.Delete: Deletes an existing entity Entity: An entity instance that contains the properties to set in the newly created record. E.g. Account, Lead, etc. GUID: The GUID of the record to delete. Returned values To delete a record in an entity, refer to the following code snippet: Associating an Entity Record to Another Description/Purpose Parameters ServiceProxy.Associate: Associates an existing entity to another Entity: An entity instance that contains the properties to set in the newly created record. E.g. Account, Lead, etc. GUID: The GUID of the record to delete. Relationship: The name of the relationship to be used to create the link. EntityReferenceCollection: A collection of entity references (to records) to be associated. Returned values To associate one entity record to another, refer to the following code snippet: Silanis Technology Inc. 36

41 esignlive for Microsoft Dynamics CRM v2.0: Integrator's Guide Silanis Technology Inc. 37

42 Modifying the Site Map Menu By modifying the Site Map menu of esignlive for Microsoft Dynamics CRM, you can add Entities and esignlive records to the esignlive area. To modify the Site Map menu, do one of the following: Install the eslconnectorsitemap_1_0_0_1.zip package. WARNING: By installing this package, your existing Site Map will be overridden. Your new Site Map will look as follows, with an esignlive section: For more customization options, you can use the SiteMap Editor tool, which is a plugin that is part of the XrmToolBox. It can be downloaded at After downloading, do the following: i. Open the SiteMap Editor tool. ii. iii. From the menu, click Manage connections to connect to your organization. After connecting, from the menu click Load SiteMap, and then click Save SiteMap. This saves your current Site Map to an XML file, which can serve as a backup. iv. Open the XML file in a text editor. Insert the code from XML Content (on the next page) to where you want the section to appear in the Site Map. v. Click Save. vi. Click Open SiteMap to reload the file. Any text or description can also be updated Silanis Technology Inc. 38