Abstract

A package is a bundle of components that make up an application or piece of functionality that you are building. Packages are typically created so that their components can be clustered in a container for code migration, editing in an IDE, or distribution to other companies in the example of AppExchange packages. Packages are completely private to your salesforce instance, unless uploaded and published to AppExchange.

Packages come in two forms: unmanaged and managed. Unmanaged packages can be used for a one-time distribution, like a template. These are ideal for sharing or migrating application templates or code samples. The installer receives an independent copy of the components. Managed packages provide intellectual property protection (the source code of many components is not available, in contrast to unmanaged packages), as well as a way for the package creator to offer upgrades to the package. Managed packages are a great way of releasing applications for sale, and also provide support for license enforcement features.

This article provides an introduction to packaging and distribution on the Force.com Platform. After a simple tutorial showing how to create and distribute an unmanaged package, the article examines the foundational concepts found in packaging, and provides details behind the difference between the two types of packages. The role of AppExchange as a directory service is also explained, as well as its support for test drives and licensing.

A Simple Tutorial

Creating and distributing a simple package really drives some of the key concepts home. This tutorial shows how to create and distribute a particular type of package, called an unmanaged package. We start by creating a simple Apex class, which we then package and distribute. If you have two Developer Edition environments yourself, you can follow along. Alternatively, just read on (it's really pretty simple) and install the package yourself.

For the purposes of this tutorial we're going to package a simple Apex class to upload to AppExchange as a private listing. Here's the source:

public class SimpleClass {

 public void foo() {
   System.debug('foo here');
 }
 
 
 static testmethod void testFoo() {
  SimpleClass a = new SimpleClass();
  a.foo();
 }
}

To get going, log in to your Developer Environment and then go to Setup -> Develop -> Apex Classes to create the class.

Now you're ready to create a package, so navigate to Setup -> Create -> Packages. Hit "New" to start. After providing a name for the package (SimplePackage), you'll be given the opportunity to add package components. Packages are collections of components, and these components range the gamut of the Force.com Platform. For example, you can package an Apex class, a Visualforce page, triggers, email templates, documents and workflow rules (see references at bottom for links to entire list). For this tutorial, click “Add” and select a component type of "Apex Class" and select the SimpleClass defined above. You'll end up with a package definition that looks similar to the following figure.

Pkg 1.jpg

That's it! You can now hit "Upload". After providing a version name (I chose 14), you will have "uploaded" your package. Essentially you've just created an unmanaged package that now sits in the cloud, that others can install. You'll end up with a screen looking something like this:

Pkg 2.jpg

As you can see, this provides an installation link. That same installation link will be emailed to you as well to facilitate distribution of the installation link to people with which you want to share the package.

Click here to access the installation link yourself. After someone clicks the installation link, they'll be asked to enter their credentials, after which they'll be presented with an installation screen:

Pkg 3.jpg

After hitting "Continue" and clicking through the security screens, the package will then be installed directly into your environment.

In other words, if you now browse your Apex Classes, you'll find SimpleClass to be present. Moreover, if you navigate to Setup -> View Installed Packages you'll see that SimplePackage is listed there, which you can very easily uninstall. If you do uninstall it, all associated files will also be uninstalled; in our example this means the Apex class, SimpleClass. More interestingly, the package creator can deprecate the package, even delete it. This won't affect you if you have installed it though--it simply means that nobody else will be able to install it as the installation link will no longer be valid.

Packaging Concepts

Let's now look at packages, packaging and AppExchange in a little more detail. A package typically consists of a number of different components. For example, it may contain user interface components, database components such as objects and triggers, Apex code, page layouts, reports and more. All of these components can be bundled together into what is called a package, for the purposes of distribution and installation. A package also comes in two flavors: unmanaged and managed. The following sections provide details on these concepts.

Package Components and Dependencies

Here is a table of many of the different types of components that can be packaged:

Apex Class Apex Trigger
Custom App Custom Button and Link
Custom Field Definition Custom Home Page
Custom Object Definition Custom Report Type
Custom S-Control 1 Custom Tab Definition
Dashboard Document
Email Alert Email Template
Field Update Folder
Home Page Component Letterhead
Profile Settings Report
Static Resource Task
Visualforce Component Visualforce Page
Workflow Outbound Message Workflow Rule

1 S-Controls have been deprecated and you should use Visualforce instead. Read the S-Control Deprecation article for more information.

The package documentation (PDF) provides a comprehensive list of which components can be packaged, as well as a few caveats (for example, some components can only be packaged on custom objects that you write, not on standard objects.)

A package can range from a simple Apex class to a set of hundreds of these components. Each component may have dependencies, in which case the dependencies are automatically added. For example, if you add a Visualforce page to a package, and that page relies on a custom controller, then the custom controller will be added to the package as well, automatically. Likewise if that automatically added custom controller class had a dependency on another component, that other component will also be added, and so on.

Code Coverage and packages

All packages, whether unmanaged or managed, must have at least 75% cumulative test coverage across all Apex classes and triggers, in order to be deployed. The tutorial in the previous section had the following method defined in the class:

static testmethod void testFoo() {
  SimpleClass a = new SimpleClass();
  a.foo();
}

The testmethod keyword declares that the method is part of the test cases, and as you can see from the code, it instantiates an instance of the class and invokes a method. You would typically add assertions to ensure that expected responses are generated. See An Introduction to Apex for more on Apex and code coverage.

Unmanaged packages

Unmanaged packages are bundles of components that are primarily created to distribute components, together with their source code. For example, the package created in the tutorial was an unmanaged package. If you install the package, not only can you execute the Apex class distributed in that package, but also view the source code of that Apex class.

For all intents and purposes you can think of unmanaged packages as creating a zip and handing it off to someone—you no longer have control over an installation of that package. It is distribution-by-copy. If someone clicks on the install link and installs the package, they get their own copy and that copy is forever independent of the creator of the package. If the creator subsequently deletes or modifies the package, your version remains unaffected. As a consequence of this you can modify or delete your version of the installed package, and its components, as you see fit.

Unmanaged packages are great for template applications and free components that you want to distribute. After installation, everything that was installed as part of the package is open, just as if the package installer had created the components himself.

Namespaces are not used in unmanaged packages. In fact, even if your organization is namespaced, the namespace is removed from all components when it is uploaded as an unmanaged package.

A great feature of packages (both managed and unmanaged) is that you can uninstall them. If you uninstall the package, all the components that were installed as part of the package are removed.

Managed Packages

Managed packages add a whole range of functionality and behavior to packages, including:

  • A package installer (the person clicking on the installation link) will not have access to the source code of many components, including Apex code, installed as part of a managed package. This protects the package owner's intellectual property.
  • A package installer is prevented from making a class of changes to an installed application that would prevent seamless upgrades from occurring.
  • The package owner can offer upgrades to the package, and the package installer can optionally upgrade to the latest version.
  • Installations can be tracked using the License Management Application, allowing the package owner to determine who installed the application, who upgraded the application, and so on.

These features are not available to unmanaged packages. Another way of looking at managed packages are as a closed-source distribution model that supports upgrading, tracking and more—something that is obviously suited to commercial distribution. Think of this as distribution-by-reference. If someone wants to install your package, they install a reference to it and the multi-tenant architecture of the platform handles the rest for you.

AppExchange

A user of your packaged application will be a user of the Force.com platform, so it makes sense for there to be a central directory of applications, making it easy to share, find and install applications with the rest of the salesforce.com community building on the platform. Enter AppExchange, an application directory service from that allows you to browse, install, and share apps and components built for the Force.com platform.

The AppExchange offers a number of features that enhance packaging even further:

  • A directory and search capability, making it easy to locate packages.
  • A ranking system, allowing installers to rate and review packages that they’ve installed.
  • A test-drive feature, letting would-be installers test drive the application before they install it.
  • A license management application can be installed, letting you control which companies have licenses for your application, how many users within a company may use it, and so on.

Managed and unmanaged packages can be placed on AppExchange—though if you are listing applications for commercial purposes it makes sense to use managed packages only.

Metadata API

The Force.com platform provides a rich and powerful metadata model and API. This API encompasses a set of web service methods that provide programmatic access to the configuration and source of your application. Using the metadata API for example, you can remotely access your organization and download all of the source code and configuration that composes your application. You can also use it to create and manipulate these metadata components. For a technical introduction to Force.com metadata, please read An Introduction to Force.com Metadata.

The metadata API is primarily used to migrate changes. For example, you can use the metadata API and the tools that are built around it to migrate changes from a test environment such as a sandbox organization, to a production organization. The API can also be used to facilitate Force.com. For example, the Force.com IDE provides a familiar integrated development environment around your application by using the metadata API.

Though the API does, in a sense, allow you to manipulate and transfer source components, this form of deployment is entirely different from packaging described in this article.

Managed Package in More Detail

Managed packages are created in much the same way as unmanaged packages, by navigating to Setup -> Create -> Packages. However, a namespace needs to be set as well.

A managed package that you produce must live alongside code that someone else may produce; it can, after all, be installed into anyone's organization. As a result, the platform demands that you create a namespace prefix. This prefix distinguishes your package and its contents from those of other developers. It is unique across all organizations, never changes, and is automatically prepended to all components.

For example: say you install a managed package that contains a Visualforce page called MyPage and a controller MyController, which has been placed in the XXX namespace. The Visualforce will then be available at a URL something like:

https://XXX.na6.visual.force.com/apex/MyPage

As a result the controller, an Apex class, will have the namespace prefix and the Visualforce page refers it as "XXX.MyController". The addition of namespace in all components installed with a managed packaged is handled automatically by the installation.

Implications of Managed Packages on Source Code

If someone installs a managed package, they don't get access to all the source code of that package. For example, if the package installs an Apex class, they will not be able to view the source code of that Apex class. Here is a list of factors that should be considered:

  • Apex class source code is completely hidden; unless the Apex class is a global class in which case the global method signatures and variables are exposed.
  • The source of Visualforce pages is not hidden. However, the source cannot be edited.
  • The source of Visualforce Components is hidden.
  • Trigger source code is also hidden.

Hence managed packages provide a strong form of IP protection.

AppExchange in More Detail

Managed and unmanaged packages can be listed on AppExchange. This provides a framework for additional functionality around packaging and distribution, which is summarized in the following sections.

Listings

Your application listing is what appears in the AppExchange and is made up of marketing materials. It is your "store-front" on the AppExchange. Customers can learn about your application by reviewing content such as a datasheet or whitepaper, seeing a demo or test driving the application as well. They can also install your application by clicking the Get It Now button, or, obtain additional information about your application if you choose to have a Learn More button instead.

To learn how to start your listing, please read the Listing Technical Resources article.

Test Drives

Test drives are a way for customers to see your application in action in a controlled environment. You set up the demo and they get to use the application. This allows customers to quickly see how powerful your application is and becomes a great selling feature.

License Management

The License Management Application (LMA) facilitates tracking of installation and upgrades of the managed packages created by your organization. The LMA lets you apply licensing on managed packages built and owned by you so that you can control how many users in a customer organization can access your package and for how long.

LMA is itself an application that can be found on AppExchange. See the License Management production documentation for full details.

Summary

This article describes how the Force.com Platform provides a number of options for packaging and distributing applications. Unmanaged packages can be quickly and easily created, to bundle together components that you want to distribute in an unmanaged fashion, by-copy. Managed packages provide a by-reference functionality. With managed packages you, the package creator, have some control over the package, the intellectual property in the package and its use. The AppExchange provides a convenient marketplace for packages, and the license management application provides a way for you to tightly control the use of a packaged application by another organization.

References