Migration

The migration feature allows Gentics Content.Node Administrators to migrate tags of pages, templates and object type definitions. The migration feature is divided into two parts. The Tagtype Migration and the Template Migration. This document will explain both types.

This feature is available with Gentics Content.Node Version 5.13.0 and later.

1 Tagtype Migration

The Tagtype Migration (TTM) feature allows Gentics Content.Node Administrators to map existing tags from one construct to another. A Tagtype Migration modifies the tags so that they match the structure of the selected tag type (construct) they will be mapped to during the migration process.

1.1 Access

The TTM is accessible using the action drop-down menu within page lists and template lists. Additionally it is also possible to access the TTM using the right click context menu within page and template lists. Furthermore the TTM can be accessed through the Tagtype definition top menu.

The feature tag typemigration must be enabled and the user must have the permission to create new tag types in order to access the TTM.

1.2 Configuration

1.3 Use Cases

The page ‘demopage.html’ contains the following legacy content tags:

Tag Keyword Tagtype
externallink1 Link [pagelink]
externallink2 Link [pagelink]
subnav Legacy Overview [legacyoverview]
content Text/HTML (long) [textlang]
teaserimage Legacy Image [legacyimage]

The goal is to migrate the content tags so that they no longer reference legacy tag types (constructs):

Tag Keyword Tagtype
externallink1 Aloha Link [gtxalohapagelink]
externallink2 Aloha Link [gtxalohapagelink]
subnav Overview [overview]
content WrappedContent [wrappedcontent]
teaserimage Bild [image]

This can be achieved using the Tagtype Migration. The user needs to input a mapping that defines which part values of the source tag should be mapped to the new tag type parts.

Example:

The source tag externallink1 tag type contains the following parts:

Part Keyword Part Type Description
vtl Velocity Basic velocity part with no value
template Text/HTML Basic velocity template with the velocity code
linkurl URL (page) Basic url page part for storing the url
class Text (short) Contains the css class
data Text (short) Legacy data attribute field value
behaviour Text (short) Legacy field for the link target

The target tag type contains the following part:

Part Keyword Part Type Description
vtl Velocity Basic velocity part with no value
template Text/HTML Basic velocity template with the velocity code
url URL (page) Basic url page part for storing the url
class Text (short) Contains the css class
title Text (short) Contains the link title
target Text (short) The link target

We can now use the Tagtype Migration to map the parts:


  linkurl -> url
  class -> class
  behaviour -> target

The vtl part cannot be mapped since it does not contain a value. The template part will not be mapped since we want to keep the template of the target tag type (construct). The data part type value will be omitted. The data from that part type will be deleted.

The migration job will migrate the tag externallink1 and externallink2. All other content tags will not be affected since no mapping has been specified for the corresponding tags.

1.4 References

Certain references to parts that are migrated using TTM are automatically updated during the migration process. The scope of these automatically updated references is limited to the tag type being migrated. This means that part references from other parts within the same tag will be updated automatically. References that are beyond the scope of the automatic reference update process, such as references to a part from another tag, must also be updated manually after the migration process has completed.

References to parts that are deleted during Tagtype Migration are not automatically updated and must be removed manually after migration.

1.5 Limitations

Part types of type Select (multiple) and Select (single) can only be mapped to another Select (single) / Select (multiple) part type when the target and source part types utilize the same datasource.

1.6 Allowed PartType Mapping Table

Part Type Value Classification Mappable To
Breadcrumb No value Not mappable
Navigation No value Not mappable
Table ext No value Not mappable
Velocity No value Not mappable
Checkbox Boolean value Boolean value
Datasource Datasource Datasource
Select (image-height) Legacy Type Not mappable
Select (image-width) Legacy Type Not mappable
DHTML Editor String value String value
HTML (custom form) String value String value
HTML (long) String value String value
Java Editor String value String value
Text String value String value
Text (custom form) String value String value
Text (short) String value String value
Text/HTML String value String value
Text/HTML (long) String value String value
HTML String value String value
List String value String value
List (ordered) String value String value
List (unordered) String value String value
Folder (Upload) FolderId FolderId
URL (Folder) FolderId FolderId
Overview Overview Overview
Select (multiple) Select multiple Select multiple
Select (single) Select single Select single
Tag (page) PageTag Ref PageTag Ref
Tag (template) TempateTag Ref TempateTag Ref
URL (file) FileId FileId
File (Upload) FileId FileId
URL (image) ImageId ImageId
URL (page) PageId, String value String value, PageId

2 Template Migration

The template migration allows the user to migrate pages by defining a mapping in between two templates. The user has to select the source template and after that the target template. After that step a mapping between the template tags of that template can be specified.

2.1 Use Case

Source Template:

Tag Description
css Text/HTML (long), Contains inline CSS
javascript Text/HTML (long), Contains a reference to the carouseljavascript tag
carouseljavascript Text/HTML (long), Contains inline javascript which updates a jquery carousel
content Text/HTML (long), In page editable tag that contains the main content
header Text/HTML (long), In page editable tag that contains the header content

