esignlive for microsoft dynamics crm v2 - deployment guide · to install version 2 of esignlive for...

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

eSignLive for Microsoft Dynamics CRMDeployment Guide Date: 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 About This Document 1

1.1 Released Files 2

1.2 Software Requirements 3

1.3 Additional Requirements 4

2 Installing the Solution 5

2.1 Prerequisites 6

2.2 Action 7

3 Configuring the Solution 9

3.1 Configuring Microsoft Azure 10

3.2 Specifying Account Information 15

3.3 Specifying a Language 19

3.4 Specifying User Permissions 20

4 Upgrading the Solution from 1.1 to 2.1 21

4.1 Importing the New Solution 22

4.2 Specifying Account Settings 23

4.3 Completing the Upgrade 24

4.4 Reinstalling the Push Notification Service 26

eSignLive Microsoft Dynamics CRM v2 -Deployment Guide

iii

5 Deploying the Push Notification Service for eSignLive for Microsoft Dynamics CRM 2.1 27

5.1 Installing the Push Notification Service 28

5.2 Verifying the Push Notification Service 33

5.3 Uninstalling the Push Notification Service 37

6 Uninstalling the Solution 38

7 Troubleshooting 39

eSignLive Microsoft Dynamics CRM v2 -Deployment Guide

iv

1 About This Document

This guide describes how to deploy eSignLive for Microsoft Dynamics CRM. In par-ticular, it discusses:

l Installing the Solution on page 5

l Configuring the Solution on page 9

l Upgrading the Solution from 1.1 to 2.1 on page 21

l Deploying the Push Notification Service for eSignLive for Microsoft Dynamics CRM 2.1 on page 27

l Uninstalling the Solution on page 38

l Troubleshooting on page 39

After you install the product, you can learn how to use it by consulting the eSignLive for Microsoft Dynamics CRM: User's Guide.

NOTE: The screen captures in these documents come from eSignLive for Microsoft Dynamics CRM 2016 Update 1(8.1) on-premises.

1 About This DocumenteSignLive Microsoft Dynamics CRM v2 -Deployment Guide

1

http://docs.esignlive.com/content/resources/pdfs/esl_for_crm_v2_-_user_s_guide.pdf

http://docs.esignlive.com/content/resources/pdfs/esl_for_crm_v2_-_user_s_guide.pdf

1.1 Released Files l eSignLive for Microsoft Dynamics CRM v2.1

l Download eSignLive for Microsoft Dynamics CRM v2.1 (the solution pack-age)

l eslConnectorSiteMap_1_0_0_X_managed.zip

l PushNotificationService.zip (for on-premises deployments only)


2

1.2 Software RequirementsYou need one of the following third-party applications:

l eSignLive for Microsoft Dynamics CRM 2016 On-Premises (Updated to 8.1.0359 or higher)

l Microsoft Dynamics 365 Update (8.2) online


3

1.3 Additional RequirementsThe person performing the deployment must have:

l Deployment Administrator rights for eSignLive for Microsoft Dynamics CRM

l A Sandbox or Production account for version 11 of OneSpan Sign, and an asso-ciated API Key

For SharePoint Integration (on-premises only):

l SharePoint and Dynamics CRM should be on the same domain and network.

l Dynamics CRM users must have at least READ and WRITE permissions on all relevant SharePoint sites.


4

2 Installing the Solution

This section describes how to install version 2 of eSignLive for Microsoft Dynamics CRM.

2 Installing the SolutioneSignLive Microsoft Dynamics CRM v2 -Deployment Guide

5

2.1 Prerequisites l You have a Sandbox or Production account for version 11 of OneSpan Sign, and

an associated API Key.

To get a free Sandbox account, follow the instructions on this page.

l You have Administrator privileges for eSignLive for Microsoft Dynamics CRM.

l If you are installing the connector on an on-premises instance of Dynamics CRM, you have performed the procedure Installing the Push Notification Ser-vice.


6

https://www.esignlive.com/products/edition-and-pricing/sign-up-for-e-signlive/free-trial

2.2 ActionTo install version 2 of eSignLive for Microsoft Dynamics CRM:

1. Log into Microsoft Dynamics CRM as a user with Administrator privileges.

2. Navigate to Microsoft Dynamics CRM > Settings.

3. In the Customization group, click Solutions.

4. In the All Solutions window, click Import.

