Skip to main content

How to upgrade to the latest Uniform for Sitecore

info

These steps have been tested with an upgrade from 5.1 to 6.0. Upgrade for an earlier version is expected to work by following the steps below, but it didn't pass the full QA cycle. If you have any issues please contact support

Steps:#

  1. Backup items under the /sitecore/system/Uniform node and files under App_config\Include\Uniform* and App_config\Include\zzz_Uniform* folders.
  2. Comment out any custom config files which patch the Uniform configuration by adding the .DISABLED extension.
  3. Install the new Uniform for Sitecore package with the merge/clear option for items and the override option for files.
  4. Publish site (incremental or smart) to the Web DB.
  5. Uncomment the custom config files which patch the Uniform configuration by removing the .DISABLED extension.
    tip

    If you encounter any server-side errors after enabling these config files, review the config changes between your previous and latest Uniform for Sitecore versions. You may use any differencing tools like WinMerge.

  6. Change the Uniform packages version for the Uniform service site to correspond with the version of the Sitecore package. In the package.json change all "@uniformdev/*": "old_version" to "@uniformdev/*": "new_version" and call yarn/npm install.

How to find which the Uniform version?#

Uniform for Sitecore versioning looks like vMajorVersion.MinorVersion.ReleaseDate-Number. There are a few ways to identify the version:

  • Look at the Sitecore package name, i.e. Uniform v6.0.211109-1 for Sitecore 9.3.0 MVC and JSS.zip.
  • For any Uniform DLLs under the Sitecore bin folder (e.g. Uniform.Deployment.Core.dll) check the file properties -> details -> product version.
  • Check any @uniformdev/* package version in the Uniform service site package.json file. For example: "@uniformdev/common-server": "^6.0.220221-1" :::

Quick test to confirm you are running 6.0 and later#

There are changes in the map service between versions before 6.0 and 6.0+. Open the map service at /uniform/api/content/<site-configuration-name>/map?uniform_token=<token> to make sure the response is a flat JSON without subitems. For example:

{  "/": {    "id": "{37020E32-200B-434F-9C3B-0A7DEF0958BD}"  },  "/album": {    "id": "{07346C0C-F808-407C-8D38-8848B482A02A}"  },  "/brokendatasource": {    "id": "{850C0E4E-686D-4C59-8180-EEFFA782DB59}"  },  "/children-content": {    "id": "{AFED2AEB-B9BA-4381-9A43-67FC3D98A4AC}"  },    ...

This is incorrect (5.x):

"isPage": true,  "lastModified": "2021-12-15T16:20:07",  "children": {    "album": {      "isPage": true,      "lastModified": "2021-12-15T16:20:07",      "children": {            ...

Troubleshooting#

Map service replies with an older 5.1 format when pages include other pages as JSON children.#

Either DLLs or configs were not applied correctly. Open the Sitecore package as an archive and copy the App_Config and bin folder content manually to Sitecore site folder. If this doesn't help, remove any Uniform-specific configs which don't exist in the installation package.

The 'item cannot be found' server error on export in the Uniform service site (deploy:export or export)#

Sitecore error: 

The item cannot be found, DB: master, id: template`

Service error:

> Build error occurredError: Export encountered errors on following paths:        /children        /isPage        /lastModified        /name        /template

Solution: Make sure the map service is in 6.0 format. If it is not, apply solution #1

The 'Attempt by method' server error when opening Sitecore in a browser#

Sitecore error:

Attempt by method 'Uniform.UpmSscServiceConfigurator.Configure(Microsoft.Extensions.DependencyInjection.IServiceCollection)' to access method 'Uniform.Assert.ArgumentNotNull(System.Object, System.String)' failed.

Solution: Something went wrong when installing the package. Apply solution #1