The Package Management Service

Last updated Thursday, June 21, 2018 in Sitecore Experience Platform for Developer, Administrator

This topic is valid for Sitecore 9, Update 2, and later.

You use the Package Management Service to provide a Web API that allows users to retrieve information about Sitecore packages and to download and install such packages, using the Update Center. You host these packages locally.

The reasons for using the Package Management Service to host and distribute Sitecore packages within your organization include:

  • You control what packages developers have installed in their development and test environments.
  • You can distribute packages consistently across a Sitecore infrastructure.

The Package Management Service is distributed as a single zip archive. The archive has a Sitecore.PackageManagementService.Web.deploy-readme.txt file that contains installation instructions.

After installation, you configure the service by specifying the values of the following parameters in the appSetting section of the web.config file:

  • Specify HotfixesRoot and UpdatesRoot. They are the file system folders where you keep hotfixes and updates, respectively.
  • Select one of these two authentication modes:
    • To completely disable authentication, set RequiredAuthorization to false.
    • To register a custom token-based authentication provider (that you must implement), specify OAuthAuthorizationServerProvider. The custom provider must inherit from Microsoft.Owin.Security.OAuth.OAuthAuthorizationServerProvider.

This topic describes:

The metadata and structure of a package

A package is a zip archive with two files:

  • Package.update – a standard Sitecore update file.
  • Package.json – information describing the package.

The information (in JSON format) includes descriptions of properties, pre-installation steps, and post-installation steps. The Update Center reads and displays this information. The following is an example of package information in JSON format:

{
    "Properties": {
        "Description": "This update package will upgrade your current Sitecore Platform version to 9.0.2",
        "Installation instruction": "https:/dev.sitecore.net/",
        "Release notes": "https:/dev.sitecore.net/",
        "Some Property": "something",
        "Another Property": "something"
    },
    "PostSteps": [{
        "Name": "Name of poststep here",
        "Description": "Description of poststep here"
    },
    {
        "Name": "Name of the next poststep here",
        "Description": "Description of poststep here"
    }],
    "PreSteps": [{
        "Name": "Name of prestep here",
        "Description": "Description of prestep here"
    },
    {
        "Name": "Name of the next prestep here",
        "Description": "Description of prestep here"
    }]
}

Versioning rules

The Sitecore platform and modules use version names based on semantic versioning.

Regular updates are named: <Major>.<Minor>.<Patch>, for example, 9.0.2.

Hotfixes are named: <Major>.<Minor>.<Patch>.<Hotfix>, for example, 9.0.0.3.

File storage

You must store packages for the Package Management Service in a specific folder structure in the file system. This structure defines the availability of packages for a specific version of the platform or a module.

The folder structure defines:

  • Is it an update or a hotfix?
  • The source version of the platform or module.
  • The target version of the platform or module.

Folder structure for updates

Updates are stored in folder structures in the following way:

  • For platform updates:

    \<updates root>\<source platform version>\Platform\<target platform version>

  • For module updates:

    \<updates root>\<source platform version>\Modules\<module name>\<current module version>\<target modules version>

You specify the update root folder in the web.config file as described previously.

For example:

UpdatesStructureGeneral

Where:

Folder path

Description

\Updates

The root folder of the updates packages.

\Updates\9.0.0

The source (current) version of the installed platform. In this example, it is 9.0.0.

\Updates\9.0.0\Platform\9.0.1 and \Updates\9.0.0\Platform\9.0.2

The target versions of the platform to which you can upgrade from the current version. In this example, you can upgrade from 9.0.0 to 9.0.1 or 9.0.2

\Updates\9.0.0\Modules

The modules that are compatible with the current installed version of the platform.

\Updates\9.0.0\Modules\SXA\1.5.0

The current version of the SXA module. In this example, it is 1.5.0.

\Updates\9.0.0\Modules\SXA\1.5.0\1.6.0

With SXA 1.5.0 installed on platform 9.0.0, you can to upgrade to SXA 1.6.0.

File structure for hotfixes

Hotfixes are stored in folder structures in the following way:

\<hotfixes root>\<platform or module name>\<source product version>\<target product version>

Hotfixes can be either for the platform or for modules. The folder structure for hotfixes is different from the structure used for updates, and hotfixes have their own, separate root folder (specified in the web.config file, as described previously).

A hotfix version has four digits: <Major>.<Minor>.<Patch>.<Hotfix>

For example:

Folder path

Description

\<hotfixes root>\platform\9.0.1\9.0.1.1

The first hotfix for the target platform version 9.0.1.

