uMirror is a very useful tool in the upgrade process of Umbraco.
In this post we will describe how to do it with Umbraco 7, but the process would be quite similar with another version.
If we have a large data structure with many dependencies or if we want to do some refactoring tasks during the update, it can be difficult, even impossible to update Umbraco only copying the new files and updating the database.
In addition, this process may take time, among its implementation, quality assurance, staging and else so on... During this time, the content keeps growing, and obviously we can’t stop it while we are preparing the new instance.
uMirror, in this case, allows us to keep in sync our fresh Umbraco instance (in different environments) with production, and be able to work with a clean Database and real data.
First, it is important to understand the basics concepts of uMirror and how it works. I invite you to have a look at its technical documentation http://our.umbraco.org/FileDownload?id=9316, is quite short and easy to understand.
uMirror will help us to migrate and mirror Umbraco content structure in a new installation of Umbraco, so, you will first have to prepare the structure of DocumentType in this new instance.
In most cases, this structure will be very similar to the previous one, but as we will map all properties’ DocumentType, it could be totally different.
To compare and synchronize content between instances, we must have a reference among them. To do this, we will add in each DocumentType (Umbraco 7), a new property where we will store the NodeId value from the previous instance. For example, we can use a numeric property called oldid.
Create an uMirror project
Once we have our DocumentType structure ready in Umbraco 7, we can start setting up the migration process. Obviously, the first step is to install uMirror in this instance.
To create a new uMirror project, just click the Create option in the uMirror context menu and fill the project name, for example MyProject.
XML File Path: we have to specify the path to the XML data source. In this example we will import Umbraco content, so that we can use as the data source the file umbraco.config from the old instance. We'll just copy it to the new instance, for example in the path: / App_Data / Old_Instance / ...
Parent Node: we need to specify where, in the Umbraco content tree, we want to import the data. In our case the tree is empty and we will choose the root node, but it could be any other node.
Document structure mapping
Now, we have to map the structure of the document.
If we take as an example, the following content structure:
We will begin by mapping the DocumentType Site. In the project’s contextual menu click on create and then choose the DocumentType, in this case Site.
Elements: XPath to select the element set we want to import from the XML file. In this example, we will select all the elements Site: //site. If we are working with the old XML schema, it would be //data [@nodeTypeAlias = 'Site'].
Primary Key: XPaths to select the value of the primary key. Here, we will use the @id attribute corresponding to NodeId value.
Node Nane: XPaths to select the value of the item’s name. We will use the @nodeName attribute.
Foreign Key Property: Foreign primary key value, in this case oldid.
Ignore Node Name: If you want to do not compare and update the value of the nodeName, it is not the case here.
Ignore Delete: If you only want to add and update content, but never delete it, it is not our case here, but it’s very useful if you want to synchronize content with a source with incremental data.
Here we will map all others properties of the DocumentType with their corresponding values in the element. If the property has the same name in both instances, uMirror will map it directly for us.
We will do the same process for the whole structure DocumentType.
In this example, we will obtain the following structures:
Now we can start the process. In the project context menu click Start and then click Go!
The uMirror process is an asynchronous task, you can close and open the browser, and the process will continue to work.
Once the process is completed, we can see in the Umbraco content section that our content has been imported.
We have our new Umbraco 7 instance in sync with our content.
Now, every time we will copy again the umbraco.config and run the process, uMirror will compare and update the content in our new Umbraco 7 instance.
In the second part of this post, we will see how uMirror is able to directly consult the umbraco.config file from the source and how we can synchronize related content and medias.