Enabling the Black Diamond 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

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
  • Create Static Auth Provider
  • Create Named Credentials 
  • Create Remote Sites
  • Activate the Black Diamond Integration
  • Enable Black Diamond Trigger Settings
  • Schedule Sync Job
  • Add Black Diamond as a New Source Value
  • Assign Permission Sets
• Data Field Mapping

Before You Begin

Practifi will set up the Black Diamond integration for you. You 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.

Please pass the above information to your Practifi Account Manager to commence the Black Diamond integration setup.

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. 

1. Go to Salesforce Setup under the user’s avatar picture icon in the top right-hand corner.
   
   
   
   
2. Use the Quick Find search bar to search for and select Auth. Providers.
   
   
   
   
3. Select the New button on the Auth. Providers page.
   
   
   
   
4. 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://api.bdreporting.com/issue/oauth2/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.
     
     
     
     
5. Select Save, and navigate back to click on the newly created Black Diamond Auth. Provider.
   
   
   
   
6. Copy the Callback URL, which will be needed to set up custom settings.
   
   
   
   

Create the Named Credential

Create a Named Credential to access the Black Diamond client system. To complete creating the Named Credential, the Client must supply the name of an Admin user within Black Diamond who will authenticate the connection to Practifi through this Named Credential.

1. In Salesforce Setup, use the Quick Find search bar to search for and select Named Credentials.
2. Click on New Named Credential.
   
   
   
   

3. Supply the following information:

   • Label - We suggest using Black Diamond.
   • 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
     
     

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

1. In Salesforce Setup, use the Quick Find search bar to search for and select Remote Site Settings. 
2. Click on New Remote Site.
   
   
   
   

3. Supply the following:

   • Remote Site Name - We suggest using Black_Diamond
   • Remote Site URL - https://api.bdreporting.com/
     
     
     
     
4. Select Save to finalize this creation.

Activate the Black Diamond Integration

1. In Salesforce Setup, use the Quick Find search bar to search for and select Custom Settings.
2. Select Manage beside Black Diamond Integration Settings. The setting row will already be present.
   
   
   
   
3. 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.
   
   
4. In Integration Settings, supply the following:
   • Callback URL - Paste the URL copied from Black Diamond Auth. Provider.
   • Named Credentials - Name of the Named Credential set up above.
   • External Id Asset Liability - practifi__External_Id_2__c
   • External Id Holding - practifi__External_Id__c
     
     
     
     
5. Select Save to finalize this change. The correct Custom Setting should look like this:
   
   
   
   
6. Navigate to the Named Credentials and select Edit for the Black Diamond named credential. 
   
   
   
   
7. 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:

1. Use the Quick Find search bar to search for and select Custom Settings. 
2. Locate Practifi Trigger Settings and select Manage beside its name. 
   
   
   
   
3. On the Practifi Trigger Settings page, select the Edit button. 
   
   
   
   
4. Locate Black Diamond Portfolio and select the checkbox beside this option. 
   
   
   
   
5. 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.

1. Go to the Quick Find search bar and search for and select Apex Classes.
2. Select the Schedule Apex button.
   
   
   
   
3. Look up BlackDiamondScheduledSync and select the Apex Class.
   
   
   
   
4. Apply the required schedule, bearing in mind the end-of-day completion jobs on the Black Diamond system.
   
   
   
   
5. Select Save to finalize this change.

Add Black Diamond As a New Source Value

1. Add Black Diamond as a new Source in the Source list. Navigate to Object Manager > Asset/Liability > Fields & Relationships > Source.
   
   
   
   
2. 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. 
   
   
   
   
3. 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.
   
   
4. Select Fields & Relationships and the Source picklist. Select Edit alongside the Source field.
   
   
   
   
5. 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:

1. In the upper right-hand corner of the screen, click the settings cog and select Setup.
2. In Salesforce Setup, use the Quick Find search bar to search for and select Permission Sets.
3. 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 be confusing to users.
4. Click Manage Assignments, then click Add Assignment.
   
   
   
   
5. 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.

Data Field Mapping

The following table details the mapping of values from Black Diamond across to Practifi Assets and Holdings.

Account (Black Diamond) >>> Asset/Liability (Practifi)

Practifi	Black Diamond
Description	Name
Account Number	Account Number
Valuation Date	As of Date
External Number	PFI ID | BD ID
Current Value	Sum of Holdings values

Holding (Black Diamond) >>> Holding (Practifi)

Practifi	Black Diamond
Name	Name
Segment Name	Segment Name
Class Name	Class Name
Product Code	Ticker
Unit Balance	Units
As At	As of Date
External Number	Account ID
Unit Value	Market Value / Units