Enabling the Envestnet Integration

Please note: This content is intended for Practifi System Administrators and is technical in nature. The steps described in this article may not be able to be completed without System Administrator permissions. Please discuss your integration installation plans with your Practifi Customer Support Team for their assistance.

Overview

Our integration with the Envestnet ENV 2 platform enables Advisors to create Clients and their Member details in Envestnet from Practifi records.  Updates from Practifi can be sent by a click to Envestnet, to maintain data currency between the two systems.  Advisors can then initiate Envestnet Proposal actions from Practifi, and complete details in Envestnet.  From within Practifi, the Advisor can view the list of Envestnet Proposals and click to link directly to Envestnet to view and update the Proposal. 

Updates to Client and Member details in Envestnet are not sent from Envestnet to Practifi - Practifi is intended to be the source of truth for Client and Member information.

• Before You Begin
• Workflow Setup for Proposal Management
• Installation
  • Set Up My Domain
  • Enable Identity Provider
  • Add Envestnet Certificate
  • Remote Site Settings
  • Enable Connected App
  • Add Envestnet Username to Each Practifi Username
  • Create Auth Provider
  • Create Named Credential
  • Apply Permission Sets
  • Configure Envestnet Integration Settings
  • Add Proposal Type to List
  • Add Link, Panel and Tab to the UI
  • User Authentication 
• Data Field Mapping

Before You Begin

Before beginning the installation process for the Evestnet integration, the following should be acquired:

1. Create a JKS certificate and send the Public portion to Envestnet for signing and return
2. The JKS certificate location, file name and password to the Keystore for API data authentication
3. The thumbprint of the JKS certificate
4. Envestnet Test and Production system URLs
5. ACS URLs of the Envestnet Test and Production systems
6. The Client Code issued by Envestnet for the Advisor firm
7. Client Key and Secret issued by Envestnet for the Advisor firm

Workflow Setup for Proposal Management

For users to initiate proposals in Practifi and send them to Envestnet for completion, the Investment Proposal Creation - Envestnet Process Type and its related Active Form must be deployed and enabled in your organization. If this functionality has not been made available in your organization, please contact Practifi Support.

Installation

The following steps are required to enable the Envestnet Integration. 

Set Up My Domain

My Domain is required for SSO authentication. In most scenarios, this should have been already configured. In this case, do not modify the domain; skip this step.

1. Locate My Domain using the Salesforce Setup Quick Find search bar and follow the wizard steps.
   
   
   
   
2. When a domain name has been chosen, select Register the Domain. Once registration is complete, an email will be received indicating that the domain is ready for testing. Note the complete URL of your domain, as this will be needed when configuring other Practifi integrations.
   
   

Enable Identity Provider

The Identity Provider service is required to support Single Sign-On (SSO) authentication. A Self-Signed certificate will be required here. Skip this step if your organization has already enabled the Identity Provider.

Please note: If the customer system already has SSO implemented for any other integrations, use that same certificate. The Identity Provider is shared across multiple integrations and only one Identity Provider is available per system.

1. Locate the Identity Provider using the Quick Find search bar in Salesforce Setup.
   
   
   
   
2. Select the Enable Identity Provider button.
   
   
   
   
3. Choose the existing Identity Provider certificate or select Create a new certificate... to generate a new Identity Provider certificate.
   
   
   
   
4. If creating a new certificate, choose a name for the Self Signed certificated which will be used by all integrations with SSO in your organization. 
   
   
   
   
5. A successfully enabled Identity Provider will show a panel like this:
   
   

Add Envestnet Certificate 

Please note: This step needs to be performed by Practifi Customer Support to extract and upload the certificate to the customer's system. Please create a Practifi Success ticket when you are ready for this step to be completed. 

Practifi will prepare a certificate and send the Public portion of the key to Envestnet. This is the certificate used for the encryption of the data between Practifi and Envestnet. Salesforce details the steps to request and set up the certificates as a general system setup task. 

Once the certificate has been created and signed by Envestnet it will be returned as a .JKS file and typically stored in a shared folder. This certificate should be imported into the Salesforce org. The thumbprint of the public portion of the certificate should be noted for use later.

