Items as resources by Sitecore part 6: translation files and update item definitions

Welcome to the sixth blog in my Items as resources-series. The first five blogs are linked at the bottom of this one. Today, I will tell you more about translation files and updated item definitions.

When using items as resources instead of items in the database, you can now easily identify the source of the item in XM Cloud, and likely also in the upcoming Sitecore 10.4. This is now possible out of the box in the content editor when the “Item source” option is checked in the Developer tab.

But it doesn't tell you if it is overwritten or if the item is spread across multiple files. Therefore, you can use the Find-overwritten-Sitecore-resource-items PowerShell scripts. This repository is now updated with support for items that live in multiple .dat files.

Translations in resource files

Sitecore XM Cloud is equipped with some IAR translation .dat files, for example, the items.master.jss.da-DK.dat. This file only contains versioned fields in the da-DK language, with some translations of fields defined in the items.master.jss. Thus, an item can be composed of multiple resource files. As far as I can see, these are only versioned fields that can be merged. When you want to compare an overwritten resource item against the database version, you get an incomplete comparison if you do not compare against all relevant files. Doing a comparison before you restore an overwritten resource item is still a fairly technical task with the Find-overwritten-Sitecore-resource-items. With the support of multiple files, the comparison is now also correct in such cases.

Load order

When the same item exists in multiple files, conflicts can arise where the value of a resource item is updated by another resource file. The load order is defined in the configuration. Each database has paths defined in the configuration under /dataProviders/dataProvider/param/protobufItems/filePaths. By default, it loads files from /App_Data/items/ first, then from /sitecore modules/items, and finally, inside a folder alphabetically.

When starting up Sitecore, you can view the load order in the log file and observe how many items are new or updated. 'Updated' means the item exists in an earlier loaded .dat file and will be replaced. Therefore, the load order is important.

Example log file ITEMS.MASTER.XE.EDGE.TARGET.DAT that updated an item

• 2328 13:03:05 INFO Resource merger: file C:\INETPUB\WWWROOT\SITECORE MODULES\ITEMS\MASTER\ITEMS.MASTER.XE.EDGE.TARGET.DAT, updated item definitions count = 1.
• 2328 13:03:05 INFO Resource merger: file C:\INETPUB\WWWROOT\SITECORE MODULES\ITEMS\MASTER\ITEMS.MASTER.XE.EDGE.TARGET.DAT, new item definitions count = 0.
• 2328 13:03:05 INFO Resource merger: file C:\INETPUB\WWWROOT\SITECORE MODULES\ITEMS\MASTER\ITEMS.MASTER.XE.EDGE.TARGET.DAT, updated shared definitions count = 1.
• 2328 13:03:05 INFO Resource merger: file C:\INETPUB\WWWROOT\SITECORE MODULES\ITEMS\MASTER\ITEMS.MASTER.XE.EDGE.TARGET.DAT, new shared definitions count = 0.
• 2328 13:03:05 INFO Resource merger: file C:\INETPUB\WWWROOT\SITECORE MODULES\ITEMS\MASTER\ITEMS.MASTER.XE.EDGE.TARGET.DAT, updated language definitions count = 1.
• 2328 13:03:05 INFO Resource merger: file C:\INETPUB\WWWROOT\SITECORE MODULES\ITEMS\MASTER\ITEMS.MASTER.XE.EDGE.TARGET.DAT, new language definitions count = 0.

The log tells you that the ITEMS.MASTER.XE.EDGE.TARGET.DAT include an updated item definitions that means an item in another resource file is ignored. In the Find-overwritten-Sitecore-resource-items PowerShell report you can find out in which files an item exists.

In this case item “Edge” from ITEMS.MASTER.XE.EDGE.TARGET.DAT is also in items.master.dat

To see the difference between the items.master.dat and the actual item you can do a comparison.

The Publishing target “Internet” is renamed to “Edge” and the Field “target database” is changed from “web” to “experienceedge”. Also, the Field “Publish to Experience Edge” is checked. This is the way Sitecore makes the items.master.dat suitable for Sitecore XP without edge and XM Cloud or Sitecore XP with edge. By adding the ITEMS.MASTER.XE.EDGE.TARGET.DAT that updated the item.

Furthermore, understanding the load order is critical, especially in scenarios where conflicts may emerge due to updates from different resource files. Beside adding translations to an resource item it is also possible to update other resource items by another resource item. this already happens with a standard Sitecore XM Cloud installation by ITEMS.MASTER.SXA.DAT and ITEMS.MASTER.XE.EDGE.TARGET.DAT

If you have any questions regarding this blog or the ones I published before in the Items as Resources-series, please feel free to contact me.