The Package Management Service

Current version: 10.0

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

The Package Management Service supports two configuration groups:

Management - this platform group contains only WCMS configuration, files, and DLLs. It is XM without the parts needed for Sitecore Analytics.
Platform - this platform group 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 in 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.

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:

RequestResponseshell

{
    "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.2.2.
Hotfixes are named: <Major>.<Minor>.<Patch>.<Hotfix>, for example, 9.2.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 the following factors:

If the package is an update or a hotfix.
The source version of the platform or module.
The target version of the platform or module.

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.

This an example of a folder structure:

Where the folders are:

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.

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>

This an example of a folder structure:

Where the folders are:

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.

Use Azure Blob storage

You can use Azure Blob storage instead of the file system for storing packages.

To use Azure Blog storage for the Package Management Service make these changes to the web.config file:

Specify values for the HotfixesRoot and UpdatesRoot settings. The values must contain the Azure Blob storage container name and the virtual directory root, delimited by /. Use only lowercase names.
Change the value of the PackageRepositoryProvider setting to Sitecore.PackageManagementService.AzureStorageProvider.Repositories.AzureBlobRepository, Sitecore.PackageManagementService.AzureStorageProvider:
RequestResponseshell
```
<add key="PackageRepositoryProvider" value="Sitecore.PackageManagementService.AzureStorageProvider.Repositories.AzureBlobRepository,  Sitecore.PackageManagementService.AzureStorageProvider"/>
```
Specify the connection string value from your Azure Blob storage account in the Azure portal as the value of the AzureStorage setting.

The Web API 2.0

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

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

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.