You are prompted for the location of the solution package.

5. Click Browse, and select the file Download OneSpan Sign for Microsoft Dynam-ics v2.0 Release Candidate (Solution Package).

6. Click Next to display the Solution Information.

7. Click Next to display the Import Options.


7

8. Select the check box under Post Import Actions, then click Import. The solu-tion is imported, and a summary page appears. After a certain delay, a message should state that the import was successful.

9. Click Close.

10. Click Publish All Customizations. This ensures that eSignLive for Microsoft Dynamics CRM online will be aware of all data changes that affect the User Interface.

11. Repeat steps 4 through 10 for the eslConnectorSiteMap file.

NOTE: To complete your installation, you must configure the solution.


8

3 Configuring the Solution

After you have installed the solution, you should configure it by performing the fol-lowing procedures:

l Configuring Microsoft Azure on page 10

l Specifying Account Information on page 15

l Specifying a Language on page 19

l Specifying User Permissions on page 20

3 Configuring the SolutioneSignLive Microsoft Dynamics CRM v2 -Deployment Guide

9

3.1 Configuring Microsoft Azure

Prerequisites

l You must have Administrator privileges for Microsoft Azure.

Action

To configure Microsoft Azure for eSignLive for Microsoft Dynamics CRM to authen-ticate OneSpan Sign for Callback notifications:

1. Log into https://portal.azure.com as a user with Administrator privileges.

2. From the menu, select Azure Active Directory.

3. From the active menu, select App registrations.

4. In the App registrations pane, click the name of the relevant application (e.g., OneSpan Sign).

5. If you have not previously configured the connector:

a. In the App registrations pane, click New application registration. The Create window appears.


10

https://portal.azure.com/

b. Complete the Name field.

c. From the Application type drop-down menu, select Native.

d. Specify the following Redirect URI:

https://<DOMAIN_NAME>/connectors/api/v2/authorization/oauth2/dynamicscrm/<ORGANIZATION_NAME>

In the above URI:

l Replace the variable <Domain_Name> with the string in the following table that corresponds to your environment.

Sandbox Production

US Customers sandbox.esignlive.com apps.esignlive.comCandadian Cus-tomers

sandbox.e-signlive.ca apps.e-signlive.ca

Australian Cus-tomers

apps.esignlive.com.au

European Cus-tomers

apps.esignlive.eu

l Replace the variable <ORGANIZATION_NAME>. To find the right replace-ment, log in to eSignLive for Microsoft Dynamics CRM by clicking the


11

Avatar icon in the top menu. Your organization name begins with "org" (although those characters and others have been erased from the following image).

e. Click Create.

6. If you have previously configured the connector:

a. Click the OneSpan Sign application (the name previously configured in the Active Directory). The Application ID is your client ID.

b. Specify a Redirect URI, using the information in Step 5d above.


12

7. Click Save. A Successfully updated application message appears.

8. In the Settings pane, click Required Permissions.

9. Ensure that the following permissions are selected in the Required Permissions pane:

l Dynamics CRM Online (Microsoft.CRM)

l Windows Azure Active Directory (Microsoft.Azure.ActiveDirectory)


13

10. If these permissions are not displayed:

a. Click Add from the Required permissions menu.

b. From the Required permissions pane:

i. Select the API for which you wish to grant a permission. The API appears in the Enable Access pane.

ii. Select the option box associated with the permission, and click Save.

11. Click Grant Permissions, and then click Yes in the dialog box that appears.


14

3.2 Specifying Account InformationYour organization should have only one OneSpan Sign account.

To inform eSignLive for Microsoft Dynamics CRM about your OneSpan Sign account:

1. Log into eSignLive for Microsoft Dynamics CRM. You must log in as a user who: (a) has Administrator privileges in Microsoft Dynamics CRM; (b) owns the email address of the OneSpan Sign account. Both these conditions must be met.

2. Navigate to eSignLive for Microsoft Dynamics CRM > OneSpan Sign > Account Settings.

An Active OneSpan Sign Accounts list appears. Initially this list should be empty.

3. From the ribbon, click New to create a new OneSpan Sign account. A new page appears.


15

4. Specify the following General parameters:

l Name: Name of the active OneSpan Sign account

l Maximum Number Of Documents: Maximum number of documents that can be included in a package (default = 10).

