1. Practifi Success
  2. System Administrator
  3. Integration Setup

Enabling the Black Diamond Integration

Follow
Avatar
Learning Team

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

Overview

The Black Diamond integration connects Practifi with Black Diamond’s wealth management platform, enabling bidirectional synchronization of client portfolios, assets, holdings, and contact information. This integration automatically keeps client financial data up to date across both systems, reduces manual data entry, and gives advisors a comprehensive view of clients in Practifi so that they can spend more time on client relationships and less on data reconciliation.

This article guides System Administrators through the complete enablement process, including prerequisites, authentication configuration, custom settings, and scheduled job setup. The integration uses OAuth 2.0 authentication and connects via Black Diamond’s Portfolio API and Client Relationship API.

For instructions on synchronizing large amounts of Black Diamond records with automation, see Using Black Diamond Automated Bulk Sync.

Please note: To enable this integration, you'll need to coordinate with the Practifi Support Team to get the required authentication credentials. Please contact your CSM or Practifi Support before beginning the enablement process.

Prerequisites

Before beginning the enablement process, ensure you have the following:

  • Salesforce System Administrator access
  • A Practifi license for the integration user
  • An active Black Diamond subscription with valid credentials
  • Black Diamond username and password for initial OAuth setup
  • Coordination with the Practifi Support Team to obtain Partner Consumer Key and Secret credentials

The integration requires both the Partner Consumer Key and Partner Consumer Secret issued by Black Diamond to Practifi. These credentials are shared across all mutual client firms and must be obtained through the Practifi Support Team.

Understanding the Integration Architecture

The Black Diamond integration uses two API endpoints to synchronize data between systems. Understanding these APIs helps you configure the integration appropriately for your firm’s needs.

Legacy Portfolio API

The Legacy Portfolio API synchronizes portfolio data, including account information and asset details. This API provides the foundation for financial data synchronization and is required for all Black Diamond integrations. The Legacy API endpoint is https://api.bdreporting.com.

Client Relationship API

The Client Relationship API extends the integration capabilities to include comprehensive client and contact synchronization, holdings data, and bidirectional sync functionality. When enabled, this API allows Practifi to send entity and contact updates back to Black Diamond, keeping client information consistent across both platforms without duplicate data entry. The Client Relationship API endpoint is https://api.blackdiamondwealthplatform.com.

Please note: The Client Relationship API covers all data points available in the Legacy API, plus additional data. New implementations should enable the Client Relationship API for the most comprehensive synchronization capabilities. The only reason to use only the Legacy API is if it meets all your firm’s data requirements and you want to avoid reconfiguring an existing integration.

Data Flow Summary

Inbound data (Black Diamond to Practifi) includes portfolios, client relationships, accounts, and holdings.

Outbound data (Practifi to Black Diamond) includes entity, contact, and address data. Outbound synchronization requires the Client Relationship API.
 

