Special Behavior of Components in Packages | ISVforce Guide

Any Apex that is included as part of a package must have at least 75% cumulative test coverage. Each trigger must also have some test coverage. When you upload your package to AppExchange, all tests are run to ensure that they run without errors. In addition, all tests are run when the package is installed in the installer’s org. If any test fails, the installer can decide whether to install the package.

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 org’s namespace is OneTruCode, the class is referenced as OneTruCode.MyHelloWorld.

Tip

Keep the following considerations in mind when including Apex in your package.

Managed packages receive a unique namespace. This namespace is prepended to your class names, methods, variables, and so on, which helps prevent duplicate names in the installer’s org.
In a single transaction, you can only reference 10 unique namespaces. For example, suppose that you have an object that executes a class in a managed package when the object is updated. Then that class updates a second object, which in turn executes a different class in a different package. Even though the first package didn’t access the second package directly, the access occurs in the same transaction. It’s therefore included in the number of namespaces accessed in a single transaction.
If you are exposing any methods as Web services, include detailed documentation so that subscribers can write external code that calls your Web service.
If an Apex class references a custom label and that label has translations, explicitly package the individual languages desired to include those translations in the package.
If you reference a custom object’s sharing object (such as MyCustomObject__share) in Apex, you add a sharing model dependency to your package. Set the default org-wide access level for the custom object to Private so other orgs can install your package successfully.
The code contained in an Apex class, trigger, or Visualforce component that’s part of a managed package is obfuscated and can’t be viewed in an installing org. The only exceptions are methods declared as global. You can view global method signatures in an installing org. In addition, License Management Org users with the View and Debug Managed Apex permission can view their packages’ obfuscated Apex classes when logged in to subscriber orgs via the Subscriber Support Console.
You can use the deprecated annotation in Apex to identify global methods, classes, exceptions, enums, interfaces, and variables that can’t be referenced in later releases of a managed package. So you can refactor code in managed packages as the requirements evolve. After you upload another package version as Managed - Released, new subscribers that install the latest package version cannot see the deprecated elements, while the elements continue to function for existing subscribers and API integrations.
Any Apex contained in an unmanaged package that explicitly references a namespace cannot be uploaded.
Apex code that refers to Data Categories can’t be uploaded.
Before you delete Visualforce pages or global Visualforce components from your package, remove all references to public Apex classes and public Visualforce components from the pages or components that you’re deleting. After removing the references, upgrade your subscribers to an interim package version before you delete the page or global component.

Apex sharing reasons can be added directly to a package, but are only available for custom objects.

Connected apps can be added to managed packages, only. Connected apps are not supported for unmanaged packages.
Subscribers or installers of a package can’t delete a connected app by itself; they can only uninstall its package. A developer can delete a connected app after a package is uploaded as Managed - Released. The connected app will be deleted in the subscriber's org during a package upgrade.
If you update a connected app and include it in a new package version, upgrading that package in a customer org updates the existing connected app.
If you push upgrade a package containing a connected app whose OAuth scope or IP ranges have changed from the previous version, the upgrade fails. This security feature blocks unauthorized users from gaining broad access to a customer org by upgrading an installed package. A customer can still perform a pull upgrade of the same package. This upgrade is allowed because it’s with the customer’s knowledge and consent.
You can add an existing connected app (one created before Summer ’13) to a managed package. You can also combine new and existing connected apps in the same managed package.
For connected apps created before Summer ’13, the existing install URL is valid until you package and upload a new version. After you upload a new version of the package with an updated connected app, the install URL no longer works.

A package that has a custom console component can only be installed in an org with the Service Cloud license or Sales Console permission enabled.

Developers can add required and universally required custom fields to managed packages as long as they have default values.
Auto-number type fields and required fields cannot be added after the object is uploaded in a Managed - Released package.
Subscriber orgs can’t install roll-up summary fields that summarize detail fields set to protected.

If a label is translated, the language must be explicitly included in the package in order for the translations to be included in the package. Subscribers can override the default translation for a custom label.