l Maximum Document Size: Maximum size (in MB) of a document that can be included in a package (default = 10.0). Note: In the Settings section of the eSignLive for Microsoft Dynamics CRM application, you can set an upper limit to an attachment's file size. That upper limit should be larger than this Maximum Document Size.

l Accepted File Types: A comma-separated list of the types of file that can be added to a package. The default value is doc; docx; pdf; odt; rtf.

l EntitiesWithNotes: Name of the Web resource that contains: (1) the list of entities for the Document Manager; (2) the drop-down menu in the Related Entity section of the Package form.

l Package Name Date Stamp Format: Format of the date stamp appended to the package name. The supported formats can be viewed here. The default value is: yyyy-MMM-dd-H-mm-ss


16

https://msdn.microsoft.com/en-us/library/8kb3ddd4(v=vs.110).aspx

5. Specify the following OneSpan Sign Configuration parameters:

l Email: Email address of the account owner

l API Key: Your OneSpan Sign API key. You can obtain it from our Support Team.

l As mentioned above, you must have a Sandbox account. Accordingly, spe-cify the parameters API URL, Designer URL and Signer URL as follows:

API URL

https://sandbox.eSignLive.com/api

Design-er URL

https://sandbox.eSignLive.com/auth?senderAuthenticatio

nToken=

{0}&target=https://sandbox.eSignLive.com/designer/

{1}?profile=dynamics2.1

Signer URL

https://sandbox.esignlive.com/auth?signerAuthenticatio

nToken=

{0}&target=https://sandbox.esignlive.com/packages/

{1}/sign?iframe=true

l Callback URL: If you have an on-premises deployment, this parameter is the URL of the Push Notification Service, which receives callbacks from OneSpan Sign (for more, see the last step of the procedure Installing the Push Notification Service). If you have an online deployment, enter the fol-lowing value for this parameter: https://server/PostEvent.svc/PostESLEvent

l Client ID: The identification number of the client from Configuring Microsoft Azure. This parameter is relevant only for online installations.

6. Indicate if you want to use SharePoint Integration. If you select 'Yes', specify the following parameters:

7. This section only applies if you are using a on-premises version of Microsoft Dynamics CRM.

a. SharePoint Server Location: select On-Premises if the SharePoint server is available locally; (2) select Online if the SharePoint server is on the Cloud.


17



b. SharePointUser Name: The username employed to access SharePoint. Ensure that the user has access to the SharePoint site/library specified in the parameters SharePoint Documents URL and SharePoint Completed Documents URL below.

c. SharePoint Password: The password for the SharePoint Username.

d. SharePoint Host URL: This parameter is reserved for the future use of SharePoint Online.

e. SharePoint Documents URL: URL of the SharePoint site or library from which documents will be uploaded to eSignLive for Microsoft Dynamics CRM documents from any library in that site. If this URL points to a spe-cific SharePoint library, the system will upload documents only from that library.

f. SharePoint Completed Documents URL: THIS FEATURE IS NOT SUPPORTED IN ESIGNLIVE FOR MICROSOFT DYNAMICS V2.

g. SharePoint Fetch Count: The maximum number of documents fetched while querying a SharePoint site.

8. Click Save or Save and Close.

9. From the ribbon, click Verify Settings to confirm that: (a) the API Key and API URL are correct; (b) communications with the OneSpan Sign server can be established.

10. From the ribbon, click Set Callback URL to register the URL with OneSpan Sign.


18

3.3 Specifying a LanguageTo specify a language for OneSpan Sign transactions:

1. Log into eSignLive for Microsoft Dynamics CRM as a user with Administrator privileges.

2. Navigate to eSignLive for Microsoft Dynamics CRM > OneSpan Sign > Lan-guage. An OneSpan Sign Languages list appears. Initially this list should be empty.

3. Click New to create a new language for OneSpan Sign.

4. Enter the required information (e.g., Name = English, Value = en). You can view all supported languages and their associated values here. You must enter one of those values, though you can specify the name as you wish.

5. Click Save.


19

3.4 Specifying User Permissions

NOTE: To test your installation, at least one user must have the right to create packages or the right to create templates. System Adminstrators always have those rights.

To specify a user's permissions:

1. Log into eSignLive for Microsoft Dynamics CRM as a user with Administrator privileges.

2. Navigate to eSignLive for Microsoft Dynamics CRM > Settings > Security > Users.

