esignlive for Microsoft Dynamics CRM

Size: px

Start display at page:

Download "esignlive for Microsoft Dynamics CRM"

Teresa James
5 years ago
Views:

1 esignlive for Microsoft Dynamics CRM Deployment Guide Product Release: 2.1 Date: June 29, 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: esignlive North America 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 esignlive North America Technology Inc. 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 esignlive North America Technology Inc. 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 esignlive North America Technology Inc. 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 esignlive North America Technology Inc. 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. ONESPAN NORTH AMERICA TECHNOLOGY INC. RESERVES THE RIGHT TO CHANGE ANY AND ALL INFORMATION CONTAINED HEREIN AT ANY TIME WITHOUT NOTICE.

3 CONTENTS About This Document 1 Released Files 1 Software Requirements 1 Additional Requirements 1 Installing the Solution 2 Prerequisites 2 Action 2 Configuring the Solution 4 Configuring Microsoft Azure 4 Specifying Account Information 7 Specifying a Language 9 Specifying User Permissions 9 Upgrading the Solution from 1.1 to Importing the New Solution 11 Specifying Account Settings 11 Completing the Upgrade 12 Reinstalling the Push Notification Service 13 Deploying the Push Notification Service for esignlive for Microsoft Dynamics CRM Installing the Push Notification Service 14 Verifying the Push Notification Service 17 Uninstalling the Push Notification Service 20 Uninstalling the Solution 22 Troubleshooting OneSpan North America Inc. iii

4 About This Document This guide describes how to deploy esignlive for Microsoft Dynamics CRM. In particular, it discusses: Installing the Solution (on page 2) Configuring the Solution (on page 4) Upgrading the Solution from 1.1 to 2.1 (on page 11) Deploying the Push Notification Service Uninstalling the Solution (on page 22) Troubleshooting (on page 23) 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) onpremises. Released Files esignlive for Microsoft Dynamics CRM v2.1 o Download esignlive for Microsoft Dynamics CRM v2.1 (the solution package) eslconnectorsitemap_1_0_0_x_managed.zip PushNotificationService.zip (for on-premises deployments only) Software Requirements You need one of the following third-party applications: esignlive for Microsoft Dynamics CRM 2016 On-Premises (Updated to or higher) Microsoft Dynamics 365 Update (8.2) online Additional Requirements The person performing the deployment must have: Deployment Administrator rights for esignlive for Microsoft Dynamics CRM A Sandbox or Production account for version 11 of esignlive, and an associated API Key For SharePoint Integration (on-premises only): SharePoint and Dynamics CRM should be on the same domain and network. Dynamics CRM users must have at least READ and WRITE permissions on all relevant SharePoint sites OneSpan North America Inc. 1

5 Installing the Solution This section describes how to install the 2.1 version of esignlive for Microsoft Dynamics CRM. Prerequisites Action You have a Sandbox or Production account for version 11 of esignlive, and an associated API Key. To get a free Sandbox account, follow the instructions on this page. You have Administrator privileges for esignlive for Microsoft Dynamics CRM. If you are installing an on-premises solution, you have performed the procedure Installing the Push Notification Service. To install the 2.0 version of esignlive for Microsoft Dynamics CRM: 1. Log into esignlive for Microsoft Dynamics CRM as a user with Administrator privileges. 2. Navigate to esignlive for 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 esignlive for Microsoft Dynamics v2.0 Release Candidate (Solution Package). 6. Click Next to display the Solution Information. 7. Click Next to display the Import Options. 8. Select the check box under Post Import Actions, then click Import. The solution is imported, and a summary page appears. After a certain delay, a message should state that the import was successful. 9. Click Close OneSpan North America Inc. 2

6 10. Click Publish All Customizations. This ensures that esignlive for Microsoft Dynamics CRMonline 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 OneSpan North America Inc. 3

Configuring the Solution After you have installed the solution, you should configure it by performing the following procedures: Configuring Microsoft Azure (below) Specifying Account Information (on

7 Configuring the Solution After you have installed the solution, you should configure it by performing the following procedures: Configuring Microsoft Azure (below) Specifying Account Information (on page 7) Specifying a Language (on page 9) Specifying User Permissions (on page 9) Configuring Microsoft Azure Prerequisites You must have Administrator privileges for Microsoft Azure. Action To configure Microsoft Azure for esignlive for Microsoft Dynamics CRM to authenticate esignlive for Callback notifications: 1. Log into 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., esignlive). 5. If you have not previously configured the connector: OneSpan North America Inc. 4

a. In the App registrations pane, click New application registration. The Create window appears. b. Complete the Name field. c. From the Application type dr

