First-Generation Managed Packaging Developer Guide

First-Generation Managed Packages
Why Switch to Second-Generation Managed Packaging?
Move to 2GP: Migrate Your Managed Packages with Ease
About Package Conversion and Package Migration
Three Phases of Package Migration Development
Plan Your Package Migration
Before You Begin Package Migrations
Convert Your Managed 1GP Package to 2GP
Migrate Your Subscribers from 1GP to 2GP
Move to 2GP Package Development
Considerations for Package Migrations
Troubleshoot Package Conversion Failures
Register a Namespace for a First-Generation Managed Package
Create a First-Generation Managed Package Using a UI
Create a First-Generation Managed Package using Salesforce DX
Components Available in First-Generation Managed Packages
Behavior of Specific Metadata in First-Generation Managed Packages
Package and Test Your First-Generation Managed Package
Update Your First-Generation Managed Package
Publish Upgrades to First-Generation Managed Packages
Manage Licenses for Managed Packages
Manage Features in First-Generation Managed Packages
AppExchange App Analytics for First-Generation Managed Packages
Developing and Distributing Unmanaged Packages
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Migrate Your Subscribers from 1GP to 2GP

Are you ready to migrate your converted package? To migrate a package you install the converted 2GP package into a subscriber org that already has the managed 1GP package version installed. Package migration requires that the major and minor version of the subscriber's installed package, match the major and minor version of 2GP you’re installing.

After a package is migrated there’s no change to the metadata or customer data associated with the package.

If your package has dependencies on other packages, the order in which you migrate the base and dependent packages is important. For more details, see Plan Your Package Migration.

Bulk Migrate Multiple Subscribers (Beta)

To migrate multiple subscribers that all have the same package version installed, use the Salesforce CLI command to schedule a push upgrade and specify the --migrate-to-2gp flag. Remember the major.minor.patch version of the package you're migrating, must be identical to the major.minor.patch version installed in a subscriber org.

The subscriber package version ID (starts with 04t) that you specify when migrating a package version, must be the ID for the converted 2GP package version, not the ID for the original 1GP package version.

Example:

1sf package push-upgrade schedule --migrate-to-2gp --package-version 04txyz --scheduled-start-time "2024-12-06T21:00:00" --org-file upgrade-orgs.csv

Push upgrades for package migrations have a daily limit. Currently, you can use push upgrades to migrate 5 subscriber orgs per day.

Push migrations is a beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this beta service is at the Customer's sole discretion.

Note

Before migrating customers using push upgrades, please review these best practices. In particular, we strongly recommend that you work with your subscribers and follow a staggered approach, starting by migrating sandboxes first, before carrying out migrations in production.

Before migrating customers using push upgrades, please review these best practices. In particular, we strongly recommend that you work with your subscribers and follow a staggered approach, starting by migrating sandboxes first, before carrying out migrations in production.

Note

Manually Migrate One Subscriber

If you have subscribers who don't allow push upgrades to their org, they can manually upgrade to the 2GP package. Provide them with the package installation URL and they can migrate the package.

Push Upgrade History and Org Migrations

From time to time, Salesforce migrates production orgs from one instance to another. If your Dev Hub org is scheduled for an org migration, it's crucial to back up your historical data related to push upgrades and 2GP migrations, as this data won't be retained post-migration.