Difference between revisions of "Package Items"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
Line 1: Line 1:
Platform elements can be selected for inclusion in a [[Package]] as ''package items''. When selected, 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 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====
====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.
:{| border="1" cellpadding="5" cellspacing="0"
:{| border="1" cellpadding="5" cellspacing="0"
! Platform Element !! Dependent Elements
! Platform Element !! Dependent Elements
Line 149: Line 155:
::* Email Templates  -- Subscribers are expected to have customized email templates with their return address, signature text, and possibly logo images, so they are left intact.
::* Email Templates  -- Subscribers are expected to have customized email templates with their return address, signature text, and possibly logo images, so they are left intact.
::* Roles -- During installation, the subscriber has the option of merging or overwriting roles that are included in the package.     
::* Roles -- During installation, the subscriber has the option of merging or overwriting roles that are included in the package.     
:* Items deleted from the packager's application are never deleted from the subscriber's system unless the [[Overwrite Previous Package]] option has been enabled by the Service Provider, and the packager has chosen the ''Overwrite'' option. (Then, and then only, items deleted from the Service Provider's system are deleted from the subscriber's system when the package is installed.)
 
{{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=====
=====Object Aspects=====
This table describes the behavior of individual [[Object Aspects]].  
This table describes the behavior of individual [[Object Aspects]].
 
''Considerations:''
:* When an object is included in a package, all of its aspects are included, as well.
:* The package-installation behavior depends on whether it is the first installation or an update.
:* For an update, whether or not "extraneous" aspects are removed depends on whether or not the package was created with the ''Overwrite'' option.<br>(An item is "extraneous" if it is not included in the package, which could occur because it was deleted from the source system, or because it was added in the target system.)
 
:{| border="1" cellpadding="5" cellspacing="0"
:{| border="1" cellpadding="5" cellspacing="0"
!rowspan="2" align="left" | Object Aspect !! align="center" colspan="3"|Installed when...
!rowspan="2" align="left" | Object Aspect !! align="center" colspan="3"|Installed when...
|-
|-
!                                              First Install !! Update !! Deleted if Extraneous
!                                              Added if New !! Updated !! Deleted if Old
|-
|-
| [[Business Rules]]                  || &#10004; || &#10004; || [[Overwrite Previous Package|Packaging option]]
| [[Business Rules]]                  || &#10004; || &#10004; || [[Overwrite Previous Package|Packaging option]]
Line 192: Line 193:
| [[Processes]]                        || &#10004; || &#10004; || '''N'''
| [[Processes]]                        || &#10004; || &#10004; || '''N'''
|-
|-
| [[Quick Text]] (Cases Objects only)  || &#10004; || '''N'''  || '''N'''
| [[Quick Text]] *                    || &#10004; || '''N'''  || '''N'''
|-
|-
| [[Record Locators]]                  || &#10004; || &#10004; || n/a
| [[Record Locators]]                  || &#10004; || &#10004; || n/a
Line 200: Line 201:
| [[Validations]]                      || &#10004; || &#10004; || [[Overwrite Previous Package|Packaging option]]
| [[Validations]]                      || &#10004; || &#10004; || [[Overwrite Previous Package|Packaging option]]
|-
|-
| [[View]] definitions *               || &#10004; || &#10004; || [[Overwrite Previous Package|Packaging option]]
| [[View]] definitions **              || &#10004; || &#10004; || [[Overwrite Previous Package|Packaging option]]
|-
|-
| [[Web Forms]]                        || &#10004; || &#10004; || '''N'''
| [[Web Forms]]                        || &#10004; || &#10004; || '''N'''
|}
|}
:: * View definitions are included only when they are visible to all, or to an included [[Role]]. Private views are not included.
:: * 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.


=====Application Elements=====
=====Application Elements=====
This table describes the behavior of other platform elements that go into an application.
This table describes the behavior of other platform elements that go into an application.
''Considerations:''
:* These items are included in a package when they are selected, or when they are a dependency, referenced by some other item.
:* The package-installation behavior depends on whether it is the first installation or an update.
:* For an update, whether or not "extraneous" items are removed depends on whether or not the package was created with the ''Overwrite'' option.<br>(An item is "extraneous" if it is not included in the package, which could occur because it was deleted from the source system, or because it was added in the target system.)
:: ''Note:''
:::* Extraneous items are removed only for things that are included in the package.
:::* If reports are included, and the Overwrite option is on, then the entire list of reports is overwritten (which removes any that were extraneous).
:::* But if reports are ''not'' included, then existing reports are left untouched.
:{| border="1" cellpadding="5" cellspacing="0"
:{| border="1" cellpadding="5" cellspacing="0"
! rowspan="2" align="left" valign="bottom"| Application Element !!colspan="2"|Included when  ||colspan="3"|Installed when
! rowspan="2" align="left" valign="bottom"| Application Element !!colspan="2"|Included when  ||colspan="3"|Installed when
|-
|-
!                                  Selected !! when Referenced by !! First Install !! Update !! Deleted if Extraneous
!                                  Selected !! or if Referenced by !! Added if New !! Updated !! Deleted if Old
|-
|-
| [[Application]]                || &#10004; || [[Package Dependency]] || &#10004; || &#10004; || '''N'''
| [[Application]]                || &#10004; || [[Package Dependency]] || &#10004; || &#10004; || '''N'''
Line 290: Line 282:


=====System Elements=====
=====System Elements=====
This section describes important system-object and system-configuration items.
This section describes important system-object and system-configuration items:
 
''Considerations:''
:* These items are included in a package when they are selected, or when they are a dependency, referenced by some other item.
:* The package-installation behavior depends on whether it is the first installation or an update.
:* For an update, whether or not "extraneous" items are removed depends on whether or not the package was created with the ''Overwrite'' option.<br>(An item is "extraneous" if it is not included in the package, which could occur because it was deleted from the source system, or because it was added in the target system.)
 
:{| border="1" cellpadding="5" cellspacing="0"
:{| border="1" cellpadding="5" cellspacing="0"
! rowspan="2" align="left" valign="bottom"| System Element !!colspan="2"|Included when  ||colspan="3"|Installed when
! rowspan="2" align="left" valign="bottom"| System Element !!colspan="2"|Included when  ||colspan="3"|Installed when
|-
|-
! Selected !! when Referenced by !! First Install !! Update !! Deleted if Extraneous
! Selected !! or if Referenced by !! Added if New !! Updated !! Deleted if Old
|-
|-
| [[Access Profiles]]            || colspan="5" align="center"|''not included''
| [[Access Profiles]]            || colspan="5" align="center"|''not included''
Line 312: Line 298:
| [[LDAP Configuration]]        || colspan="5" align="center"|''not included''
| [[LDAP Configuration]]        || colspan="5" align="center"|''not included''
|-
|-
| [[Marketplace]] listings       || colspan="5" align="center"|''not included''
| [[Marketplace]] listings *    || colspan="5" align="center"|''not included''
|-
|-
| [[Service Portal]] settings    || colspan="5" align="center"|''not included''
| [[Service Portal]] settings    || colspan="5" align="center"|''not included''
|-
|-
| [[Scheduled Jobs]] *           || colspan="5" align="center"|''not included''
| [[Scheduled Jobs]] **          || colspan="5" align="center"|''not included''
|-
|-
| [[Single Sign-On]] settings    || colspan="5" align="center"|''not included''
| [[Single Sign-On]] settings    || colspan="5" align="center"|''not included''
Line 322: Line 308:
| [[Twitter]] settings          || colspan="5" align="center"|''not included''
| [[Twitter]] settings          || colspan="5" align="center"|''not included''
|}
|}
:: * [[Scheduled Rules]], on the other hand, ''are'' included, along with other [[Business Rules]].
:: * 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]].

Revision as of 23:04, 18 May 2015

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
  • 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.
  • Classes (includes
    user-created classes)
  • The Business Hours Calendar used in processes.
    (An installed calendar is never overwritten, so installers are free to modify the calendar to suit their purposes.)
  • Teams and Roles used in Process tasks
  • Sites
  • Includes Teams and Roles involved
  • Includes Child Teams if the Include Child Teams option is selected for that team
  • Includes localized labels and items


  • Web Tabs

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

Notepad.png

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

Items that are Never Packaged

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

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 -- Subscribers are expected to have customized email templates with their return address, signature text, and possibly logo images, so they are left intact.
  • Roles -- During installation, the subscriber has the option of merging or overwriting roles that are included in the package.

Notepad.png

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 Packaging option
Custom Form Actions Packaging option
Document Templates Packaging option
Email Templates N N
External Data Source definitions Packaging option
Fields Packaging option
Field Audit Log Settings n/a
Field Scripts Packaging option
Forms Packaging option
Form Scripts Packaging option
Indexes Y
Layout Rules Packaging option
Macros Packaging option
Processes N
Quick Text * N N
Record Locators n/a
Subforms Packaging option
Validations Packaging option
View definitions ** Packaging option
Web Forms N
* 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.
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 N
Classes Business Rule
Macro
N
Customer Satisfaction Surveys ServiceDesk N n/a
Case Analytics Dashboard ServiceDesk n/a Packaging option
Dashboards if visible to all, a Role, or a Team Packaging option
Global Picklists Object Field N
Global Template Variables not included
Knowledge Base articles not included
Knowledge Base categories not included
Mapping Profiles Packaging option
Object definitions Lookup field
Rollup Summary Field
Packaging option
Object records Package Data class as defined by the class
Pages Custom Form Action
Dashboard
Site
Web Tab
Packaging option
Reports Dashboard Packaging option
Roles Application
Process
Team Data Sharing Policy
Subscriber choice N
Sites Application Packaging option
SLAs not included
Static Resources Packaging option
Tab Preferences Role Packaging option
Team definitions Business Rule
Macro
Process
Team Data Sharing Policy
N N
Team-object Business Rules Team Packaging option
Team Data Sharing Policies Packaging option
Translation Workbench n/a
Users Object * n/a
User-object Business Rules Users Object Packaging option
User-object Fields Users Object Packaging option
View Preferences Role Packaging option
Web Services Business Rule
External Data Source
External Lookup
Process
N
Web Tabs Application Packaging option
* The Users Object should be included to the package whenever fields or business rules have been added that the application references.
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
Facebook 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
Twitter 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.