Distribute Your Upgrades
Learning Objectives
After completing this unit, you’ll be able to:
- 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 your managed packages.
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 after they have it.
You can use push upgrades for major or minor updates, and new patch versions. 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!
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 app 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.
Salesforce strongly recommends that push upgrades are scheduled to occur during off-peak business hours.
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 app. 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.
Salesforce partners need special permission to push upgrades. To request access, log a support case in the Salesforce Partner Community (login required).
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 Apex Metadata, 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');
insert(a);
}
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:
@isTest
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?
Schedule Upgrades with the SOAP API
SOAP API lets you schedule and control upgrades programmatically, and to track their progress. With SOAP 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 SOAP API here—it’s a bit more involved. The Second-Generation Managed Packaging Developer Guide outlines how you can schedule your own push upgrades.
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.
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.