eSignLive for Microsoft Dynamics CRM v2 - …...1.4 Overview for Integrators Version 2.1 of eSignLive for Microsoft Dynamics CRM supports eSignLive for Microsoft Dynamics CRM online.

NOTE: This PDF is no longer being maintained. For the latest updates, please refer to our Community Portal.

eSignLive for Microsoft Dynamics CRMIntegrator's GuideDate: January 28, 2020

Product Release: 2.1

https://community.onespan.com/documentation/onespan-sign

Copyright Notices

Copyright © 2019 OneSpan North America, Inc. All rights reserved.

Trademarks

OneSpan™, DIGIPASS® and CRONTO® are registered or unregistered trademarks of OneSpan North America Inc. and/or OneSpan International GmbH (collectively "OneSpan") in the U.S. and other countries.

OneSpan reserves all rights to the trademarks, service marks and logos of OneSpan and its subsidiaries.

All other trademarks or trade names are the property of their respective owners.

Intellectual Property

OneSpan Software, documents and related materials (“Materials”) contain proprietary and confidential information. All title, rights and interest in OneSpan Software and Materials, updates and upgrades thereof, including software rights, copyrights, patent rights, industrial design rights, trade secret rights, sui generis database rights, and all other intellectual and industrial property rights, vest exclusively in OneSpan or its licensors. No OneSpan Software or Materials may be downloaded, copied, transferred, disclosed, reproduced, redistributed, or transmitted in any form or by any means, elec-tronic, mechanical or otherwise, for any commercial or production purpose, except as otherwise marked or when expressly permitted by OneSpan in writing.

Disclaimer

OneSpan accepts no liability for the accuracy, completeness, or timeliness of content, or for the reliability of links to and content of external or third party websites or materials.

OneSpan shall have no liability under any circumstances for any loss, damage, or expense incurred by you, your com-pany, or any third party arising from the use or inability to use OneSpan Software or Materials, or any third party mater-ial made available or downloadable. OneSpan will not be liable in relation to any loss/damage caused by modification of these Legal Notices or content.

Reservation

OneSpan reserves the right to modify these Notices and the content at any time. OneSpan likewise reserves the right to withdraw or revoke consent or otherwise prohibit use of the OneSpan Software or Materials if such use does not con-form to the terms of any written agreement between OneSpan and you, or other applicable terms that OneSpan pub-lishes from time to time.

Contact us

Phone: 1-855-MYESIGNe-Mail: [email protected] Support: https://www.esignlive.com/customer-supportResource center: https://www.esignlive.com/resource-centerCompany Website: https://www.onespan.com

Date: January 28, 2020

https://www.esignlive.com/customer-support

https://www.esignlive.com/resource-center

https://www.onespan.com/

CONTENTS

1 Introduction 1

1.1 Document Purpose 2

1.2 Document Audience 3

1.3 Document Organization 4

1.4 Overview for Integrators 5

1.5 Using the eSignLive for Microsoft Dynamics CRM API 6

2 Creating Packages Programmatically 7

2.1 Creating a Custom Button on a CRM Form 9

2.2 Creating a Custom Button on the Ribbon 16

2.3 Adding a Document to a Package 19

2.4 Adding a Convention to a Package 23

2.5 Sending a Package Automatically 25

3 Automation Using OneSpan Sign Conventions 26

3.1 Positioning OneSpan Sign Fields via Text Tags 28

3.2 Auto-Populating Data via Field Mappings 39

3.3 Auto-Populating Fields 46

4 Using Custom Entities 52

4.1 Creating a Package Using a Custom Entity 53

4.2 Adding a Sub-Grid to Display Associated Packages 56

eSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

iii

5 Obtaining OneSpan Sign Package Status Notifications 59

5.1 Setting Up Notifications 60

5.2 Actions Triggered by a New Notification 62

6 Support for the API 63

6.1 Connecting to an Organization 65

6.2 Creating a Record 66

6.3 Updating a Record 67

6.4 Deleting a Record 68

6.5 Associating an Entity Record to Another 69

7 Modifying the Site Map Menu 70

7.1 XML Content 73

8 HTML Example 75

eSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

iv

1 Introduction

This page discusses the following introductory topics:

l Document Purpose on page 2

l Document Audience on page 3

l Document Organization on page 4

l Overview for Integrators on page 5

l Using the eSignLive for Microsoft Dynamics CRM API on page 6

1 IntroductioneSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

1

1.1 Document PurposeThis guide describes how to integrate version 2.1 of eSignLive for Microsoft Dynam-ics CRM with eSignLive for Microsoft Dynamics CRM.

Specifically, the guide describes how to: (1) execute certain actions pro-grammatically; (2) customize eSignLive for Microsoft Dynamics CRM for your envir-onment.


2

1.2 Document AudienceThis document's intended audience is:

l eSignLive for Microsoft Dynamics CRM Administrators, or advanced users who have a detailed knowledge of the setup and advanced configuration abilities of eSignLive for Microsoft Dynamics CRM

