in implementation guides ~ read.
Apps

Apps

DOWNLOAD

First things first !
To download this implementation guide, click the download button below.
If you need more information about the implementation guide, you can read the Table of Contents below.

Download

Package and Distribute Your
Apps
Salesforce Summer

salesforcedocs
Last updated May

Copyright salesforcecom inc All rights reserved Salesforce is a registered trademark of salesforcecom inc

as are other names and marks Other marks appearing herein may be trademarks of their respective owners

CONTENTS

Package and Distribute Your Apps
Work with Packages
Distribute Your Apps
Support Subscribers of Your App

PACKAGE AND DISTRIBUTE YOUR APPS

Want to distribute opensource projects to provide developers with the basic building blocks for an application Or distribute and sell
applications to customers Packages let you do all that and more
Find additional information in the ISVforce Guide or visit the Salesforce Partner Portal

IN THIS SECTION

Work with Packages
Create managed and unmanaged packages
Distribute Your Apps
Upload your apps publish extensions and upgrades and manage versions
Support Subscribers of Your App
Support AppExchange customers view subscriber organizations and details

Work with Packages
Create managed and unmanaged packages

IN THIS SECTION

Understanding Packages
Glossary
Creating Managed Packages
Manage Packages
View Package Details
Determining Your Development Process
Resolving Apex Test Failures
Running Apex on Package InstallUpgrade
Running Apex on Package Uninstall
Developing App Documentation
Assigning Salesforce AppExchange Publishers
Convert Unmanaged Packages to Managed

Package and Distribute Your Apps

Understanding Packages

Understanding Packages

A package is a container for something as small as an individual component or as large as a set of

related apps After creating a package you can distribute it to other Salesforce users and
organizations including those outside your company
Packages come in two formsunmanaged and managed
Unmanaged packages
Unmanaged packages are typically used to distribute opensource projects or application
templates to provide developers with the basic building blocks for an application Once the
components are installed from an unmanaged package the components can be edited in the
organization they are installed in The developer who created and uploaded the unmanaged
package has no control over the installed components and cant change or upgrade them
Unmanaged packages should not be used to migrate components from a sandbox to production
organization Instead use Change Sets
As a best practice install an unmanaged package only if the org used to upload the package
still exists If that org is deleted you may not be able to install the unmanaged package
Managed packages
Managed packages are typically used by Salesforce partners to distribute and sell applications
to customers These packages must be created from a Developer Edition organization Using

the AppExchange and the License Management Application LMA developers can sell and

manage userbased licenses to the app Managed packages are also fully upgradeable To
ensure seamless upgrades certain destructive changes like removing objects or fields can not
be performed
Managed packages also offer the following benefits
Intellectual property protection for Apex

EDITIONS

Available in Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Developer
Edition
Package uploads and
installs are available in
Group Professional
Enterprise Performance
Unlimited and Developer
Editions

USER PERMISSIONS

To create packages
Create AppExchange
Packages
To upload packages to the
AppExchange
Upload AppExchange
Packages

Builtin versioning support for API accessible components

The ability to branch and patch a previous version
The ability to seamlessly push patch updates to subscribers
Unique naming of all components to ensure conflictfree installs
The following definitions illustrate these concepts
Unmanaged and Managed Packages

Components

A component is one constituent part of a package It defines an item such as a custom object or a custom field You can combine

components in a package to produce powerful features or applications In an unmanaged package components are not upgradeable
In a managed package some components can be upgraded while others cant

Package and Distribute Your Apps

Glossary

Attributes
An attribute is a field on a component such as the name of an email template or the Allow Reports checkbox on a custom
object On a nonupgradeable component in either an unmanaged or managed package attributes are editable by both the developer
the one who created the package and the subscriber the one who installed the package On an upgradeable component in a
managed package some attributes can be edited by the developer some can be edited by the subscriber and some are locked
meaning they cant be edited by either the developer or subscriber
For information on which components can be included in a package and which attributes are editable for each component see the
ISVforce Guide
Packages consist of one or more Salesforce components which in turn consist of one or more attributes Components and their attributes
behave differently in managed and unmanaged packages
If you plan to distribute an app it is important to consider packaging throughout the development process For example
While creating your app consider how components and their attributes behave in different packages and Salesforce editions
While preparing your app for distribution consider how you want to release it to your customers
While installing a package consider your organizations security and license agreements

