This migration tool is for migrating TWCloud data from TWCloud 18.5 including all service packs, 19.0, 19.0 SP1, or 19.0 SP2 to TWCloud 19.0 SP3. If you have existing data created in CEDW 18.3 or TWCloud 18.4, you must migrate the data to TWCloud 18.5 first using TWCloud 18.5 migrator. There are two sets of instructions below. Please select either set of the instructions according to your current TWCloud version.
Warning
title
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
19.0 GA
20
19.0 SP1
20
19.0 SP2
24
19.0 SP3
26
Note
Before migrating the database, perform a cold backup per the procedure here. 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.
Anchor
migratedatabase
migratedatabase
To migrate data from TWCloud 19.0, 19.0 SP1, or 19.0 SP2 to TWCloud 19.0 SP3:
[19.0 DB schema Version 20 or 24, UML2.5.1] >(Migration tool)>[19.0 SP3 DB schema Version 26, UML2.5.1]
Download the TWCloud 19.0 SP3 migration tool zip and extract the zipped file.
Start the migration tool (migrator for Linux or migrator.exe for Windows).
Wait for the migration process to complete.
Anchor
migrate185
migrate185
To migrate data from TWCloud 18.5 (any service pack) to TWCloud 19.0 SP3:
[18.5 DB schema Version 12, UML2.5] > (Migration tool run for the first time) > [19.0 DB schema Version 20, UML2.5] > (UML migrator) > [19.0 DB schema Version 20, UML2.5.1]> (Migration tool run for the second time) >[19.0 SP3 DB schema Version 26, UML2.5.1]
If your data are created in TWCloud earlier than the 18.5 version, run the TWCloud 18.5 migrator. Otherwise, proceed to the next step.
If you are using TWCloud older than 18.5 SP4 version with Cassandra 2.2.x, you will need to upgrade Cassandra to 3.11.x (Otherwise, start Cassandra and make sure that it is running then skip to Step 10). Prior to doing this, please note the data and commitlog locations in cassandra.yaml. Uninstall Cassandra 2.2.x and install Cassandra 3.11.x. Based on the new Cassandra.yaml, move the respective files from the old locations to the new locations, or adjust the locations in the new Cassandra.yaml to point to the original locations. It is advisable to take this opportunity to ensure that the data and commit log file locations follow our recommendations in the Cassandra installation section.
Download the TWCloud 19.0 SP3 migration tool zip and extract the zipped file.
Start the migration tool (migrator for Linux or migrator.exe for Windows) and wait for the migration process to complete. The migration process will stop at the schema Version 20.
Download the UML migrator zip, extract it, and proceed to the UML migrator instruction. The UML migrator will migrate data from UML 2.5 to UML 2.5.1.
Run the migration tool (from Step 11) again and wait for the migration process to complete.
Note
If your database has already been migrated, a message will be displayed, stating that the database is up to date.
Warning
If you start TWCloud 19.0 SP3 with the Cassandra database created in any previous version of the server without migrating your data first, the TWCloud server will fail to start, and an error message similar to the following content will appear in server.log:
ERROR 2019-02-04 14:43:50.548+07:00 [com.nomagic.esi.server.core.coremanager(15)] The activate method has thrown an exception [com.nomagic.esi.server.core, com.nomagic.esi.osgi.logger.a.a@4930fdbb] java.lang.RuntimeException: Schema version is version 20, expected 26. Please do the migration. INFO 2019-02-04 14:43:50.545+07:00 Shutting down in 7 seconds [com.nomagic.esi.server.core.impl.CoreManagerComponent, Thread-7]
Upgrading your CEDW 18.3, TWCloud 18.4 or 18.5 to the current version of TWCloud is also possible without migrating your database. If you do not need to keep your existing data, you can simply skip the migration steps and delete your database folder.
Anchor
migrateuml
migrateuml
Migrating a UML meta-model in the database
Note
This section is only applicable if you are upgrading from a version lower than 19.0
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 SP3. If you do not migrate the UML meta-model prior to using TWCloud 19.0 SP3, 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 SP3 before running the migration tool, you will receive an error similar to the following "Cannot migrate. Database version is 18.5, expected 19.0 SP3. 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 TWCloud
You must migrate your data prior to upgrading to TWCloud 19.0 SP3. 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
Location of your data
The location of your data is configured in cassandra.yaml, as specified by the data_file_directories parameter
To upgrade to TWCloud 19.0 SP3
Stop the Teamwork Cloud Services
(Optional) Make a copy of the installation directory - this will leave a reference to the existing configuration, as well as a source for your signed certificates, if you are not using the self-signed certificates generated during the install.
Uninstall CEDW 18Uninstall CEDW 18.3, TWCloud 18.4, 18.5, 19.0, 19.0 SP1, or 19.0 SP2 from your machine. Do not uninstall Cassandra.
Once you have successfully migrated your data to TWCloud 19.0 SP3, 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. 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.
Note
To ensure project integrity, it is recommended that you migrate all dependent projects (projects with its used projects) at once. In this case, you will not need to link used projects manually. You can migrate projects in separate batches; however, before migrating, you should identify projects related via the used project. After migration, used projects will end up as separately embedded projects rather than being correctly linked. Thus, you will need to link them manually.
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.
