Force.com Enterprise Architecture: Architect and deliver packaged Force.com applications that cater to enterprise business needs, Second Edition

Several Salesforce organizations are required to develop, package, and test your application. You can sign up for these organizations at https://developer.salesforce.com/. Though in due course, as your relationship with Salesforce becomes more formal, you will have the option of accessing their Partner Portal website to create organizations of different types and capabilities. We will discuss this in more detail later.

It's a good idea to have some kind of naming convention to keep track of the different organizations and logins. Use the following table as a guide and create the following organizations via https://developer.salesforce.com/. As stated earlier, these organizations will be used only for the purposes of learning and exploring throughout this book:

The following are other organization types that you will eventually need in order to manage the publication and licensing of your application. However, they are not needed to complete the chapters in this book:

Typically, the LMO and APO can be the same as your primary Salesforce production org, which allows you to track all your leads and future opportunities in the same place. This leads to the rule of APO = LMO = production org. Though neither of them should be your actual developer or test orgs, you can work with Salesforce support and your Salesforce account manager to plan and assign these orgs.

For this book, we will use the world of Formula 1 motor car racing as the basis for a packaged application that we will build together. Formula 1 is, for me, the motor sport that is equivalent to enterprise applications software, due to its scale and complexity. It is also a sport that I follow. My knowledge of both of these fields helped me when building the examples that we will use.

We will refer to our application as FormulaForce throughout this book, though please keep in mind Salesforce's branding policies when naming your own application, as they prevent the use of the word "Force" in the company or product titles.

This application will focus on the data collection aspects of the races, drivers, and their many statistics, utilizing platform features to structure, visualize, and process this data in both historic and current contexts.

For this chapter, we will create some initial Custom Objects and fields, as detailed in the following table. Do not worry about creating any custom tabs just yet. You can use your preferred approach to create these initial objects. Ensure that you are logged in to your packaging org (we will use the development org later in this book).

The following screenshot shows the preceding objects within the Schema Builder tool, available under the Setup menu:

A package is a container that holds your application components, such as Custom Objects, Apex code, Apex triggers, Visualforce pages, Lightning Components, and so on. This makes up your application. While there are other ways to move components between Salesforce orgs, a package provides a container that you can use for your entire application or deliver optional features by leveraging the so-called extension packages.

There are two types of packages—managed and unmanaged. Unmanaged packages result in the transfer of components from one org to another; however, the result is as if those components had been originally created in the destination org, meaning that they can be readily modified or even deleted by the administrator of that org. Furthermore, they are not upgradable, and are not particularly ideal from a support perspective. Moreover, the Apex code that you write is also visible for all to see, so your intellectual property is at risk.

Packages are created in your packaging org. There can be only one managed package being developed in your packaging org (though additional unmanaged packages are supported, it is not recommended to mix your packaging org with them). You can also install other dependent managed packages and reference their components from your application. The steps to be performed are discussed in the following sections:

Setting your package namespace

An important decision when creating a managed package is the namespace; this is a prefix applied to all your components (Custom Objects, Visualforce pages, Lightning Components, and so on) and is used by developers in subscriber orgs to uniquely distinguish between your packaged components and others, even those from other packages. The namespace prefix is an important part of the branding of the application since it is implicitly attached to any Apex code or other components that you include in your package.

It can be up to 15 characters, though I personally recommend that you keep it to less than this, as it becomes hard to remember and leads to frustrating typos if you make it too complicated. I would also avoid underscore characters. It is a good idea to have a naming convention if you are likely to create more managed packages in the future (in different packaging orgs). The following is the format of an example naming convention:

[company acronym - 1 to 4 characters][package prefix 1 to 4 characters]

For example, the ACME Corporation's Road Runner application might be named acmerr.

When the namespace has not been set, the Packages page (accessed under the Setup menu under the Create submenu) indicates that only unmanaged packages can be created. Click on the Edit button to begin a small wizard to enter your desired namespace. This can only be done once and must be globally unique (meaning it cannot be set in any other org), much like a website domain name.

Tip

Assigning namespaces

For the purposes of following this book, please feel free to make up any namespace you desire, for example, fforce{yourinitials}. Do not use one that you may plan to use in the future, since once it has been assigned, it cannot be changed or reused.

The following screenshot shows the Packages page:

Once you have set the namespace, the preceding page should look like the following screenshot, with the difference being that it is now showing the namespace prefix that you have used and that managed packages can now also be created. You are now ready to create a managed package and assign it to the namespace.

Creating the package and assigning it to the namespace

Click on the New button on the Packages page and give your package a name (it can be changed later). Be sure to tick the Managed checkbox as well. Click on Save and return to the Packages page, which should now look like the following:

Adding components to the package

In the Packages page, click on the link to your package in order to view its details. From this page, you can manage the contents of your package and upload it. Click on the Add button to add the Custom Objects created earlier in this chapter. Note that you do not need to add any custom fields—these are added automatically.

The following screenshot shows broadly what your Package Detail page should look like at this stage:

When you review the components added to the package, you will see that some components can be removed while other components cannot be removed. This is because the platform implicitly adds some components for you, as they are dependencies. As we progress through this book, adding different component types, you will see this list automatically grow in some cases, and in others, we must explicitly add them.

Packages can have dependencies on platform features and/or other packages. You can review and manage these dependencies through the usage of the Package Detail page and the use of dynamic coding conventions, as described here.

While some features of Salesforce are common, customers can purchase different editions and features according to their needs. Developer Edition organizations have access to most of these features for free. This means that as you develop your application, it is important to understand when and when not to use those features (this is done in order to avoid unwanted dependencies that might block or inhibit the adoption of your application).

By default, when referencing a certain Standard Object, field, or component type, you will generate a prerequisite dependency on your package, which your customers will need to have before they can complete the installation. Some Salesforce features, for example Multi-Currency or Chatter, have either a configuration or, in some cases, a cost impact to your users (different org editions). Carefully consider which features your package is dependent on.

Most of the feature dependencies, though not all, are visible via the View Dependencies button on the Package Detail page (this information is also available on the Upload page, allowing you to make a final check). It is good practice to add this check into your packaging procedures to ensure that no unwanted dependencies have crept in. Clicking on this button for the package that we have been building in this chapter so far confirms that there are no dependencies.

For dependencies that are not shown, it is a good idea to make sure that the features enabled for your testing orgs are clear, thus any other dependencies will show during installation or further testing.

Later in this book, we will be discussing Lightning Components. If you're packaging these, you will be implicitly imposing the need for your customers to utilize the Salesforce My Domain feature. This is not enforced at installation time, so it is an optional dependency. However, users will not be able to use your packaged Lightning Components without first enabling and configuring My Domain.

Uploading the release and beta packages

Once you have checked your dependencies, click on the Upload button. You will be prompted to give a name and version to your package. The version will be managed for you in subsequent releases. Packages are uploaded in one of two states, beta or release, as described shortly.

We will perform a release upload by selecting the Managed - Release option from the Release Type field, so make sure you are happy with the objects created in the earlier section of this chapter, as they cannot easily be changed after this point.

Once you are happy with the information on the screen, click on the Upload button once again to begin the packaging process. Once the upload process completes, you will see a confirmation page as follows:

Packages can be uploaded in one of two states, as described here:

• Release: Release packages can be installed into subscriber production orgs and can also provide an upgrade path from previous releases. The downside is that you cannot delete the previously released components, or change certain things, such as a field's type. Changes to the components that are marked global, such as Apex code and Visualforce components, are also restricted. While Salesforce is gradually enhancing the platform to provide the ability to modify certain released aspects, you need to be certain that your application release is stable before selecting this option.

• Beta: Beta packages cannot be installed into subscriber production orgs; you can install only into Developer Edition (such as your testing org), sandbox, or Partner Portal created orgs. Also, Beta packages cannot be upgraded once installed; this is the reason why Salesforce does not permit their installation into production orgs. The key benefit is in the ability to continue to change new components of the release to address bugs and features relating to user feedback.

Tip

The ability to delete previously-published components (uploaded within a release package) is, at the time of writing this book, in pilot. It can be enabled by raising a support case with Salesforce Support. Once you have understood the full implications, they will enable it.

At this stage in the book, we have simply added some Custom Objects, so the upload should complete reasonably quickly. Note that what you're actually uploading to is AppExchange, which will be covered in the following sections.

Tip

If you want to protect your package, you can provide a password (this can be changed afterwards). The user performing the installation will be prompted for it during the installation process.