SEE ALSO

Manage Packages
Prepare Your Apps for Distribution

Glossary
The following terms and definitions describe key application and packaging concepts and capabilities
App

Short for application A collection of components such as tabs reports dashboards and

Visualforce pages that address a specific business need Salesforce provides standard apps such
as Sales and Service You can customize the standard apps to match the way you work In
addition you can package an app and upload it to the AppExchange along with related
components such as custom fields custom tabs and custom objects Then you can make the
app available to other Salesforce users from the AppExchange
AppExchange
The AppExchange is a sharing interface from Salesforce that allows you to browse and share
apps and services for the Lightning Platform

EDITIONS

Available in Salesforce
Classic not available in all
orgs
Available in Group
Professional Enterprise
Performance Unlimited
and Developer Editions

Beta Managed Package
In the context of managed packages a beta managed package is an early version of a managed package distributed to a sampling
of your intended audience to test it
Deploy
To move functionality from an inactive state to active For example when developing new features in the Salesforce user interface
you must select the Deployed option to make the functionality visible to other users
The process by which an application or other functionality is moved from development to production
To move metadata components from a local file system to a Salesforce organization
For installed apps deployment makes any custom objects in the app available to users in your organization Before a custom object
is deployed it is only available to administrators and any users with the Customize Application permission

Package and Distribute Your Apps

Glossary

License Management Application LMA

A free AppExchange app that allows you to track sales leads and accounts for every user who downloads your managed package

app from the AppExchange

License Management Organization LMO

The Salesforce organization that you use to track all the Salesforce users who install your package A license management organization

must have the License Management Application LMA installed It automatically receives notification every time your package is

installed or uninstalled so that you can easily notify users of upgrades You can specify any Enterprise Unlimited Performance or
Developer Edition organization as your license management organization For more information go to
httpwwwsalesforcecomdocsenlmaindexhtm
Major Release

A significant release of a package During these releases the major and minor numbers of a package version increase to any chosen

value
Managed Package

A collection of application components that is posted as a unit on the AppExchange and associated with a namespace and possibly

a License Management Organization To support upgrades a package must be managed An organization can create a single
managed package that can be downloaded and installed by many different organizations Managed packages differ from unmanaged
packages by having some locked components allowing the managed package to be upgraded later Unmanaged packages do not
include locked components and cannot be upgraded In addition managed packages obfuscate certain components like Apex on
subscribing organizations to protect the intellectual property of the developer
Managed Package Extension
Any package component or set of components that adds to the functionality of a managed package You cannot install an extension
before installing its managed package
Namespace Prefix
In a packaging context a namespace prefix is a one to character alphanumeric identifier that distinguishes your package and its

contents from packages of other developers on AppExchange Namespace prefixes are caseinsensitive For example ABC and abc

are not recognized as unique Your namespace prefix must be globally unique across all Salesforce organizations It keeps your
managed package under your control exclusively
Package

A group of Lightning Platform components and applications that are made available to other organizations through the AppExchange

You use packages to bundle an app along with any related components so that you can upload them to AppExchange together
Package Dependency
This is created when one component references another component permission or preference that is required for the component
to be valid Components can include but are not limited to
Standard or custom fields
Standard or custom objects
Visualforce pages
Apex code
Permissions and preferences can include but are not limited to
Divisions
Multicurrency
Record types

Package and Distribute Your Apps

Glossary

Package Installation

Installation incorporates the contents of a package into your Salesforce organization A package on the AppExchange can include

an app a component or a combination of the two After you install a package you may need to deploy components in the package
to make it generally available to the users in your organization
Package Version

A package version is a number that identifies the set of components uploaded in a package The version number has the format

majorNumberminorNumberpatchNumber for example The major and minor numbers increase to a chosen
value during every major release The patchNumber is generated and updated only for a patch release

