Using Push Upgrade API to Automate Package Upgrade Process
As an ISV, you have created and listed a great application on the AppExchange. But this is just the beginning! You will have to go through various release cycles to fix bugs or add new features that your customers want. In Salesforce terms, you will have to “upgrade” your managed package to a newer version of your application. We assume that you know the different types of package upgrade types and are familiar with the versioning process.
If not, I recommend going through App Upgrading for AppExchange on Trailhead to learn more and get a shiny new badge.
What is a push upgrade?
Push upgrade is a technology that automates upgrades to your package on the customer/subscriber orgs. You can push an upgrade to all or any number of orgs that have installed your managed package.
Note: Push upgrades work only with managed packages, and are available to Salesforce partners who join partner program; please visit: partners.salesforce.com. If you’re already a member of the partner program, you can open a case in the partner community to have push upgrades enabled.
How do we use a push upgrade?
Push upgrades can be easily scheduled from the setup UI in the org where you have packaged your application. You can select the version of your app to be pushed, the organizations to which the upgrade should be pushed, and the date and time the push should begin. To learn how to push an upgrade via UI, refer to Scheduling Push Upgrade.
The ability to Push upgrades via UI is great, however, it does require you to be familiar with a specific click-path and can be quite tedious for multi-org upgrade pushes. This can also easily induce errors due to the manual nature of the process.
The other method to perform push upgrades is via the Push Upgrade API. The Push Upgrade API automates the push process, speeds it up, and makes it less error-prone.
Push Upgrade API
The push upgrade process can be accessed and managed with the Push Upgrade API. With push upgrades enabled, there are some API accessible standard objects that become available for use. It is important to understand these objects and what data they hold. Below is a list of these objects.
Clearly, there is some powerful information stored in these objects that can be queried and put to good use. The possibilities of leveraging this data to automate the release process and make it more efficient are endless. To get those creative juices flowing, check out the below example of what can be achieved with the Push Upgrade API.
Going back to the initial scenario where you have to go through the release cycle, let’s say have created a new version of your app with the latest and the greatest technology. You might have hundreds or thousands of customers who need the app upgrade. Often, some of your customers will not be ready to upgrade right away because they have their own development or release cycles in progress. What do you do now? Maybe, reach out to every one of them and capture their preferences in a spreadsheet? That is certainly not an efficient process, is time-consuming, and is error-prone. This is where you start to appreciate the power of push upgrades.
Below is a sequence diagram of an automation example that can be achieved.
Here are the detailed steps:
To get started, build a simple form which collects data from the customer as to when they want to upgrade to a particular/latest version at what date time. The form can be a VF page in your managed package, a community page, a simple public HTML page or a page hosted on your server/website that can collect the data and send the information to a custom Apex REST endpoint in your org where the app has been packaged. Let’s call this org the ISV Packaging Org.
- Your apex REST class endpoint will accept the information from the customer about their org id and the package details like the name, the version they want to upgrade to and the time at which they want the upgrade to happen.
- Use the Push Upgrade API to create a push request at the date and time requested by the customer.
- A push request is created and sent back with a PushRequestId.
- Create a package push job request using the PushRequestId from the previous step and the subscriber org Id.
- We get a job creation success or a failure message. Handle the failure and proceed if it is a success.
- Initiate a push for the desired date and time.
- A success or a failure message is returned. Handle the failure and proceed if it is a success.
- Notify the customer that the push request has been created
- The Push Upgrade Service will push the new version of the package directly to the customer org at the scheduled time.
I have built a POC implementation for this. Have a look at the GitHub code as a reference point to get an idea on how to implement this solution
Note: If you are using Java or .Net as your server back end, you can have your server gather the data and make calls using the Push Upgrade API. We also have some example code in the SOAP API Developer Guide under each of the push upgrade related objects that were mentioned above.
What are the possibilities?
The information push upgrade provides is very valuable. If you combine the License Management Application (LMA) data with this data, you can be more intelligent about your push upgrades. You can send email notifications to the subscriber org lead contacts and factor in other things like the timezone, location, etc. Instead of a customer requesting the push, you can do it at your end by building a lightning component with a UI that helps you automatically schedule push upgrades to multiples customers.
With great power comes great responsibility
Push Upgrades are very powerful. They automatically deliver new versions of your app to your customers without any effort on their end. It is your responsibility as an ISV to ensure you have a good communication plan with your customers before you deliver the upgrades to avoid any issues at their side. Trust and security are the fundamental Salesforce values which should be applied here, too. Make sure you are familiar with Push Upgrade Best Practices before you start using it.
Summary
Push Upgrade API is a powerful tool that can be leveraged to automate your package upgrade process to save time, make the process more efficient, and build trust with your customers. If you have any questions, post it on AppExchange & ISV Technical Enablement on the Partner Community.
Resources
Github code
Push Upgrades
Push Upgrade API
TrailheaDX Video Recording: Automate Release Process via Package and Deploy APIs
Push Upgrade Best Practices