\<hotfixes root>\SXA\1.5.0\1.5.0.1

The first hotfix (1.5.0.1) for SXA module version 1.5.0.

The Web API

The service provides a Web API for observing and downloading packages.

Updates for the Sitecore platform

The API has these methods for querying and downloading updates for the Sitecore platform:

  • /api/updates/<sitecoreVersion>/platforms

    Returns a list of package descriptions for a specific platform version.

  • /api/updates/<sitecoreVersion>/platforms/latest

    Returns the description of the latest package for a specific platform version.

  • api/updates/<sitecoreVersion>/platforms/<packageVersion>

    Returns the description of the package for a specific platform and package version.

  • /api/download/updates/<sitecoreVersion>/platforms/<packageVersion>

    Returns the package stream for a specific platform version by package name and version.

For example:

  • If you have 9.0.1 and 9.0.2 updates for 9.0.0, returns the latest (9.0.2).

  • Returns the package information for the 9.0.1 package.

Updates for modules

The API has these methods for querying and downloading updates for modules:

  • /api/updates/<sitecoreVersion>/modules/<moduleName>/<moduleVersion>

    Returns the list of package descriptions for a specific module version.

  • /api/updates/<sitecoreVersion>/modules/<moduleName>/<moduleVersion>/latest

    Returns the description of the latest package for the specific module version.

  • /api/updates/<sitecoreVersion>/modules/<moduleName>/<moduleVersion>/<packageVersion>

    Returns the description of the package for specific module version by module name, package version, and platform version.

  • /api/download/updates/<sitecoreVersion>/modules/<moduleName>/<moduleVersion>/<packageVersion>

    Returns the package stream for the specific platform version by package name and version.

For example:

  • http://<hostname>/api/updates/9.0.0/modules/SXA/1.6.0/latest

    Returns information about the latest package available for SXA 1.6.0 that is compatible with 9.0.0 of the platform.

  • http://<hostname>/api/updates/9.0.0/modules/SXA/1.6.0/1.70

    Returns information about the specific update package version 1.7.0 available for SXA 1.6.0, compatible with platform 9.0.0

Hotfixes for the Sitecore platform

The API has these methods for querying and downloading hotfixes for the platform:

  • /api/hotfixes/platforms/<sitecoreVersion>

    Returns a list of descriptions of the hotfixes that are available for the specific platform version.

  • /api/hotfixes/platforms/<sitecoreVersion>/latest

    Returns the description of the latest available hotfix package for the specific platform version.

  • /api/hotfixes/platforms/<sitecoreVersion>/<targetVersion>

    Returns the description of the specific hotfix package for the specific platform version.

  • /api/download/hotfixes/platforms/<sitecoreVersion>/<targetVersion>

    Returns the hotfix package stream for the specific platform version.

For example:

  • http://<hostname>/api/hotfixes/platforms/9.0.0/latest

    Returns the latest hotfix package available for the platform version 9.0.0.

  • http://<hostname>/api/hotfixes/platforms/9.0.0/9.0.0.1

    Returns the hotfix package 9.0.0.1 for platform version 9.0.0.

Hotfixes for modules

The API has these methods for querying and downloading hotfixes for modules:

  • /api/hotfixes/modules/<moduleName>/<moduleVersion>

    Returns a list of descriptions of packages that are available for a specific version of a module.

  • /api/hotfixes/modules/<moduleName>/<moduleVersion>/latest

    Returns a description of the latest hotfix package that is available for the module.

  • /api/hotfixes/modules/<moduleName>/<moduleVersion>/<targetVersion>

    Returns a description of the specific hotfix package for the module of specific version.

  • /api/download/hotfixes/modules/<moduleName>/<moduleVersion>/<targetVersion>

    Returns the hotfix package stream for a specific version of the module.

For example:

  • http://<hostname>/api/hotfixes/modules/SXA/1.6.0/latest

    Returns the latest hotfix package available for the SXA version 1.6.0 module.

  • http://<hostname>/api/hotfixes/modules/SXA/1.6.0/1.6.0.2

    Returns the hotfix package 1.6.0.2 for the SXA 1.6.0 module.

Handling unexpected or invalid requests

The service gives the following responses for requests that it cannot understand or handle:

Problem

Response

Mistakes in the URL (for example a misspelling)

404 (resource not found)

Requested collection of data not found

200 (returns empty collection)

Requested resource not found

400 (resource not found)

Parameter cannot be parsed

400

Send feedback about the documentation to docsite@sitecore.net.