Decide What to Deliver

Learning Objectives

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

  • Define patches and upgrades and give examples of each.
  • Explain the significance of package version numbers.
  • Describe how to create a patch and an upgrade.

Business Is Booming! What's Next?

As the lead developer for PartnerX, you’re proud to report that your AppX is a hit on AppExchange. You’re getting feedback from your customers and brainstorming your next steps. There’s no shortage of ideas on how to improve AppX.

So what do you prioritize, and how do you deliver improvements? Answering these questions takes planning. Your customers are already using your solution, so some changes are tricky to deploy. Ideally, you can keep AppX’s upgrade process just as awesome for your customers as the rest of their experiences are.

Plan Your Updates

The updates you make to your product come in two flavors:

  • Patches—Minor changes, such as cosmetic UX updates or bug fixes, which don’t affect your product’s behavior.
  • Upgrades—New or major changes to functionality that alter the behavior of the product and the way that customers interact with it.

Suppose you find an inconsistent label you want to fix. Or perhaps you’re just fixing a glitch in a formula for updating customer data. These changes make great patches.

For that amazing new feature you promised to your customers, use an upgrade. Upgrades let you make significant changes, like introducing better workflows or changing your data model.

Before we go any further, let’s take a look at a simple tool for conveying information about changes to our customers: version numbers.

Package Versions

We’ve all seen software version numbers. Broadly speaking, bigger numbers mean better products. That’s the hope, anyway!

Salesforce provides a nice, easy format for versioning your product’s package. Let’s look at the latest version of AppX:

AppX version 2.1.3

This version number has three parts:

  • A major version number (2). Changes to major version numbers indicate large, sweeping changes to a product.
  • A minor version number (1). A minor version number changes when you add a feature or change something noticeable in your product, but things still work essentially the same as before.
  • A patch version number (3). Patch version numbers change every time you update your product with a patch.

Patch version numbers are easy to manage—they change automatically every time you create a patch for your package.

Major and minor version numbers change when you make an upgrade for your product. The biggest difference between major and minor versions is that customers typically don’t have to change the way they use an app when they do a minor version upgrade.

Is your upgrade a major change or a minor one? You decide. Use the version number to manage customer expectations.

How do you actually change your package? Let’s start with patches, since they’re easiest.

Create a Patch

Use a patch when you make a change that doesn’t affect the underlying data model or business logic. Patches can be created only off a major release, and only for a managed package.

When you create a patch, you do the work in a patch development org. This is a special org that allows only changes that don’t break existing installations. If you’re an AppExchange partner, you can create a patch development org after you log a support case in the Salesforce Partner Community to get the right permission. For product, specify Partner Community & AppExchange. For topic, specify Security Review.

When you work in a patch development org, you can’t:

  • Add new package components, web services, or dependencies
  • Delete existing package components or deprecate any Apex method
  • Change API or dynamic Apex access controls

For a complete list of restrictions, refer to the ISVforce Guide.

You create a patch development org using your packaging org, not your environment hub. You can connect a patch org to your environment hub after you create it.

To create a patch org:

  1. From Setup in your packaging org, enter Packages in the Quick Find box, then select Packages.
  2. Click your managed package, then the Patch Organization tab, and click New.
  3. Select the package version that you want to patch from the Patching Major Release picklist. The release type must be Managed - Released.
  4. Enter a username for a login to your patch organization, and an associated email address. A username is generated once you select the version (see the screenshot below), but you can change it. The email address should be your main email where you receive org logins and password resets. These are specific to your patch development org. The Create Patch Development Organization section of the Package Manager is where you enter a username and email address for your new patch development org.
  5. Click Save.

The Patch Development Cycle

Suppose you’re making changes to version 2.0 of your app. You create a patch org and create two patches there, versions 2.0.1 and 2.0.2. Later, you merge these patches into version 3.0, which you distribute as an upgrade.

A patch is created from a major version, developed within a patch development org, and merged back into the main development org for a major or minor upgrade.