Second-generation managed packages (2GP) include the fields and records for custom metadata types that you add. You can’t add fields directly to an existing package after the package version is promoted. If you create multiple packages that share the same namespace, then layouts and records can be in separate packages, but custom fields on the custom metadata type must be in the same package.

You can add fields to a custom metadata type by publishing an extension to the existing package, creating an entity relationship field, and mapping the field to the custom metadata type in your extension. See Add Custom Metadata Type Fields to Existing Packages.

If a developer enables the Allow Reports or Allow Activities attributes on a packaged custom object, the subscriber’s org also has these features enabled during an upgrade. Once enabled in a Managed - Released package, the developer and the subscriber cannot disable these attributes.
Standard button and link overrides are also packageable.
In your extension package, if you want to access history information for custom objects contained in the base package, work with the base package owner to:
1. Enable history tracking in the release org of the base package.
2. Upload a new version of the base package.
3. Install the new version of the base package in the release org of the extension package to access the history tracking info.
As a best practice, don’t enable history tracking for custom objects contained in the base package directly in the extension package’s release org. Doing so can result in an error when you install the package and when you create patch orgs for the extension package.

If you deploy a change set with a custom permission that includes a connected app, the connected app must already be installed in the destination org.

A developer can edit a custom report type in a managed package after it’s released, and can add new fields. Subscribers automatically receive these changes when they install a new version of the managed package. However, developers can’t remove objects from the report type after the package is released. If you delete a field in a custom report type that’s part of a managed package, and the deleted field is part of bucketing or used in grouping, you receive an error message.

If a custom setting is contained in a managed package, and the Visibility is specified as Protected, the custom setting isn’t contained in the list of components for the package on the subscriber's org. All data for the custom setting is hidden from the subscriber.

The tab style for a custom tab must be unique within your app. However, it does not need to be unique within the org where it’s installed. A custom tab style doesn’t conflict with an existing custom tab in the installer’s environment.
To provide custom tab names in different languages, from Setup, enter Rename Tabs and Labels in the Quick Find box, then select Rename Tabs and Labels.
Subscribers cannot edit custom tabs in a managed package.

Packages referring to Customer Portal or partner portal fields are supported. The subscriber installing the package must have the respective portal enabled to install the package.

Developers of managed packages must consider the implications of introducing dashboard components that reference reports released in a previous version of the package. If the subscriber deleted the report or moved the report to a personal folder, the dashboard component referencing the report is dropped during the installation. Also, if the subscriber has modified the report, the report results can impact what displays in the dashboard component. As a best practice, release a dashboard and the related reports in the same version.

When divisions are enabled on a custom object in a package, the subscribing org must have the divisions feature enabled to install the package.
Setting the division filter on a report does not cause a dependency. The setting is dropped when installed into the subscriber’s org.
Summarizing by the object’s division field—for example, Account Division—in a report causes a dependency.
If the object’s division field in a report is included as a column, and the subscriber’s org does not support divisions on the object, the column is dropped during installation.
If you install a custom report type that includes an object’s division field as a column, that column is dropped if the org does not support divisions.

After installing an external data source from a managed or unmanaged package, the subscriber must reauthenticate to the external system.
- For password authentication, the subscriber must re-enter the password in the external data source definition.
- For OAuth, the subscriber must update the callback URL in the client configuration for the authentication provider, then reauthenticate by selecting Start Authentication Flow on Save on the external data source.
Certificates aren’t packageable. If you package an external data source that specifies a certificate, make sure that the subscriber org has a valid certificate with the same name.

In managed and unmanaged packages, external objects are included in the custom object component.
Include External Change Data Tracking components in a managed package by selecting your test from the Apex Class Component Type list. The trigger, test, external data source, external object, and other related assets are brought into the package for distribution.

Developers and subscribers can add, change, or remove field dependencies.
If the developer adds a field dependency, it is added during installation unless the subscriber has already specified a dependency for the same field.
If a developer removes a dependency, this change is not reflected in the subscriber’s org during an upgrade.
If the developer introduces a new picklist value mapping between the dependent and controlling fields, the mapping is added during an upgrade.
If a developer removes a picklist value mapping, the change is not reflected in the subscriber’s org during an upgrade.

