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
-
In the Salesforce org, create a new static resource.
-
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:
-
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
. -
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>
Updated 27 days ago