Migrating Teamwork Cloud version 19.0 is performed in two stages, migrating a database to version 19.0 using the database schema migration tool and migrating the UML Specification to version 2.5.1 using the UML migration tool.
Warning: Check the schema version before upgrading TWCloud
Before upgrading your TWCloud, check if the schema of your current TWCloud is the same as that of TWCloud you are going to upgrade to. If both schema versions match, you can upgrade your TWCloud without the need to migrate your data. Otherwise, you need to migrate your data.
TWCloud version
Schema version
18.3
1
18.4
8
18.4 SP1
8
18.5
12
18.5 SP1
12
18.5 SP2
12
18.5 SP3
12
18.5 SP4
12
TWC 19.0 GA
20
Anchor
migratedatabase
migratedatabase
Migrating a Cassandra database
This section outlines the steps to migrate your data from a previous version of TWCloud to 19.0. If you already have existing data created in CEDW 18.3, TWCloud 18.4 or 18.5, you must migrate the data to a 19.0 compatible format before using Teamwork Cloud (TWCloud) 19.0. Use the migration tool to accomplish this. The migration tool is a .zip file that should be on the same download page as the TWCloud installer file. If your database has already been migrated, you should see a message informing you that the database is up to date.
Warning
Before migrating the database, perform a cold backup per the procedure (how to do that clickhere).
Warning
title
Warning
If you start TWCloud 19.0 with the Cassandra database created in any previous versions of the server without migrating your data first, the TWCloud server will fail to start, and an error message similar to the following will appear in server.log:
ERROR 2017-10-17 16:25:27.317 Connection to Cassandra failed: Database version is version 18.5, expected 19.0. Please do the migration. [e]
ERROR 2017-10-17 16:25:27.317 Error while trying to activate CoreManagerComponent [e]
INFO 2017-10-17 16:25:27.324 Shutting down in 7 seconds [e]
The following instructions show how to migrate data from TWCloud 18.5 to TWCloud 19.0.
Anchor
migratedata
migratedata
To migrate data from 18.5 to TWCloud 19.0
Stop TWCloud if it is running.
Confirm that Cassandra is up and running.
Run the command, nodetool drain, to flush all memtables from the node to the SSTables on the disk.
C:\> cd "Program Files\apache-cassandra-3.11.2\bin"
C:\> nodetool drain
Back up the Cassandra database on your machine. You can back up the database by copying the stored database folder. You are required to back up the following default folders for each OS.
You can change the database folder by configuring cassandra.yaml. Make sure that you back up the correct folder. Alternatively, you can use the backup and restore script, explained in Backup and restore data procedures. In this case, you must start Cassandra, since the script makes use of the nodetool utility which will connect to the running instance of Cassandra.
If your data is created in an earlier version than TWCloud 18.5, run the TWCloud 18.5 migrator. Otherwise, proceed to the next step.
To upgrade your Cassandra version to 3.11.2, uninstall the old version and install Cassandra 3.11.2 in this step.
Start Cassandra and confirm that it is up and running.
Run the command, nodetool upgradesstables. This process may take a while.
Run the migration tool for your operating system (migrator for Linux or migrator.exe for Windows).
Wait for the migration process to complete and the successful data migration message to appear.
Upgrade your UML meta-model using the following instructions.
Anchor
migrateuml
migrateuml
Migrating a UML meta-model in the database
As of version 19.0, TWCloud uses the UML meta-model version 2.5.1. Therefore, you need to migrate the UML meta model in the database since earlier versions of TWCloud are using the UML meta-model version 2.5. This UML meta-model migration is necessary to continue working with old TWCloud projects in 19.0. If you do not migrate the UML meta-model prior to using TWCloud 19.0, the project will not load. You can download the migration tool to migrate the UML meta-model to version 2.5.1.
Warning
title
Warning
The migration tool modifies the Cassandra database and may leave it in an incomplete migration state in the event of failure. To prevent data loss, create a backup your database before performing the UML migration. To find out more about backing up your data, see Backup and restore data procedures.
If the Cassandra database has not been migrated to TWCloud 19.0 before running the migration tool, you will receive an error similar to the following "Cannot migrate. Database version is 18.5, expected 19.0. Please migrate to specified database version first."
You must complete the following prerequisites before migrating the UML meta-model in your database to version 2.5.1.
To migrate database to UML v2.5.1 follow these steps
Stop TWCloud server if it is running.
Make sure that Cassandra is up and running.
Run the UML migrator application (for Linux or for Windows).
Open the Command Prompt (if using Windows) or Terminal window (if using Linux).
Go to the migration tool directory.
Launch the migrator UML application in the terminal with the following parameters
Windows: Migrator -host 127.0.0.1 -port 9160
Linux: ./Migrator -host 127.0.0.1 -port 9160
Wait for the migration to complete. Upon successful migration, the following message appears: "Finished UML 2.5 -> 2.5.1 migration."
The parameters are:
host is the Cassandra host name or ip address
port is the Cassandra port (i.e. 9160)
u is the Cassandra username (optional) (i.e. cassandra)
pwd is the Cassandra password (optional) (i.e. cassandra)
n is the cluster name (optional) (i.e. "Test cluster")
Anchor
upgradetwc
upgradetwc
Upgrading to TWCloud 19.0
You must migrate your data prior to upgrading to TWCloud 19.0. If you do not need your existing data, you can skip the migration and simply delete the Cassandra database folder from your machine.
Info
title
Info
By default, the Cassandra database folder is located on:
Once you have successfully migrated your data to TWCloud 19.0, you must update the projects in the database to the latest version. A project that is not updated will open in read-only mode. When you open the project in a modeling tool, the following notification appears. Project editing is disabled, because it uses system or standard profiles that are incompatible with the current installation.
You will not be able to edit a project until you update the project to the latest version.
You can see the same notification in the Notification Window. Therefore, you must update the project before you can edit it.
Editing a project that has not been upgraded to the latest version is not allowed.
You need an Administer Resource permission to upgrade a project by migrating it. You can use the automatic server project migration feature to migrate all server projects at one time or migrate each server project manually. While the project is being migrated, other users are prevented from any modifications in that project. We highly recommend that the same person migrates all projects.
From the Collaborate menu, select Migrate Project to Version X. The dialog Migrate Project to Version X opens.
Select projects to migrate. Do one of the following:
On the dialog toolbar, click to select all server projects.
Select category (or categories) to migrate with all projects inside it.
Select separate projects from category (or categories).
Info
Select Speed up model history-related operations if you want to upgrade caches of earlier model revisions on the server. This is useful if your modeling workflow includes using historical model versions; however, this option may slow down the migration process.
Select Enable migration of password-protected projects to enable selection of password protected projects. During the migration process, you will be prompted to enter a password for each of the password-protected projects you selected to migrate. If this option is not selected, after the project migration is completed, you will get a message with a list of password-protected projects that were not migrated. You must migrate those projects manually.
After the project migration is completed, you will either get a message about successful project migration or a list of projects that were not migrated. You must migrate those projects manually.
To migrate server projects manually (for a user role with the Administer Resourcespermission)
On the main menu, click Collaborate > Projects. The Manage projects dialog opens.
Select a project and click Open. A dialog prompting you to update the System/Standard Profiles in the project to allow project editing opens.
Click Continue. After the System/Standard Profiles are updated, the modeling tool opens a notification showing that the model was successfully updated.
You can also see the same notification in the Notification Window.
Info
title
Note
You can open the Notification Window by pressing Ctrl + M or click Window > Notification Window.
