OpenFin integration with Salesforce Lightning Web Components

Overview

By default, Salesforce’s Lightning Locker security feature restricts access to all non-core web APIs, including those provided by OpenFin Container.

To enable interoperability, OpenFin and Salesforce worked together to find a solution that enables custom Salesforce components to access OpenFin APIs and use them just like any other app. The result of this collaboration is the Salesforce integration for Lightning Web Components, which is supported by Salesforce for current and future versions of Lightning Locker.

Prerequisites

📘

If you're new to Salesforce components, Salesforce provides this guide to developing components.

Install

Add the @openfin/salesforce-lwc NPM package:

npm install @openfin/salesforce-lwc

Configure

To allow custom Salesforce components to access OpenFin APIs:

🚧

The following configuration step must be done from a Salesforce System Administrator profile.

  1. Add the API source as a static resource in your Salesforce org. Refer to (Creating a Static Resource on the Salesforce developer site for details.) In the form that Salesforce provides, specify the following values:

    • Name: openfin-salesforce-lwc
    • Description: "Client library for enabling the use of OpenFin's JavaScript APIs in Salesforce components."
    • File: FULL_PATH_TO_APP_NODE_MODULES/@openfin/salesforce-lwc/openfin.salesforce-lwc.js
    • Cache Control: Public
  2. To enable Salesforce to call the OpenFin APIs, the prepareFinApiInPreload function must be called in a preload script. You can work with the script that is included with the NPM package, which is installed at YOUR_INSTALL_LOCATION/node_modules/@openfin/salesforce-lwc/preload.js. Or you can create your own:

import { prepareFinApiInPreload } from '@openfin/salesforce-lwc';

   (() => {
      // Prepare OpenFin APIs
      prepareFinApiInPreload();
   })();

📘

Make sure that your OpenFin app has access to the server where the preload script is hosted.

  1. Configure your OpenFin app to run the preload script. You add the script to your app's manifest, providing your own value for the path to the script.

    For a platform application:

{
     "platform": {
       "defaultViewOptions": {
         "preloadScripts": [
           {
             "url": "https://FULL_PATH_FOR_YOUR_FILE/preload.js"
           }
         ]
       }
     }
     // ...
   }

For a traditional OpenFin app with a startup_app entry:

{
     "startup_app": {
       "preloadScripts": [
         {
           "url": "https://FULL_PATH_FOR_YOUR_FILE/preload.js"
         }
       ]
     }
     // ...
   }

Access OpenFin APIs in a custom Salesforce component

In Lightning Web Components

To use OpenFin APIs in a Lightning Web Component, you must first load the static resource added previously as a third-party library. The static resource adds API functions to window.fin.salesforce. Call the initFinApiInLwc function to add OpenFin APIs to the window:

// Initialize OpenFin APIs for use
window.fin.salesforce.initFinApiInLwc();

// window.fin is now ready to use
const runtimeInfo = await window.fin.System.getRuntimeInfo();

// window.fdc3 is also ready to use
await window.fdc3.broadcast({
  type: 'fdc3.contact',
  name: 'Joe Bloggs',
  id: {
    email: '[email protected]',
  },
});

📘

To access the FDC3 API, make sure to configure your app’s manifest to enable FDC3.

Here is a complete example of a Lightning Web Component loading the static resource and using the OpenFin API:

import openfinSalesforceLwc from '@salesforce/resourceUrl/openfin_salesforce_lwc';
import { loadScript } from 'lightning/platformResourceLoader';
import { LightningElement } from 'lwc';

export default class MyComponent extends LightningElement {
  async connectedCallback() {
    try {
      await loadScript(this, openfinSalesforceLwc);
    } catch (err) {
      console.warn('Failed to load static resource, has it been added in Salesforce org settings?');
      return;
    }

    // Initialize OpenFin APIs for use
    window.fin.salesforce.initFinApiInLwc();

    // Output the current OpenFin runtime info to the console
    console.log(await window.fin.System.getRuntimeInfo());
  }
}

In Aura components

To use the OpenFin API in your Aura component, add a <ltng:require> tag to your component and use the $Resource global value provider to reference the static resource:

<aura:component>
  <ltng:require
    scripts="{!$Resource.openfin_salesforce_lwc}"
    afterScriptsLoaded="{!c.scriptsLoaded}" />
</aura:component>

Did this page help you?