6. Work on the delta

Goal

Create your own extra migration tasks that do all the delta change that the initial migration did not cover. Keep editing and running these extra tasks until you get rid of the delta.

Time

This is the most time-consuming part of the migration. You need to go through the page and component templates you found in your earlier estimation. If the initial migration tasks manage to migrate much of your configuration and content then you have less work to do here. Note that if substantial areas of configuration fail to transform, you may have to create extra migration tasks.

Add extra tasks to your version handler

The migration report contains information about changes you still must be done in configuration and content. Create extra update tasks for these changes in your version handler.

Example: Creating new areas

The migration report says you need to create two new areas.

The migration tool may generate code that you can use in your update task. You can find such code in the report. Here is an example what the tool suggests you add to your update task to create the new areas.

register(DeltaBuilder.update("VERSION","")
  .addTask(new AddAreaTask("Add an area","Add an area teaserGroupItems to template acmeEventGroup", 
    "acme-website", "config", true,
    "/modules/acme-website/templates/components/teasers/acmeEventGroup", "teaserGroupItems",
    new HashMap() {{ // properties
      put("description", "");
      put("title", "");
      put("templateScript", "/templating-kit/components/teasers/teaserGroupItems.ftl");
    }},
    new HashMap() {{ // availableComponents
      put("acmeTeaserEventsList", "acme-website:components/teasers/acmeTeaserEventsList");
    }}
  ))
  .addTask(new AddAreaTask("Add an area","Add an area teaserGroupItems to template acmeTeaserGroup", 
    "acme-website", "config", true,
    "/modules/acme-website/templates/components/teasers/acmeTeaserGroup", "teaserGroupItems",
    new HashMap() {{ // properties
      put("description", "");
      put("title", "");
      put("templateScript", "/templating-kit/components/teasers/teaserGroupItems.ftl");
    }},
    new HashMap() {{ // availableComponents
      put("acmeTeaserInternalGroupItem", "acme-website:components/teasers/acmeTeaserInternalGroupItem");
      put("acmeTeaserExternalGroupItem", "acme-website:components/teasers/acmeTeaserExternalGroupItem");
    }}
  ))
}

Read the code generated by the tool and see if it makes sense. Integrate it into your own update tasks. Based on the code above, your update task could look like this.

.addTask(new AddAreaTask("Add teaserGroupItems area to acmeEventGroup",
   "Add an area teaserGroupItems to template acmeEventGroup", "acme-website", "config", true,
   "/modules/acme-website/templates/components/teasers/acmeEventGroup", "teaserGroupItems",
   new HashMap<String, String>() {
      { // properties
         put("description", "Event Group Area");
         put("title", "Event Group Area");
      }
   }, new HashMap<String, String>() {
      { // availableComponents
         put("acmeTeaserEventsList", "acme-website:components/teasers/acmeTeaserEventsList");
      }
   }))

.addTask(new AddAreaTask("Add teaserGroupItems area to acmeTeaserGroup",
   "Add an area teaserGroupItems to template acmeTeaserGroup", "acme-website", "config", true,
   "/modules/acme-website/templates/components/teasers/acmeTeaserGroup", "teaserGroupItems",
   new HashMap<String, String>() {
      { // properties
         put("description", "Teaser Group Area");
         put("title", "Teaser Group Area");
      }
   }, new HashMap<String, String>() {
      { // availableComponents
         put("acmeTeaserInternalGroupItem","acme-website:components/teasers/cpTeaserInternalGroupItem");
         put("acmeTeaserExternalGroupItem", "acme-website:components/teasers/cpTeaserExternalGroupItem");
      }
   }))

Working on the delta

The delta is the remaining changes that the module did not do automatically. Do multiple iterations running and editing the tasks in the version handler until the delta is also covered. This is the most important part of the migration effort. Expect to spend most of your time here.

Iterating

Iterate through every page on the site. One iteration covers one page:

1. Open the page
2. Identify what is broken.
   
   • If something needs to be changed in the template script, change the template script.
   • If something needs to be changed in the configuration, update the configuration manually (.pdf) and check the result. Add a task that reflects this change in the version handler.
   • If something needs to be changed in the content, change the content manually and check the results. Add a task that reflects this change in the version handler.
   • If something needs to be changed in the Java code, update the Java code.
3. Proceed to the next page. Keep iterating until you have gone through all the pages on the website.

Theme migration

If you have an STK-based theme, you need to migrate it. See How to migrate your STK theme.

Results

• Your extra migration tasks are done. They contain all the changes in the delta which the initial tasks did not complete.
• Changes to template scripts and Java code are stored directly in your project.

Documentation

• Migrating template scripts explains what changed in template scripts.
• Template Migration Reference (.pdf) summarizes the most important configuration and template script changes.
• Pages reference lists configuration properties you can use in a page template definition
• Areas reference lists configuration properties you can use in an area definition
• Components reference lists configuration properties you can use in an area definition

Next step

7. Test extra migration tasks