Unmanaged packages are not upgradeable so each package version is simply a set of components for distribution A package version

has more significance for managed packages Packages can exhibit different behavior for different versions Publishers can use
package versions to evolve the components in their managed packages gracefully by releasing subsequent package versions without
breaking existing customer integrations using the package See also Patch and Patch Development Organization
Patch

A patch enables a developer to change the functionality of existing components in a managed package while ensuring subscribing

organizations that there are no visible behavior changes to the package For example you can add new variables or change the
body of an Apex class but you may not add deprecate or remove any of its methods Patches are tracked by a patchNumber
appended to every package version See also Patch Development Organization and Package Version
Patch Development Organization
The organization where patch versions are developed maintained and uploaded Patch development organizations are created
automatically for a developer organization when they request to create a patch See also Patch and Package Version
Patch Release

A minor upgrade to a managed package During these releases the patch number of a package version increments

Publisher
The publisher of an AppExchange listing is the Salesforce user or organization that published the listing
Push Upgrade

A method of delivering updates that sends upgrades of an installed managed package to all organizations that have installed the

package
Subscriber
The subscriber of a package is a Salesforce user with an installed package in their Salesforce organization
Test Drive

A test drive is a fully functional Salesforce organization that contains an app and any sample records added by the publisher for a

particular package It allows users on AppExchange to experience an app as a readonly user using a familiar Salesforce interface
Unmanaged Package

A package that cannot be upgraded or controlled by its developer

Upgrading
Upgrading a package is the process of installing a newer version Salesforce supports upgrades for managed packages that are not
beta
Uploading

Uploading a package in Salesforce provides an installation URL so other users can install it Uploading also makes your packaged

available to be published on AppExchange

SEE ALSO

Build Your Own Salesforce App

Package and Distribute Your Apps

Creating Managed Packages

Creating Managed Packages
Creating a managed package is just as easy as creating an unmanaged package The only requirement
to create a managed package is that youre using a Developer Edition organization

EDITIONS

Before creating a managed package

Available in Salesforce
Classic not available in all
orgs and Lightning
Experience

Review the information about managed packages in the ISVforce Guide to determine if this is
the right type of package for your app

Optionally install the License Management Application LMA from

httpsitesforcecomappexchange Search for License Management App to locate

it The License Management Application LMA tracks information about each user who installs

your app It allows you to track what users have which version giving you a means of distributing
information about upgrades

The License Management Application LMA can be installed in any Salesforce organization

except a Personal Group or Professional Edition organization and does not need to be the
same Salesforce organization that you use to create or upload the package although it can be

You can also use the same License Management Application LMA to manage an unlimited

number of your managed packages in different Developer Edition organizations
Configure your developer settings Your developer settings specify your namespace prefix the

Salesforce organization where you install the License Management Application LMA and the

unmanaged package you want to convert into a managed package

IN THIS SECTION

Available in Developer
Edition
Package uploads and
installs are available in
Group Professional
Enterprise Performance
Unlimited and Developer
Editions

USER PERMISSIONS

To enable managed
packages
Customize Application
To create packages
Create AppExchange
packages

About Managed Packages
Configure Your Developer Settings

To upload packages
Download AppExchange
packages

Register a Namespace Prefix
Specifying a License Management Organization

SEE ALSO

Manage Packages
Convert Unmanaged Packages to Managed
Configure Your Developer Settings
Register a Namespace Prefix
Specifying a License Management Organization

Package and Distribute Your Apps

Creating Managed Packages

About Managed Packages

A managed package is a collection of application components that are posted as a unit on

AppExchange and are associated with a namespace and a License Management Organization

EDITIONS

You must use a Developer Edition organization to create and work with a managed package

Available in Salesforce
Classic not available in all
orgs and Lightning
Experience

Managed packages are depicted by the following icons

Managed Beta

Managed Released

Managed Installed

Available in Developer
Edition

Tip To prevent naming conflicts Salesforce recommends using managed packages for all
packages that contain Apex to ensure that all Apex objects contain your namespace prefix
For example if an Apex class is called MyHelloWorld and your orgs namespace is
OneTruCode the class is referenced as OneTruCodeMyHelloWorld