Field sets in installed packages perform different merge behaviors during a package upgrade:

If a package developer:	Then in the package upgrade:
Changes a field from Unavailable to Available for the Field Set or In the Field Set	The modified field is placed at the end of the upgraded field set in whichever column it was added to.
Adds a field	The new field is placed at the end of the upgraded field set in whichever column it was added to.
Changes a field from Available for the Field Set or In the Field Set to Unavailable	The field is removed from the upgraded field set.
Changes a field from In the Field Set to Available for the Field Set (or vice versa)	The change is not reflected in the upgraded field set.

Subscribers aren’t notified of changes to their installed field sets. The developer must notify users ——of changes to released field sets through the package release notes or other documentation. Merging has the potential to remove fields in your field set.

Note

When a field set is installed, a subscriber can add or remove any field.

When you upload a package or package version, the active flow version is included. If the flow has no active version, the latest version is packaged.
To update a managed package with a different flow version, activate that version and upload the package again. Or deactivate all versions of the flow, make sure the latest flow version is the one to distribute, and then upload the package.
In a development org, you can’t delete a flow or flow version after you upload it to a released or beta managed package.
You can’t delete flows from Managed - Beta package installations in development org.
You can’t delete a flow from an installed package. To remove a packaged flow from your org, deactivate it and then uninstall the package.
If you have multiple versions of a flow installed from multiple unmanaged packages, you can’t remove only one version by uninstalling its package. Uninstalling a package—managed or unmanaged—that contains a single version of the flow removes the entire flow, including all versions.
You can’t include flows in package patches.
An active flow in a package is active after it’s installed. The previous active version of the flow in the destination org is deactivated in favor of the newly installed version. Any in-progress flows based on the now-deactivated version continue to run without interruption but reflect the previous version of the flow.
Upgrading a managed package in your org installs a new flow version only if there’s a newer flow version from the developer. After several upgrades, you can end up with multiple flow versions.
If you install a managed package that contains multiple flow versions in a fresh destination org, only the latest flow version is deployed.
If you install a flow from an unmanaged package that has the same name but a different version number as a flow in your org, the newly installed flow becomes the latest version of the existing flow. However, if the packaged flow has the same name and version number as a flow already in your org, the package install fails. You can’t overwrite a flow.
Flow Builder can’t open flows that are installed from managed packages, unless they’re templates.
You can’t create a package that contains flows invoked by both managed and unmanaged package pages. As a workaround, create two packages, one for each type of component. For example, suppose that you want to package a customizable flow invoked by a managed package page. Create one unmanaged package with the flow that users can customize. Then create another managed package with the Visualforce page referencing the flow (including namespace) from the first package.
When you translate a flow from a managed package, the flow’s Master Definition Name doesn’t appear on the Translate page or the Override page. To update the translation for the Master Definition Name, edit the flow label and then update the translation from the Translate page.
If any of the following elements are used in a flow, packageable components that they reference aren’t included in the package automatically. To deploy the package successfully, manually add those referenced components to the package.
- Post to Chatter
- Send Email
- Submit for Approval
If a flow references a Lightning component that depends on a CSP Trusted Site, the trusted site isn’t included in the package or change set automatically.

Components that Salesforce stores in folders, such as documents, cannot be added to packages when stored in personal and unfiled folders. Put documents, reports, and other components that Salesforce stores in folders in one of your publicly accessible folders.
Components such as documents, email templates, reports, or dashboards are stored in new folders in the installer’s org using the publisher’s folder names. Give these folders names that indicate they are part of the package.
If a new report, dashboard, document, or email template is installed during an upgrade, and the folder containing the component was deleted by the subscriber, the folder is re-created. Any components in the folder that were previously deleted are not restored.
The name of a component contained in a folder must be unique across all folders of the same component type, excluding personal folders. Components contained in a personal folder must be unique within the personal folder only.

When you package a custom home page layout, all the custom home page components included on the page layout are automatically added. Standard components such as Messages & Alerts are not included in the package and do not overwrite the installer’s Messages & Alerts. To include a message in your custom home page layout, create an HTML Area type custom Home tab component containing your message. From Setup, enter Home Page Components in the Quick Find box, then select Home Page Components. Then add the message to your custom home page layout.

Once installed, your custom home page layouts are listed with all the subscriber’s home page layouts. Distinguish them by including the name of your app in the page layout name.

Packaged connections are installed as unprovisioned. Alert subscribers about how to provision connections after package installation.
If a developer changes the Region of a packaged connection that is subscriber-provisioned, the upgrade fails for the subscriber. Alert subscribers about tearing down the connection before updating the Region field. As a best practice, avoid changing the Region of a packaged connection unless absolutely necessary.

List views associated with queues cannot be included in a package.

If a subscriber installs a report or custom report type that includes an object’s currency field as a column, that column is dropped if the subscriber’s org is not enabled for multiple currencies.
Referencing an object’s currency field in a report’s criteria—for example, Account Currency—causes a dependency.
Summarizing by an object’s currency field in a report causes a dependency.
Using a currency designation in a report criteria value—for example, “Annual Revenue equals GBP 100”—does not cause a dependency. The report generates an error when run in the installers org if it does not support the currency.
If an object’s currency field in a report is included as a column and the subscriber’s org is not enabled for multiple currencies, that column is dropped during installation.
If a subscriber installs a custom report type that includes an object’s currency field as a column, that column is dropped if the org is not enabled for multiple currencies.

After installing a named credential from a managed or unmanaged package, the subscriber must reauthenticate to the external system.
- For password authentication, the subscriber reenters the password in the named credential definition.
- For OAuth, the subscriber updates the callback URL in the client configuration for the authentication provider and then reauthenticates by selecting Start Authentication Flow on Save on the named credential.
Named credentials aren’t automatically added to packages. If you package an external data source or Apex code that specifies a named credential as a callout endpoint, add the named credential to the package. Alternatively, make sure that the subscriber org has a valid named credential with the same name.
If you have multiple orgs, you can create a named credential with the same name but with a different endpoint URL in each org. You can then package and deploy—on all the orgs—one callout definition that references the shared name of those named credentials. For example, the named credential in each org can have a different endpoint URL to accommodate differences in development and production environments. If an Apex callout specifies the shared name of those named credentials, the Apex class that defines the callout can be packaged and deployed on all those orgs without programmatically checking the environment.
Certificates aren’t packageable. If you package a named credential that specifies a certificate, make sure that the subscriber org has a valid certificate with the same name.

Packaged connections are installed as unprovisioned. Alert subscribers about how to provision connections after package installation.
If a developer changes the Region or Service Name of a packaged connection that is subscriber-provisioned, the upgrade fails for the subscriber. Alert subscribers about tearing down the connection before you update the Region or Service Name fields. As a best practice, avoid changing the Region or Service Name of a packaged connection unless absolutely necessary.
If you package a Named Credential that references an Outbound Network Connection, the referenced Outbound Network Connection component is automatically added to the package.

The page layout of the person uploading a package is the layout used for Group and Professional Edition orgs and becomes the default page layout for Enterprise, Unlimited, Performance, and Developer Edition orgs.

Package page layouts alongside complimentary record types if the layout is being installed on an existing object. Otherwise, manually apply the installed page layouts to profiles.

If a page layout and a record type are created as a result of installing a package, the uploading user’s page layout assignment for that record type is assigned to that record type for all profiles in the subscriber org, unless a profile is mapped during an install or upgrade.

You can include permission sets as components in a package, with the following permissions and access settings:

Assigned custom apps
Custom object permissions
External object permissions
Custom field permissions
Custom permissions
Custom tab visibility settings
Apex class access
Visualforce page access
External data source access

Standard tab visibility settings aren’t included in permission set components.

Note

Use permission sets to install or upgrade a collection of permissions. In contrast to profile settings, permission sets don’t overwrite profiles.

When explicitly referencing a picklist value in code, keep in mind that picklist values for custom fields can be renamed, added, edited, or deleted by subscribers. Carefully consider this possibility when explicitly referencing a picklist value in code.
Picklist field values can be added or deleted in the developer’s organization.
Changes to standard picklists can’t be packaged and deployed to subscriber orgs and picklist values deleted by the developer are still available in the subscriber’s org. If there are differences between the package and the target org, or if there are dependencies on new values from features such as PathAssistant, the deploy fails. To change values in subscriber orgs, you must manually add or modify the values in the target subscriber org.
Updating picklist values in unlocked packages is not supported. You must manually add or modify the values in the target subscriber org.
Package upgrades retain dependent picklist values that are saved in a managed custom field.
Global value sets can be added to developer and subscriber orgs. Global value sets have the following behavior during a package upgrade:
- Label and API names for field values don’t change in subscriber orgs.
- New field values aren’t added to the subscriber orgs.
- Active and inactive value settings in subscriber orgs don’t change.
- Default values in subscriber orgs don’t change.
- Global value set label names change if the package upgrade includes a global value set label change.

Profile settings include the following for components in the package:

Assigned custom apps
Assigned connected apps
Tab settings
Page layout assignments
Record type assignments
Custom field permissions
Custom metadata type permissions
Custom object permissions
Custom permissions
Custom settings permissions
External object permissions
Apex class access
Visualforce page access
External data source access

Profile settings overwrite existing profiles in the installer’s org with specific permission and setting changes. Profile Settings get applied only if the package is installed in the target org for specific profiles and not if it is installed for all profiles.

If record types are included in the package, the subscriber’s org must support record types to install the package.
When a new picklist value is installed, it is associated with all installed record types according to the mappings specified by the developer. A subscriber can change this association.
Referencing an object’s record type field in a report’s criteria—for example, Account Record Type—causes a dependency.
Summarizing by an object’s record type field in a report’s criteria—for example, Account Record Type—causes a dependency.
If an object’s record type field is included as a column in a report, and the subscriber’s org is not using record types on the object or does not support record types, the column is dropped during installation.
If you install a custom report type that includes an object’s record type field as a column, that column is dropped if the org does not support record types or the object does not have record types defined.

Developers of managed packages must consider the implications of introducing reporting snapshots that reference reports released in a previous version of the package. If the subscriber deleted the report or moved the report to a personal folder, the reporting snapshot referencing the report isn’t installed, even though the Package Installation page indicates that it will be. Also, if the subscriber has modified the report, the report can return results impacting the information displayed by the reporting snapshot. As a best practice, the developer releases the reporting snapshot and the related reports in the same version.

Because the subscriber selects the running use, some reporting snapshot field mappings could become invalid if the running user doesn’t have access to source or target fields.

If a report includes elements that cannot be packaged, those elements are dropped or downgraded, or the package upload fails. For example:

Hierarchy drill-downs are dropped from activity and opportunities reports.
Filters on unpackageable fields are automatically dropped (for example, in filters on standard object record types).
Package upload fails if a report includes filter logic on an unpackageable field (for example, in filters on standard object record types).
Lookup values on the Select Campaign field of standard campaign reports are dropped.
Reports are dropped from packages if they have been moved to a private folder or to the Unfiled Public Reports folder.
When a package is installed into an org that does not have Chart Analytics 2.0:
- Combination charts are downgraded instead of dropped. For example, a combination vertical column chart with a line added is downgraded to a simple vertical column chart; a combination bar chart with additional bars is downgraded to a simple bar chart.
- Unsupported chart types, such as donut and funnel, are dropped.

Only s-controls in unmanaged packages created before January 2010 can be installed by subscribers.

S-controls have been deprecated and are superseded by Visualforce pages.

If you have enabled the translation workbench and added a language to your package, any associated translated values are automatically packaged for the appropriate components in your package. Make sure that you have provided translations for all possible components.
An installer of your package can see which languages are supported on the package detail page. The installer does not need to enable anything to have the packaged language translations appear. The only reasons installers might want to enable the translation workbench are to change translations for unmanaged components after installation, override custom label translations in a managed package, or translate into more languages.
If you are designing a package extension, you can include translations for the extension components but not translations for components in the base package.

For custom objects that are packaged, any associated validation rules are implicitly packaged as well.

