# Implementation & Migration Guides

Source: https://docs.interop.io/adapters/salesforce/implementation-and-migration-guides/index.html

## 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](https://docs.interop.io/adapters/salesforce/legacy-adapter/installation-and-configuration/index.md) section.*

The following sections provide:

- Guidance on how to plan and execute [implementation strategies](#implementation_guide) for your interoperability solutions when using the Salesforce Adapter.

- Guidance on how to [migrate](#migrating_from_50_to_60) 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](#implementation_guide-ioconnect_desktop) | The Salesforce platform is opened as an io.Connect app in **io.Connect Desktop**. Use the `workspaceUtilityBar` and `workspaceBaseComponent` components. |
| [io.Connect Browser](#implementation_guide-ioconnect_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](#implementation_guide-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](#implementation_guide-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](#implementation_guide-context_synchronization) | `io_context` | `contextSyncUtilityBar`, `Fdc3ContextMixin` |
| [CRM API](#implementation_guide-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`](https://www.npmjs.com/package/@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](#implementation_guide-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](https://docs.interop.io/adapters/salesforce/usage/io-connect-platform/index.md) 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](#implementation_guide-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](https://docs.interop.io/adapters/salesforce/usage/io-connect-platform/index.md) 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](#implementation_guide-lightning_locker_organization) section.*

> ℹ️ *For more details, see the [Usage > Web Browser](https://docs.interop.io/adapters/salesforce/usage/web-browser/index.md) 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](https://docs.interop.io/adapters/salesforce/usage/lightning-message-service/index.md) 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](#implementation_guide-ioconnect_browser) and [io.Connect Desktop](#implementation_guide-ioconnect_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](https://docs.interop.io/adapters/salesforce/usage/context-synchronization/index.md) 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](#implementation_guide-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.