l eSignLive for Microsoft Dynamics CRM developers who are comfortable with JavaScript, and who want to develop customizations using the automation abil-ities of the eSignLive for Microsoft Dynamics CRM API.


3

1.3 Document OrganizationThe other main sections of this guide discuss:

l Creating Packages Programmatically on page 7

l Automation Using OneSpan Sign Conventions on page 26

l Using Custom Entities on page 52

l Obtaining OneSpan Sign Package Status Notifications on page 59

l Support for the API on page 63

l Modifying the Site Map Menu on page 70

l HTML Example on page 75


4

1.4 Overview for IntegratorsVersion 2.1 of eSignLive for Microsoft Dynamics CRM supports eSignLive for Microsoft Dynamics CRM online.

OneSpan Signfor eSignLive for Microsoft Dynamics CRM v2.1 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 eSignLive for Microsoft Dynamics CRM, etc.


5

1.5 Using the eSignLive for Microsoft Dynamics CRM API

All entities for eSignLive for Microsoft Dynamics CRM v2.1 can be modified using the eSignLive for Microsoft Dynamics CRM API.

That API can be accessed through the organization service "http://{dynamics url}/{organization}/organization.svc".

Integrators can use the API to perform the following operations:

l Create, update, and delete Convention records

l Create, update, and delete new Signer Label records

l Create, update, and delete new Text Tag records

l Associate Conventions to Templates

l Associate Conventions to Packages

l Associate Signer Labels to Signers within a Package or Template

l Create, update, and delete Field Mapping records

l Enable or disable auto-prepare settings for a Package or a Template

l Enable or disable insert settings for a Package or a Template

l Activate or deactivate Conventions

For more information, please consult the eSignLive for Microsoft Dynamics CRM API website.


6

https://msdn.microsoft.com/en-ca/library/mt593051.aspx


2 Creating Packages Programmatically

OneSpan Signfor Dynamics CRMcan automate the preparation ofOneSpan Signpackages 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 https://-technet.microsoft.com/en-us/library/dn531171.aspx.

2 Creating Packages ProgrammaticallyeSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

7

https://technet.microsoft.com/en-us/library/dn531171.aspx

https://technet.microsoft.com/en-us/library/dn531171.aspx

After you've satisfied the above prerequisite, you can create a Custom Button in either of the following ways:

l Creating a Custom Button on a CRM Form on page 9

l Creating a Custom Button on the Ribbon on page 16

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:

l Adding a Document to a Package on page 19

l Adding a Convention to a Package on page 23

l Sending a Package Automatically on page 25


8

2.1 Creating a Custom Button on a CRM FormTo create a Custom Button on a CRM form, perform the following steps:

l Step 1: Create the Source HTML and JavaScript on page 9

l Step 2: Import the Web Resource into Dynamics 365 on page 10

l Step 3: Insert the Web Resource into an Entity Form on page 11

2.1.1 Step 1: Create the Source HTML and JavaScript

NOTE: The HTML Example on page 75 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 but-ton'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" type="text/javascript"></script>

2. JQuery v 2.1.1 – This version is included with Dynamics 2.1.1.

<script src="../../esl_/scripts/jquery.js" type="text/javascript"></script>

3. Module to support XrmServiceToolkit. https://www.nu-get.org/packages/json2/1.0.2.

<script src="../../esl_/scripts/json.js" type="text/javascript"></script>

4. XrmServiceToolkit is a JavaScript library that can be used for JavaScript Devel-opment under the platform for eSignLive for Microsoft Dynamics CRM


9

https://www.nuget.org/packages/json2/1.0.2

https://www.nuget.org/packages/json2/1.0.2

2013/2015 environments. See: https://xrmservicetoolkit.codeplex.com/. The dependencies are: JQuery and json2.

<script src="../../esl_/scripts/XrmServiceToolkit.js" type="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.

2.1.2 Step 2: Import the Web Resource into Dynamics 365After 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 eSignLive for 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.


10

https://xrmservicetoolkit.codeplex.com/

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 75) and click Choose File.

5. Click Save and then Publish. The Web Resource becomes available to the entire system.

2.1.3 Step 3: Insert the Web Resource into an Entity FormAfter 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 eSignLive for Microsoft Dynamics CRM menu, select Settings > Customizations > Customize the System.

2. From the side menu of the Solution window, select the entity form to cus-tomize, e.g. Entities > Account > Forms.

3. Click New > Main Form.


11

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.


12

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 10.

8. Complete the Name and Label fields.

9. If the HTML Example on page 75 sample was used, the following buttons are inserted at the top of the form:

l Clicking Create creates a package. If a primary contact is assigned to the account, it will be added to the package as a signer.


13

l Clicking Create2 also creates a package. The code attempts to find a saved template named template01.

NOTE:

l To decrease the volume of JavaScript, this example uses jQuery. For more information, see jQuery's online documentation.

