Push upgrade documentation

Question

I've found great information on patch and push upgrades in the Salesforce Packaging Guide and help notes. Although the steps for creating patches are listed in detail in both areas of documentation, I cannot find the steps for creating major upgrades!

Please can someone share some documentation that details (major) push upgrades in detail?

Answer 1

You don't have to create a major upgrade as such. I have been through the process several times but never read/found any official documentation. If you want the steps to create one then here they are - obviously you need to have the feature enabled for the package you're wanting to upgrade, this has in the past needed you to raise a case in the partner portal (I'm guessing this is still the same).

• Build your package as you would normally
• Go back to Setup | Create | Packages and select your package
• Go to the Versions tab and press the Push Upgrades button
• On the next page press the Schedule Push Upgrade
• Select the version you want to upgrade to and the Date/Time you want to do it
• Selecting the target version will bring up a list of the Orgs you can upgrade - select the ones you want and then press the Schedule button.

One thing worth noting is that it can take a long time to complete the upgrade. And it of course goes without saying that it's worth trying it out on a test org first.

Answer 2

You can push major releases just the same as you would a minor release.

From personal experience, going through the push process has several upsides.

1. creating any patch orgs gives you access to the source and config of historical releases,

2. enabling push upgrades avails a list of all orgs (with contact details) that ever installed your package,

Keep in mind that changes made in a patch org are (of course) not propagated to the packaging org.

So if patching your most recent version, make those same changes in the packaging org accordingly. Then distribute the patch instead of the package, until next major release.

Salesforce leverage their Streaming API to show real-time progress of the upgrades. My skinny packages took 2 minutes to make it into the first sandbox and 5 minutes to production.

You can cherry-pick which orgs to push your changes to. The job is abortable if you eyeball it failing anywhere, which is comforting.

The best official resource you could ask for is probably the Push Upgrade Best Practises which is below, verbatim:

Push Upgrade - Best Practices

Push Upgrade is a feature that you, as an ISV, can use to seamlessly upgrade managed packages installed in customer orgs from version X to version Y. This feature works only with managed packages and can be used to help ensure that all of your customers are on the same or latest version of your package.

At a high level, the feature can be described as:

• Upgrade your managed package installed in customer org from version X to version Y.
• Select one, many, or all customer orgs to upgrade and select a particular version to upgrade to.
• Schedule the upgrade to start at a particular date and time.
• View progress of upgrades, abort upgrades in progress, view result of push upgrade.
• In conjunction with push, you may use a Post-install Apex Script to automate many postupgrade configurations that your customers may have previously performed manually.

The full feature is described in detail in the ISVforce Guide.

The advantages of this feature include:

• Ensure all or most of your customers are on the same version of your application, simplifying and reducing your customer support needs and giving your customer access to the latest and best of your application.
• Automate upgrades so that your customers don't have to manually pull and install the latest package version.

Push Upgrade is one of the most powerful features that we have released to our ISV community.

You have the power to upgrade your customers, but please use that power carefully.

Salesforce upgrades customers in a way similar to Push Upgrade, and we have invested in finetuning the process and we strongly urge you to adhere to the best practices documented here.

Remember, the Push Upgrade feature used incorrectly could result in significant customer satisfaction issues.

Please follow these best practices as you start using the Push Upgrade feature.

Plan, Test and Communicate

1. Communicate, communicate and communicate some more. Your customers may not even know about the Push Upgrade feature. Some may have strong reservations about changes being pushed to their orgs. Talk to them and explain how the SaaS model works, how they can benefit from seamless upgrades, how you are using best practices to ensure a smooth upgrade and what your process and commitment is to them regarding the timing and content of a new package. Communication is the key for the success of this program. Share an upgrade timeline plan with your customers so that they know when you will upgrade, and how often.

2. Plan when you want to push upgrades to your customers' orgs. Keep in mind that most customers don't want changes around their month end, quarter end and year-end or audit cycles. Do your customers have other time periods that are critical when they don't want any changes to their org or when they may not have available staff to verify changes or perform any needed post-installation steps?

3. Schedule push upgrades during your customer's off-peak hours - late evenings and night. Have you considered time zone issues? Do you have customers outside USA who have different off-peak hours? As the Push Upgrade feature allows you to schedule any number of customer orgs at a time, consider grouping orgs by time zone, if business hours vary widely across your customer-base

4. Don't schedule push upgrades anywhere near Salesforce planned maintenance windows. In most cases, it might be better to wait 3-4 weeks after a major Salesforce release before you push out major upgrades.
5. Since you are pushing changes to the org instead of the customer pulling in changes, there is a still higher bar for you to ensure that the new version of your app works well and works in all customer configurations. Test, test and test!

Stagger the Push

1. Don't push changes to all customers at once. You need to ensure that you have bandwidth to handle support cases if there are issues. Also, you will want to discover any additional issues before your entire customer base is affected.
2. Push to your own test orgs first to see that push happens seamlessly. Log in to your test org after the push upgrade and test to see that everything works as expected.
3. When applicable, push to the sandbox orgs of your customers first before pushing to their production orgs. Give them a week or more to test/validate/fix in the sandbox environment before pushing to their production orgs.
4. Push to small batches of customer production orgs initially. For example if you have 1,000 customers, push upgrade 50 or 100 customers at a time, at least the first few times. Once you gain confidence, you can upgrade customers in larger batches.

Customer Trust is Paramount

1. You are responsible to ensure that your customers' orgs are not adversely affected by your new package. Avoid making changes to the package, such as changes to validation rules or formula fields, that may break external integrations made by the customer. If for some reason you do, test and communicate well in advance. Please keep in mind that you could impact customer data, not just metadata, by pushing an upgrade with bugs.
2. Write an Apex test on install to do basic sanity testing to see that the basic app works.
3. If you are enhancing an existing feature, use a post install script to automatically assign new components to existing users using permission sets. See the ISVforce Guide for more details.
4. If you are adding a new feature, don't auto-assign the feature to existing users. Communicate and work with the administrators of the customer org so they can make the determination and assignment regarding who should have access to the new feature, and what the timing of their roll-out should be.