8 a. In the App registrations pane, click New application registration. The Create window appears. b. Complete the Name field. c. From the Application type drop-down menu, select Native. d. Specify the following Redirect URI: NAME>/connectors/api/v2/authorization/oauth2/dynamicscrm/<ORGANIZATION_ NAME> In the above URI: 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.com Candadian Customers sandbox.e-signlive.ca apps.e-signlive.ca Australian Customers European Customers apps.esignlive.com.au apps.esignlive.eu Replace the variable <ORGANIZATION_NAME>. To find the right replacement, log in to esignlive for Microsoft Dynamics CRM by clicking the Avatar icon in the top menu. Your organization name begins with "org" (although those characters and others have been erased from the following image) OneSpan North America Inc. 5

e. Click Create. 6. If you have previously configured the connector: a.

The Application ID is your client ID. b. Specify a Redirect URI, using the information in Step 5d above. 7.

In the Settings pane, click Required Permissions. 9.

9 e. Click Create. 6. If you have previously configured the connector: a. Click the esignlive 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. 7. Click Save. A Successfully updated application message appears. 8. In the Settings pane, click Required Permissions. 9. Ensure that the following permissions are displayed in the Required Permissions pane: Dynamics CRM Online (Microsoft.CRM) Windows Azure Active Directory (Microsoft.Azure.ActiveDirectory) 10. If these permissions are not displayed: OneSpan North America Inc. 6

10 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. iii. Click Grant Permissions, and then click Yes from the dialog box that appears. Specifying Account Information Your organization should have only one esignlive account. To inform esignlive for Microsoft Dynamics CRM about your esignlive account: 1. Log into esignlive for Microsoft Dynamics CRM as a user with Administrator privileges. 2. Navigate to esignlive for Microsoft Dynamics CRM > esignlive > Account Settings. An Active esignlive Accounts list appears. Initially this list should be empty. 3. From the ribbon, click New to create a new esignlive account. A new page appears. 4. Specify the following General parameters: Name: Name of the active esignlive account Maximum Number Of Documents: Maximum number of documents that can be included in a package (default = 10). 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 OneSpan North America Inc. 7

11 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. 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. 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 5. Specify the following esignlive Configuration parameters: address of the account owner API Key: Your esignlive API key. You can obtain it from Technical Support (sign.support@onespan.com; MYESIGN). As mentioned above, you must have a Sandbox account. Accordingly, specify the parameters API URL, Designer URL and Signer URL as follows: API URL Designer URL Signer URL Callback URL: If you have an on-premises deployment, this parameter is the URL of the Push Notification Service, which receives callbacks from esignlive (for more, see the last step of the procedure Installing the Push Notification Service). If you have an online deployment, enter the following value for this parameter: /PostEvent.svc/PostESLEvent 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: a. SharePoint Server Location: (1) select On-Premises if the SharePoint server is available locally; (2) select Online if the SharePoint server is on the Cloud. 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 specific SharePoint library, the system will upload documents only from that library. f. SharePoint Completed Documents URL: URL of the SharePoint site or library in which documents from a completed esignlive for Microsoft Dynamics CRM package are stored. If this URL points to a SharePoint site, the system will store documents to a library in that site. If this URL points to a specific SharePoint library, the system will store documents only in that library. The system will store all signed and completed documents in a new folder called <package name> GUID, which is located in the library specified by this URL. By default, that folder will be stored in the Shared Documents library on the SharePoint site you specified. g. SharePoint Fetch Count: The maximum number of documents fetched while querying a SharePoint site. 7. Click Save or Save and Close. 8. From the ribbon, click Verify Settings to confirm that: (a) the API Key and API URL are correct; (b) communications with the esignlive server can be established. 9. From the ribbon, click Set Callback URL to register the URL with esignlive OneSpan North America Inc. 8

Specifying a Language To specify a language for esignlive transactions: 1. Log into esignlive for Microsoft Dynamics CRM as a user with Administrator privileges. 2.

12 Specifying a Language To specify a language for esignlive transactions: 1. Log into esignlive for Microsoft Dynamics CRM as a user with Administrator privileges. 2. Navigate to esignlive for Microsoft Dynamics CRM > esignlive > Language. An esignlive Languages list appears. Initially this list should be empty. 3. Click New to create a new language for esignlive. 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. 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 OneSpan North America Inc. 9

13 6. Click OK OneSpan North America Inc. 10

