Unicorn Configuration Validation

unicornn
Unicorn is a great platform for tracking and propagating changes between environments. There is an incredible amount of flexibility in the configurations which is a great thing, however it’s really easy to mess up in an inconspicuous ways.

The most common ways I’ve seen that things get messed up are:

  • Dependencies are inaccurately defined
  • Paths tracked aren’t rooted in stock Sitecore items
  • Gaps in the tracked items exist (i.e. an untracked parent and tracked grandparent)
  • Typos

Unicorn is incredibly forgiving as far as handling these errors. There is an internal process that attempts to automatically apply dependencies implicitly that will most likely do the job for you. Often times these errors will not show up until someone tries to apply the configurations to an empty Sitecore install. This is definately not a situation you want to find yourself in while rebuilding a production environment in an emergency. It’s in your best interest to make sure that you’re building your tracked tree appropriately before it comes to that.

What can be done?

I propose a scripting solution. Sounds complicated? Yes it certainly was a challenging problem. When looking at unicorn configurations there’s a surprising amount of complexity that you need to take into.

  • Abstract configurations
  • Includes
  • Excludes
  • Excepts
  • Wildcards

It doesn’t take long for the configurations to become incredibly complex to manage.

Enter powershell

I’ve created a two step process to handle analyzing and reporting.

Step 1, building a model

The first step is to construct a trie style data structure to simulate a desired state of a unicorn configuration.
The script simply requires the root path which contains all your configuration files, it’ll automatically find all the Unicorn configurations wherever they are.
$tst = Get-UnicornModel.ps1 -Path “C:\Code\MyProject\ProjectRoot”

Gist for model building script found here

Powershellstructure
You can see here is a powershell object representation of /sitecore/layout/layouts
From here you can see some basic data about the desired state of your Sitecore environment.

  • Config – A list of configurations that track this item (it needs to be a list because multiple unicorn configs CAN track a single item
  • Node – Name of the node
  • Path – Path of the node
  • Parent – Object representation of parent node in the same format as this one
  • Database – Database the item is located in
  • Next – List of objects that represent the tracked children of this node

Important to note that this is in no way parsed from the yml files but rather implied by parsing configurations. Think of it as a desired state of your unicorn setup.

Step 2, analyzing the model

Once you have all this information at hand, it’s relatively easy to parse it looking for oddities. As it sits i am currently tracking three things.
Invoke-UnicornAssessment.ps1 -Trie $model -ErrorOnOrphans
Notice there are two switches to control the behavior of this script

  • -ErrorOnOrphans : Script throws an error when there are orphans detected
  • -ErrorOnDependencyMismatch : Script throws an error when the dependencies aren’t properly explicitly set

This is to control from your devops pipelines if you want to have this be a warning or a full stop error that halts progress.

Gist for analyzing script found here

  • Does a configuration have an unspecified dependency on another configuration?
  • Are there orphans? (item tracked, parent NOT tracked, grandparent tracked)
  • Root not part of default Sitecore

reportingerrors
Rootnodes
Using this model, the analysis can easily be expanded to track anything that you desire. For example, maybe you want to make sure that your developers aren’t tracking items under the home node, this can be easily implemented using this model

The end result

Now you can have confidence that your Unicorn configurations won’t have cronic problems as well as being able to finely control how Unicorn configurations are managed. Anyone, no matter your experience level with Unicorn can make mistakes setting this stuff up, now you can rest a little more easily :).