Migration tool

Mats Halfvares, the Content Studio Development team

The Content Studio migration tool will assist and do most of the job when migrating from version 4 (ASP and VB-script) to version 5 (ASP.NET and VB.NET).

More details on migration are found in the article Migrating to Content Studio 5.

Using the Migration tool

The Content Studio Migration tool is available for all customers and can be downloaded at Content Studio web page.
This tool can assist you with the following:

Analyze the database to find
- incompatible components
- server side code
- custom components
- components that can contain incompatible code
- your own defined content (configurable)
Replace incompatible content
- ".asp" with ".aspx"
- your own replacements (configurable)
Upgrade the database to Content Studio version 5
Provide you with a detailed report containing found issues

Installing the tool

The migration tool can be run on any computer running Windows XP, Windows Server 2003 or later. For Windows XP and Windows Server 2003 you must have the .NET Framework 2.0 installed and it is recommended that the framework is updated to the latest version.

Copy the downloaded content, including the Data sub directory, to a directory of your choise on your computer.

In order to run the program you must be have db owner permission on the site database to analyze or migrate.
On Windows Vista where user account control is active (default) and your Sql Server is located on the local computer, you might need to check that your windows account have the necessary permissions in SQL server even though that you are logged in as a account with adminstrative privileges. Since a process that you start by default does not run with elevated privileges you cannot rely on your membership in the local administrator group since these rights are stripped off from your login token. Instead you might be able to run the Migration tool with administrative privileges or explicitly add your login to Sql Server and set it as db owner of the site database.

Running the migration tool

Start the migration tool by double clicking on the CSMigrationTool.exe file.
Now you will see the following welcome screen.

The welcome step

In the next step you need to select the database to analyze or migrate. Only Content Studio 4.x.x database can be used.

The select database step

By pressing the Select button the select database dialog appears and assists you when you select the database to migrate or analyze.

The select database dialog is searching for databases on the server

The third step asks you to specify some options to use during the process

Steps to perform

Upgrade

The upgrade is required, but will only be performed when the real migration is performed

Perform content replacements

Perform all the configured content replacements.
This is performed only when the real migration is made

Check for outdated components

Checks for all occurences of outdated AS components.
All occurences found will be logged, but no data will be changed.

Check for custom components

Checks for all occurences of custom AS components.
All occurences found will be logged, but no data will be changed.

Check for server side code

Inline server side code.

This is code that exists between <% %> script tags

Script block server side code.

This is code that exists between

<script runat="server"> 
</script>

elements

All occurences found will be logged, but no data will be changed.

Migration reporting

Normal: Only general information scan results and summary is written to the report file
This is the recommended level that will server most users.
Extended: The same info as the Normal level together with more detailed information is written to the report file
This setting is inteded for users that would like to have information about most details. The reporting file generated is often serveral times bigger than the file generated by Normal level.
Debug: The same info as the Extended level is written to the report file but on an extremly detailed level.
This setting is inteded when there is a need to detect problems with the program. The reporting file generated can be very large and difficult to read for normal programs.
Reporting file location: This alternative allows you to select the directory where the reporting file should be stored.
Before you can continue you must choose a reporting location.

The select options step

Before starting the actual process you can select whether to migrate or just simulate and analyze the migration process.

By default the tool is set to just analyze the database and simulate the migration process rather than actually perform it. This makes it possibly to test the process and get the report before any migration is done something that radically facilitates the often difficult task of estimate the work and time needed for a CS 4 to CS 5 migration.

If you uncheck the Simulate only checkbox you will start a true migration process in the next step. Before the tool allows you to start you will need to verify that you have a valid backup and that the database is not in use by a running website.

Warning

Never run the real migration process on a database that is in use by a running CS 4.x Web site. The database will be upgraded, data will be changed and the Web site will stop working.
Make sure that you have a recent valid backup of the database before starting the migration process. If anything goes wrong you must be able to restore the database to its original CS 4.x state. This is especially important if you have your own replacements done. For more information on how to customise the replacement and scan process see the section Customizing the migration tool below.

The select summary step

During the actual migration process you can follow what is going on in the status window. Detailed messages are not shown here but logged to the report file so you can see them afterwards.

