Items as resources by Sitecore part 5: Gutter

Jan Bluemink | 27-06-2023

When working as a Sitecore developer with items as resources (IAR items), it would be helpful to have a functionality that allows you to identify which items are IAR items and determine if they have been overwritten. Additionally, it would be great to see the changes made to an overwritten IAR item.

In this blog post, we will explore how the Gutter feature in Sitecore can provide this functionality.

Creating an IAR Gutter

With Sitecore PowerShell, you can easily create a Gutter. For detailed instructions on creating a Gutter, a number of articles are recommended. Be sure to check out Sitecore’s PowerShell integration points content editor. To detect if an item is a resource file and if it has been overwritten, check out the Items as resources PowerShell Content Editor Warning. To compare IAR items, read Items as resources by Sitecore part 4: compare, and to understand how to read IAR .dat files, go to Items as resources by Sitecore part 2: reports.

By combining the above resources, you can create an IAR Gutter in Sitecore PowerShell.

Sitecore Items As Resources gutter

The challenge

The Gutter feature is straightforward, but it also allows you to perform additional actions on click. Nice to have if you click on an overwritten item and want to perform a comparison. The code for the comparison is explained in "Items as resources by Sitecore part 4: compare". However, to execute the code, you need to know which resource file the item is stored in. Accessing the resource file data loaded in the Sitecore Kernel is not possible, or at least I don’t know how to do it. Ideally, Sitecore should provide a public comparison method for more efficient operations. As a workaround, you can find the resource file for an item by opening each resource file one at a time until you find the item. Surprisingly, this process is fast and only needs to be performed when you click to perform a comparison. Bonus feature, this displays the resource file location when clicking on a non-overwritten item.

You can find all the PowerShell code on GitHub.

Sitecore Items as Resources Gutter compare

Installation

After creating the IAR Gutter PowerShell items (by installing the "items.master.iaroverwrittenreport.dat" or pushing the serialized item to Sitecore), follow these steps to activate the Gutter:

In the Sitecore Shell, click the "start" button in de bottom left corner.
Click "Rebuild the script" integration points.
Open the PowerShell Toolbox.
Enable the IAR gutter in the Sitecore Content Editor by right-clicking on the left side of the Tree and selecting "IAR Gutter".

You are now able to use the Gutter. All the PowerShell code related to the Gutter and more, can be found on my GitHub.

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.

XM-Cloud-PowerShell-logfile

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

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.

Want to know more?

Want to read more technical blogs from Sitecore MVP Jan Bluemink? You might find these interesting:

blog

Migrating Your Content Seamlessly: A Comprehensive Tech Guide from WordPress to Sitecore XM Cloud

blog

(Web)hooked on a feeling

blog