Special Behavior of Components in Packages

When you’re building an app for distribution, it’s important to consider how packaging affects your app and its components. Use the following information to help you determine what to include in your packages, how to design your app, and how to distribute your packages (managed or unmanaged).

Reporting Snapshot

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.

Apex Classes or Triggers

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 organization. The installer can decide whether to install the package if any tests fail.

To prevent naming conflicts, Salesforce recommends using managed packages for all packages that contain Apex. This way, all the Apex objects contain your namespace prefix. For example, if there is an Apex class called MyHelloWorld and the namespace for your organization 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 automatically prepended to your class names, methods, variables, and so on, which helps prevent duplicate names in the installer’s organization.
• In a single transaction, you can only reference 10 unique namespaces. For example, suppose 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 second package wasn’t accessed directly by the first, because it occurs in the same transaction, it’s included in the number of namespaces being 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, this adds a sharing model dependency to your package. You must set the organization-wide sharing default access level for the custom object to Private in order for other organizations to install your package successfully.
• The code contained in an Apex class or trigger that is part of a managed package is automatically obfuscated and cannot be viewed in an installing organization. The only exceptions are methods declared as global, meaning that the method signatures can be viewed in an installing organization.
• You can use the deprecated annotation in Apex to identify global methods, classes, exceptions, enums, interfaces, and variables that can no longer be referenced in subsequent releases of the managed package in which they reside. This is useful when you are refactoring 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

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

Compact Layouts

When you package a compact layout, its record type mappings aren’t included. Subscribers or installers of a package containing a compact layout must recreate its record type mappings in their organization.

Connected Apps

• 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 organization during a package upgrade
• If you update a connected app and include it in a new package version, upgrading that package in a customer organization 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 will fail. This is a security feature, to block unauthorized users from gaining broad access to a customer organization by upgrading an installed package. A customer can still perform a pull upgrade of the same package; this is allowed because it’s with the customer’s knowledge and consent.
• You can add an existing connected app (that is, one created prior to Summer ‘13) to a managed package. You can also combine new and existing connected apps in the same managed package.
• For connected apps created prior to Summer ‘13, the existing install URL continues to be valid until you package and upload a new version. Once you upload a new version of the package with an updated connected app, the install URL will no longer work.

Custom Console

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

Custom Fields

• Picklist field values for custom fields can be added, edited, or deleted by subscribers. A developer should carefully consider this when explicitly referencing a picklist value in code. Picklist values can be added or deleted by the developer. During a package upgrade, no new picklist values are installed into the subscriber’s organization for existing fields. Any picklist values deleted by the developer are still available in the subscriber’s organization.
• 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.

Custom Labels

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.

Custom Objects

• If a developer enables the Allow Reports or Allow Activities attributes on a packaged custom object, the subscriber’s organization 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.

Custom Permissions

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 organization.

Custom Report Types

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.

Custom Settings

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

Custom Tabs

• The Tab Style for a custom tab must be unique within your app. However, it does not need to be unique within the organization where it is installed. A custom tab’s style will not 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.

Customer Portal and Partner Portal

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.

Dashboard Components

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 install. Also, if the subscriber has modified the report, that report may return results impacting what information is displayed by the dashboard component. As a best practice, the developer should release a dashboard and the related reports in the same version.

Divisions

• When divisions are enabled on a custom object in a package, the subscribing organization 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 organization.
• 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 organization does not support divisions on the object, then the column is dropped during install.
• If you install a custom report type that includes an object’s division field as a column, that column is dropped if the organization does not support divisions.

External Data Sources

• After installing an external data source from a managed or unmanaged package, the subscriber must re-authenticate 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 re-authenticate 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.

External Objects

In managed and unmanaged packages, external objects are included in the custom object component.

Field Dependencies

• 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 organization 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 organization during an upgrade.

Field Sets

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 new 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—through the package release notes or other documentation—of any changes to released field sets. Merging has the potential to remove fields in your field set.

Note

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

Flows

• You can package only active flows. The active version of the flow is determined when you upload a package version. If none of the flow’s versions are active, the upload fails.
• To update a managed package with a different flow version, activate that version and upload the package again. You don’t need to add the newly activated version to the package. However, if you activate a flow version by mistake and upload the package, you’ll distribute that flow version to everyone. Be sure to verify which version you really want to upload.
• In a development organization, you can’t delete a flow or flow version after you upload it to a released or beta managed package.
• You can’t delete flow components from Managed - Beta package installations in development organizations.
• You can’t delete a flow from an installed package. To remove a packaged flow from your organization, 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 organization 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 organization 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 package that contains multiple flow versions in a fresh destination organization, 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 organization, 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 organization, the package install fails. You can’t overwrite a flow.
• The Cloud Flow Designer can’t open flows that are installed from managed packages.

Folders

• 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 organization 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.

Home Page Components

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.

Home Page Layouts

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.

List Views

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

Multi-Currency

• 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 organization 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 organization 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 organization is not enabled for multiple currencies, that column is dropped during install.
• If a subscriber installs a custom report type that includes an object’s currency field as a column, that column is dropped if the organization is not enabled for multiple currencies.

Named Credentials

• After installing a named credential from a managed or unmanaged package, the subscriber must re-authenticate to the external system.
  • For password authentication, the subscriber re-enters 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 re-authenticates 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 organization has a valid named credential with the same name.

  If you have multiple organizations, 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 organization has a valid certificate with the same name.
• The following callout options for named credentials can be set only via the user interface. If the default values aren’t appropriate in the destination organization, the admin for that organization must manually configure the named credential after deployment.

  • Generate Authorization Header—Default: Enabled
  • Allow Merge Fields in HTTP Header—Default: Disabled
  • Allow Merge Fields in HTTP Body—Default: Disabled

Page Layouts

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.

Permission Sets

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

• 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

Assigned apps and 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.

Picklist Values

• Subscribers can rename or delete picklist field values. A developer should carefully consider this when explicitly referencing a picklist field value in Apex.
• Picklist field values can be added or deleted in the developer’s organization. Upon upgrade, no new values are installed. Any values deleted by the developer are still available in the subscriber’s organization until the subscriber deletes them.

Profile Settings

Profile settings include the following for components in the package:

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

Profile settings overwrite existing profiles in the installer’s organization with specific permission and setting changes.

Record Types

• If record types are included in the package, the subscriber’s organization 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 organization is not using record types on the object or does not support record types, then the column is dropped during install.
• If you install a custom report type that includes an object’s record type field as a column, that column is dropped if the organization does not support record types or the object does not have any record types defined.

Reports

If a report includes elements that cannot be packaged, those elements will be dropped or downgraded, or the package upload will fail. 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 organization 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.

S-Controls

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

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

Translation Workbench

• 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 for the packaged language translations to appear. The only reason installers may want to enable the translation workbench is to change translations for unmanaged components after installation, override custom label translations in a managed package, or to translate into additional languages.
• If you are designing a package extension, you can include translations for the extension components but not additional translations for components in the base package.

Validation Rules

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

Workflow

• 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 Process Builder has superseded flow trigger workflow actions, formerly available in a pilot program. Organizations that are using flow trigger workflow actions can continue to create and edit them, but flow trigger workflow actions aren’t available for new organizations.

• Some workflow actions can be protected by the developer. For more information on protected components, see Protected Components.
• Developers can associate or disassociate workflow actions with a workflow rule at any time. These changes, including disassociation, are reflected in the subscriber’s organization 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 organization-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.