The uSync Soft Shoe Shuffle

Heads Up!

This article is several years old now, and much has happened in Umbraco land since then, so please keep that in mind while reading it.

So I've been using uSync, the popular 'Umbraco database to disc' serialization tool created by Kevin Jump of Jumoo for about a year now; just really to put Umbraco doctype changes into git, so that I can work with other devs without a shared database, and to ease moving something I'm working on between my desktop and my laptop.

But everyone's doing that now, that's old hat, so what is this uSync Soft Shoe Shuffle that I've somehow volunteered to demonstrate for 24 days in Umbraco ? I hear you say...

Well it's akin to the tablecloth trick, you know whipping the tablecloth off of the table, and having most; ok ideally all of the plates and cups left on the table: smugly unharmed.

Let me try and achieve the same result as these kids but with uSync and Umbraco.

What do I mean ?

Well imagine you have a set of document types that a site has been running on for while and you suddenly realise there's some obvious commonality between them, and it would all be much neater if the doctypes inherited from a common parent doctype that defined the shared properties in one place.

We've all been there, maybe the client changed their mind after the point of sign off or something, it can happen; but the problem now is you can't easily change those doctypes with the site so full of content, without losing or mucking that content up. Or at least that's the vague premise for this experiment.

(Someone will comment below to say there is a package that just does this, so use whatever that is, but right now I'm just interested to see if this might work)

The experiment

So let me show you an example of a manoeuvre, that all the cool kids are calling 'The uSync Soft Shoe Shuffle':

I'm experimenting here on Umbraco 6 with one of the Umbraco 7 starter kits we backported for an Umbraco 6/7 demo a few weeks back.

  1. Install uSync

  2. Install uSync Content Edition

  3. uSync and uSync Content edition have configuration files in /config, that can be a little bit confusing at first, (and also after a while).

    To begin with we're going to set uSync to read="true", write="false", attach="true" and versions="false", this is generally how you would normally work with uSync.


    Any changes in the uSync files on disk will be 'read' into Umbraco, and uSync will attach itself to Umbraco events for when doctypes etc. change, and serialise those changes to disk.

    Similarly for uSync Content edition we will have import="true" and events="true", quite why Mr Jump didn't call those settings the same thing between editions, I don't know...

  4. On first install uSync and uSync Content edition will run through your Umbraco installation and serialize existing doctypes etc and content to your /usync folder on disk, have a look, they are there, open them up and see what they contain, can you guess what I'm going to do ?


    In the example site, there are 'Text Pages' and 'News Items' and these both have a common rich text editor property called 'bodyText'.


    I'm going to add a 'Content' doctype between 'Master' and 'News Item' and Master and 'Text Page', and move the bodyText Property to be defined only on the new Content doctype, without breaking any cups, glasses or plates.

Let the shuffle begin.

  1. First create the new Content, doctype, I'm giving it an alias of umbContent, remember that.


    then add the bodyText property

  2. Because uSync is running in attach mode you can see it has generated the Content folder under master, and the corresponding def.config file contains the serialised details of the new doctype on disk.

  3. We're now going to hack the uSync files directly on disk, so we're going to 'turn off' uSync and uSync Content edition - set read & attach to false, set import & events to false - break the web.config and reload the Umbraco site. (very important you do this)

  4. Go into the uSync folder on disc, copy the umbTextPage and umbNewsItem folders into the new umbContent folder.

  5. Now that uSync is safely turned off, delete all of the content on the site, yes ALL OF THE CONTENT. Delete it, that's what I said, do it now!

  6. Next delete the umbNewsItem and umbTextPage doctype, I know it's madness.

  7. You should now be getting a bit of a sick feeling in your stomach.

Waving the magic wand

  1. On disk open the corresponding def.config files for umbTextFile and umbNewsItem, find the bodyText property definition and delete it,


    locate the 'Master' property in the xml definition and change it from umbMaster to umbContent. This will make these doctypes inherit from the new umbContent doctype, and that is where they will pick up their bodyText property from.

  2. Now we need to turn on uSync (but NOT uSync Content edition) so in the uSync settings only set read="true", and break the web.config, refresh the site.

  3. Say the magic words: 'Reload the nodes', et voila: uSync should have recreated the umbTextPage and umbNewsItem doctypes, nested underneath the umbContent doctype, and things like structure 'shouldn't have been forgotten'

  4. Now we're nearly ready to pull the tablecloth, (I mean turn back on uSync Content edition), but first we don't want uSync Content edition to know it has had content before, and so we need to delete it's two mapping xml files which it uses to keep track of local id's between umbraco installs, and are stored in /app_data/temp:


Yanking the tablecloth

  1. We are ready, deep breath, count to 3, in the uSync Content edition config file set import="true" and break the web.config one last time, reload the content nodes, and Ta-dah! The content is back. 


    This works because uSync Content edition serializes content to disk based on doctype alias, and property name alias, in the example above, we haven't changed the doctype alias or the alias of the property name, we've just changed where they are defined and uSync Content edition doesn't really care about that.



So is this useful ? probably not, I was just wondering if it would work, and it sort of does, but I'm not recommending you try this on a live site, plates and hearts will get broken; but hopefully I've managed to give you a bit of an insight into the way that uSync and uSync Content edition work together.

Right well that about wraps it up for the uSync Soft Shoe Shuffle, the cool kids are all here now and they're drinking eggnog and beckoning me to join them, so I'll wish you all a Merry Christmas and leave you with the sounds of the excellent Joe Loss and his Orchestra, and their version of the Soft Shoe Shuffle:

take it away Joe...


Thanks to Kevin Jump for uSync.

This was a:




Marc Goodson

Marc is on Twitter as