Data Center Migration Plugin Module

Introduction

Data Center Migration provides two plugin points that can be used by plugin developer to integrate into the migration process

  • Exporter - used to add plugin data to a migration archive
  • Importer - used to read plugin data from a migration archive

Exporter

Registered export modules are called when the export process encounters one of three top level "scopes"

  1. Project
  2. PullRequest
  3. Repository

Export Context

In addition to the entity being exported an ExportContext is also supplied to the relevant method. The export context can be used to add data to the export archive, add errors, warnings and entity mappings to the export job.

Importer

When the import process encounters an entry that is the responsibility of a Importer either the onArchiveEntry or onEntry will be called depending on the type of entry encountered. This will allow the importer to access the content of the entry and perform the import.

Import Context

An ImportContext is used to add errors, warnings and provide entity mappings to the import job.

Entity Mappings

Bitbucket provides no guarantee the ID's of entities being imported and exported will be stable across instances. This is a problem because entities need to refer to each other e.g. a PullRequest references a Repository. The solution: ExportContext provides the concept of a MigrationEntityType that is supplied to getEntityMapping which provides a mapping between the original id of an entity on the source instance and the id of the entity on the target instance.

Configuration

The root element for the Data Center Migration plugin module is <migration-handler/>. It allows the following configuration attributes:

Attributes

NameRequiredDescription
keyYesThe identifier of the plugin module. This key must be unique within the plugin where it is defined.
exporterYes An exporter definition containing a fully qualified class name This class must implement Exporter
importerYes An importer definition containing a fully qualified class name. This class must implement Importer
weightThe (integer) weight of the plugin module. Migration handlers with a higher weight will be processed later. Third party plugins must use a weight greater than 100

Example

Here is an example for a custom Data Center Migration handler

1
2
3
4
5
6
7
8
9
10
11
12
13
<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
    <plugin-info>
        <description>${project.description}</description>
        <version>${project.version}</version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
    </plugin-info>

    <migration-handler key="ExampleMigrationHandler" weight="101">
        <exporter class="this.is.an.ExampleExporter"/>
        <importer class="this.is.an.ExampleImporter"/>
    </migration-handler>

</atlassian-plugin>

Weights

Third party plugins must use a plugin weight greater than 100