Migration

Overview

The Brightspot Migration plugin provides developers with a toolkit to rapidly migrate legacy data sources into Brightspot. The following sections detail the steps to extract, transform, and load existing content using this plugin.

Out of the box the plugin supports migration from any 3rd party SQL database into Brightspot, and support for content manipulation of an existing Brightspot installation.

Migration is performed by creating your own concrete Java classes from the abstract classes provided by the plugin and implementing the methods necessary to satisfy your project’s requirements. The Brightspot Migration plugin provides the framework and CMS interface for controlling and reporting your migrations.

Data Sources

The Brightspot Migration plugin provides straightforward solutions for:

• WordPress
• Drupal
• Adobe Experience Manager
• Custom Relational Databases (JDBC)
• Custom REST API
• Brightspot to Brightspot

Mapping between these data sources and Brightspot content types is done in custom Java classes created for this purpose.

Basic Migration

Migration is performed in four discrete steps, executed by four Java “Migrators”:

1. ID / Base
2. Joining
3. Referenced Content
4. Copy / Index

ID / Base Migrator

The ID Migrator simply catalogs all content in the legacy database, determines the primary identifier for that content (a URL, an auto-incrementing ID, a UUID, etc.), and maps it to a new Brightspot ID. This mapping is permanent, and is not overwritten during subsequent migrations.

The Base Migrator provides the initial transformation of legacy data into Brightspot objects. These two functions are implemented as SQL statements and a simple transformation method.

Example:

public class StoryMigrator extends
        SqlBaseMigrator<StoryMigrator.LegacyData, Story> {

    @Override
    public Story createObject(MigrationContext context,
            LegacyData data) {

        Story story = new Story();
        story.setTitle(data.title);
        story.setBody(data.text);
        story.setPublishDate(data.created_dt);
        story.as(MigrationObjectModification.class)
            .report("Changed legacy article '" + data.title + "' to Article.");

        return story;
    }

    @Override
    protected String getIdsQuery(int limit, long offset, Long after,
            String legacyId) {

        return "SELECT id, modified_on"
            + " FROM articles"
            + " ORDER BY id"
            + " LIMIT " + limit
            + " OFFSET " + offset;
    }

    @Override
    protected String getDataQuery(int limit, long offset,
            Long after, String legacyId) {

        return "SELECT id, author_id, title, text, created_dt,"
            + " modified_dt FROM articles"
            + " LIMIT " + limit
            + " OFFSET " + offset;
    }
}

Joining Migrator

The most common use case for the Join Migrator is a legacy database that has 3 tables (for example, Story, Category, Story_Categories) in which Story_Categories maps the rows in tables Story and Category with each other. Tables Story and Category will have been mapped in separate SQL Base Migrator subclasses and our Join Migrator will pull from Story_Categories and return the references needed to associate the content within Brightspot.

Example:

public class StoryCategoryJoinMigrator
        extends SqlJoiningMigrator<StoryCategoryJoinMigrator.LegacyData,
        Story> {

    @Override
    protected String getJoinQuery(int limit, long offset,
            Long after, String legacyId) {

        return "SELECT article_id, category_id"
            + " FROM object_category"
            + " ORDER BY article_id LIMIT " + limit
            + " OFFSET " + offset;
    }

    @Override
    public void doJoin(MigrationContext context, Story story,
            Collection<StoryCategoryJoinMigrator.LegacyData> data) {

        data.forEach(row -> {
            String categoryId = "category:" + row.category_id;

            Category category = context.findReferenceByLegacyId(
                    CategoryMigrator.class, Category.class,
                    categoryId);

            if (tag != null) {
                story.addCategory(tag);
            }
        });
    }
}

Referenced Content Migrator

This optional migrator is used in cases where the legacy data extracted in your SQL Base Migrator subclass is known to have content embeded in it that will also need to be migrated as content into Brightspot.

In our example we are migrating content from an articles table in a legacy database. Inside the text column there are references to images that we know will have to be parsed out and saved as unique Image instances in our Brightspot CMS. A Reference Migrator would be used to do this part of the migration.

Example

Reporting

As you can see in the first example above in the createObject method, the MigrationObjectModification#report method is invoked to add a report action to the generated migration report. This report is available as a CSV download.

There is no limit to the number of report actions you can add. If your migrator is doing a number of things, some of them conditionally, you should add a report action to see what the migrator would do when executed - or what it did after execution.