Enabling the Black Diamond Integration

Follow
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

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. 

  1. Go to Salesforce Setup under the user’s avatar picture icon in the top right-hand corner.

    mceclip2.png

  2. Use the Quick Find search bar to search for and select Auth. Providers.

    mceclip3.png

  3. Select the New button on the Auth. Providers page.

    mceclip1.png

  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://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.

      mceclip2.pngmceclip0.png

  5. Select Save, and navigate back to click on the newly created Black Diamond Auth. Provider.

    mceclip0.png

  6. Copy the Callback URL, which will be needed to set up custom settings.

    mceclip2.png

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)

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Named Credentials.
  2. On the Named Credentials page, click the New drop-down and select New Legacy.

    Screenshot 2024-10-14 at 1.07.14 PM.png

  3. 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
  4. Click Save.
  5. Verify the Authentication Status field displays Authenticated as its value.

    f843c104-7d6f-410f-8709-5dd4e2c63680.png

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

  1. In Salesforce Setup, use the Quick Find search bar to search for and select Named Credentials.
  2. On the Named Credentials page, click the New drop-down and select New Legacy.

    Screenshot 2024-10-14 at 1.07.14 PM.png

  3. 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

      mceclip2.png

  4. Click Save.
  5. Verify the Authentication Status field displays Authenticated as its value.

    92e1cbfc-9f61-4d45-aeb9-01a2138e0048.png

 

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.

    mceclip7.png

  3. Supply the following:

    • Remote Site Name - We suggest using Black_Diamond
    • Remote Site URL - https://login.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.

    mceclip4.png

  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.

    ActivateStep3.png
  4. In Integration Settings, supply the following:
    • Callback URL - Paste the URL copied from Black Diamond Auth. Provider.
    • Named Credentials (Legacy) - Black_Diamond_Legacy
    • Named CredentialBlack_Diamond
    • External Id Asset Liability - practifi__External_Id__c
    • External Id Holding - practifi__External_Id__c
  5. Select Save to finalize this change. 
  6. Navigate to the Named Credentials and select Edit for the Black Diamond named credential. 

    mceclip3.png

  7. Select Save, and the Named Credential will now have the Authentication Status of Authenticated

    ActivateStep7.png

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. 

    Screenshot_2023-02-08_at_10.02.15_AM.png

  3. On the Practifi Trigger Settings page, select the Edit button. 

    Screenshot_2023-02-08_at_10.01.49_AM.png

  4. 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
  5. Click the Save button to finalize this change.  

    Screenshot_2023-02-08_at_10.01.22_AM.png

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.

    mceclip12.png

  3. Look up BlackDiamondScheduledSync and select the Apex Class.

    mceclip2.png

  4. Apply the required schedule, bearing in mind the end-of-day completion jobs on the Black Diamond system.

    mceclip14.png

  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.

    mceclip5.png

  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. 

    mceclip0.png

  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.

    mceclip2.png
  4. Select Fields & Relationships and the Source picklist. Select Edit alongside the Source field.

    mceclip6.png

  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.

    mceclip7.png

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 confuse users.
  4. Click Manage Assignments, then click Add Assignment.

    Screenshot 2024-04-30 at 9.38.07 AM.png

  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.

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:

  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.
  3. On the Black Diamond Integration Settings page, click the Edit button.
  4. Check the Enable Client Relationship box.
  5. Check the Use Client Relationships to Link Records box.

    Screenshot 2024-10-04 at 12.19.05 PM.png

  6. 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

0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.