Distribute Your Upgrades

Learning Objectives

After completing this unit, you’ll be able to:

  • Explain how Salesforce helps you deliver updates without disrupting your customers.
  • List different ways you can deliver upgrades to your customers.
  • Describe the tools you can use to make upgrades easier on your customers.

Latest Version, Please!

In the last unit, you learned about package version numbers, which identify unique versions for managed packages.

Different versions of the same package can be, well, different. A major version change in an app can alter its behavior drastically. Even a minor version change can modify several things under the hood. Package version numbers help you protect your customers from disruptive change by forcing you to consider the impact of your changes on them.

As we mentioned, maintaining different versions of your product is less than ideal. Try to keep all your customers on a single version—the most recent version—of your product. This gives everyone the same experience, the latest bug fixes, and all the coolest features.

Let’s see how that is done.

Push Upgrades to Your Customers

If you really want your customers to use the latest version of your product, there’s an easy way to make sure they do: Use push upgrades. In a push upgrade, you push the latest version of your offering to your customers. They don’t have to do anything to complete the upgrade—they just use the new version once they have it.

You can use push upgrades for both upgrades (major or minor) and patches. When a push upgrade completes, customers see a new version number on their Package Detail page for the product. And, of course, they also see all your cool new features.

Communicate, Communicate, Communicate

We hope that by now we’ve sold you on push upgrades. Now you can pass the word on to your customers—they certainly want to hear about an upcoming push upgrade before they get it!

In upgrades, as in most activities, communication is essential. For a great set of guidelines in managing expectations and minimizing impacts, check out the ISVforce Guide.

How to Be Pushy

Here’s how a push upgrade works:

  • You select one or more customer orgs to upgrade.
  • You choose the version of your product to install on those orgs.
  • You schedule the upgrade for a given date and time.
  • You track the progress of the upgrade. Check to see whether it completes successfully, or abort a pending upgrade if you want to reschedule.

That’s the high-level view. You decide exactly how the upgrade works—which orgs get updated first, and what happens to each org.

With Great Power Comes Great Responsibility

Push upgrades give you control. You can distribute anything from a simple patch to a major overhaul of your product. You can upgrade a single customer or all of them.

Done correctly, a push upgrade can be seamless—everyone gets the new version and uses it. Done poorly, well... everyone who uses a computer knows what a botched upgrade looks like.

Use your judgment. If you’re adding lots of features or components, consider the impact:

  • Will the components work with existing installations?
  • Does your upgrade interfere with common customizations?
  • Does your upgrade modify customer data in a disruptive way?

New features are easy to manage—none of your customers use them until you ship your upgrade. Existing features are trickier. Try to preserve the way things work so that your customers stay productive.

AppExchange partners need special permission to push upgrades. To request Push Major Upgrade and Patch permissions, log a support case in the Salesforce Partner Community. For product, specify Partner Community & AppExchange. For topic, specify Security Review.

Great Power Isn’t Absolute Power

Push upgrades have their limits:

  • Upgraded permission sets don’t carry over tab visibility settings.
  • You can’t activate remote site settings automatically after installations.

Keep these in mind when you plan your deployment—you must coordinate upgrades of these sorts with your customers.

Automate the Details

Upgrades are trickier than fresh installs because they make changes to an existing system. And who knows what’s going on in a customer org?

Sometimes you need to do post-install work—tasks performed after the installation. For example, you can modify customer data to accommodate an updated formula or to fix inconsistencies. With our new Apex Metadata API, you can even update a page layout when you add a custom field to your package.

Salesforce lets you write an Apex class for post-install work. This class performs its work after your upgrade has been installed in an org.