Analytics components include Analytics applications, dashboards, dataflows, datasets, lenses, recipes, and user XMD. As you package Analytics components, keep these tips and best practices in mind.

Analytics unmanaged packages, as opposed to managed packages, are considered a developer-only feature and are not supported for general-purpose distribution. While Analytics unmanaged packages work as expected within the constraints of Salesforce unmanaged packages, they aren’t subject to the same level of testing as managed packages. Unmanaged packages come without many of the safeguards of managed packages, and are intended for developers familiar with their limitations. Also refer to the relevant topic in the ISV Guide.
Before a recipe is available for packaging, you must create a dataset with the recipe. The related dataflow must be added to the package along with the recipe for deployment to succeed.
Analytics Admin permissions are required to create a package but not for deployment, which requires only Salesforce admin permissions.
There is no spidering between datasets and dataflows, meaning there is no dependency following. When packaging both, they must be added manually. If they are not, an error appears during deployment. The same is true for change sets—when packaging both datasets and dataflows, add them manually.
When you package a data flow, source and security predicates aren't included in the package.
Because views are user-specific, they aren’t included when you package the dashboard.
If you migrate dashboards manually using JSON copy/paste, any conditional formatting, widget-specific number formats, and measure labels on blended queries are lost. To retain these formats and labels in the migrated dashboard, include the Analytics Dataset Metadata component type when packaging your change set.
The Winter ’18 release contains a beta version of Apex steps, which lets developers include custom Apex functionality in a dashboard to access Salesforce platform features that aren’t inherently supported in Analytics. If you include dashboards in a package, Apex steps are not included—migrate Apex classes separately.
Before the Spring ’17 release, images didn’t render when deploying a dashboard that used an image widget that referenced image files not available on the target org. There were two workarounds: Manually upload the images, or add a folder containing the images to the package. As of the Spring ’17 release, images are packaged with the dashboard, and references between dashboards are maintained. You can’t delete a dashboard that is referenced in a link. Either re-create the image, or link the widgets in the dashboard in the source org. Then repackage or fix the link issues in the target org.
Take care when packaging dataflows. Invalid schema overrides and unsupported or illegal parameters are removed. For example, Type = dim is no longer supported. Use Type = text instead. Comments in JSON are removed. Nodes can appear in a different order.

Salesforce prevents you from uploading workflow alerts that have a public group, partner user, or role recipient. Change the recipient to a user before uploading your app. During installation, Salesforce replaces that user with the user installing the app, and the installer can customize it as necessary.
Salesforce prevents you from uploading workflow field updates that change an Owner field to a queue. Change the updated field value to a user before uploading your app. During installation, Salesforce replaces that user with the user installing the app, and the installer can customize it as necessary.
Salesforce prevents you from uploading workflow rules, field updates, and outbound messages that reference a record type on a standard or managed-installed object.
Salesforce prevents you from uploading workflow tasks that are assigned to a role. Change the Assigned To field to a user before uploading your app. During installation, Salesforce replaces that user with the user installing the app, and the installer can customize it as necessary.
You can package workflow rules and associated workflow actions, such as email alerts and field updates. However, any time-based triggers aren’t included in the package. Notify your installers to set up any time-based triggers that are essential to your app.
Flow triggers aren’t packageable. The pilot program for flow trigger workflow actions is closed. If you've already enabled the pilot in your org, you can continue to create and edit flow trigger workflow actions. If you didn't enable the pilot in your org, use Flow Builder to create a record-triggered flow, or use Process Builder to launch a flow from a process.
Developers can protect some workflow actions.
Developers can associate or disassociate workflow actions with a workflow rule at any time. These changes, including disassociation, are reflected in the subscriber’s org upon install. In managed packages, a subscriber cannot disassociate workflow actions from a workflow rule if it was associated by the developer.
References to a specific user in workflow actions, such as the email recipient of a workflow email alert, are replaced by the user installing the package. Workflow actions referencing roles, public groups, account team, opportunity team, or case team roles may not be uploaded.
References to an org-wide address, such as the From email address of a workflow email alert, are reset to Current User during installation.
On install, all workflow rules newly created in the installed or upgraded package, have the same activation status as in the uploaded package.