mr.migrator 1.0b5

Build your own pipeline

see collective.transmogrifer pipelines for more details.

Once you’ve created your pipeline .cfg you can use it on the commandline via

migrate --pipeline=mypipeline.cfg

or if installing via buildout

[migrate]
recipe = mr.migrator
pipeline = mypipeline.cfg

If you’re using blueprints in your pipeline you will need to ensure that zcml configuration that registers them is executed. If you are using buildout you can use the following

[buildout]
parts += mr.migrator

[migrator]
recipe = mr.migrator
pipeline = mypipeline.cfg
eggs = transmogrify.sqlalchemy
zcml = transmogrify.sqlalchemy

This will ensure that the package that contains the blueprints is downloaded and the zcml for it is run before the pipeline is run so that the blueprints are registered.

If you aren’t using buildout you can will need to tell the runner which packages to load zcml in via

migrate --zcml=transmogrify.sqlalchemy,transmogrify.other

If you the blueprint package includes the following entry_point you can skip the zcml settings above

entry-points = {"z3c.autoinclude.plugin":['target = transmogrify']}

There currently isn’t a way to run a custom pipeline if using the Plone plugin. You will have to register it as below.

Using a Registered Pipeline

If a pipeline has been registered inside another package via zcml such as

<configure
    xmlns="http://namespaces.zope.org/zope"
    xmlns:transmogrifier="http://namespaces.plone.org/transmogrifier"
    i18n_domain="collective.transmogrifier">

<transmogrifier:registerConfig
    name="exampleconfig"
    title="Example pipeline configuration"
    description="This is an example pipeline configuration"
    configuration="example.cfg"
    />

</configure>

and the package has an entry point that will enable the zcml to be loaded such as

entry_points = {"z3c.autoinclude.plugin":['target = transmogrify']}

Then you can get mr.migrator to run that pipeline via

migrate --pipeline=exampleconfig

or

[migrate]
recipe = mr.migrator
pipeline = exampleconfig

An example of a package which declares a pipeline designed to be overridden is funnelweb.

Controlling Logging

You can show additional debug output on any particular set by setting a debug commandline switch. For instance to see see additional details about template matching failures

$> bin/mr.migrator --template1:debug

Working directly with transmogrifier (advanced)

You might need to insert further transformation steps for your particular conversion usecase. To do this, you can extend a plugins underlying transmogrifier pipeline. mr.migrator uses a transmogrifier pipeline to perform the needed transformations and all commandline and recipe options refer to options in the pipeline.

You can view pipeline and all its options via the following command

$> bin/mr.migrator --show-pipeline

You can also save this pipeline and customise it for your own needs

$> bin/mr.migrator --show-pipeline > pipeline.cfg
$> {edit} pipeline.cfg
$> bin/mr.migrator --pipeline=pipeline.cfg

Customising the pipeline allows you add your own personal transformations which haven’t been pre-considered by the standard mr.migrator tool.

See transmogrifier documentation to see how to add your own blueprints or add blueprints that already exist to your custom pipeline.

Using external blueprints

If you have decided you need to customise your pipeline and you want to install transformation steps that use blueprints not already included in mr.migrator or transmogrifier, you can include them using the eggs option in a mr.migrator buildout part

[mr.migrator]
recipe = mr.migrator
eggs = myblueprintpackage
pipeline = mypipeline.cfg

However, this only works if your blueprint package includes the following setuptools entrypoint in its setup.py

entry_points="""
      [z3c.autoinclude.plugin]
      target = transmogrify
      """,
      )