Sitecore Experience Manager

The Package Management Service

Abstract

How to use the Package Management Service for a local update center

Note

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.

Note

Starting from Sitecore 9.1.1, the Package Management Service supports two configuration groups:

  • Management - this platform group contains only WCMS configuration, files, and DLLs. It is XM without bits needed for Sitecore Analytics.

  • Platform - this platform group also contains the files needed for XP., and is a full Sitecore configuration.

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 appSettingsection 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:

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"
    }]
}

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.

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 before Sitecore 9.1.1

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:

The_Package_Management_Service-Picture_2-rId11-17622959.png

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.

Folder structure for updates for Sitecore 9.1.1 and later

Updates are stored in folder structures in the following way:

  • For platform updates:

    <updates root>\<source platform version>\<platform group name (Platform or Management)>\<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:

pms9111-1_jpg.png

Where:

Folder path

Description

\updates

The root folder of the updates packages.

\updates\9.1.0

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

\updates\9.1.0\platform\9.1.1 and \updates\9.1.0\platform\9.1.2

 The target versions of the platform to which you can upgrade from the current version. In this example, you can upgrade from 9.1.0 to 9.1.1 or 9.1.2

\updates\9.1.0\management\9.1.1 and \updates\9.1.0\management\9.1.2

The target versions of the platform configuration “Management” to which you can upgrade from the current version. In this example, you can upgrade from 9.1.0 Management to 9.1.1 or 9.1.2 Management.

\updates\9.0.0\modules

The modules that are compatible with the currently 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 upgrade to SXA 1.6.0.

File structure for hotfixes before Sitecore 9.1.1

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.

File structure for hotfixes for Sitecore 9.1.1 and later

Hotfixes are stored in folder structures in the following way:

<hotfixes root>\<package name (Platform, Management or module name like EXM)>\<source product version>\<target product version>

For example:

pms9111-2_jpg.png

Where:

Folder path

Description

<hotfixes root>\management\9.1.0\9.1.0.1

The first hotfix for the target platform Management group version 9.0.1.

<hotfixes root>\platform\9.1.0\9.1.0.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 service provides a Web API for observing and downloading packages.

Version 2.0 of the API has a different versioning policy. It is included in Sitecore 9.1.1 and later.

Version 1.0 of the API does not support the Management platform group.

You add ?api-version=<number of api version> to a query string to use a specific version of the API.

If there is no API version in the query string, version 1.0 of the API is used.

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.

The service provides a Web API for observing and downloading packages. Version 1.0 of the API has a different versioning policy. Version 2.0 of the API is included in Sitecore 9.1.1 and later.

You add ?api-version=<number of api version> to a query string to use a specific version of the API.

If there is no API version in the query string, version 1.0 of the API is used.

Updates for the Sitecore platform

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

  • /api/updates/<sitecoreVersion>/<platform group name (Platform or Management)>?api-version=2.0

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

  • /api/updates/<sitecoreVersion>/<platform group name (Platform or Management)>/latest?api-version=2.0

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

  • /api/updates/<sitecoreVersion>/<platform group name (Platform or Management)>/<packageVersion>?api-version=2.0

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

  • /api/download/updates/<sitecoreVersion>/platforms/<platform group name (Platform or Management)>?api-version=2.0

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

Updates for modules

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

  • /api/updates/<sitecoreVersion>/modules/<moduleName>/<moduleVersion>?api-version=2.0

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

  • /api/updates/<sitecoreVersion>/modules/<moduleName>/<moduleVersion>/latest?api-version=2.0

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

  • /api/updates/<sitecoreVersion>/modules/<moduleName>/<moduleVersion>/<packageVersion>?api-version=2.0

    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>?api-version=2.0

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

Hotfixes for the Sitecore platform and modules

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

  • /api/hotfixes/<packageName(Platform, Management or module name like EXM)>/<packageVersion>/latest?api-version=2.0

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

  • /api/hotfixes/<packageName(Platform, Management or module name like EXM)>/<packageVersion>?api-version=2.0

    Returns a list of descriptions of the available hotfixes that for the specific platform group version or module version.

  • /api/hotfixes/<packageName(Platform, Management or module name like EXM)>/<sitecoreVersion>/<packageVersion>?api-version=2.0

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

  • /api/download/hotfixes/<packageName(Platform, Management or module name like EXM)>/<sitecoreVersion>/<packageVersion>?api-version=2.0

    Returns the hotfix package stream for the specific platform version.