Enabling the eMoney Integration - SPA

Introduction

Our integration with eMoney allows Advisors to create Client and Member records in eMoney, and open Plans (Scenarios and What-Ifs) from within Practifi for viewing and updating in eMoney.  

Before You Begin

eMoney provides a guide on setting up their system to make data connections to external systems like Practifi.  There are steps that require the involvement of eMoney representatives for key setup information, and technical requirements regarding the signing of JWT certificates.  The guide is available here.  Read this guide first.

As part of the certificate setup process, eMoney will send back two Client IDs, one for Test and another for Production, and a single API key.  

To complete this installation the following information will be needed:

1. Two X509 authentication certificates, one for Production, and another for a Test system.
2. Client ID from eMoney as part of the certificates approval process and entered as part of the Auth Provider set up. 
3. API Key for EMoney Integration Settings from eMoney and entered as part of the custom settings for this integration.

Data Field Mapping

The following data field mapping takes place between Practifi and eMoney.  The key point to remember is that elements from the Practifi representations of a Household and its two key Members appear in particular locations in the eMoney representation.  

Practifi	eMoney
Household Primary Contact Partner Contact	Client Account Address from Primary Contact Client Spouse

The detailed mapping is as follows:

Practifi		eMoney
Primary Contact	FirstName	Client	firstName
	LastName		lastName
	BirthDate		dateOfBirth
	Sex__c		gender
	General_Health_c		inGoodHealth
	Country_Of_Citizenship__c		citizenship
	Email		email
	MobilePhone		cellPhone
	Employer__c		Job.companyName
	Occupation__c		jobTitle
	Work_Email__c		job.businessEmail
	Phone		job.businessPhone
	Fax		job.businessFax
Partner Contact	FirstName	Spouse	firstName
	LastName		lastName
	Birthdate		dateOfBirth
	Sex__c		gender
	General_Health__c		inGoodHealth
	Country_Of_Citizenship__c		citizenship
	Email		email
	MobilePhone		cellPhone
	Employer__c		Job.companyName
	Occupation__c		jobTitle
	Work_Email__c		job.businessEmail
	Phone		job.businessPhone
	Fax		job.businessFax
Account	ShippingAddress	Client Account	address1
	ShippingCity		city
	ShippingState		state
	ShippingPostalCode		postalCode
Primary Contact	Phone		homePhone
	Fax		fax
	Marital_Status__c		maritalStatus
	User Mapping		ownerId

LIMITATION:  At present only the Primary and Partner Contacts are passed and updated in Practifi and eMoney.  Dependents and other entities are not supported yet. 

• Updates FROM Practifi TO eMoney take place immediately upon Saving an update in Practifi
• Updates FROM eMoney TO Practifi take place:
  • On clicking Sync from EMoney button on Practifi Client record, and
  • Completion of scheduled sync job 

Set-Up Steps

The installation steps cover the following areas:

1. Request and Install the eMoney Certificate
2. Create Remote Site settings
3. Create the Auth Provider
4. Create the Named Credential
5. Configure eMoney Integration Settings
6. Update Practifi Trigger Settings
7. Add Tab Values to Menu Items List
8. Enable Menu Items
9. Mapping of Practifi Users to eMoney User Logins (if necessary)
10. Schedule Data Sync Job

1. Request and Install the eMoney Certificate

eMoney has a guide here for the requesting of certificates.  Note in particular the choices of Certification Authorities that are acceptable to eMoney for this purpose.

Salesforce also details the steps to request and set up the certificates as a general system setup task.  It is available here.

2. Create Remote Site settings

Two Remote Site settings are required for each system, Test or Production.  Note for which system the Remote Sites are being created when entering the URL information:

1. emoney_api
2. emoney_auth

Locate the Remote Site Settings configuration panel in Salesforce, and click New Remote Site

emoney_api

This is the remote site for the API call servicing endpoints.

Supply the following:

• Remote Site Name:  emoney_api
• Remote Site URL:
  • Test: https://api-externalbeta2.emaplan.com/
  • Production: https://api.emoneyadvisor.com
• Active: ticked

emoney_auth

This is the remote site for API authentication calls.

Supply the following:

• Remote Site Name:  emoney_auth
• Remote Site URL:
  • Test: https://signin-externalbeta2.emaplan.com/connect/token
  • Production: https://signin.emaplan.com/connect/token
• Active: Ticked

After completing these steps the following Remote Sites should appear.

3. Create the Auth Provider

One Auth Provider is required between the customer's Practifi system and eMoney.  Locate the Auth. Providers configuration panel in Salesforce, and click New.

Select EMoneyAuthProvider as the Provider Type.  This type is added to the list as part of the Practifi installation.

A new panel appears on which additional fields need to be completed.