The Salesforce Partner Program has many advantages. The first place to visit is https://partners.salesforce.com/. You will want to focus on the areas of the site relating to being an Independent Software Vendor (ISV) partner. From here, you can click on Join Now. It is free to join, though you will want to read through the various agreements carefully, of course.

Once you wish to start listing a package and charging users for it, you will need to arrange billing details for Salesforce to take the various fees involved. While this book is not equipped to go into the details, do pay careful attention to the Standard Objects used in your package, as this will determine the license type required by your users and the overall cost to them, in addition to your charges.

Obviously, Salesforce would prefer your application to use as many features of the CRM application as possible, which may also be beneficial to you as a feature of your application, since it's an appealing immediate integration not found on other platforms, such as the ability to instantly integrate with accounts and contacts.

If you're planning on using Standard Objects, and are in doubt about the costs (as they do vary depending on the type), you can request a conversation with Salesforce to discuss this; this is something to keep in mind in the early stages.

Make sure, when you associate a Salesforce user with the Partner Community, you utilize a user that you use daily (known as your Partner Business Org user) and not one from a development or test org. Once you have completed the signup process, you will gain access to the Partner Community. The following screenshot shows what the current Partner Community home page looks like. From here, you can access many useful services:

This is your primary place to communicate with Salesforce and access additional materials and announcements relevant to ISVs, so do keep checking often. You can raise cases and provide additional logins to other users in your organization, such as other developers who may wish to report issues or ask questions.

Getting the best out of the Partner Community

It's worth taking some time to review the content and facilities in the Partner Community. Some of the key areas to take a look at are listed as follows:

• Education and Trailhead: This allows you to monitor the progress of other users in your organization on Trailhead. Trailhead is Salesforce's way of learning while doing. Users read about new technologies or development approaches and are then asked to perform some challenges to validate their understanding. They are awarded badges, as part of a gamification system. Using this tab, you can see who has the most badges!

• Featured Groups: This page, under More, allows you quick access to a number of Salesforce-managed Chatter groups. A key group is the Partner Alerts group, I would strongly recommend you set up an E-mail digest for this group. Only Salesforce posts to this group, so a per-post digest level is tolerable and keeps you informed without having to log in to the community.

• Support: This is, of course, the place you go to raise cases with Salesforce. As you raise cases, the UI automatically attempts to search for known issues or support articles that might help answer your questions. You can also report and filter on open cases here.

• Publishing: This page allows you to list your creations on the Salesforce AppExchange site. Later sections in this chapter cover this in more detail.

• Partner Alerts: Partner Alerts are critical to keeping on top of changes to the service that could affect your development process and/or your customers. These might range from critical fixes, security improvements, or changes in behavior you need to be prepared for. Although rare, you may be asked to make changes to your solution by a certain deadline to ensure your users are not impacted.

There are many Chatter groups shown in the Featured Groups page in the Partner Community. Review them all and set up E-mail digests to help keep you informed without having to manually log in and check through this page each time.

Salesforce provides a website referred to as AppExchange, which lets prospective customers find, try out, and install applications built using Force.com. Applications listed here can also receive ratings and feedback. You can also list your mobile applications on this site as well.

Once your package is known to AppExchange, each time you click on the Upload button on your released package (as described previously), you effectively create a private listing. Private listings are not visible to the public until you decide to make them so. It gives you the chance to prepare any relevant marketing details and pricing information while final testing is completed. Note that you can still distribute your package to other Salesforce users or even early beta or pilot customers without having to make your listing public.

In order to start building a listing, you need to log in to Partner Community and click the Publishing tab in the header. This will present you with your Publishing Console. Here, you can link and manage Organizations that contain your Packages, create Listings and review Analytics regarding how often your listings are visited.

Select the Publishing Console option from the menu, then click on the Create New Listing button and complete the steps shown in the wizard to associate the packaging org with AppExchange; once completed, you should see it listed.

It's really important that you consistently log in to AppExchange using your APO user credentials. Salesforce will let you log in with other users. To make it easy to confirm, consider changing the user's display name to something like MyCompany Packaging.

Although it is not a requirement to complete the listing steps, unless you want to try out the process yourself to see the type of information required. You can delete any private listings that you created after you complete this book.