Package uploads and
installs are available in
Group Professional
Enterprise Performance
Unlimited and Developer
Editions

Configure Your Developer Settings
The developer settings in a Developer Edition organization allow you to create a single managed
package upload that package to the AppExchange allowing other users to install and upgrade the
package in their organization After configuring your developer settings the first time you can no
longer modify them Regardless of the developer settings you can always create an unlimited
number of unmanaged packages
To configure your developer settings
From Setup enter Packages in the Quick Find box then select Packages
Click Edit
Note This button doesnt appear if youve already configured your developer settings
Review the selections necessary to configure developer settings and click Continue
Register a namespace prefix
Choose the package you want to convert to a managed package If you do not yet have a
package to convert leave this selection blank and update it later

EDITIONS

Available in Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Developer
Edition
Package uploads and
installs are available in
Group Professional
Enterprise Performance
Unlimited and Developer
Editions

Click Review My Selections

USER PERMISSIONS

Click Save

To configure developer
settings
Customize Application

Tip You may want to specify a License Management Organization LMO for your managed

package to find out more go to httpsitesforcecomappexchangepublisherHome

SEE ALSO

Creating Managed Packages

To create packages
Create AppExchange
Packages
To upload packages
Upload AppExchange
Packages

Register a Namespace Prefix
Specifying a License Management Organization

Package and Distribute Your Apps

Creating Managed Packages

Register a Namespace Prefix
In a packaging context a namespace prefix is a one to character alphanumeric identifier that
distinguishes your package and its contents from packages of other developers on AppExchange

Namespace prefixes are caseinsensitive For example ABC and abc are not recognized as unique

Your namespace prefix must be globally unique across all Salesforce organizations It keeps your
managed package under your control exclusively
Important When creating a namespace use something thats useful and informative to
users However dont name a namespace after a person for example by using a persons
name nickname or private information
Salesforce automatically prepends your namespace prefix followed by two underscores to

all unique component names in your Salesforce organization A unique package component is one

that requires a name that no other component has within Salesforce such as custom objects
custom fields custom links scontrols and validation rules For example if your namespace prefix

is abc and your managed package contains a custom object with the API name Expensec use

the API name abcExpensec to access this object using the API The namespace prefix is

displayed on all component detail pages

EDITIONS

Available in Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Developer
Edition
Package uploads and
installs are available in
Group Professional
Enterprise Performance
Unlimited and Developer
Editions

Warning Scontrols stored in the scontrol library or the Documents tab that do not use

the Lightning Platform API still function properly after you register a namespace prefix

However scontrols stored outside of your organization or scontrols that use the Lightning

Platform API to call Salesforce may require some finetuning For more information see

Scontrol in the Object Reference
Your namespace prefix must
Begin with a letter
Contain one to alphanumeric characters
Not contain two consecutive underscores
For example myNp and mynp are valid namespaces but Company and mynp arent
To register a namespace prefix
From Setup enter Packages in the Quick Find box Under Create select Packages
Note This item is only available in Salesforce Classic
In the Developer Settings panel click Edit
Note This button doesnt appear if youve already configured your developer settings
Review the selections that are required for configuring developer settings and then click Continue
Enter the namespace prefix you want to register
Click Check Availability to determine if the namespace prefix is already in use
If the namespace prefix that you entered isnt available repeat the previous two steps
Click Review My Selections

Package and Distribute Your Apps

Creating Managed Packages

Click Save

SEE ALSO

Creating Managed Packages
Configure Your Developer Settings
Specifying a License Management Organization

Specifying a License Management Organization

A license management organization is a Salesforce organization that you use to track all Salesforce

users who install your managed package The license management organization receives notification
in the form of a lead record when a user installs or uninstalls your package and tracks each package
upload on Salesforce AppExchange
Your license management organization can be any Salesforce Enterprise Unlimited Performance

or Developer Edition organization that has installed the free License Management Application LMA

from AppExchange To specify a License Management Organization go to
httpsitesforcecomappexchangepublisherHome