Black Diamond
Legacy Portfolio API
[api.bdreporting.com](http://api.bdreporting.com)
→ Holdings, Performance Data
 Practifi
Client Relationship API
[api.blackdiamondwealthplatform.com](http://api.blackdiamondwealthplatform.com)
→ Client Relationships, Accounts, Holdings
← Entity Details, Contact Info, Addresses

The integration uses two API endpoints to enable comprehensive bidirectional data synchronization.

 

Assigning Permission Sets

Users who need to access Black Diamond integration features require appropriate permission sets. The permission set you assign depends on which API version your firm uses.

To assign permission sets:

  1. Navigate to Setup by clicking the gear icon in the upper right-hand corner and selecting Setup.
  2. Use the Quick Find search bar to search for and select Users.
  3. Click on the name of the user who needs the permission set.
  4. In the Permission Set Assignments section, click Edit Assignments.
  5. Add one of the following permission sets to the Enabled Permission Sets list:
    • Practifi - Integrations - Black Diamond (Portfolio) for firms using only the Legacy API
    • Practifi - Integrations - Black Diamond (Client Relationship) for firms using the Client Relationship API

  6. Click Save.

     Select the appropriate Black Diamond permission set based on your firm’s API configuration.

Please note: While you can technically add both permission sets, this is not recommended. Enabling both permission sets displays two data tables within Settings > Integrations, which may confuse users.

Creating the Auth Provider

The Auth Provider configuration establishes the OAuth 2.0 authentication connection between Practifi and Black Diamond.

To create the Auth Provider:

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Auth. Providers.
  2. Click New.
  3. Configure the following fields:
Field Value
Provider Type BlackDiamondAuthProvider
Name Black Diamond (or another meaningful name)
URL Suffix BlackDiamond (auto-created from Name)
Access Token URL https://login.bdreporting.com/connect/token
Callback Url https://login.bdreporting.com
Client Id (obtain from Practifi Support)
Client Secret (obtain from Practifi Support)
Password Your Black Diamond Portal Password
Username Your Black Diamond Portal Username
Execute As Any user with the Manage Users permission
  1. Click Save.

  2. After saving, copy the Callback URL displayed on the page. You will need this value for the Custom Settings configuration.

Please note: Choose the Name value carefully and do not delete and recreate this record after initial creation. Salesforce retains references to the original name, and changes may cause authentication issues.

Configuring Remote Site Settings

Remote Site Settings authorize Practifi to communicate with Black Diamond’s API endpoint.

To configure Remote Site Settings:

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Remote Site Settings.
  2. Click New Remote Site.
  3. Configure the following fields:
Field Value
Remote Site Name Black_Diamond
Remote Site URL https://login.bdreporting.com
Active Checked

  1. Click Save.

    The Remote Site Setting authorizes communication with the Black Diamond authentication endpoint.

Creating Named Credentials

The integration requires two Named Credentials: one for the Legacy API and one for the Client Relationship API. Both credentials must be configured for the integration to function correctly.

Creating the Legacy Named Credential

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Named Credentials.
  2. Click the dropdown arrow next to New and select New Legacy.
  3. Configure the following fields:
Field Value
Label Black Diamond Legacy
Name Black_Diamond_Legacy (auto-created from Label)
URL https://api.bdreporting.com
Identity Type Named Principal
Authentication Protocol OAuth 2.0
Authentication Provider (Select the Auth Provider created in the previous step)
Scope (Leave empty)
Start Authentication Flow on Save Checked
Generate Authorization Header Checked
  1. Click Save. This redirects you to the Black Diamond login page.
  2. Enter your Black Diamond credentials to complete authentication.

  3. Verify that the Authentication Status shows Authenticated.

    The Legacy Named Credential connects to the Portfolio API endpoint.

Please note: You may encounter an error when saving if Custom Settings are not yet configured. The Named Credential will be finalized after the Custom Settings configuration is complete.

Creating the Client Relationship Named Credential

  1. In Named Credentials, click the dropdown arrow next to New and select New Legacy.
  2. Configure the following fields:
Field Value
Label Black Diamond
Name Black_Diamond (auto-created from Label)
URL https://api.blackdiamondwealthplatform.com
Identity Type Named Principal
Authentication Protocol OAuth 2.0
Authentication Provider (Select the Auth Provider created previously)
Scope (Leave empty)
Start Authentication Flow on Save Checked
Generate Authorization Header Checked
  1. Click Save. This redirects you to the Black Diamond login page.
  2. Enter your Black Diamond credentials to complete authentication.

  3. Verify that the Authentication Status shows Authenticated.

    The Client Relationship Named Credential connects to the comprehensive API endpoint for bidirectional sync.

Configuring Practifi Trigger Settings

Trigger Settings control which Practifi objects are synchronized with Black Diamond. These settings must be enabled for the integration to process data correctly.

To configure Trigger Settings:

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Custom Settings.
  2. Click the Manage link next to Practifi Trigger Settings.
  3. Click Edit.
  4. Ensure the following checkboxes are selected:
    • Account
    • Black Diamond Portfolio
    • Contact
    • Relationship
    • Contact Point Address (if Contact Point Address sync is required)
    • Contact Point Email
    • Contact Point Phone
    • External System Item

  5. Click Save.

    Enable triggers for all objects that should participate in Black Diamond synchronization.

Configuring Black Diamond Integration Settings

The Black Diamond Integration Settings control the synchronization behavior between systems, including which Named Credentials to use and which sync features to enable.

To configure Black Diamond Integration Settings:

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Custom Settings.
  2. Click the Manage link next to Black Diamond Integration Settings.
  3. Click New above the Default Organization Level Value section.

Please note: Use the New button at the top of the page, not the one at the bottom. Using the bottom New button creates a Custom Setting Action and causes errors when saving Named Credentials.

  1. Configure the following fields:
Field Value Purpose
Callback URL (Paste the URL copied from the Auth Provider step) Authentication callback
Named Credentials Legacy Black_Diamond_Legacy Must match Legacy Named Credential name
Named Credential Black_Diamond Must match Client Relationship Named Credential name
Use Client Relationships to Link Records Checked (if using Client Relationship API) Enables client relationship sync and holding data
Enable PF to BD Client Relationship Sync Checked (for bidirectional sync) Enables outbound sync from Practifi to Black Diamond
Sync Contact Point Address Optional Enables address sync to Black Diamond
Sync Holdings Batch Size 50 (default) Controls holding sync batch size
Sync Assets Batch Size 50 (default) Controls asset sync batch size
  1. Click Save.

After saving, return to Named Credentials, open the Black Diamond credential, and click Save again. The Authentication Status should now display as Authenticated.

Integration settings control sync behavior and connect to the appropriate Named Credentials.

Adding Black Diamond as a Source Value

The Source field on Asset/Liability records identifies the data source, providing your team with a clear audit trail for synchronized records and making it easier to distinguish data originating in Black Diamond from records entered directly in Practifi. Adding Black Diamond as a source value allows the integration to tag synchronized records properly.

To add Black Diamond as a source value:

  1. In Salesforce Setup, click Object Manager in the top navigation.
  2. Search for and select Asset/Liability.
  3. Click Fields & Relationships in the left sidebar.
  4. Click Source.
  5. Scroll to the bottom of the page and click New in the picklist values section.
  6. Enter Black Diamond as the new value.
  7. Click Save.

Making the Value Visible

After adding the value, make it available in the appropriate record types:

  1. Return to the Asset/Liability object in Object Manager.
  2. Click Record Types.
  3. Click Asset.
  4. In the Picklists Available for Editing section, click Source.
  5. Click Edit next to the Source field.
  6. Move Black Diamond from the Available Values list to the Selected Values list.

  7. Click Save.

    Add Black Diamond to the Source picklist and make it visible in the Asset record type.

Scheduling the Synchronization Job

The integration uses a scheduled Apex job to synchronize data from Black Diamond to Practifi daily, so advisors begin each day with current portfolio and account information ready in Practifi. You can schedule this job through the Setup interface or via the Developer Console.

Option 1: Scheduling Through Setup

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Apex Classes.
  2. Click Schedule Apex.
  3. Configure the job with the following settings:
    • Job Name: BlackDiamondSync
    • Apex Class: Click the magnifying glass and select BlackDiamondScheduledSync
    • Frequency: Select all days of the week
    • Start Date: Today’s date
    • End Date: A date far in the future
    • Preferred Start Time: An early morning time during off-peak hours (considering Black Diamond’s US location)

  4. Click Save.

    Configure the scheduled job to run daily during off-peak hours.

Option 2: Scheduling Through Developer Console

For more precise control over the schedule timing:

  1. In Salesforce Setup, click the Support Source dropdown in the upper right and select Developer Console.
  2. Use Ctrl + E to open the Execute Anonymous window.
  3. Enter the following code (adjust the schedule string as needed):
practifi.BlackDiamondScheduledSync bd = new practifi.BlackDiamondScheduledSync();
// Seconds Minutes Hours Day_of_month Month Day_of_week
String sch = '00 00 06 * * ?';
String jobID = System.schedule('BD Schedule', sch, bd);
  1. Click Execute.
  2. Navigate to Scheduled Jobs in Setup to verify the job was created.

Please note: The schedule string uses cron format with time in GMT. The example above runs at 6:00 AM GMT. Adjust the hours value to run during your preferred off-peak time, taking into account your local time zone offset.

Enabling the Client Relationship API

The Client Relationship API provides enhanced synchronization capabilities, including holding data and bidirectional sync with Black Diamond. New integrations should enable this API to provide the most comprehensive functionality and keep client information aligned across both systems.

To enable the Client Relationship API:

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Custom Settings.
  2. Click Manage next to Black Diamond Integration Settings.
  3. Click Edit.
  4. Configure the following settings:
    • Use Client Relationships to Link Records: Checked
    • Enable PF to BD Client Relationship Sync: Checked
    • Sync Contact Point Address (optional): Check if you want addresses to sync to Black Diamond
    • External Id Contact (optional): Leave blank to use practifi__External_Id__c, or specify an alternative field

  5. Click Save.

    Enable the Client Relationship API settings to activate bidirectional sync and holding data.

Please note: When Sync Contact Point Address is enabled, addresses synced from Practifi overwrite any addresses previously created directly in Black Diamond.

Understanding Data Mappings

The integration maps data between Black Diamond and Practifi according to predefined field mappings. Understanding these mappings helps you anticipate how data appears in each system.

Account to Asset/Liability Mapping

Black Diamond account records sync to Practifi Asset/Liability records with the following key mappings:

Black Diamond Field Practifi Field Notes
displayName Name Primary name field; falls back to name, then account
name Description Stores system-generated name
accountNumber Account_Number__c  
[custodian.name](http://custodian.name) Custodian_Name__c  
asOfDate As_At__c  
startDate Date_Opened__c  
closedDate Date_Closed__c  
supervised Under_Advice__c  
If closedDate is empty, Owned; otherwise, Disposed Stage (Asset/Liability) When a portfolio is deleted, associated assets are automatically set to the Disposed stage

Contact Data Mapping

Black Diamond contact records sync to Practifi Contact records with the following key mappings:

Black Diamond Field Practifi Field Notes
firstName FirstName  
lastName LastName  
middleName practifi__Middle_Name__c Truncated to 100 characters
dateOfBirth Birthdate  
gender practifi__Gender__c  
displayName Name  

Please note: Certain fields are truncated to meet Black Diamond’s character limits. The middle name, suffix, nickname, and street address fields are truncated to 100 characters. Job title truncates to 40 characters.

Holding Data Mapping

When the Client Relationship API is enabled, holding records sync with the following mappings:

Black Diamond Field Practifi Field
asOfDate As_At__c
assetName Name
segmentName Segment_Name__c
className Class_Name__c
ticker Product_Code__c
units Units__c
marketValue/units Price__c

Understanding Portfolio Deletion Behavior

When a Black Diamond Portfolio is deleted, the integration automatically handles associated assets to maintain data integrity in Practifi and keep AUM reporting accurate as portfolios change.

Asset Lifecycle Overview

The diagram below distinguishes active stages from non-active stages and shows which asset stages are included in AUM calculations:

Non-Active Stages

(Excluded from AUM)
Draft • Declined • Did Not Proceed • Potential • Disposed
← Auto-transition when the portfolio is deleted

Active Stages

(Included in AUM)
Owned • Application • Financed
These stages represent assets currently managed and are included in all AUM rollup calculations

An asset in Practifi is automatically marked as Disposed when its associated Black Diamond portfolio is deleted, ensuring accurate AUM calculations.

Automatic Asset Disposal

When a portfolio is deleted in Black Diamond:

  • Associated assets and liabilities are automatically marked as Disposed in Practifi
  • This applies to both Portfolio-based and Client Relationship-based integration models
  • Disposed assets are retained for historical reference but excluded from AUM calculations
  • The transition to Disposed status happens automatically during the next scheduled synchronization

AUM Calculation Updates

To ensure accurate reporting and data consistency, AUM rollup calculations now exclude assets in the following non-active stages:

  • Disposed
  • Draft
  • Declined
  • Did Not Proceed
  • Potential

Only assets with the following stages are included in AUM calculations:

  • Owned
  • Application
  • Financed

Affected Rollup Jobs

The following rollup jobs have been updated to reflect this behavior:

Core Product:

  • AUM To Service
  • Annual Revenue To Service
  • AUM To Financial Product
  • Number of Assets

Superannuation:

  • Member Account to Value
  • Total Member Accounts
  • Active Member Accounts

Please note: This automatic disposal process prevents orphaned records with stale dates from appearing in your client data when portfolios are removed from Black Diamond.

Monitoring and Troubleshooting

After enabling the integration, monitor synchronization status and address any issues that arise.

Monitoring Sync Status

Review synchronization activity through these locations:

  • Scheduled Jobs: Setup > Scheduled Jobs to verify the BlackDiamondSync job runs as expected
  • Apex Jobs: Setup > Apex Jobs to review execution history and identify failures
  • Integration Logs: Review Integration Log records where External System equals Black Diamond. For instructions on how to do this, see Using Salesforce Inspector Reloaded in Practifi.
Troubleshooting Full Integration Failure

If synchronization is not occurring at all:

  1. Verify that all configuration steps in this article have been completed correctly.
  2. Confirm that both Named Credentials show Authenticated status.
  3. Check that the scheduled job exists and is active in Setup > Scheduled Jobs.
  4. Review Apex Jobs to confirm the Black Diamond job executed without errors.
Troubleshooting Partial Integration Issues

If some data synchronizes, but other data does not:

  1. Review Practifi Trigger Settings to ensure all required objects are enabled.
  2. Verify Black Diamond Integration Settings are configured correctly.
  3. Check Integration Log records for specific error messages.
  4. Review the Apex job execution status for failures.

Troubleshooting Record-Level Sync Failures

If specific records fail to synchronize:

  1. For outbound sync, confirm the Send to Black Diamond button was clicked to initiate sync for the client record.
  2. Verify that the External ID Contact field is correctly configured.
  3. Ensure existing Black Diamond contact IDs are populated in Practifi to prevent duplication.
  4. Confirm Enable PF to BD Client Relationship Sync is enabled in Custom Settings.

Troubleshooting Asset Stage Issues

If assets are unexpectedly showing as Disposed:

  1. Verify whether the associated Black Diamond portfolio still exists.
  2. Check if the portfolio was recently deleted in Black Diamond.
  3. Confirm that disposed assets should be excluded from AUM calculations based on your firm's reporting requirements.
  4. Review the asset's stage history to determine when and why the status changed.

Security Considerations

The Black Diamond integration requires careful attention to security configuration to protect client data.

User Permissions

  • Users require appropriate permission sets assigned based on the API version in use.
  • The integration user must have the Practifi - Administrator permission set group.
  • Permission set selection (Portfolio vs. Client Relationship) determines which integration features users can access.

Authentication Security

  • OAuth 2.0 authentication provides secure token-based access.
  • Named Credentials store authentication tokens securely within Salesforce.
  • Both Legacy and Client Relationship APIs require separate Named Credentials.
  • Refresh tokens may be used instead of passwords after initial authentication setup.

Data Access

  • The Black Diamond username used during setup determines which client firm data is accessible through the API.
  • Sandbox credentials are separate from production credentials.
  • Two-way sync is configurable via Custom Settings, allowing you to control the direction of data flow.

Data Removal Limitations

The integration has specific limitations regarding the removal of data that has been synchronized to Black Diamond. Understanding these limitations helps set appropriate expectations.

Address Data

When removing address information from Practifi:

  • Changes to street and other address fields sync successfully.
  • Removing only the street field (while other fields remain) does not trigger a sync.
  • Completely removing all address fields does not remove existing data from Black Diamond; street and country values persist.

Please note: Once address data syncs to Black Diamond, it cannot be removed entirely via Practifi. Some address components persist even when all fields are cleared.

Phone Numbers and Emails

Deleting phone number and email fields in Practifi does not remove them from Black Diamond. Once synced, these contact details persist in Black Diamond even after removal from Practifi.

Entity Data

The Entity Name field is required and cannot be removed. Attempting to clear it does not trigger a sync. Address fields on entities follow the same limitations as contact address fields.

Gender Field Mapping

Gender field values map as follows:

Practifi Value Black Diamond Value
Male Male
Female Female
None Not Specified
Other (No mapping; field unchanged)

The Other value cannot be synchronized because Black Diamond only supports Male, Female, and Not Specified values.

For any additional assistance with the Black Diamond integration, please contact the Practifi Support Team.

0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.

Articles in this section

See more