View source for Packages

<noinclude>__NUMBEREDHEADINGS__</noinclude>'''Settings > Administration > Global Resources > Packages'''

A ''package'' is a collection of objects, [[application]]s, and other platform resources.

==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 {{enterprisebrand}} into custom Packages, which deliver customized business solutions to [[Package Subscribers]]. 

::[[File:AppFlowCatalog.gif]]

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

;How it Works:
#Platform elements and applications are Packaged and Published.
#They can then be submitted for approval
#Approved packages become part of the Application Catalog
#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.
{{#if: {{ShowIsvInfo}} {{ShowMspInfo}} |:* ISVs and MSPs can do an automated [[Mass Deployment of Packages to Tenants|Deploy]] of Packages to multiple tenants}}

===Package Items===
{{:Package Items}}

===Package Considerations===
{{:Package Considerations}}

===Package Limitations===
{{:Package Limitations}}

==Working with Packages==

{{permissions|Manage Packages|create, modify or delete Packages}}

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

:;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.

:;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.}}

:;Related Information:
::* '''Items''' - The list of ''package items''. (The contents of the package).
::* '''Package Dependencies''' - Other packages that are required for this package to run.

===Create a Package===
#Go to '''Settings > Administration > Global Resources > Packages'''
#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 [[Image:checkboxicon.gif|link=]] icon
#:''Learn more [[#About Locked and Unlocked Packages|About Locked and Unlocked Packages]]''
#Click '''[Save]'''

===Add Items to a Package===
:1. In the ''Related Informatio''n section, click '''[Add Item]''' to select items for the package
:2. Choose the '''Item Type''' from the list of things you can include
::{| cellpadding="5" cellspacing="1" width="75%"
|
[[File:packageitemtype.gif|none|thumb]]
| valign="top"|
<br>
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|Package Items]]
:3. Click the checkbox [[image:checkboxicon.gif|link=]] 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.}}

====Adding Package Data Items====
To add [[Package Data]]:
# Choose '''Add Item > Item Type''', and choose the item that corresponds to the data in that object.<br/>For example, '''Zip Map Data'''.<br/>A pane appears that lets you specify the data elements to include.
# 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.
# 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.}}

====Reviewing Item Dependencies====
In the ''Item Dependencies'' section, review the list of specified [[#Package Items|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.

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

===Remove an Item from a Package===
#In the ''Related Information'' section of a Package, navigate to the item of interest
#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

===Publish a Package===
{{:Publish}}

====Edit Catalog Entry====
When a package is published, the '''[Edit Catalog Info]''' button is enabled. (It appears only in the [[Installable Version]] of the platform.)

{{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:'''
# Click '''[Edit Catalog Info]''' to specify additional information that should appear for the package when it is listed in a catalog.
# Fill in the settings below.
# Click '''[Save and Preview]''' to see a formatted version of the catalog entry.
#: ''Browser popups must be enabled'' to display the generated page.
# When done, click '''[Save and Exit]'''.<br>The catalog is submitted to the [[Service Provider]] for inclusion in their catalog, and an email is sent to alert them to the new submission. In return, you get an email when the submission is approved (or rejected).

'''Catalog Settings'''
<blockquote>
'''Basic Information'''
:{| class="tight-rows"
|-
|align="right" width="120em"| '''Summary Description''' 
| A brief description of the catalog.

|-
| align="right"| '''Catalog Icon'''
| Upload a 55x55 pixel icon to accompany the package in the catalog.

|-
| align="right"| '''Screenshot 1'''
| Attach an image that shows the package or application in operation.

|-
| align="right"| '''Screenshot 2'''
| Attach a second image.

|-
| align="right"| '''Overview Benefits'''
| A summary of the advantages to be gained from use of the package. 

|-
| align="right"| '''Overview Description'''
| align="left"| 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.
:{| class="tight-rows"
|-
|align="right" width="60em"| '''Name''' 
| Name of the publisher.

|-
| align="right"| '''Phone'''
| Publishers phone number.

|-
| align="right"| '''Website'''
| URL to the publisher's website. For example: http://yourCompany.com

|-
| align="right"| '''Email'''
| Publisher's email address.
|}
</blockquote>

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

{{TenantFeatureByName|Install Package from File|}}

To download a package:
# Publish the package, if it has not already been published.<br/>The '''Installation Details''' section appears.
# In the '''Installation Details''' section, click '''[Download Package]'''.
# Save the file to your system from the browser.

{{Warn|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.}}

===Deploy a Package===
{{:Deploy}}

:''Learn more: [[Manage_Catalog#Package_Approval_or_Rejection|Package Approval or Rejection]]''

===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:
# Click '''Settings > Administration > Global Resources > Packages'''
# Click the link of the package of interest
# In the Installation Details section, find the Installation Link
# 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:
# Paste the ''Installation Link'' URL into a web browser to visit the installation page.
# Click the '''[Install]''' button to install the package.<br>(A valid user account is required to [[Login]].)

===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:
#Click '''Settings > Administration > Global Resources > Packages'''
#Click the package name to open the package of interest
#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.

==Installing Packages==

===About Package Installation===
During installation, these actions are taken by the platform:
:*A list of available package items is displayed
:*Names of {{Type|}}s, {{Type}}s, [[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

===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

===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'''

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

{{TenantFeatureByName|Install Package from File|}}

To install a package from a file:
# Download the zip file that contains the package.
# Visit '''Settings > Administration > Global Resources > Packages'''
# Click '''[Install from File]'''
# Use the File Chooser to select the zip file
# Click '''[Next]'''.<br>The package is installed.

{{Warn|Do not rename the zip file after downloading it. During installation, the name of the file is validated against the file's contents.}}

{{#if: {{ShowIsvInfo}} |
===Special Considerations for ISVs===
# 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.)
# ISV Admin can manage items inside a locked package even if it came from another platform instance.
}}

===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.}}
<noinclude>

[[Category:Packaging]]
[[Category:Global Resources| 7]]
</noinclude>