Prepare Your AppExchange App to Support Org Migrations

Special thanks to my co-author Mike Faust.

As a Salesforce AppExchange partner, your subscribers’ orgs can live anywhere — from our first-party data centers or third-party data centers such as Hyperforce or Government Cloud. Subscriber orgs can move instances within the same data centers or they can migrate between both first party and third party (public cloud) data centers. As Hyperforce’s footprint expands, an increasing number of subscribers will be running on Hyperforce. As of today, an org can be created directly on a Hyperforce instance, while existing customers will most likely go through an org migration.

Org migrations of any type require customers to perform a series of checks prior to migration. As an app publisher, it’s vitally important for your customers that your application can support and pass these checks. Let’s cover how to ensure a smooth process for org migrations.

How to Make Your AppExchange Package Org Migration Friendly

Let’s discuss two important items for AppExchange partners to address so their application will continue to work through an org migration: removing hard-coded references and allowing all appropriate Salesforce IP ranges and domains. These items apply to your package as well as to any modifications made by your customers. If your customers extend your application, it’s important to also highlight this in your documentation.

1. Remove Hard-Coded References

Hard-coded references are links in code or metadata which refer to a specific Salesforce instance. For example, the URL https://ap28.salesforce.com is a hard-coded reference to the AP28 instance. A link like this will fail if and when the target org on AP28 migrates to another instance.

To prevent this, ensure that links within your application refer to instance-less URLs like https://login.salesforce.com or https://<mydomain>.my.salesforce.com.

Important Note: For Government Cloud, https://login.salesforce.com is not supported. Login access is available only through My Domain.

My Domain lets a customer specify a name to include in their Salesforce org URLs. In addition to enabling consistent access through org migrations, My Domain is also a requirement for a lot of functionality including SSO and Lightning. As of Winter ‘22, all Salesforce orgs must have a My Domain enabled. This is enforced.

For links within an org you can use relative URLs like /{Account.Id} instead of a full path.

You can also take advantage of the tools available within the platform to programmatically create URLs such as the URLFOR function or the Apex URL Class.

2. Allow All Appropriate Salesforce IP Ranges and Domains

For your integrations, Salesforce recommends allowing all Salesforce IP addresses and domains in your firewall filters. Salesforce also recommends bookmarking and regularly checking the document to ensure that you are keeping up as Salesforce updates its infrastructure.

For Hyperforce, it is crucial that all required Salesforce domains are enabled in order to maintain connectivity to customers on Hyperforce instances.

To help you ensure your application meets these and other best practices, use the ISV Technical Enablement Plugin for SalesforceDX. This plugin is able to scan your package for hard-coded references and tell you where to fix them.

Summary

Org migrations are an ongoing part of the Salesforce platform, and will only increase in importance as more instances are created in third-party data centers for uses like Hyperforce and Government Cloud. To ensure your app functions through an org migration, it is important to never assume you know where any org will exist by removing URLs that include instance names and to ensure that any external endpoints allow connections from all potential instance IP addresses.

To learn more about org migrations, refer to the resources below.

Resources:
Prepare for an Org Migration
Updating Hard-Coded References
Hyperforce FAQ
Government Cloud for ISVs