Packages

Settings > Administration > Global Resources > Packages

A package is a collection of objects, applications, and other platform resources.

1 About Packages

Packaging provides the ability to deploy fully-featured solutions with seamless distribution to platform Tenants. (Tenants who have installed such a package are deemed to be Package Subscribers. The user who does the installation is called the Package Installer.)

Publishers can bundle all elements of the LongJump Platform into custom Packages, which deliver customized business solutions to Package Subscribers.

Tenants can create and publish packages for internal use, or for wider distribution.

How it Works

1. Platform elements and applications are Packaged and Published.
2. They can then be submitted for approval
3. Approved packages become part of the Application Catalog
4. Tenants can then install the published package.

Alternatively:

• A publisher can give tenants a link they can use to install the package, without having to put it into the catalog first.
• ISVs and MSPs can do an automated Deploy of Packages to multiple tenants

1.1 Package Items

The following platform elements can be selected for inclusion in a Package as package items. When selected, the dependent elements shown in the table are automatically included. (Things that are not dependent are shown as excluded.)

1.1.1 Standard Dependencies

Platform Element	Dependent Elements
Application	Includes Custom Objects Includes Web Tabs Includes Application Information settings Includes role-based Workspace Display Order for objects Includes role-based Default View Preferences for objects Includes Sidebars and Sidebars Assignments
Objects (Custom Objects and Built-in or CRM objects)	Includes all customizable options Excludes Reports and Web Forms Excludes data
Object Data and other Data (Package Data)
Reports
Component
Classes (includes user-created classes)
Pages
Static Resources
Web Tabs (includes Components, Pages, or Widgets, if available)
Roles
Teams
Data Sharing Policies	Includes Teams and Roles involved Includes Child Teams if the Include Child Teams option is selected for that team
Mapping Profiles
Translation Workbench	Includes localized labels and items
Sites	Includes Pages

1.1.2 Special Dependencies

When the following elements are added to a package, the listed items are added as dependencies:

Opportunity

Price Book and Product are added as dependencies

Product

Price Book is added as dependency

Price Book

Product is added as a dependency

Campaign

List and List member are added as dependencies

Lists

List member is added as a dependency

Data Sharing Policies

Roles and Teams included as dependencies

• If the Include Child Teams checkbox is enabled, the child teams of the selected teams in the Data Sharing Policy are added as dependencies

Objects in a Master-Detail relationship

Note: The "Master-Detail relationship" option on a Lookup field has been deprecated. This section is provided for legacy objects that have a Lookup field for which that option has been selected. Learn more: Master-Detail relationships If a Detail object is added to a Package, the Master object is added (automatically) as a dependent object If a Master object is added to a Package and if that Master object includes any Rollup Summary Fields, then the Detail object is added (automatically) as a dependent object When a Tenant installs a Package, the Rollup Summary Fields limit defined in Manage Tenant Capabilities is honored If the limit is exceeded, the installation process will stop and cannot proceed In order to complete the installation, delete existing Rollup Summary Fields to reduce the total number to within the defined limit After packaging, do not add or remove any Master-Detail relationships; doing so may cause unexpected results and/or loss of data

1.2 Package Considerations

• To publish an application, include it as part of a Package, and then publish the package. Application components are automatically added to the package.

• The components contained in a locked package cannot be modified. So new fields cannot be added to an object, for example, and existing fields cannot be modified.

• The components of an unlocked can be modified, with both additions and changes. Additions are preserved during an upgrade. Changes are overwritten. For example:

• If a Data Policy is added to a package object after installation, that Data Policy is preserved.
• If the package object contains a Data Policy, and that Data Policy is modified after installation, the modifications are overwritten by the next upgrade (assuming that it still contains that Data Policy).
• Similarly for additions and modifications to Forms, Validations, and other aspects of the package object.

Notes:

• If a field expected by such an addition no longer exists, an error will occur when the field is referenced.
• If the field is "retired" rather than deleted (by changing it's label and using the old label on a different field, then an added item like a Data Policy that depends on the field would still work, but could deliver inaccurate results.

• Given those considerations, anyone who is in a role which allows them to modify an unlocked package needs to know what the package contains and know that, while any additions will be preserved, any changes will be overwritten at the next upgrade.

• When you add an item like a field to an object which is part of an installed package (and which might later be upgraded), a unique identifying number is appended--so there is no chance that a future upgrade will overwrite your addition.

Exception: If you are in a development Sandbox, working on a package imported from another Sandbox, your additions are seamless. No identifiers are appended.

• If Versioning has been enabled in the installer's database, all of the versioned items are added as "checkout" items (items that must be checked out before they can be modified).

• If a package element is checked out, it cannot be added to a package until it is committed (checked in)

• The names of Fields and Objects created cannot match the name of any Package element. If there is a conflict, Package installation will fail. To succeed, either the Publisher or Subscriber will need to rename the conflicting item(s).

• To include Package Data, you must Create a Data Handler class and then Configure Package Data, so that data can be selected as part of the packaging process.
• Permissions Considerations:
  • When roles are included in a package:
    • Any permissions they contain for objects present in the package are carried over to the subscriber's instance of the platform.
    • Any administrative permissions they define are also carried over.
    • No other permissions are carried over.
  • When a user installs a package that contains role definitions:
    • The user is prompted to assign users to the new roles.
    • If the user is re-installing, the user can choose to override, ignore, or merge permissions for the new roles. (Installation documentation should instruct the user on the preferred course of action.) The choices are:
    • Override - Overwrite the existing role definition.
    • Ignore - Leave the existing role untouched.
    • Merge (the default) - form a union of existing role permissions and the role permissions defined in the package.
  • If a package does not include any Roles:
    • The package installer is shown a list of existing Roles defined in the tenancy.
    • The installer can select the Roles which will have access to the objects included in the package.
    • All selected roles get Create, Delete, and View permissions for records owned by the user, and View permissions for records owned by other team members.

• When installing a Package that includes Sites, these fields are automatically populated:

• Login As User for Unauthenticated Access field is populated as the user who is logged in
• User Web Adress is BLANK

Note: When a package is reinstalled, these fields retain the values configured by the Package Subscriber.

1.3 Package Limitations

These package items have the following limitations:

Report

Only reports in folders that are "Visible to Everyone" or "Visible to {someRole}" can be added to a package. Reports in folders that that are visible to specific users or teams cannot be added. (The Role needs to be added to the package, as well, unless it is sure to be on the installer's system, for example by virtue of being in a package that this one depends on.)
Learn more: About Report Folders

Custom Object Views

Only views with the "Visible to Everyone" control (or visible to selected roles) can be added to a package

Users

Not included in packages, and must be re-created in the new instance

2 Working with Packages

Users that have the Manage Packages permission can create, modify or delete Packages

2.1 Package Attributes

When you open a package, some sections always appear. Others only appear when the package is published:

2.1.1 Package Information

Basic information about the package, including:

• Package ID - This ID is the package record ID. It's used when downloading a package, and in APIs that manipulate package contents.

2.1.2 Subscription Details

This section appears only when the package has been published. It contains:

• Installation Link - The link subscribers can use to install the package.

Important: The value that appears in the URL's id query parameter is the package installation ID. That value is used in APIs that deploy and install packages.

2.1.3 Items

The list of items that were chosen for inclusion in the package. Generally consists of an application, but may also consist of objects, classes, and other application elements.

2.1.4 Item Dependencies

Objects, classes, and other application elements that are required by the items that were chosen.

2.1.5 Package Dependencies

Other packages that are required for this package to run.

2.1.6 Revision Details

A list of up to five of the most recent package versions. Each item in the list displays:

Version number

The number assigned to the package when published.

Version notes

Any notes that were entered for the package when published.

Publication Date

The date and time the package was published.

Catalog Status

• Submitted - The package was submitted for inclusion in the Service Provider's catalog, but has not yet been approved.
• Approved - The package was approved by the Service Provider. It should now appear in the Service Provider's catalog. (That is a two-step process, so it is normal for there to be a small delay between approval and appearance in the catalog.)

Considerations

• Only the most recent 5 versions are shown in the list, unless a version was submitted for inclusion in the Service Provider's catalog. That version is always retained in the list, until supplanted by a newer version.
• Only one version of a package appears in the catalog.
• A new version of a package is created does not replace the existing version in the catalog until the new version has been submitted and approved.
• In the rare case that a new version of package is published before a submitted version is approved, the status of the original version changes from Submitted to (none). (In the Catalog Information page, click [Save and Submit] to send the new version for approval.)
• If a submission is disapproved by the Service Provider, an email is sent to the submitter, and the Catalog Status reverts from Submitted back to (none).
• When a submission is approved, package revisions and edits to the catalog information do not affect the existing catalog entry, until they are submitted and approved.
• When a package is re-published, the aggregate user rating for the previous version is transferred to the new one.

2.2 Create a Package

1. Go to Settings > Administration > Global Resources > Packages
2. Click [New Package] and enter the following information:

   Name

   Name of the Package (this name appears in the Catalog)

   Description

   Description of the Package

   Locked

   To Lock the package, click the checkbox icon

   Learn more About Locked and Unlocked Packages

3. Click [Save]

2.3 Add Items to a Package

1. In the Related Information section, click [Add Item] to select items for the package

2. Choose the Item Type from the list of things you can include

If Package Data has been configured, the Data Handlers for configured objects will also appear in this list. (More on that subject in a moment.)

Learn more: Package Items

3. Click the checkbox icon for each item you want to include in the package

4. Click [Add to Package]

Continue adding until the package contains the desired items.

Note: For any object that has a Workflow, any designated "Specific User" decision makers will be removed from the package, since those users will not exist in the Package Installer's system. Ideally then, ensure that no state in the Workflow has only "Specific User" decision makers. (Use roles instead.) If any states do designate specific users, warn installers that they will need to specify an owner for that state.

2.3.1 Adding Package Data Items

To add Package Data:

1. Choose Add Item > Item Type, and choose the item that corresponds to the data in that object.
   For example, Zip Map Data.
   A pane appears that lets you specify the data elements to include.
2. When the data-item selection appears, select All at the top left of the pane to add everything, or else select and deselect individual data items.
3. Click [Add to Package]

Note: It is possible for there to be package data that is not part of an object. When object-data is included, it is also possible that the target-object is expected to exist on the Package Installer's system. What happens is up to the Data Handler, so object definitions are not automatically included along with object data.

2.3.2 Reviewing Item Dependencies

In the Item Dependencies section, review the list of specified Package Items, along with the dependent items they caused to be included.

For example, if a report is added to a package, the Objects that are used as the basis for that report and the Database View the combines them will be added to the package as dependent items.

2.4 Specify Package Dependencies

A package can be dependent on specific versions of other packages.

Click the [Add Package Dependencies] button to add a dependency, and select the package version:

• If the specified package is published in the current tenancy, the list of versions for that package is displayed.
• If the specified package was installed, the currently installed version is displayed.

Considerations:

• If package B is listed as a dependency for package A, then package B cannot be deleted as long as package A is installed.
• Objects are only added to a package if they are not already present in a package that is listed as a dependency.

2.5 Remove an Item from a Package

1. In the Related Information section of a Package, navigate to the item of interest
2. Click the Remove link to delete an item

   When an item is deleted, it is automatically removed from the package along with its dependencies, for example:

   • If the report is deleted, the report and the dependencies are removed from the package as well

2.6 Publish a Package

Publishing a package makes it available for tenants to install. It also makes it possible for the publisher (you) to automatically upgrade local Package Subscribers, using the Deploy option.

2.6.1 Publishing a Package

The Publish Package option must be enabled by your Service Provider. This feature is disabled by default.

To publish a Package:

1. Follow the instructions to Create a Package, then Add items to the Package.
2. Optionally, click [Edit] to make changes to an existing package before publishing.
3. Fill in the package settings below.
4. Click [Publish] to begin the publishing process.

Basic Information

• Name - Name of the package
• Version - Version number of the package.

  The value can be set to whatever you like.

  The default value is an auto-incrementing dot-version:

  • If the current Package version is "1", the default will be "1.1".
  • If the current version is "1.1", the default will be "1.2", and so on
  • After publication, the value is displayed as the version number in the Package object.
    (The Package object stores version numbers and notes for the last five versions.)

• Version Notes - Notes about the package. They appear in the revision list.

Installation Options

This section appears when the Overwrite Previous Package option has been enabled by the Service Provider.

• Merge with Previous Version

  Make additions to installed package items, and add new package items.

• Overwrite Previous Version

  Delete installed package items that have been dropped from the package,
  make additions to previously installed items, and add new items.

2.6.2 Edit Catalog Information

When a package is published, the [Edit Catalog Info] button is enabled. (It appears only in the Installable Version of the platform.) Information defined here is used to describe the package in an application catalog, or Community Marketplace.

Note: If the Community Marketplace has been enabled by the Service Provider, all of the information provided on this page is displayed. Otherwise, only the description and catalog icon are used.

To edit a catalog entry:

1. Click [Edit Catalog Info] to specify additional information that should appear for the package when it is listed in a catalog.
2. Fill in the Catalog Settings.
3. Click [Save and Preview] to see a formatted version of the catalog entry.
   • This option appears only Community Marketplace has been enabled by the Service Provider.
   • Browser popups must be enabled to display the generated page.

4. Click [Save and Close] to save work in progress.

5. Click [Save and Submit] to submit the package for inclusion in the Service Provider's catalog.
   • Click through the user agreement to finish the submission process.
   • An email is sent to the Service Provider to let them know there is a new package in their approval queue.
   • In return, you get an email when the submission is approved (or rejected).
   • The submission status is also displayed in the package's Revision Details.

Catalog Settings

Basic Information

Summary Description	A brief description of the catalog.
Catalog Icon	Upload a 55x55 pixel icon to accompany the package in the catalog.
Screenshot 1	Attach an image that shows the package or application in operation.
Screenshot 2	Attach a second image.
Overview Benefits	A summary of the advantages to be gained from use of the package.
Overview Description	A longer description of the package that explains what it does and how it works.

Category Information

The list of available categories is defined by the Service Provider, using the Manage Catalog options.

Use the left/right arrow keys to move applicable categories from the Available list to the Selected column, and back.

Use the up/down arrow keys to change the order in which the category-designations appear.

Frequently Asked Questions

Provide additional information in question-and-answer format.

For each entry:

• Enter the question in the first field.
• Enter the answer in the second.

To change the order of questions, click and drag the arrows icon to move a question to a new position.

Click the "X" icon to delete a question.

Click [Add More] to add additional questions.

Publisher Profile

Contact information for the publisher.

Name	Name of the publisher.
Phone	Publishers phone number.
Website	URL to the publisher's website. For example: http://yourCompany.com
Email	Publisher's email address.

2.7 Download a Package

A package you create can also be downloaded from the platform to your system as a zip file. Others can then use the file to install the package.

The Install Package from File option is managed by a Service Provider admin This feature is disabled, by default Learn more: Tenant Configuration Options

To download a package:

1. Publish the package, if it has not already been published.
   The Installation Details section appears.
2. In the Installation Details section, click [Download Package].
3. Save the file to your system from the browser.

Warning: Do not rename the zip file, once it has been created. During installation, the name of the file is validated against the file's contents.

2.8 Deploy a Package

Deploying a package automatically upgrades local Package Subscribers (tenants in the same platform instance who have installed the package).

The Mass Deployment of Packages to Tenants option must be enabled by your Service Provider. This feature is disabled by default.

When you deploy a package, you can chose to automatically upgrade:

• All (local) tenants who have installed the package
• Selected (local) tenants who have installed the package

To deploy a Package:

1. Create a Package, and add items to it.
2. Click [Publish]
   The zip file and Installation Link are created.
3. Click [Deploy].
4. Specify which tenants to upgrade.
5. Specify a deployment time, or chose Immediate.
6. Click [Deploy] again to act on your selections.

Learn more: Package Approval or Rejection

2.9 Distribute a Package to Remote Tenants

When a Package is Published, it can be downloaded from a browser. An Installation Link is automatically created that can be used to distribute the package.

To Give the Download URL to Remote Tenants:

1. Click Settings > Administration > Global Resources > Packages
2. Click the link of the package of interest
3. In the Installation Details section, find the Installation Link
4. Copy the Installation Link URL and paste it into a web page or send it in an email.

Users with valid accounts can then download the package and install the application by following this procedure, which should be provided in the installation instructions:

1. Paste the Installation Link URL into a web browser to visit the installation page.
2. Click the [Install] button to install the package.
   (A valid user account is required to Login.)

2.10 Delete a Package

When a Package is deleted, the Teams and Roles are not deleted

• To remove the Teams or Roles from an installed Package, delete the Teams or Roles manually

To delete a package:

1. Click Settings > Administration > Global Resources > Packages
2. Click the package name to open the package of interest
3. Click the [Delete] button to delete the package

If a Package is deleted and that package has been installed, or if the package is being used by any other package, then any items or dependent items in the package are retained, and are not deleted.

3 Installing Packages

3.1 About Package Installation

During installation, these actions are taken by the platform:

• A list of available package items is displayed
• Names of Custom Objects, Built-in or CRM objects, Fields, Classes, and Pages are validated for uniqueness

• If the Package Subscriber has created an item with the same name as an item in the package, the installation will fail. In order for package installation to succeed, the Package Subscriber must change the name of the Field or Object that is in conflict.

• Role and Team names are not validated for uniqueness

• If the Role/Team names match the Default Roles or My Team (default), then duplicate roles/teams are created; To avoid confusion, it is recommended that the roles/teams be renamed
• If a child team is included in the package, it will be attached to the first top-level team in the installer's instance

3.1.1 Installation Errors and Warnings

If the user's major platform version is smaller than the installed version, installation is not allowed. (So a package published in version 10.0 of the platform cannot be installed in a version 9.x platform.)

If the major version is the same, but the minor version is smaller, installation is permitted--but only after you click through a dialog that says the package may work, it also may not. (For example, if you attempt to install a package published in version 10.1 of the platform into a 10.0 instance.)

Rationale:
Major platform versions invariably have database changes that are incompatible with applications published in an older version, so such installations are not allowed. Minor platform versions generally don't have incompatible changes--but they may--so the installation should proceed only when the package creator has tested the installation and has given an OK.

3.2 About Locked and Unlocked Packages

In an Unlocked package, objects and data can be modified and deleted by the Package Subscriber.

In a Locked package, in contrast:

• Data can be modified and deleted, but objects (including global picklists) can only be modified to the extent that permission to do so has been granted by their respective Object Packaging Options.
• Any classes, components, data policies, pages, and any other form of executable java code contained in the package cannot be viewed, edited, or deleted by the Package Subscriber.

Exception

• A subscriber to a locked package can still modify Custom Access Criteria. Those settings are retained during an upgrade.

Considerations

• The Publisher can change an Unlocked package to a Locked package
• A Locked package cannot be changed to an Unlocked package
• The Object Packaging Options apply only to Locked packages

Notes

• Roles control the user's ability to customize the platform
• Consider modifying roles to support best practices

3.3 Information for Package Installers

Considerations

• When installing a package upgrade, new items are added and existing items are either Merged or Overwritten, based on the Overwrite Previous Package configuration defined by the Publisher
• An installed package and any of the items it contains can be repackaged and republished

Available actions for Locked Packages

Users cannot Edit or Delete package items, however:

• After installation, Package Subscribers can choose to Enable or Disable the following items, if the publisher has granted that permission in the Object Packaging Options:

• Data Policy
• Validation
• Action
• Workflow
• Print Templates

Available actions for Unlocked Packages

Users can Edit or Delete package items

Considerations

• When an unlocked package is upgraded by the Publisher, local customizations made by the Package Subscriber may be overwritten.
• To signal that fact, a warning message is displayed before the upgrade: Customizations are over-written with a package upgrade

3.4 Installing from a File

A package can be downloaded to your system as a zip file and used for installation. This feature is used to migrate packages between separate instances of the platform--for example, in a development environment.

The Install Package from File option is managed by a Service Provider admin This feature is disabled, by default Learn more: Tenant Configuration Options

To install a package from a file:

1. Download the zip file that contains the package.
2. Visit Settings > Administration > Global Resources > Packages
3. Click [Install from File]
4. Use the File Chooser to select the zip file
5. Click [Next].
   The package is installed.

Warning: Do not rename the zip file after downloading it. During installation, the name of the file is validated against the file's contents.

3.5 Special Considerations for ISVs

1. ISV Admin can subscribe to own packages. (If the ISV Admin has published a package on another system, then it can be uploaded and managed as though it were created on the current platform.)
2. ISV Admin can manage items inside a locked package even if it came from another platform instance.

3.6 What Happens to Modified Objects when a Package is Re-Installed?

The short answer is, "the platform does the right thing". So data is never lost without warning. The longer answer depends on the case at hand:

Publisher has added a field

The new field is added during package installation. The field value is empty in all existing records. Additional programming or manual updates are required to populate those fields with values.

Publisher has removed a field

In general, the field is not removed during package installation. It remains in the Subscriber's object. Record data stored in that field is unaffected.

Exception: If the package was locked and the publisher has chosen to overwrite the previous version when re-publishing, then the field is removed during package installation.

Subscriber has added a field

The field remains in the object, and stored data is unaffected.

Subscriber has removed a field

The field is added back when the package is reinstalled.

Note: The one situation that does not arise is that of a renamed field. Fields can be added and removed, but they cannot be renamed. (The field label can change, but not its name.) In effect, the field name is a unique index, so the platform always knows what to do.