Description

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 XWiki.org JIRA.

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.

Parameters

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.

-1.0

Document Migrator since 1.1

Script Migrator since 1.1

Tags:
Created by Clément Aubin on 2018/09/15 20:36
    

Get Connected