What does such a class look like? Here’s a simple example:

 global class PostInstallClass implements InstallHandler {
 global void onInstall(InstallContext context) {
 if(context.previousVersion() == null) {
 // This means the package is being installed for the first time
 // Perform required activities for the first time install
 Account a = new Account(name='NewAccount');
 else if(context.previousVersion().compareTo(new Version(1,0)) == 0) {
 // This means the previous version is 1.0
 if(context.isUpgrade()) {
 // This means the package is getting upgraded
 // Perform required activities for package upgrades
 if(context.isPush()) {
 //This means the package is getting pushed
 //Perform required activities for push upgrades

Every new Apex class needs a test class, so here’s one for our example:

 static void testInstallScript() {
 PostInstallClass postinstall = new PostInstallClass();
 Test.testInstall(postinstall, null);
 Test.testInstall(postinstall, new Version(1,0), true);
 List<Account> a = [Select id, name from Account where name ='NewAccount'];
 System.assertEquals(a.size(), 1, 'Account not found');

Use the testInstall method of the Test class to test your PostInstall class. What goes into that method? You decide!

Thoughtful Automation

Automation is great when it works. Think about how best to use it with existing and new features.

For enhancements to existing features, use a post-install class to automatically assign any new permissions for feature components to existing users. That way, everyone can keep using the package without interruption.

Don’t use a post-install Apex script to auto-assign component permissions for new features. Instead, alert customer admins to these features and let them work out the details.

Schedule Your Upgrade

Now that you’ve defined your upgrade, it’s time to schedule it. Who gets the upgrade, and when? You can deploy an upgrade interactively, or use the Enterprise API to upgrade customers automatically.

To schedule a push upgrade interactively:

  1. Log in to your packaging org.
  2. From Setup, enter Packages in the Quick Find box, then select Packages.
  3. Select the name of the managed package to push.
  4. On the Package Detail page, select Versions and click Push Upgrades.
  5. Click Schedule Push Upgrade.  The Push Upgrade History section with a red square around the Schedule Push Upgrade button
  6. Select a package version from the Patch Version picklist.
  7. If you want to schedule a start date, enter the date in the Scheduled Start Date field.   The Schedule Push Upgrade section is where you select a package version and a start date for a push upgrade.
  8. In the Select Target Organizations section, select the orgs to upgrade. Orgs that you already upgraded don’t appear in this list. Click Schedule.  The Select Target Organizations section is where you use filters to generate a list of orgs that you want to update.

Use filters to select a list of orgs to update. You can filter orgs by:

  • Their partial or full name, or by org ID
  • Whether they are sandbox or production orgs
  • The version of your package they have installed

Schedule Upgrades with the Enterprise API

When you’re upgrading a lot of customers at once according to various rules and filters, interactive scheduling gets difficult. The Enterprise API allows you to schedule and control upgrades programmatically, and to track their progress. With the Enterprise API, you can:

  • Find the customers using your package with SOQL queries
  • Schedule push upgrades to these customers
  • Monitor the status of an upgrade, and check for errors

The API gives you plenty of flexibility for deploying upgrades. For example, you can create a web form that allows customers to upgrade to a new version. Clicking a button on the form can schedule a push upgrade for these customers.

We don’t describe how to use the Enterprise API here—it’s a bit more involved. The ISVforce Guide has detailed steps and code examples you can use to schedule your own push upgrades.

Track Changes

As you send updates to your customers, you can keep track of who already has the latest version of your package. To find the customers who have received a push upgrade:

  1. From your development org, click Setup.
  2. Enter Packages in the Quick Find box and select Packages.
  3. Click the name of your package and click Push Upgrades.
  4. Click the name of a target org to see the Push Upgrade Details page.   The Push Upgrades history page is where you select the org that you are upgrading.
  5. The Push Upgrade Details page has information about the push upgrade: its status (4), any scheduled start date (5), how long it takes to complete, the target org (6), and more.
  6. Navigate to the Organizations section, which shows a list of all the orgs to upgrade.
  7. Use the search box (7) to filter the orgs down to a list of customers whose upgrade status you want to search. Type an expression into the search box. Search for part or all of an org’s name, or for a complete org ID. You can also search by the status of the push upgrade using a picklist.  The Job Details section is where you select the orgs you want to track.

Update Your Listing

Customers love to see that an app is actively being updated, and it’s easy for them to check.  Each listing includes the latest release date.

An AppExchange listing with a red square around the latest release date

After you update your managed package, make sure your AppExchange listing matches your latest version.

  1. Log in to the Partner Community, navigate to the Publishing tab, and select the Packages subtab.
  2. By your latest package version, click Start Review. If a previous version of your managed package passed security review, then your latest version will automatically pass.
  3. After your new version passes, associate it with your listing.

a. Access the Publishing tab and select the Listings subtab.

b. Open your listing, select the App subtab, and click Select Package.

Change: The Only Constant

When you develop software, things change. Bugs get fixed, features get added, and algorithms and structures evolve. You’ve already dealt with changes on your own development team. Now you’ve seen how to deliver these changes to your customers.

Salesforce helps you:

  • Structure your changes by giving you two mechanisms to deliver them: patches and upgrades
  • Manage customer expectations for changes with a sensible version numbering system
  • Simplify maintenance by keeping your customers current with push upgrades

Use these tools to give your customers timely and seamless updates. As Salesforce customers, they expect all the benefits of Software as a Service. Keep the SaaS promise, and you can keep them happy.


Keep learning for
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities