Help Center

Menu

Bulk upgrade components

The bulk upgrade components tool lets system administrators and root user upgrade DXP Components and Core Components found in standard page and content page asset types. This approach of synchronizing assets is best suited for creating template and component changes in a development environment and releasing them to a production site in batches.

A Bulk Component Upgrade Tool video demonstration is also available

How to use the Bulk Component Upgrade Tool

The tool is available from Tools  Bulk upgrade components in the Squiz Content Management toolbar.

For this tool to work, Component Service must be configured for your Content Management instance. Follow the steps in the Component Service tutorial to configure your Content Management instance to work with Component Service.

You’ll notice two sections on the screen when you load the interface.

Configuration section

This section lets you set up how the upgrade will run and what root nodes of your system will be impacted.

Report section

This section lets you view the last-run results of an upgrade test run in a CSV report.

Configuration section

The Configuration section lets you set up the upgrade scope.

Root nodes

Use the asset picker to select a root node from which the upgrade applies.

You can apply updates to multiple root nodes using Add to add more selections.

The number of root nodes you select and their relative depth directly affects the time it will take for the upgrade to finish.
Asset type

The All option is selected by default.

You can choose from Standard page and Content page if you only want to upgrade components selectively or limit the time needed to perform an upgrade.

Test-run only

This option lets you test the upgrade before you fully commit to upgrading the components beneath the selected root nodes.

This option produces an upgrade_component_report CSV that you can use to troubleshoot issues with an upgrade.

Start upgrade

Start the upgrade process based on the settings you have configured.

The asset tree depth of the root nodes selected affects how long the upgrade (test run or full upgrade) will take. Check the HIPO job status that appears to estimate when the upgrade will finish.

You should always do a test run before upgrading your components. Updates applied through the tool take immediate effect in your system.

How does the upgrade logic work?

Components are upgraded to the highest editable version of the component in the set, which has a schema compatible with the current content.

To better understand this logic, consider a scenario where you have a component with the following Editable and Renderable versions:

editable renderable versions

The component you want to upgrade has a renderable version of v1.0.0. Users can only edit this component if it has the following Editable versions:

  • v1.1.0

  • v1.2.0

  • v2.0.0.

Therefore an upgrade to the component is required so users can continue to use the component on pages.

During the upgrade, v2.0.0 was discovered to have an incompatible schema, so it failed the upgrade test. The good news is that both v1.2.0 and v1.1.0 both reported no issues. Therefore both versions are candidates for upgrade.

The tool attempts to upgrade to v1.2.0 because it is now the latest editable version. The upgrade stops at v1.2.0 because it satisfies the upgrade logic that the tool requires.

Based on this example, you might be able to anticipate what might happen if v1.2.0 also turned out to have problems. In this case, v1.1.0 is the only other editable version for the component. Therefore, given the scenario conditions, the upgrade tool would attempt to upgrade to this version and succeed.

Report section

If you select the Test-run only option, the Report section links to a CSV report generated by the upgrade tool. The report is replaced with the latest version every time you run a test.

The CSV report contains the following general asset information columns for each component detected as part of the upgrade process:

  • Asset ID

  • Asset type

  • Asset name

  • Asset status

  • Context.

Diagnostic information

The other columns in the CSV have useful details when working out problems identified for assets during the upgrade process.

Upgrade status

This column contains all possible upgrade statuses listed in alphabetical order and information about their related messages that appear in the Detail column.

Failed

The component was found to have a problem that prevented the upgrade from being applied.

Check the Detail column to learn more about the issue.

Not required

The component did not need to be upgraded because the current version of the component is still editable in the set.

These status details relate to the Not required status type:

The current version is the latest available, upgrade not required

The component is on the latest editable version in the set.

The current version is editable, upgrade not required

A later editable version is available in the set. However, the upgrade was not attempted because the current version of the component being used is also still editable.

Skipped

The component is not editable (and also might not render). However, an upgrade was not attempted because there was nothing to upgrade.

In other words, this is a "forewarning" status that could indicate subsequent upgrades will break because of these conditions:

  • The component has been removed from the set

  • No later editable version exists to upgrade to.

Upgraded

The component was upgraded without any issues.

Previous component ID

Shows the component ID before the upgrade was applied.

Three segments are included in the ID, which helps you identify the component set and component version you are upgrading.

component-set/[namespace/component-name]/version

component-set

The set in which the component was included.

namespace/component-name

Each component is identified in the Component Service by a namespace and the component’s name.

For example, a common namespace could be the name of the team or developer creating components shared with the Organization. In the case of Core Components included in a set, the namespace is squiz.

version

One of the Editable versions of the component shown in Component Service.

editable version highlighted

Updated component ID

The pattern described in Previous component ID applies to the updated ID.

You should expect the version segment to increment for assets with the Upgraded Upgrade status value in the report.

The version will not increment when any other status appears.

Detail

If the status shows anything other than Upgraded successfully or Latest available some action is required before the upgrade can be completed successfully.

Read Common upgrade failure root causes to learn how to interpret the messages reported by the upgrade tool.

How to give upgrades the best chance of succeeding

The main point to remember about upgrading components is that the component schema change determines whether a component can be updated or whether it requires manual intervention to resolve.

Suppose you only add new, optional fields to a component schema as part of an upgrade. In that case, the likelihood of an upgrade succeeding is quite high for that component. In some cases, newly added required fields that form part of an optional field group will not cause an upgrade to fail. This seemingly odd outcome happens because the parent field sets the validation conditions in such scenarios.

Common upgrade failure root causes

These common conditions will cause upgrade failures.

Changing field names that have data saved against the previous name

The most common error encountered is schema validation issues ending with the The required property '[property_name]' is missing root cause.

This error commonly appears when the field name is changed. For example, if a typo in a field name is fixed.

To fix this error, you need to use the Asset ID to locate the component, then edit the component schema manually and correct the field name in the schema.

Additional required fields are added

When a field is added to a schema, the conditions surrounding the field are validated like a user is updating the component. A required field, therefore, must have valid content in it and the upgrade process detects that the field is empty.

Validation conditions are changed

Changing conditions, such as the minimum or maximum length of a field or the pattern matching criteria, will result in previously valid data changing to invalid.

Enumerated field changes

Be careful with changing or removing enum values such as radio buttons or checkbox items. You can encounter a situation where only a subset of component instances can be upgraded because a schema change removed an enum option. In this situation, components with that value selected will not be upgradeable because the data saved against that value will be lost if the upgrade is applied.