The analyze/migration step

The last step shows a summary of the analyze or migration that has been done and alsow allows you to directly open the generated xml report file by clicking the link.

The finish step

The report file has a consistent schema that makes it possible to open with for example Microsoft Excel and filter the data as you like. The sample below shows that the xml report file is made up of a series of report items that either display some sort of information, a compatibility warning or a breaking error. The idea is to separate the entries in groups that probably will have the following impact on your web site.

Information: Impact: none.
Warning: Impact: Will probably not work but a workaround exists.
Breaking (Error): Impact: Will not work and the page or component must be rewritten, or, the functionality is no longer supported.

Xml

<?xml version="1.0" encoding="utf-8"?>
<Report>
    <Item>
        <Number>1</Number>
        <Created>2007-11-29T15:21:42</Created>
        <EventID>1</EventID>
        <Event>Information</Event>
        <Item />
        <Description>CS Database migration report for Sql Server instance: 
                     THMAHAL; Database: SkellefteaWebb
        </Description>
        <Data />
    </Item>
    <Item>
        <Number>2</Number>
        <Created>2007-11-29T15:21:42</Created>
        <EventID>1</EventID>
        <Event>Information</Event>
        <Item />
        <Description>Starting a simulation of the migrating process</Description>
        <Data />
    </Item>
    <Item>
        <Number>33</Number>
        <Created>2007-11-29T15:22:01</Created>
        <EventID>4</EventID>
        <Event>Warning</Event>
        <Item>Admin/HTML-sidor/A till Ö (1605)</Item>
        <Description>The document contains the "Web map A-Z" AS-component 
                     which is outdated. Replacement: "Web map A-Z 2.0".: 
                     Occurences: at least one.
        </Description>
        <Data />
    </Item>
    <!-- more Item elements-->
    <Item>
        <Number>34</Number>
        <Created>2007-11-29T15:22:01</Created>
        <EventID>4</EventID>
        <Event>Warning</Event>
        <Item>Admin/HTML-sidor/Kalendarium (1822)</Item>
        <Description>The document contains the "Insert script" AS-component 
                     which might contain incompatible code.: Occurences: 3
        </Description>
        <Data>
            ************ Content of matching scan item no. 1 **************
            &lt;% DrawCalendar("") %&gt;
            ************ End content *********
            ************ Content of matching scan item no. 2 **************
            &lt;%
            if(Request.QueryString("date") &lt;&gt; "") then
            dDate = cDate(Request.QueryString("date"))
            else
            dDate = cDate(Date)
            end if
            iWeek = Request.QueryString("week")
            if(iWeek = "") then iWeek = 0

            WeekStart = DateAdd("d", (Weekday(dDate) - 2)*-1, dDate)
            if(DateDiff("d", WeekStart, dDate) = -1) then WeekStart = DateAdd("d", -7, WeekStart)

            for i = 0 to 4
            %&gt;
            ************ End content *********
            ************ Content of matching scan item no. 3 **************
            &lt;%
            next
            %&gt;
            ************ End content *********
        </Data>
    </Item>
    <!-- more Item elements-->
    <Item>
        <Number>110</Number>
        <Created>2007-11-29T15:22:03</Created>
        <EventID>1</EventID>
        <Event>Information</Event>
        <Item />
        <Description>******* Start summary *******</Description>
        <Data />
    </Item>
    <!-- more Item elements-->
    <Item>
        <Number>125</Number>
        <Created>2007-11-29T15:22:03</Created>
        <EventID>1</EventID>
        <Event>Information</Event>
        <Item>AS component: "Preview draft button"</Item>
        <Description>Occurences found in 1 document(s).</Description>
        <Data />
    </Item>
    <Item>
        <Number>126</Number>
        <Created>2007-11-29T15:22:03</Created>
        <EventID>1</EventID>
        <Event>Information</Event>
        <Item />
        <Description>****** End summary ******</Description>
        <Data />
    </Item>    
</Report>

The generated report together with a manual analyze of the site structure and the content in general can be used when you estimate the amount of work that needs to be done to get the web site working in the new environment.

