Packages

> Administration > Account Management > 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 AgileApps Cloud 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 can do an automated Mass Deployment of Packages to Tenants

1.1 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 Rule is added to a packaged object after installation, that Rule is preserved.
• If the packaged object contains a Rule, and that Rule is modified after installation, the modifications are overwritten by the next upgrade (assuming that the new version still contains that Rule).
• Similarly for additions and modifications to Forms, Validations, and other aspects of the packaged 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 Rule that uses 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 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.

• 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.2 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, visible to selected roles, or visible to selected teams can be added to a package.

Users

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

Note: Up to 5 translated languages can be included while packaging. Exceeding 5 is known to cause performance concerns with package installation.

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 appear only 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 Installation 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.

How it works:

When the package is created, and items that are already in the package will be added as a result of the dependency, including:

• Objects
• Application definitions, and their settings
• Any other Package Items that are part of the package

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 > Administration > Account Management > 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. Under Item Type choose from the list of things you can include, as described previously under Package Items

Note:
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.)

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: Before including them in the package, any Default Roles and the default team (My Team) should be renamed. Otherwise, duplicate names/teams are created in the installer's domain, which could be confusing.

2.3.1 Adding Data to a Package

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.

The Publish Package option is enabled by your Service Provider. The default single sign-on setting on on-premises installation is Off. The default single sign-on setting on the cloud is On. (Contact Support to make changes.)

2.6.1 Publishing a Package

Publishing a package creates a zip file that can be deployed to installers in one of several ways.

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.

2.6.2 Publishing a Delta Package

A delta package is one that contains only those elements which have changed--that is, the differences, or "delta", from the original version of the package. So if the original version of the package contained an entire application, the "delta" (update) package might contain a single object.

To publish a delta package:

1. Follow the instructions to Create a Package, then Add items to the Package.
2. Fill in the package settings below.
3. Click [Publish] to begin the publishing process.

   Often, that is all you need to do to generate a delta package.

   Each item in the package has a GUID, so the equivalent item in the target system is automatically updated when the package is installed.

   At times, though, you need the additional behaviors that result from using the Overwrite Previous Package option.

   That option updates a couple of object aspects that are normally left alone, and it causes items deleted from the source system to be deleted from the target system.

4. When package-overwrite behavior is needed, publish the package a second time, without changing it.
   The overwrite option now appears.
5. Choose the Overwrite Previous Package option to get those behaviors.

Learn more: Package Items#How Package Items are Applied

2.6.3 Package Settings

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.

  Version notes appear in the package's Revision Details.

  They are also shown to installers, when they are doing a direct online install--for example, from the Community Marketplace.

  The notes are not included in the archive, so they are not shown when installing from a file.

  (The notes should be copied to the email or web page that includes the file, along with any other information the installer needs to know.)

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.4 Editing Catalog Information

When a package is published, the [Edit Catalog Info] button is enabled. 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 if 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 Distribute a Package

When a Package is Published, the Installation Details section of the package page has an installation link and a [Download] button. Which one you use depends on who is to receive the package.

2.7.1 Use "Deploy" to Automatically Upgrade Existing Installs

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 is enabled by your Service Provider. The default single sign-on setting on on-premises installation is Off . The default single sign-on setting on the cloud is Off . (Contact Support to make changes.)

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.7.2 Allow Tenants on the Same Platform to Self-Install

This option exists only when Tenant Subdomains are enabled.