l In the above example, the library XrmServiceToolkit.js helps shorten the JavaScript code. This library can be updated.

l If you want to add animation, or to block the User Interface during the code's execution, use the following code:

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.


14

///</summary> var $div = $("#containerLoadingProgress"); if ($div.length === 0) { $div = parent.$("#containerLoadingProgress"); } $div.hide(); };


15

2.2 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: https://www.develop1.net/public/rwb/ribbonworkbench.aspx.

2.2.1 PrerequisitesWhen you are creating the relevant JavaScript code, the following libraries are recommended to help shorten the code's volume:

l esl_/scripts/jquery.js

l esl_/scripts/json.js

l 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.

2.2.2 ActionTo create a Custom Button on the ribbon:

1. From the Ribbon Workbench 2016 menu, click Customization. The following window appears.


16

https://msdn.microsoft.com/en-us/library/gg309639.aspx

https://msdn.microsoft.com/en-us/library/gg309639.aspx

https://www.develop1.net/public/rwb/ribbonworkbench.aspx

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 cus-tomized Javascript code.

6. This field will call parameters to pass to this function.


17


18

2.3 Adding a Document to a Package

NOTE: OneSpan Sign supports the following types of documents:

l Adobe's Portable Document Format (*.pdf)

l Microsoft Word (*.doc or *.docx)

l Open Office (*.odt)

l Text (.txt)

l Rich Text Format (.rtf)

CAUTION: Please be aware of the following:

l The maximum size of a single document is 16 MB. The only exceptions concern our Salesforce and Microsoft SharePoint connectors, whose maximum is 5 MB per doc-ument. Smaller documents yield better performance — we recommend under 5 MB per document.

l If you enable email delivery while configuring a recipient, documents that are lar-ger than 5 MB will not be added as attachments to the email.

l OneSpan will not provide Technical Support for a transaction or transaction tem-plate that has more than 10 documents.

l Document file names should not contain any of the following comma-separated characters: *, /, \, :, <, >, |, ?, ".

l A document's name cannot contain the string esigned.

l Uploading password-protected or corrupted documents will trigger an error.

