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.
[!!] Migration task: Migrate Config
Task started at: 2013-01-10 17:54:41
Log records:
- [INFO] The task transforms every STK-based template definition (prototype, concrete template and paragraphs). The following steps are performed:
- Update properties to match the new convention.
- Create areas.
- Handle autogeneration (replace autoGeneratedParagraph nodes). - [SYSTEM] Starting to transform each STK-based template definition.acme-website
- [SYSTEM] [action] Please verify the definition: /modules/acme-website/templates/components/teasers/acmeEventGroup. It might be possible that you have to create areas from the subparagraph found in parameters.subparagraphs.
- [SYSTEM] [action] Please verify the definition: /modules/acme-website/templates/components/teasers/acmeTeaserGroup. It might be possible that you have to create areas from the subparagraph found in parameters.subparagraphs.
- [SYSTEM] Finishing to transform every STK-based template definition.acme-website
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:
- Open the page
- 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.
- 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