Target Template:

Tag Description
inlinecss Text/HTML (long), Contains inline CSS
inlinejs Text/HTML (long), Contains inline JS
inlinejs2 Text/HTML (long), Contains inline JS
inlinejs3 Text/HTML (long), Contains inline JS
body Text/HTML (long), In page editable tag that contains the main content
headertext Text/HTML (long), In page editable tag that contains the header content

Mapping:

  • carouseljavascript → inlinejs3
  • css → inlinecss
  • javascript → inlinejs
  • content → body
  • header → headertext

This migration will modify all pages that use the source template. The tags in that page that were inherited by the non editable template tag will be renamed to the target template tag name. In our case the carouseljavascript tag will be renamed to inlinejs3. This will also affect the references to the carouseljavascript tag. All those references will be changed to inlinejs3. The construct id for the tags in the page will be changed according to the defined mapping. The migration will select the target construct / tagtype for the migration by examining the target template tag construct type.

2.2 Limitation

The Template Migration will only be applied for the parent Node of the template you selected first.

3 Post Processors

Following the migration process, custom post processors may be applied to migrated objects. To achieve this, an implementation of the interface com.gentics.api.contentnode.ttm.ITagMigrationPostprocessor must to be specified in the configuration. The implemented class must be able to be loaded by the Servlet ClassLoader.

The ITagMigrationPostprocessor interface provides method definitions for pages, templates, folders, files and images, all of which can be modified following the migration. The TtmMigrationRequest object is provided as well and can be used to retrieve the migration mapping parameters. A logger class is also available and logging calls made in the post processor will appear in the log file for the corresponding migration job.

Interface:


public interface ITagMigrationPostprocessor {
	
	/**
	 * Performs post-processing on a template following a tag type migration.
	 * 
	 * @param template
	 *            the template to apply the post-processing to
	 * @param request
	 *            the TtmMigrationRequest which initiated the migration process, containing the tag migration mappings
	 * @param logger
	 *            the tag type migration logger
	 * @throws NodeException
	 */
	void applyPostMigrationProcessing(Template template, TtmMigrationRequest request, Logger logger) throws TagTypeMigrationException;

	/**
	 * Performs post-processing on a page following a tag type migration.
	 * 
	 * @param page
	 *            the page to apply the post-processing to
	 * @param request
	 *            the TtmMigrationRequest which initiated the migration process, containing the tag migration mappings
	 * @param logger
	 *            the tag type migration logger
	 * @throws NodeException
	 */
	void applyPostMigrationProcessing(Page page, TtmMigrationRequest request, Logger logger) throws TagTypeMigrationException;

	/**
	 * Performs post-processing on a folder following a tag type migration.
	 * 
	 * @param folder
	 *            the folder to apply the post-processing to
	 * @param request
	 *            the TtmMigrationRequest which initiated the migration process, containing the tag migration mappings
	 * @param logger
	 *            the tag type migration logger
	 * @throws NodeException
	 */
	void applyPostMigrationProcessing(Folder folder, TtmMigrationRequest request, Logger logger) throws TagTypeMigrationException;

	/**
	 * Performs post-processing on a image following a tag type migration.
	 * 
	 * @param image
	 *            the image to apply the post-processing to
	 * @param request
	 *            the TtmMigrationRequest which initiated the migration process, containing the tag migration mappings
	 * @param logger
	 *            the tag type migration logger
	 * @throws NodeException
	 */
	void applyPostMigrationProcessing(Image image, TtmMigrationRequest request, Logger logger) throws TagTypeMigrationException;

	/**
	 * Performs post-processing on a file following a tag type migration.
	 * 
	 * @param file
	 *            the file to apply the post-processing to
	 * @param request
	 *            the TtmMigrationRequest which initiated the migration process, containing the tag migration mappings
	 * @param logger
	 *            the tag type migration logger
	 * @throws NodeException
	 */
	void applyPostMigrationProcessing(File file, TtmMigrationRequest request, Logger logger) throws TagTypeMigrationException;
	
}

Post processors can be specified by adding the following configuration to the node.conf file.


	$TAGTYPEMIGRATION_POSTPROCESSTORS = array();
	$TAGTYPEMIGRATION_POSTPROCESSTORS[0] = 'tdl.yourcompany.contentnode.TTMTestProcessor';
	$TAGTYPEMIGRATION_POSTPROCESSTORS[1] = 'tdl.yourcompany.contentnode.TTMTestProcessor2';
	$TAGTYPEMIGRATION_POSTPROCESSTORS[2] = 'tdl.yourcompany.contentnode.TTMTestProcessor3';

Each post processor has a unique id, which is defined as the array index of the $TAGTYPEMIGRATION_POSTPROCESSTORS array. The id also determines the order in which the post processors will be invoked.

During the migration process, the post processor(s) that should be applied following the migration can be selected in the user interface by activating the corresponding checkboxes.