Customizing the migration tool

During the migration process the tool performs both content replacement and content scanning operations. Event though these actions covers the most common tasks there might be cases where a developer needs to do provide their own replacements or scans. The instructions used is all stored in the file config.xml that must be located in the same directory as the executable file CSMigrationTool.exe
This file is in the Xml format and is divided into two main sections:

configuration/replacements: This section stores all the replacement instructions
configuration/scans: defines a list of scanning instructions to be made

Xml

<?xml encoding="utf-8" version="1.0" ?>
<configuration>
  <!-- This section searches the content for an expression and replaces it with another-->
  <replacements>
    <!-- A list of replacement to be performed 
        mandatory:       true if the scan is mandatory, for future use only. 
        case-sensitive:  true if the searchcondition is case sensitive, false otherwise. 
        description:     A description of the scan to be performed. searchcondition: 
        searchcondition: A regular expression to be used to find matches that should be replaced
        replacements:    The replacement string that will replace the text find by searchcondition. 
                         If the replacement contains a $ (dollar) character this must be replaced with $$.-->

       <replace case-sensitive="false"
                description="Replacing .ASP with .aspx" mandatory="true"
                replacement=".aspx" 
                searchcondition=".ASP(?=\W|$)" />
  </replacements>
  <!-- This section contains a number of scan elements that defines what to search and warn for-->
  <scans>
    <!-- Scans to be performed 
        class:           can be code or component. Also one item marked as class=template can exist
        level:           can be 0=Information, 1=Warning or 2=Breaking.
        case-sensitive:  true if the searchcondition is case sensitive, false otherwise.
        description:     A description of the scan to be performed, for debug logging mainly.
        searchcondition: A regular expression to be used to find matches.
        message:         A message to be written along with the document id and name if any match was found.
        findAll:         (true, or false) optional, searches for all occurences that matches the searchcondition. 
                         The default value is false.
        displayContent:  (true or false) optional, writes the content of the matches to the reports data field.
                         The default value is false.
        xPathToSource:   Optional, only used with class="component". When displayContent="true" this is an 
                         Xpath expression that can be used to extract parts of the content of the Xml definition 
                         of the sought after component.
                         The XPath-expression may return more than one node, in that case the different nodes will be 
                         grouped with a delimiter between them where the node name is indicated. 
    -->
        <scan class="code" 
              level="1" 
              case-sensitive="true" 
              description="Inline script blocks" 
              searchcondition="\&lt;\%[\s\S]*?\%\&gt;" 
              findAll="true" 
              displayContent="true" 
              message="Inline ASP script code found!" />

        <!-- AS components that can contain incompatible code-->
        <scan class="component" 
              level="1" 
              case-sensitive="true" 
              description="AS component: &quot;Insert script&quot;"
              message="The document contains the &quot;Insert script&quot; AS-component which might contain incompatible code."
              findAll="true"
              displayContent="true"
              searchcondition="&lt;CSROOT[^&gt;]+&gt;[\s]*?&lt;CSSCRIPT[^\&gt;]*?\sname\=['&quot;]Insert\sscript['&quot;][\s\S]*?&lt;/CSROOT&gt;" 
              xPathToSource="CSROOT/CSSCRIPT/PARAMETERS/PARAMETER[@name='Script']/@value" />
   </scans>       
</configuration>

As you can see in the excerpt from the config.xml file, you can provide your own replacement and scan operations that should be executed during migration. Before you run the program you must be sure that your regular expressions work exactly as expected and that there in not syntax error in the file. As always it is a good idea to always have a working copy of the config.xml file that you can use in case something goes wrong. Please examine the file to see how we have done it and what actually is going on under the hood.
The example above shows the configuration for a replacement operation and a code scanning operation where all the occurences of inline code blocks are found and the content of these script blocks are written in the report. The third example searches for all occurences of the Insert Script component and uses an XPath query to retrieve the code content of the Script parameter in AS component Xml source.

Warning

It can be very complicated to edit existing configurations or add new replacement or scanning operations. Even the slightest mistake will make the Migration tool useless and custom configurations requires thorough knowledge of Regular expressions and XPath expressions.