Integrating with Salesforce Components

🚧

Warning

Salesforce's Lightning Locker has been replaced by the Lightning Web Security (LWS) architecture. LWS is enabled by default for all new Salesforce orgs in versions of Salesforce later than Summer 23. The information in this article applies only to Salesforce orgs have not been updated to use LWS.

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 OpenFin app. As a result of this collaboration, OpenFin provides a simple API library to enable OpenFin APIs from within Salesforce components, which is supported by Salesforce for current and future versions of Lightning Locker.

Prerequisites

• OpenFin

• Salesforce

  • Org with System Administrator profile, or sign up for a free Salesforce developer org.

Installation

Add the @openfin/salesforce-lwc NPM package as a dependency for your app:

npm install @openfin/salesforce-lwc

Configuration

Add the API library as a static resource

1. In the Salesforce org, create a new static resource.

2. Specify the following:

   • Name: "openfin-salesforce-lwc"

   • Description: "Client library for enabling the use of OpenFin's JavaScript APIs in Salesforce components."

   • File: Click Choose file and browse to your app’s local node_modules folder and select the file @openfin/salesforce-lwc/openfin.salesforce-lwc.js.

   • Cache Control: "Public"

Configure preload script

To enable Salesforce to call the OpenFin APIs, the prepareFinApiInPreload function must be called in a preload script. Either:

1. Use the preload script that is included with the NPM package, which can be found in your app’s local node_modules folder as @openfin/salesforce-lwc/preload.js.

2. Or you can create your own preload script by including the following code and bundling as a UMD module using your preferred module bundler (e.g. webpack):

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

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

Whichever approach you choose, you must 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:

• For a platform application:

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

• For a traditional OpenFin app with a startup_app entry:

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

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

Usage

In Lightning Web Components

📘

Note

If you're new to Salesforce development, Salesforce provides this guide to developing Lightning Web Components.

To use OpenFin APIs in a Lightning Web Component, you must first load the static resource 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.

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
    const runtimeInfo = await window.fin.System.getRuntimeInfo();
    console.log('Runtime info:', runtimeInfo);
  }
}

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>