Migration Guide
This document describes how you can migrate from an older version of the Mashup Server to a newer version. Steps for reverting to a previous version have not been tested or documented.
In all migrations, please make sure that you either backup the existing mashup server installation or leave the installation's database and script directories intact until you verify that the migration to the newer version has been completed successfully.
Upgrading to a Point Release within the Same Version
Migrating from a Mashup Server 1.0 installation to a 1.0.1 or 1.0.2 or from a 1.5 to a 1.5.1 simply requires the copying of database and scripts folders across to the new installation. The steps to be followed are:- Shut down your existing Mashup Server instance.
- Backup your database and scripts directories, by copying them to a separate location. Both directories can be found in the installation root of your mashup server.
- Extract the binary distribution of the new version of the mashup server in a different location. Leave the old installation untouched, so that you can revert to the previous version at any point if you wish to do so.
- Delete the contents of the 'database' and 'scripts' directories of the new installation.
- Copy the contents of the 'database' and 'scripts' directories of the old installation into the now empty 'database' and 'scripts' directories of the new installation.
- Start the new server. You will not be requested to provision the new installation as the previously created administrator account will be active on the new server.
Upgrading from a 1.0.x installation to a 1.5.x Installation
Migrating a 1.0.x installation of the Mashup Server to a 1.5 requires that data be exported from the older version of the WSO2 Mashup Server and imported into the new version. The steps below describe how the downloadable 'MigrationTool' can be setup and used to perform the data migration.
Getting the Migration Tool
You can download the MigrationTool.zip file containing the binaries, JSP's and configuration files required to perform the migration from here. Extract the contents of the zip file and perform the steps below to migrate your Mashups and MetaData from your 1.0.x installation to your a 1.5.x installation.
Performing the Migration Using the Migration Tool
This document assumes you have installed, but not provisioned a WSO2 Mashup Server 1.5.x on the same system that is running the WSO2 Mashup Server 1.0.x. The installation root directories of your Mashup Server 1.0.x, Mashup Server 1.5.x will be referred to as 'Mashup 1.0 Home' and 'Mashup 1.5 Home' respectively. The extracted contents of the MigrationTool.zip file are assumed to reside in the 'MigrationTool' directory.
Step 1 - Exporting Data from the 1.0.x installation
1.1. Move the 'wso2mashup-core-1.0.2.jar' file out of the 'Mashup 1.0 Home\lib' directory.
1.2. Copy the 'wso2mashup-core-1.0.x-withexport.jar' file from the 'MigrationTool\export' directory to the 'Mashup 1.0 Home\lib' directory.
1.3. Copy the 'extract.jsp' file from the 'MigrationTool\export' directory to the 'Mashup 1.0 Home\lib\tomcat\webapps\ROOT' directory.
1.4. Start the 1.0.2 Mashup Server and access the extract.jsp page (typically at https://localhost:7443/extract.jsp).
1.5. The follwing page should be displayed:
1.6. Shut down the 1.0.x Server.
1.7. Delete the 'wso2mashup-core-1.0.x-withexport.jar' file from the 'Mashup 1.0 Home\lib' directory and restore the 'wso2mashup-core-1.0.2.jar' file.
Step 2 - Importing Data into the 1.5.x Installation
2.1. Move the 'wso2mashup-core-1.5.1.jar' file out of the 'Mashup 1.5 Home\lib' directory.
2.2 Copy the 'wso2mashup-core-1.5.x-withimport.jar' file from the 'MigrationTool\import' directory to the 'Mashup 1.5 Home\lib' directory.
2.3 Copy the 'populate.jsp' file from the 'MigrationTool\import' directory to the 'Mashup 1.5 Home\lib\tomcat\webapps\ROOT' directory.
2.4 Copy the 'migration.xml' file from the 'MigrationTool\import' directory to the 'Mashup 1.5 Home\conf' directory.
2.5.1 Update the <url> parameter in this file with the fully qualified path to the 'Mashup 1.0 Home\database\WSO2WSAS_DB' directory.'
2.5 Move the 'server.xml' file out of the 'Mashup 1.5 Home\conf' directory and copy the 'server.xml' file from the 'MigrationTool\import' directory there.
2.6 Copy the user script directories from the 'Mashup 1.0 Home\scripts' directory to the 'Mashup 1.5 Home\scripts' directory.
2.6.1 Copy the mashup-metadata.xml file from the 'Mashup 1.0 Home' directory to the 'Mashup 1.5 Home' directory.
2.7 Start 1.5.1 Server and access the populate.jsp page (typically at https://localhost:7443/populate.jsp). The following page should be displayed.
2.8 Shut down the 1.5.x server.
2.9 Delete the files you copied in from the 'MigrationTool' directory and restore the 'server.xml' file and 'wso2mashup-core-1.5.1.jar' files to the 'conf' and 'lib' directories respectively.
2.10. Optional: Use a database tool of your choice* to run the 'extracted_logs.sql' file, available in the 'Mashup 1.0 Home' against the 'Mashup 1.5 Home\database\WSO2REGISTRY_DB' database, to restore activity logs.
2.11. Start up and provision the 1.5.x server. The data migration is complete!
Performing the Migration by Building the Source
If required, you can also obtain the source code for the MetadataExtractor and MigrationInitializer java classes, which are not included in the MigrationTool.zip file and use them to build the migration tools from source.
MetaData Export
User, Mashup and Activity information is extracted saved into the Mashup Home directory by the 'MetadataExtractor' java class. The source code for this class should be included in a new 'migration' package of the mashup server's core module source and built into a mashup-core java archive. The remaing steps for data extraction are the same.
The mashup-metadata.xml file contains serialized user information and metadata for all mashups including tags, comments and ratings entered by all users.
MetaData Import
The 'MigrationInitializer' java class re-creates the users registered in the old instance of the Mashup Server in the new instance and also restores the user profile and mashup metadata. The source code for this class should be included in the 1.5.x source and built into a mashup-core java archive. The remaing steps for data import are the same.