EDITIONS

Available in Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Developer
Edition
Package uploads and
installs are available in
Group Professional
Enterprise Performance
Unlimited and Developer
Editions

SEE ALSO

Creating Managed Packages
Configure Your Developer Settings
Register a Namespace Prefix

Package and Distribute Your Apps

Manage Packages

Manage Packages

A package is a collection of Lightning Platform components and applications that are made available

to other organizations through the AppExchange A managed package is a collection of application

components that are posted as a unit on AppExchange and are associated with a namespace and
a License Management Organization To support upgrades a package must be managed An
organization can create a single managed package that can be downloaded and installed by many
different organizations Managed packages differ from unmanaged packages by having some locked
components allowing the managed package to be upgraded later Unmanaged packages do not
include locked components and cannot be upgraded In addition managed packages obfuscate
certain components like Apex on subscribing organizations to protect the intellectual property
of the developer
For details see the ISVforce Guide
To manage your packages enter Packages in the Quick Find box then select Packages
For more customization see Configure Your Developer Settings on page
From the list of packages you can
Click New to create a new package enter a package name and description and click Save to
store it in your list of packages
Click Edit to update the package properties
Click Del to delete the package The components contained in your package are not deleted
Click the name of the package to view the details of the package

EDITIONS

Available in Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Developer
Edition
Package uploads and
installs are available in
Group Professional
Enterprise Performance
Unlimited and Developer
Editions

USER PERMISSIONS

To upload packages
Upload AppExchange
packages

Note To create a test drive or choose a License Management Organization LMO for what

you have uploaded click Proceed to AppExchange from the package upload detail page

IN THIS SECTION

About Package Versions
Create a Package
Packages are containers for distributing custom functionality between Salesforce orgs Create a package to upload your app or
Lightning component to the AppExchange or to deploy changes between orgs
Add Components to Your Package
Components Available in Managed Packages

A component is a part of a managed package A component defines an item such as a custom object or a custom field You can

combine components in a package to produce powerful features or applications In managed packages you can upgrade some
components
Protected Components
Components Automatically Added to Packages
Editing Components and Attributes After Installation
Component Behavior in Packages
Determine which components to include in your package and understand how components impact app design and distribution
requirements for your managed or unmanaged packages

Package and Distribute Your Apps

Manage Packages

Permission Sets and Profile Settings in Packages
Developers can use permission sets or profile settings to grant permissions and other access settings to a package When deciding
whether to use permission sets profile settings or a combination of both consider the similarities and differences

SEE ALSO

Understanding Packages
View Package Details
Create a Package

About Package Versions

A package version is a number that identifies the set of components uploaded in a package The

version number has the format majorNumberminorNumberpatchNumber for example
The major and minor numbers increase to a chosen value during every major release The
patchNumber is generated and updated only for a patch release Unmanaged packages are

not upgradeable so each package version is simply a set of components for distribution A package

version has more significance for managed packages Packages can exhibit different behavior for
different versions Publishers can use package versions to evolve the components in their managed
packages gracefully by releasing subsequent package versions without breaking existing customer
integrations using the package
Version numbers depend on the package release type which identifies the way packages are
distributed There are two kinds
Major Release

A major release denotes a

Managed Released package During these releases the major
and minor numbers of a package version increase to a chosen value

EDITIONS

Available in Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Developer
Edition
Package uploads and
installs are available in
Group Professional
Enterprise Performance
Unlimited and Developer
Editions

Patch Release

A patch release is only for patch versions of a package During these releases the patch number

of a package version increments
The following table shows a sequence of version numbers for a series of uploads
Upload
Sequence

Type

Version
Number

Notes

First upload

Managed Beta

The first Managed Beta upload

Second upload

Managed Released

A Managed Released upload Note that the version number does not

change

Third upload

Managed Released

Note the change of the minor release number for this Managed Released
upload If you are uploading a new patch version you cant change the patch
number

Fourth upload

Managed Beta

The first Managed Beta upload for version number Note the major
version number update

Fifth upload

Managed Released

A Managed Released upload Note that the version number does not

change

***