When you merge your patches into version 3.0, you’re finished with this patch org. Create another patch org for any patches to version 3.0.

For the nitty-gritty details, see the ISVforce Guide.

Create an Upgrade

You’ve got major changes in the works—new objects and business logic, Lightning components—and you want your customers to get them. For that, you create an upgrade for your package. You can upgrade only a managed package.

Some components can’t be upgraded. The ISVforce Guide has information about which components are upgradeable.

Create a New Version of Your Package

Before you start, decide whether your upgrade deserves a major or minor version change. This alerts your customers to what they’re in for.

If you want to remove a component from your package, log a support case in the Salesforce Partner Community to enable the Component Deletion permission in your packaging org. For product, specify Platform. For topic, specify AppExchange & Managed Packages. You can delete only certain components—see the ISVforce Guide for the details.

Create an upgrade the same way you create a new managed package:

  1. From Setup in your development org, enter Packages in the Quick Find box, then select Package Manager. Then select the package from the list of available packages. The      Package The Package Manager page is where you select your package.
  2. Any components you change appear in the Component sub-tab, along with any new dependencies. To add a component manually, click AddThe Package Detail page is where you add components to your package.
  3. Select the appropriate Component Type, check the checkbox beside the desired component, and click Add to Package. Below we add Active and Customer Priority custom fields. The Package Detail page is where you add custom components and fields to your package.
  4. When you’re ready to create the package, click Upload to create a new version of the package. This brings up the Upload Package page. The Upload Package page is where you enter the details of your package before uploading it.
  5. In the Version Name field, name this version of your package so it’s consistent with your previous versions. The Version Number field contains a suggested version number that you can override.
  6. Click Upload again to finish the package creation.
  7. You receive an email with a link to the package on AppExchange. Share this link with your customers who want to install this upgrade manually. Use the list of installed users from the License Management Application to spread the word.

Simplify, Simplify

The package manager lets you deprecate older versions of your package. That prevents customers from installing these versions, though existing installs continue to work. This makes maintenance easier.

The Package Detail page is where you can deprecate older versions of your app.

We’ll get back to maintenance in the next unit.

Finish Up

You’ve made all the changes you’re going to make, rigorously tested them, and uploaded your managed package. You’re just about finished. There are only a few things left to do before you deliver the goods to your customers.

Security Review

If you have a product on AppExchange, you know that trust is our number one priority at Salesforce. After all, your app made it through our security review process. Your patches and upgrades must meet the same security standards as your app.

Now some good news: You don’t have to go through a full security review for every patch or upgrade. When you update your product’s listing, the Salesforce security operations team reviews your code within 24 hours.

For a refresher on our Security Review process, check out the AppExchange Security Review module.

Update Your App listing

Now that your shiny new product is ready, it’s time to update your AppExchange listing.

  1. From the Salesforce Partner community, navigate to Publishing. Then select your listing. The Listings tab of the Publishing Console is where you select your app’s listing.
  2. Navigate to the App tab. Under “What package do you want to link to this listing?” click Select PackageThe App tab of the Publishing Console is where you update your app’s listing.
  3. Select your package from the list. The list of available packages that you select from
  4. Click SaveThe App tab of the Publishing Console with a red square around the Save button

Update Your Free Trial

You’re using Test Drive or Trialforce to offer your customers a free trial of your product, aren’t you? Of course you are! Let’s update your trial while we’re at it. How you do this depends on the type of trial you offer.

  • Installable Trial—Your customers install your trial in their own org. Make sure your listing is up to date, and your customers can simply install your new version.
  • Test Drive or Trialforce—Install your new version in your Trial Source Org and create a new trial template. Don’t forget to update any test data and submit your template for security review.

If you aren’t offering free trials to your customers, head to the AppExchange App Trial Management module to learn about them.

And that’s it! The new version of your product is ready to go. Now let’s look at how you distribute updates to your customers, SaaS-style.


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