Transmogrifier Basics

In this section you will:

  • Learn the basic pipeline setup
  • Install the necessary add-ons
  • Create a migration package

Transmogrifier Setup and Terminology

  • The import is set up by creating a pipeline. The pipeline is a series of steps, each pointing to a blueprint. The blueprint is the Python code that is run for that particular step in the pipeline. Each item being imported runs through the full pipeline before moving on to the next item.

  • If you have an older Plone site, your content is likely using Archetypes-style content types. Newer Plone sites use Dexterity, so a large part of the upgrade process is moving to Dexterity content types. The steps and add-ons in this training will set up Dexterity-style types.

  • A jsonify export is built so that folders are exported before their containing items. The path to each item is included in the data, and this is what Transmogrifier uses for building the new site’s structure. If you leave all the paths alone and import all items from the old site, you should not end up with any broken links!


A few add-ons are needed for running Transmogrifier. With the package you create in the next step, these will be automatically installed. Note there are more than just these packages available, depending on what you are doing with your import.

  • collective.jsonmigrator (for migrating from json)
  • transmogrify.dexterity
  • collective.transmogrifier - a dependency of transmogrify.dexterity

Create a Migration Package

With mr.bob and bobtemplates.migration, you can quickly set up a package for handling migrations:

$ pip install bobtemplates.migration
$ mrbob -O ploneconf.migration bobtemplates.migration:jsonify

This command will ask a few questions about the author (you), and what version of Plone you want to use. Check for the latest version.

The created package can be used as an add-on in an existing buildout, or as a buildout on its own. For this training, we’ll use it on its own. Follow the instructions below to get a sample Plone site running. You can use Python 3 if you are creating a Plone 5.2+ instance.

$ cd ploneconf.migration
$ virtualenv env --python=python2.7
$ env/bin/pip install zc.buildout
$ env/bin/buildout
$ bin/instance fg

This will start up the instance in foreground mode for you, and will be accessible in your browser at http://localhost:8080. Click the ‘Create a new Plone site’ button, and create a site with the id Plone.

Next: Before Import