Using the Collage to Cascade Server CMS Migration Tool

Introduction

The Collage to Cascade Migration Tool is a GUI migration tool, designed much like a familiar wizard. This guide is designed to walk you through using the tool and migrating your website from Serena Collage to Cascade Server. You can also request to see the Migration Tool in action.

Before Getting Started

In order to use our the Migration Tool, you will first need to create an XML export of all of the content that you would like to migrate from your Serena Collage site to your Cascade Server Site. It is important to note that prior to migrating your content, the infrastructure of your site in Cascade Server should be completely functional. In other words, all Content Types, Metadata Sets, and Data Definitions have to be in place.

In addition, we recommend that you create a spreadsheet of all of your Asset Types in Serena Collage. The spreadsheet should outline the folder in which these Serena Asset Types reside, the fields the Asset Types contain, and the Content Types in Cascade Server to which your Serena Asset Types will be mapped.

Requirements

Before using the Migration Tool, please make sure:

• You have administrative rights in Cascade Server. The tool cannot be run without administrative privileges.
• You are operating an instance of Cascade Server that is of version 6.2.1 or newer. When using the tool, the website to which you will be migrating content must be organized in a formal “Site” in Cascade Server, rather than housed in the Global Area.

Instructions

To install the Serena Migration tool, extract the zip file to the machine from which you want to run the tool. In the migration folder that will be created upon extraction of the zip file, you will see a “tomcat” folder containing the following subfolders:

The “bin” folder contains the executable files for starting and stopping the tool. Double-clicking “startup.bat” (in the “bin” folder) will enable you to run the tool and “shutdown.bat” will terminate it. In order to avoid having to navigate to these executable files each time, we recommend that you create a shortcut to both of them and put them on your desktop or in your startup menu.

When you run “startup.bat”, you will see that a “Tomcat” window appears:

Because the Migration Tool is a web application, it is important to keep Tomcat running while you are using the tool, as it serves as the tool’s servlet container. You can terminate Tomcat and hence, the tool, by double-clicking on the “shutdown.bat” shortcut at any time.

Once Tomcat is running, open a web browser and go to the following URL: http://localhost:8081/

Note: As you can see, the tool uses port 8081, so please make sure that you do not have any other processes running on this port.

If the tool has been installed successfully, you will see the following screen upon going to the URL specified above:

• In the “Cascade Server 6.4.x URL” field, enter the URL of the Cascade Server instance that houses the Site to which you would like to migrate your Serena Content, i.e. - http://services.cascadeserver.com
• Enter your user name and password for Cascade Server.
• Enter the name of the site to which you want to migrate your Serena Content, i.e. "Admissions"
• Click “Save and Next.”

The next screen will ask you to upload the zip archive that contains the content you've exported from Serenal Collage. If this is the first time you are using the tool, the screen will look like this:

• Click the “Browse” button and navigate to the zip file.
• Click “Save and Next.”

Depending on the size of your export file, this process may take up to a minute. If there are any issues with the XML files, the tool will display a warning, such as the one seen below:

If prompted by the screen above, you can either go back to the previous screen until you have examined your XML  files, or you can ignore the warning and proceed by clicking “Ignore These and Continue.” We recommend that you write down the warnings or copy them into a document, so that you can look at the affected assets upon completion of the migration process. 

Once you have successfully uploaded your zip file, you will see that the folder containing your XML files is stored in the “uploads” folder of your Migration Tool’s tomcat folder.

The next time you go the “upload” screen, you will see that all of the uploaded files that you have completed will be available as options for the “XML Folder” selection (see example below). This expedites the migration process in cases in which you want to run a migration based on an export that you have already uploaded.

After you have successfully uploaded and selected your export data, you will get to the “Root Folder Assignment Screen" displayed below:

This screen is designed to allow you to map your Serena root level folders to directories or external links in Cascade, primarily so all links will be re-written properly. For instance, if you have a Serena folder that needs to be referenced differently in Cascade-published URLs, you can either select the “Cross Site” radio button and specify the appropriate directory, or select the “External Link” radio button and enter an external URL. A typical case for the latter would be if you had sections of your site that you are not migrating yet, so you would want to point to the external link.

Please note that you are not required to select any data on this screen.

• For each new mapping to be conducted, click the “Add Mapping” button

You will then be shown the specified mappings, as in the summary below:

• To remove a mapping, click the “Remove” button.
• When you’re done mapping the root level folders, click “Save and Next.”

The next screen allows you to map XML "Asset Types" from Serena Collage to "Content Types" in Cascade Server:

• Select an XML Asset Type from the drop-down box. 
• Next, select the appropriate Cascade Content Type from the additional drop-down down box and click “Add Mapping”.

Your selection will now be displayed in the summary below. You can remove your mapping by clicking the “Remove” button.

• After mapping all Asset Types to Content Types, click “Save and Next."

The following screens will let you assign field mappings. Each Asset Type/Content Type mapped will have a Field Mapping screen, which will allow you to map each Asset Type’s fields to Cascade metadata fields and Data Definitions.

• To add an additional mapping, which will also be displayed in the summary, click the "+" button.
• To remove a mapping, click the "-" button.

To map a static value from your XML export to a field in Cascade select "Static Value" from the drop-down and enter the value in the text field, which will appear below the drop-down:

• When you’re done mapping all of the fields for the Asset Type/Content Type, click “Save and “Next.”

Once you have mapped the fields for each Asset Type/Content Type, you will see a Summary Screen:

If the summary looks as it should, you will then choose the method by which to “Overwrite Behavior” by selecting one of the available radio buttons:

1. Keep existing-  keeps assets in Cascade Server as are and append numbers to new asset names
2. Overwrite existing - which deletes and overwrites all of the existing assets
3. Update existing - which edits existing assets.

• Once you have made your selection, click the “Migration” button to run the migration process.

You will see a Progress Screen:

The Progress Screen will detail how each page was handled by the Migration Tool. For instance, if a file was skipped because it wasn't included in your mappings, it will display an appropriate message. If a file was created successfully, you will see a “success” notification. If an asset could not be created in the migration process, you will get an error message, indicating the source of the problem.

You will also see a notification for every link that was re-written by the tool. Clicking on links in the summary will take you to the actual asset in Cascade Server. If you get a link error, click on the name of the asset, and you will be able to examine it inside the Cascade Server system.

Summarized at the bottom of the Progress Screen are the number of assets created, the number of assets that were skipped, the number of errors creating assets, the number of aligned links, and the number of aligning errors.

After running the Migration Tool, you now have several options:

• Go back to the Migration Mapping Summary Screen by clicking the “Go Back” button.
• Start a new migration process from the beginning by clicking the “Start From Beginning” button.
• Restart the migration process based on the current mappings by clicking the “Restart Migration” button.
• Run a Link Checker on your migration by clicking the "Start Link Checker" button.

Note- depending on the number of links on your site, the link checking process can take several minutes, and in some cases, up to an hour. The summary will show you a listing of all broken links for each page:

Both the migration summary log and the linkchecker log can be accessed by going to the “logs” folder inside your Migration Tool’s tomcat folder.