@openfin/salesforce-lwc v1.1.1

OpenFin Salesforce Integration for Lightning Web Components

OpenFin’s Salesforce integration enables developers to create a two-way connection between OpenFin Container and Salesforce. The integration consists of the following NPM packages:

• @openfin/salesforce-lwc: Connect custom Salesforce components with OpenFin Container (this package)
• @openfin/salesforce: Connect OpenFin Container with Salesforce

Introduction

Running Salesforce in OpenFin is a popular requirement, with developers naturally wanting to take advantage of the extensive APIs provided by both Salesforce and OpenFin. However, 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 Container APIs and use them just like any other app. As a result, the solution offered by this package is supported by Salesforce for current and future versions of Lightning Locker.

Prerequisites

OpenFin

If you are not already familiar with building apps for OpenFin Container, follow this guide to help you get started.

Salesforce

The OpenFin Salesforce integration can be used with any Salesforce org, however you will need the admin role to apply the required configuration changes. Alternatively, sign up at developer.salesforce.com for a free developer org which you can use without restriction.

If you are not already familiar with how to develop components for Salesforce, follow this guide for an introduction.

Installation

First, add the package as a dependency for your app.

npm install @openfin/salesforce-lwc

or

yarn add @openfin/salesforce-lwc

Using OpenFin APIs from Salesforce components

Add this package to your Salesforce org as a static resource

To load this package from within a Salesforce component, you first need to add it as a static resource in your Salesforce org.

Note: The compiled JavaScript file can be found in the @openfin/salesforce-lwc folder within your OpenFin app’s node_modules folder after installing this package.

1. On the main Setup page for your org, search for "static resources" and click on the relevant result.
2. Click New to add a new static resource.
3. Complete the form as directed:
   • Name: openfin_salesforce_lwc
   • Description: "Client library for enabling the use of OpenFin’s Javascript APIs in Salesforce components."
   • File: <path_to_app_node_modules>/@openfin/salesforce-lwc/api.js
   • Cache Control: Public
4. Click Save to create the static resource.

You need to do this only once for your Salesforce org; it is then available to any OpenFin app you create.

Create a preload script

An app that uses this package needs to run a preload script that calls the prepareFinApiInPreload() function:

// preload.ts

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

(() => {
  // Prepare OpenFin LWC support
  prepareFinApiInPreload();
})();

Note: Using a bundling tool such as webpack ensures that required dependencies are included with your compiled preload script.

Add the preload script to your app

To ensure the compiled preload script is run before app content is loaded, it must be added to your OpenFin app’s manifest.

For platform applications

When using a platform application, preload scripts can be added in three places:

• Platform level: add preloadScripts to the platform property in the manifest:

  {
    "platform": {
      "preloadScripts": [
        {
          "url": "https://path.to/your/preload_script.js"
        }
      ]
    }
    // ...
  }

• Window level: add preloadScripts to the defaultWindowOptions property in the manifest:

  {
    "platform": {
      "defaultWindowOptions": {
        "preloadScripts": [
          {
            "url": "https://path.to/your/preload_script.js"
          }
        ]
      }
    }
    // ...
  }

• View level: add preloadScripts to the defaultViewOptions property in the manifest:

  {
    "platform": {
      "defaultViewOptions": {
        "preloadScripts": [
          {
            "url": "https://path.to/your/preload_script.js"
          }
        ]
      }
    }
    // ...
  }

For non-platform applications

If your app is a traditional OpenFin app with a startup_app entry, add preloadScripts to the startup_app property in the manifest:

{
  "startup_app": {
    "preloadScripts": [
      {
        "url": "https://path.to/your/preload_script.js"
      }
    ]
  }
  // ...
}

Call the OpenFin API within a custom Salesforce component

For Lightning web components

To use the API in a Lightning web component, you must first load the static resource as a third-party library.

With the static resource loaded, the API functions are added to window.fin.salesforce. Call the initFinApiInLwc() function before calling any OpenFin API functions via window.fin:

// Initialise window.fin for use
window.fin.salesforce.initFinApiInLwc();

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

Here is a complete example of a Lightning web component loading the static resource and using the OpenFin JS API:

// myComponent.js

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

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

    // Initialise window.fin for use
    window.fin.salesforce.initFinApiInLwc();

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

For 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>