1. Go to > Administration > Account Management > Packages > {Package} > Installation Details
2. If platform subdomains are enabled:
   • That link has the form https://{subdomain}.agileappslive.com/networking/Service?t=734&id=...
   • Other tenants on the platform can use that link by substituting their {subdomain} and putting the link into a browser.
     (If subdomains aren't enabled, the displayed link can be used by any tenant on the same platform instance, without modification.)
   • That link goes to a page that has an [Install] button, along with a list of package contents.
   • If they haven't logged in yet, they'll be prompted to do so before they can see the page.
   • Clicking [Install] adds the package to their system.

2.7.3 Download for Distribution to Tenants on a Remote Platform

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 (as long as that option is enabled).

The Install Package from File option is enabled by your Service Provider. The default single sign-on setting on on-premises installation is Off. The default single sign-on setting on the cloud is On. (Contact Support to make changes.)

To download a package:

1. Go to > Administration > Account Management > Packages > {Package}
2. Publish the package, if it has not already been published.
   The Installation Details section appears.
3. Click the [Download] button to get a package zip file.
4. In the Installation Details section, the [Download] button to get a package zip file.
5. Save the file to your system from the browser.
   (For convenience, you can then rename the file to something appropriate.)
6. Send the zip file to installers on other systems, or put it on the web and send a link to it.

2.8 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 > Administration > Account Management > 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

The installation page displays:

• Package version notes
• Any messages generated by the platform (for example, messages that result from version conflicts)
• Options for dealing with Role definitions in the package, given that those roles may have been modified by the subscriber (next section)
• A list of items contained in the package

3.1.1 Overriding or Merging Roles

A subscriber has these options when installing a package upgrade:

• Override existing roles - Replace current role definitions with the roles defined in the package.
• Ignore package roles - Don't import role definitions from the package. (Could be problematic if new roles were created.)
• Merge roles - Merges new roles and privileges added by the package provider into the current roles, with any privileges that may have been added by the installer.

3.1.2 Record Visibility Criteria

When a subscriber installs a package:

• If the record visibility is not enabled for subscriber, Record Level Visibility restriction is not applicable.
• If the record visibility is enabled for subscriber, the Package published by the publisher comes with merge or overwrite option.

With merge option:

• In case of conflicts with the record visibility criteria of the subscriber, the record visibility criteria of the subscriber takes precedence.
• In the absence of any conflicts with the subscriber, publishers record visibility criteria is applied

With overwrite option:

• In case of conflicts with the record visibility criteria of the subscriber, the record visibility criteria of the publisher takes precedence. This removes any previous restrictions associated with the existing records of that object.
• In the absence of any conflicts with the subscriber, publishers record visibility criteria is applied.

Note: A conflict can arise in the following cases: When there is a conflict in record visibility being enabled or disabled between publisher and subscriber. When there is a difference in record visibility criteria between the publisher and subscriber

3.1.3 Other Considerations

• Names of Custom Objects, System 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 a Role in the package has the same name as any of the Default Roles, a duplicate role is created.
• If a Team in the package has the name as the default team (My Team), a duplicate team is created.

(Package providers should rename those default roles and teams before including them in the package.)

• If a child team is included in the package, it is attached to the first top-level team in the installer's instance.

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, pages, and any other form of executable java code contained in the package cannot be viewed, edited, or deleted by the Package Subscriber.

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

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

Overwritten

The package's version of the platform entity replaces the installed version.

All changes and additions are replaced by the package contents:

• Fields added to the installed version of an object are lost, along with changes to the object and any fields it contains.
• Rules added to an installed Rule Set or event are lost, along with changes to existing Rules.
• Similarly for other platform entities.
• Processes are overwritten, but your versions are still available, so Process Versioning can be used to revert to your customized versions.

Merged

The package's version of the platform entity is merged into the installed version.

All changes and additions are replaced by the package contents:

• Fields added to the installed version of an object are retained, but changes to object fields are overwritten.
• Rules added to an installed Rule Set or event are retained, but changes to existing Rules are overwitten.
• Similarly for other platform entities.
• Processes are overwritten, but your versions are still available, so Process Versioning can be used to revert to your customized versions.

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:

• Validation
• Custom Form Actions
• Document 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

The Install Package from File option is enabled by your Service Provider. The default single sign-on setting on on-premises installation is Off. The default single sign-on setting on the cloud is On. (Contact Support to make changes.)

To Install a Package from a .zip file:

1. Click > Administration > Account Management > Packages
2. Click the [Subscribe from File] button
3. Select the name of the .zip file

The package is installed

During installation, these actions are taken by the AgileApps Cloud platform:

• A list of available package items is displayed
• Validation is performed (check that Objects, Classes, Pages, Functions have unique names)
  • If any fields have been added to the packaged object, the customer_id is post-fixed to the internal field name to maintain uniqueness
  • Validation will also be done for classes, pages and resources before installing

3.5 Special Considerations for On-Premise Installations

1. The platform admin can subscribe to packages created in the installation. (If package has been published on another system, then it can be uploaded and managed as though it were created on the current platform.)
2. A platform admin can manage items inside a locked package 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.

4 Package Items

Platform elements that are included in a Package are known as package items.

This page details when items are included in the package, when they are installed in the target system, and when old items that have been removed from the source system are deleted from the target system, as well.

The information provided here is the foundation for the companion article: Choosing a Deployment Strategy for Development Systems

4.1 Standard Dependencies

When an item is selected for packaging, dependent elements are automatically included. Items that are related, but upon which the selected item does not actually depend are excluded by default--although they can generally be selected manually, if desired.

Platform Element	Dependent Elements
Application	Includes Application settings Includes all Custom Objects used in the application, along with their dependencies (see below) Includes all Global Picklists referenced by a field in an included object Includes all Classes that are referenced by a Business Rule or Macro Includes Dashboards that are visible to all, a Role, or a Team. (Does not include private dashboards.) Includes all Pages used in Dashboards, Web Tabs, and Sites, as well as all Pages invoked by an Action Button Includes all Application Reports that are visible to all or that are visible to an application Role. Includes all Roles used in the application Includes all Sites defined in the application Includes role-based Tab Preferences for objects Includes all Team definitions that are referenced in a Business Rule, Process, or Macro Includes role-based View Preferences for objects Includes all Web Services that are used in a Process, an External Lookup, an External Data Source, or a Business Rule Includes all Web Tabs defined in the application
Objects (Custom Objects and System Objects)	Includes all object settings and object relationships, including Record Locators Includes all objects that are the target of a Lookup Note: Does not automatically include objects that have a Lookup to the current object. If such Related Objects are not included in the package, any Related Information sections defined in object forms are automatically removed. Includes all objects that are encompassed by a Rollup Summary Field Includes Business Rules Includes Document Templates Includes External Data Source definitions Includes Forms, Layout Rules, Form Scripts, and Custom Form Actions Includes Fields and Field Scripts Includes Indexes Includes Macros Includes Processes Includes Validations Includes Web Forms Excludes Reports Reports can be individually selected. Reports on an object are not automatically included. Excludes data Data is not included automatically. Java code can be written to create Package Data classes that add selected records during packaging, and that take the records out when the package is installed.
Object data and other data (Package Data)
Classes (includes user-created classes)
Mapping Profiles
Pages
Reports
Sites	Includes Pages
Static Resources
Teams
Team Data Sharing Policies	Includes Teams and Roles involved Includes Child Teams if the Include Child Teams option is selected for that team
Template
Template Access URL	Includes Template. Includes Application. For more information about Templates, see How to Create a Custom User Interface (CUI).
Translation Workbench	Includes localized labels and items
Web Services
Web Tabs	includes Pages, and any referenced Widgets (if available)

4.2 Special Dependencies

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

Team 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

Template Access URL

Templates and Application included as dependencies. For more information about Templates, see How to Create a Custom User Interface (CUI).

4.3 Items that are Never Packaged

These platform elements are never added to a package. Customizations made by the subscriber remain intact.

• Access Profiles
• Knowledge Base articles
• Knowledge Base categories
• SLAs

4.4 How Package Items are Applied

The principles that follow summarize the behavior of package items at installation time. Detailed tables list the behavior for individual items, following the summary.

4.4.1 Principles

• New items in the Package are added to the subscriber's system, while items with the same ID are replaced, or updated.

Note:

All aspects of an object (fields and forms, validations, and so on) are given a Globally Unique ID or GUID. Those IDs are preserved when the package is installed, which allows existing items to be replaced while new items are added. (When the overwrite option is chosen, items on the target system that do not have a matching GUID in the package are deleted.)

• If the subscriber created a new platform element with the same name as an item included in the package, the subscriber gets an error. (The error occurs immediately after they select the package. Installation is not allowed to proceed.)
• With few exceptions, modified items in the Package replace the versions that came from a previous Package.
  The exceptions are:

• Global Picklists -- Subscribers are expected to have added items and modified labels, so they are left intact.
• Email Templates and Quick Text -- These items are overwritten only if Overwrite Previous Package was selected by the publisher.
• Roles -- During installation, the subscriber has the option of merging or overwriting roles that are included in the package.

Note: Items that were added to the target system are never deleted. Items are deleted only when: (1) They were previously installed from the source system, (2) They were subsequently removed from that system, and (3) The Overwrite Previous Package option was chosen when the package was created.

4.4.2 Object Aspects

This table describes the behavior of individual Object Aspects.

Object Aspect	Installed when...
	Added if New	Updated	Deleted if Old
Business Rules	✔	✔	Package Overwrite option
Custom Form Actions	✔	✔	Package Overwrite option
Document Templates	✔	✔	Package Overwrite option
Email Templates	✔	Package Overwrite option	Package Overwrite option
External Data Source definitions	✔	✔	Package Overwrite option
Fields	✔	✔	Package Overwrite option
Field Audit Log Settings	✔	✔	n/a
Field Scripts	✔	✔	Package Overwrite option
Forms	✔	✔	Package Overwrite option
Form Scripts	✔	✔	Package Overwrite option
Indexes	✔	✔	Y
Layout Rules	✔	✔	Package Overwrite option
Macros	✔	✔	Package Overwrite option
Processes	✔	✔	Package Overwrite option
Quick Text *	✔	Package Overwrite option	Package Overwrite option
Record Locators	✔	✔	n/a
Subforms	✔	✔	Package Overwrite option
Validations	✔	✔	Package Overwrite option
View definitions **	✔	✔	Package Overwrite option
Web Forms	✔	✔ ***	Package Overwrite option

* Applies only to Cases object in the ServiceDesk application.

** View definitions are included only when they are visible to all, or to an included Role. Private views are not included.

*** Web Forms on objects other than Cases can contain two kinds of email templates--an auto-response template that

is sent to the submitter, and a notification template that tells internal users about new records. Unlike other email templates, they are always overwritten.

4.4.3 Application Elements

This table describes the behavior of other platform elements that go into an application.

Application Element	Included when		Installed when
	Selected	or if Referenced by	Added if New	Updated	Deleted if Old
Application	✔	Package Dependency Template Access URL	✔	✔	Package Overwrite option
Classes	✔	Business Rule Macro	✔	✔	Package Overwrite option
Customer Satisfaction Surveys		ServiceDesk	✔	N	n/a
Case Analytics Dashboard		ServiceDesk	✔	n/a	Package Overwrite option
Dashboards		if visible to all, a Role, or a Team	✔	✔	Package Overwrite option
Global Picklists		Object Field	✔	✔	N
Global Template Variables	not included
Knowledge Base articles	not included
Knowledge Base categories	not included
Mapping Profiles	✔		✔	✔	Package Overwrite option
Object definitions	✔	Lookup field Rollup Summary Field	✔	✔	Package Overwrite option
Object records		Package Data class	as defined by the class
Pages	✔	Custom Form Action Dashboard Site Web Tab	✔	✔	Package Overwrite option
Reports	✔	visible to all or to an application role	✔	✔	Package Overwrite option
Roles		Application Process Team Data Sharing Policy	✔	Subscriber choice	N
Sites	✔	Application	✔	✔	Package Overwrite option
SLAs	not included
Static Resources	✔		✔	✔	Package Overwrite option
Tab Preferences		Role	✔	✔	Package Overwrite option
Team definitions	✔	Business Rule Macro Process Team Data Sharing Policy	✔	N	N
Team-object Business Rules		Team	✔	✔	Package Overwrite option
Team Data Sharing Policies	✔		✔	✔	Package Overwrite option
Templates	✔	Template Access URL	✔	✔	Package Overwrite option
Template Access URL	✔		✔	✔	Package Overwrite option
Translation Workbench entries	✔		✔	✔	Package Overwrite option
Users Object *	✔		✔	✔	n/a
User-object Business Rules		Users Object	✔	✔	Package Overwrite option
User-object Fields		Users Object	✔	✔	Package Overwrite option
View Preferences		Role	✔	✔	Package Overwrite option
Web Services	✔	Business Rule External Data Source External Lookup Process	✔	✔	N
Web Tabs	✔	Application	✔	✔	Package Overwrite option

Note: Include the Users Object in the package whenever fields or business rules in the package has references to the Users object. Include the Users Object in the package whenever record visibility criteria for an object in the package has references to user custom field.

4.4.4 System Elements

This section describes important system-object and system-configuration items:

System Element	Included when		Installed when
	Selected	or if Referenced by	Added if New	Updated	Deleted if Old
Access Profiles	not included
Business Hours Calendars		Process	✔	N	N
Email Channel settings	not included
LDAP Configuration	not included
Marketplace listings *	not included
Service Portal settings	not included
Scheduled Jobs **	not included
Single Sign-On settings	not included

* Potentially valuable for an on-premise installation that wants to back up their primary admin tenancy.

** Scheduled Rules, on the other hand, are included, along with other Business Rules.

5 Choosing a Deployment Strategy for Development Systems

AgileApps Cloud platform package deployment is based on the publisher/subscriber model, where subscribers are expected to have customized key aspects of the package. In the publishing process, those aspects of the installed application are left alone. Package deployment is already optimized for the publisher/subscriber model, so if that's what you're doing you're in pretty good shape. You may want to double-check the behavior of things you'll be publishing, but there shouldn't be much you need to do.

Things get a little more interesting if you're deploying packages in a development scenario, where you have one or more development systems, a test system, and a production system. In that model, the application built in the development environment needs to be fully and completely replicated in the test environment. When it is ready for distribution, it must then be fully replicated in the production environment(s).

In that situation, there are several things you'll need to do. Those steps are described in this article. (The steps are based on the information provided in the Package Items page.)

5.1 Partition the Application

If you have multiple developers, the first step is to partition the application appropriately:

1. Make sure that only one person makes edits to any given aspect of an object.
   If multiple people add validations, for example, that can work. But only one person should make edits to existing validations, otherwise someone's work will get overwritten.

2. Each person who owns objects should package them and share the package with other developers.
   That step ensures that each of the development systems has the same object definitions.

3. Ideally, that person will be responsible for all additions to an object, as well.
   If several developers add validations, for example, an integration step is required to get all of the validations on the test system. (Each developer can publish to the test system--but then individual developers don't have the same set. Or they can all publish to each other--but that requires coordination. It's easier to make one person responsible for all of the validations, and all of the forms, field definitions, and other aspects of any given object.)

4. Similarly, make one person responsible for each of the other application artifacts like Roles and Tab Preferences.

5.2 Choose Your Deployment Model

The next step is choose your deployment model (sandbox deployment or publish/install):

• If you have created development sandboxes, it's natural to use Sandbox Deployment.

• The advantage of that process is that sandbox pathways are clearly defined.
• The disadvantage is that the owner of the target sandbox has no say in the matter--the deployment comes at them when the packager says, whether or not the target system is ready.
• Is also important to note that the deployment process still follows the publisher/subscriber model, and that the same rules apply. So choosing sandbox deployment doesn't automatically replace everything on the target system.

• As a result, it is common even in the development scenario to use the normal publication process, where the packager "publishes" a package to make it available, after which the target systems install the package. The advantages of that process are:

• The installer can choose when to install the package.
• The installer can see what's in the package

But:

• The installer needs to be sure to choose the "override roles" option during the installation, to be sure that any changes that were made to existing roles are reflected on the target system.

5.3 Create and Deploy the Package

1. When creating the package, include the Users Object if any new fields or business rules have been added that the application depends on.
2. Consider making the package a locked package, so it can't be customized in the test (or production) system.

   Learn more: Packages#About Locked and Unlocked Packages

3. After it is created, use your preferred deployment strategy to update target installations.

5.4 Perform Any Necessary Manual Replications

Finally, you need to make sure that each system targeted by the deployment process is an accurate reflection of the packaged application.

To do that:

1. Publish the package in "overwrite" mode, so that deletes (for most package items) are replicated in the target environment.

   Learn more: Packaging option

2. The package installer should choose the override option for roles, in case any role-definitions have changed. (Most developer-environments will also choose overwrite, unless they have been working on roles, in which case they will choose to merge role definitions.)

   Learn more: Subscriber choice

3. On all target systems, manually delete any of these elements that are no longer needed:

   • Applications

     This step is required only if an application-definition was added as a result of a Package Dependency, and that application is no longer needed.

     When you delete the application, components shared by other applications remain. Only components that are unique to the application are deleted.

   • Classes
   • Global Picklists
   • Roles

4. On all target systems, manually replicate any changes made to these application items, and manually delete any that were removed:

   • Business Hours Calenders
   • Customer Satisfaction Surveys (if publishing ServiceDesk)
   • Global Template Variables
   • KnowledgeBase articles and categories (if publishing ServiceDesk)
   • Site definitions
   • Team definitions

5. On all target systems, manually reproduce environment-specific customizations:

   • Web Services
     Web Service end-point URLs and authentication details need to be restored, if they are different in the development, test, and production environments.

6. On all target systems, manually reproduce any changes made to these system components, if they need to be replicated in the target environment:

   • Access Profiles
   • Authorization mechanisms

     • LDAP Configuration
     • Single Sign-On settings

   • Business Calendars
   • Communication channel settings

     • Email Channel settings

   • Service Portal settings
   • Scheduled Jobs

For more information on Assets, see Deploying AgileApps assets using webMethods Deployer