l PDFs added to a transaction must not have syntax errors. We strongly recommend that you scan a PDF for syntax errors before you add it to a transaction (e.g., by


19

using Adobe's Preflight tool).

l PDFs with the NeedAppearances flag set to true are not currently supported.

If you want to add a document to a package, the following code can be: (1) added to the sample; (2) invoked when required.

//// 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() {


20

/// 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, 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 >> alert(e0.message); }, false);


21

}, function (e0) { ///Handle any errors, for example >> alert(e0.message); }, false); }


22

2.4 Adding a Convention to a PackageIf 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 = { 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


23

//// 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); }


24

2.5 Sending a Package AutomaticallyIf 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, "esl_plugincommandSet", function (data) { //Handle succerss // 'data' would contain an json object of type 'esl_plugincommand' }, function (e) { //Handle error 'e' }, true); }


25

3 Automation Using OneSpan Sign Conventions

An OneSpan Sign convention is defined by the fact that it contains one or more of the following types of objects:

l Text Tags — A Text Tag is an object that can insert a OneSpan Sign field (e.g., Street Address) at particular positions in multiple documents for multiple sign-ers.

l Field Mappings — A Field Mapping is an object that enables the following fea-tures:

l Insert — This feature copies a value of a eSignLive for Microsoft Dynamics CRM field (e.g., Street Address) into a corresponding field of a OneSpan Sign 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 eSignLive for Microsoft Dynamics CRM "related entity".

NOTE: The relevant OneSpan Sign field must exist before you can insert a eSignLive for Microsoft Dynamics CRM value into it. You can create the required OneSpan Sign field by using a Text Tag.

l Writeback — This feature copies a value of a OneSpan Sign field (e.g., Street Address) into a corresponding eSignLive for Microsoft Dynamics CRM field. Using it, data entered by signers during the Signing Ceremony can be written back into eSignLive for Microsoft Dynamics CRM fields,

3 Automation Using OneSpan Sign ConventionseSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

26

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 OneSpan Sign Template Admin per-missions.

OneSpan Sign Conventions can be used to perform the following kinds of tasks:

l Positioning OneSpan Sign Fields via Text Tags on page 28

l Auto-Populating Data via Field Mappings on page 39

l Auto-Populating Fields on page 46


27

3.1 Positioning OneSpan Sign Fields via Text TagsA selected Convention's Text Tag can be used to insert a OneSpan Sign field at par-ticular positions in multiple documents for multiple signers.

In fact, three types of Text Tags can be used for this purpose:

l Prerequisites on page 29

l Positioning Fields at Static Positions on page 33

l Positioning Fields via Text Anchors on page 35

CAUTION: 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 OneSpan Sign package created with that label could be corrupted.


28

CAUTION: When a Text Tag inserts an object in a document, that object overwrites and thus obscures any preexisting content in that place.

3.1.1 Positioning Fields via PDF Form FieldsThe following procedure illustrates how to use the PDF Form Field Text Tag to insert OneSpan Sign fields in multiple documents for multiple signers.

Prerequisites

l The PDF Form Fields already have fixed positions in the relevant PDF (OneSpan Sign fields will be placed in those PDF Form Fields).

Action

To use PDF Form Fields to insert a OneSpan Sign 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 +.

4. In the New OneSpan Sign Signer Label page, provide a Signer Label name.

5. Click Save.

6. Click the active name to create a Text Tag in the Signer Label.


29

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.


30

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.


31

11. Create a new OneSpan Sign 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 cre-ated 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.


32

3.1.2 Positioning Fields at Static PositionsThe following procedure illustrates how to use the Static Position Text Tag to insert OneSpan Sign fields at static positions (fixed X-Y coordinates) in multiple doc-uments for multiple signers.

To insert a OneSpan Sign field at a static position in multiple documents for mul-tiple signers:




4. Click Save.


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 OneSpan Sign 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 OneSpan Sign field to be created.


11. Click Save.



33

13. In the Convention section of Advanced Options, click Lookup and choose the previously created Convention.



NOTE: If at this step you choose the Signer Label created above, the field cre-ated above will appear for that signer.

16. Click Prepare to see the Designer. Verify that the field defined in the Con-vention 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.


34

3.1.3 Positioning Fields via Text AnchorsThe following procedure illustrates how to use the Text Anchor Text Tag to insert OneSpan Sign 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 doc-uments.


35

To use Text Anchors to insert a OneSpan Sign field in multiple documents for two signers:




4. Click Save.


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, OneSpan Sign 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 cal-culate the position.

10. In the Position section, specify a Top Offset and Left Offset for the field's pos-ition 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 OneSpan Sign field.



36

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.



37

18. In the Convention section of Advanced Options, click Lookup and choose the previously created Convention.



NOTE: If at this step you choose the Signer Label created above, the field cre-ated above will appear for that signer.

21. Click Prepare to open the Designer. Verify that the Signature Blocks and sign-ing dates defined above have been properly inserted. You can then close the Designer, and click Send to send the package.


38

3.2 Auto-Populating Data via Field MappingsA Field Mapping is an object that enables the following features:

l Insert - This feature copies a value of a eSignLive for Microsoft Dynamics CRM field (e.g., Street Address) into a corresponding field of a OneSpan Sign doc-ument 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 eSignLive for Microsoft Dynamics CRM "related entity".

NOTE: The relevant OneSpan Sign field must exist before you can insert a eSignLive for Microsoft Dynamics CRM value into it. You can create the required OneSpan Sign field by using a Text Tag.

l Writeback — This feature copies a value of a OneSpan Sign field (e.g., Street Address) into a corresponding eSignLive for Microsoft Dynamics CRM field. Using it, data entered by signers during the Signing Ceremony can be written back into eSignLive for Microsoft Dynamics CRM fields, based on Field Map-pings defined when the package is completed.

NOTE: The Writeback feature is disabled by default.

The rest of this section describes:

l Inserting CRM Signer Data into OneSpan Sign Fields on page 39

l Inserting CRM Related-Entity Data into OneSpan Sign Fields on page 42

l Updating CRM Fields with OneSpan Sign Data (Writeback) on page 44

3.2.1 Inserting CRM Signer Data into OneSpan Sign FieldsThe following procedure illustrates how to insert into OneSpan Sign 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 a OneSpan Sign package the address of a eSignLive for Microsoft Dynamics CRM contact who is also a signer.


39

To insert a CRM contact’s address into a OneSpan Sign package:

Creating a Convention

1. Click the OneSpan Sign 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 OneSpan Sign Document Field Reference section, provide an OneSpan Sign 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 a OneSpan Sign field (e.g., the contact's City).

7. Click Add Field Reference.


40

8. Ensure that the Insert option box is checked when the field is added. This enables the system to insert data from the eSignLive for Microsoft Dynamics CRM entity’s field into the OneSpan Sign 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 a OneSpan Sign 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.


41

The package will be sent. When the package is complete, its signed doc-uments should contain the contact's address. Thanks to this procedure, that address in OneSpan Sign documents will have been auto-populated directly from eSignLive for Microsoft Dynamics CRM.

3.2.2 Inserting CRM Related-Entity Data into OneSpan Sign FieldsThe following procedure illustrates how to insert into OneSpan Sign documents CRM data from a record linked to a OneSpan Sign package entity.

In particular, it describes how to insert an address from an Account record into a OneSpan Sign package.

To insert a eSignLive for Microsoft Dynamics CRM Account’s address into a OneSpan Sign package:

Creating a Convention

1. Click the OneSpan Sign Convention tab.

2. Click New.

3. Enter a name for the new Convention, and then 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 Related Entity.

3. In the OneSpan Sign Document Field Reference section, give the OneSpan Sign 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.


42

8. Ensure that the Insert option box is checked when the field is added. This will enable the system to insert data from the eSignLive for Microsoft Dynamics CRM object’s field into the OneSpan Sign 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 a OneSpan Sign 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 dis-played 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.


43

When the package is complete, its signed documents should contain the Account's address. With this procedure, the address in OneSpan Sign doc-uments will be auto-populated directly from eSignLive for Microsoft Dynamics CRM.

3.2.3 Updating CRM Fields with OneSpan Sign Data (Writeback)A Field Mapping's Write Back feature can update data in eSignLive for Microsoft Dynamics CRM fields from OneSpan Sign documents.

For example, suppose that: (1) a signer notices during the Signing Ceremony that his address is wrong in a OneSpan Sign package document; (2) the signer corrects his address in that document.

If that OneSpan Sign address is mapped to a field of a eSignLive for Microsoft Dynamics CRM related entity, and the Write Back option has been checked for that mapping, when the OneSpan Sign package is complete, the updated address will be written into the eSignLive for Microsoft Dynamics CRM field.

NOTE: The data to be written back into eSignLive for Microsoft Dynamics CRM must be entered during the Signing Ceremony.


44

To update a CRM field with data from a OneSpan Sign document when the asso-ciated package is completed:

1. Select the Write Back option for the associated Field Mapping.

2. When the OneSpan Sign package is complete, verify that the data updated dur-ing the Signing Ceremony appears in the associated eSignLive for Microsoft Dynamics CRM field.


45

3.3 Auto-Populating Fields After an OneSpan Sign 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:

l Position OneSpan Sign fields in multiple documents for multiple signers via Text Tags

l Update OneSpan Sign fields with CRM data via Field Mappings (the Insert fea-ture)

l Update CRM fields with OneSpan Sign data via Field Mappings(the Writeback feature)

The following sections describe how to do these things:

l Updating OneSpan Sign Fields on page 46

l Updating CRM Fields (Writeback) on page 49

3.3.1 Updating OneSpan Sign FieldsThe Insert feature copies a value of a CRM field (e.g., First Name) into a cor-responding field of a OneSpan Sign 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 OneSpan Sign documents with eSignLive for Microsoft Dynamics CRM data:

l Updating OneSpan Sign Fields via the User Interface on page 47

l Updating OneSpan Sign Fields Programmatically on page 48


46

Updating OneSpan Sign Fields via the User Interface

To employ the User Interface to automatically insert data from the eSignLive for Microsoft Dynamics CRM database into an input field in a OneSpan Sign document:

1. Creating a Convention on page 40.

2. Creating a Field Mapping on page 40, and copy its OneSpan Sign 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 OneSpan Sign Field Name.

d. Save the Text Tag.

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 a OneSpan Sign package. On the Advanced Options section, link your Convention to the package.

5. Optionally, select Auto-Prepare with Text Tags.


47

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 eSignLive for Microsoft Dynamics CRM entity defined on the Field Mapping; (3) insert that data into the input field of the OneSpan Sign document.

At the end of this procedure, you should see all inserted eSignLive for Microsoft Dynamics CRM data in the created package.

Updating OneSpan Sign Fields Programmatically

To use a program to automatically insert data from the eSignLive for Microsoft Dynamics CRM database into an input field in a OneSpan Sign document:

1. Write code that will: (a) create the package; (b) attach to the package a suit-able Convention, suitable documents, suitable signers, etc.

NOTE: If your Convention contains Text Tags, fields will automatically be cre-ated and positioned inside OneSpan Sign documents.


48

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 OneSpan Sign Package, or create a Custom Button (for a custom entity) that runs the code. When that button is clicked, you should see all inser-ted eSignLive for Microsoft Dynamics CRM data in the created package.

3.3.2 Updating CRM Fields (Writeback)A Field Mapping's Write Back feature can automatically update data in eSignLive for Microsoft Dynamics CRM fields from OneSpan Sign documents.

For example, suppose that: (1) a signer notices during the Signing Ceremony that his address is wrong in a OneSpan Sign package document; (2) the signer corrects his address in that document.

If that OneSpan Sign address is mapped to a field of a eSignLive for Microsoft Dynamics CRM related entity, and the Write Back option has been checked for that mapping, when the OneSpan Sign package is complete, the updated address is writ-ten into the eSignLive for Microsoft Dynamics CRM field.

There are two ways of updating eSignLive for Microsoft Dynamics CRM fields with data from OneSpan Sign documents:

l Updating CRM Fields via the User Interface on page 50

l Updating CRM Fields Programmatically on page 50

NOTE: For both of these methods, the data to be written back into eSignLive for Microsoft Dynamics CRM must be entered during the Signing Ceremony.


49

Updating CRM Fields via the User Interface

To employ the User Interface to update a eSignLive for Microsoft Dynamics CRM field with data from a OneSpan Sign document when the associated package is completed:

1. Select the Write Back option for the associated Field Mapping.

2. When the OneSpan Sign package is complete, verify that the data updated dur-ing the Signing Ceremony appears in the associated eSignLive for Microsoft Dynamics CRM field.

Updating CRM Fields Programmatically

To use a program to update a CRM field with data from a OneSpan Sign document when the associated package is completed:

1. Write code that will: (a) create the package; (b) attach to the package a suit-able Convention, suitable documents, suitable signers, etc.

NOTE: If your Convention contains Text Tags, fields will automatically be created and positioned inside OneSpan Sign 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 the New OneSpan Sign Package button, or create a Custom Button (for a custom entity) that runs the code. When that button is clicked after the


50

OneSpan Sign package is complete, the data that was updated during the Sign-ing Ceremony will appear in the associated eSignLive for Microsoft Dynamics CRM field.


51

4 Using Custom Entities

eSignLive for Microsoft Dynamics CRM permits users to create specialized Custom Entities.

Administrators can use these entities to perform the following procedures:

l Creating a Package Using a Custom Entity on page 53

l Adding a Sub-Grid to Display Associated Packages on page 56

4 Using Custom EntitieseSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

52

4.1 Creating a Package Using a Custom EntityYou can create a OneSpan Sign 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 a OneSpan Sign package from an existing Custom Entity:

1. Ensure that in your eSignLive for Microsoft Dynamics CRM organization, the Rib-bon Workbench for adding buttons is installed.

2. Log in to eSignLive for 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.


53

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.

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.eSignLive.com.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.


54

The new button becomes available in the Custom Entity, and clicking it will cre-ate a new package.


55

4.2 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 OneSpan Sign packages associated with that entity. If so, perform the following pro-cedure.

To add a package sub-grid to a Custom Entity:

1. Log in to eSignLive for 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 Cus-tom Entity; (2) be unmanaged.

A new page appears.


56

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.


57

9. In the Set Properties panel:

l Type the Schema name for the sub-grid control.

l In the Label field, type the display name of the sub-grid.

10. In the Data Source panel:

l Ensure that records are selected with the Only Related Records option.

l 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:

l Select the Required View from the View Selector options.

l 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.

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


58

5 Obtaining OneSpan Sign Package Status Notifications

Whenever the status of a OneSpan Sign package changes, a notification is sent to eSignLive for Microsoft Dynamics CRM.

This section describes:

l Setting Up Notifications on page 60

l Actions Triggered by a New Notification on page 62

5 Obtaining OneSpan Sign Package Status NotificationseSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

59

5.1 Setting Up NotificationsOneSpan Sign sends a notification regarding package status to subscribed services. The service URL is provided in the Callback URL in the OneSpan Sign Account entity record. The URL provides an exposed service that can be invoked by OneSpan Sign.

Here is an example of the Callback URL: https://eSignLive.comService/PostEvent.svc/PostELSEvent.

To configure eSignLive for Microsoft Dynamics CRM for callback notifications:

1. Specify a suitable Callback URL in the OneSpan Sign Account entity record.

2. Save that record.

3. Click Set Callback URL.

After this step has been performed, OneSpan Sign adds a notification record to the OneSpan Sign Notification entity whenever the status of a OneSpan Sign package changes.


60


61

5.2 Actions Triggered by a New NotificationWhen a new record is added to the OneSpan Sign Notification entity, it triggers the following actions.

l Invoke action: The ESLNotificationPostCreate plugin in the OneSpan Sign.com.Crm.Esl.Connector assembly is executed. It implements the other actions in this list.

l 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 noti-fication record. When a package is completed, a notification with Package_Complete status is added to the eSignLive Notification entity.

l Update signer status: OneSpan Sign 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.

l Upload signed documents to Dynamics CRM : Completed signed documents are uploaded to the eSignLive Package entity of eSignLive for Microsoft Dynam-ics CRM.

TIP: For more information about using eSignLive Notifications in eSignLive for Microsoft Dynamics CRM, see eSignLive Notifications.


62

6 Support for the API

All entities can be modified using the eSignLive for Microsoft Dynamics CRM API. The API in eSignLive for 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:

l Create, update, and delete Convention records

l Create, update, and delete new Signer Label records

l Create, update, and delete new Text Tag records

l Associate Conventions to Templates

l Associate Conventions to Packages

l Associate Signer Labels to Signers within a Package or Template

l Create, update, and delete Field Mapping records

l Enable or disable auto-prepare settings for a Package or a Template

l Enable or disable insert settings for a Package or a Template

l Activate or deactivate Conventions

TIP: For more information, consult the eSignLive for Microsoft Dynamics CRM API website.

This section describes the following:

6 Support for the APIeSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

63



l Connecting to an Organization on page 65

l Creating a Record on page 66

l Updating a Record on page 67

l Deleting a Record on page 68

l Associating an Entity Record to Another on page 69


64

6.1 Connecting to an Organization

Description/Purpose ServiceProxy: Provides an authenticated WCF channel to the organ-ization service

Parameters l Uri: The URI of the organization service

l 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 eSignLive for Microsoft Dynamics CRM has been configured for claims authentication. The parameter value is the URI of the WS-Trust metadata endpoint of the second ADFS instance.

l ClientCredentials: The logon credentials of the client

l 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 spe-cific organization in eSignLive for Microsoft Dynamics CRM.


65

6.2 Creating a Record

Description/Purpose ServiceProxy.Create: Creates a new recordParameters Entity: An entity instance that contains the properties to set in the

newly created record. E.g. Account, Lead, etc.Returned values 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 eSignLive for Microsoft Dynamics CRM.


66

6.3 Updating a Record

Description/Purpose ServiceProxy.Update: Updates an existing entityParameters 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:


67

6.4 Deleting a Record

Description/Purpose ServiceProxy.Delete: Deletes an existing entityParameters 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:


68

6.5 Associating an Entity Record to Another

Description/Purpose ServiceProxy.Associate: Associates an existing entity to anotherParameters 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:


69

7 Modifying the Site Map Menu

By modifying the Site Map menu of eSignLive for Microsoft Dynamics CRM, you can add Entities and OneSpan Sign records to the OneSpan Sign area.

To modify the Site Map menu, do one of the following:

l Install the eslConnectorSiteMap_1_0_0_1.zip package.

CAUTION: By installing this package, your existing Site Map will be over-ridden. Your new Site Map will look as follows, with an OneSpan Sign section:

7 Modifying the Site Map MenueSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

70

l 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 http://m-scrmtools.blogspot.ca/. After downloading, do the following:

i. Open the SiteMap Editor tool.

ii. From the menu, click Manage connections to connect to your organ-ization.

iii. 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.


71

http://mscrmtools.blogspot.ca/

http://mscrmtools.blogspot.ca/

iv. Open the XML file in a text editor. Insert the code from XML Content on page 73 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.

vii. Click Update SiteMap to publish the Site Map on Dynamics 365.

TIP: Refresh your browser to see the changes. A hard refresh (CTRL-F5) may be required.


72

7.1 XML ContentCode

<SubArea Entity="esl_package" Id="esl_package" Description="eSignLive package/transaction" Title="Packages" AvailableOffline="false" PassParams="false"> <Privilege Entity="esl_package" Privilege="Read" /> </SubArea> </Group> <Group Id="eSignLive.com_Settings" Description="eSignLive.com eSignLive Settings" Title="eSignLive Settings" IsProfile="false"> <SubArea Entity="esl_template" Id="esl_template" Description="eSignLive templates" Title="Templates" AvailableOffline="false" PassParams="false"> <Privilege Entity="esl_template" Privilege="Read" /> </SubArea> <SubArea Entity="esl_account" Id="eSignLive_Account" Description="eSignLive Account settings" Title="Account Settings" AvailableOffline="false" PassParams="false"> <Privilege Entity="esl_account" Privilege="Create,Delete,Write" /> </SubArea> <SubArea Entity="esl_language" Id="esl_language" Description="eSignLive Language settings" Title="Language" AvailableOffline="false" PassParams="false"> <Privilege Entity="esl_language" Privilege="Read" /> </SubArea> </Group> <Group Id="Extensions" ResourceId="Group_Extensions"> <SubArea Entity="esl_convention" Id="esl_convention" Description="eSignLive conventions - auto prepare text tags" Title="Conventions" AvailableOffline="false" PassParams="false"> <Privilege Entity="esl_convention" Privilege="Read" /> </SubArea> <SubArea Entity="esl_esignlivenotification" Id="esl_esignlivenotification" Description="eSignlive Notifications" Title="Notifications" AvailableOffline="false" PassParams="false"> <Privilege Entity="esl_esignlivenotification" Privilege="Read" /> </SubArea> <SubArea Entity="esl_plugincommand" Id="esl_command"


73

Description="eSignLive Commands/Actions" Title="Commands" AvailableOffline="false" PassParams="false"> <Privilege Entity="esl_plugincommand" Privilege="Read" /> </SubArea> </Group> </Area>


74

8 HTML Example

You may need to adjust the paths of the src attributes in the <script> and <img> tags of the following example to make them to reflect the location of the associated resource.

For example, suppose a user has saved the resource /WebResources/new_/something.htm. In this case, the relative paths would require the insertion of an extra ../ before each reference. Thus the first reference in the code example below would become:

<script src="../../ClientGlobalContext.js.aspx" type="text/javascript"></script>

TIP: We recommend that integrators favour relative paths over fixed or absolute paths.

TIP: The following example uses minimal error handling. Each integrator should ensure that the code they implement meets the error-handling standards they want to enforce.

<!DOCTYPE html> <html> <head> <title></title> <script src="../ClientGlobalContext.js.aspx" type="text/javascript"></script> <script src="../esl_/scripts/jquery.js" type="text/javascript"></script> <script src="../esl_/scripts/jquery_ui.js"

8 HTML ExampleeSignLive for Microsoft Dynamics CRM v2 - Integrator's Guide

75

type="text/javascript"></script> <script src="../esl_/scripts/json.js" type="text/javascript"></script> <script src="../esl_/scripts/XrmServiceToolkit.js" type="text/javascript"></script> <style> ul { margin: -8px 0 0 0; } li { float: left; display: inline; margin-left: 5px; } </style> </head> <body> <div> <ul> <li><button id="btnCreate"><img src="../esl_/images/PackageCreateIcon.png" height="14" alt="Create Package" /><span>Create</span></button></li> <li><button id="btnCreate2"><img src="../esl_/images/PackageCreateIcon.png" height="14" alt="Create Package with template" /><span>Create2</span></button></li> </ul> </div> <script type="text/javascript"> $(function () { "use strict"; function get (key) { var attr = parent.Xrm.Page.getAttribute(key); return attr.getValue(); }; function failedCall(error) { try { parent.Xrm.Utility.alertDialog(message); } catch (e) { alert(error.message); }


76

} function createOnCrm (item, entitySet, callback) { XrmServiceToolkit.Rest.Create(item, entitySet, function (result1) { if (callback) callback(result1); }, failedCall, false); } function createSoapOnCrm (be, callback) { var result1 = XrmServiceToolkit.Soap.Create(be); if (callback) callback(result1); } function addSignerToPackage (id, s, callback) { XrmServiceToolkit.Rest.Associate( id, "esl_packageSet", s, "esl_signerSet", "esl_package_signer ", function (resp) { callback(resp); }, failedCall, false); } function getTemplateByName (name) { var result1 = { Id: "00000000-0000-0000-000000000000", Name: "", LogicalName: "esl_template" }; XrmServiceToolkit.Rest.RetrieveMultiple( "esl_templateSet",


77

"?$top=1&$select=esl_templateId,esl_name&$filter=esl_name eq '" + name + "'", function (result) { result1.Id = result[0].esl_templateId; result1.Name = result[0].esl_name; }, failedCall, function () {}, false); return result1; } function getPackageSimple (name) { var currentdate = new Date(); return { esl_name: "test-" + name, esl_description: "test " + name + " " + currentdate.toLocaleTimeString(), esl_lookupobjecttype: parent.Xrm.Page.context.getQueryStringParameters().etc, esl_loopkuprecordguid: parent.Xrm.Page.data.entity.getId(), esl_lookuprecordname: name, esl_lookupentitytype: parent.Xrm.Page.data.entity.getEntityName(), }; } function getPackageWithTemplate(name, templatename) { var currentdate = new Date(); var templateRef = getTemplateByName(templatename); return { esl_name: "test-" + name, esl_description: "test " + name + " " + currentdate.toLocaleTimeString(), esl_lookupobjecttype: parent.Xrm.Page.context.getQueryStringParameters().etc, esl_loopkuprecordguid: parent.Xrm.Page.data.entity.getId(),


78

esl_lookuprecordname: name, esl_lookupentitytype: parent.Xrm.Page.data.entity.getEntityName(), esl_basedontemplate: templateRef, }; } function getPrimaryContact(callback) { var primarycontactid = get("primarycontactid"); if (!primarycontactid) return null; var contactRef = primarycontactid[0]; var be = new XrmServiceToolkit.Soap.BusinessEntity("esl_signer", null); be.attributes.esl_name = "Signer1"; be.attributes.esl_signingorder = 2; be.attributes.esl_contactid = { id: contactRef.id, logicalName: contactRef.entityType, name: contactRef.name, type: "EntityReference", }; XrmServiceToolkit.Rest.Retrieve( contactRef.id, "ContactSet", "EMailAddress1,FirstName,LastName,JobTitle,MobilePhone", null, /*expand*/ function (resp) { if (resp) { be.attributes.esl_emailaddress = resp.EMailAddress1; be.attributes.esl_firstname = resp.FirstName; be.attributes.esl_lastname = resp.LastName; be.attributes.esl_title = resp.JobTitle; be.attributes.esl_smsphone = resp.MobilePhone; }


79

callback(be); }, failedCall, false); } function openPackage (packageId) { parent.Xrm.Utility.openEntityForm("esl_package", packageId); } function addSigner(contact, packageId, callback) { if (contact == null) openPackage(packageId); createSoapOnCrm(contact, function (result2) { addSignerToPackage( packageId, result2, function () { callback(packageId); }); }); } function createPackage(eslPackage) { createOnCrm(eslPackage, "esl_packageSet", function(p) { getPrimaryContact( function(contact) { addSigner( contact, p.esl_packageId, function(id) { openPackage(id); }); }); }); } $("#btnCreate").click(function () { var p = getPackageSimple(get("name")); try {


80

createPackage(p); } catch (e) { failedCall(e); } }); $("#btnCreate2").click(function () { var p = getPackageWithTemplate(get("name"), "template01"); try { createPackage(p); } catch (e) { failedCall(e); } }); }); </script> </body> </html>


81