Supply the following.  Note the system is being set up, Test or Production, when entering the URLs:

• Name: emoney
• URL Suffix: emoney (default)
• Certificate: eMoneyCert (as uploaded above under 1. Request and Install eMoney Certificate step, above)
• Client Id: Supplied by eMoney as part of certificate approval process, one for Test and another for Production systems
• Developer Name: emoney
• Scope: API
• Token Endpoint:
  • Test: https://signin-externalbeta2.emaplan.com/connect/token
  • Production: https://signin.emaplan.com/connect/token
• Execute As: Any active user on the Customer system

On clicking Save the following new Auth Provider will have been created.

4. Create the Named Credential

One Named Credential is required between the customer's Practifi system and eMoney.  Locate the Named Credentials configuration panels in Salesforce, and click New Named Credential.

'

Supply the following. Note the system is being set up, Test or Production, when entering the URLs:

• Label: emoney
• Name: emoney
• URL:
  • Test: https://api-externalbeta2.emaplan.com/
  • Production: https://api.emoneyadvisor.com
• Identity Type: Named Principal
• Authentication Protocol: OAuth 2.0
• Authentication Provider: emoney (set up in the Auth. Provider step, above)
• Scope: API
• Start Authentication Flow on Save: Ticked
• Generate Authorization Header: Ticked

On clicking Save the systems will begin authentication with each other as a once-off step, and the Authentication Status field will change to read Authenticated.

5. Configure eMoney Integration Settings

Locate the Custom Settings configuration panel in Salesforce, and click New.

Locate the EMoney Integration Setting row, and click Manage

Review the following, adjust the settings as needed, then click Save:

NOTE: These settings should be implemented as listed here.  The level of detail provided by these settings is as an aid to diagnose problems, where the system behaviour can be temporarily modified to check for a particular condition which may be causing a problem.

Field	Value	Purpose
API Key		Supplied by Emoney
API Version	v1	Identify the API version in use
Auto Map Client	Ticked	If enabled, automap clients between eMoney and Practifi by a common email address between the eMoney client and the Primary Contact.  That is, the Primary Contact represents the eMoney client.
Auto Map User *	Ticked	If enabled, automap clients between eMoney and Practifi by their common email addresses
Create New Batch Size	Blank	For troubleshooting only
Create New	Ticked	If enabled, allows the creation of a new Practifi client based on eMoney client.  This setting is necessary for the Create Client tickbox feature under Data Management > EMoney Clients to function.
Default User Id *	Blank	This field is used for mapping of many Practifi client owners to one eMoney owner.  The one (and only) eMoney user is mapped to all Practifi advisors. If this field is completed with an eMoney UserId, that UserId will be used to create and new Clients and become the owner in eMoney. *
eMoney As Source Of Truth	Ticked	If enabled, eMoney data values will become the initial client information from eMoney to Practifi after linking an existing Practifi Client with an eMoney client. If disabled, the existing Practifi Client values will overwrite the existing eMoney values when linking an existing Practifi Client with an eMoney client.
Enabled	Ticked	If disabled, all eMoney features will be disabled, and the eMoney button in the client headers will be hidden
Get Clients Page Size	Blank	For troubleshooting only
Link Clients Batch Size	Blank	For troubleshooting only
Link Clients	Ticked	If enabled, allows mapping of an existing client in Practifi with an eMoney Client.  This setting is required to allow linking of existing Practifi and eMoney clients using the Data Management > EMoney Clients page.
Named Credentials	emoney	Set up in Named Credentials step 4, above
Patch Client Batch Size	Blank	For troubleshooting only
Patch Clients	Ticked	If enabled, automatically update clients information in eMoney if any client information is changed in Practifi (ie allows the triggers to function)
Pull Clients Batch Size	Blank	For troubleshooting only
Push Clients Batch Size	Blank	For troubleshooting only
Push Clients	Ticked	If enabled, allows client information to be pushed from Practifi to eMoney.  This setting is required to enable the Send to EMoney button to function on the Practifi Client record.
Show Exception in Batchable	Blank	For troubleshooting only, the default should set to blank
Sync Clients Batch Size	Blank	For troubleshooting only
Sync Clients	Ticked	If enabled, allow syncing clients between eMoney and Practifi.  This setting is necessary to allow the update triggers, and overnight sync jobs, to function.
Sync From EMoney	Ticked	If enabled, allows syncing of data from eMoney to Practifi.  This setting is required to enable the Sync from EMoney button to function on the Practifi Client record.
Sync Owner From EMoney *	Ticked	If enabled, allow sync of Advisor owner of clients from eMoney to Practifi (ie Practifi client owner is updated to match eMoney owner). Disable this setting if one-to-many User mapping is in effect (see section 9 below)
Sync Owner To EMoney *	Ticked	If enabled, allow sync of Advisor owner of clients from Practifi to eMoney (ie eMoney client owner is updated to match Practifi owner). Disable this setting if one-to-many User mapping is in effect (see section 9 below)
Sync Plans Batch Size	Blank	For troubleshooting only
Sync Plans	Blank	If enabled, allows sync of Plans from eMoney to Practifi (as Advices).  Plans are never initiated in Practifi.
Sync To EMoney	Ticked	If enabled, allow syncing client data to eMoney.  This setting is required to enable the update triggers to function.
Unlink Clients Batch Size	Blank	For troubleshooting only
Unlink Clients	Ticked	If enabled, when Unlinking a client in Practifi from an eMoney client, the Advices under the client in Practifi will be deleted.  Plans in eMoney are not altered.
Verbose Logging	Blank	For troubleshooting only, by default should set to blank

