Reading time: 5 min read
Sitecore Environment-Specific Items: Introducing "Item Patching"
Environment-specific Sitecore values for items.
The Challenge of Environment-Specific Items in Sitecore
Sitecore’s configuration factory is one of its most useful Sitecore features, allowing developers to separate configurations into multiple files and easily manage environment-specific settings using rule-based configuration (env:define and env:require).
When it comes to Sitecore items, there is no built-in solution for environment-specific values. Ideally, no setting or environment-specific value should be stored as a Sitecore item, but in reality, this is not always feasible, legacy solutions, modules such as Coveo’s, and even Sitecore Experience Accelerator (SXA) use configuration items that are specific per environment.
I have worked on many projects where it was virtually impossible to request a database restore from one environment to another. My first attempt to solve this situation was creating PowerShell scripts to fix the data when they moved across environments, but it was never a sustainable solution.
To address this problem, I created this module that allows environment-specific values to be managed within Sitecore items in the content tree. It allows us to manage only the differences as child items, making it easy and clear that environment-specific values are present.
This module proved extremely useful for Sitecore XM and XP. One of the main reasons I have built it was to have the ability to restore databases from higher environments with no hassle, however as a positive side effect there are two other benefits, which also applies to XM Cloud - moving data with packages, and managing all environment values in a centralized location which also can be source controlled.
Common Problems When Working with Sitecore Items Across Multiple Environments
Managing Sitecore items across multiple environments presents challenges:
- Database Restores: Restoring a production database to a lower environment should not require extensive reconfiguration and risks.
- Consistent Deployment: Serialized items should be deployed to all environments, including environment-specific settings.
- Package Installation: Moving packages between environments should not result in incorrect settings being applied (e.g., accidentally allowing web crawlers in lower environments).
Introducing the Solution: A Module for Environment-Specific Sitecore Item Management
A module that enables developers to define environment-specific values within Sitecore items. The module will automatically apply changes based on predefined configurations, ensuring a seamless data restore experience.
Key Features of the Environment-Specific Item Patching Module
- Environment-Aware Item Storage: Store environment-specific values alongside regular Sitecore items without interfering with Sitecore functioning.
- Automatic Application of Values: The module automatically updates items based on the environment when a package is installed or the server restarts.
- Simple Configuration: Developers can configure which items and environments are managed using a simple
.configfile.
How the Module Works to Manage Sitecore Item Variations per Environment
You can make any item in the content tree to be subject of environment-specific values. In the image below, we have some fields from “Settings” differing across environments.
- The module automatically generates additional environment-specific items (represented in gray in the image).
- Each environment-specific item stores only the difference between the main “Settings” item.
- The values can be applied to the main item based on events such as Initialize and Package Installed.
Getting Started with the Sitecore Environment-Specific Item Patching Module
The module is available on GitHub: https://github.com/robertobarbedo/Sitecore.Feature.ItemPatching
- Download the module.
- Add it to your solution.
- Configure.
- Edit the
ItemPatching.z.MyClient.configfile. - Define the environments used in your organization.
- Specify the locations and templates that will be controlled.
- Edit the
Configuration Settings for the Sitecore Item Patching Module
All project specific configuration can be done in App_Config/Include/ItemPatching.z.MyClient.config - there are pre-defined values to help understanding, they need to be replaced by your own project settings.
For Sitecore XM/XP you will need <add key="env:define" value="[dev,qa,etc]" /> in the web.config.
For XM Cloud you will need a project variable in your CM: $(env:ENVIRONMENT_NAME).
Settings
| ItemPatching.Environments | A list of all environments for your project. |
|---|---|
| ItemPatching.Environment | Note the difference is this setting is singular. It is used to match an ItemPatching Environment to an Actual Project Environment. |
| itemPatching > locations > location | These settings are used to scope the actions. You can define what template Item Patching will apply and in what parts of your content tree. |
| itemPatching > locations > location > path | Only descendants of path will be considered by the module. |
| itemPatching > locations > location > templates | Only items of the specified templates will have their environment-specific items created. |
How to Use the Module Within the Sitecore Content Editor
Once configured and deployed to your solution, the module provides two new buttons under the Developer tab in the Sitecore Ribbon:
Generate
- Creates all necessary items for configuring environment-specific values.
- These items should be serialized and pushed to source control if its original item is also serialized.
- Use generate only when you need to create a new item to generate environment gray items as children.
Apply
- Transfers values by copying the fields from the environment-specific item to the main item.
- For example, in a local environment, the module copies values from the "local" item into the main “Settings” item.
- This same action is triggered on the Initialize pipeline and Package Installed event.
Additionally, changes can be applied in any other custom situation by code, using ItemPatchingManager.Apply().
Final Thoughts on Simplifying Sitecore Environment-Specific Item Management
Managing environment-specific Sitecore items has always been a challenge, the module proved itself valuable by making it easy to manage the differences between environments. By automating the Apply execution, it becomes a seamless experience.