Mass Deployment of Packages to Tenants

About Mass Deployment

This option gives the Service Provider the ability to Package applications for distribution to multiple tenants. This feature is provided to extend the functionality of Package upgrades in a multi-tenant environment.

If an item contained in the package being deployed already exists in the tenant's system/platform, then deployment will result in an upgrade/update, otherwise, package deployment will result in a brand new installment of the item.

Learn more: Overwrite Previous 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.)

Package Criteria

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

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)

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

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

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.

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.

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.

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.

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.

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.

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.

Deployment Considerations

• Deployment can only be done on packages that meet the Package Criteria
• In case of server failure/reboot during deploying, the process should be resumed when the server recovers
• If the Remote Tenant option is selected, the user will be required to enter the following information:

• Remote Server URL (must be in a valid URL format with URL protocol)
• Username
• Password

Deploy a Package

To Deploy a Package:

1. Click > Administration > Account Management > Packages
2. Click the desired Package
   (That package must already have been published.)
3. Click the [Deploy] button
4. Select deployment type: 'All Tenants' OR 'Selective Tenants'. ('All Tenants' is checked by default)
5. Optionally, choose to send an upgrade notification email to each tenant; When checked, an email message is sent to the tenant's designated copy support email address (as configured in Company Information) upon the deployment completion (if deployment is successful); If the tenant has no designated email address, no message is sent; This option is disabled by default
6. Select Schedule Time: 'Immediate' OR 'Schedule Date'. ('Immediate' is checked by default)
   • Upon the completion of deployment, an email is sent to the user who submitted the request. The email contains the deployment status summary (number of tenants processed and number of successful/failed deployments)
7. Click the [Deploy] button to submit the request

To check the status of a Deployment:

1. Click > Administration > Monitoring > Mass Operation Status
2. Select the deployment of interest to view the progress

Distribute and Install a Package via .ZIP File

Packages can be deployed as a compressed .ZIP file, a feature available to Service Providers.

The ZIP file option provides the ability to move packages across different installations of the AgileApps Cloud platform.

Examples

• Move from the Development instance to the QA instance for testing
• Move packages from the QA instance to the production instance
• Download the package as a zip file and archive it

Create a Package as a .ZIP file

To create a Package as a downloadable .ZIP file:

1. Click the [Download Package] button to create a compressed .zip file

   

   The Package Revision Details section indicates the number of package revisions, and will automatically update when you publish new versions

2. Click [Publish] to create the package

Considerations

• This file can be distributed by ftp or as digital media, loaded directly to a user's desktop

• When uncompressed, the application is installed to that user's account

• This file may be very large, and unsuitable for emailing

Install a Package from a .zip 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

Alternate Package Distribution Methods

A package can also be distributed in these ways:

• Publish the package and submit it to the Service Provider for distribution in the Catalog.
• Post the URL to the web or put it into an email, so users can subscribe to it directly.

Learn more: Publish a Package