* See section 9 Mapping of Practifi Users to eMoney User Logins, below, for the settings to apply here.

Click Save to update the fields.

6. Update Practifi Trigger Settings

Return to the Custom Settings configuration panel in Salesforce, and locate the Practifi Trigger Settings row, and click Manage

Supply the following relating to eMoney, then click Save:

• EMoney Client: Ticked
• EMoney User: Ticked

7. Add Tab Values to Menu Items List

Two new tabs need to be activated to show eMoney tabs:

1. emoneyuser
2. emoney

Locate the Picklist Value Sets configuration panel in Salesforce.

Locate the Menu Item Tabs row, and click on the name.

Locate the emoney and emoneyuser items in the list of Global Values.  If they are not present add New to the list.

Add emoney and emoneyuser in lower case and one per line, and Save

They may not be in alphabetically order on your system.  Ensure they are Activated.

8. Enable Menu Items

Under Practifi Settings, locate the Menu Items tab

Set the Menu Items filters as below, and ensure the emoney rows are Active

Click Save to update the changes.

Manual Menu Item Creation

If these rows are not visible in the system they should be created manually.

Click +Add in the top left

Supply the following for EMoney Users tab:

• Context: datamanagement
• Tab: emoneyuser (if not available ensure you’ve added this in the Menu Tab picklist step, above)
• Header Page: datamanagement_header
• View Page: datamanagement_emoney_user_list
• Label: EMoney Users
• Icon: times
• Order: 18.01
• Code: SBDATAEMONEYUSER
• All other values default

Click +Add in the top left

Supply the following for the EMoney Client tab:

• Context: datamanagement
• Tab: emoney (if not available ensure you’ve added this in Menu Tab picklist step, above)
• Header Page: datamanagement_header
• View Page: datamanagement_emoney_client_list
• Label: EMoney Clients
• Icon: times
• Order: 18.02
• Code: SBDATAEMONEYCLIENT
• All other values default

9. Mapping of Practifi Users to eMoney User Logins (if necessary)

Flexibility to determine whether a single eMoney user login is used by all Practifi users, or whether each Practifi user has their own eMoney login, is supported by the eMoney Users tab of the Data Management section in Practifi, and key settings under the eMoney Integration Settings in section 4, above. 

Requirement	Settings
Each Practifi User has a unique login to eMoney, matched by a common email address	Auto-Map User - Ticked Default UserID - Blank
Each Practifi User has a login to eMoney, but with a different email address	Auto-Map User - Unticked Default UserID - Unticked Use the eMoney Users tab to manually select the Practifi User to match its eMoney User (see Updating of User Mapping, below)
A single eMoney User login is to be used across all Practifi Users	Auto-Map User - Unticked Default UserID - Common eMoney UserID Sync Owner from EMoney - Unticked Sync Owner from Practifi - Unticked

 

If an eMoney user login needs to be mapped manually to a Practifi login, the EMoney Users panel under Data Management in Practifi will all this.

Where an eMoney Advisor login does not have a corresponding Practifi User login, start by clicking on the pencil edit icon, entering part of the Practifi User login name required, selecting that name. and clicking Save.

An eMoney User can only be linked to one Practifi user.  The list of eMoney Advisor usernames may be refreshed with the Sync EMoney Users button.

10. Schedule Data Sync Job

A synch job to carry changes made in eMoney to linked Clients in Practifi should be scheduled to run at intervals as required by the firm's users.  Perform this least once per day.

In Salesforce, go to the user’s dropdown and select Developer Console.

Under Debug, open an Open Execute Anonymous Window

Paste in the following fragment of code into the window and Execute.

// Create synch to sync client information from eMoney to Practifi at 2am each day

cloupra.EMoneyInvocable emoney = new cloupra.EMoneyInvocable('syncClients');
String sch = '00 00 02 * * ?';
String jobID = System.schedule('eMoney Sync clients', sch, emoney);

See the Salesforce document here on how to configure schedule times.