1. Locate the Certificate and Key Management using the Quick Find search bar in Salesforce Setup.
   
   
   
   
2. Select the Import from Keystore button.
   
   
   
   
3. A list of folders on the local or shared folder drive will appear from where the certificate, signed earlier by Envestnet, has been downloaded and stored. Choose the file. Depending on how it was prepared, the file may have been password protected. If so, supply the Keystore Password and select Save.
   
   
   
   
4. After successfully importing the certificate, it will appear under Certificate and Key Management. At this point, also note the certificate thumbprint. 
   
   
   
   
5. To make note of the certificate thumbprint, download the certificate from Salesforce. This will download just the public portion of the certificate key as a .crt file.
   
   
   
   
6. From its downloaded location (it should have a file extension of .crt), double-click to open it, and note the Thumbprint value. Copy it to a place where it can be pasted for use later.
   
   

Remote Site Settings

Set up a Remote Site pointing to the Envestnet system from Salesforce.

Please Note: You may have been given the URL for a Test and a Production system. A Remote Site configuration will be needed for each.

1. Locate Remote Site Settings through the Quick Find search bar in Salesforce Setup.
   
   
   
   
2. Select the New Remote Site button.
   
   
   
   
3. Supply the following:
   • Remote Site Name: 
     • Test: Envestnet_UAT
     • Production: Envestnet
   • Remote Site URL:
     • Test: https://uat.envestnet.io
     • Production: https://envestnet.io
   • Active: ticked
4. Once the information is entered, select Save.  
   
   
   

Enable Connected App

This step is required for SSO authentication between the two systems.

1. Locate App Manager by using the Quick Find search bar in Salesforce Setup.
   
   
   
   
2. Select the New Connected App button.
   
   
   
   
3. Supply the following:
   • Connected App Name - Provide a meaningful name, for example, Envestnet SSO.
   • API Name - This value will auto-generate from the Connected App Name field.
   • Contact Email - This should be an email for a System Administrator in your organization.
   • Enable SAML (in the Web App Settings section) - Check this box.
   • Entity Id - The thumbprint of the public certificate, e.g. 057dadd685......c733ee882ea728
   • ACS URL - 
     • Test: https://uat.envestnet.com/secure/sso/saml_confirm.jsp?firm=practifi 
     • Production: https://portal.envestnet.com/secure/sso/saml_confirm.jsp?firm=practifi
   • Subject Type - Select Custom Attribute from the drop-down menu.
   • Custom Attribute - Select Envestnet_Username from the drop-down menu.
   • Name ID Format - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
   • Issuer - The thumbprint of the public certificate, e.g. 057dadd685......c733ee882ea728
   • IdP Certificate - The name of the Envestnet certificate, e.g. envestnet_dev.
   • Signing Algorithm for SAML Messages - SHA1
   • Fields to the end of the form are left blank.
     
     
     
     
4. Once this information is entered, select Save.
5. Permissions need to be assigned to this App. From the saved Connected App screen, select the Manage button.
   
   
6. Under the Profiles section, select Manage Profiles to assign permission to this SSO App by user profiles or select Manage Permission Sets to assign by previously defined permission sets.
   
   
   
   
7. The Advisor firm's policies will determine how they wish to allocate permissions to this App. For example, allocating SSO access permissions by Profile would look like this:
   
   
   
   
8. On the Manage Connected Apps screen, navigate to the Custom Attributes section and select New.
   
   
   
   
9. Supply the following:
   • Attribute key - Target
   • Attribute value - 'proposal_view:' + $User.practifi__Envestnet_Proposal_Handle__c
     
     
     
     
10. Locate the SAML Login Information section, and note the value in the IdP-Initiated Login URL field. Copy the path value from the /idp onwards. This is needed for the Custom Setting section.
    
    
    
    

Add Envestnet Username to Each Practifi Username

The Envestnet Username (that is, the user's Envestnet login) for each Envestnet user must be added to its corresponding Practifi Username in Salesforce. This is done using the Salesforce Developer Console.

Create a query that retrieves at least the list of users by name and the practifi__Envestnet_Username__c column. In the case of large numbers, the names can be entered manually from the results list or by uploading a Dataloader file.

Create Auth Provider

A single Auth Provider will be needed to connect Envestnet and Practifi systems to enable data exchange. Separate configurations will be needed for any Test and Production systems, as each must point to different URLs.

1. Locate Auth. Providers in Salesforce Setup by using the Quick Find search bar.
   
   
   
   
2. On the Auth. Providers page, select New.
   
   
   
   
3. Select EnvestnetAuthProvider as the Provider Type.
   
   
   
   

4. Supply the following:

   • Provider Type - EnvestnetAuthProvider
   • Name - A meaningful name (e.g., EnvestnetIntegrationsUSDemo2).  
   • URL Suffix - This information will auto-populate from the information input in the Name field. (eg. EnvestnetIntegrationsUSDemo2)
   • Certificate - Envestnet certificate which was imported at the Add Eventnet certificate step. (eg. envestnet_dev)
   • Client Code -  
     • Test - practifi
     • Production - Provided by Envestnet
   • Issuer - The thumbprint of public certificate e.g. 057dadd685......c733ee882ea728
   • Key -
     
     • Production - Provided by Envestnet
   • Secret -  
     
     • Production - Provided by Envestnet
   • Token Endpoint - 
     • Test - https://uat.envestnet.io/openenv/api/oauth2/token
     • Production - https://envestnet.io/openenv/api/oauth2/token
   • Execute As - The User/Advisor with Manage Users permission in the Salesforce profile. 
     
     
     
     
5. Once this information has been entered, select Save.

Create Named Credential

A single Auth Provider will be needed to connect Envestnet and Practifi systems to enable data exchange. Be aware that separate configurations will be needed for any Test and Production systems. Each will need to point to different URLs.

1. Locate Named Credentials in Salesforce Setup by using the Quick Find search bar.
   
   
   
   
2. Select New Named Credential.
   
   
   
   
3. Supply the following:
   • Label - A meaningful name (e.g., EnvestnetIntegrationsUSDemo2)
   • Name - This information will auto-populate based on the value entered in the Label field (e.g., EnvestnetIntegrationsUSDemo2).  
   • URL - 
     • Test: https://uat.envestnet.io/openenv/api
     • Production: https://envestnet.io/openenv/api
   • Certificate - Leave this field empty
   • Identity Type - Per User (note this setting)
   • Authentication Protocol - OAuth 2.0
   • Authentication Provider - the name of the Auth. Provider (eg. EnvestnetIntegrationsUSDemo2)
   • Scope - Leave this field empty
   • Start Authentication Flow on Save - Leave this box unchecked
     
       
4. Once this information is input, select Save.

Please note: The Admin setting up this Envestnet configuration will not be able to authenticate all the firm's users so they can start using the Envestnet integration. Each Advisor must authenticate themselves between the systems. 

Apply Permission Sets

Each Advisor who will be using the Envestnet Integration will need to have access to the Named Credential set up above.  This step will require the cloning of the initially supplied Practifi - Envestnet permission set so that it can be edited to include the Named Credential. The initial permission set cannot be edited, only a clone of the permission set can be edited.

1. Locate Permission Sets in Salesforce Setup using the Quick Find search bar.
   
   
   
   
2. Select the Clone button next to the Practifi - Integration - Envestnet permission set.
   
   
   
   
3. Locate and select the Practifi - Integration - Envestnet User row. 
   
   
   
   
4. Supply a name for the cloned copy of the permission set (e.g., Practifi—Integration—Envestnet User). From the updated list, click the cloned-copy name.
5. Click on the Named Credential Access link.
   
   
   
   
6. Select New to add a Name Credential or Edit to verify the list.
   
   
   
   
7. Ensure the Named Credential appears on the right side of the table under Enabled Named Credentials.
   
   
   
   
8. Select Save to complete the update.

Configure Envestnet Integration Settings

Please Note: One general Custom Setting is required for Envestnet configurations. One separate setting per Advisor under this custom setting.

1. Locate Custom Settings in Salesforce Setup by using the Quick Find search bar.
   
   
   
   
2. Locate the Envestnet Integration Settings record and select Manage.
   
   
   
   
3. If no Envestnet Integration Setting values have been applied yet, click the top-most New button to create them.
   
   
   
   
4. Supply the following: 
   
   • Enabled -Ticked
   • Named Credential - Created at the Named Credentials step. eg EnvestnetIntegrationsUSDemo2.  
   • Verbose Logging - Leave this unchecked. It is only used for testing
   • SSO URL - Copied from the Enable Connected App step, e.g., /idp/login?app=0sp2w000000CafE    Include the leading "/"
     

Add Proposal Type to List

This step will list the type Envestnet Proposal on the first panel which appears after the user clicks on the New Proposal button for the client. 

1. In the App Launcher, use the search bar to locate and select the Settings app.
   
   
   
   
2. Use the Navigation Menu to select Categories from the drop-down menu.
   
   
   
   
3. Ensure that the view All Service Types is selected for the Categories list view.
   
   
   
   
4. Search and locate the Envestnet Proposal Category Name.
   
   
   
   
5. Select Edit at the top right and supply the following under the Details subtab:
   • Category Name - Envestnet Proposal
   • Code - STINTENVPROP (or similar, to indicate a code for the Envestnet Proposal type)
   • Related To - Service Type
   • Group Code - STINVPROPOSAL (This value is required)
   • Active - Checked
     
     
     
     
6. Once this is entered, select Save.

Add Link, Tab and Panel to the UI

This step requires the Practifi Customer Support team's assistance in installing screen updates to show the Envestnet Integration information to the user. Please let the Support team know when you are ready for this step to be completed.

The steps are essentially the following:

1. A new table to list the Practifi Clients which have been transmitted to Envestnet, and for which new clients have been created in Envestnet.
2. Adding a new link option on the Client record for a Send to Envestnet function
3. A new section on the Client record to show Financial Advice and an Envestnet Proposals subtab
4. A panel to enable the user to link out from an Envestnet Proposal listing directly into Envestnet

User Authentication

The final step for enablement is for each Advisor to authenticate their Practifi user login with their Envestnet user login.  Please note: Each user must do this as a one-off step. 

The steps are as follows:

1. Select your user icon in the upper right-hand corner and select Settings.
   
   
   
   
2. Within Settings, select the Authentication Settings for External Systems link under the My Personal Information section.
   
   
   
   
3. Select New on this page to connect the Practifi user with the Envestnet user.
   
   
   
   

4. Supply the following, if not already completed:

   • External System Definition - Named Credential
   • Named Credential - From the drop-down list, select the name of the Named Credential created previously.
   • User - The username of the logged-in user. Use the search tool icon to locate and select the user.
   • Authentication Protocol - OAuth 2.0
   • Start Authentication Flow on Save - Check this box
     
     
     
     
5. Once this information is completed, select Save.
6. Upon clicking Save, the system will take the user to an Envestnet log-in panel, where the user should log in and confirm their link to Envestnet through Practifi. Upon completion, the user is returned to the list of External Systems for which they have been authenticated to access.
7. Selecting Edit will verify that the Administration Authentication Status now reads as Authenticated. The user may Cancel from this view and commence using the Envestnet Integration.
   
   

Data Field Mapping

The data mapped from Practifi to Envestnet relates to two principal Practifi concepts, Practifi Households and Practifi Contacts/Members. No other data elements are mapped back to Envestnet from Practifi.

Envestnet sends a single-line summary of each Proposal held in Envestnet for the Practifi Client, under the Financial Advice section in the Client record in Practifi.

Practifi Household	Envestnet Client
Account.Name	familyName

Practifi Household Member	Envestnet Family Member
Account.FirstName	firstName
Account.Middle_Name__pc	middleName
Account.LastName	lastName
Account.PersonBirthdate	birthDate
Account.Marital_Status__pc	maritalStatus
Relationship__c.Relationship_Type__r.Name Primary Contact Partner / Household Dependent / Household <anything else>	memberType Primary - 1 Spouse - 20 Child - 10 Other - 100
Account.Envestnet_Handle__c	memberHandle
Account.PersonMailingStreet	addressLine1
	addressLine2
Account.PersonMailingCity	city
Account.PersonMailingState	state
Account.PersonMailingPostalCode	zipCode
Account.PersonMailingCountry	country
1	addressType
Account.PersonHomePhone	homePhone
Account.Phone	businessPhone
Account.Fax	fax
Account.PersonEmail	email