When you uploaded your package earlier in this chapter, you will receive an e-mail with a link to install the package. If not, review the Versions tab on the Package Detail page in your packaging org. Ensure that you're logged out and click on the link. When prompted, log in to your testing org. The installation process will start. A reduced screenshot of the initial installation page is shown in the following screenshot; click on the Continue button and follow the default installation prompts to complete the installation:

Package installation covers the following aspects (once the user has entered the package password, if one was set):

When the installation is complete, navigate to the Installed Packages menu option under the Setup menu. Here, you can see the confirmation of some of your package details, such as namespace and version, as well as any licensing details, which will be discussed later in this chapter.

<project name="FormulaForce" 
   xmlns:sf="antlib:com.salesforce" basedir=".">

  <!--  Downloaded from Salesforce Tools page under Setup -->
  <typedef 
    uri="antlib:com.salesforce" 
    resource="com/salesforce/antlib.xml" 
    classpath="${basedir}/lib/ant-salesforce.jar"/>

  <!-- Import macros to install/uninstall packages -->
 <import file="${basedir}/lib/ant-salesforce.xml"/>
  <target name="package.installdemo">
 
    <uninstallPackage 
       namespace="yournamespace"   
       username="${sf.username}" 
       password="${sf.password}"/> 
    <installPackage
       namespace="yournamespace"version="1.0"
       username="${sf.username}"
       password="${sf.password}"/>
  </target>
</project>

ant package.installdemo
							-Dsf.username=testorgusername
							-Dsf.password=testorgpasswordtestorgtoken

Once you have completed the security review, you are able to request by raising a support cases via the Partner Portal to have access to the LMA. Once this is provided by Salesforce, use the installation URL to install it like any other package into your LMO.

The following screenshot shows the main tabs of the License Management Application once installed:

In this section, I will use a package that I already own and have already taken through the process to help illustrate the steps that are involved. For this reason, you do not need to perform these steps.

After completing the installation, return to AppExchange and log in. Then, locate your listing in Publisher Console under Uploaded Packages. Next to your package, there will be a Manage Licenses link. After clicking on this link for the first time, you will be asked to connect your package to your LMO org. Once this is done, you will be able to define the license requirements for your package.

The following example shows the license for a free package with an immediately active license for all users in the subscriber org:

In most cases regarding packages that you intend to charge for, you would offer a free trial rather than setting the license default to active immediately. For paid packages, select a license length, unless it's a one-off charge, and then select the license that does not expire. Finally, if you're providing a trial license, you need to consider carefully the default number of seats (users); users may need to be able to assign themselves different roles in your application to get the full experience.

If you configure a number of seats against the license, then the Manage Licenses link will be shown on the Installed Packages page next to your package. The administrator in the subscriber org can use this page to assign applicable users to your package. The following screenshot shows how your installed package looks to the administrator when the package has licensing enabled:

Note that you do not need to keep reapplying the license requirements for each version you upload; the last details you defined will be carried forward to new versions of your package until you change them. Either way, these details can also be completely overridden on the License page of the LMA application.

The Licenses tab and managing customer licenses

The Licenses tab provides a list of individual license records that are automatically generated when the users install your package into their orgs. Salesforce captures this action and creates the relevant details, including Lead information. This also contains the contact details of the organization and person who performed the install, as shown in the following screenshot:

From each of these records, you can modify the current license details to extend the expiry period or disable the application completely. If you do this, the package will remain installed with all of its data. However, none of the users will be able to access the objects, Apex code, or pages, not even the administrator. You can also re-enable the license at any time. The following screenshot shows the License Edit section:

The Subscribers tab

The Subscribers tab lists all your customers or subscribers (it shows their Organization Name from the company profile) that have your packages installed (only those linked via AppExchange). This includes their Organization ID, Edition (Developer, Enterprise, or others), and also the type of instance (sandbox or production).

The Subscriber Overview page

When you click on Organization Name from the list in this tab, you are taken to the Subscriber Overview page. This page is sometimes known as the Partner Black Tab. This page is packed with useful information, such as the contact details (also seen via the Leads tab) and the login access that may have been granted (we will discuss this in more detail in the next section), as well as which of your packages they have installed, their current licensed status, and when they was installed. The following is a screenshot of the Subscriber Overview page:

