How to change content from one document type to another in Umbraco 8

One of the great things about Umbraco is its flexibility, but recently I hit a dead-end trying to refactor some existing content from one document type to another. It used to be possible to move between document types in Umbraco 7, but this Umbraco forum post and GitHub issue describe the problem developers face in Umbraco 8.

I had a relatively simple use case involving an existing Umbraco Cloud site, where I wanted to migrate about 50 content nodes from a generic "page" type - containing quite involved Grid content - to a new, more specific type. The new page type would have some extra fields (sorry, properties) but most importantly I wanted to move all the content to a new microsite, which would use different page templates and have different permissions to enforce a new parent/child structure.

Here's how I did it on an Umbraco Cloud project (version 8.14):

• Copy the existing document type to a new version.
• Alter the new document type, leaving alone any properties containing content I wanted to keep.
• Use a database script to find all the content nodes I wanted to migrate, and reassign them from the old document type to the new one.
• Test, and deploy to cloud environments, rerunning the migration script.

Step by step instructions

1.  First things first, get a local development environment - clone the source code (if you haven't already!) and download a recent bacpac of the database to work on. That way all of this can be done in safety.

2. Once you're up and running with a local build, find the existing document type - note its numeric id from the URL in the browser. (1087 in my example)

3. Copy the document type, move it or rename it to suit your new structure. Don't forget to rename the document type alias by unlocking the padlock to keep your code tidy.  Note the id of the new document type: it's 5979 here. If you're confident, you can alter the properties of the new document type now - there is no magic in the reassignment step in the database.

4. Get in the database (I'm old school and use SQL Management Studio, but other IDEs are available) and find all the documents to migrate - for me it is all the content (of document type 1087) that are descendants of a given node - (in this case node id 4756).

You can safely test you have the right documents by using this select statement - just update the magic numbers to suit your situation:

SELECT * FROM umbracoNode 
INNER JOIN umbracoContent 
  ON umbracoContent.nodeId = umbracoNode.id
WHERE (umbracoNode.path LIKE '%,4756,%') 
  AND (umbracoContent.contentTypeId = 1087)

When your select statement has the right list of documents you want to reassign, add in an update statement - this is the simplest code to read:

UPDATE umbracoContent
SET contentTypeId = 5979
WHERE (nodeId IN 
 (SELECT umbracoNode.id 
  FROM umbracoNode INNER JOIN
  umbracoContent AS uc ON uc.nodeId = umbracoNode.id
  WHERE (umbracoNode.path LIKE '%,4756,%') 
    AND (uc.contentTypeId = 1087)
 )
)

5. Check in the Content section of the backoffice - and it has worked!  I'm not sure what it's done to caches, previews and all the rest of it, so I rebuilt the Database Cache to be sure things don't get in a tangle on the public site.

6. Now change the properties of the new document type.  Actually, I didn't need to do much to make a difference, I removed some compositions we no longer needed and added in a couple of new fields. The biggest benefit of the document type reassignment is to be able to apply a new set of page templates specifically for this document type and change the permissions to enforce a new parent/child structure.

If you remove or rename any properties from the new document type, then any content documents will also lose these properties. This means this approach is limited - it is not a generic solution for content migration. But it is useful for "narrowing" the type of a document type or refactoring a set of existing content as the structure of a site changes.

7. Deploying the code

When you create or edit a document type, Umbraco Deploy (which is part of the Umbraco Cloud blackmagic to keep environments in sync) adds UDA files in the data/revision/ folder of your source control. So when you're done and commit your changes to source control those new document types become available in your Umbraco Cloud development environment.

You need to run the database migration script again, the instructions for connecting SQL Manager to Umbraco cloud databases are spot on, and don't forget to do a backup first.

Test on the cloud development environment first, and then do it again in live.

And finally

Although this site wasn't multilingual, I don't see why it shouldn't work on more complex content structures. However this technique is very much for migrating content types during site development or maintenance. It isn't going to help when you want to do more complex conversions of some bits of content between existing document types.

Maybe one day this will get taken out of the "too hard" bucket by the Umbraco core team, or maybe there's space for a really useful package to help with this?