How to Implement a Custom Page Importer for the CQ5 Upgrade Tool

Question

How do I implement a custom CQ3.X or CQ4.X page importer?

See here for basic documentation on the upgrade tool itself

What is a page importer?

A page importer is an OSGi service that implements an import page method that gets called when a page of a specific csd type is requested from the CQ3.X or CQ4.x instance by the CQ5 Upgrade Tool. A single page importer can be implemented for multiple CSDs or for a single CSD type.

Prerequisite knowledge required for this article:

• How to Set Up the Development Environment with Eclipse
• How to create and deploy a bundle to Apache Felix

Answer, Resolution

Below are empty implementations of custom page importers. i.e. they won't import anything unless you create the nodes/nodetypes/mixins and properties for the page content you want to import.

Implement a class that imports multiple template CSD page types

import javax.jcr.Node;
import javax.jcr.PathNotFoundException;
import javax.jcr.RepositoryException;
import javax.jcr.Session;
import javax.jcr.Value;
import javax.jcr.ValueFormatException;
import javax.jcr.lock.LockException;
import javax.jcr.nodetype.ConstraintViolationException;
import javax.jcr.version.VersionException;

import org.apache.jackrabbit.util.Text;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.day.cq.commons.jcr.JcrUtil;
import com.day.cq.compat.migration.ImporterContext;
import com.day.cq.compat.migration.PageImporter;
import com.day.cq.compat.migration.contentbus.Atom;
import com.day.cq.compat.migration.contentbus.Container;
import com.day.cq.compat.migration.contentbus.ContainerList;
/**
 * The importer for all pages from daycare.
 *
 * @scr.component metatype="no" immediate="true"
 * @scr.service interface="com.day.cq.compat.migration.PageImporter"
 * @scr.property nameRef="PageImporter.PROP_CSD" valueRef="ALLCONTENTCSD"
 */
public class GenericContentPageImporter implements PageImporter {
    // this variable configures which template csds get processed by this page importer
    private final static String[] ALLCONTENTCSD = new String[] { "genericcontent",
        "globalhomepage",
        "localhomepage" };
  
    public Node importPage(ImporterContext context, Page page) throws RepositoryException {
        Session session = context.getSession();
        processPage(context, page, session);
        if (session.hasPendingChanges()) {
            session.save();
        }
        return null;
    }

    public void processPage(ImporterContext context, Page page, Session session) {
       //TODO: Implement import functionality here...
    }
}

Implement a page that imports a single CSD page type

import javax.jcr.Node;
import javax.jcr.PathNotFoundException;
import javax.jcr.RepositoryException;
import javax.jcr.Session;
import javax.jcr.Value;
import javax.jcr.ValueFormatException;
import javax.jcr.lock.LockException;
import javax.jcr.nodetype.ConstraintViolationException;
import javax.jcr.version.VersionException;

import org.apache.jackrabbit.util.Text;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.day.cq.commons.jcr.JcrUtil;
import com.day.cq.compat.migration.ImporterContext;
import com.day.cq.compat.migration.PageImporter;
import com.day.cq.compat.migration.contentbus.Atom;
import com.day.cq.compat.migration.contentbus.Container;
import com.day.cq.compat.migration.contentbus.ContainerList;
import com.day.cq.compat.migration.GenericImporter;
import com.day.cq.compat.migration.ProvidedPageImporter;

public class CustomPageImporter extends GenericImporter implements ProvidedPageImporter {
    CustomPageImporter() {
    }

    public String getCSDName() {
        return "mytemplatecsdname";
    }

    /**
     * Imports the given page into the Repository.
     * <p>
     * The difference to the base class implementation is, that the page
     * is actually not stored at the final destination as inidcated by the
     * page handle mapping but below <code>/var/dam</code> for where the
     * assets are picked up for them to be imported as a DAM asset.
     */
    public Node importPage(ImporterContext context, Page page)
            throws RepositoryException {
        
      //TODO: Implement import functionality here...
    }
}

Affected Versions

CQ5.2+