Integrating with Salesforce Components

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

📘

Lightning Web Components Dev Guide

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>