Salesforce AppExchange solution

The OpenFin package on Salesforce AppExchange enables two-way interoperability between an OpenFin-based application and a Salesforce application running within the OpenFin environment.
Both sides can share appropriate FDC3 contexts and raise FDC3 intents for Salesforce's Account and Contact records.

You can set up this integration by installing the OpenFin package from AppExchange into your Salesforce org and configuring the contained Lightning web components.
Detailed instructions in this article describe the Salesforce user interface, which might be changed by Salesforce without notice.

The process to set up the OpenFin AppExchange app consists of the following steps at a high level:

1. Install the app package into your Salesforce org. This step requires administrator access to the org.

2. Configure the OpenFin components:

   • A utility bar component is required for sharing context with other OpenFin apps, and handling incoming contexts and user intents.
     This step also requires org-level administrator access.

   • A button component that you can add to Salesforce pages to raise intents to OpenFin-based applications that support FDC3 (or other OpenFin interoperability APIs), which can then process them as needed.
     This step requires only edit-access to Salesforce pages.

🚧

Warning

If your Salesforce org does not use Lightning Web Security (LWS), you must create and run a preload script in order for the OpenFin solution on the Salesforce AppExchange to work properly.
See Configure a preload script for details.

Install the package into your Salesforce org

1. Go to the page for the OpenFin package on SalesForce AppExchange, and click Get It Now.

2. Log in as an administrator user.

Once you install the OpenFin package, it is visible within the Setup view of your Salesforce org as an "Installed Package."

Configure the utility bar component

The OpenFin utility bar component can be added to any Salesforce Lightning app.
This component enables interoperability in Salesforce in two ways:

• It handles incoming messages and redirects them to the appropriate record page.

• It broadcasts context when the user navigates to a record page.

Only Account and Contact records are currently supported.
See the following tables for the mapping from FDC3 contexts and intents to Salesforce objects:

To configure the component:

1. On the App Manager page of Salesforce Setup, locate the Salesforce application for which you want to enable interoperability with OpenFin.
   The “App Type” must be “Lightning,” as only Lightning apps support the utility bar.
   In the drop-down menu for the application, click Edit to open the application's Settings page.

2. In the left navigation pane of the Settings page, click Utility Items (Desktop Only).

3. Click Add Utility Item; search for "OpenFin" and select the OpenFin item.

4. In the detail pane for the OpenFin item, you can configure properties of its display and behavior, such as the label and icon, and the height and width of its panel.

5. Ensure the Start automatically checkbox is checked, so that the item is started whenever the application is running.

6. By default, the component enables context sharing and intent handling for both Contacts and Accounts.
   You can disable any of those items as needed, for example, if it is managed by another integration.
   At least one operation and one object type must be enabled in order for the component to have any effect.

7. Click Save to save your changes and enable the component.

📘

Note

To support fdc3.instrument contexts, Account records must have the TickerSymbol field added to the object.
Once this is done, Instrument data are included when broadcasting fdc3.organization contexts; incoming fdc3.instrument contexts redirect Salesforce to the Account record whose TickerSymbol value matches the context.

Add the “Raise Intent” button in Salesforce pages

You can add a button to Salesforce pages that enables users to raise intents from Salesforce and explicitly trigger workflows in OpenFin-based applications that support interoperability APIs.
You must have page-editing access to add the button to pages.

The “raise intent” button can be added to Account or Contact record pages as well as non-record pages. When the user clicks the button, the action depends on the type of the page.

• Account or Contact record pages: The configured intent is raised that includes context data representing the current record.

• Non-record pages: The configured intent is raised but its context data is fdc3.nothing, meaning that there is no context data.

To configure the component, do the following:

1. From the page that you want to add the button to, open the Edit interface.

2. Drag the OpenFin: Raise Intent component from the components list and drop it where you want the button to be placed.

3. You can change the properties of the button as needed:

   • Set Label to a string that is meaningful to end users, and that informs them of the action that the button triggers.

   • Set Intent Name to the name of the intent that you want the button to invoke.

   • Set the Size and Variant as needed for your design and purposes.

4. Save the changes to the page.

5. Activate the changes at the appropriate level for your needs. App Default is typically used.

Configure a preload script

This section applies only to Salesforce orgs that do not use Lightning Web Security (LWS), for example because they pre-date LWS and have not yet had LWS enabled.
Any org where LWS is not enabled uses the Lightning Locker security service, which prevents Salesforce components from accessing OpenFin APIs by default, therefore requiring a preload script.

To enable the OpenFin components installed from Salesforce AppExchange to call the OpenFin APIs, the following code snippet must be added to a preload script applied to all views where Salesforce will run:

if (window.fin === undefined) {
  return;
}
CustomEvent.prototype.fin = window.fin;
CustomEvent.prototype.fdc3 = window.fdc3;

Configure your OpenFin app to run the preload script by adding the script’s URL to your app’s manifest preloadScripts property at the appropriate location:

{
  "platform": {
    "defaultViewOptions": {
      "preloadScripts": [
        {
          "url": "PRELOAD_SCRIPT_URL"
        }
      ]
    }
  }
}

{
  "startup_app": {
    "preloadScripts": [
      {
        "url": "PRELOAD_SCRIPT_URL"
      }
    ]
  }
}

Be sure to replace PRELOAD_SCRIPT_URL with the actual URL to your preload script.