Items as resources by Sitecore part 4: compare

Jan Bluemink | 24-05-2023

When working with items as resources in Sitecore, it would be great to have a functionality that allows you to determine the changes between an overwritten resource item and the original resource item.

This blog post explains how to compare Sitecore items as resources and how to add the comparison functionality to the PowerShell report described in "Items as Resources by Sitecore - Part 2: Reports" and "Items as Resources by Sitecore - Part 3: Restoring".

IAR Item Compare

Sitecore's out-of-the-box comparison functionality includes a resource item cleanup feature. Originally designed for database cleanup during upgrades, it can now be used in XM cloud to restore all items or only those that are identical. The easiest way to use this functionality is by using the Sitecore CLI (Command Line Interface), The CLI itemres command.

For example:

PS C:\projects\sxa-starter> dotnet sitecore itemres cleanup --what-if --force
Starting cleaning up databases.
Processing...
What if mode is active. No changes will be made.

Cleaning up databases is finished:
Cleanup of resource items is finished for 'master' database. Removed: 3 item(s).
[master] [D] /sitecore/layout/Renderings/Feature/JSS Experience Accelerator/Page Content/RichText (9c6d53e3-fe57-4638-af7b-6d68304c7a94)
[master] [D] /sitecore/system/Settings/Services/Rendering Hosts/Default (dffee92b-0441-45a4-9207-67810b72bd46)
[master] [D] /sitecore/system/Settings/Foundation/Experience Accelerator/Multisite/Management/Sites (f78ec6be-d9ba-4595-b740-e801acdb0459)

Cleanup of resource items is finished for 'web' database. Removed: 0 item(s).	
Cleanup of resource items is finished for 'core' database. Removed: 0 item(s).

Note: the --what-if and –force options are currently only available in XM Cloud and not in Sitecore 10.3. However, these options will likely be introduced in the future Sitecore XP 10.4 version.

In addition to using the CLI, you can execute the cleanup process with PowerShell. For Sitecore 10.3, simply call the CleanUp command without any parameters.

$item = Get-Item -Path "master:\content\Home"
$result = [Sitecore.Resources.DatabaseCleanUp.CleanUpService]::CleanUp($true, $true)
$result

XM-Cloud-PowerShell-logfile

It is also possible to directly invoke the cleanup from the composite data provider.

$item = Get-Item -Path "master:\content\Home"
$itemcdp = [Sitecore.Data.DataProviders.CompositeDataProvider]$item.Database.GetDataProviders()[0]
$itemcdp.CleanUpCommonItems()

After executing the cleanup, the Sitecore log file provides a record of field changes, allowing developers to track and identify modified fields.

Build an overwrite resource item compare in Sitecore PowerShell

To build an overwrite resource item comparison in Sitecore PowerShell, we need a functionality that can compare specific items without relying on log file comparisons.

The process of comparing a resource item from a resource file with an item in the SQL Database involves iterating through the fields and comparing their values. Additionally, the reverse process can be used to identify any new fields.

Accessing the resource item requires opening the file in the same way as we did for the report. This is because Sitecore functionality is internal/private in the Sitecore.Kernel and not directly accessible. Within the resource file, fields are stored in two collections: one for shared fields and one for versioned fields. In the case of unversioned but language-specific fields, they are assigned version 0 in the resource file. Empty fields or those with default values do not exist in the resource file. You will find the source code on my Github.

Compare-report-example

However, there are some exceptions. In Sitecore’s own resources files on XM Cloud the items are stored in multiple .dat files, one for the item and for every language a separated file. This is not currently included in the PowerShell compare.

The Compare functionality in the PowerShell script Find-overwritten-Sitecore-resource-items compares a single item read from a resource file with the corresponding item in a Sitecore database. The purpose of this comparison is to identify any differences between the two versions.

The report does not apply filters to exclude obvious changed fields, such as the Updated datetime, Revision, or Updated by fields. Instead, it provides a complete overview of all differences found. With this comprehensive overview, you can make an informed decision on whether to restore the original resource item or leave it as it is.