3. From the Enabled Users list, double-click the name of the relevant user.

4. Click Manage Roles.

5. Check all and only the boxes next the Roles you want to give the user.

6. Click OK.


20

4 Upgrading the Solution from 1.1 to 2.1

NOTE: This section is relevant only if you have an on-premises deployment of eSignLive for Microsoft Dynamics CRM.

If you want to upgrade an installed 1.1 version of eSignLive for Microsoft Dynamics CRM to the 2.1 version, a eSignLive for Microsoft Dynamics CRM Administrator should sequentially perform the following procedures:.

l Importing the New Solution on page 22

l Specifying Account Settings on page 23

l Completing the Upgrade on page 24

l Reinstalling the Push Notification Service on page 26

4 Upgrading the Solution from 1.1 to 2.1eSignLive Microsoft Dynamics CRM v2 -Deployment Guide

21

4.1 Importing the New SolutionTo import the new solution:

1. Log in to eSignLive for Microsoft Dynamics CRM as a user with Administrator privileges.

2. From the top menu, select eSignLive for Microsoft Dynamics CRM > Settings > Solutions.

3. From the Solutions grid, click Import. You are prompted for the location of the solution package.

4. Click Browse, and select the provided solution package — e.g., Download eSignLive for Microsoft Dynamics CRM v2.1 Release Candidate (Solution Pack-age).

5. Click Next to display solution information. eSignLive for Microsoft Dynamics CRM indicates that there is an update for your currently installed solution.

6. Ensure that: (i) the Maintain customizations (recommended) option is enabled; (ii) you have checked any SDK message processing steps that were included in the solution.

7. Click Next. The solution is imported, and a summary page appears. A warning message may appear that can safely be ignored. The message states that when the solution was imported, the SDK message steps were disabled and then enabled.

8. Click Close.

9. From All Solutions, click Publish All Customizations.

10. Reload the page. The solution should now be the updated version (e.g., 2.1.1.2).


22

4.2 Specifying Account SettingsTo inform eSignLive for Microsoft Dynamics CRM about your OneSpan Sign account:

1. Navigate to eSignLive for Microsoft Dynamics CRM > OneSpan Sign Account.

2. Select your OneSpan Sign account. The OneSpan Sign Account: Information page appears.

3. Specify all parameters appropriately. For more information, see Specifying Account Information on page 15.


23

4.3 Completing the UpgradeTo complete your upgrade to version 2.1 of eSignLive for Microsoft Dynamics CRM:

1. Install the setup file eSignLive.com.Crm.UpgradeService.Setup.msi.

This creates a folder in C:\Program Files (x86)\eSignLive\eSignLive.-com.Crm.UpgradeService.Setup.

2. Open the configuration file eSignLive.com.Crm.UpgradeService.exe.config, and update the CrmLocal settings with your eSignLive for Microsoft Dynamics CRM service user credentials.

NOTE: All variables in the preceding example refer to eSignLive for Microsoft Dynamics CRM.

For example:

<add name="CrmLocal"

connectionString="Url=http://<server>/<organization>; Domain=xxxxxx; Username=xxxxx; Password=xxxx"/>

3. Run the services.msc file from the Start menu. Then select and start the ser-vice name OneSpan Sign Connector Upgrade Service.


24

4. Run the Event viewer, and verify the status of the selected service (e.g., there should not be any error messages).

5. Log in to eSignLive for Microsoft Dynamics CRM, and verify that data has been appropriately updated for existing OneSpan Sign packages. Specifically, all Account and Opportunity drop-down values must be Related Entity fields or Related Record fields.


25

4.4 Reinstalling the Push Notification ServiceTo reinstall the Push Notification Service, see Deploying the Push Notification Ser-vice. Your new service will replace the previous Push Notification Service, but it will use the same port.


26

5 Deploying the Push Notification Service for eSignLive for Microsoft Dynamics CRM 2.1

NOTE: The Push Notification Service is needed only if your connector is installed on an on-premises instance of Dynamics CRM. If you are installing the connector on Dynamics CRM 365, please ignore this section.

NOTE: The deployment instructions below are relevant only if you are using v2.1 of eSignLive for Microsoft Dynamics CRM. If you are using v1.2, click here.

The Push Notification Service:

1. Receives an Event Notification (callback) from OneSpan Sign every time the status of an e-signature process changes;