Once your package has completed the security review, additional functionality for supporting your customers is enabled. Specifically, this includes the ability to log in securely (without exchanging passwords) to their environments and debug your application. When logged in in this way, you can see everything the user sees, in addition to extended debug logs that contain the same level of detail as they would in a developer org.

First, your customer enables access via the Grant Account Login page. This time, however, your organization (note that this is the Company Name as defined in the packaging org under Company Profile) will be listed as one of those available in addition to Salesforce Support. The following screenshot shows the Grant Account Login page:

Next, you log in to your LMO and navigate to the Subscribers tab as described. Open Subscriber Overview for the customer, and you should now see the link to Login as that user. From this point on, you can follow the steps given to you by your customer and utilize the standard Debug Logs and Developer Console tools to capture the debug information you need. The following screenshot shows a user who has been granted login access via your package to their org:

Salesforce has started to expose information relating to the usage of your package components in the subscriber orgs since the Spring "14 release of the platform. This enables you to report what Custom Objects and Visualforce pages your customers are using and, more importantly, those they are not. This information is provided by Salesforce and cannot be opted out of by the customer.

This facility needs to be enabled by Salesforce Support. Once enabled, the MetricsDataFile object is available in your production org and will receive a data file periodically that contains the metric's records. The Usage Metrics Visualization application can be found by searching on AppExchange, and can help with visualizing this information.

Large enterprise applications often require some consultation with customers to tune and customize to their needs after the initial package installation. If you wish to provide trial versions of your application, Salesforce provides a means to take snapshots of the results of this installation and setup process, including sample data.

You can then allow prospective users who visit your AppExchange listing, or your website to sign up to receive a personalized instance of a Salesforce org based on the snapshot you made. The potential customers can then use this to fully explore the application for a limited time, until they sign up as a paying customer. Such orgs will eventually expire when the Salesforce trial period ends for the org created (typically 14 days). Thus, you should keep this in mind when setting the default expiry on your package licensing.

The standard approach is to offer a web form for the prospective user to complete in order to obtain the trial. Review the Providing a Free Trial on your Website and Providing a Free Trial on AppExchange sections of the ISVforce Guide for more on this.

You can also consider utilizing the Signup Request API, which gives you more control over how the process is started and the ability to monitor it, such that you can create the lead records yourself. You can find out more about this in the Creating Signups using the API section in the ISVforce Guide. As a more advanced option, if you are an ISV with an existing application and wish to utilize Salesforce.com as a backend service, you can use this API to completely create and manage orgs on their behalf. Review the Creating Proxy Signups for OAuth and the API Access section in the ISVforce Guide for more information on this.

Alternatively, if the prospective user wishes to try your package in their sandbox environment, for example, you can permit them to install the package directly, either from AppExchange or from your website. In this case, ensure that you have defined a default expiry on your package license, as described earlier. In this scenario, you or the prospective user will have to perform the setup steps after installation.

Finally, there is a third option called Test Drive, which does not create a new org for the prospective user on request, but does require you to set up an org with your application, preconfigure it, and then link it to your listing via AppExchange. Instead of the users completing a signup page, they click on the Test Drive button on your AppExchange listing. This logs them in to your test drive org as read-only users. Because this is a shared org, the user experience and features you can offer to users is limited to those that mainly read information. I recommend that you consider Trialforce over this option, unless there is a really compelling reason to use it.

This chapter has given you a practical overview of the initial package creation process through installing it into another Salesforce organization. While some of the features discussed cannot be fully exercised until you're close to your first release phase, you can now head to development with a good understanding of how early decisions, such as references to Standard Objects, are critical to your licensing and cost decisions.

It is also important to keep in mind that, while tools such as Trialforce help automate the setup, this does not apply to installing and configuring your customer environments. Thus, when making choices regarding configurations and defaults in your design, keep in mind the costs to the customer during the implementation cycle.

Make sure you plan for the security review process in your release cycle (the free online version has a limited bandwidth) and ideally integrate it into your CI build system (a paid facility) as early as possible, since the tool not only monitors security flaws but also helps report breaches in best practices, such as lack of test asserts and SOQL or DML statements in loops.

In the following chapters, we will start exploring the engineering aspects of building an enterprise application as we build upgrades on the package created in this chapter, allowing us to better explore how the platform supports incremental growth of your application.