Application Adapters Documentation

Salesforce

Overview

⚠️ Note that the following sections are relevant only for the latest versions of the Salesforce Adapter (6.0 and later).

ℹ️ For details on the legacy versions (3.0 and 4.0), see the Legacy Adapter section.

The following sections provide:

  • Guidance on how to plan and execute implementation strategies for your interoperability solutions when using the Salesforce Adapter.

  • Guidance on how to migrate an existing 5.0 installation to 6.0.

Implementation Guide

This guide describes the different use cases and the respective strategies for composing complete interoperability solutions when using the Salesforce Adapter.

The decisions described here will determine which components you will use, how they will connect to the io.Connect platform, and what you will need to configure in your Salesforce organization.

The following factors will determine your implementation strategy:

  1. The environment in which Salesforce runs - within the io.Connect platform (io.Connect Desktop or io.Connect Browser), or in a standalone web browser.

  2. The security architecture of your Salesforce organization - Lightning Web Security or Lightning Locker.

  3. The optional modules included in your package build.

The first two factors will determine your implementation strategy. The third will determine which out-of-the-box functionalities you can add to it.

Implementation Scenarios

The following table lists the possible implementation scenarios:

Scenario Description
io.Connect Desktop The Salesforce platform is opened as an io.Connect app in io.Connect Desktop. Use the workspaceUtilityBar and workspaceBaseComponent components.
io.Connect Browser The Salesforce platform is opened as an io.Connect app in a new browser window or tab in io.Connect Browser. Use the workspaceUtilityBar and workspaceBaseComponent components.
Web Browser Salesforce is opened in a standalone web browser, outside the io.Connect platform. Use the webBrowserUtilityBar and webBrowserBaseComponent components.

If your organization is using Lightning Locker instead of Lightning Web Security, see the strategy described in the Lightning Locker Organization section.

The following table lists the functionalities you can add to a scenario, provided that your package build includes the respective module:

Functionality Module Components
Context Synchronization io_context contextSyncUtilityBar, Fdc3ContextMixin
CRM API crm_api CrmPlugin, crmUtilityBar, crmWebBrowserCrmUtilityBar

Composition Rules

The following rules apply to every scenario:

  • A Salesforce app is allowed a single connection to the io.Connect framework. Keep that connection in a Utility Bar component, as it's loaded once per app and stays connected while the user navigates between records, objects, and tabs.

  • Implement each interoperability-related functionality (e.g., registering an Interop method via io.interop.register()) as a separate plugin class inside the selected interop-enabled Utility Bar component. This enables you to develop and test each functionality independently. Plugins aren't available in organizations that use Lightning Locker.

  • Attach your Utility Bar component as a utility item that starts automatically. Otherwise, it will connect to the io.Connect framework and will register its Interop methods only after the user clicks the utility item.

io.Connect Desktop

The Salesforce platform is defined as an io.Connect app and is opened in an io.Connect Window or a Workspace. The platform components connect to the io.Connect framework through the injected @interopio/desktop library, so no Gateway credentials are needed.

To implement this scenario:

  1. Define Salesforce as an io.Connect app, enable auto injection of the @interopio/desktop library, and provide the preload script distributed with the Salesforce Adapter package.

  2. Create a Utility Bar component that extends workspaceUtilityBar and holds your interoperability logic in plugins.

  3. Attach your component to the Lightning app in which you want to use it.

⚠️ Note that this scenario requires Lightning Web Security. In organizations that use Lightning Locker, implement the Lightning Locker Organization scenario instead.

⚠️ Note that a Lightning Out app has no Utility Bar, so you must use the workspaceBaseComponent component when embedding Salesforce components in your own web app.

ℹ️ For more details, see the Usage > io.Connect Platform section.

io.Connect Browser

The Salesforce platform is defined as an io.Connect app and is opened in an io.Connect Window or a Workspace. Due to the security restrictions imposed by Salesforce, the app must be opened in a new browser window or tab, as it's impossible to embed the Salesforce platform in an <iframe>.

To implement this scenario:

  1. Define Salesforce as an io.Connect app in the configuration of your Main app and configure it to open in a new browser window or tab.

  2. Create a Utility Bar component that extends workspaceUtilityBar and holds your interoperability logic in plugins.

  3. Attach your component to the Lightning app in which you want to use it.

⚠️ Note that this scenario requires Lightning Web Security. In organizations that use Lightning Locker, implement the Lightning Locker Organization scenario instead.

⚠️ Note that using the platform components in io.Connect Browser projects is still an experimental feature, so enabling some of the io.Connect Browser functionalities may require additional development.

⚠️ Note that a Lightning Out app has no Utility Bar, so you must use the workspaceBaseComponent component when embedding Salesforce components in your own web app.

ℹ️ For more details, see the Usage > io.Connect Platform section.

Web Browser

Salesforce is opened in a standalone web browser and connects to the io.Connect Gateway over a WebSocket. This is the only scenario that requires connection settings and a user login.

To implement this scenario:

  1. Create a Utility Bar component that extends webBrowserUtilityBar and holds your interoperability logic in plugins, or use the available webBrowserUtilityBar component as it is.

  2. Attach your component to the Lightning app in which you want to use it.

  3. Provide the default connection settings for your organization, its users, or its user profiles, and configure the lifetime of the Gateway token.

  4. Wrap each of your components in the webBrowserBaseComponent component, which reaches the connection of the Utility Bar over the Lightning Message Service bridge.

⚠️ Note that the webBrowserBaseComponent component isn't available in organizations that use Lightning Locker. Apply the InteropConsumerMixin mixin to your components instead, as described in the Lightning Locker Organization section.

