ISVforce Guide Salesforce App Packaging

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 296 [warning: Documents this large are best viewed by clicking the View PDF Link!]

ISVforce Guide
Version 39.0, Spring ’17
@salesforcedocs
Last updated: April 17, 2017
© Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS
Chapter 1: Introduction ................................................1
Resources for Partners ..................................................2
Roles in the Application Lifecycle ............................................2
How to Sign Up for Test Environments ........................................3
Chapter 2: ISVforce Quick Start ..........................................4
Tutorial #1: Sign Up for AppExchange ........................................5
Step 1: Sign Up for the Partner Program ...................................5
Step 2: Create a Development and Test Environment ..........................5
Step 3: Get a Business Org ............................................6
Step 4: Edit Your Publisher Profile ........................................6
Sign-up Summary ..................................................6
Tutorial #2: Developing Your App ...........................................7
Step 1: Create an App ...............................................7
Step 2: Package Your App ............................................8
Step 3: Assign a Namespace ..........................................8
Step 4: Upload a Beta ...............................................9
Step 5: Install and Test the Beta .........................................9
Development Summary .............................................10
Tutorial #3: Publishing and Licensing ........................................11
Step 1: Uploading to the AppExchange ...................................11
Step 2: Create an AppExchange Listing ...................................11
Step 3: Complete the AppExchange Listing ................................12
Step 4: Manage Licenses for Your App ...................................12
Publishing and Licensing Summary .....................................13
Tutorial #4: Updating Your App ............................................13
Step 1: Creating a Patch Organization ....................................14
Step 2: Developing a Patch ...........................................14
Step 3: Uploading the Patch ..........................................15
Step 4: Installing or Pushing a Patch .....................................15
Updating Your App Summary .........................................16
Chapter 3: Designing and Building Your App ...............................17
Overview of Packages ..................................................18
Planning the Release of Managed Packages ...............................19
Create a Package .................................................20
Developing and Distributing Unmanaged Packages ..........................20
Components Available in Managed Packages .................................21
Editing Components and Attributes after Installation ..........................28
Components Automatically Added to Packages .............................35
Special Behavior of Components in Packages ..............................37
Protected Components .............................................46
Understanding Dependencies ........................................47
About Permission Sets and Profile Settings ................................48
Custom Profile Settings .............................................49
Protecting Your Intellectual Property .....................................50
Creating Packaged Applications with Chatter ..............................50
Matching the Salesforce Look and Feel ...................................51
Developing App Documentation .......................................52
About API and Dynamic Apex Access in Packages ..............................52
Manage API and Dynamic Apex Access in Packages .........................55
Configuring Default Package Versions for API Calls ..........................56
About the Partner WSDL .............................................57
Generating an Enterprise WSDL with Managed Packages ......................58
Working with External Services ........................................58
Architectural Considerations for Group and Professional Editions .....................59
Features in Group and Professional Editions ...............................60
Limits for Group and Professional Editions .................................61
Access Control in Group and Professional Editions ...........................61
Using Apex in Group and Professional Editions .............................61
API Access in Group and Professional Editions ..............................62
Designing Your App to Support Multiple Editions ............................63
Sample Design Scenarios for Group and Professional Editions ...................65
Connected Apps .....................................................66
Create a Connected App ............................................66
Edit, Reconfigure, or Delete a Connected App in Salesforce Classic ................74
Install a Connected App .............................................76
View Connected App Details ..........................................77
Manage a Connected App ...........................................78
Edit Connected App Behavior .........................................80
Monitor Usage for an OAuth Connected App ..............................84
Uninstall a Connected App ...........................................85
Environment Hub .....................................................86
Get Started with the Environment Hub ...................................87
Manage Orgs in the Environment Hub ...................................89
Single Sign-on in the Environment Hub ...................................91
Environment Hub Best Practices .......................................93
Environment Hub FAQ ..............................................94
Considerations for the Environment Hub in Lightning Experience .................96
Notifications for Package Errors ...........................................96
Set the Notification Email Address ......................................97
Chapter 4: Packaging and Testing Your App ...............................98
Contents
About Managed Packages ..............................................99
Configure Your Developer Settings ......................................99
Register a Namespace Prefix .........................................100
Specifying a License Management Organization ............................101
Create and Upload a Managed Package ................................103
View Package Details ..............................................105
Installing a Package ..................................................108
Component Availability After Deployment .................................111
Uninstalling a Package .................................................111
Installing Managed Packages using the API ..................................112
Resolving Apex Test Failures .............................................113
Running Apex on Package Install/Upgrade ...................................113
How does a Post Install Script Work? ....................................114
Example of a Post Install Script ........................................115
Specifying a Post Install Script .........................................116
Running Apex on Package Uninstall ........................................117
How does an Uninstall Script Work? ....................................117
Example of an Uninstall Script ........................................117
Specifying an Uninstall Script .........................................118
Publishing Extensions to Managed Packages .................................119
Chapter 5: Passing the Security Review ..................................120
Security Review ......................................................121
Security Review Steps .................................................121
Security Review Wizard ................................................123
Submit a Client or Mobile App for Security Review ..............................124
Submit an Extension Package for Security Review ...............................124
Security Review Resources ..............................................124
Security Review FAQ ..................................................125
Chapter 6: Publish Your Offering on the AppExchange .......................129
What Is the AppExchange? ..............................................130
Publish on the AppExchange ............................................130
Connect a Packaging Organization to the AppExchange ......................130
Create or Edit Your Provider Profile .....................................131
Create or Edit an AppExchange Listing ...................................131
Make Your AppExchange Listing Effective ................................132
Choose an Installation Option ........................................132
Register Your Package and Choose License Settings .........................133
Submit Your Listing for Security Review ..................................133
Email Notifications ...................................................134
AppExchange Checkout ................................................135
Configure Stripe for AppExchange Checkout ..............................136
Sell Using AppExchange Checkout .....................................136
Contents
AppExchange Checkout FAQ .........................................138
Checkout Management App ............................................140
Checkout Management App Best Practices ...............................142
Checkout Management App Objects ...................................142
Get Started with the Checkout Management App ...........................144
Sample Checkout Management App Customizations ........................148
Update Settings in the Checkout Management App .........................150
View Checkout Management App Logs ..................................152
Work with AppExchange Leads ...........................................152
AppExchange Leads FAQ ...........................................152
Analytics Reports for Publishers ...........................................154
Update the Package in an AppExchange Listing ...............................156
AppExchange FAQ ...................................................156
Can I have multiple listings for an app or component? ........................160
Chapter 7: Manage Orders ...........................................161
Channel Order App ...................................................162
Channel Order App Objects .........................................162
Order Types ....................................................163
Order Statuses ..................................................164
Get Started with the Channel Order App .....................................165
Install the Channel Order App ........................................165
Define a Channel Order App Email Service ...............................166
Import Product Data to the Channel Order App .............................167
Assign Access to the Channel Order App ................................168
Display Customers in the Channel Order App ..............................169
Upgrade the Channel Order App .........................................169
Channel Order App Upgrade Considerations ..............................169
Upgrade to Channel Order App v2.0 ...................................170
Manage Orders in the Channel Order App ...................................172
Submit an Order .................................................173
Edit an Order ...................................................175
Clone an Order ..................................................175
Recall an Order ..................................................176
Delete an Order .................................................176
Refresh Product Data ..............................................176
Channel Order Apex API ...............................................176
CHANNEL_ORDERS Namespace .......................................177
Service Order ....................................................191
Service Order Detail ...............................................193
Partner Order Submit API ...........................................196
Chapter 8: Managing Licenses ........................................199
License Management App .............................................200
Contents
How Does the License Management App Work? ...........................200
Integrate the License Management App into Your Business Processes ............204
Best Practices for the License Management App ...........................205
Get Started with the License Management App ................................205
Install the License Management App ...................................205
Associate a Package with the License Management App .....................206
Configure the License Management App ................................207
Manage Leads and Licenses for Your Offering ................................208
Modify a License Record in the License Management App .....................208
Change the Lead Manager in the License Management App ...................209
Refresh Licenses for an Offering in the License Management App ................209
Move the License Management App to Another Salesforce Org .................210
Troubleshoot the License Management App ..................................210
Leads and Licenses Aren’t Being Created ................................210
Proxy User Has Deactivated Message ...................................211
License Management App FAQ ...........................................211
Is the LMA compatible with Lightning Experience? ...........................211
Can I install the LMA in a non-production Salesforce org? ......................212
Why can’t I see the Modify License button on my license records? ................212
A customer installed my package before I associated it with the LMA. How can I manage
the license record? ...............................................212
Can I automate the assignment of licenses to users in the subscriber org? ..........212
Why aren’t leads and licenses being created in the LMA? ......................212
What happens when I decrease the number of available licenses below the current
number of licensed users? ..........................................212
Chapter 9: Provide a Free Trial .........................................213
Why Use Trialforce? ...................................................214
Trialforce ..........................................................214
Set Up Trialforce .....................................................216
Link a Package with Your License Management Organization ...................216
Request a Trialforce Management Org ..................................217
Setting Up Custom Branding for Trialforce ................................217
Create a Trialforce Source Organization .................................219
Create a Trialforce Template .........................................220
Link a Trialforce Template to the AppExchange ............................220
Submit a Trialforce Template for Security Review ............................221
Provide a Free Trial on the AppExchange ....................................221
Provide a Free Trial on the AppExchange Using Trialforce ......................221
Provide a Test Drive on the AppExchange ................................222
Provide a Free Trial on the AppExchange When Your Offering Is Installed ...........223
Provide a Free Trial on Your Website .......................................223
Request a Sign-Up Form for Trialforce ..................................223
Link a Trialforce Template to the Sign-Up Form .............................223
Contents
Customizing the HTML Registration Form ................................224
Provisioning New Trial Organizations ...................................225
Modify the Trial for an Upgrade ..........................................225
Trialforce Best Practices ................................................226
Creating Signups using the API ...........................................226
Trialforce FAQ ......................................................239
Chapter 10: Supporting Your AppExchange Customers ......................241
Subscriber Support Console .............................................242
Viewing Subscriber Details ..........................................242
Request Login Access from a Customer .................................242
Logging in to Subscriber Organizations .................................243
Troubleshooting in Subscriber Organizations ..............................243
Usage Metrics ......................................................244
Setting up Usage Metrics ...........................................244
Accessing Usage Metrics Data .......................................245
MetricsDataFile ..................................................246
Usage Metrics Visualization .........................................248
Chapter 11: Upgrading Your App .......................................251
About Package Versions ...............................................253
Creating and Uploading Patches .........................................253
Working with Patch Versions ............................................254
Versioning Apex Code .............................................257
Apex Deprecation Effects for Subscribers ................................258
Publish Upgrades to Managed Packages ...................................259
Delete Components in Managed Packages ..............................259
Viewing Deleted Components ........................................261
Modifying Custom Fields after a Package is Released ........................262
Manage Versions ................................................263
Pushing an Upgrade .................................................263
About Push Upgrades .............................................263
Push Upgrade Best Practices ........................................264
Assigning Access to New Components and Fields ..........................265
Sample Post Install Script for a Push Upgrade .............................266
Scheduling Push Upgrades .........................................267
View Push Upgrade Details .........................................269
View an Organization’s Upgrade History ................................270
APPENDICES ....................................................272
Appendix A: ISVforce User License Comparison .....................272
Appendix B: OEM User License Comparison ........................276
Contents
GLOSSARY ......................................................280
INDEX ..........................................................283
Contents
CHAPTER 1 Introduction
The ISVforce Guide is written for independent software vendors (ISVs) who want to build and sell
applications using the Force.com platform. This guide is organized by the following chapters:
In this chapter ...
•Resources for
Partners •Quick Start—Start here to acquire and configure all of the environments you need in order to build
and sell apps.
•Roles in the
Application Lifecycle •Designing and Building Your App—Before you start development, it's important to know how all
the pieces fit together. This chapter covers architectural decisions to consider before development.
•How to Sign Up for
Test Environments •Packaging and Testing Your App—This chapter also covers specifics about developing and testing
packaged apps.
•Passing the Security Review—Learn about security best practices and plan for security review.
•Publish Your Offering on the AppExchange—List your app on the AppExchange marketplace.
•Managing Orders—Use the Channel Order App to create, manage, and submit orders to the Partner
Operations team.
•Managing Licenses—Use the License Management App to manage your customer and app licenses.
•Providing a Free Trial—Create a free trial to help you sell your app to non-Salesforce customers.
•Supporting Your AppExchange Customers—Give your customers technical support for the installation
and use of your app.
•Upgrading Your App—When it's time to upgrade your packaged app, you can push minor patches
or create major releases.
1
Resources for Partners
The Partner Community, at https://partners.salesforce.com, is the primary resource for all ISVs. To get started, we recommend visiting
the Education page, your one-stop shop for all ISV content. In addition, you can use the Partner Community to:
•Collaborate with other partners and salesforce.com using our Chatter community.
•Stay up-to-date on news and events related to the Salesforce Partner Program.
•Log cases for access to partner-specific features and customer support.
•Use enhanced search, integrated with the Success Community, to quickly find relevant resources.
•Browse the Salesforce Partner Online Training catalog and sign up for courses.
The Partner Community is self-service—the first person to register your partnership becomes your designated administrator and manages
the creation of additional users for your company. You can change or add administrators, as required.
Roles in the Application Lifecycle
This guide covers the entire lifecycle of a package application, so some of the topics might not be relevant to you. The following list has
topic suggestions by role.
An application architect
The application architect determines the scope of the application and the internal structures that support it. Architects need to know
details about the underlying Force.com platform that will determine not only the application's use, but which editions it supports,
how it's installed, configured, and upgraded. Architects need to be familiar with this entire guide, but especially the following
chapters:
•Designing and Building Your App on page 17
•Passing the Security Review on page 120
A developer creates, packages, and uploads an app
A developer, or often a team of developers, create an app, package it, and upload it to the AppExchange. Developers also update
the app with bug fixes and new features. As a developer, you'll want to see the following chapters:
•Designing and Building Your App on page 17
•Packaging and Testing Your App on page 98
•Developing App Documentation on page 52
•Upgrading Your App on page 251
A publisher distributes, sells, and supports the app
The publisher of an app is the person or company who has a profile and one or more listings for the app on AppExchange. Publisher
listings contain a link to an app they have uploaded to AppExchange, or to a third-party website. Publishers also set default license
settings. As a publisher, you'll want to see the following chapters:
•Publish Your Offering on the AppExchange on page 129
•Provide a Free Trial on page 213
•Supporting Your AppExchange Customers on page 241
An administrator installs the app
An administrator, or admin, downloads your app from AppExchange and installs it into their organization. Admins might also
customize the app to further suit their business needs. See the following topic to learn how admins will interact with your app.
•Installing a Package on page 108
2
Resources for PartnersIntroduction
How to Sign Up for Test Environments
To sign up for test environments (organizations), use the Environment Hub.
Note: If you’re a new Salesforce user, log in to the organization that you received when you signed up for the Partner Program.
The Environment Hub is enabled in this organization by default. If you’re an existing Salesforce user and are using a different
organization to manage development, log a case in the Partner Community to enable the Environment Hub.
1. Log in to the organization where Environment Hub is enabled.
2. Select the Environment Hub tab, then click Create Organization.
3. In the Purpose drop-down list, select Test/Demo.
4. In the Edition drop-down list, choose the edition you want to test against.
5. Fill in the remaining required fields. Optionally, set up My Domain.
6. Agree to the terms and then click Create.
7. You'll receive an email that will prompt you to log in and change your password. Click the link, change your password, and create
a password question and answer.
3
How to Sign Up for Test EnvironmentsIntroduction
CHAPTER 2 ISVforce Quick Start
This quick start is meant to take you through the application lifecycle as quickly as possible. Upon
completion, you'll have everything you need to develop and publish a packaged application.
In this chapter ...
•Tutorial #1: Sign Up
for AppExchange Note: You must be an ISVforce/OEM partner to complete all steps in this quick start, as it covers
some features only available to eligible partners.
•Tutorial #2:
Developing Your App
How is the Quick Start Organized?
The quick start is broken up into four tutorials, which are meant to be completed in order. Because some
of the steps require an automated email response, the time to complete the steps can vary. However,
you can stop at any step and pick up where you left off.
•Tutorial #3:
Publishing and
Licensing
•Tutorial #4: Updating
Your App
•Tutorial #1 takes you through the process of signing up for the Salesforce ISV Partner Program and
getting all of the organizations (environments) you'll need.
•Tutorial #2 walks you through creating a simple Hello World application.
•Tutorial #3 helps you publish and manage your app.
•Tutorial #4 tells you how to update your app for major and minor releases.
Tell Me More....
At the end of each step, there is an optional Tell Me More section. If you like to do things quickly, move
on to the next step. However, if you're a smell-the-roses type, there's a lot of useful information here.
•For a list of useful terms, see the Glossary on page 280.
•To learn more about Force.com and to access a rich set of resources, visit Salesforce Developers at
https://developer.salesforce.com.
•For a gentle introduction to developing on Force.com, see the Force.com Workbook at
https://developer.salesforce.com/page/Force.com_workbook.
4
Tutorial #1: Sign Up for AppExchange
In this tutorial, you set up the tools you need to develop, sell, and support apps and components built on the Force.com platform. You
start by signing up for the Partner Program. You then have access to the Partner Community, which allows you to view helpful resources,
create support cases, and collaborate with other partners and Salesforce. The Partner Community is also the best source for news and
events about the Partner Program. In addition, you can access the Environment Hub, where you can create development and test
organizations.
If you’re familiar with Salesforce, you know that an organization is a cloud unto itself. If you’re new to Salesforce, think of your organization
as a separate environment for developing, testing, and publishing your offering.
Step 1: Sign Up for the Partner Program
The first step is to sign up for the Partner Program.
1. In your browser, go to https://partners.salesforce.com and click Join Now.
Note: The signup process varies according to the region or country. Follow the instructions presented.
2. Fill in the fields about you and your company.
3. Select the first option: Independent Software Vendor (ISV).
4. Click Submit Registration.
In a moment, you’ll receive a confirmation, followed by an email welcoming you to the Partner Program and including login credentials.
Congratulations, you’re now part of the Salesforce ISV Partner Program! Click the link to the Partner Community
(https://partners.salesforce.com) and log in. Bookmark this page. You’ll be using it a lot.
Step 2: Create a Development and Test Environment
To build and sell on the Force.com platform, you need different environments for different tasks. We call these environments organizations,
or orgs for short. You use the Environment Hub to create these orgs. The first org you need is the Partner Developer Edition, which is
where you develop and package your offering. If you already have a Developer Edition org, we recommend signing up for the Partner
Developer Edition org because you can have more data storage, licenses, and users.
Note: If you’re a new Salesforce user, log in to the organization that you received when you signed up for the Partner Program.
The Environment Hub is enabled in this organization by default. If you’re an existing Salesforce user and are using a different
organization to manage development, log a case in the Partner Community to enable the Environment Hub.
1. Log in to the organization where the Environment Hub is enabled, usually your partner business org.
2. Click the Environment Hub tab, and then click Create Organization.
3. In the Purpose drop-down list, select Development. For simplicity, we refer to this as your dev org.
4. Fill in the required fields. Optionally, set up My Domain.
5. Agree to the terms and then click Create.
6. In the Purpose drop-down list, select Test/Demo and Partner Enterprise for the org edition. This process creates a test org, where
you test the app or component that your are developing.
7. Shortly, you’ll receive emails that prompt you to log in and change your password for your dev and test orgs.
5
Tutorial #1: Sign Up for AppExchangeISVforce Quick Start
Tell Me More...
The Environment Hub has several types of test orgs available, because different editions of Salesforce have different features. If you plan
to distribute your app or component to a particular edition, you want to test your offering and make sure that it works there. Although
that’s beyond the scope of this quick start. For more information, see Architectural Considerations for Group and Professional Editions
on page 59.
Step 3: Get a Business Org
In the previous step, you created orgs for developing and testing your offering. To manage sales and distribution, you need one more
org. In this step, you log a case in the Partner Community to have a partner business org provisioned for you. Your Partner Business Org
contains the apps that you use to manage sales and distribution, including the License Management App (LMA) and Channel Order
App (COA).
1. In the Partner Community, under the Support tab, select New Case.
2. Select Request Partner Benefits, and then select Create a Case.
3. In the Description field, tell us if you have an existing org or if you need a new one. If you have an existing Salesforce org, enter the
Org ID in the Description field to add two more CRM licenses to your org. If you don’t have an existing org, we provide a new one
for you. In either case, make sure to enter your business address and then select Submit Case.
Note: It can take 24–48 hours for your case to be closed. You can check the status of your case at any time under the Support
tab of the Partner Community.
4. You’ll receive an email prompting you to log in and change your password. Do that, and then bookmark the page.
Step 4: Edit Your Publisher Profile
In this step, you log in to the Partner Community and provide information about your company. We display some of this information
on AppExchange listings to help customers get to your business.
1. Log in to the Partner Community using the username and password of your business org.
2. On the Publishing page, click Company Info.
3. Fill out the information in the Provider Profile, and then click Save.
Sign-up Summary
In this first tutorial, you signed up for the Partner Program and all the organizations you need to develop, test, and sell your offering.
Let’s review what you signed up for and the purpose of each.
Partner Program
The Partner Program gives you access to the Partner Community, where you can get help and training information, log cases for
support issues, and collaborate with other partners. You also get access to the Environment Hub, which lets you create and manage
new test and development orgs.
Partner Developer Edition
Also known as your dev org, this is where you develop your offering and eventually package it for distribution.
Test Organization
Also know as your test org, this is where you install and test your offering.
Partner Business Organization
This is where you license and manage your offering.
6
Step 3: Get a Business OrgISVforce Quick Start
Tutorial #2: Developing Your App
In this tutorial you'll create a very simple “Hello World” application. It won't do much, but it's enough to understand where development
takes place in the lifecycle of a packaged application.
Step 1: Create an App
In this step you're going to create an app that contains a page, and a tab to display the page.
1. In your browser, log in to your Partner Developer Edition organization. Hereafter we'll call this your “dev org”.
2. From Setup, enter Visualforce Pages in the Quick Find box, then select Visualforce Pages.
3. In the Visualforce list, click New.
4. In the Label field enter Greeting.
5. In the Visualforce Markup area, replace the contents of the <h1> tag with Hello World.
Visualforce Page Editor
6. Click Save.
Now you'll associate the page with a tab.
1. In the sidebar menu, enter Tabs in the Quick Find box, then select Tabs.
2. In the Visualforce Tabs list, click New.
3. In the New Visualforce Tab wizard, click the drop-down box and select the Hello World page you just created.
4. For the Tab Label, enter Hello.
5. Click the Tab Style field and choose any icon to represent your tab.
6. Click Next, then Next again, and Save on the final page.
Now you'll create a new app that contains your tab and page.
1. In the sidebar menu, enter Apps in the Quick Find box, then select Apps.
2. Click New.
3. In the App Label field enter Hello World and then click Next and Next again on the following page.
7
Tutorial #2: Developing Your AppISVforce Quick Start
4. On the Choose the Tabs page, scroll to the bottom of the Available Tabs list, find your Hello tab, and add it to the Selected Tabs list.
Click Next.
5. Select the Visible checkbox to make this app visible to all profiles and then click Save.
Tell Me More....
If it seems like you just created a page within a container, within another container, you did. And you're about to put all of that in another
container! What's with all these containers and what do they do?
•A tab is a container for things you want to display on the same page, such as a chart, a table, or the Visualforce page your created.
•An app is a container for tabs that appear next to each other. When you create an app, it's available in the app picker in the upper
right hand corner of the screen.
•A package is a container for things you upload to the AppExchange. Usually a package contains an app your customers can install
in their org, but you can also upload packages that extend existing apps. You haven't created a package yet, you'll do that in the
next step.
Step 2: Package Your App
In this step you'll package the app so you can distribute it on the AppExchange. A package is simply a container for components. In this
case it's your app, tab, and page.
1. From Setup, enter Packages in the Quick Find box, select Packages, and then click New.
2. In the Package Name field enter Hello World and then click Save.
3. On the Package Detail page click Add Components.
4. Select your Hello World app and then click Add to Package.
Tell Me More....
When you clicked Add to Package, did you notice that your Hello tab and Greeting page were automatically added to the package?
When you create a package, the framework automatically detects dependent components and adds them to the package.
Step 3: Assign a Namespace
In this step you'll choose a unique identifier called a namespace. A namespace differentiates your components from other components
and allows you to do things such as upgrade the app after it's been installed. Choose your namespace carefully as it can’t be changed
later.
1. From Setup, enter Packages in the Quick Find box, then select Packages.
2. In the Developer Settings list, click Edit and on the following page click Continue.
3. In the Namespace Prefix field, enter a 1-15 character alphanumeric ID and then click Check Availability. Repeat this step until you
have a unique namespace.
4. In the Package to be managed field choose your Hello World package and then click Review Your Selections.
5. Review the information on the page and then click Save.
8
Step 2: Package Your AppISVforce Quick Start
Tell Me More....
Within the underlying code, your namespace is prepended to all components that are packaged from your dev org. This allows your
package and its contents to be distinguished from those of other developers, and ensures your exclusive control of all packaged
components.
Step 4: Upload a Beta
Before you upload a production version of your app, it's a common practice to upload a beta version for testing.
1. From Setup, enter Packages in the Quick Find box, then select Packages.
2. On the Packages page, click your Hello World package and then click Upload.
3. On the Upload Package page, enter a version name and number.
4. For the Release Type, make sure to choose Managed — Beta.
5. Scroll to the bottom and click Upload. It may take a moment for the upload to complete.
Congratulations, you've uploaded an app to the AppExchange! Your app isn't available to the public, but you can access it through an
install link. You'll do that in the next step.
Tell Me More....
The purpose of a beta is for testing only. Therefore, a beta can only be installed in a test org, Developer Edition, or sandbox (more on
that later). Next you'll install the beta in the test org you created in Step 2: Create a Development and Test Environment.
Step 5: Install and Test the Beta
Installing the beta is easy, just click the link and provide the username and password you use for your test org.
1. Click the Installation URL now.
Installation URL Link
2. On the login page, enter the Username and Password of your test org.
3. On the Package Installation Details page, click Continue.
4. Click Next.
5. On the Security Level page, Grant access to all users and click Next.
6. Click Install.
7. Once the installation completes, you can select your app from the app picker in the upper right corner.
9
Step 4: Upload a BetaISVforce Quick Start
Hello World App
8. You should see your Hello tab, and the greeting text on your page.
Hello World Tab and Page
At this point you would normally test the application and make sure it works as designed. Your app installs easily and displays what you
want, so let's move on.
Tell Me More....
Beta packages can also be installed in sandboxes. A sandbox is a replica of your customer's org that allows them to develop, test, or
install apps, and verify the changes they want to commit. None of the orgs you've signed up for in this workbook have a sandbox, but
if you have a sandbox in another org and want to install your app in it, you must replace the initial portion of the Installation URL with
http://test.salesforce.com.
Development Summary
Congratulations, you just completed an essential part of the software development lifecycle! Further changes to your app will follow
the same procedure:
1. Modify the existing app in your dev org.
2. Package the app.
3. Upload as a beta package.
4. Install the beta in a test org.
5. Test the installed app.
10
Development SummaryISVforce Quick Start
Tutorial #3: Publishing and Licensing
Imagine you've been through a few development cycles with your beta and you're ready to publish a public app. The next step is to
upload a production app, or what we call a managed released version of your app. Then you can create a listing so that other people can
find your app and know what it does. Finally, you want to connect your app to your business org so you manage the licenses for people
that install your app.
Step 1: Uploading to the AppExchange
This step will seem familiar, it's similar to uploading a beta.
1. If you've been following along non-stop, you're probably still logged in to your test org. Go ahead and log in to your dev org now.
2. Notice in the upper right corner there's a link that says Developing Hello World, version 1.0. Click that link to go directly to the
Package Detail page.
Developing Hello World, version 1.0
3. On the Package Detail page, click Upload.
4. For the Release Type, choose Managed — Released.
5. Scroll to the bottom and click Upload.
6. Click OK on the popup.
Step 2: Create an AppExchange Listing
In this step, you create an AppExchange listing, which is the primary way customers discover apps, components, and services to enhance
their Salesforce experience.
1. After your package uploads, click the link to publish on the AppExchange. You are directed to the Listings tab on the Publishing
page.
2. If prompted, enter your login credentials for the Partner Community.
11
Tutorial #3: Publishing and LicensingISVforce Quick Start
3. Read and agree to the terms and conditions, and then click I Agree.
4. The first question asks if you’ve already listed on the AppExchange. You did that in Tutorial 1, Step 4: Edit Your Publisher Profile on
page 6, so select Yes and click Continue.
5. Click Link New Organization.
6. You’re prompted for your username and password. Enter the values for your development org.
7. Click the Publishing tab.
8. Click New Listing.
9. Enter a listing title, such as Hello World App by <your name>. Adding your name helps ensure that your listing title is
unique.
10. Choose App, and then click Save & Next to open the AppExchange publishing console.
11. On the Text tab, fill in the required fields, and then click Save & Next again.
Tell Me More...
Don’t be concerned with making your listing perfect, because it’s not public yet, and you can change the listing at any time.
Step 3: Complete the AppExchange Listing
Many customers like to see and experience a product before they decide to purchase. We give you several ways to show off your app
or component in an AppExchange listing. For example, you can add screenshots and videos to draw attention to key features, or add
white papers to help demonstrate business value. You can also let customers try your offering in their own organizations or set up a test
environment that you’ve customized.
1. If you’re not already there, click the Media tab in the AppExchange publishing console.
2. Add an app logo, tile image, and screenshot. Because your listing isn’t used outside of this tutorial, use any image file that you have
available.
3. Click the App tab, and then select An app that includes a package (entirely or in part).
4. Click Select Package and choose the package that you uploaded in the previous step.
5. For the installation method, select Directly from the AppExchange.
6. Choose whether you want the app to be installed for every user in the customer’s organization or just system administrators. For
this tutorial, either option is fine.
7. For app specifications, select editions and languages. For this tutorial, you can select any available edition and language.
8. Click Save & Next.
9. Click Save & Next twice, because you don’t want to configure a free trial or set up lead collection for this app.
10. For pricing, select Free. Use the default values for all other fields.
11. Agree to the terms and conditions, and then click Save.
Congratulations—you’ve completed your first listing! Like everything else you’ve done so far, you can go back and change it later if you
want.
Step 4: Manage Licenses for Your App
The License Management App (LMA) helps you manage sales, licensing, and support for your offering. The LMA comes preinstalled in
your business organization. In this step, you connect your app to the LMA.
12
Step 3: Complete the AppExchange ListingISVforce Quick Start
Note: This feature is available to eligible partners. For more information on the Partner Program, including eligibility requirements,
visit www.salesforce.com/partners.
1. If you haven’t done so already, log in to the Partner Community.
2. On the Publishing page, click the Packages tab.
3. Find the package that you want to link, and then click Manage Licenses.
4. Click Register.
5. Enter the login credentials of your partner business org, and then click Submit.
6. For the default license type, choose free trial.
7. Enter a trial length in days.
8. For the number of seats, choose the site-wide license.
9. Click Save.
It can take up to 30 minutes for your app to be connected to the LMA. Take a break; you’ve earned it!
Publishing and Licensing Summary
In this tutorial, you uploaded your managed-released app to the AppExchange and created a listing for your app. You also linked your
app to the License Management App, available in your business organization. You can use the LMA to manage and renew licenses and
to set default license settings. For example, you can license your app as a free trial that expires after a specified number of days. For more
information, see Managing Licenses on page 199.
Right now your app has a private listing on the AppExchange that you can share with potential customers, but the public doesn't see
it unless they have the link. Before you can list the app publicly, you'll need to pass a security review, which is beyond the scope of this
quick start. For more information, see Security Review Steps on page 121.
Tutorial #4: Updating Your App
If you're familiar with Salesforce, you know we do weekly patch releases to fix bugs, and a few times a year we have a major release to
introduce new features. As an ISV, you can do the same thing by delivering a patch release to fix bugs and a major release for new
features.
•For new features, the process is the same as you've experienced. You start by modifying your app, package it, upload a beta, test
the beta, and then upload a managed-released version. Major releases increment the version to the next whole number, from 1.0
to 2.0, for example, and minor releases to the first dot from 1.0 to 1.1. There are no hard rules for what constitutes a major or minor
release. That's up to you.
•For bug fixes, the process is slightly different. You start by creating a patch org, a special environment which has limited functionality
and can only be used to develop a patch for a specific package. After you upload the patch, you have the option of pushing the
patch to your customers, so they get your bug fixes the next time they log in. Minor releases increment the version number to the
second decimal, from 1.0 to 1.0.1, for example.
•Major or minor releases must be installed by customers (pulled). However, you can push patch releases directly to customer orgs.
This feature is only available to registered ISVforce/OEM partners. For more information on the Partner Program, including eligibility
requirements, please visit us at www.salesforce.com/partners.
Since the process for developing a major release is already familiar, let's do a patch release and then deliver it by pushing the patch to
our customers.
13
Publishing and Licensing SummaryISVforce Quick Start
Step 1: Creating a Patch Organization
In order to create a patch, you need to generate a new patch development organization.
To create a patch version:
1. From Setup, enter Packages in the Quick Find box, then select Packages.
2. Click the name of your managed package.
3. Click the Patch Organization tab and then click New.
4. Select the package version that you want to create a patch for in the Patching Major Release drop-down list. The release type must
be Managed - Released.
5. Enter a Username for a login to your patch organization.
6. Enter an Email Address associated with your login.
7. Click Save.
Note: If you ever lose your login information, click Reset on the package detail page under Patch Development Organizations
to reset the login to your patch development organization.
In a moment you'll receive an email with your login credentials. After you've logged in and changed your password, proceed to the next
step.
Tell Me More....
Development in a patch development organization is restricted. The following is a list of caveats:
•New package components can’t be added.
•Existing package components can’t be deleted.
•API and dynamic Apex access controls can’t change for the package.
•No deprecation of any Apex code.
•No new Apex class relationships, such as extends, can be added.
•No new Apex access modifiers, such as virtual or global, can be added.
•No new Web services can be added.
•No new feature dependencies can be added.
Step 2: Developing a Patch
We're going to make a simple change to your app. Instead of displaying just Hello World, you'll add today's date.
1. In your patch org, from Setup, enter Packages in the Quick Find box, select Packages, then click your Hello World package.
2. In the list of Package Components, click your Greeting page.
3. Click Edit.
4. Right after the closing </h1> tag, enter the following:
<br/>
<apex:outputText value="The date and time is: {!NOW()}"/>
5. Click Save.
6. To see the output, click the Hello tab and you'll notice that today's time and date are displayed.
14
Step 1: Creating a Patch OrganizationISVforce Quick Start
Display the date and time
That's as much as we need to do in this patch. Let's move on.
Tell Me More....
The !NOW function returns the date in a standard format. There are many more built-in functions and ways to format the output. For
more information, see the Visualforce Developer's Guide.
Step 3: Uploading the Patch
Typically the next step is to upload a beta patch and install that in a test organization. Since this is very similar to Step 4: Upload a Beta
and Step 5: Install and Test the Beta, that you completed in Tutorial #2: Developing Your App, we won't make you do that again.
1. In your patch org, from Setup, enter Packages in the Quick Find box, select Packages, and click your Hello World package.
2. On the Upload Package page, click Upload.
3. Enter a version name, such as today's date.
4. Notice that the Version Number has had its patchNumber incremented.
5. Select Managed — Released.
6. Optionally, enter and confirm a password to share the package privately with anyone who has the password. Don't enter a password
if you want to make the package available to anyone on AppExchange and share your package publicly.
7. Salesforce automatically selects the requirements it finds. In addition, select any other required components from the Package
Requirements and Object Requirements sections to notify installers of any requirements for this package.
8. Click Upload.
Congratulations, you've uploaded a patch release. You'll want to share that patch with others, and you'll do that next.
Step 4: Installing or Pushing a Patch
There are two ways to deliver a patch, you can have your customers install it, or you can push it to them. Push upgrades happen
automatically, that is, the next time your customer logs in, they have the updates. Let's try that.
1. Log in to your dev org.
15
Step 3: Uploading the PatchISVforce Quick Start
2. In the upper right corner, click Developing Hello World, version 1.0.
Developing Hello World, version 1.0
3. On the Package Detail page, click Push Upgrades.
4. Click Schedule Push Upgrades.
5. From the Patch Version drop-down list, select the patch version to push.
6. In the Scheduled Start Date field, enter today's date.
7. In the Select Target Organizations section, select your test org.
8. Click Schedule.
And you've done it! You pushed a patch release to your subscriber so that they automatically get your updates. You should verify that
your customers received the patch to ensure it was installed successfully.
Tell Me More....
Beta versions aren't eligible for push upgrades. You must uninstall a beta and then install a new one.
Updating Your App Summary
In this tutorial you learned how to update your app in a patch org and push that update to your customers. You started by creating a
patch organization that was specific to a released package version. Then you modified your app, uploaded it, and scheduled the push
upgrade to your customers.
Congratulations, you're done! Or have you really just begun? You can modify your existing app to be anything you want it to be, or
create a new dev org in the Environment Hub and build another app. You can use the same sales and test orgs and everything else
you've configured to publish and manage many more apps. You're on your way to ISVforce success!
16
Updating Your App SummaryISVforce Quick Start
CHAPTER 3 Designing and Building Your App
This section contains important concepts and architectural decisions to consider before you start
development, such as:
In this chapter ...
•Overview of
Packages •Understanding Managed and Unmanaged Packages
•Components Available for Packaging
•Components
Available in
Managed Packages
•Special Behavior of Components in Packages
•Limits for Group and Professional Editions
•About API and
Dynamic Apex
Access in Packages
•Understanding Dependencies
•Working With External Services
•Protecting Your Intellectual Property
•Architectural
Considerations for •Working with Connected Apps
Group and
Professional Editions
•Connected Apps
•Environment Hub
•Notifications for
Package Errors
17
Overview of 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 forms—unmanaged and managed:
Unmanaged packages
Unmanaged packages are typically used to distribute open-source 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 can't change or upgrade them. Unmanaged packages should not be used to migrate components
from a sandbox to production organization. Instead, use Change Sets.
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 user-based 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
•Built-in 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 conflict-free installs
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.
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 can’t.
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 non-upgradeable 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 can’t be edited by either the developer or subscriber.
18
Overview of PackagesDesigning and Building Your App
Planning the Release of Managed Packages
Releasing an AppExchange package is similar to releasing any other program in software development. You may want to roll it out in
iterations to ensure each component functions as planned. You may even have beta testers who have offered to install an early version
of your package and provide feedback.
Once you release a package by publishing it on AppExchange, anyone can install it. So, plan your release carefully. Review the states
defined below to familiarize yourself with the release process. Salesforce automatically applies the appropriate state to your package
and components depending on the upload settings you choose and where it is in the release process.
DescriptionState
The package has not been converted into a managed package or the component has
not been added to a managed package. Note that a component that is “Managed - Beta”
Unmanaged
can become “Unmanaged” if it is removed from a managed package. All packages are
unmanaged unless otherwise indicated by one of the managed icons below.
The package or component was created in the current Salesforce organization and is
managed, but it is not released because of one of these reasons:
Managed - Beta
•It has not been uploaded.
•It has been uploaded with Managed - Beta option selected. This option prevents
it from being published, publicly available on AppExchange. The developer can still
edit any component but the installer may not be able to depending on which
components were packaged.
Note: Don’t install a Managed - Beta package over a Managed - Released package.
If you do, the package is no longer upgradeable and your only option is to uninstall
and reinstall it.
The package or component was created in the current Salesforce organization and is
managed. It is also uploaded with the Managed - Released option selected,
Managed - Released
indicating that it can be published on AppExchange and is publicly available. Note that
once you have moved a package to this state, some properties of the components are
no longer editable for both the developer and installer.
This type of release is considered a major release on page 253.
If you need to provide a minor upgrade to a managed package, consider creating a patch
instead of a new major release. A patch enables a developer to change the functionality
Patch
of existing components in a managed package, while ensuring that subscribers experience
no visible changes to the package.
This type of release is considered a patch release on page 253.
The package or component was installed from another Salesforce organization but is
managed.
Managed - Installed
A developer can refine the functionality in a managed package over time, uploading and releasing new versions as the requirements
evolve. This might involve redesigning some of the components in the managed package. Developers can delete some, but not all,
types of components in a Managed - Released package when upgrading it. For details, see Delete Components in Managed Packages
on page 259.
19
Planning the Release of Managed PackagesDesigning and Building Your App
Create a Package
EDITIONS
Available in: Salesforce
Classic 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”
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.
Tip: Before you begin, determine if you want to create and upload a managed or unmanaged
package.
1. From Setup, enter Packages in the Quick Find box, then select Packages.
2. Click New.
3. Enter a name for your package. This does not have to be the same name that appears on
AppExchange.
4. From the drop-down menu, select the default language of all component labels in the package.
5. Optionally, choose a custom link from the Configure Custom Link field to display
configuration information to installers of your app. You can select a predefined custom link to
a URL or s-control that you have created for your home page layouts; see the Configure Option
on page 52. The custom link displays as a Configure link within Salesforce on the Force.com
AppExchange Downloads page and app detail page of the installer's organization.
6. Optionally, in the Notify on Apex Error field, enter the username of the person who
should receive an email notification if an exception occurs in Apex that is not caught by the
Apex code. If you do not specify a username, all uncaught exceptions generate an email
notification that is sent to Salesforce. This is only available for managed packages. For more
information, see Handling Apex Exceptions in Managed Packages.
Note: Apex can only be packaged from Developer, Enterprise, Unlimited, and Performance Edition organizations.
7. Optionally, in the Notify on Packaging Error field, enter the email address of the person who receives an email notification
if an error occurs when a subscriber’s attempt to install, upgrade, or uninstall a packaged app fails. This field appears only if packaging
error notifications are enabled. To enable notifications, contact your Salesforce representative.
8. Optionally, enter a description that describes the package. You will have a chance to change this description before you upload it
to AppExchange.
9. Optionally, specify a post install script. This is an Apex script that runs in the subscriber organization after the package is installed or
upgraded. For more information, see Running Apex on Package Install/Upgrade.
10. Optionally, specify an uninstall script. This is an Apex script that runs in the subscriber organization after the package is uninstalled.
For more information, see Running Apex on Package Uninstall.
11. Click Save.
Developing and Distributing Unmanaged Packages
Unmanaged packages are traditionally used for distributing open-source projects to developers, or as a one time drop of applications
that require customization after installation. You should never use unmanaged packages for sandbox to production migration. Instead,
use theForce.com IDE or the Force.com Migration Tool. If you’re using Enterprise, Unlimited, or Performance Edition, see Change Sets.
SEE ALSO:
Components Available in Unmanaged Packages
20
Create a PackageDesigning and Building Your App
Create and Upload an Unmanaged Package
Use the following procedure to upload an unmanaged package through the UI. (You can also upload a package using the Tooling API.
For sample code and more details, see the PackageUploadRequest object in the Tooling API Developer Guide.)
1. Create the package:
a. From Setup, enter Packages in the Quick Find box, then select Packages.
b. Click New.
c. Fill in the details of the package.
d. Click Save.
2. Add the necessary components for your app.
a. Click Add Components.
b. From the drop-down list, choose the type of component.
c. Select the components you want to add.
Note: Some components cannot be added to Managed - Released packages. For a list of packageable components, see
Components Available in Managed Packages on page 21. Also, S-controls cannot be added to packages with restricted
API access.
d. Click Add To Package.
e. Repeat these steps until you have added all the components you want in your package.
Note: Some related components are automatically included in the package even though they might not display in the Package
Components list. For example, when you add a custom object to a package, its custom fields, page layouts, and relationships
with standard objects are automatically included. For a complete list of components, see Components Automatically Added
to Packages on page 35.
3. Click Upload.
You will receive an email that includes an installation link when your package has been uploaded successfully. Wait a few moments
before clicking the installation link or distributing it to others, as it might take a few minutes for it to become active.
Components Available in Managed Packages
Not all components can be packaged for distribution. If you create an app that uses components that aren't packageable, your subscribers
will have to create and configure those components after they install your app. If ease of installation is an important concern for your
subscribers, keep the packageable components in mind as you develop.
The following table shows the components that are available in a managed package, and whether or not it is updateable or deletable.
The following sections describe the table columns and their values.
Upgradeable
Some components are updated to a newer version when a package is upgraded.
•No: The component is not upgraded.
•Yes: The component is upgraded.
Subscriber Deletable
A subscriber or installer of a package can delete the component.
•No: The subscriber cannot delete the component.
21
Create and Upload an Unmanaged PackageDesigning and Building Your App
•Yes: The subscriber can delete the component.
Developer Deletable
A developer can delete some components after the package is uploaded as Managed - Released. Deleted components are not
deleted in the subscriber's organization during a package upgrade. The Protectable attribute contains more details on deleting
components.
•No: The developer cannot delete a Managed - Released component.
•Yes: The developer can delete a Managed - Released component.
Protectable
Developers can mark certain components as protected. Protected components can’t be linked to or referenced by components
created in a subscriber org. A developer can delete a protected component in a future release without worrying about failing
installations. However, once a component is marked as unprotected and is released globally, the developer can’t delete it. When
the subscriber upgrades to a version of the package where the component is deleted, the component is removed from the subscriber's
organization.
•No: The component cannot be marked protected.
•Yes: The component can be marked protected.
IP Protection
Certain components automatically include intellectual property protection, such as obfuscating Apex code. The only exceptions are
Apex methods declared as global, meaning that the method signatures can be viewed by the subscriber. The information in the
components you package and publish might be visible to users on AppExchange. Use caution when adding your code to a custom
s-control, formula, Visualforce page, or any other component that you cannot hide in your app.
•No: The component does not support intellectual property protection.
•Yes: The component supports intellectual property protection.
IP ProtectionProtectableDeveloper
Deletable
Subscriber
Deletable
UpgradeableComponent
NoNoNoNoYesAction
YesNoYes (if not set to
global access)
NoYesApex Class
NoNoNoNoYesApex Sharing
Reason
NoNoYesYesNoApex Sharing
Recalculation
YesNoYesNoYesApex Trigger
NoNoYesYesNoApplication
NoNoNoNoYesArticle Type
NoNoNoYesNoCall Center
NoNoNoNoYesCompact Layout
NoNoYesYesYesConnected App
22
Components Available in Managed PackagesDesigning and Building Your App
IP ProtectionProtectableDeveloper
Deletable
Subscriber
Deletable
UpgradeableComponent
NoNo, except custom
links (for Home page
only)
Yes**Yes*YesCustom Button or
Link
NoNoYes**Yes*YesCustom Console
Components 1
NoNoYes**Yes*YesCustom Field
NoYesYes, if protectedNoYesCustom Label
NoNoYes**Yes*YesCustom Object
NoNoNoNoYesCustom Permission
NoNoNoNoYesCustom Report
Type
YesNoYes**Yes*YesCustom Setting
NoNoYesYesNoDashboard
NoNoYesYesNoDocument
NoNoYesYesNoEmail Template
NoNoNoNoYesExternal Data
Source
NoNoYes**Yes*YesField Set
NoNoNoNoYesLightning Page
NoNoNoYesYesFlow
NoNoYesYesNoFolder
NoNoNoNoYesHome Page
Component
NoNoYesYesNoHome Page Layout
NoNoYesYesNoLetterhead
NoNoNoNoNoLightning
Application
NoNoNoNoYesLightning
Component
NoNoNoNoYesLightning Event
NoNoNoNoYesLightning Interface
1Requires a Service Cloud license.
23
Components Available in Managed PackagesDesigning and Building Your App
IP ProtectionProtectableDeveloper
Deletable
Subscriber
Deletable
UpgradeableComponent
NoNoYesYesNoList View
NoNoNoNoYesNamed Credential
NoNoYesYesNoPage Layout
NoNoYes**Yes*YesPermission Set
NoNoNoNoNoPlatform Cache
See Flow.Process
NoNoYes**Yes*YesRecord Type
NoNoYesYesNoRemote Site
Setting
NoNoYesYesNoReport
NoNoYesYesNoReporting
Snapshot
NoNoNoNoYesS-Control
NoNoYes**Yes*YesStatic Resource
NoNoYes**Yes*YesTab
NoNoNoNoYesTranslation
NoNoYes**Yes*YesValidation Rule
YesNoYes**Yes***YesVisualforce
Component
NoNoYes**Yes*YesVisualforce Page
NoNoYesNoYesWave App
NoNoYesNoYesWave Dashboard
NoNoYesNoYesWave Dataflow
NoNoYesNoYesWave Dataset
NoNoYesNoYesWave Lens
NoYesYes, if protectedNoYesWorkflow Email
Alert
NoYesYes, if protectedNoYesWorkflow Field
Update
NoYesYes, if protectedNoYesWorkflow
Outbound
Message
24
Components Available in Managed PackagesDesigning and Building Your App
IP ProtectionProtectableDeveloper
Deletable
Subscriber
Deletable
UpgradeableComponent
NoNoNoNoYesWorkflow Rule
NoYesYes, if protectedNoYesWorkflow Task
* If you remove this component type from a new version of your package and a subscriber upgrades, the Administrator (System
Administrator) of the subscriber organization can delete the component.
** If the ability to remove components has been enabled for your packaging organization, you can delete these component types even
if they are part of a Managed - Released package.
*** If you remove a public Visualforce component from a new version of your package and a subscriber upgrades, the component is
removed from the subscriber’s organization upon upgrade. If the Visualforce component is global, it remains in the subscriber organization
until the Administrator (System Administrator) deletes it.
Component Attributes and Behaviors
Only some attributes of a component are upgradeable. Many components also behave differently or include additional restrictions
in a managed package. It's important to consider these behaviors when designing your package.
If you register your namespace after you referenced a flow in a Visualforce page or Apex code, don’t forget to add the namespace
to the flow name. Otherwise, the package will fail to install.
Deleting Visualforce Pages and Global Visualforce Components
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.
SEE ALSO:
Editing Components and Attributes after Installation
Components Automatically Added to Packages
Delete Components in Managed Packages
Components Available in Unmanaged Packages
Not all components can be packaged for distribution. The following table lists the components that are available in an unmanaged
package, how the component is included in the package, and whether the component supports automatic renaming.
Packaged Explicitly or Implicitly
Components can be added either explicitly or implicitly. Explicit components must be included directly in the package, while implicit
components are automatically added. For example, if you create a custom field on a standard object, you must explicitly add the
custom field to your package. However, if you create a custom object and add a custom field to it, the field is implicitly added to the
package when you add the custom object.
•Explicitly: The component must be manually added to the package.
•Implicitly: The component is automatically added to the package when another dependent component, usually a custom
object, is added.
Automatic Renaming
Salesforce can resolve naming conflicts automatically on install.
•No: If a naming conflict occurs the install is blocked.
25
Components Available in Unmanaged PackagesDesigning and Building Your App
•Yes: If a naming conflict occurs Salesforce can optionally change the name of the component being installed.
Automatic RenamingPackaged Explicitly or ImplicitlyComponent
YesExplicitlyReporting Snapshot
NoExplicitlyApex Class
NoImplicitly
On an extension: Explicitly
Apex Sharing Reason
NoImplicitlyApex Sharing Recalculation
NoOn a standard or extension object: Explicitly
On an object in the package: Implicitly
Apex Trigger
NoExplicitlyApplication
NoOn a standard object: Explicitly
On a custom object: Implicitly
Custom Button or Link
NoOn a standard object: Explicitly
On a custom object: Implicitly
Custom Field
NoImplicitlyCustom Label
NoExplicitlyCustom Object
NoImplicitly
With required custom permissions: Explicitly
Custom Permission
NoExplicitlyCustom Report Type
NoExplicitlyCustom Setting
YesExplicitly
In a folder: Implicitly
Dashboard
YesExplicitly
In a folder: Implicitly
Document
YesExplicitly
In a folder: Implicitly
Email Template
NoExplicitly
Referenced by an external object: Implicitly
External Data Source
Assigned by a permission set: Implicitly
YesExplicitlyFolder
NoExplicitlyHome Page Component
26
Components Available in Unmanaged PackagesDesigning and Building Your App
Automatic RenamingPackaged Explicitly or ImplicitlyComponent
NoExplicitlyHome Page Layout
YesExplicitlyLetterhead
NoExplicitlyLightning Application
NoExplicitlyLightning Component
NoExplicitlyLightning Event
NoExplicitlyLightning Interface
YesOn a standard object: Explicitly
On a custom object: Implicitly
List View
NoExplicitlyNamed Credential
NoOn a standard object: Explicitly
On a custom object: Implicitly
Page Layout
NoOn a standard object: Explicitly
On a custom object: Implicitly
Record Type
YesExplicitly
In a folder: Implicitly
Report
NoExplicitlyS-Control
NoExplicitlyStatic Resource
NoExplicitlyTab
NoExplicitlyTranslation
NoOn a standard object: Explicitly
On a custom object: Implicitly
Validation Rule
NoExplicitlyVisualforce Component
NoExplicitlyVisualforce Page
NoExplicitlyWorkflow Email Alert
NoExplicitlyWorkflow Field Update
NoExplicitlyWorkflow Outbound Message
NoExplicitlyWorkflow Rule
27
Components Available in Unmanaged PackagesDesigning and Building Your App
Automatic RenamingPackaged Explicitly or ImplicitlyComponent
NoExplicitlyWorkflow Task
SEE ALSO:
Components Automatically Added to Packages
Editing Components and Attributes after Installation
The following table shows which components and attributes are editable after installation from a managed package.
Developer Editable
The developer can edit the component attributes in this column. These attributes are locked in the subscriber’s organization.
Subscriber and Developer Editable
The subscriber and developer can edit the component attributes in this column. However, these attributes aren’t upgradeable. Only
new subscribers receive the latest changes.
Locked
After a package is Managed - Released, the developer and subscriber can’t edit the component attributes in this column.
LockedSubscriber and Developer
Editable
Developer EditableComponent
Action •• Target Record Type All fields except Target
Record Type
•Action layout
•Predefined values for action
fields
Reporting Snapshot •• Reporting Snapshot Unique
Name
All attributes except
Reporting Snapshot Unique
Name
Apex Class •• API Version Name
•Code
Apex Sharing Reason •• Reason NameReason Label
Apex Sharing Recalculation •Apex Class
Apex Trigger •• API Version Name
•Code
Application •• App NameAll attributes except App
Name
28
Editing Components and Attributes after InstallationDesigning and Building Your App
LockedSubscriber and Developer
Editable
Developer EditableComponent
Article Types •• Available for Customer
Portal
•Description Name
•Label
•Channel Displays
•Plural Label
•Default Sharing Model
•Starts with a Vowel Sound
•Development Status
•Enable Divisions
•Grant Access Using
Hierarchy
•Search Layouts
Compact Layout •All attributes
Connected App •API Name
•ACS URL
•Access Method
•Canvas App URL •Created Date/By
•Entity ID
•IP Relaxation
•Callback URL •Consumer Key
•Consumer Secret
•Manage Permission Sets
•Connected App Name
•Contact Email •Installed By
•Manage Profiles
•Mobile Start URL
•Contact Phone •Installed Date
•Last Modified Date/By
•Permitted Users
•Description
•Icon URL •• Refresh Token Policy Version
•• SAML AttributesInfo URL
•Trusted IP Range •Service Provider Certificate
•Start URL
•Locations
•Logo Image URL •Subject Type
•OAuth Scopes
Custom Button or Link •Display Type
•Height
•Behavior
•Button or Link URL •• Resizeable Name
•• Show Address BarContent Source
•Description •Show Menu Bar
•Show Scrollbars
•Display Checkboxes
•Label •Show Status Bar
•Show Toolbars
•Link Encoding
•Width
•Window Position
Custom Field •Child Relationship Name
•Chatter Feed Tracking
•Auto-Number Display
Format •• Data TypeHelp Text
29
Editing Components and Attributes after InstallationDesigning and Building Your App
LockedSubscriber and Developer
Editable
Developer EditableComponent
•Decimal Places •• External IDMask Type
•Mask Character
•Description •Field Name
•Roll-Up Summary Field
•Sharing Setting
•Default Value
•Field Label •Roll-Up Summary Object
•Sort Picklist Values
•• Formula •Roll-Up Summary TypeTrack Field History
• •
Length Unique
•Lookup Filter
•Related List Label
•Required
•Roll-Up Summary Filter
Criteria
Custom Label •• Category Name
•Short Description
•Value
Custom Object •Object Name
•Allow Activities
•Description
•Label •Record Name Data Type
•Allow Reports
•Available for Customer
Portal
•Plural Label •Record Name Display
Format
•Record Name
•Context-Sensitive Help
Setting
•Starts with a Vowel Sound
•Default Sharing Model
•Development Status
•Enable Divisions
•Enhanced Lookup
•Grant Access Using
Hierarchy
•Search Layouts
•Track Field History
Custom Permission •Connected App
•Description
•Label
•Name
Custom Report Type ••• Report Type NameDevelopment StatusAll attributes except
Development Status and
Report Type Name
30
Editing Components and Attributes after InstallationDesigning and Building Your App
LockedSubscriber and Developer
Editable
Developer EditableComponent
Custom Setting •Object Name
•Description
• • Setting TypeLabel
•Visibility
Dashboard •• Dashboard Unique NameAll attributes except
Dashboard Unique Name
Document •• Document Unique NameAll attributes except
Document Unique Name
Email Template •• Email Template NameAll attributes except Email
Template Name
External Data Source •• Auth Provider
•NameType
•Certificate
•Custom Configuration
•Endpoint
•Identity Type
•OAuth Scope
•Password
•Protocol
•Username
Field Set ••• Description NameSelected fields (only
subscriber controlled)
•Label
•Available fields
Lightning Page •Lightning Page
Flow •Flow Unique Name
•Name
•Entire flow
•• URLDescription
•Status
Folder •• Folder Unique NameAll attributes except Folder
Unique Name
Home Page Component •Name
•Body
• •
Component Position Type
31
Editing Components and Attributes after InstallationDesigning and Building Your App
LockedSubscriber and Developer
Editable
Developer EditableComponent
Home Page Layout •• Layout NameAll attributes except Layout
Name
Letterhead •• Letterhead NameAll attributes except
Letterhead Name
NameLightning Application •API Version
•Description
•Label
•Markup
NameLightning Component •API Version
•Description
•Label
•Markup
NameLightning Event •API Version
•Description
•Label
•Markup
NameLightning Interface •API Version
•Description
•Label
•Markup
List View •• View Unique NameAll attributes except View
Unique Name
Named Credential •• Auth Provider
•Endpoint Name
•• CertificateLabel
•Identity Type
•OAuth Scope
•Password
•Protocol
•Username
Page Layout •• Page Layout NameAll attributes except Page
Layout Name
32
Editing Components and Attributes after InstallationDesigning and Building Your App
LockedSubscriber and Developer
Editable
Developer EditableComponent
Permission Set •• Description Name
•Label
•Custom object permissions
•Custom field permissions
•Apex class access settings
•Visualforce page access
settings
Platform Cache •All attributes
Record Type •• Active
•Description Name
•• Business ProcessRecord Type Label
All attributes except Remote Site
Name
Remote Site Setting •Remote Site Name
Report •• Report Unique NameAll attributes except Report
Unique Name
S-Control •S-Control Name
•• Content Prebuild in Page
• •
Description Type
•Encoding
•Filename
•Label
Static Resource •• Description Name
•File
Tab •• Salesforce Mobile Classic
Ready
•Description Tab Name
•Encoding
•Tab Style
•Has Sidebar
•Height
•Label
•S-control
•Splash Page Custom Link
•Type
•URL
•Width
Translation •All attributes
33
Editing Components and Attributes after InstallationDesigning and Building Your App
LockedSubscriber and Developer
Editable
Developer EditableComponent
Validation Rule ••• Description Rule NameActive
•Error Condition Formula
•Error Location
•Error Message
Visualforce Component •• API Version Name
•Description
•Label
•Markup
Visualforce Page •• API Version Name
•Description
•Label
•Markup
Workflow Email Alert •• Additional Emails Description
•Email Template
•From Email Address
•Recipients
Workflow Field Update ••• Description NameLookup
•Field Value
•Formula Value
Workflow Outbound Message ••• Description NameUser to Send As
•Endpoint URL
•Fields to Send
•Send Session ID
Workflow Rule ••• Description Rule NameActive
•Evaluation Criteria
•Rule Criteria
Workflow Task •• Assign To Subject
•Comments
•Due Date
•Priority
•Record Type
•Status
34
Editing Components and Attributes after InstallationDesigning and Building Your App
Components Automatically Added to Packages
When adding components to your package, some related components are automatically added, if required. For example, if you add a
Visualforce page to a package that references a custom controller, that Apex class is also added.
To understand what components might be automatically included, review the following list:
These types of components might be automatically included:When you add this component:
Action target object (if it’s a custom object), action target field, action record type, predefined
field values, action layout; and any custom fields that the action layout or predefined values
refer to on the target object
Action
ReportsReporting Snapshot
Custom fields, custom objects, and other explicitly referenced Apex classes, as well as anything
else that is directly referenced by the Apex class
Apex class
Note: If an Apex class references a custom label, and that label has translations, you
must explicitly package the individual languages desired in order for those translations
to be included.
Custom fields, custom objects, and any explicitly referenced Apex classes, as well as anything
else that is directly referenced by the Apex trigger
Apex trigger
Custom fields, the default page layoutArticle type
Custom fieldsCompact layout
Custom tabs (including web tabs), documents (stored as images on the tab), documents
folder
Custom app
Custom fields and custom objectsCustom button or link
Custom objectsCustom field
Custom home page components on the layoutCustom home page layouts
Apex sharing reasons, Apex sharing recalculations, Apex triggers, custom buttons or links,
custom fields, list views, page layouts, record types, validation rules
Custom settings
Custom fields, validation rules, page layouts, list views, custom buttons, custom links, record
types, Apex sharing reasons, Apex sharing recalculations, and Apex triggers
Custom object
Note:
•Apex sharing reasons are unavailable in extensions.
•When packaged and installed, only public list views from an app are installed. If a
custom object has any custom list views that you want to include in your package,
ensure that the list view is accessible by all users.
35
Components Automatically Added to PackagesDesigning and Building Your App
These types of components might be automatically included:When you add this component:
External data source, custom fields, page layouts, list views, custom buttons, and custom linksCustom object (as an external object)
Note:
•When packaged and installed, only public list views from an app are installed. If
an external object has any custom list views that you want to include in your
package, ensure that the list view is accessible by all users.
•In managed and unmanaged packages, external objects are included in the custom
object component.
Custom objects (including all of its components), s-controls, and Visualforce pagesCustom tab
Folders, reports (including all of its components), s-controls, and Visualforce pagesDashboard
FolderDocument
Folder, letterhead, custom fields, and documents (stored as images on the letterhead or
template)
Email template
Any referenced fieldsField set
Any associated actionsLightning Page
Lightning PageLightning Page tab
Custom objects, custom fields, Apex classes, and Visualforce pagesFlow
Everything in the folderFolder
All Lightning resources referenced by the application, such as components, events, and
interfaces. Custom fields, custom objects, list views, page layouts, and Apex classes referenced
by the application.
Lightning application
All Lightning resources referenced by the component, such as nested components, events,
and interfaces. Custom fields, custom objects, list views, page layouts, and Apex classes
referenced by the component.
Lightning component
Custom fields, custom objects, list views, and page layoutsLightning event
Custom fields, custom objects, list views, and page layoutsLightning interface
Actions, custom buttons, custom links, s-controls, and Visualforce pagesPage layout
Any custom permissions, external data sources, Visualforce pages, and Apex classes that are
assigned in the permission set
Permission set
Record type mappings, compact layoutRecord type
Folder, custom fields, custom objects, custom report types, and custom s-controlsReport
Custom fields and custom objectsS-control
Translated terms for the selected language on any component in the packageTranslation
Custom fields (referenced in the formula)Validation rule
36
Components Automatically Added to PackagesDesigning and Building Your App
These types of components might be automatically included:When you add this component:
Associated Visualforce pageVisualforce home page component
Apex classes that are used as custom controllers, Visualforce custom components, and
referenced field sets
Visualforce pages
All associated workflow alerts, field updates, outbound messages, and tasks; also, if the
workflow rule is designed for a custom object, the custom object is automatically included
Workflow rule
Note: Some package components, such as validation rules or record types, might not display in the list of package components,
but are included and install with the other components.
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).
Note:
•For more information on the properties of each component in packages, see the packaged components properties table.
•For more information on the attributes of each component in packages, see the component attributes table.
•Component names must be unique within an organization. To ensure that your component names don’t conflict with those
in an installer’s organization, use a managed package so that all your component names contain your namespace prefix.
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.
Tip: 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.
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.
37
Special Behavior of Components in PackagesDesigning and Building Your App
•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, 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 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.
38
Special Behavior of Components in PackagesDesigning and Building Your App
•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 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.
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 org. 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 org
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
39
Special Behavior of Components in PackagesDesigning and Building Your App
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 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,
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 org 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 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
Field sets in installed packages perform different merge behaviors during a package upgrade:
Then in the package upgrade:If a package developer:
The modified field is placed at the end of the upgraded field set
in whichever column it was added to.
Changes a field from Unavailable to Available for the
Field Set or In the Field Set
The new field is placed at the end of the upgraded field set in
whichever column it was added to.
Adds a new field
The field is removed from the upgraded field set.Changes a field from Available for the Field Set or In the Field
Set to Unavailable
40
Special Behavior of Components in PackagesDesigning and Building Your App
Then in the package upgrade:If a package developer:
The change is not reflected in the upgraded field set.Changes a field from In the Field Set to Available for the Field
Set (or vice versa)
Note: 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.
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.
•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.
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.
41
Special Behavior of Components in PackagesDesigning and Building Your App
•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 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.
42
Special Behavior of Components in PackagesDesigning and Building Your App
•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 org, the admin for that org 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
Note: Assigned apps and standard tab visibility settings aren’t included in permission set components.
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
43
Special Behavior of Components in PackagesDesigning and Building Your App
•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.
Reporting Snapshots
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.
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.
44
Special Behavior of Components in PackagesDesigning and Building Your App
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.
Wave Analytics
Wave Analytics components include Wave apps, dashboards, dataflows, datasets, lenses, and master user XMD. As you package
Wave components, keep these tips and best practices in mind.
•Wave unmanaged packages, as opposed to managed packages, are considered a developer-only feature and are not supported
for general-purpose distribution. While Wave unmanaged packages should work as expected within the constraints of Salesforce
unmanaged packages, they have not been 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.
•Wave 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.
•Before the Spring '17 release, images would not render when deploying a dashboard that used an image widget that referenced
image files not available on the target org. There were two workarounds; to either 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. Consequently, you will be unable to delete a dashboard if it is referenced in a link. In such
cases, either re-create the image or link widgets in the dashboard in the source org, and then re-package, 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, it's now Type = text). Comments in JSON are removed. Nodes may appear in a
different order.
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.
45
Special Behavior of Components in PackagesDesigning and Building Your App
•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
the Flows action in Process Builder instead.
•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.
Protected Components
Developers can mark certain components as protected. Protected components can’t be linked to or referenced by components created
in a subscriber org. A developer can delete a protected component in a future release without worrying about failing installations.
However, once a component is marked as unprotected and is released globally, the developer can’t delete it.
The developer can mark the following components as protected in managed packages.
•Custom labels
•Custom links (for Home page only)
•Workflow alerts
•Workflow field updates
•Workflow outbound messages
•Workflow tasks
•Workflow flow triggers
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 the Flows action in Process Builder instead.
46
Protected ComponentsDesigning and Building Your App
Understanding Dependencies
EDITIONS
Available in: Salesforce
Classic
AppExchange packages
and Visualforce are
available in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Apex available in:
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To upload packages:
•“Upload AppExchange
Packages”
To view Apex dependencies:
•“Author Apex”
To view Visualforce
dependencies:
•“Developer Mode”
Package dependencies are created when one component references another component,
permission, or preference that is required for the component to be valid. Force.com tracks certain
dependencies, including:
•Organizational dependencies, such as whether multicurrency or campaigns are enabled
•Component-specific dependencies, such as whether particular record types or divisions exist
•References to both standard and custom objects or fields
Packages, Apex classes, Apex triggers, Visualforce components, and Visualforce pages can have
dependencies on components within an organization. These dependencies are recorded on the
Show Dependencies page.
Dependencies are important for packaging because any dependency in a component of a package
is considered a dependency of the package as a whole.
Note: An installer’s organization must meet all dependency requirements listed on the Show
Dependencies page or else the installation will fail. For example, the installer's organization
must have divisions enabled to install a package that references divisions.
Dependencies are important for Apex classes or triggers because any component on which a class
or trigger depends must be included with the class or trigger when the code is deployed or packaged.
In addition to dependencies, the operational scope is also displayed on the Show Dependencies
page. The operational scope is a table that lists any data manipulation language (DML) operations
(such as insert or merge) that Apex executes on a specified object. The operational scope
can be used when installing an application to determine the full extent of the application’s database
operations.
To view the dependencies and operational scope for a package, Apex class, Apex trigger, or
Visualforce page:
1. Navigate to the appropriate component from Setup:
•For packages, enter Packages in the Quick Find box, then select Packages.
•For Apex classes, enter Apex Classes in the Quick Find box, then select Apex Classes.
•For Apex triggers, from the management settings for the appropriate object, go to Triggers.
•For Visualforce pages, enter Visualforce Pages in the Quick Find box, then select Visualforce Pages.
2. Select the name of the component.
3. Click View Dependencies for a package, or Show Dependencies for all other components, to see a list of objects that depend
upon the selected component.
If a list of dependent objects displays, click Fields to access the field-level detail of the operational scope. The field-level detail includes
information, such as whether a field is updated by Apex. For more information, see Field Operational Scope.
Packages, Apex code, and Visualforce pages can be dependent on many components, including but not limited to:
•Custom field definitions
•Validation formulas
•Reports
•Record types
•Apex
•Visualforce pages and components
47
Understanding DependenciesDesigning and Building Your App
For example, if a Visualforce page includes a reference to a multicurrency field, such as {!contract.ISO_code}, that Visualforce
page has a dependency on multicurrency. If a package contains this Visualforce page, it also has a dependency on multicurrency. Any
organization that wants to install this package must have multicurrency enabled.
About Permission Sets and Profile Settings
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.
Profile SettingsPermission SetsBehavior
What permissions and settings are included? •Assigned apps
•Custom object permissions
•External object permissions •Assigned connected apps
•Tab settings
•Custom field permissions
•Custom permissions •Page layout assignments
•Record type assignments
•Custom tab visibility settings
•Apex class access •Custom object permissions
•External object permissions
•Visualforce page access
•External data source access •Custom field permissions
•Custom permissions
Note: Although permission sets
include assigned apps and standard •Apex class access
tab visibility settings, these settings •Visualforce page access
can’t be packaged as permission set
components. •External data source access
Profile settings are applied to existing
profiles in the subscriber's organization on
Yes.Can they be upgraded in managed
packages?
install or upgrade. Only permissions related
to new components created as part of the
install or upgrade are applied.
Yes.Subscribers can edit permission sets in
unmanaged packages, but not in managed
packages.
Can subscribers edit them?
Yes. Subscribers can clone any profile that
includes permissions and settings related
to packaged components.
Yes. However, if a subscriber clones a
permission set or creates one that's based
on a packaged permission set, it won't be
updated in subsequent upgrades. Only the
Can you clone or create them?
permission sets included in a package are
upgraded.
No.No. Also, you can’t include object
permissions for a custom object in a
Do they include standard object
permissions?
master-detail relationship where the master
is a standard object.
No.No.Do they include user permissions?
48
About Permission Sets and Profile SettingsDesigning and Building Your App
Profile SettingsPermission SetsBehavior
Yes. Profile settings are applied to existing
profiles in the subscriber's organization on
No. Subscribers must assign permission sets
after installation.
Are they included in the installation wizard?
install or upgrade. Only permissions related
to new components created as part of the
install or upgrade are applied.
None. In a subscriber organization, the
installation overrides the profile settings,
not their user licenses.
A permission set is only installed if the
subscriber organization has at least one user
license that matches the permission set. For
example, permission sets with the Salesforce
What are the user license requirements?
Platform user license aren't installed in an
organization that has no Salesforce Platform
user licenses. If a subscriber subsequently
acquires a license, they must reinstall the
package to get the permission sets
associated with the newly acquired license.
Permission sets with no user license are
always installed. If you assign a permission
set with no user license, all of its enabled
settings and permissions must be allowed
by the user’s license, or the assignment will
fail.
Profile settings are applied to existing
profiles.
Subscribers must assign packaged
permission sets after installing the package.
How are they assigned to users?
Best Practices
•Use permission sets in addition to packaged profiles so your subscribers can easily add new permissions for existing app users.
•If users need access to apps, standard tabs, page layouts, and record types, don't use permission sets as the sole permission-granting
model for your app.
•Create packaged permission sets that grant access to the custom components in a package, but not standard Salesforce components.
Custom Profile Settings
When building your AppExchange app, create profiles to define how users access objects and data, and what they can do within your
app. For example, profiles specify custom object permissions and the tab visibility for your app. When installing or upgrading your app,
admins can associate your custom profiles with existing non-standard profiles. Permissions in your custom profile that are related to
new components created as part of the install or upgrade are added to the existing profile. The security settings associated with standard
objects and existing custom objects in an installer’s organization are unaffected.
Consider these tips when creating custom profiles for apps you want to publish.
•Give each custom profile a name that identifies the profile as belonging to the app. For example, if you’re creating a Human Resources
app named “HR2GO,” a good profile name would be “HR2GO Approving Manager.”
•If your custom profiles have a hierarchy, use a name that indicates the profile’s location in the hierarchy. For example, name a
senior-level manager’s profile “HR2GO Level 2 Approving Manager.”
49
Custom Profile SettingsDesigning and Building Your App
•Avoid custom profile names that can be interpreted differently in other organizations. For example, the profile name “HR2GO Level
2 Approving Manager” is open to less interpretation than “Sr. Manager.”
•Provide a meaningful description for each profile. The description displays to the user installing your app.
Alternatively, you can use permission sets to maintain control of permission settings through the upgrade process. Permission sets
contain a subset of profile access settings, including object permissions, field permissions, Apex class access, and Visualforce page access.
These permissions are the same as those available on profiles. You can add a permission set as a component in a package.
Note: In packages, assigned apps and tab settings aren’t included in permission set components.
Protecting Your Intellectual Property
The details of your custom objects, custom links, reports, and other installed items are revealed to installers so that they can check for
malicious content. However, revealing an app’s components prevents developers from protecting some intellectual property.
The following information is important when considering your intellectual property and its protection.
•Only publish package components that are your intellectual property and that you have the rights to share.
•After your components are available on AppExchange, you cannot recall them from anyone who has installed them.
•The information in the components that you package and publish might be visible to customers. Use caution when adding your
code to a formula, Visualforce page, or other component that you cannot hide in your app.
•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.
•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 org. All data for the custom setting is hidden from the
subscriber.
Creating Packaged Applications with Chatter
The objects, field settings, and field settings history of Chatter are packageable. However, an object's field is only tracked if the object
itself is tracked. For example, you can create a new custom field on the Account standard object, but the field will only be tracked if you
have enabled feed tracking on Accounts.
When developing applications that use Chatter, it's important to be aware that some organizations might not have Chatter enabled. By
default, when you upload Chatter applications, the package is only available to organizations that have Chatter enabled. You can change
this behavior and allow organizations to install the package even if they don't have Chatter. Note the following:
•You must use a managed package. Unmanaged packages that include Chatter functionality can only be installed in organizations
that have Chatter enabled.
•DML operations and SOSL, and SOQL calls will throw a runtime exception if the subscriber organization does not have Chatter
enabled. You must catch and handle any Apex exceptions that are thrown as a result of the missing Chatter feature. These exceptions
are of the type REQUIRED_FEATURE_MISSING_EXCEPTION for SOSL and SOQL calls. For DML calls, you must check for
the specific REQUIRED_FEATURE_MISSING status code on a DML Exception.
•When you upload the package, deselect the Chatter required checkbox (this is automatically selected if you have an Apex reference
to Chatter).
Note: If the Chatter required checkbox can't be deselected, then some component in the package has a special requirement
for Chatter. This can happen, for example, if you package a custom report type that relies on Chatter. If the Chatter-required
checkbox can't be disabled, then the package can only be installed in organizations that have Chatter enabled.
50
Protecting Your Intellectual PropertyDesigning and Building Your App
The following example tries to post to feeds and get a user's feed. If Chatter is not enabled in the organization, the code catches the
REQUIRED_FEATURE_MISSING exception. Note that this is an incomplete code example and does not run.
public void addFeedItem(String post, Id objId) {
FeedItem fpost = new FeedItem();
// Get the parent ID of the feed
fpost.ParentId = objId;
fpost.Body = post;
try{
insert fpost;
} catch (System.DmlException e) {
for (Integer i = 0; i < e.getNumDml(); i++) {
// Chatter not endabled, do not insert record
System.assertEquals(StatusCode.REQUIRED_FEATURE_MISSING, e.getDmlType(i));
System.Debug('Chatter not enabled in this organization:' + e.getDMLMessage());
}
}
}
public List<NewsFeed> getMyFeed() {
List<NewsFeed> myfeed;
try{
myfeed = [SELECT Id, Type, CreatedById, CreatedBy.FirstName,CreatedBy.LastName,
CreatedDate, ParentId, Parent.Name,FeedItemId, Body,
Title, CreatedById, LinkUrl,
(SELECT Id, FieldName, OldValue, NewValue
FROM FeedTrackedChanges ORDER BY Id DESC),
(SELECT Id, CommentBody, CreatedDate, CreatedById,
CreatedBy.FirstName, CreatedBy.LastName
FROM FeedComments ORDER BY CreatedDate DESC, ID DESC LIMIT 10)
FROM NewsFeed
ORDER BY CreatedDate DESC, ID DESC LIMIT 20];
} catch(System.RequiredFeatureMissingException e){
// The above has returned an empty NewsFeed
// Chatter is not enabled in this organization
myfeed = new List<NewsFeed>{};
System.Debug('Chatter not enabled in organization:' + e.getMessage());
}
return myfeed;
}
Matching the Salesforce Look and Feel
Apps that resemble the Salesforce user interface look and feel are instantly more familiar to users and easy to use. The easiest way to
model the design of your app after the Salesforce user interface look and feel is to use Visualforce. When you use a standard controller
with a Visualforce page, your new page takes on the style of the associated object’s standard tab in Salesforce. For more information,
see Using Salesforce Styles in the Visualforce Developer's Guide.
51
Matching the Salesforce Look and FeelDesigning and Building Your App
Developing App Documentation
EDITIONS
Available in: Salesforce
Classic
Available in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Salesforce recommends publishing your app on AppExchange with the following types of
documentation:
Configure Option
You can include a Configure option for installers. This option can link to installation and
configuration details, such as:
•Provisioning the external service of a composite app
•Custom app settings
The Configure option is included in your package as a custom link. You can create a custom
link for your home page layouts and add it to your package.
1. Create a custom link to a URL that contains configuration information or a Visualforce page that implements configuration. When
you create your custom link, set the display properties to Open in separate popup window so that the user returns
to the same Salesforce page when done.
2. When you create the package, choose this custom link in the Configure Custom Link field of your package detail.
Data Sheet
Give installers the fundamental information they need to know about your app before they install.
Customization and Enhancement Guide
Let installers know what they must customize after installation as part of their implementation.
Custom Help
You can provide custom help for your custom object records and custom fields.
Tip: To give your custom help a professional tone using Salesforce terminology, follow the Salesforce Style Guide for
Documentation and User Interface Text.
About API and Dynamic Apex Access in Packages
EDITIONS
Available in: Salesforce
Classic
Available in: Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
ApexPackage components have access via dynamic Apex and the API to standard and custom
objects in the organization where they are installed. Developers of Force.com AppExchange packages
that are intended for external customers (also called third-party developers or partners) may wish
to restrict this access. Restricting access makes packages safer for administrators to install. Also,
administrators who install such packages may wish to restrict this access after installation, even if
the package developers have not, for improved security.
API Access is a package setting that controls the dynamic Apex and API access that s-controls
and other package components have to standard and custom objects. The setting displays for both
the developer and installer on the package detail page. With this setting:
•The developer of an AppExchange package can restrict API access for a package before uploading
it to Force.com AppExchange. Once restricted, the package components receive Apex and API
sessions that are restricted to the custom objects in the package. The developer can also enable access to specific standard objects,
and any custom objects in other packages that this package depends on.
•The installer of a package can accept or reject package access privileges when installing the package to his or her organization.
•After installation, an administrator can change Apex and API access for a package at any time. The installer can also enable access
on additional objects such as custom objects created in the installer’s organization or objects installed by unrelated packages.
There are two possible options for the API Access setting:
52
Developing App DocumentationDesigning and Building Your App
•The default Unrestricted, which gives the package components the same API access to standard objects as the user who is
logged in when the component sends a request to the API. Apex runs in system mode. Unrestricted access gives Apex read access
to all standard and custom objects.
•Restricted, which allows the administrator to select which standard objects the components in the package can access. Further,
the components in restricted packages can only access custom objects in the current package if the user has the object permissions
that provide access to them.
Considerations for API and Dynamic Apex Access in Packages
By default, dynamic Apex can only access the components with which the code is packaged. To provide access to standard objects not
included in the package, the developer must set the API Access.
1. From Setup, enter Packages in the Quick Find box, then select Packages.
2. Select the package that contains a dynamic Apex that needs access to standard objects in the installing organization.
3. In the Package Detail related list, click Enable Restrictions or Restricted, whichever is available.
4. Set the access level (Read, Create, Edit, Delete) for the standard objects that the dynamic Apex can access.
5. Click Save.
Choosing Restricted for the API Access setting in a package affects the following:
•API access in a package overrides the following user permissions:
–Author Apex
–Customize Application
–Edit HTML Templates
–Edit Read Only Fields
–Manage Billing
–Manage Call Centers
–Manage Categories
–Manage Custom Report Types
–Manage Dashboards
–Manage Letterheads
–Manage Package Licenses
–Manage Public Documents
–Manage Public List Views
–Manage Public Reports
–Manage Public Templates
–Manage Users
–Transfer Record
–Use Team Reassignment Wizards
–View Setup and Configuration
–Weekly Export Data
•If Read, Create, Edit, and Delete access are not selected in the API access setting for objects, users do not have access to
those objects from the package components, even if the user has the “Modify All Data” and “View All Data” permissions.
•A package with Restricted API access can’t create new users.
53
About API and Dynamic Apex Access in PackagesDesigning and Building Your App
•Salesforce denies access to Web service and executeanonymous requests from an AppExchange package that has
Restricted access.
The following considerations also apply to API access in packages:
•Workflow rules and Apex triggers fire regardless of API access in a package.
•If a component is in more than one package in an organization, API access is unrestricted for that component in all packages in the
organization regardless of the access setting.
•If Salesforce introduces a new standard object after you select restricted access for a package, access to the new standard object is
not granted by default. You must modify the restricted access setting to include the new standard object.
•When you upgrade a package, changes to the API access are ignored even if the developer specified them. This ensures that the
administrator installing the upgrade has full control. Installers should carefully examine the changes in package access in each
upgrade during installation and note all acceptable changes. Then, because those changes are ignored, the administrator should
manually apply any acceptable changes after installing an upgrade.
•S-controls are served by Salesforce and rendered inline in Salesforce. Because of this tight integration, there are several means by
which an s-control in an installed package could escalate its privileges to the user’s full privileges. In order to protect the security of
organizations that install packages, s-controls have the following limitations:
–For packages you are developing (that is, not installed from AppExchange), you can only add s-controls to packages with the
default Unrestricted API access. Once a package has an s-control, you cannot enable Restricted API access.
–For packages you have installed, you can enable access restrictions even if the package contains s-controls. However, access
restrictions provide only limited protection for s-controls. Salesforce recommends that you understand the JavaScript in an
s-control before relying on access restriction for s-control security.
–If an installed package has Restricted API access, upgrades will be successful only if the upgraded version does not contain
any s-controls. If s-controls are present in the upgraded version, you must change the currently installed package to
Unrestricted API access.
54
About API and Dynamic Apex Access in PackagesDesigning and Building Your App
Manage API and Dynamic Apex Access in Packages
EDITIONS
Available in: Salesforce
Classic
Available in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
USER PERMISSIONS
To edit API and dynamic
Apex access for a package
you have created or
installed:
•“Create AppExchange
packages”
To accept or reject package
API and dynamic Apex
access for a package as
part of installation:
•“Download
AppExchange
packages”
API Access is a package setting that controls the dynamic Apex and API access that s-controls
and other package components have to standard and custom objects. The setting displays for both
the developer and installer on the package detail page. With this setting:
•The developer of an AppExchange package can restrict API access for a package before uploading
it to Force.com AppExchange. Once restricted, the package components receive Apex and API
sessions that are restricted to the custom objects in the package. The developer can also enable
access to specific standard objects, and any custom objects in other packages that this package
depends on.
•The installer of a package can accept or reject package access privileges when installing the
package to his or her organization.
•After installation, an administrator can change Apex and API access for a package at any time.
The installer can also enable access on additional objects such as custom objects created in the
installer’s organization or objects installed by unrelated packages.
Setting API and Dynamic Apex Access in Packages
To change package access privileges in a package you or someone in your organization has created:
1. From Setup, enter Packages in the Quick Find box, then select Packages.
2. Select a package.
3. The API Access field displays the current setting, Restricted or Unrestricted,
and a link to either Enable Restrictions or Disable Restrictions. If Read, Create, Edit,
and Delete access are not selected in the API access setting for objects, users do not have
access to those objects from the package components, even if the user has the “Modify All
Data” and “View All Data” permissions.
Use the API Access field to:
Enable Restrictions
This option is available only if the current setting is Unrestricted. Select this option if you want to specify the dynamic
Apex and API access that package components have to standard objects in the installer's organization. When you select this
option, the Extended Object Permissions list is displayed. Select the Read, Create, Edit, or Delete checkboxes to enable
access for each object in the list. This selection is disabled in some situations. Click Save when finished. For more information
about choosing the Restricted option, including information about when it is disabled, see Considerations for API and
Dynamic Apex Access in Packages on page 53.
Disable Restrictions
This option is available only if the current setting is Restricted. Select this option if you do not want to restrict the Apex
and API access privileges that the components in the package have to standard and custom objects. This option gives all the
components in the package the same API access as the user who is logged in. For example, if a user can access accounts, an
Apex class in the package that accesses accounts would succeed when triggered by that user.
Restricted
Click this link if you have already restricted API access and wish to edit the restrictions.
Accepting or Rejecting API and Dynamic Apex Access Privileges During Installation
To accept or reject the API and dynamic Apex access privileges for a package you are installing:
55
Manage API and Dynamic Apex Access in PackagesDesigning and Building Your App
•Start the installation process on Force.com AppExchange.
•In Approve API Access, either accept by clicking Next, or reject by clicking Cancel. Complete the installation steps if you have not
canceled.
Changing API and Dynamic Apex Access Privileges After Installation
To edit the package API and dynamic Apex access privileges after you have installed a package:
1. From Setup, enter Installed Packages in the Quick Find box, then select Installed Packages.
2. Click the name of the package you wish to edit.
3. The API Access field displays the current setting, Restricted or Unrestricted, and a link to either Enable Restrictions
or Disable Restrictions. If Read, Create, Edit, and Delete access are not selected in the API access setting for objects,
users do not have access to those objects from the package components, even if the user has the “Modify All Data” and “View All
Data” permissions.
Use the API Access field to:
Enable Restrictions
This option is available only if the current setting is Unrestricted. Select this option if you want to specify the dynamic
Apex and API access that package components have to standard objects in the installer's organization. When you select this
option, the Extended Object Permissions list is displayed. Select the Read, Create, Edit, or Delete checkboxes to enable
access for each object in the list. This selection is disabled in some situations. Click Save when finished. For more information
about choosing the Restricted option, including information about when it is disabled, see Considerations for API and
Dynamic Apex Access in Packages on page 53.
Disable Restrictions
This option is available only if the current setting is Restricted. Select this option if you do not want to restrict the Apex
and API access privileges that the components in the package have to standard and custom objects. This option gives all the
components in the package the same API access as the user who is logged in. For example, if a user can access accounts, an
Apex class in the package that accesses accounts would succeed when triggered by that user.
Restricted
Click this link if you have already restricted API access and wish to edit the restrictions.
Configuring Default Package Versions for API Calls
EDITIONS
Available in: Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited,
and Developer, Editions
USER PERMISSIONS
To configure default
package versions for API
calls:
•“Customize Application”
A package version is a number that identifies the set of components uploaded in a package. The
version number has the format majorNumber.minorNumber.patchNumber (for example,
2.1.3). 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. 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.
Default package versions for API calls provide fallback settings if package versions are not provided
by an API call. Many API clients do not include package version information, so the default settings
maintain existing behavior for these clients.
You can specify the default package versions for enterprise API and partner API calls. The enterprise
WSDL is for customers who want to build an integration with their Salesforce organization only. It
is strongly typed, which means that calls operate on objects and fields with specific data types,
such as int and string. The partner WSDL is for customers, partners, and ISVs who want to
build an integration that can work across multiple Salesforce organizations, regardless of their
56
Configuring Default Package Versions for API CallsDesigning and Building Your App
custom objects or fields. It is loosely typed, which means that calls operate on name-value pairs of field names and values instead of
specific data types.
You must associate the enterprise WSDL with specific package versions to maintain existing behavior for clients. There are options for
setting the package version bindings for an API call from client applications using either the enterprise or partner WSDL. The package
version information for API calls issued from a client application based on the enterprise WSDL is determined by the first match in the
following settings.
1. The PackageVersionHeader SOAP header.
2. The SOAP endpoint contains a URL with a format of serverName/services/Soap/c/api_version/ID where
api_version is the version of the API, such as 39.0, and ID encodes your package version selections when the enterprise WSDL
was generated.
3. The default enterprise package version settings.
The partner WSDL is more flexible as it is used for integration with multiple organizations. If you choose the Not Specified option for a
package version when configuring the default partner package versions, the behavior is defined by the latest installed package version.
This means that behavior of package components, such as an Apex trigger, could change when a package is upgraded and that change
would immediately impact the integration. Subscribers may want to select a specific version for an installed package for all partner API
calls from client applications to ensure that subsequent installations of package versions do not affect their existing integrations.
The package version information for partner API calls is determined by the first match in the following settings.
1. The PackageVersionHeader SOAP header.
2. An API call from a Visualforce page uses the package versions set for the Visualforce page.
3. The default partner package version settings.
To configure default package versions for API calls:
1. From Setup, enter API in the Quick Find box, then select API.
2. Click Configure Enterprise Package Version Settings or Configure Partner Package Version Settings. These links are only
available if you have at least one managed package installed in your organization.
3. Select a Package Version for each of your installed managed packages. If you are unsure which package version to select,
you should leave the default selection.
4. Click Save.
Note: Installing a new version of a package in your organization does not affect the current default settings.
About the Partner WSDL
The Partner Web Services WSDL is used for client applications that are metadata-driven and dynamic in nature. It is particularly—but
not exclusively—useful to Salesforce partners who are building client applications for multiple organizations. As a loosely typed
representation of the Salesforce data model that works with name-value pairs of field names and values instead of specific data types,
it can be used to access data within any organization. This WSDL is most appropriate for developers of clients that can issue a query call
to get information about an object before the client acts on the object. The partner WSDL document needs to be downloaded and
consumed only once per version of the API.
For more information about the Partner WSDL, see Using the Partner WSDL in the SOAP API Developer's Guide.
57
About the Partner WSDLDesigning and Building Your App
Generating an Enterprise WSDL with Managed Packages
EDITIONS
Available in: Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited,
and Developer, Editions
USER PERMISSIONS
To download a WSDL:
•“Customize Application”
If you are downloading an enterprise WSDL and you have managed packages installed in your
organization, you need to take an extra step to select the version of each installed package to include
in the generated WSDL. The enterprise WSDL is strongly typed, which means that it contains objects
and fields with specific data types, such as int and string.
A package version is a number that identifies the set of components uploaded in a package. The
version number has the format majorNumber.minorNumber.patchNumber (for example,
2.1.3). 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. 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. A subscriber
can select a package version for each installed managed package to allow their API client to continue
to function with specific, known behavior even when they install subsequent versions of a package.
Each package version can have variations in the composition of its objects and fields, so you must
select a specific version when you generate the strongly typed WSDL.
To download an enterprise WSDL when you have managed packages installed:
1. From Setup, enter API in the Quick Find box, then select API.
2. Click Generate Enterprise WSDL.
3. Select the Package Version for each of your installed managed packages. If you are unsure which package version to select,
you should leave the default, which is the latest package version.
4. Click Generate.
5. Use the File menu in your browser to save the WSDL to your computer.
6. On your computer, import the local copy of the WSDL document into your development environment.
Note the following in your generated enterprise WSDL:
•Each of your managed package version selections is included in a comment at the top of the WSDL.
•The generated WSDL contains the objects and fields in your organization, including those available in the selected versions of each
installed package. If a field or object is added in a later package version, you must generate the enterprise WSDL with that package
version to work with the object or field in your API integration.
•The SOAP endpoint at the end of the WSDL contains a URL with a format of
serverName/services/Soap/c/api_version/ID where api_version is the version of the API, such as 39.0,
and ID encodes your package version selections when you communicate with Salesforce.
You can also select the default package versions for the enterprise WSDL without downloading a WSDL from the API page in Setup.
Default package versions for API calls provide fallback settings if package versions are not provided by an API call. Many API clients do
not include package version information, so the default settings maintain existing behavior for these clients.
Working with External Services
You might want to update your Salesforce data when changes occur in another service. Likewise, you might also want to update the
data in another service (outside of Salesforce) based on changes to your Salesforce data. Salesforce provides ways of doing both of these
transactions. For example, you might want to send a mass email to more contacts and leads than Salesforce allows. To do so, you can
use an external mail service that allows users to build a recipient list of names and email addresses using the contact and lead information
in your Salesforce organization.
An app built on the Force.com platform can connect with an external service in many different ways. For example:
58
Generating an Enterprise WSDL with Managed PackagesDesigning and Building Your App
•You can create a custom link or custom formula field that passes information to an external service.
•You can use the Force.com API to transfer data in and out of Salesforce.
•You can use an Apex class that contains a Web service method.
Before any Visualforce page, Apex callout, or JavaScript code using XmlHttpRequest in an s-control or custom button can call an external
site, that site must be registered in the Remote Site Settings page, or the call fails. For information on registering components, see
Configure Remote Site Settings.
Warning: Do not store usernames and passwords within any external service.
Provisioning External Services
If your app links to an external service, users who install the app must be signed up to use the service. Provide access in one of two ways:
•Access by all active users in an organization with no real need to identify an individual
•Access on a per user basis where identification of the individual is important
The Salesforce service provides two globally unique IDs to support these options. The user ID identifies an individual and is unique across
all organizations. User IDs are never reused. Likewise, the organization ID uniquely identifies the organization.
Avoid using email addresses, company names, and Salesforce usernames when providing access to an external service. Usernames can
change over time and email addresses and company names can be duplicated.
If you are providing access to an external service, we recommend the following:
•Use Single Sign-On (SSO) techniques to identify new users when they use your service.
•For each point of entry to your app, such as a custom link or web tab, include the user ID in the parameter string. Have your service
examine the user ID to verify that the user ID belongs to a known user. Include a session ID in the parameter string so that your
service can read back through the Force.com API and validate that this user has an active session and is authenticated.
•Offer the external service for any known users. For new users, display an alternative page to collect the required information.
•Do not store passwords for individual users. Besides the obvious security risks, many organizations reset passwords on a regular
basis, which requires the user to update the password on your system as well. We recommend designing your external service to
use the user ID and session ID to authenticate and identify users.
•If your application requires asynchronous updates after a user session has expired, dedicate a distinct administrator user license for
this.
Architectural Considerations for Group and Professional Editions
Salesforce CRM is offered in five tiers, or editions:
•Group Edition (GE)*
•Professional Edition (PE)
•Enterprise Edition (EE)
•Unlimited Edition (UE)
•Performance Edition (PXE)*
Note: Group and Performance Editions are no longer sold. For a comparison chart of editions and their features, see the Salesforce
Pricing and Editions page.
If you plan to sell your app to existing Salesforce customers, it’s important to understand the differences between these editions because
they will affect the design of your app. It’s convenient to think about them in clusters, GE/PE and EE/UE/PXE, as the editions in each
59
Architectural Considerations for Group and Professional
Editions
Designing and Building Your App
cluster have similar functionality. For example, you might only want to support EE/UE/PXE if your app requires certain objects and features
that aren't available in GE/PE. Also, instead of a single solution that supports all editions, you can have a tiered offering. This would consist
of a basic solution for GE/PE and an advanced one for EE/UE/PXE customers that takes advantage of the additional features.
EE/UE/PXE have the most robust functionality. They support Force.com platform licenses in addition to Salesforce CRM licenses. If your
app doesn’t require Salesforce CRM features (such as Leads, Opportunities, Cases, etc.), Force.com platform licenses provide you with
the most flexibility in deploying your app to users who might not normally be Salesforce users. Your app is still subject to the edition
limits and packaging rules.
GE/PE don't contain all of the functionality that you can build in a Developer Edition (DE). Therefore, an application developed in your
DE organization might not install in a GE/PE organization. If you’re designing an application to work specifically in GE/PE, you must be
aware of how these editions differ.
There are a number of other considerations to keep in mind when deciding whether to support these editions. Force.com platform
licenses cannot be provisioned in GE/PE organizations. This means that only existing Salesforce CRM users can use your app. There are
some features that aren't available in GE/PE. There are several special permissions available to eligible partner apps that overcome these
limitations.
See the following sections for available features, limits, and other design considerations.
•Features in Group and Professional Editions
•Limits for Group and Professional Editions
•Access Control in Group and Professional Editions
•Using Apex in Group and Professional Editions
•API Access in Group and Professional Editions
•Designing Your App to Support Multiple Editions
•Sample Design Scenarios
Features in Group and Professional Editions
The easiest way to determine which features and objects are available in a particular edition is by reviewing the Edition Comparison
Table. You can also look up which editions support a specific feature or object by searching the online help. It’s important that you check
these resources before you start designing your app to make an informed decision on which editions to target. When you’re finished
building your app, we recommend that you test it by installing your package in GE and PE test orgs to ensure that everything functions
properly.
The following table shows the key differences between GE and PE.
Professional EditionGroup EditionFeature
YesNoAssets
YesNoCampaigns
Yes (with the Sales Cloud)NoContracts
Yes (no Opportunity Splits or Custom
Field forecasts)
NoForecasts
YesNoIdeas
YesNoProducts
YesNoSolutions
60
Features in Group and Professional EditionsDesigning and Building Your App
Professional EditionGroup EditionFeature
YesNoRecord types
YesYesPermission sets
YesNoCustom profiles
YesNoCustom report types
No (See note.)NoWorkflow and approvals
See note.See note.Apex code
Yes (for some features)NoSharing rules
See note.See note.API
NoNoSites
Note:
•All listed features are available in DE.
•As a partner, workflows within your application run in a Professional Edition org. However, customers can’t create their own
workflows. They must purchase the feature directly from Salesforce.
•A client ID allows your app to use the API for integration to composite apps. For more information, see Using Apex in Group
and Professional Editions and API Access in Group and Professional Editions.
Limits for Group and Professional Editions
All Salesforce editions have limits that restrict the number of apps, objects, and tabs that can be used. For details on the limits for various
editions, see the Edition Limits Table.
For partners who are enrolled in the ISV Program, any managed package publicly posted on the AppExchange no longer counts against
the apps/objects/tabs limits for your Salesforce Edition. This effectively means that ISV partners no longer have to worry about package
installation failures because of apps/objects/tabs limits being exceeded. This feature is automatically enabled after your app passes the
security review.
Access Control in Group and Professional Editions
Group Edition doesn’t support field-level security or custom profiles. You can manage field-level security by using the page layout for
each object instead. When customers install your app, they can’t define which profiles have access to what. Ensure that your design
works for the Standard User Profile. Permission sets can be installed but not updated in GE and PE orgs.
Because field level security is handled by the page layout, any fields you want to be visible must be added to the page layout. This means
that for fields to be accessible via the API or Visualforce, they must be added to the page layout.
Using Apex in Group and Professional Editions
Your app can contain business logic such as classes, triggers, email services, etc. written in Apex. As a general rule, Apex is not supported
in GE/PE, so it will not run in these editions. However, Apex developed as part of an ISV app and included in a managed package can
run in GE/PE, even though those editions do not support Apex by default.
61
Limits for Group and Professional EditionsDesigning and Building Your App
You must be an eligible partner with salesforce.com and your app has to pass the security review. The appropriate permissions will
automatically be enabled after you pass the security review.
Here are some important considerations for using Apex in GE/PE.
•GE/PE customers can’t create or modify Apex in your app; they can only run the existing Apex.
•Your Apex code should not depend on features and functionality that exist only in DE, EE, UE, or PXE, or your app will fail to install.
•Make sure to use REST if you plan to expose an Apex method as a Web service. Apex classes that have been exposed as a SOAP Web
service can’t be invoked from an external web app in GE/PE.
•Using Apex to make Web service callouts is allowed in GE/PE. For instance, if you’re planning to make a Web service callout to an
external Web service, as long as the managed package is authorized, these classes will function in GE/PE.
API Access in Group and Professional Editions
API access is not normally supported in GE and PE orgs. However, after your app passes the security review, you’re eligible to use some
APIs for building composite applications.
•Currently, the standard Data SOAP and REST APIs are supported for GE and PE apps, and Metadata API is supported in PE apps. To
request API access, see How do I get an API token for my app? You can also contact Salesforce to request that a connected app be
whitelisted to use the REST API in GE or PE orgs.
•Other APIs, such as the Bulk API and Apex methods exposed as SOAP Web services, remain unavailable.
•You can enable REST-based Web services using connected app consumer whitelisting.
•You can enable SOAP-based Web services, including Metadata API, using an API token called a Client ID, which is appended to your
SOAP headers in integration calls. This special key enables your app to make calls to GE and PE orgs for Data API and PE orgs for
Metadata API, even if the customer does not have API access.
The Client ID has these properties.
•You can't use the Client ID with the AJAX Toolkit in custom JavaScript, S-controls, or anywhere in your app where its value would
be exposed to the end customer.
•For development purposes, GE and PE orgs created via the Environment Hub already have the Metadata API and SOAP API (Data
API) enabled. You can then develop and test your app before the security review. After your app passes the security review and you
obtain an API token, test your app again to ensure that it’s working correctly.
•The Client ID grants GE and PE access to the SOAP API, and PE access to the Metadata API. With the Metadata API, you can dynamically
create various components that you typically create in Setup. For instance, you can create a custom field dynamically in a PE
organization with the API token.
This table shows which APIs are accessible when using GE and PE and the method of access.
Access to GE and PEAPI
Yes, with tokenWeb Services (SOAP)
NoApex methods exposed as Web services (SOAP)
Yes, with connected app consumer whitelistingWeb services (REST)
Yes, with connected app consumer whitelistingApex methods exposed as Web services (REST)
YesChatter REST API
Yes, with tokenMetadata API
NoBulk API
62
API Access in Group and Professional EditionsDesigning and Building Your App
Access to GE and PEAPI
No, can’t set the token
Data Loader tool (uses SOAP Web services)
Accessing the REST API in Group and Professional Editions
The Force.com REST API provides you a powerful, convenient, and simple Web services API for interacting with Force.com. Qualified
partners can request salesforce.com to enable your application for REST API calls to GE/PE organizations. To get access to the REST API,
you must meet these conditions.
•Access to the Partner Community – If you’re new, please learn about and join one of the ISV Partner Programs.
•Pass the security review – All applications enrolled in the AppExchange and/or OEM Program must go through a periodic security
review.
•Access to Salesforce Developer Edition – If you don’t already have access to a DE organization, you can get the Partner Developer
Edition from the Environment Hub.
To request the REST API token:
1. Create a new connected app from your DE organization. Log in to salesforce.com with your developer account. From Setup, enter
Apps in the Quick Find box, then select Apps, and click New in the Connected Apps section.
Note: We strongly recommend that you do this in an organization you will continue using for a long time, such as the one
where you build your managed package or your Trialforce management organization (TMO).
2. Enter the information requested and click Save. Saving your app gives you the Consumer Key and Consumer Secret the app uses
to communicate with Salesforce.
3. Submit a case from the Partner Community and provide your DE Org ID and the credentials for your connected app.
We’ll evaluate your request and enable the appropriate permission. Once this is done, you’ll receive a case notification from us. Please
wait 24 hours to make sure the permission is completely activated. Your client_id (or Consumer Key) and client_secret (or Consumer
Secret) will be checked against the information you submit via the case during the OAuth authentication. If it matches, the system will
allow you to communicate with GE/PE.
Note:
•This permission is intended solely for REST API. It does not enable your application to use SOAP Web Services API, Bulk API,
Metadata API, etc. for GE/PE.
•This permission is applied only to your application. We do not turn on the API in the GE/PE organization.
Designing Your App to Support Multiple Editions
Supporting multiple editions provides the opportunity to release richer versions of your app that can support more advanced features
found in EE, UE, and PXE. There are two technologies that can be leveraged to support multiple editions. The first approach uses extension
packages and the second leverages Dynamic Apex. There are benefits to both, so be sure to review both strategies before designing
your app.
Supporting Multiple Editions Using an Extension Package
This approach uses a base managed package that contains core app functionality. The base package only contains features supported
in GE/PE. You then use a second managed package, or extension package, that extends and enhances the base package. The extension
63
Designing Your App to Support Multiple EditionsDesigning and Building Your App
package adds additional features supported in EE/UE/PXE. For example, you have a warehouse application that tracks inventory and an
extension to this app includes workflow (which isn't available in Group). Your Group and Professional Edition customers can install the
base warehouse application, while your other customers install the base package and then the extension package with workflow
components.
Using a base and extension package to support multiple editions
Using extension packages enables you to avoid multiple code sets and to upsell your customers. Upgrading a customer only requires
installing the extension package.
Here is the process for creating an extension package.
1. Create your base managed package that leverages features supported by GE/PE.
2. Install your base managed package in a separate DE org.
3. In this org create your extension package that includes additional functionality supported in GE/PE. You can reference the base
managed package to avoid duplicating functionality. Any component that references the base managed package will automatically
trigger this package to be an extension package.
Since your extension package depends on your base package, it’s important to spend time designing your app and the interfaces between
the packages. For example, if the extension package needs to call an Apex class in the base package, you must make sure the desired
Apex class is made global.
It’s also important to consider the entire application lifecycle. For example, If you want to add new features, they should be included in
the appropriate package. Updates to the base package should not break the extension package.
Note: To access history information for custom objects in your extension package, work with the base package owner to enable
history tracking in the org for the base package. Enabling history tracking in a base package can result in an error when you install
the package and when you create patch orgs for the extension package.
64
Designing Your App to Support Multiple EditionsDesigning and Building Your App
Supporting Multiple Editions using Dynamic Apex
Using dynamic Apex, dynamic SOQL, and dynamic DML, it’s possible to create one managed package for all editions you plan to support
without having to use extension packages. Your app behavior can change dynamically based on the features available in your customer's
edition. This is useful when designing an app with the intent to support multiple editions.
Make sure that Apex, workflows, etc. in your package do not contain any strongly-typed reference to a feature that isn't supported by
GE/PE. This can include adding a custom field on an unsupported standard object, such as Campaigns, or making an Apex reference to
features like multi-currency or territory management. When you reference a feature in your package not supported by GE/PE, this package
dependency will cause the installation to fail.
Instead, if you use dynamic Apex to first check if these features are available before referencing them, you can install your managed
package in GE/PE. The important piece to consider is you must code your Dynamic Apex in a way that can support both use cases. This
ensures that if your customer doesn’t have a specific feature or object, your app will still function.
Sample Design Scenarios for Group and Professional Editions
Here are some scenarios to help you understand when and how to build for Group and Professional Editions.
Scenario 1: You want to build an app that uses record types
Since record types aren’t available in Group Edition, decide if you want to support this edition. Assuming you do, you can build a
base managed package that doesn’t include record types. After uploading this managed package in a released state, you can install
it into another Developer Edition org to start building the extension. Your extension can add record types that your Professional,
Enterprise, Unlimited, and Performance Edition customers can install and use.
Scenario 2: You want to build an app with 80 custom objects
Typically this scenario presents a problem for Group and Professional Edition orgs because of their custom objects limit. However,
if you make your app available on the AppExchange, it doesn’t count toward custom objects, tabs, and apps limits. So even if your
app has 80 custom objects, it installs and works in Group and Professional Edition orgs.
Scenario 3: You want to build an app that makes Apex callouts to a web service
Apex doesn’t usually run in Group and Professional Editions, but if you get your managed package authorized during the security
review, your Apex executes as expected. So for this scenario, you build your Apex callout to invoke your external service and then
include this class in your package.
Scenario 4: You want to build an app that leverages Campaigns
Campaigns are supported by default in Group Edition. For this scenario, you have two options.
•Option 1 - Build a base managed package that doesn’t reference Campaigns. en it’s complete, upload and install it into another
Developer Edition org. Build the Campaign functionality as an extension package. Now your Group Edition customers can install
the base, while the rest can also install the extension to get extra features.
•Option 2 - This option requires only one package if you use Dynamic Apex as the only reference to Campaigns (as described
earlier) and do not include a custom field on the Campaign. Your app can then be installed in Group Edition orgs and higher. If
Campaigns is in your customer’s edition, then your Dynamic Apex can manipulate Campaigns as expected.
Scenario 5: You want to build a composite app where your receive inbound API calls
You have a separate hosted app that you want to integrate with Salesforce, so you need to make API calls to Group and Professional
Edition customers. Such calls aren’t possible by default, but if you’re an eligible partner, request a special API token that allows your
SOAP calls to integrate with Group and Professional Edition orgs. Be sure to embed the Client ID in the SOAP header of your external
code.
65
Sample Design Scenarios for Group and Professional EditionsDesigning and Building Your App
Connected Apps
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall packaged connected
apps:
AND “Download AppExchange Packages”
A connected app integrates an application with Salesforce using APIs. Connected apps use standard SAML and OAuth protocols to
authenticate, provide single sign-on, and provide tokens for use with Salesforce APIs. In addition to standard OAuth capabilities, connected
apps allow Salesforce admins to set various security policies and have explicit control over who can use the corresponding apps.
Create a Connected App
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
66
Connected AppsDesigning and Building Your App
“Customize Application” AND either
“Modify All Data” OR “Manage Connected Apps”
To install and uninstall packaged connected apps:
AND “Download AppExchange Packages”
When you create a connected app, you specify general information about the app and settings for OAuth, web apps, mobile apps, and
canvas apps. You can also customize how the app is invoked by creating a connected app handler with the ConnectedAppPlugin
Apex class.
The New Connected App wizard walks you through creating a connected app.
•In Salesforce Classic, from Setup, enter Apps in the Quick Find box, then select App. Under Connected Apps, click New.
•In Lightning Experience, you use the App Manager to create connected apps. From Setup, enter App in the Quick Find box, then
select App Manager. (1) Click New Connected App. (2)
Note: Be sure to select App Manager to create a connected app, not Manage Connected Apps. (3)
The information you enter to create a connected app is divided into these settings:
•Basic Information
•API (Enable OAuth Settings)
•Web App Settings
•Custom Connected App Handler
•Mobile App Settings
•Canvas App Settings
You can create a connected app without specifying authorization, canvas, or mobile settings. This kind of connected app behaves like
a “bookmark” to the specified URL that appears in the user’s App Launcher and the dropdown app menu. Simply enter basic information
and provide a Start URL in the Web App Settings. If the destination requires authentication, the service hosting the destination URL
prompts users to provide login credentials when they navigate to it.
When you’re finished entering the information, click Save. You can now publish your app, make further edits, or delete it. If you’re using
OAuth, saving your app gives you two new values that the app uses to communicate with Salesforce.
•Consumer Key: A value used by the consumer to identify itself to Salesforce. Referred to as client_id in OAuth 2.0.
•Consumer Secret: A secret used by the consumer to establish ownership of the consumer key. Referred to as client_secret
in OAuth 2.0.
67
Create a Connected AppDesigning and Building Your App
Important: For your convenience, you can update some fields in a connected app and the changes apply immediately to all
installed versions of the app. For example, connected app descriptions are immediately updated in each version of the connected
app. The following version-independent fields bypass the packaging or installation lifecycle.
•Description
•Info URL
•Logo Image URL
•Callback URL
Basic Information
Specify basic information about your app in this section, including the app name, logo, and contact information.
1. Enter the connected app name. This name is displayed in the App Manager and on its App Launcher tile.
Note: The connected app name must be unique for the connected apps in your org. You can reuse the name of a deleted
connected app if the connected app was created using the Spring ’14 release or later.
2. Enter the API name used when referring to your app from a program. It defaults to a version of the name without spaces. Only letters,
numbers, and underscores are allowed, so if the original app name contains any other characters, edit the default name.
3. Enter the contact email for Salesforce to use when contacting you or your support team. This address isn’t given to Salesforce admins
who install the app.
4. Enter the contact phone for Salesforce to use in case we need to contact you. This number isn’t given to Salesforce admins who
install the app.
5. Enter a logo image URL to display your logo on the App Launcher tile. It also appears on the consent page that users see when
authenticating. The URL must use HTTPS. Use a GIF, JPG, or PNG file format and a file size that’s preferably under 20 KB, but at most
100 KB. We resize the image to 128 pixels by 128 pixels, so be sure that you like how it looks. If you don’t supply a logo, Salesforce
generates one for you using the app’s initials.
•You can upload your own logo image by clicking Upload logo image. Select an image from your local file system that meets
the size requirements for the logo. When your upload is successful, the URL to the logo appears in the Logo Image URL field.
Otherwise, make sure that the logo meets the size requirements.
•You can also select a logo from the Salesforce samples by clicking Choose one of our sample logos. The logos include ones
for Salesforce apps, third-party apps, and standards bodies. Click the logo you want, and then copy and paste the URL into the
Logo Image URL field.
•You can use a logo hosted publicly on Salesforce servers by uploading an image as a document from the Documents tab. View
the image to get the URL, and then enter the URL into the Logo Image URL field.
6. Enter an icon URL to display a logo on the OAuth approval page that users see when they first use your app. Use an icon that’s 16
pixels high and wide and on a white background.
You can select an icon from the samples provided by Salesforce. Click Choose one of our sample logos. Click the icon you want,
and then copy and paste the displayed URL into the Icon URL field.
7. If you have a web page with more information about your app, provide an info URL.
8. Enter a description up to 256 characters to display on the connected app’s App Launcher tile. If you don’t supply a description, just
the name appears on the tile.
68
Create a Connected AppDesigning and Building Your App
Note: The App Launcher displays the connected app’s name, description, and logo (if provided) on an App Launcher tile. Make
sure that the text is meaningful and mistake-free.
API (Enable OAuth Settings)
This section controls how your app communicates with Salesforce. Select Enable OAuth Settings to configure authentication settings.
1. Enter the callback URL (endpoint) that Salesforce calls back to your application during OAuth. It’s the OAuth redirect URI. Depending
on which OAuth flow you use, the URL is typically the one that a user’s browser is redirected to after successful authentication.
Because this URL is used for some OAuth flows to pass an access token, the URL must use secure HTTPS or a custom URI scheme. If
you enter multiple callback URLs, at run time Salesforce matches the callback URL value specified by the app with one of the values
in Callback URL. It must match one of the values to pass validation.
2. If you’re using the JWT OAuth flow, select Use Digital Signatures. If the app uses a certificate, click Choose File and select the
certificate file.
3. Add all supported OAuth scopes to Selected OAuth Scopes. These scopes refer to permissions given by the user running the connected
app. The OAuth token name is in parentheses.
Access and manage your Chatter feed (chatter_api)
Allows access to Chatter REST API resources only.
Access and manage your data (api)
Allows access to the logged-in user’s account using APIs, such as REST API and Bulk API. This value also includes chatter_api,
which allows access to Chatter REST API resources.
Access your basic information (id, profile, email, address, phone)
Allows access to the Identity URL service.
Access custom permissions (custom_permissions)
Allows access to the custom permissions in an org associated with the connected app. It shows whether the current user has
each permission enabled.
Allow access to your unique identifier (openid)
Allows access to the logged-in user’s unique identifier for OpenID Connect apps.
Full access (full)
Allows access to the logged-in user’s data, and encompasses all other scopes. full doesn’t return a refresh token. You must
explicitly request the refresh_token scope to get one.
Perform requests on your behalf at any time (refresh_token, offline_access)
Allows a refresh token to be returned if the app is eligible to receive one. This scope lets the app interact with the user’s data
while the user is offline. The refresh_token scope is synonymous with offline_access.
Provide access to custom applications (visualforce)
Allows access to Visualforce pages.
Provide access to your data via the Web (web)
Allows use of the access_token on the web. It includes visualforce, which allows access to Visualforce pages.
4. If you’re setting up OAuth for applications on devices with limited input or display capabilities, such as TVs, appliances, or command-line
applications, select Enable for Device Flow.
Note: When enabled, the value for the callback URL defaults to a placeholder unless you specify your own URL. A callback
URL isn’t used in the device authentication flow. You can specify your own callback URL as needed, such as when this same
consumer is being used for a different flow.
69
Create a Connected AppDesigning and Building Your App
5. If you’re setting up OAuth for a client app that can’t keep the client secret confidential and must use the web server flow because
it can’t use the user-agent flow, deselect Require Secret for Web Server Flow. We still generate a client secret for your app but
this setting instructs the web server flow to not require the client_secret parameter in the access token request. If your app
can use the user-agent flow, we recommend user-agent as a more secure option than web server flow without the secret.
6. Control how the OAuth request handles the ID token. If the OAuth request includes the openid scope, the returned token can
include the ID token.
•To include the ID token in refresh token responses, select Include ID Token. It’s always included in access token responses.
•With the primary ID token setting enabled, configure the secondary settings that control the ID token contents in both access
and refresh token responses. Select at least one of these settings.
Include Standard Claims
Include the standard claims that contain information about the user, such as the user’s name, profile, phone_number, and
address. The OpenID Connect specifications define a set of standard claims to be returned in the ID token.
Include Custom Attributes
If your app has specified custom attributes, include them in the ID token.
Include Custom Permissions
If your app has specified custom permissions, include them in the ID token.
7. If you’re setting up your app to issue asset tokens for connected devices, configure the asset token settings.
•Select Enable Asset Tokens. Then specify these settings.
Token Valid for
The length of time that the asset token is valid after it’s issued.
Asset Signing Certificate
The self-signed certificate that you’ve already created for signing asset tokens.
Asset Audiences
The intended consumers of the asset token. For example, the backend service for your connected device, such as
https://your_device_backend.com.
Include Custom Attributes
If your app has specified custom attributes, include them in the asset token.
Include Custom Permissions
If your app has specified custom permissions, include them in the asset token.
•Specify the callback URL (endpoint). For example, https://your_device_backend.com/callback.
•Make sure that you add the OAuth scopes that are required for asset tokens.
–Access and manage your data (api)
–Allow access to your unique identifier (openid)
If your org had the No user approval required for users in this organization option selected on your remote access before the Spring
’12 release, users in the org where the app was created are automatically approved for the app. This option is selected to indicate the
automatic approval. For connected apps, the recommended procedure after you’ve created an app is for admins to install the app and
then set Permitted Users to Admin-approved users. If the remote access option wasn’t originally selected, the option doesn’t show
up.
70
Create a Connected AppDesigning and Building Your App
Web App Settings
Enter a start URL for your app to direct users to a specific location after they’ve authenticated. If you don’t enter a start URL, users are
sent to the app’s default start page after authentication completes. If the connected app that you’re creating is a canvas app, skip this
field. The Canvas App URL field contains the URL that gets called for the connected app.
If your connected app uses a SAML service provider, select Enable SAML. Enter the entity Id, ACS URL, subject type, name ID format,
and issuer, available from your service provider. Select Verify Request Signatures if the service provider gave you a security
certificate. Browse your system for the certificate. This is only necessary if you plan to initiate logging in to Salesforce from the service
provider and the service provider signs their SAML requests.
Important: If you upload a certificate, all SAML requests must be signed. If no certificate is uploaded, all SAML requests are
accepted.
Optionally, select Encrypt SAML Response to upload a certificate and select an encryption method for encrypting the assertion. Valid
encryption algorithm values are AES–128 (128–bit key), AES–256 (256–bit key), and Triple-DES (Triple Data Encryption Algorithm).
Custom Connected App Handler
Customize the behavior of a connected app with Apex. Create a class that extends the ConnectedAppPlugin Apex class, and
associate it with a connected app. The class can support new authentication protocols or respond to user attributes in a way that benefits
a business process.
The plug-in runs on behalf of a user account. In the Run As field, select the user for the plug-in. If the user isn’t authorized for the connected
app, use the authorize method to do so. For more information, see the ConnectedAppPlugin class in the Apex Code
Developer's Guide.
Mobile App Settings
1. Enter the mobile start URL to direct users to a specific location when the app is accessed from a mobile device. If you don’t enter a
mobile start URL, users are sent to the start URL defined under Web App Settings. If the connected app you’re creating is a canvas
app, you can skip this field. The Canvas App URL field contains the URL that gets called for the connected app.
2. Select PIN Protect if your app supports PIN protection. This setting allows the admin to set the session timeout and PIN length for
mobile applications after installing the connected app. PIN protection is supported by the Salesforce Mobile SDK
(https://developer.salesforce.com/page/Mobile_SDK). You can also implement it manually by reading the mobile_policy
object from the user’s Identity URL.
3. Specify the app platform from the dropdown list.
4. Specify the supported device form factors for the mobile app from the Restrict to Device Type dropdown list. If the app supports all
form factors, don’t choose a value.
5. Enter the app version number of the mobile app.
6. Enter the minimum OS version required for the app.
7. Select Private App to confirm that this app is for internal (non-public) distribution only. This setting is required because Apple
doesn’t allow distribution of public mobile apps outside its App Store.
8. If the mobile app is private, specify the location of the Mobile App Binary file. The format of the file is IPA for iOS, and APK for Android.
9. For iOS apps only:
a. Specify the location of the Application Icon that is displayed while the app is being downloaded and installed on an iOS device.
b. Specify the iOS Bundle Identifier.
71
Create a Connected AppDesigning and Building Your App
Note: For iOS 7 and later, use the same bundle identifier that you used when developing the app in XCode. If you don’t,
end users see two app icons during installation.
10. If the mobile connected app is a public app and you haven’t uploaded its binary file to Salesforce, enter the app binary URL.
Note: If you remove mobile integration from a new version of an existing connected app, mobile integration is no longer included
in any version of it. For example, you publish a package containing version 1.0 of your connected app with mobile integration.
You then remove mobile integration from the app, repackage it, and publish it as version 1.1. If a customer installs the earlier
package with version 1.0, the connected app doesn’t contain mobile integration.
Your connected app can receive push notifications if you meet the following requirements.
•Your app is built with Salesforce Mobile SDK.
•Your app implements the Mobile SDK push notification protocol for your platform.
•You’re a registered developer with the mobile platform provider (Apple or Google).
•Your app is registered with Apple Push Notification Service (APNS) for iOS push notifications or with Google Cloud Messaging (GCM)
for Android push notifications.
•You’ve implemented Apex handlers for push notifications.
Note: A push-enabled connected app can support only one mobile platform. To support push notifications on Android and iOS
versions of your mobile app, create a connected app for each platform.
For details, see the Salesforce Mobile Push Notifications Implementation Guide.
To configure push notifications for APNS (iOS):
1. Select Push Messaging Enabled.
2. For Supported Push Platform, select Apple.
3. Select the Apple environment that is valid for your APNS push notifications certificate.
4. For Certificate, select the .p12 certificate file that you received from APNS when you registered your app for push notifications (for
example, appkey.p12).
5. Enter the password for your .p12 certificate file.
To configure push notifications for GCM (Android):
1. Select Push Messaging Enabled.
2. For Supported Push Platform, select Android GCM.
3. For Key for Server Applications (API Key), enter the key that you obtained during developer registration with Google.
To change the mobile platform that you’ve configured for push notifications:
1. Deselect Push Messaging Enabled.
2. Save the connected app, and then click Edit.
3. Change App Platform and associated values in Mobile Settings to reflect the new platform.
4. Reconfigure push notifications for the new platform.
Canvas App Settings
Two types of canvas apps are available.
•Canvas apps that the org’s Salesforce admin installed.
72
Create a Connected AppDesigning and Building Your App
•Canvas personal apps that users installed across orgs. Users access a canvas personal app from the Chatter tab, and are prompted
to allow the app to connect to their Salesforce data. Users can choose to make an app a canvas personal app. For more information,
see “Canvas Personal Apps” in the Force.com Canvas Developer’s Guide.
1. If your connected app is exposed as a canvas app, select Force.com Canvas.
2. Enter the canvas app URL to the third-party app. The user is directed to this URL when clicking the link to your canvas app.
3. Select an access method. This method specifies how the canvas app initiates the OAuth authentication flow.
•Signed Request (POST)—OAuth authentication is used, but when Salesforce admins install the canvas app, they implicitly allow
access for users. Users aren’t prompted to allow apps to access their user information. When you use this access method,
authentication is posted directly to the canvas app URL.
If your canvas app uses signed request authentication, be sure that you don’t select Perform requests on your behalf at any
time for the Selected OAuth Scopes.
•OAuth Webflow (GET)—OAuth authentication is used, and the user is prompted to allow apps to access their information. When
you use this access method, the canvas app must initiate the OAuth authentication flow.
4. If you’re using SAML single sign-on (SSO) for canvas app authentication, select the SAML Initiation Method field. This field is
enabled if you select Enable SAML in the Web App Settings section. The options for this field include the following.
•Identity Provider Initiated—Salesforce makes the initial request to start the SSO flow.
•Service Provider Initiated—Canvas app starts the SSO flow after the app is invoked.
5. Under Locations, select where the canvas app appears to users.
•Chatter Feed—Canvas app appears in the feed. If selected, create a CanvasPost feed item and ensure that the current user has
access to the canvas app.
•Chatter Tab—Canvas app appears in the app navigation list on the Chatter tab. If selected, the canvas app appears automatically.
•Console—Canvas app appears in the footer or sidebars of the Salesforce console. If selected, you must choose where the canvas
app appears in a console by adding it as a custom console component.
•Layouts and Mobile Cards—Canvas app can appear on a page layout or a mobile card. If selected, choose where the canvas app
appears by adding it to the page layout.
•Mobile Nav—Canvas app is accessible from the navigation menu in Salesforce1.
Note: Canvas apps don’t appear in the Salesforce1 navigation menu on Android mobile devices. To see canvas apps in
the navigation menu, log in to the Salesforce1 mobile browser app.
•Open CTI—Canvas app appears in the call control tool. If selected, specify the canvas app in your call center’s definition file for
it to appear.
•Publisher—Canvas app appears in the publisher. If selected, create a canvas custom quick action and add it to the global layout
or to an object layout.
•Visualforce Page—Canvas app can appear on a Visualforce page. If you add an <apex:canvasApp> component to expose
a canvas app on a Visualforce page, be sure to select this location for the canvas app. If you don’t, you receive an error.
6. Select Create Actions Automatically to create a global action for your canvas app. To do so, select Publisher under Location. If
you don’t, no global actions are created. You can also create the action later.
7. If you implement your own Canvas.CanvasLifecycleHandler Apex class, provide the class name in Lifecycle
Class. Providing a Canvas.CanvasLifecycleHandler Apex class lets you customize context information and add
custom behavior to your canvas app.
8. To let users install your app, select Enable as a Canvas Personal App. Chatter Tab is the only location that supports canvas personal
apps. For details, see “Canvas Personal Apps” in the Force.com Canvas Developer’s Guide.
73
Create a Connected AppDesigning and Building Your App
Note: If you don’t see the Enable as a Canvas Personal App setting, the admin for the app’s destination org hasn’t enabled
canvas personal apps. For details, see “Enabling Canvas Personal Apps within an Organization” in the Force.com Canvas
Developer’s Guide.
Edit, Reconfigure, or Delete a Connected App in Salesforce Classic
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall packaged connected
apps:
AND “Download AppExchange Packages”
After creating a connected app, you can edit, reconfigure, or it. You can restrict access and add custom attributes.
Edit a Connected App
You can edit a connected app at any time to change its description, logo, icon, or callback URL. You can update settings for OAuth, web
apps, mobile apps, or canvas apps.
1. Open the list of apps. From Setup, enter Apps in the Quick Find box, then select Apps.
2. Locate the connected app in the apps list, and click Edit.
3. Make your changes and click Save
Important: For your convenience, you can update some fields in a connected app and the changes apply immediately to all
installed versions of the app. For example, connected app descriptions are immediately updated in each version of the connected
app. The following version-independent fields bypass the packaging or installation lifecycle.
•Description
•Info URL
•Logo Image URL
74
Edit, Reconfigure, or Delete a Connected App in Salesforce
Classic
Designing and Building Your App
•Callback URL
Restrict Access to a Trusted IP Range and Allow Access from Outside the IP Range
After you’ve created the connected app, you can specify the allowed IP ranges from which a user can log in. The IP ranges work with
OAuth-enabled connected apps, not SAML-enabled connected apps.
To set the allowed IP range:
1. Open the list of apps. From Setup, enter Apps in the Quick Find box, then select Apps.
2. Locate the connected app in the apps list, and click its name.
3. In the Trusted IP Range for OAuth Web server flow section, click New.
4. For the start IP address, enter a valid IP address. For the end IP address, enter the same or higher IP address.
Enter multiple discontinuous ranges by clicking New.
You can give specific users access to an OAuth connected app from outside of the Trusted IP Range. For example, to give users access
when traveling, set the connected app to Relax IP Restrictions with second factor. When a user tries to use the connected app from
outside the range, the user is prompted to provide a second factor of authentication, such as a token code. After successful second-factor
authentication, the user can use the connected app.
To allow access outside the specified IP ranges:
1. Open the list of apps. From Setup, enter Apps in the Quick Find box, then select Apps.
2. Locate the connected app in the apps list, and click Manage.
3. Click Edit Policies.
4. In the IP Relaxation field, select Relax IP Restrictions.
Note: If Enforce login IP ranges on every request is enabled, it affects the IP relaxation behavior. For more information, see
Connected App IP Relaxation and Continuous IP Enforcement on page 83.
Add Custom Attributes
After you’ve created the connected app, you can add custom attributes. With custom attributes, you can get more information about a
user’s identity, like an address or job title. Custom attributes specify SAML metadata or specify OAuth parameters that are read at OAuth
runtime.
1. Open the list of apps. From Setup, enter Apps in the Quick Find box, then select Apps.
2. Locate the connected app in the apps list, and click its name.
3. Under Custom Attributes, click New.
Each custom attribute must have a unique key and use fields available from the Insert Field menu. For example, assign a key name,
such as country and insert the field $Organization.Country. When using SAML, attributes are sent as SAML attribute
statements. When using OAuth, attributes are available as a custom_attributes object in the user’s Identity URL.
Delete a Connected App
Note: The connected app name must be unique for the connected apps in your org. You can reuse the name of a deleted
connected app if the connected app was created using the Spring ’14 release or later.
1. Open the list of apps. From Setup, enter Apps in the Quick Find box, then select Apps.
75
Edit, Reconfigure, or Delete a Connected App in Salesforce
Classic
Designing and Building Your App
2. Locate the connected app in the apps list, and click its name.
3. Click Delete, and click Delete again to confirm.
If you delete a connected app that has been included in a package, the app remains available in the package until you update the
package. Don’t delete a connected app that Salesforce distributes, such as Salesforce1.
Install a Connected App
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall packaged connected
apps:
AND “Download AppExchange Packages”
You install a connected app in your org by installing a managed package that includes the connected app as a component. For example,
ISVs package connected apps to make them available on AppExchange. You can also install an OAuth connected app from the Connected
Apps OAuth Usage page. This page lists all OAuth connected apps that users in your org are connecting to currently—including apps
that developers created in other Salesforce orgs.
When an Install button appears next to a connected app, users in your org are connecting to the app but it isn’t installed in your org. To
manage an app’s security policies, such as which users can access the app and for how long, you must install the connected app in your
org.
1. From Setup, enter OAuth in the Quick Find box, then select Connected Apps OAuth Usage.
2. Select an app and click Install.
3. Click Manage App Policies to get details about the app.
4. Click Edit Policies to control the app’s security policies.
76
Install a Connected AppDesigning and Building Your App
View Connected App Details
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall packaged connected
apps:
AND “Download AppExchange Packages”
The Connected App Detail page provides information about the connected app, including its version and scopes. You can edit and check
usage of the connected app and associate profiles and permissions.
•Click Edit to change the app configuration on the Connected App Edit page.
•Click Download Metadata to get the service provider SAML login URLs and endpoints that are specific to your community or
custom domain configuration. This button only appears if your org is enabled as an Identity Provider, and only with connected apps
that use SAML. Instead of downloading metadata, you can access the metadata via a URL in Metadata Discovery Endpoint. Your
service provider uses this URL to configure single sign-on to connect to Salesforce.
•Click View OAuth Usage to see the usage report for OAuth connected apps in your org.
•Click Enable User Provisioning to enable user provisioning for a connected app. When enabled, use the User Provisioning wizard
to configure or update the settings. After you run the User Provisioning wizard, you can individually manage the linkage between
user accounts and their account settings on the third-party system in the User Accounts section.
•Click Manage Profiles to select the profiles for the app from the Application Profile Assignment page. Select the profiles to have
access to the app (except in Group Edition).
Important: This option won’t appear if the OAuth policy for Permitted Users is set to All users may
self-authorize because this option isn’t needed when users can authorize themselves.
•Click Manage Permission Sets to select the permission sets for the profiles for this app from the Application Permission Set
Assignment page. Select the permission sets to have access to the app.
Important: This option won’t appear if the OAuth policy for Permitted Users is set to All users may
self-authorize because this option isn’t needed when users can authorize themselves.
•Click New in Service Provider SAML Attributes to create attribute key/value pairs. You can also edit or delete existing attributes.
77
View Connected App DetailsDesigning and Building Your App
If you select Admin-approved users for Permitted Users on the Connected App Edit page, only the users with at least one of the
selected profiles or permission sets can run the app. If you select All Users, profiles and permission sets are ignored.
Manage a Connected App
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall packaged connected
apps:
AND “Download AppExchange Packages”
The Connected Apps page lists all connected apps created or installed in the org from other orgs or from AppExchange. You can select
an app to get more information and monitor its usage. You can also edit policies, for example, to specify a start URL, add your own
connected app handler, or enable user provisioning.
To view and update properties of a connected app, from Setup, enter Connected Apps in the Quick Find box, then select
Manage Connected Apps. Click the name of the connected app to view information, usage, and policies.
Click Edit Policies to specify a start URL, add your own connected app handler, add custom attributes, or enable user provisioning.
Note: Sessions refresh automatically between every 15 minutes and 24 hours while a user is in the app. The refresh is based on
the session timeout value set for your org. The refresh is often undetected by the user.
Connected Apps Installed by Salesforce
Some Salesforce client apps are implemented as connected apps and Salesforce automatically installs in your org. For example, Salesforce1
and Salesforce for Outlook are installed automatically. That’s why the list of connected apps in your list of installed apps is longer than
you might expect.
These client-type Salesforce connected apps are distributed in two managed packages: one for Salesforce1-related apps and one for
non-Salesforce1-related apps. The list of included apps changes with each release. However, to simplify administration, each package
is asynchronously installed in your org the first time a user in the org accesses one of these apps.
If you want to install (or reinstall) the Salesforce1 package for connected apps, proactively, you can install it from the AppExchange.
78
Manage a Connected AppDesigning and Building Your App
The packages appear in Setup under the Installed Packages List.
Click each package name to see the list of components. The following are some components for the Salesforce Connected Apps package.
Note: The Force.com IDE and Force.com Migration tool are “wrapper” connected apps that use the SOAP API to connect to
Salesforce instead of OAuth, which other types of connected apps do. They still use the connected apps framework to allow or
deny users access to the apps in an org.
The following are some components for the Salesforce1 and Chatter apps package.
To manage installed connected apps, from Setup, enter Connected Apps in the Quick Find box, then select Manage
Connected Apps. The connected apps that Salesforce installs appear in the list as installed by a managed package. They appear along
with your other installed connected apps.
79
Manage a Connected AppDesigning and Building Your App
Connected Apps Installed from the Connected Apps OAuth Usage Page
In addition to the apps installed from managed packages, this list contains apps installed from the Connected Apps OAuth Usage page.
Edit Connected App Behavior
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall packaged connected
apps:
AND “Download AppExchange Packages”
Modify connected app settings and permissions to control how they behave. For example, you can change refresh token and session-level
policies for all connected apps running in your org. You can change OAuth policies for OAuth-enabled connected apps. And you can
customize the behavior of a connected app with Apex.
1. Open the list of apps.
•In Salesforce Classic, from Setup, enter Apps in the Quick Find box, select Apps, then click the name of the connected app.
•In Lightning Experience, from Setup, enter Apps in the Quick Find box, select App Manager, click , and then select Edit.
Basic Information
Basic Information applies to all connected apps, except canvas apps.
•Start URL—For connected apps that use single sign-on. Set the URL to the page where the user starts the authentication process.
This URL also appears in the app menu.
•Mobile Start URL—For mobile connected apps to direct users to a specific location when the app is accessed from a mobile device.
If your app is a canvas app, the connected app ignores the start URL fields. Instead, it uses the canvas app URL specified when the
connected app was created.
80
Edit Connected App BehaviorDesigning and Building Your App
OAuth Policies
OAuth policies apply if the connected app is OAuth-enabled.
•The Permitted Users policy determines who can run the app.
–All Users may self-authorize—Default. Anyone in the org can authorize the app. Users must approve the app the first time they
access it.
–Admin-approved users are pre-authorized—Only users with the appropriate profile or permission set can access the app. These
users don’t have to approve the app before they can access it. Manage profiles for the app by editing each profile’s Connected
App Access list. Manage permission sets for the app by editing each permission set’s Assigned Connected Apps list. This setting
is not available in Group Edition.
Warning: If you switch from All Users may self-authorize to Admin-approved users are pre-authorized, anyone using
the app loses access, unless the user belongs to a permission set or profile that you have specified for the app.
Note: If the user’s profile or permission set has the Use Any API Client user permission, the Admin-approved users are
pre-authorized policy is bypassed. This user permission is available only if the Admin Approved Apps Only org permission is
enabled. The Use Any API Client user permission allows a non-admin-approved user to access and run the app, even if the
connected app’s settings require admin-approved users and the Admin Approved Apps Only org permission is enabled. This
permission scheme allows specific users, such as short-term contractors, to access a connected app temporarily.
•The IP Relaxation policy determines whether a user’s access to the app is restricted by IP ranges. A Salesforce admin can choose to
enforce or bypass IP restrictions by choosing one of the following options.
–Enforce IP restrictions—Default. A user running this app is subject to the org’s IP restrictions, such as IP ranges, which are set in
the user’s profile.
–Relax IP restrictions with second factor—A user running this app bypasses the org’s IP restrictions when either of these conditions
is true.
•The app has a whitelist of IP ranges and is using the web server OAuth authentication flow. Only requests coming from the
whitelisted IPs are allowed.
•The app has no IP-range whitelist, is using the web server or user-agent OAuth authentication flow, and the user successfully
completes identity confirmation.
–Relax IP restrictions—A user running this app is not subject to any org IP restrictions.
Note: If Enforce login IP ranges on every request is enabled, it affects the IP relaxation behavior. For more information,
see Connected App IP Relaxation and Continuous IP Enforcement on page 83.
•The Refresh Token policy determines whether a refresh token is provided during authorization to get a new access token. If refresh
tokens are provided, users can continue to access the OAuth-enabled connected app without having to reauthorize when the access
token expires. Admins limit the lifetime of access tokens with the session timeout value. The connected app exchanges the refresh
token with an access token to start a new session. A Salesforce admin can choose one of the following refresh token policies.
–Refresh token is valid until revoked—Default. The refresh token is used indefinitely, unless revoked by the user or Salesforce
admin. You revoke tokens on a user’s detail page under OAuth Connected Apps or on the OAuth Connected Apps Usage Setup
page.
–Immediately expire refresh token—The refresh token is invalid immediately. The user can use the current session (access token)
already issued, but can’t obtain a new session when the access token expires.
–Expire refresh token if not used for n—The refresh token is valid as long as it’s been used within a specified amount of time. For
example, if set to seven days, and the refresh token isn’t exchanged for a new session within seven days, the next attempt to
use the token fails. The expired token can’t generate new sessions. If the refresh token is exchanged within seven days, the token
is valid for another seven days. The monitoring period of inactivity also resets.
81
Edit Connected App BehaviorDesigning and Building Your App
–Expire refresh token after n—The refresh token is valid for a fixed amount of time. For example, if the policy states one day, the
user can obtain new sessions only for 24 hours.
The Refresh Token policy is evaluated only during usage of the issued refresh token and doesn’t affect a user’s current session. Refresh
tokens are required only when a user’s session has expired or isn’t available. For example, if you set a refresh token policy to expire
the refresh token after 1 hour, and the user uses the app for 2 hours, the user isn’t forced to authenticate after one hour. However,
the user is required to authenticate again when the session expires and the client attempts to exchange its refresh token for a new
session.
If your connected app is a canvas app that uses signed request authentication, be sure to:
•Set Permitted Users to Admin-approved users are pre-authorized.
•Set Expire Refresh Tokens to The first time they use this application.
•Give users access via profiles and permission sets.
Session Policies
Session policies apply to all connected apps.
•Session Timeout Value—Specifies when access tokens expire to end a user’s connected app session. You can control how long a
user’s session lasts by setting the timeout value for the connected app, user profile, or org’s session settings (in that order). If you
don’t set a value or None is selected (the default), Salesforce uses the timeout value in the user’s profile. If the profile doesn’t specify
a timeout value, Salesforce uses the timeout value in the org’s Session Settings.
•The current permissions for the connected app are also listed in the org’s Session Settings.
•High Assurance session required—Requires users to enter a time-based token when trying to log in to access the app.
Mobile App Settings
Mobile App settings apply to mobile connected apps that enforce PIN protection.
•Require Pin after—Specifies how much time can pass while the app is idle before the app locks itself and requires the PIN before
continuing. Allowable values are none (no locking), 1, 5, 10, and 30 minutes. This policy is only enforced if a corresponding pin length
is configured. Enforcement of the policy is the responsibility of the connected app. Apps written using the Salesforce Mobile SDK
can enforce this policy, or the app can read the policy from the UserInfo service and enforce the policy.
Note: This setting doesn’t invalidate a user’s session. When the session expires due to inactivity, this policy only requires that
the user enter a PIN to continue using the current session.
•Pin Length—Sets the length of the identification number sent for authentication confirmation. The length can be from 4 to 8 digits,
inclusive.
Custom attributes are available for all connected apps. Developers can set custom SAML metadata or custom OAuth attributes for a
connected app. Salesforce admins can delete or edit the attributes or add custom attributes. Attributes deleted, edited, or added by
admins override attributes set by developers. For more information, see Edit, Reconfigure, or Delete a Connected App in Salesforce Classic
on page 74.
Custom Connected App Handler
Customize the behavior of a connected app with Apex. Create a class that extends the ConnectedAppPlugin Apex class, and
associate it with a connected app. The class can support new authentication protocols or respond to user attributes in a way that benefits
a business process.
82
Edit Connected App BehaviorDesigning and Building Your App
The plug-in runs on behalf of a user account. In the Run As field, select the user for the plug-in. If the user isn’t authorized for the connected
app, use the authorize method to do so. For more information, see the ConnectedAppPlugin class in the Apex Code
Developer's Guide.
User Provisioning Settings
Enable User Provisioning—Enable user provisioning for the connected app to create, update, and delete user accounts in the connected
app based on users in your Salesforce org. Salesforce provides a wizard to guide you through configuring or updating user provisioning
settings.
Connected App IP Relaxation and Continuous IP Enforcement
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
This topic describes how the Enforce login IP ranges on every request Session
Settings option affects OAuth-enabled connected app IP relaxation settings.
If you relaxed IP restrictions for your OAuth-enabled connected app, and your organization has the
Enforce login IP ranges on every request option enabled, the access to your
connected app can change. This access change applies to client access, including mobile devices,
for all OAuth-enabled connected apps. IP relaxation does not apply to SAML-enabled connected
apps.
Table 1: Connected App IP Relaxation Settings and Continuous IP Enforcement
When Continuous IP Enforcement Is
Enabled
When Continuous IP
Enforcement Is Disabled
(Default)
IP
Relaxation
A user running this app is subject to the
organization’s IP restrictions, such as IP
ranges set in the user’s profile.
A user running this app is subject to
the organization’s IP restrictions, such
as IP ranges set in the user’s profile.
Enforce
IP
restrictions
A user running this app bypasses the
organization’s IP restrictions when either of
A user running this app bypasses the
organization’s IP restrictions when
either of these conditions is true:
Relax
IP
restrictions
with
the OAuth conditions in the previous
column is true. However, the user can’t
access the following for security reasons:
•The app has IP ranges whitelisted
and is using the Web server OAuth
second
factor •Change passwordauthentication flow. Only requests
coming from the whitelisted IPs
are allowed.
•Add a time-based token
•Any pages in a login flow
•The app has no IP range whitelist,
is using the Web server or
user-agent OAuth authentication
flow, and the user successfully
completes identity confirmation.
A user running this connected app is not
subject to any IP restrictions. However, the
A user running this connected app is
not subject to any IP restrictions.
Relax
IP
restrictions user can’t access the following for security
reasons:
•Change password
83
Connected App IP Relaxation and Continuous IP EnforcementDesigning and Building Your App
When Continuous IP Enforcement Is EnabledWhen Continuous IP Enforcement Is Disabled
(Default)
IP Relaxation
•Add a time-based token
•Any pages in a login flow
Monitor Usage for an OAuth Connected App
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“View Setup and Configuration” AND
“Manage Users”
To view the OAuth Connected Apps Usage
page:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall packaged connected
apps:
AND “Download AppExchange Packages”
The OAuth Usage page lists all OAuth connected apps that users in the org are connecting to. These apps have an active access or refresh
token. If all tokens for an app are revoked or expired, the app disappears from this list.
The list displays all current OAuth connections to the org, regardless of where the app came from. If an app has an Install button next
to it, the connected app was created in another org. Install the app so that you can manage its security policies, for example, which users
can access the app and for how long.
To view information about OAuth connected apps, from Setup, enter OAuth in the Quick Find box, then select Connected Apps
OAuth Usage. The resulting list of apps can be long because it contains all Salesforce and custom OAuth apps available to your users,
not just the ones installed in your org. For example, it lists apps from AppExchange, Salesforce partners and other developers.
Connected App
Name of the connected app. The list contains only the apps that anyone in the org is using.
Description
Description of the connected app.
84
Monitor Usage for an OAuth Connected AppDesigning and Building Your App
Manage App Policies
Click Manage App Policies to open the detail page for the connected app. From the detail page, you can click Edit Policies to
manage the app’s access and security policies.
User Count
Number of users who are using the app. Click a User Count number to open the Connected App User’s Usage page to see information
about users, including:
•When they first used the app
•Most recent time they used the app
•Total number of times they used the app
From this page, you can end a user’s access to the current session by clicking Revoke. Or, you can click Revoke All at the top of the
page to log out everyone currently using the app.
Action
You can perform one of the following actions.
•Install—Make the OAuth connected app available for access and security policy management. When you click install, the
Manage App Policies link appears next to the app. Click the link to open the app’s detail page where you can set policies. Install
appears next to apps that were created in another org but not made available by Salesforce or a managed package. Install these
apps to manage their security policies in your org.
•Uninstall—Remove the local copy of the OAuth connected app. Click uninstall only when the original developer deletes the
app in the other Salesforce org. Uninstall doesn’t remove the connected app. It just removes the local copy that you installed to
set the app’s OAuth policies in your org. By uninstalling the app, you’re only removing the OAuth policies that you set for the
app in your org. You’re actually loosening your security measures.
•Block—Make the OAuth connected app inaccessible to your org’s users. Blocking an app ends all current user sessions and
blocks all new sessions.
•Unblock—Stop preventing new connections from being established. It allows users to log in and access the app at another
time.
Uninstall a Connected App
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Connected Apps can be
created in: Group,
Professional, Enterprise,
Performance, Unlimited,
and Developer Editions
Connected Apps can be
installed in: All Editions
USER PERMISSIONS
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To read, create, update, or delete connected
apps:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To update all fields except Profiles,
Permission Sets, and Service Provider SAML
Attributes:
“Customize Application” AND “Modify All
Data”
To update Profiles, Permission Sets, and
Service Provider SAML Attributes:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected
Apps”
To install and uninstall connected apps:
85
Uninstall a Connected AppDesigning and Building Your App
“Customize Application” AND either
“Modify All Data” OR “Manage Connected Apps”
To install and uninstall packaged connected apps:
AND “Download AppExchange Packages”
You can remove a connected app from your org in different ways. You can uninstall an OAuth connected app from the Connected App
OAuth Usage page. Or, if the connected app was installed as a managed package, you can also remove the app by uninstalling the
package.
The Connected App OAuth Usage page lists all OAuth connected apps that users in your org are accessing. If the app has an Uninstall
button next to it, the app was created by a developer in another org. It’s recommended that you uninstall an app only when the original
developer deletes the app on the other org. Uninstall doesn’t remove the connected app. It just removes the local copy that you installed
to set the app’s OAuth policies in your org. By uninstalling the app, you’re only removing the OAuth policies that you set for the app in
your org. You’re actually loosening your security measures.
To make the connected app inaccessible to your org’s users, click Block. Blocking an app ends all current user sessions with the connected
app and blocks all new sessions. You can restore access to the app by clicking Unblock.
Do not uninstall connected app packages owned and distributed by Salesforce, such as the Salesforce1 for iOS package. Salesforce
installs and manages these packages.
Environment Hub
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, and
Unlimited Editions
The Environment Hub lets you connect, create, view, and log in to Salesforce orgs from one location.
If your company has multiple environments for development, testing, and trials, the Environment
Hub lets you streamline your approach to org management.
From the Environment Hub, you can:
•Connect existing orgs to the hub with automatic discovery of related orgs.
•Create standard and partner edition orgs for development, testing, and trials.
•View and filter hub members according to criteria that you choose, like edition, creation date,
instance, origin, and SSO status.
•Create single sign-on (SSO) user mappings for easy login access to hub members.
Each hub member org corresponds to an EnvironmentHubMember object. EnvironmentHubMember is a standard object, similar to
Accounts or Contacts, so you can use the platform to extend or modify the Environment Hub programmatically. For example, you can
create custom fields, set up workflow rules, or define user mappings and enable SSO using the API for any hub member org.
Get Started with the Environment Hub
Configure the Environment Hub so that users at your company can access the app to create and manage member orgs. Then enable
My Domain so that you can connect existing orgs to the hub and create SSO user mappings.
Manage Orgs in the Environment Hub
You can manage all your existing Salesforce orgs from one location by connecting them to the Environment Hub. You can also
create orgs using Salesforce templates for development, testing, and trial purposes.
Single Sign-on in the Environment Hub
Developing, testing, and deploying apps means switching between multiple Salesforce environments and providing login credentials
each time. Single sign-on (SSO) simplifies this process by letting an Environment Hub user log in to member orgs without
reauthenticating. You can set up SSO by defining user mappings manually, using Federation IDs, or creating a formula.
86
Environment HubDesigning and Building Your App
Environment Hub Best Practices
Follow these guidelines and best practices when you use the Environment Hub.
Environment Hub FAQ
Answers to common questions about the Environment Hub.
Considerations for the Environment Hub in Lightning Experience
Be aware of these considerations when creating and managing orgs in the Environment Hub.
Get Started with the Environment Hub
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, and
Unlimited Editions
Configure the Environment Hub so that users at your company can access the app to create and
manage member orgs. Then enable My Domain so that you can connect existing orgs to the hub
and create SSO user mappings.
Configure the Environment Hub
Enable the Environment Hub in your org, and then configure it to give other users access.
Enable My Domain for the Environment Hub
My Domain is required to connect existing orgs to the Environment Hub and create SSO user
mappings. Enable My Domain in the org where the Environment Hub is installed.
Configure the Environment Hub
USER PERMISSIONS
To set up and configure the
Environment Hub:
•“Manage Environment
Hub”
Enable the Environment Hub in your org, and then configure it to give other users access.
1. Contact Salesforce to enable the Environment Hub in your org. If you’re an ISV partner, you can
skip this step. The Environment Hub is already installed in your Partner Business Org.
2. Log in to the org where the Environment Hub is enabled, and then go to Setup.
3. Assign users access to features in the Environment Hub.
a. From Setup, enter Profiles in the Quick Find box, then select Profiles.
b. Create a profile, or edit an existing one.
c. Edit the profile’s settings.
Environment Hub SettingsProfile Section
Enable the Environment Hub custom app to make it available
in the App Launcher in Lightning Experience or App Menu in
Salesforce Classic.
Custom App Settings
Unless advised by Salesforce, don’t adjust settings in this
section of the profile.
Connected App Access
If you enable single sign-on (SSO) in a member org, new entries
appear in this section of the profile. Entries appear in the format
Service Provider Access
Service Provider [Organization ID], where Organization ID is the
ID of the member org. Users who don’t have access to the
service provider sometimes see this message when attempting
87
Get Started with the Environment HubDesigning and Building Your App
Environment Hub SettingsProfile Section
to log in via SSO: “User ‘[UserID]’ does not have access to sp
‘[Service Provider ID]’.”
When configuring the Environment Hub in a new org, this
section is empty.
Enable “Manage Environment Hub” to allow users to:Administrative Permissions
•Create orgs for development, testing, and trials.
•Configure SSO for member orgs.
Enable “Connect Organization to Environment Hub” to allow
users to connect existing orgs to the Environment Hub.
General User Permissions
Grant object permissions based on the level of access required
by the Environment Hub user.
Standard Object Permissions
Hub Members object:
•“Read”—View existing Hub Member records.
•“Create”—This permission has no impact on the ability to
create Hub Member records. That’s because record creation
is handled either by connecting an existing org or creating
an org from the Environment Hub.
•“Edit”—Edit fields on existing Hub Member records.
•“Delete”—Disconnect an org from the Environment Hub
and delete its corresponding Hub Member record and
Service Provider record (if SSO was enabled for the
member).
•“View All”—Read all Hub Member records, regardless of
who created them.
•“Modify All”—Read, edit, and delete all Hub Member
records, regardless of who created them.
Hub Invitations object:
•If you enable the “Connect Organization to Environment
Hub” permission, enable “Create”, “Read”, “Update, and
“Delete” for Hub Invitations.
Signup Request object:
•If you enable the “Manage Environment Hub” permission,
enable “Create” and “Read” for Signup Requests to allow
users to create orgs. Optionally, enable “Delete” to allow
users to remove orgs from the hub.
d. Select Save.
88
Get Started with the Environment HubDesigning and Building Your App
Enable My Domain for the Environment Hub
USER PERMISSIONS
To set up a domain name:
•“Customize Application”
My Domain is required to connect existing orgs to the Environment Hub and create SSO user
mappings. Enable My Domain in the org where the Environment Hub is installed.
1. Find an available domain name and sign up for it.
a. From Setup, enter My Domain in the Quick Find box, then select My Domain.
b. Enter the subdomain name you want to use within the sample URL.
c. Select Check Availability. If your name is already taken, choose a different one.
d. Select Register Domain.
You receive a confirmation email from Salesforce when your new domain is ready for testing.
2. Test your domain name and deploy it to your org.
a. Click the URL in the confirmation email to log in to Salesforce using your new domain. Alternatively, from Setup, enter My
Domain in the Quick Find box, select My Domain, and then select Click here to login.
b. Test the new domain by clicking tabs and links within your org. Notice that all pages show your new domain name.
Tip: If you use custom buttons or Visualforce pages in your org, test them before deploying the new domain name. If you
used instance-based URLs in your customizations, your links are broken.
c. To roll out the new domain name to your org, from Setup, enter My Domain in the Quick Find box, select My Domain,
and then select Deploy to Users.
The domain is activated immediately, and your users are redirected to pages with the new domain.
3. Set the domain login policy for users accessing your pages.
a. From Setup, enter My Domain in the Quick Find box, then select My Domain.
b. Under My Domain Settings, select Edit.
c. To turn off authentication for users who do not use your domain-specific login page, select the login policy. This option enhances
security by preventing login attempts by anyone who doesn’t know your domain name.
d. Choose a redirect policy based on the level of security that you want. You have these 3 options, in order of increasing security.
•Redirect users to the same page within the domain.
•Redirect users with a warning.
•Prevent redirecting by having users enter the new domain name.
Manage Orgs in the Environment Hub
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, and
Unlimited Editions
You can manage all your existing Salesforce orgs from one location by connecting them to the
Environment Hub. You can also create orgs using Salesforce templates for development, testing,
and trial purposes.
Connect an Org to the Environment Hub
You can connect existing Salesforce orgs to the Environment Hub, allowing you to manage all
your development, test, and trial environments from one location. When you connect an org
to the hub, related orgs are automatically discovered so you don’t have to manually connect
them.
89
Manage Orgs in the Environment HubDesigning and Building Your App
Create an Org from the Environment Hub
You can create orgs from the Environment Hub for development, testing, and trial purposes. If you’re an ISV partner, you can also
create partner edition orgs with increased limits, more storage, and other customizations to support app development. When you
create an org from the Environment Hub, it becomes a hub member and its default language is set by the user’s locale.
Connect an Org to the Environment Hub
USER PERMISSIONS
To connect an organization
to the Environment Hub:
•“Connect Organization
to Environment Hub”
You can connect existing Salesforce orgs to the Environment Hub, allowing you to manage all your
development, test, and trial environments from one location. When you connect an org to the hub,
related orgs are automatically discovered so you don’t have to manually connect them.
The following types of related orgs are automatically discovered.
•For any organization, all sandbox orgs created from it
•For a release org, all its related patch orgs
•For a Trialforce Management Org, all Trialforce Source Orgs created from it
•For an org with the License Management App (LMA) installed, any release org with a managed package registered in the LMA
Note: You can't connect a sandbox org to the Environment Hub directly. If you want to connect a sandbox, first connect the org
used to create the sandbox to the Environment Hub. Then, refresh the sandbox org. The refresh automatically adds it as a hub
member.
1. Log in to the Environment Hub, and then select Connect Org.
2. Enter the admin username for the org that you want to connect and, optionally, a short description. A description makes it easier to
find the org later, especially if your hub has many members.
3. By default, single sign-on (SSO) is enabled for the org you connected. To disable SSO, deselect Auto-enable SSO for this org.
4. Select Connect Org again.
5. In the pop-up window, enter the org’s admin username and password. If you don’t see the pop-up, temporarily disable your browser’s
ad blocking software and try again.
6. Select Log In, and then select Allow.
Create an Org from the Environment Hub
USER PERMISSIONS
To set up and configure the
Environment Hub:
•“Manage Environment
Hub”
You can create orgs from the Environment Hub for development, testing, and trial purposes. If
you’re an ISV partner, you can also create partner edition orgs with increased limits, more storage,
and other customizations to support app development. When you create an org from the
Environment Hub, it becomes a hub member and its default language is set by the user’s locale.
Note: You can create up to 20 member orgs per day. To create more orgs, log a case in the
Partner Community.
1. Log in to the Environment Hub, and then select Create Org.
2. Choose an org purpose.
Lets You Create:Purpose
Developer Edition orgs for building and packaging apps.Development
90
Manage Orgs in the Environment HubDesigning and Building Your App
Lets You Create:Purpose
Trial versions of standard Salesforce orgs for testing and demos. These orgs are similar to the ones
customers create at www.salesforce.com/trial. When you create a Test/Demo org, you can specify a
Trialforce template if you want the org to include your customizations.
Test/Demo
Trialforce Source Organizations (TSOs) as an alternative to using a Trialforce Management Organization.
Unless you need custom branding on your login page or emails, use the Environment Hub to create
TSOs.
Trialforce
3. Enter the required information for the org type you selected.
4. Read the Master Subscription Agreement, and then select the checkbox.
5. Select Create.
When your org is ready, you receive an email confirmation, and the org appears in your list of hub members.
Single Sign-on in the Environment Hub
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, and
Unlimited Editions
Developing, testing, and deploying apps means switching between multiple Salesforce environments
and providing login credentials each time. Single sign-on (SSO) simplifies this process by letting an
Environment Hub user log in to member orgs without reauthenticating. You can set up SSO by
defining user mappings manually, using Federation IDs, or creating a formula.
The Environment Hub supports these SSO methods for matching users.
DescriptionSSO Method
Match users in the Environment Hub to users in a member org
manually. Mapped Users is the default method for SSO user
mappings defined from the member detail page.
Mapped Users
Match users who have the same Federation ID in both the
Environment Hub and a member org.
Federation ID
Match users in the Environment Hub and a member org
according to a formula that you define.
User Name Formula
If you specify multiple SSO methods, they’re evaluated in this order: (1) Mapped Users, (2) Federation ID, and (3) User Name Formula.
The first method that results in a match is used to log in the user, and the other methods are ignored. If a matching user can’t be identified,
the Environment Hub directs the user to the standard Salesforce login page.
Note: SSO doesn’t work for newly added users or for user mappings defined in a sandbox org. Only add users, edit user information,
or define SSO user mappings in the parent org for the sandbox.
Enable SSO for a Member Org
You can enable single sign-on (SSO) to let an Environment Hub user log in to a member org without reauthenticating.
91
Single Sign-on in the Environment HubDesigning and Building Your App
Define an SSO User Mapping
You can manually define a single-sign on (SSO) user mapping between a user in the Environment Hub and a user in a member org.
Before you define a user mapping, enable SSO in the hub member org.
Use a Federation ID or Formula for SSO
You can match an Environment Hub user with a user in a member org using a Federation ID or a user name formula. For either
method, enable SSO in the hub member org first.
Disable SSO for a Member Org
If you want Environment Hub users to reauthenticate when they log in to a member org, you can disable SSO. Disabling SSO doesn’t
remove the user mappings that you’ve defined, so you can always re-enable SSO later.
Enable SSO for a Member Org
USER PERMISSIONS
To set up and configure the
Environment Hub:
•“Manage Environment
Hub”
You can enable single sign-on (SSO) to let an Environment Hub user log in to a member org without
reauthenticating.
1. Log in to the Environment Hub, and then select a member org. If you don’t see any member
orgs, check your list view.
2. Select Enable SSO.
3. Confirm that you want to enable SSO for this org, and then select Enable SSO again.
Define an SSO User Mapping
USER PERMISSIONS
To set up and configure the
Environment Hub:
•“Manage Environment
Hub”
You can manually define a single-sign on (SSO) user mapping between a user in the Environment
Hub and a user in a member org. Before you define a user mapping, enable SSO in the hub member
org.
User mappings can be many-to-one but not one-to-many. In other words, you can associate multiple
users in the Environment Hub to one user in a member org. For example, if you wanted members
of your QA team to log in to a test org as the same user, you could define user mappings.
1. Log in to the Environment Hub, and then select a member org. If you don’t see any member
orgs, check your list view.
2. Go to the Single Sign-On User Mappings related list, and then select New SSO User Mapping.
3. Enter the username of the user that you want to map in the member org, and then look up a user in the Environment Hub.
4. Select Save.
Use a Federation ID or Formula for SSO
USER PERMISSIONS
To set up and configure the
Environment Hub:
•“Manage Environment
Hub”
You can match an Environment Hub user with a user in a member org using a Federation ID or a
user name formula. For either method, enable SSO in the hub member org first.
1. Log in to the Environment Hub, and then select a member org. If you don’t see any member
orgs, check your list view.
2. Go to SSO Settings, and then choose a method.
StepsMethod
Select the checkbox.SSO Method 2 - Federation
ID
92
Single Sign-on in the Environment HubDesigning and Building Your App
StepsMethod
Select the checkbox, and then define a formula. For example, to match
the first part of the username (the part before the “@” sign) with an explicit
domain name, enter:
LEFT($User.Username, FIND("@", $User.Username))
& ("mydev.org")
SSO Method 3 - User Name Formula
3. Select Save.
Disable SSO for a Member Org
USER PERMISSIONS
To set up and configure the
Environment Hub:
•“Manage Environment
Hub”
If you want Environment Hub users to reauthenticate when they log in to a member org, you can
disable SSO. Disabling SSO doesn’t remove the user mappings that you’ve defined, so you can
always re-enable SSO later.
1. Log in to the Environment Hub, and then select a member org. If you don’t see any member
orgs, check your list view.
2. Select Disable SSO.
3. Confirm that you want to disable SSO for this org, and then select Disable SSO again.
Environment Hub Best Practices
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, and
Unlimited Editions
Follow these guidelines and best practices when you use the Environment Hub.
•If you’re an admin or developer, choose the org that your team uses most frequently as your
hub org. If you’re an ISV partner, the Environment Hub is already installed in your Partner Business
Org.
•Set up My Domain for each member org, in addition to the hub org. Because each My Domain
includes a unique domain URL, it’s easier to distinguish between the member orgs that you
use for development, testing, and trials.
•Because each member org is a standard object (of type EnvironmentHubMember), you can
modify its behavior or access it programmatically. For example, you can create custom fields,
set up workflow rules, or define user mappings and enable single sign-on using the API for any
member org.
•Decide on a strategy for enabling SSO access based on your company’s security requirements. Then choose the SSO method (explicit
mapping, Federation ID, or custom formula) that meets your needs.
•SSO doesn’t work for newly added users or for user mappings defined in a sandbox org. Only add users, edit user information, or
define SSO user mappings in the parent org for the sandbox.
•The Environment Hub connected app is for internal use only. Don’t enable it for any profiles. Unless advised by Salesforce, don’t
delete the connected app or adjust its settings.
93
Environment Hub Best PracticesDesigning and Building Your App
Environment Hub FAQ
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited,
and Developer Editions
Answers to common questions about the Environment Hub.
Can I use the Environment Hub in Lightning Experience?
Where do I install the Environment Hub?
Is My Domain required to use the Environment Hub?
No, My Domain isn’t required. But if you don’t set up My Domain, you can’t connect existing
orgs to the Environment Hub or use single sign-on to log in to member orgs. Salesforce
recommends setting up My Domain when you configure the Environment Hub.
Can I install the Environment Hub in more than one org?
Can I enable the Environment Hub in a sandbox org?
What kinds of orgs can I create in the Environment Hub?
How is locale determined for the orgs I create in the Environment Hub?
Are the orgs that I create in the Environment Hub the same as the ones I created in the Partner Portal?
Can an org be a member of multiple Environment Hubs?
Can I disable the Environment Hub?
Can I use the Environment Hub in Lightning Experience?
Yes, both Salesforce Classic and Lightning Experience support the Environment Hub.
Where do I install the Environment Hub?
If you’re an ISV partner, the Environment Hub is already installed in your Partner Business Org.
Otherwise, install the Environment Hub in an org that all your users can access, such as your CRM org. Do not install the Environment
Hub in a Developer Edition org that contains your managed package. Doing so can cause problems when you upload a new package
version or push an upgrade to customers.
Is My Domain required to use the Environment Hub?
No, My Domain isn’t required. But if you don’t set up My Domain, you can’t connect existing orgs to the Environment Hub or use single
sign-on to log in to member orgs. Salesforce recommends setting up My Domain when you configure the Environment Hub.
Can I install the Environment Hub in more than one org?
Yes, but you must manage each Environment Hub independently. Although Salesforce recommends one Environment Hub per company,
several hubs could make sense for your company. For example, if you want to keep orgs that are associated with product lines separate.
Can I enable the Environment Hub in a sandbox org?
No, you can’t enable the Environment Hub in a sandbox org. Enable the Environment Hub in a production org that all your users can
access.
94
Environment Hub FAQDesigning and Building Your App
What kinds of orgs can I create in the Environment Hub?
You can create orgs for development, testing, and trials. ISV partners can also create partner edition orgs with increased limits, more
storage, and other customizations to support app development. If you’re a partner but don’t see partner edition orgs in the Environment
Hub, log a case in the Partner Community.
Expires AfterBest Used ForOrg Type
30 daysTestingGroup Edition
30 daysTestingEnterprise Edition
30 daysTestingProfessional Edition
NeverDeveloping apps and Lightning componentsPartner Developer Edition
1 year, unless you request an extensionRobust testing and customer demosPartner Group Edition
1 year, unless you request an extensionRobust testing and customer demosPartner Enterprise Edition
1 year, unless you request an extensionRobust testing and customer demosPartner Professional Edition
1 year, unless you request an extensionCreating Trialforce templatesTrialforce Source Org
1 year, unless you request an extensionCustomer demosConsulting Partner Edition
How is locale determined for the orgs I create in the Environment Hub?
Your Salesforce user locale determines the default locale of orgs that you create. For example, if your user locale is set to English
(United Kingdom), that is the default locale for the orgs you create. In this way, the orgs you create are already customized for
the regions where they reside.
Are the orgs that I create in the Environment Hub the same as the ones I created in
the Partner Portal?
Yes, the orgs are identical to the ones that you created in the Partner Portal. The Environment Hub uses the same templates, so the orgs
come with the same customizations, such as higher limits and more licenses. You can also use the Environment Hub to create the same
Group, Professional, and Enterprise Edition orgs that customers use. That way, you can test your app against realistic customer
implementations.
Can an org be a member of multiple Environment Hubs?
No, an org can be a member of only one Environment Hub at a time. After you connect an org to the Environment Hub, you must contact
Salesforce Customer Support to break the association.
Can I disable the Environment Hub?
After you install the Environment Hub in an org, you can’t disable it. However, you can hide the Environment Hub from users. Go to
Setup and enter App Menu in to the Quick Find box, and then select App Menu. From the App Menu, you can choose whether to
hide an app or make it visible.
95
Environment Hub FAQDesigning and Building Your App
Considerations for the Environment Hub in Lightning Experience
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited,
and Developer Editions
Be aware of these considerations when creating and managing orgs in the Environment Hub.
List View Limitations
You can’t filter hub members by org expiration date when creating or updating list views in
Lightning Experience. If you have an existing list view that includes org expiration date in its
filter criteria, that list view won’t work in Lightning Experience. To filter hub members by org
expiration date, switch to Salesforce Classic and then use the list view.
Notifications for Package Errors
EDITIONS
Available in: Salesforce
Classic
Accurately track failed package installations, upgrades, and uninstallations in subscriber orgs with
the Notifications for Package Errors feature. Proactively address issues with managed and unmanaged
packages and provide support to subscribers so that they can successfully install and upgrade your
apps.
You can choose to send a notification to an email address in your org when a subscriber’s attempt
to install, upgrade, or uninstall a packaged app fails. To enable this feature, contact your Salesforce
representative.
Errors can happen with these package operations:
•Installation
•Upgrade
•Push upgrade
•Uninstallation
When an installation fails, an email is sent to the specified address with the following details:
•Reason for the failure
•Subscriber org information
•Metadata of the package that wasn’t installed properly
•Who attempted to install the package
This example email is for a package installation that failed because the base package wasn’t installed before the subscriber tried to install
an extension.
On Mon, Jul 13, 2015 at 11:51 AM, NO REPLY <no-reply@salesforce.com> wrote:
The install of your package failed. Here are the details:
Error Message: 00DD00000007uJp: VALIDATION_FAILED [DB 0710 DE1 Pkg1 1.2: A required package
is missing: Package "DB 0710 DE1 Pkg1", Version 1.2 or later must be installed first.]
Date/Time of Occurrence = Mon Jul 13 18:51:20 GMT 2015
Subscriber Org Name = DB 071015 EE 1
Subscriber Org ID = 00DD00000007uJp
Subscriber Org Status = TRIAL
Subscriber Org Edition = Enterprise Edition
96
Considerations for the Environment Hub in Lightning
Experience
Designing and Building Your App
Package Name = DB 0710 DE2 Pkg1
Package ID = 033D000000060EE
Package Namespace = DB_0710_DE2
Package Type = MANAGED
Package Version Name = 1.2
Package Version Number = 1.2
Package Version Id = 04tD00000006QoF
Installer Name = Admin User
Installer Email Address = dburki@salesforce.com
Set the Notification Email Address
Specify which address to email when a package installation, upgrade, or uninstallation fails.
Notifications are sent only for package versions that are uploaded after the address is added. For example, if you upload package version
1.0 and then set the notification address, notifications aren’t sent for failures related to version 1.0. Notifications start when version 2.0
is uploaded.
Also, you can’t change or remove the notification email address for the package after it’s been uploaded.
1. To enable this feature, contact your Salesforce representative.
2. From Setup, enter Packages in the Quick Find box, then select Packages.
3. Click the package name, and then click Edit on the package detail page.
4. Enter the email address to send notifications to, and click Save.
Notifications for Package Errors Configured in a Partner Org
97
Set the Notification Email AddressDesigning and Building Your App
CHAPTER 4 Packaging and Testing Your App
This section contains information on packaging and testing your app during development. The general
procedure is as follows:
In this chapter ...
•About Managed
Packages 1. Create and upload a beta package.
2. Install the beta package in a partner testing organization (Enterprise, Professional or Group Editions
are available). These can be created in the Environment Hub.
•Installing a Package
•Uninstalling a
Package 3. Test the package.
•Installing Managed
Packages using the
API
4. Fix bugs and make changes in your development organization.
5. Repeat these steps until you’re ready to release a managed package.
SEE ALSO:
Creating and Uploading a Beta Package
Installing a Package
•Resolving Apex Test
Failures
•Running Apex on
Package
Install/Upgrade
•Running Apex on
Package Uninstall
•Publishing Extensions
to Managed
Packages
98
About Managed Packages
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: Developer
Edition
Package uploads and
installs are available in
Group, Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
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.
•You must use a Developer Edition organization to create and work with a managed package.
•Managed packages are depicted by the following icons:
–Managed - Beta
–Managed - Released
–Managed - Installed
Tip: 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.
Configure Your Developer Settings
EDITIONS
Available in: Salesforce
Classic 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 configure developer
settings:
•“Customize Application”
To create packages:
•“Create AppExchange
Packages”
To upload packages:
•“Upload AppExchange
Packages”
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:
1. From Setup, enter Packages in the Quick Find box, then select Packages.
2. Click Edit.
Note: This button doesn’t appear if you’ve already configured your developer settings.
3. Review the selections necessary to configure developer settings, and click Continue.
4. Register a namespace prefix.
5. 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.
6. Click Review My Selections.
7. Click Save.
Tip: You may want to specify a License Management Organization (LMO) for your managed
package; to find out more, go to http://sites.force.com/appexchange/publisherHome.
99
About Managed PackagesPackaging and Testing Your App
Register a Namespace Prefix
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: Developer
Edition
Package uploads and
installs are available in
Group, Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
In a packaging context, a namespace prefix is a one to 15-character alphanumeric identifier that
distinguishes your package and its contents from packages of other developers on AppExchange.
Namespace prefixes are case-insensitive. 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.
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, s-controls, and validation rules. For example, if your namespace prefix
is abc and your managed package contains a custom object with the API name, Expense__c, use
the API name abc__Expense__c to access this object using the API. The namespace prefix is
displayed on all component detail pages.
Warning: S-controls stored in the s-control library or the Documents tab that do not use
the Force.com API still function properly after you register a namespace prefix. However,
s-controls stored outside of your organization or s-controls that use the Force.com API to call
Salesforce may require some fine-tuning. For more information, see S-control in the Object
Reference.
Your namespace prefix must:
•Begin with a letter
•Contain one to 15 alphanumeric characters
•Not contain two consecutive underscores
For example, myNp123 and my_np are valid namespaces, but 123Company and my__np aren’t.
To register a namespace prefix:
1. From Setup, enter Packages in the Quick Find box. Under Create, select Packages.
Note: This item is only available in Salesforce Classic.
2. In the Developer Settings panel, click Edit.
Note: This button doesn’t appear if you’ve already configured your developer settings.
3. Review the selections that are required for configuring developer settings, and then click Continue.
4. Enter the namespace prefix you want to register.
5. Click Check Availability to determine if the namespace prefix is already in use.
6. If the namespace prefix that you entered isn’t available, repeat the previous two steps.
7. Click Review My Selections.
8. Click Save.
100
Register a Namespace PrefixPackaging and Testing Your App
Specifying a License Management Organization
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: Developer
Edition
Package uploads and
installs are available in
Group, Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
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 Force.com 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
http://sites.force.com/appexchange/publisherHome.
What are Beta Versions of Managed Packages?
A beta package is an early version of a managed package that is uploaded in a Managed - Beta
state. The purpose of a Managed - Beta package is to allow the developer to test their application
in different Salesforce organizations and to share the app with a pilot set of users for evaluation
and feedback.
Before installing a beta version of a managed package, review the following notes:
•Beta packages can be installed in sandbox or Developer Edition organizations, or test organizations furnished through the Environment
Hub only.
•The components of a beta package are editable by the developer's organization until a Managed - Released package is uploaded.
•Beta versions aren't considered major releases, so the package version number doesn't change.
•Beta packages are not upgradeable. Because developers can still edit the components of a beta package, the Managed - Released
version might not be compatible with the beta package installed. Uninstall the beta package and install a new beta package or
released version. For more information, see Uninstalling a Package on page 111 and Installing a Package on page 108.
Creating and Uploading a Beta Package
USER PERMISSIONS
To create packages:
•“Create AppExchange
Packages”
To upload packages:
•“Upload AppExchange
Packages”
Use the following procedure to create and upload a beta package through the UI. (You can also
upload a package using the Tooling API. For sample code and more details, see the
PackageUploadRequest object in the Tooling API Developer Guide.)
1. Create a package:
a. From Setup, enter Packages in the Quick Find box, then select Packages.
b. Click New.
c. Enter a name for your package. This does not have to be the same name that appears on
AppExchange.
d. From the drop-down menu, select the default language of all component labels in the package.
e. Optionally, in the Notify on Apex Error field, enter the username of the person who should receive an email notification
if an exception occurs in Apex code that is not caught by the code. If you don’t specify a username, all uncaught exceptions
generate an email notification that is sent to Salesforce.
f. Optionally, in the Notify on Packaging Error field, enter the email address of the person who receives an email
notification if an error occurs when a subscriber’s attempt to install, upgrade, or uninstall a packaged app fails. This field appears
only if packaging error notifications are enabled. To enable notifications, contact your Salesforce representative.
101
Specifying a License Management OrganizationPackaging and Testing Your App
g. Optionally, choose a custom link from the Configure Custom Link field to display configuration information to installers.
The custom link displays as a Configure link within Salesforce on the Installed Packages page and package detail page of the
subscriber's organization.
h. Optionally, enter a description that describes the package. You will have a chance to change this description before you upload
it to AppExchange.
i. Optionally, specify a post install script. This is an Apex script that runs in the subscriber organization after the package is installed
or upgraded. For more information, see Running Apex on Package Install/Upgrade on page 113.
j. Optionally, specify an uninstall script. This is an Apex script that runs in the subscriber organization after the package is uninstalled.
For more information, see Running Apex on Package Uninstall on page 117.
k. On the right side of the screen, select the Managed checkbox.
l. Click Save.
2. Optionally, change the API access privileges. By default, API access is set to Unrestricted, but you can change this setting to
further restrict API access of the components in the package.
3. Add the necessary components for your app.
a. Click Add Components.
b. From the drop-down list, choose the type of component.
c. Select the components you want to add.
Note: Some components cannot be added to Managed - Released packages. For a list of packageable components, see
Components Available in Managed Packages on page 21. Also, S-controls cannot be added to packages with restricted
API access.
d. Click Add To Package.
e. Repeat these steps until you have added all the components you want in your package.
Note: Some related components are automatically included in the package even though they might not display in the Package
Components list. For example, when you add a custom object to a package, its custom fields, page layouts, and relationships
with standard objects are automatically included. For a complete list of components, see Components Automatically Added
to Packages on page 35.
4. Optionally, click View Dependencies and review a list of components that rely on other components, permissions, or preferences
within the package. For more information on dependencies, see About Dependencies on page 47. Click Done to return to the
Package detail page.
5. Click Upload.
6. On the Upload Package page, do the following:
a. Enter a Version Name, such as Spring 11 — Beta.
b. Enter a Version Number, such as 1.0. All beta packages use the same version number until you upload a Managed -
Released package.
c. Select a Release Type of Managed - Beta.
Note: Beta packages can only be installed in Developer Edition, sandbox, or test organizations requested through the
Environment Hub, and thus can't be pushed to customer organizations.
d. Optionally, enter and confirm a password to share the package privately with anyone who has the password. Don't enter a
password if you want to make the package available to anyone on AppExchange and share your package publicly.
102
Creating and Uploading a Beta PackagePackaging and Testing Your App
e. Salesforce automatically selects the requirements it finds. In addition, select any other required components from the Package
Requirements and Object Requirements sections to notify installers of any requirements for this package.
f. Click Upload.
You will receive an email that includes an installation link when your package has been uploaded successfully.
Create and Upload a Managed Package
EDITIONS
Available in: Salesforce
Classic 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 enable managed
packages:
•“Customize Application”
To create packages:
•“Create AppExchange
packages”
To upload packages:
•“Download
AppExchange
packages”
Creating a managed package is just as easy as creating an unmanaged package. The only requirement
to create a managed package is that you’re using a Developer Edition organization.
Before creating a managed package:
•Determine if you want to create and upload a managed or unmanaged package.
•Optionally, install the License Management Application (LMA) from
http://sites.force.com/appexchange. 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 on page 99. Your developer settings specify your namespace
prefix on page 100, the Salesforce organization where you install the License Management
Application (LMA), and the unmanaged package you want to convert into a managed package.
Use the following procedure to create and upload a managed package through the UI. (You can
also upload a package using the Tooling API. For sample code and more details, see the
PackageUploadRequest object in the Tooling API Developer Guide.)
This procedure assumes you have already created a namespace and beta package. If you’re uploading
a beta package for testing, see Creating and Uploading a Beta Package on page 101.
1. Create a package:
a. From Setup, enter Packages in the Quick Find box, then select Packages.
b. Click New.
c. Enter a name for your package. This does not have to be the same name that appears on AppExchange.
d. From the drop-down menu, select the default language of all component labels in the package.
e. Optionally, in the Notify on Apex Error field, enter the username of the person who should receive an email notification
if an exception occurs in Apex code that is not caught by the code. If you don’t specify a username, all uncaught exceptions
generate an email notification that is sent to Salesforce.
f. Optionally, in the Notify on Packaging Error field, enter the email address of the person who receives an email
notification if an error occurs when a subscriber’s attempt to install, upgrade, or uninstall a packaged app fails. This field appears
only if packaging error notifications are enabled. To enable notifications, contact your Salesforce representative.
g. Optionally, choose a custom link from the Configure Custom Link field to display configuration information to installers.
The custom link displays as a Configure link within Salesforce on the Installed Packages page and package detail page of the
subscriber's organization.
103
Create and Upload a Managed PackagePackaging and Testing Your App
h. Optionally, enter a description that describes the package. You will have a chance to change this description before you upload
it to AppExchange.
i. Optionally, specify a post install script. This is an Apex script that runs in the subscriber organization after the package is installed
or upgraded. For more information, see Running Apex on Package Install/Upgrade on page 113.
j. Optionally, specify an uninstall script. This is an Apex script that runs in the subscriber organization after the package is uninstalled.
For more information, see Running Apex on Package Uninstall on page 117.
k. On the right side of the screen, select the Managed checkbox.
l. Click Save.
2. Optionally, change the API access privileges. By default, API access is set to Unrestricted, but you can change this setting to
further restrict API access of the components in the package.
3. Add the necessary components for your app.
a. Click Add Components.
b. From the drop-down list, choose the type of component.
c. Select the components you want to add.
Note: Some components cannot be added to Managed - Released packages. For a list of packageable components, see
Components Available in Managed Packages on page 21. Also, S-controls cannot be added to packages with restricted
API access.
d. Click Add To Package.
e. Repeat these steps until you have added all the components you want in your package.
Note: Some related components are automatically included in the package even though they might not display in the Package
Components list. For example, when you add a custom object to a package, its custom fields, page layouts, and relationships
with standard objects are automatically included. For a complete list of components, see Components Automatically Added
to Packages on page 35.
4. Optionally, click View Dependencies and review a list of components that rely on other components, permissions, or preferences
within the package. For more information on dependencies, see About Dependencies on page 47. Click Done to return to the
Package detail page.
5. Click Upload.
6. On the Upload Package page, do the following:
a. Enter a Version Name, such as Spring 12. The version name is the marketing name for a specific release of a package
and allows you to create a more descriptive title for the version than just a number.
b. Enter a Version Number, such as 1.0. For more information on versions, see Upgrading Your App on page 251.
c. Select a Release Type of Managed - Released.
d. Change the Description, if necessary.
e. Optionally, specify a link to release notes for the package. Click URL and enter the details in the text field that appears. This link
will be displayed during the installation process, and on the Package Details page after installation.
Note: As a best practice, this should point to an external URL, so you can make the information available to customers
in advance of the release, and update it independently of the package.
f. Optionally, specify a link to post install instructions for the package. Click URL or Visualforce page and enter the details in the
text field that appears. This link will be displayed on the Package Details page after installation.
104
Create and Upload a Managed PackagePackaging and Testing Your App
Note: As a best practice, this should point to an external URL, so you can update the information independently of the
package.
g. Optionally, enter and confirm a password to share the package privately with anyone who has the password. Don't enter a
password if you want to make the package available to anyone on AppExchange and share your package publicly.
h. Salesforce automatically selects the requirements it finds. In addition, select any other required components from the Package
Requirements and Object Requirements sections to notify installers of any requirements for this package.
i. Click Upload.
7. Once your upload is complete, you can do any of the following.
•Click Change Password link to change the password option.
•Click Deprecate to prevent new installations of this package while allowing existing installations to continue operating.
Note: You cannot deprecate the most recent version of a managed package.
When you deprecate a package, remember to remove it from AppExchange as well. See “Removing Apps from AppExchange”
in the AppExchange online help.
•Click Undeprecate to make a deprecated version available for installation again.
You will receive an email that includes an installation link when your package has been uploaded successfully.
Note:
•When using the install URL, the old installer is displayed by default. You can customize the installation behavior by modifying
the installation URL you provide your customers.
–To access the new installer, append the text &newui=1 to the installation URL.
–To access the new installer with the "All Users" option selected by default, append the additional text &p1=full to the
installation URL.
•If you uploaded from your Salesforce production organization, notify installers who want to install it in a sandbox organization
to replace the “login.salesforce.com” portion of the installation URL with “test.salesforce.com.”
View Package Details
From Setup, enter Packages in the Quick Find box, then select Packages. Click the name of a package to view its details,
including added components, whether it’s a managed package, whether the package has been uploaded, and so on.
The detail page has the following sections:
•Package Details on page 106
•Components on page 107
•Versions on page 107
•Patch Organizations on page 108
From the Package Detail page, you can do any of the following:
•Click Edit to change the package name, custom link that displays when users click Configure, or description.
•Click Delete to delete the package. This does not delete the components contained in the package but the components will no
longer be bundled together within this package.
•Click Upload to upload the package. You will receive an email when the upload is complete.
105
View Package DetailsPackaging and Testing Your App
•Optionally, you can enable, disable, or change the dynamic Apex and API access that components in the package have to standard
objects in the installing organization by using the links next to API Access.
Viewing Package Details
For package developers, the package detail section displays the following package attributes (in alphabetical order):
DescriptionAttribute
The type of access that the API and dynamic Apex that package
components have. The default setting is Unrestricted, which
API Access
means that all package components that access the API have the
same access as the user who is logged in. Click Enable Restrictions
or Disable Restrictions to change the API and dynamic Apex
access permissions for a package.
The name of the developer that created this package, including
the date and time.
Created By
A detailed description of the package.Description
The language used for the labels on components. The default value
is your user language.
Language
The name of the last user to modify this package, including the
date and time.
Last Modified By
The username of the person who should receive an email
notification if an exception occurs in Apex that is not caught by
Notify on Apex Error
the code. If you don’t specify a username, all uncaught exceptions
generate an email notification that is sent to Salesforce. This is only
available for managed packages.
Note: Apex can only be packaged from Developer,
Enterprise, Unlimited, and Performance Edition
organizations.
The email address of the person who receives an email notification
if an error occurs when a subscriber’s attempt to install, upgrade,
Notify on Packaging Error
or uninstall a packaged app fails. This field appears only if packaging
error notifications are enabled. To enable notifications, contact
your Salesforce representative.
The name of the package, given by the publisher.Package Name
The Apex code that runs after this package is installed or upgraded.
For more information, see Running Apex on Package
Install/Upgrade on page 113.
Post Install Script
Indicates whether this is a managed or unmanaged package.Type
The Apex code that runs after this package is uninstalled. For more
information, see Running Apex on Package Uninstall on page 117.
Uninstall Script
106
View Package DetailsPackaging and Testing Your App
Viewing Package Components
For package developers, the Components tab lists every package component contained in the package, including the name and type
of each component.
Click Add to add components to the package.
Note: Some related components are automatically included in the package even though they may not display in the Package
Components list. For example, when you add a custom object to a package, its custom fields, page layouts, and relationships with
standard objects are automatically included. For a complete list of components SalesforceSalesforce automatically includes, see
Components Automatically Added on page 35.
Click View Dependencies to review a list of components that rely on other components, permissions, or preferences within the package.
An entity may include such things as an s-control, a standard or custom field, or an organization-wide setting like multicurrency. Your
package cannot be installed unless the installer has the listed components enabled or installed. For more information on dependencies,
see Understanding Dependencies on page 47. Click Back to Package to return to the Package detail page.
Click View Deleted Components to see which components were deleted from the package across all of its versions.
Viewing Version History
For package developers, the Versions tab lists all the previous uploads of a package.
Click Push Upgrades to automatically upgrade subscribers to a specific version.
Click the Version Number of any listed uploads to manage that upload. For more information, see Managing Versions on page 263.
Note: Push Upgrades is available for patches and major upgrades. Registered ISV partners can request Push Major Upgrade
functionality by logging a case in the Partner Community.
The versions table displays the following package attributes (in alphabetical order):
DescriptionAttribute
Lists the actions you can perform on the package. The possible
actions are:
Action
•Deprecate: Deprecates a package version.
Warning: Users will no longer be able to download
or install this package. However, existing installations
will continue to work.
•Undeprecate: Enables a package version to be installed by
users once again.
The status of the package. The possible statuses are:Status
•Released: The package is Managed - Released.
•Beta: The package is Managed - Beta.
•Deprecated: The package version is deprecated.
The version name for this package version. The version name is
the marketing name for a specific release of a package. It is more
descriptive than the Version Number.
Version Name
107
View Package DetailsPackaging and Testing Your App
DescriptionAttribute
The version number for the latest installed package version. The
format is majorNumber.minorNumber.patchNumber,
Version Number
such as 2.1.3. The version number represents a release of a package.
The Version Name is a more descriptive name for the release.
The patchNumber is generated only when you create a patch.
If there is no patchNumber, it is assumed to be zero (0).
Viewing Patch Development Organizations
Every patch is developed in a patch development organization, which is the organization where patch versions are developed, maintained,
and uploaded. To start developing a patch, you need to create a patch development organization. To do this, see Creating and Uploading
Patches on page 253. Patch development organizations are necessary to permit developers to make changes to existing components
without causing incompatibilities between existing subscriber installations. Click New to create a new patch for this package.
The Patch Organizations table lists all the patch development organizations created. It lists the following attributes (in alphabetical order):
DescriptionAttribute
Lists the actions you can perform on a patch development
organization. The possible actions are:
Action
•Login: Log in to your patch development organization.
•Reset: Emails a new temporary password for your patch
development organization.
The login associated with the patch organization.Administrator Username
The package version number that you are patching.Patching Major Release
Installing a Package
During the development and testing cycle, you might need to periodically install and uninstall packages before you install the next beta.
Follow these steps to install a package.
Pre-Installation
1. In a browser, type in the installation URL you received when you uploaded the package.
2. Enter your username and password for the Salesforce organization in which you want to install the package, and then click the login
button.
3. If the package is password-protected, enter the password you received from the publisher.
Default Installation
Click Install. You’ll see a message that describes the progress and a confirmation message after the installation is complete.
108
Installing a PackagePackaging and Testing Your App
Custom Installation
Follow these steps if you need to modify the default settings, as an administrator.
1. Choose one or more of these options, as appropriate.
•Click View Components. You’ll see an overlay with a list of components in the package. For managed packages, the screen
also contains a list of connected apps (trusted applications that are granted access to a user's Salesforce data after the user and
the application are verified). Review the list to confirm that the components and any connected apps shown are acceptable,
and then close the overlay.
Note: Some package items, such as validation rules, record types, or custom settings might not appear in the Package
Components list but are included in the package and installed with the other items. If there are no items in the Package
Components list, the package might contain only minor changes.
•If the package contains a remote site setting, you must approve access to websites outside of Salesforce. The dialog box lists all
the websites that the package communicates with. We recommend that a website uses SSL (secure sockets layer) for transmitting
data. After you verify that the websites are safe, select Yes, grant access to these third-party websites and click Continue,
or click Cancel to cancel the installation of the package.
Warning: By installing remote site settings, you’re allowing the package to transmit data to and from a third-party website.
Before using the package, contact the publisher to understand what data is transmitted and how it's used. If you have an
internal security contact, ask the contact to review the application so that you understand its impact before use.
•Click API Access. You’ll see an overlay with a list of the API access settings that package components have been granted. Review
the settings to verify they’re acceptable, and then close the overlay to return to the installer screen.
•In Enterprise, Performance, Unlimited, and Developer Editions, choose one of the following security options.
Note: Depending on the type of installation, you might not see this option. For example, in Group and Professional
Editions, or if the package doesn’t contain a custom object, Salesforce skips this option, which gives all users full access.
Install for Admins Only
Specifies the following settings on the installing administrator’s profile and any profile with the "Customize Application"
permission.
–Object permissions—“Read,” “Create,” “Edit,” “Delete,” “View All,” and “Modify All” enabled
–Field-level security—set to visible and editable for all fields
–Apex classes—enabled
–Visualforce pages—enabled
–App settings—enabled
–Tab settings—determined by the package creator
–Page layout settings—determined by the package creator
–Record Type settings—determined by the package creator
After installation, if you have Enterprise, Performance, Unlimited, or Developer Edition, set the appropriate user and object
permissions on custom profiles as needed.
Install for All Users
Specifies the following settings on all internal custom profiles.
–Object permissions—“Read,” “Create,” “Edit,” and “Delete” enabled
–Field-level security—set to visible and editable for all fields
–Apex classes—enabled
109
Installing a PackagePackaging and Testing Your App
–Visualforce pages—enabled
–App settings—enabled
–Tab settings—determined by the package creator
–Page layout settings—determined by the package creator
–Record Type settings—determined by the package creator
Note: The Customer Portal User, Customer Portal Manager, High Volume Customer Portal, Authenticated Website,
Partner User, and standard profiles receive no access.
Install for Specific Profiles...
Enables you to choose the usage access for all custom profiles in your organization. You can set each profile to have full
access or no access for the new package and all its components.
–Full Access—Specifies the following settings for each profile.
•Object permissions—“Read,” “Create,” “Edit,” “Delete,” “View All,” and “Modify All” enabled
•Field-level security—set to visible and editable for all fields
•Apex classes—enabled
•Visualforce pages—enabled
•App settings—enabled
•Tab settings—determined by the package creator
•Page layout settings—determined by the package creator
•Record Type settings—determined by the package creator
–No Access—Specifies the same settings as Full Access, except all object permissions are disabled.
You might see other options if the publisher has included settings for custom profiles. You can incorporate the settings of
the publisher’s custom profiles into your profiles without affecting your settings. Choose the name of the profile settings in
the drop-down list next to the profile that you need to apply them to. The current settings in that profile remain intact.
Alternatively, click Set All next to an access level to give this setting to all user profiles.
2. Click Install. You’ll see a message that describes the progress and a confirmation message after the installation is complete.
Post-Installation Steps
If the package includes post-installation instructions, they’re displayed after the installation is completed. Review and follow the instructions
provided. In addition, before you deploy the package to your users, make any necessary changes for your implementation. Depending
on the contents of the package, you might need to perform some of the following customization steps.
•If the package includes permission sets, assign the included permission sets to your users who need them. In managed packages,
you can't make changes to permission sets that are included in the package, but subsequent upgrades happen automatically. If you
clone a permission set that comes with a managed package or create your own, you can make changes to the permission set, but
subsequent upgrades won't affect it.
•If you’re re-installing a package and need to re-import the package data by using the export file that you received after uninstalling,
see Importing Package Data.
•If you installed a managed package, click Manage Licenses to assign licenses to users.
Note: You can’t assign licenses in Lightning Experience. If you need to assign a license, switch to Salesforce Classic.
•Configure components in the package as required. For more information, see Configuring Installed Packages.
110
Installing a PackagePackaging and Testing Your App
Component Availability After Deployment
Many components have an Is Deployed attribute that controls whether they are available for end users. After installation, all components
are immediately available if they were available in the developer's organization.
For tips on customizing the installed package and components, see Configuring Installed Packages. Installed packages are available to
users in your organization with the appropriate permissions and page layout settings.
Uninstalling a Package
To remove a package:
1. From Setup, enter Installed in the Quick Find box, then select Installed Packages.
2. Click Uninstall next to the package that you want to remove.
3. Select Yes, I want to uninstall... and click Uninstall.
4. After an uninstall, Salesforce automatically creates an export file containing the package data, as well as any associated notes and
attachments. When the uninstall is complete, Salesforce sends an email containing a link to the export file to the user performing
the uninstall. The export file and related notes and attachments are listed below the list of installed packages. We recommend storing
the file elsewhere because it’s only available for a limited period of time after the uninstall completes.
Tip: If you reinstall the package later and want to reimport the package data, see Importing Package Data.
When you uninstall packages, consider the following:
•If you’re uninstalling a package that includes a custom object, all components on that custom object are also deleted. This includes
custom fields, validation rules, s-controls, custom buttons and links, as well as workflow rules and approval processes.
•You can’t uninstall a package whenever any component in the package is referenced by a component that will not get included in
the uninstall. For example:
–When an installed package includes any component on a standard object that another component references, Salesforce prevents
you from uninstalling the package. This means that you can install a package that includes a custom user field and build a
workflow rule that gets triggered when the value of that field is a specific value. Uninstalling the package would prevent your
workflow from working.
–When you have installed two unrelated packages that each include a custom object and one custom object component references
a component in the other, Salesforce prevents you from uninstalling the package. This means that you can install an expense
report app that includes a custom user field and create a validation rule on another installed custom object that references that
custom user field. However, uninstalling the expense report app prevents the validation rule from working.
–When an installed folder contains components you added after installation, Salesforce prevents you from uninstalling the package.
–When an installed letterhead is used for an email template you added after installation, Salesforce prevents you from uninstalling
the package.
•You can’t uninstall a package if a field added by the package is being updated by a background job, such as an update to a roll-up
summary field. Wait until the background job finishes, and try again.
•Uninstall export files contain custom app data for your package, excluding some components, such as documents and formula field
values.
111
Component Availability After DeploymentPackaging and Testing Your App
Installing Managed Packages using the API
You can install, upgrade, and uninstall managed packages using the API, instead of the user interface. Automating these repeated tasks
can help you can work more efficiently and to speed up application development.
To install, upgrade, or uninstall a package, use the standard Metadata API deploy() call with the InstalledPackage metadata
type. The following operations are supported.
•Deploying an InstalledPackage installs the package in the deploying organization.
•Deploying a newer version of a currently installed package upgrades the package.
•Deploying an InstalledPackage using a manifest called destructiveChanges.xml, instead of package.xml,
uninstalls it from the organization.
Note: