I decided to write a series of articles about Unicorn serialization and how to configure it in a Sitecore SXA project. This article is the first one in the series and is just a brief introduction to Unicorn explaining basic concepts, mostly directed towards people that used different serialization tools in the past and are just starting with Unicorn. If you are familiar with the basics you can jump straight away to part 2 where I cover serialization for SXA in detail. In the configuration examples, for the purpose of this article, I used Sitecore 9.0.2 with Unicorn 4.0.2 with Habitat Home Platform.

About Unicorn

Because Sitecore items are stored in the databases, the challenge during the development process is to keep the databases in sync between the developers working on the project and to move items between environments during deployments. This can be achieved in a few ways supplied out of the box with Sitecore e.g. creating Sitecore packages and sharing them after every update to an item, reserializing items and exchanging them or by sharing one local database with all people in the team. Unfortunately, the above solutions are error-prone, they are lacking packages versioning and can cause issues when two people work on the same item and try to merge their changes. This is why it is recommended to use serialization tools like Unicorn or TDS (Team Development for Sitecore).

Unicorn is an open source tool which allows performing Sitecore items serialization from the database to a file system, so they can be shared among developers using version control system like git. After the initial setup Unicorn allows to perform automatic serialisation of changes to the items when they are made in Sitecore. All of the serialized items are stored as text files with YAML extension.

Unicorn works together with Rainbow which is a library that supplies a set of interfaces which allow to wrap the Sitecore items structure and replace the Sitecore serialization format, file system organization and enables cross-source item comparison.

Unicorn serialization basics

The idea behind Unicorn is to serialize only items that you need, by adding their Sitecore item paths to Unicorn configuration files. When the item is controlled by Unicorn all the child – items can be serialized automatically unless excluded, which is very convenient because the developer does not have to remember to serialize items manually after every change they made. The exception is only for newly created items which should be reserialized in order to be stored in the file system correctly – it is called initial serialization and Unicorn will complain during the next sync if you forget doing it.

Every time you pull the code from GIT you should perform Unicorn serialization. Make sure that you committed all your new Sitecore items first, otherwise, you will lose all your changes. If the items are deleted during the Unicorn serialization, they are moved to the bin if it exists so it should be still possible to bring them back.

Unicorn serialization can be performed in two ways:

• Using URL https://yoursitedomain.com/unicorn.aspx (coming out of the box with Unicorn)

  

  An example list of Unicorn configurations in Habitat Home Platform.

  The unicorn.aspx page contains a list of configurations defined for the Sitecore instance and allows performing reserialization and sync for each of them separately or for all of them if there are more than one configurations defined. For each of the configurations, you have two options to choose: to reserialize items or to sync them. You can also click on “Sync all the things” to perform sync for all of the configurations at once.

  Sync operation means that we pull the newest version of the database to our local instance.

  Reserialization deletes all the serialized YAML files from the file system and serializes the local version of Sitecore items of the database to file system.

  From your local instance, after the initial reserialization, you always should perform sync operation only unless you know what are you doing! Reserialization of the particular Unicorn configuration should be performed only once during Unicorn initial setup or in case if data is malformed and need to be reinitialized. Using “transparent sync” option allows you skipping the pull & sync step during development because after pulling items from git the configurations will be synced automatically. By default, the transparent sync is switched off.

  Running sync through the unicorn.aspx page automatically publishes items (when the auto-publish feature is on) that got updated and runs re-indexing process which is important in case you serialized content items. Currently, synchronization from Visual Studio does not support this feature.

  For newly added items/fields, you should perform reserialization from Sitecore Content Editor only for the part of CMS tree containing items you added, otherwise you risk data loss. Unicorn by default integrates with Sitecore serialization and you can use the Developer tab on the ribbon to Serialize item or tree.

  

  Developer toolbar on the ribbon allowing serialization of Sitecore items.

  Be careful, if the parent item will not be synced first the child items may not be serialized and you will not see any exceptions. It is a good practice to click on one of the items intended to be serialized and check if you can see the yellow strap at the top of the item saying that it is controlled by Unicorn. If the item has been properly serialized you will see a path to the YAML file.

  Yellow strap presenting the information about Unicorn synchronization for the item.

• In Visual Studio from gulp tasks runner (only if you have Helix based solution with gulp build setup)

  Gulp tasks capable of running Unicorn sync in Task Runner Explorer

  To perform only Unicorn sync, right click on the Sync-Unicorn task and select “Run”. This task should be also by default invoked when you use “default” task in Helix gulp setup, so if you do the full project publish you do not need to run it separately. After running the sync check output in the console window if the synchronization succeeded.

YAML files and Serialization File System structure

YAML file is just a text file which stores basic data about the particular items, like item ID, parent item ID, template ID, item path, all fields in particular versions and languages. YAML files are human readable and quite easy to interpret which also makes them easy to merge or even edit manually in comparison to regular Sitecore serialization.

---
ID: "936350e1-6057-4250-986b-72be51833410"
Parent: "8a3283a7-2209-4f06-8eae-31f12eec322c"
Template: "0437fee2-44c9-46a6-abe9-28858d9fee8c"
Path: /sitecore/templates/Feature/Habitat Sites/Demo
DB: master
Languages:
- Language: en
  Versions:
  - Version: 1
    Fields:
    - ID: "25bed78c-4957-4165-998a-ca1b52f67497"
      Hint: __Created
      Value: 20171108T132710Z
    - ID: "5dd74568-4d4b-44c1-b513-0af5f4cda34f"
      Hint: __Created by
      Value: |
        sitecore\admin
- Language: "ja-JP"
  Fields:
  - ID: "b5e02ad9-d56f-4c41-a065-a133db87bdeb"
    Hint: __Display name
    Value: デモ
  Versions:
  - Version: 1
    Fields:
    - ID: "25bed78c-4957-4165-998a-ca1b52f67497"
      Hint: __Created
      Value: 20181024T125723Z
    - ID: "5dd74568-4d4b-44c1-b513-0af5f4cda34f"
      Hint: __Created by
      Value: |
        sitecore\admin

YAML file example.

Serialization File System (SFS) maintain Sitecore tree structure for serialized items and stores each included subtree in its own hierarchy. On the picture below you can find an example of the structure of the items serialized to disk. Notice, that for each item, which also is a parent item for other items e.g. Data, you can see the Data.yaml which defines the particular item, and a Data folder that contains all its children. It is not allowed to serialize items in Data folder without serializing Data.yaml too, but fear not – it does not mean that you have to serialize the whole Sitecore tree from the root items to the bottom. The root items in Unicorn configurations are relative so you can choose the item on which you would like to start the serialization from.

Example of items in the Serialization File System for Unicorn items.

The serialized items are stored in the file data store defined for particular Unicorn configuration. File data store is just a folder defined to be a parent of all the YAML files for a particular configuration. Because the configurations can be separated in this way you can keep the clean structure inside your different projects. This means that it is easy to keep the folder structure in line with Helix conventions.

More information about Unicorn:

https://github.com/SitecoreUnicorn/Unicorn

https://github.com/SitecoreUnicorn/Rainbow

https://kamsar.net/index.php/category/Unicorn

This is the end of the first part of the introduction to Unicorn. You can find part 2 about serialization for SXA in here.
Feel free to leave a comment below and let me know what you think or if there is anything you would like me to write about.