ℹ️ For more details, see the Usage > Web Browser section.

Lightning Locker Organization

Lightning Locker prevents you from creating Lightning Web Components that use components from another package or namespace, so a Lightning Message Service bridge is used instead. A broadcaster component owns the connection and relays Interop method invocations to and from your own components.

The consumer side of the bridge can't be imported across namespaces either, so it's distributed in an additional package, which is provided only to clients and for proof of concept projects.

To implement this scenario:

  1. Attach the lmsBroadcaster component to the Lightning app in which you want to use it.

  2. Install the additional package, which provides the InteropConsumerMixin mixin and a reference consumer component.

  3. Apply the InteropConsumerMixin mixin to each of your components, so that they can register and invoke Interop methods through the broadcaster.

⚠️ Note that only the Utility Bar components that use the Lightning Message Service bridge can be used in this scenario - lmsBroadcaster within the io.Connect platform, and webBrowserUtilityBar or its Aura wrapper interopio_Salesforce_Adapter in a web browser. The workspaceUtilityBar component doesn't work in organizations that use Lightning Locker.

⚠️ Note that the workspaceBaseComponent and webBrowserBaseComponent components aren't available either, as they must be referenced in the HTML file of your own component, which Lightning Locker prevents across namespaces.

⚠️ Note that plugins aren't available in this scenario, so you must keep your interoperability logic in your own components.

⚠️ Note that the bridge supports only registering and invoking Interop methods. The rest of the io.Connect APIs and the streaming Interop methods aren't available.

ℹ️ For more details, see the Usage > Lightning Message Service section.

Context Synchronization

The Context Synchronization module keeps the Contact record displayed in Salesforce synchronized with the context data of your other interop-enabled apps. It's an addition to the io.Connect Browser and io.Connect Desktop scenarios.

To add this functionality, either attach the available contextSyncUtilityBar component, or apply the Fdc3ContextMixin mixin to your existing Utility Bar component. Configure the module via the "sfContext" object in your io.Connect Channel definition or in the "customProperties" object of your Salesforce app definition.

ℹ️ For more details, see the Usage > Context Synchronization section.

CRM API

The CRM module provides the T42.CRM.* Interop methods, which enable your interop-enabled apps to create, read, update, and delete Salesforce records. The records and the fields available to these methods are configured via Custom Metadata types.

To add this functionality, add the CrmPlugin plugin to your own Utility Bar component, or attach one of the available Utility Bar components of the module, which use the plugin directly - crmUtilityBar for the io.Connect platform scenarios, or crmWebBrowserCrmUtilityBar for the Web Browser scenario.

Migrating from 5.0 to 6.0

The Salesforce Adapter 6.0 replaces the single monolithic package with a core SDK and a set of optional modules - Web Browser, CRM, Lightning Message Service, and Context Synchronization. A package build can now contain only the modules your organization actually uses, which reduces the installed footprint and allows a module to be updated without republishing everything else.

The interop-enabled components have been renamed after the mode in which they are used - with a workspace prefix for components running within the io.Connect platform, and with a webBrowser prefix for components running in a web browser.

The 6.0 release also removes items that have been deprecated since earlier versions, such as the Aura events of the legacy Glue42 package.

The following sections describe the breaking changes in 6.0 and the steps for migrating an existing 5.0 installation to 6.0.

Removed Components

The following components have been removed and replaced with identical components with new names:

Removed Component Replacement
interopConnectedComponentBase webBrowserBaseComponent
interopConnectedComponentStandalone workspaceBaseComponent
interopConnectedLightBase workspaceLightComponent
interopSalesforceAdapter webBrowserUtilityBar (crmWebBrowserCrmUtilityBar for the CRM variant)
lmsStandalone lmsBroadcaster

Update both the HTML tag and the JavaScript import path in every component that uses a renamed component.

Removed Aura Events

The following duplicate Aura events of the legacy Glue42 package have been removed:

Removed Event Replacement
GlueConnectionStatus ConnectionStatusResponse
GlueCustomInteropEvent HandleInteropEvent
glueInvoke TriggerInteropEvent
ResendGlueConnectionStatus ConnectionStatusRequest

Other Breaking Changes

  • The Mapping__c and Mapping_Field__c custom objects have been removed. The T42.CRM.SyncRecord method is now configured via Custom Metadata types.
  • The ApexExportsMixin mixin must be imported from crmMixins instead of from workspaceUtilityBar.
  • The workspaceUtilityBar component no longer exposes the <c-constants> component to Aura.

Migration Guide

The renamed components replace their 5.0 counterparts instead of aliasing them, so a 5.0 installation can't be upgraded in place. Salesforce won't allow uninstalling the 5.0 package while a Lightning page, a Lightning app, or a FlexiPage still references any of its components.

To make the migration process easier, you can request a 6.0 package to be produced for you under a namespace different from the one used by your existing 5.0 installation. This will enable both versions to run side by side, so that interoperability remains available to your users while you rework your pages:

  1. Install the 6.0 package under the new namespace, alongside the existing 5.0 package.

  2. Move your pages and components to the new namespace one at a time, replacing the removed components with their 6.0 equivalents and validating each page before moving to the next one.

  3. Uninstall the 5.0 package once no references to the old namespace remain.

  4. Assign the new permission set groups to your users - "User of 'interop.io Salesforce Adapter'" or "Administrator of 'interop.io Salesforce Adapter'". Skip this step if your build doesn't include the Web Browser or the CRM module.