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
Practifi’s direct integration with Black Diamond allows you to gain visibility over client portfolios from accounts to individual holdings without manually aggregating and reconciling from multiple sources. Black Diamond’s aggregated portfolio data is synchronized with Practifi overnight. Investment portfolios, asset classes and holding balances are all accessible from the client's record in Practifi.
This article outlines the steps to enable the Black Diamond integration in your organization. For more information about the Black Diamond integration, please consult our Using the Black Diamond Integration article.
- Before You Begin
- Installation
- Data Field Mapping (Legacy Portfolio API)
- Data Field Mapping (Client Relationship API)
Before You Begin
Your firm must have a Black Diamond subscription to use this integration.
Please make sure you have the following credentials from Black Diamond for the initial setup:
- Black Diamond username – The username for a valid Black Diamond user. This identifies the client firm they are part of and what data they have access to. When using the Sandbox (test system), use the credentials you were given to access that site.
- Black Diamond password - The password for the username used above. This may be discarded after initial use if a Refresh Token, detailed below, is used instead.
Installation
Create the Static Auth Provider
Under OAuth 2.0, the Authentication Provider is set up between Black Diamond and Practifi for all client organizations. It is the same reference for all client organizations and is only set up once by Practifi.
- Go to Salesforce Setup under the user’s avatar picture icon in the top right-hand corner.
-
Use the Quick Find search bar to search for and select Auth. Providers.
- Select the New button on the Auth. Providers page.
- Supply the following details on the new Auth Provider panel:
- Provider Type - BlackDiamondAuthProvider
-
Name - Use Black Diamond
- Please note: Choose the name carefully, and once the name has been created, do not delete it and try to recreate it. Salesforce still retains a reference to the original name and will have trouble authenticating with Black Diamond again after the change.
- URL Suffix - Use the default value. Note its use again under the Developer Name field
- Access Token URL - https://login.bdreporting.com/connect/token
- Client Id - This is a partner Consumer Key issued to Practifi by Black Diamond, to be shared across all the mutual client firms. Please contact the Practifi Support team to get access to this Id.
- Client Secret - This is a partner Consumer Secret issued to Practifi by Black Diamond, to be shared across all the mutual client firms. Please contact the Practifi Support team to get access to the Client Secret.
- Password - Enter the credentials of your Black Diamond account.
- Username - Enter the credentials of your Black Diamond account.
-
Execute As - Select an active Admin user. A Salesforce user that has permission to create Auth Providers is required. This is typically a System Administrator.
- Select Save, and navigate back to click on the newly created Black Diamond Auth. Provider.
-
Copy the Callback URL, which will be needed to set up custom settings.
Create the Named Credential
Two Named Credentials must be created to access the Black Diamond client system, one named Black Diamond (Legacy) and one named Black Diamond. To complete the creation of these Named Credentials, the Client must supply the name of an Admin user within Black Diamond who will authenticate the connection to Practifi through this Named Credential. The following sections cover the steps to create these two Named Credentials.
Black Diamond (Legacy)
- In Salesforce Setup, use the Quick Find search bar to search for and select Named Credentials.
-
On the Named Credentials page, click the New drop-down and select New Legacy.
-
On the New Named Credential screen, enter the following information:
- Label - Black Diamond (Legacy)
- Name - Leave the default value in this field.
- URL - https://api.bdreporting.com
- Identity Type - Named Principal
- Authentication Protocol - OAuth 2.0
- Authentication Provider - Black Diamond or the name StaticAuthProvider set up above.
- Scope - Null
- Start Authentication on Save - Checked. This will take the user to the Black Diamond login page, where the Admin user provides their Black Diamond username and password. The integration is then authenticated to allow Black Diamond client data to be accessed by Practifi.
- Generate Authorization Header - Checked
- Click Save.
- Verify the Authentication Status field displays Authenticated as its value.
Please note: You may face an error when saving this Named Credential because the Custom Settings and Remote Site Settings are not done yet, which we will do in the next few steps. The Named Credential will be finalized at the very last step.
Black Diamond
- In Salesforce Setup, use the Quick Find search bar to search for and select Named Credentials.
-
On the Named Credentials page, click the New drop-down and select New Legacy.
-
On the New Named Credential screen, enter the following information:
- Label - Black Diamond.
- Name - Leave the default value in this field.
- URL - https://api.blackdiamondwealthplatform.com
- Identity Type - Named Principal
- Authentication Protocol - OAuth 2.0
- Authentication Provider - Black Diamond or the name StaticAuthProvider set up above.
- Scope - Null
- Start Authentication on Save - Checked. This will take the user to the Black Diamond login page, where the Admin user provides their Black Diamond username and password. The integration is then authenticated to allow Black Diamond client data to be accessed by Practifi.
-
Generate Authorization Header - Checked
- Click Save.
- Verify the Authentication Status field displays Authenticated as its value.
Please note: You may face an error when saving this Named Credential because the Custom Settings and Remote Site Settings are not done yet, which we will do in the next few steps. The Named Credential will be finalized at the very last step.
Create the Remote Sites
- In Salesforce Setup, use the Quick Find search bar to search for and select Remote Site Settings.
-
Click on New Remote Site.
-
Supply the following:
- Remote Site Name - We suggest using Black_Diamond
- Remote Site URL - https://login.bdreporting.com
- Select Save to finalize this creation.
Activate the Black Diamond Integration
- In Salesforce Setup, use the Quick Find search bar to search for and select Custom Settings.
- Select Manage beside Black Diamond Integration Settings. The setting row will already be present.
- Within the Custom Setting page, the New button at the top is the one to use. Please do NOT use the bottom New button, which will create a Custom Setting Action and cause a "Formula Expression is required on the action attributes" error when trying to save the Named Credential later.
- In Integration Settings, supply the following:
- Callback URL - Paste the URL copied from Black Diamond Auth. Provider.
- Named Credentials (Legacy) - Black_Diamond_Legacy
- Named Credential - Black_Diamond
- External Id Asset Liability - practifi__External_Id__c
- External Id Holding - practifi__External_Id__c
- Select Save to finalize this change.
-
Navigate to the Named Credentials and select Edit for the Black Diamond named credential.
-
Select Save, and the Named Credential will now have the Authentication Status of Authenticated.
Enable Black Diamond Trigger Settings
For the integration to function successfully, the Black Diamond Portfolio trigger must be enabled under Practifi Trigger Settings. To enable this trigger:
- Use the Quick Find search bar to search for and select Custom Settings.
- Locate Practifi Trigger Settings and select Manage beside its name.
- On the Practifi Trigger Settings page, select the Edit button.
- Locate the following options and ensure the box beside them are checked:
- Black Diamond Portfolio - Checked
- External System Item - Checked
- Account - Checked
- Contact - Checked
- Contact Point Address - Checked
- Click the Save button to finalize this change.
Schedule Sync Job
The importing of Black Diamond Assets and Holding takes place once a day, at the end of the processing day for Black Diamond. Remember that Black Diamond is located in the USA, so the time of day chosen should be during the off-work hours for a USA business.
- Go to the Quick Find search bar and search for and select Apex Classes.
-
Select the Schedule Apex button.
-
Look up BlackDiamondScheduledSync and select the Apex Class.
-
Apply the required schedule, bearing in mind the end-of-day completion jobs on the Black Diamond system.
- Select Save to finalize this change.
Add Black Diamond As a New Source Value
- Add Black Diamond as a new Source in the Source list. Navigate to Object Manager > Asset/Liability > Fields & Relationships > Source.
-
Towards the end of the page is the list of available Sources. To add a new Source of Black Diamond, select New and add to the existing list.
-
After this step, the newly added value must be made visible to users for selection. From the Asset/Liability Object Manager, select the Record Type and then the Asset record type.
-
Select Fields & Relationships and the Source picklist. Select Edit alongside the Source field.
-
Move the Black Diamond value from the left-hand side in the Available Values list to the right-hand side Selected Values list and select Save.
Assign Permission Sets
You must assign one of two permission sets, depending on which API your firm is using. To assign the permission set:
- In the upper right-hand corner of the screen, click the settings cog and select Setup.
- In Salesforce Setup, use the Quick Find search bar to search for and select Permission Sets.
- Select one of the following permission sets:
- Practifi - Integrations - Black Diamond (Portfolio) is for the legacy API.
-
Practifi - Integrations - Black Diamond (Client Relationship) is for new setups or those switching to the Client Relationship API.
- Please note: While it is possible to assign both permission sets, we do not recommend it. This will result in duplicate data tables, which might confuse users.
- Click Manage Assignments, then click Add Assignment.
- Select the users that need access to the integration and select Assign.
Please note: If Black Diamond is the only integration added to the Practifi system, then the choice of Black Diamond as a dropdown choice on the Integrations tab will not appear. The Black Diamond portfolios will appear immediately on the mapping panel without needing to select Black Diamond specifically.
Enable the Client Relationship API
If this is a new integration setup or you want the integration to be based on Client Relationship rather than Portfolio, you must turn it on in Custom Settings. When using the Client Relationship API, holding data will be enabled. The Portfolio API does not bring in any holding data.
To enable the Client Relationship API:
- In Salesforce Setup, use the Quick Find search bar to search for and select Custom Settings.
- Select Manage beside Black Diamond Integration Settings.
- On the Black Diamond Integration Settings page, click the Edit button.
- Check the Enable Client Relationship box.
- Check the Use Client Relationships to Link Records box.
- Click Save.
Data Field Mapping (Legacy Portfolio API)
The following table details the mapping of values from Black Diamond across to Practifi Assets/Liabilities and Holdings.
Account | Asset_Liability__c |
---|---|
“Black Diamond“ |
Source__c |
{Portfolio Id}|{id} |
External_Id__c (Based on the value of External_Id_Asset_Liability__c in Black_Diamond_Integration_Settings__c) |
name |
Name |
accountNumber |
Account_Number__c |
Custodian Name - {custodianName} |
Description__c |
asOfDate |
As_At__c |
“Asset“ |
RecordTypeId |
If closedDate is Empty “Owned”, otherwise “Disposed”. |
Stage__c |
supervised |
Under_Advice__c |
Holding | Holding__c |
---|---|
asOfDate |
As_At__c |
assetName |
Name |
segmentName |
Segment_Name__c |
className |
Class_Name__c |
ticker |
Product_Code__c |
“True“ |
Unitised__c |
marketValue/units |
Price__c |
units |
Units__c |
Data Field Mapping (Client Relationship API)
Practifi receives the following information from Black Diamond, which is displayed on the Integrations page:
Client Relationship | External_System_Item__c |
---|---|
name | Item_Name__c |
id | External_Id__c |
teams | Team_Id__c |
"Black Diamond" | External_System__c |
The following data from Black Diamond is displayed on the Financial Product page in Practifi:
Account | Asset_Liability__c |
---|---|
"Black Diamond" | Source__c |
name |
Name |
accountNumber |
Account_Number__c |
displayName |
Description__c |
asOfDate |
As_At__c |
startDate |
Date_Opened__c |
closedDate |
Date_Closed__c |
custodian.name |
Custodian_Name__c |
subCategory.name |
Subcategory__c |
“Managed funds” |
Category__c |
accountType.identifier |
Account_Type__c |
accountRegistrationType.identifier |
Registration_Type__c |
taxStatus |
Tax_Status__c |
taxLotMethod |
Tax_Methodology__c |
discretionary |
Discretionary__c |
billable (reverse) |
Exclude_From_Billing__c |
supervised |
Under_Advice__c |
“Asset“ |
RecordTypeId |
If closedDate is empty, “Owned”; Otherwise, “Disposed“ |
Stage__c |
{ClientRelationship Id}|{id} |
External_Id__c (Based on the value of External_Id_Asset_Liability__c in Black_Diamond_Integration_Settings__c) |
Practifi sends the following information back to Black Diamond:
Practifi (Entity) | Black Diamond |
---|---|
External Id |
Id |
Entity Name |
Name |
Became Client On |
Inception Date |
Became Lost Client On |
Termination Date |
Practifi (Contact Point Address) | Black Diamond (Address) |
---|---|
Name |
Label |
If Map to Record = Postal |
Mailing Address = true |
Street |
Street Line 1 |
City |
Municipality |
State |
Administrative Area |
Postal Code |
Postal Code |
Country |
Country Code |
Comments
Article is closed for comments.