14 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:. Importing the New Solution (below) Specifying Account Settings (below) Completing the Upgrade (on the next page) Reinstalling the Push Notification Service (on page 13) Importing the New Solution To 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 Package). 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., ). Specifying Account Settings To inform esignlive for Microsoft Dynamics CRM about your esignlive account: 1. Navigate to esignlive for Microsoft Dynamics CRM > esignlive Account. 2. Select your esignlive account. The esignlive Account: Information page appears OneSpan North America Inc. 11

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

15 3. Specify all parameters appropriately. For more information, see Specifying Account Information (on page 7). Completing the Upgrade To 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. For example: <add name="crmlocal" connectionstring="url= Domain=xxxxxx; Username=xxxxx; Password=xxxx"/> NOTE: All variables in the preceding example refer to esignlive for Microsoft Dynamics CRM. 3. Run the services.msc file from the Start menu. Then select and start the service name esignlive Connector Upgrade Service OneSpan North America Inc. 12

Specifically, all Account and Opportunity drop-down values must be Related Entity fields or Related Record fields.

16 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 esignlive packages. Specifically, all Account and Opportunity drop-down values must be Related Entity fields or Related Record fields. Reinstalling the Push Notification Service To reinstall the Push Notification Service, see Deploying the Push Notification Service. Your new service will replace the previous Push Notification Service, but it will use the same port OneSpan North America Inc. 13

17 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-premises. If you have a SaaS deployment, 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 esignlive every time the status of an e-signature process changes; 2. Transmits that information to the relevant connector. The rest of this section describes: Installing the Push Notification Service (below) Verifying the Push Notification Service (on page 17) Uninstalling the Push Notification Service (on page 20) Installing the Push Notification Service To 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: OneSpan North America Inc. 14

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

18 a. Connect to IIS with sufficient privileges. b. Click Add Web Site. A new dialog box appears. c. Specify the following parameters: d. Click OK. Site name: You can specify any name you want. Physical path: This path should identify the folder where the zip file was unzipped. Port: You can specify any port number you want. e. Ensure that the Application Pool version is 4.0 by selecting the Basic Settings of the Application Pool, as illustrated below OneSpan North America Inc. 15

3. Edit the file web.config as follows: a.

19 3. Edit the file web.config as follows: a. Update the connectionstring in the "<add name="crmlocal" connectionstring="...">" section of the file. b. Update the following parameters: URL: The URL of your esignlive for Microsoft Dynamics CRM organization (e.g., Domain: The domain name Username: The user name associated with a domain account that has Admin privileges on esignlive for Microsoft Dynamics CRM 2.0 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 OneSpan North America Inc. 16

$For this purpose, bear in mind that: The URL for the Push Notification Service is: http://{server_name:port}/postevent.$

20 5. Bind the IIS Website to the public IP or domain, so esignlive can send notifications to the Push Notification Service. For this purpose, bear in mind that: The URL for the Push Notification Service is: 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 esignlive's IP address. If so, you can obtain that IP address from Technical Support (sign.support@onespan.com; MYESIGN). NOTE: This URL should be used in esignlive Account > Callback URL in the connector configuration. NOTE: PostESLEvent is the method in the service that receives HTTP POST requests with a JSON payload as event data. Verifying the Push Notification Service To verify that events are being properly received by the Push Notification Service: 1. Create a package using your esignlive connector. 2. Verify that the service has received a esignlive 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 OneSpan North America Inc. 17

Ensure that the account running the Application Pool has

21 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 write permissions to the Website folder OneSpan North America Inc. 18

22 OneSpan North America Inc. 19

23 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. 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 OneSpan North America Inc. 20

24 To uninstall the Push Notification Service for your connector: 1. Delete the IIS Website and Application Pool by right-clicking PushNotificationService, and selecting Remove. 2. Remove the service's unzipped folder OneSpan North America Inc. 21

25 Uninstalling the Solution WARNING: Unless you back up your data, uninstalling the solution will cause you to lose: (1) all esignlive data stored in esignlive lists; (2) all documents attached to the esignlive 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 OneSpan North America Inc. 22

26 Troubleshooting If you encounter any problems, you may contact Technical Support MYESIGN). You can also reach us by fax at (514) You may also want to visit our Resource Center at: OneSpan North America Inc. 23

esignlive SAML Administrator's Guide Product Release: 6.5 Date: July 05, 2018 esignlive 8200 Decarie Blvd, Suite 300 Montreal, Quebec H4P 2P5

esignlive SAML Administrator's Guide Product Release: 6.5 Date: July 05, 2018 esignlive 8200 Decarie Blvd, Suite 300 Montreal, Quebec H4P 2P5 Phone: 1-855-MYESIGN Fax: (514) 337-5258 Web: www.esignlive.com