4.5 Table of Contents
This upgrade guide provides a step by step process for performing an upgrade of an existing project to the latest version of Brightspot 4.5 and covers a majority of scenarios or issues that may occur during an upgrade.
If you believe anything is missing from the documentation, please reach out to your Brightspot representative to ensure that we can continue to keep this up to date and accurate.
Below are the relevant versions to be used for the Brightspot 4.5 Upgrade Guide
- Brightspot: 4.5.22
- Component-lib: 4.5.23
- Brightspot-GO: Refer to below table
| Current Version Range | Upgrade To Version |
| 0.x | 0.18.0 |
| 1.x | 1.4.6 |
Step 1: Verify the initial build
Before beginning an upgrade, we should verify the state of the initial build. The outcome of this step will help guide some steps later in the upgrade process.
Brightspot Enterprise 4.5 Developer Upgrade Guide → Initial Build Verification Guide
Running the initial build To run the initial build of the project, use the command below. This will execute a clean build of the project. Troubleshooting Below are some errors that can occur and steps...
Step 2: Verify ThemeCompatibilityTest (TCT)
TCT is a test that ensures the expected theme JSON structure is compatible with the view structure generated by Brightspot Styleguide. You should verify the state of this before making any code changes, since in some cases, TCT may not be installed or executing properly.
During the upgrade process, it is important to not introduce new TCT errors, but if TCT isn’t running/installed/configured, we need to know since fixing TCT errors directly is separate from the general upgrade process and can be done afterward.
Below is a guide on how to verify TCT and make necessary configuration changes.
Brightspot Enterprise 4.5 Developer Upgrade Guide → Verifying ThemeCompatibilityTest (TCT) Guide
You can verify TCT is running by executing a build command on the project with that test specifically noted. Here is an example: This will execute the build and the test. You sho...
Step 3: Analyze and Resolve Shadowed Code
Shadowed code is code that is forked from platform code, and overrides classes/files that would otherwise be accessible through a library dependency.
Please follow the guide below carefully to resolve/analyze any shadowed code.
Before beginning an upgrade on the project, analyze all shadowed code thoroughly and document the analysis. This analysis is critical for providing context for remediation.
Brightspot Enterprise 4.5 Developer Upgrade Guide → Shadowed Code Resolution Guide
Resolving code shadows is not well-defined in a step-by-step process. Shadowed code can be very tricky and time consuming to resolve, so it’s very important that the engineer takes diligent documentat...
Step 4: Upgrade Styleguide in all bundles
We need to upgrade the Styleguide in all bundles on the project. There is usually only one bundle, but it is important to ensure that all bundles are updated if more than one exist.
More documentation on how to use the latest Brightspot Styleguide can be found here: https://www.brightspot.com/documentation/brightspot-cms-developer-guide/latest/theme-guide#introduction-to-theming
Brightspot Enterprise 4.5 Developer Upgrade Guide → Styleguide Upgrade Guide
Below is a link to the upgrade docs in our delivery notes. Building additional css files (Some special ones like AMP). This may also apply for special .less files which are includes...
Step 5: Upgrade Brightspot Dependency Versions
It is recommended to do this at the same time as the Gradle upgrade.
Refer to the versions and procedures in the following linked guide.
Brightspot Enterprise 4.5 Developer Upgrade Guide → Brightspot Dependency Version Upgrades Guide
Update the Brightspot dependency versions in accordance with the specifications in this document.
Step 6: Resolve Unsupported Dependencies
If upgrading from an older version, you might run into dependencies that are no longer supported when upgrading to the latest Brightspot version.
Below is a guide detailing some of the dependencies that are no longer supported, and some steps to resolve these dependencies before beginning the rest of the upgrade.
If this isn’t done first, it can cause later builds to fail since the dependencies are no longer supported in newer versions.
Brightspot Enterprise 4.5 Developer Upgrade Guide → Resolve Unsupported Dependencies Guide
There are some dependencies that require intervention before the upgrade begins. These dependencies are invalid because they should have been materialized to begin with, and can cause cor...
Step 7: Brightspot Gradle upgrades
It is recommended to do this at the same time as the Brightspot dependency version upgrades.
Refer to the below guide for upgrading Gradle on the project.
Follow the documentation found in the Brightspot Gradle Plugins guide. Always use the latest version of the plugins, as listed at ...
Step 8: 4.5 Features
Every project being upgraded to 4.5 includes certain features that are added automatically. For other features, developer intervention is required. To view a list of all of these features, please refer to the 4.5 Product Guide.
Follow the below guide for more information on implementing these features.
Brightspot Enterprise 4.5 Developer Upgrade Guide → Adding 4.5 Features Guide
Brightspot version 4.5 introduces multiple new features. For a complete list, see the Brightspot 4.5 Product Guide. While many features are automatically included with the new version, others require ...
Step 9: Post-Upgrade Verification
After completing all previous steps, we will fix some known errors that arose during the 4.2 to 4.5 transition.
Brightspot Enterprise 4.5 Developer Upgrade Guide → Post-Upgrade Verification Guide
Duplicate Dashboard Search Widget SearchDashboardWidget was reworked and moved from project to platform code in Brightspot 4.5. Projects upgrading from Brightspot 4.2 will have a duplicate Search dash...
Step 10: Brightspot Cloud Upgrades
For customers hosted on Brightspot Cloud, follow the below guide for upgrading your Java version and Tomcat container version.
Brightspot Enterprise 4.5 Developer Upgrade Guide → Java 11 / Tomcat 9 Upgrade Guide
You can upgrade a project without performing a full upgrade. There are some limitations based on versions, which is covered in the prerequisites section below. Prerequisites Gradle versio...
Upgrade Github Actions workflows
Contact your account representative for an updated Github Actions Workflow implementation.