bricksModule providing a toolkit for developers to implement new migrations in the extension that they develop.
Developed by

Clément Aubin

Active Installs5
1 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager


The migrator application has been created in order to help extension developers implementing migrations at the extension level. A migration can be anything from moving a document to executing a custom script on the wiki ; the migrator application just provides a framework for performing that kind of tasks and a couple of helpers for the most standard migrations that you can encounter.

For any feature request or bug report, please don't hesitate to create a ticket on JIRA.


To use this extension add a dependency to it in your the extension requiring migrations. You can either depend on this extension as a whole or depend only on some specific migrator so that you don't need to bring the code for all the migrators.


List all the extension ids available here

How does it works?

The migrator application hooks to the extension manager by default. Just after an extension upgrade is performed, the application checks whether it has any migration to perform for its current version. If so, the migrations are applied on the fly, completely transparently from a user point of view.

Once a migration has been applied, the unique identifier of this migration is stored in order to prevent the migration to be applied twice by mistake.

Creating new migrations

In order to create a new migration, you should instantiate a new migration descriptor. This descriptor holds every information needed for a migration : the extension ID and the extension version targeted by the migrator and the parameters of the migration itself (which can change depending on the migration that is executed). The descriptor has also a type, which indicates the type of migration that he describes. Example of migration types are:

  • XClass migrations : move XObjects from one XClass to another
  • XObjects migrations : make sure that certain XObjects are present or absent
  • Document migrations : ensure that some documents are deleted or renamed
  • Script migrations : run a defined script

In the scope of the Migrator Application, those migration types are instantiated as "migrators", for example, an "XClass migrator" is a set of components and tools that help to perform XClass based migrations.

The way migration descriptors have to be defined depends heavily on the migrator that you want to use (XClass, XObjects, Document, Script, …). For migrators provided by default by the Migrator Application framework, the creation of a migration descriptor is performed by instantiating XObjects having specific XClasses. For example, to create a migration descriptor for an XClass migration, you will have to add an XObject of XClass Migrator.Migrators.ClassMigrationClass.

Once a migration descriptor is created, a unique identifier is computed for this descriptor and will be used to track whether the migration it describes has been applied or not in the end users wikis. To see how migration descriptor UUIDs are being generated, see the source of AbstractMigrationDescriptor.

If you want to create new migrations, we advise you to use the Migrator Application Development Toolkit.

Default Migrators

The following section describes the migrators provided by default by the Migrator Application and how they can be used. Those migrators will all implement the following properties in order to fit into the migration framework:

NameDescriptionDefault valueSince
Migration nameThe name of the migration-1.0
Migration descriptionA short description of what the migration does-1.0
Extension IDThe ID of the extension (groupId:artifactId) concerned by the migration-1.0
Extension versionThe version of the extension concerned by the migration-1.0

Class Migrator

The class migrator aims to help you moving from one XClass to another while also migrating the XObjects that implement the old XClass. The class migrator is implemented by defining an XObject with the XClass Migrator.Migrators.ClassMigrationClass. The XProperties of this class are explained in the table below.


NameDescriptionDefault valueSince
Old XClass referenceThe reference of the old XClass that should be migrated-1.0
New XClass referenceThe reference of the new XClass-1.0
Remove old XClass?Should the old XClass document be removed once the migration of the XObjects is complete?false1.0
Remove old XObjects?Should the old XObjects be removed once they have been migrated to the new XObjects?false1.0
Properties mapping

A mapping allowing you to rename the properties of the old XClass to the new ones. By default, the migrator will migrate every property of the previous XClass.


Document Migrator

since 1.1


Doc to write

Script Migrator

since 1.1


Doc to write

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki


Dependencies for this extension (org.xwiki.contrib:application-migrator-development-ui 1.0):

  • org.xwiki.contrib:application-migrator-migrators-class-default 1.0
  • org.xwiki.contrib:application-migrator-migrators-document-default 1.0
  • org.xwiki.contrib:application-migrator-script 1.0

Get Connected