2. Transmits that information to the relevant connector.

The rest of this section describes:

l Installing the Push Notification Service on page 28

l Verifying the Push Notification Service on page 33

l Uninstalling the Push Notification Service on page 37

5 Deploying the Push Notification Service for eSignLive for Microsoft Dynamics CRM 2.1eSignLive Microsoft Dynamics CRM v2 -Deployment Guide

27

5.1 Installing the Push Notification ServiceTo install the Push Notification Service:

1. Unzip the file PushNotificationService.zip into the folder where you want to install the service.

2. Create an IIS Website by doing the following:

a. Connect to IIS with sufficient privileges.

b. Click Add Web Site. A new dialog box appears.


28

c. Specify the following parameters:

l Site name: You can specify any name you want.

l Physical path: This path should identify the folder where the zip file was unzipped.

l Port: You can specify any port number you want.

d. Click OK.

e. Ensure that the Application Pool version is 4.0 by selecting the Basic Settings of the Application Pool, as illustrated below.


29

3. Edit the file web.config as follows:

a. Update the connectionString in the "<add name="CrmLocal" con-nectionString="....">" section of the file.

b. Update the following parameters:

l URL: The URL of your eSignLive for Microsoft Dynamics CRM organization (e.g., http://hostname:8888/Dynamics2015)

l Domain: The domain name


30

l Username: The user name associated with a domain account that has Admin privileges on eSignLive for Microsoft Dynamics CRM 2.0

l Password: Password for the Username

c. Save your changes, and restart the Website in IIS.

4. To verify that the service is running: (1) open the service in the Contents View of IIS; (2) browse for PostEvent.svc.

5. Bind the IIS Website to the public IP or domain, so OneSpan Sign can send noti-fications to the Push Notification Service. For this purpose, bear in mind that:

l The URL for the Push Notification Service is:

http://{SERVER_NAME:PORT}/PostEvent.svc/PostESLEvent

Here {SERVER_NAME:PORT} is a placeholder for the server name and port number.

NOTE: The service can be hosted on any port you want.

NOTE: The server name and port must be accessible from the Internet. You may want to open your firewall exclusively to OneSpan Sign's IP address. If so, you can obtain that IP address from our Support Team.

NOTE: This URL should be used in OneSpan Sign Account > Callback URL in the connector configuration.


31


NOTE: PostESLEvent is the method in the service that receives HTTP POST requests with a JSON payload as event data.


32

5.2 Verifying the Push Notification ServiceTo verify that events are being properly received by the Push Notification Service:

1. Create a package using your OneSpan Sign connector.

2. Verify that the service has received a OneSpan Sign Notification Entity about the new package.

3. If the expected events do not appear, check the following service log:

{SERVICE_INSTALLATION_FOLDER}\Logs\Log.txt

4. If the log files have not been created, there could be a permission issue on the IIS Website directory. Ensure that the account running the Application Pool has


33

write permissions to the Website folder.


34


35

NOTE: The Push Notification Service will not work if there is not enough free memory. If you find that it isn't working, ensure that on the server where the service is installed, the free memory is > 5% of the total memory.


36

5.3 Uninstalling the Push Notification Service

NOTE: The Push Notification Service is needed by your connector if it was installed on-premises. Thus you should uninstall the service only if you also want to uninstall the on-premises deployment of your connector.

To uninstall the Push Notification Service for your connector:

1. Delete the IIS Website and Application Pool by right-clicking PushNo-tificationService, and selecting Remove.

2. Remove the service's unzipped folder.


37

6 Uninstalling the Solution

CAUTION: Unless you back up your data, uninstalling the solution will cause you to lose: (1) all OneSpan Sign data stored in OneSpan Sign lists; (2) all documents attached to the OneSpan Sign Documents list.

To uninstall eSignLive for Microsoft Dynamics CRM 2.1:

1. From the top menu, go to eSignLive for Microsoft Dynamics CRM Settings > Solutions.

2. Select EslConnector, and click Delete.

6 Uninstalling the SolutioneSignLive Microsoft Dynamics CRM v2 -Deployment Guide

38

7 Troubleshooting

If you encounter any problems, you may contact our Support Team.

You can also reach us by fax at (514) 337-5258.

You may also want to visit our Resource Center at:

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

7 TroubleshootingeSignLive Microsoft Dynamics CRM v2 -Deployment Guide

39


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