This page includes the following:

 

This migration tool is for migrating TWCloud data from TWCloud 18.5 including all service packs, 19.0, or 19.0 SP1 to TWCloud 19.0 SP2. 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: 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 versionSchema version
18.31
18.48
18.4 SP18
18.512
18.5 SP112
18.5 SP212
18.5 SP312
18.5 SP412
19.0 GA

20

19.0 SP120
19.0 SP224

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.


To migrate data from TWCloud 19.0 or 19.0 SP1 to TWCloud 19.0 SP2:

[19.0 DB schema Version 20, UML2.5.1] >(Migration tool)>[19.0 sp2 DB schema Version 24, UML2.5.1]

  1. Stop TWCloud server if it is running.
  2. Make sure that Cassandra is running.
  3. Run the command: nodetool drain, to flush all memtables from the node to SSTables on disk. For more information about the nodetool drain command, see http://cassandra.apache.org/doc/latest/tools/nodetool/drain.html
  4. Stop Cassandra.
  5. Back up the Cassandra database on your machine.
  6. Start Cassandra and make sure that it is running.
  7. Download the TWCloud 19.0 SP2 migration tool zip and extract the zipped file.
  8. Start the migration tool (migrator for Linux or migrator.exe for Windows).
  9. Wait for the migration process to complete.


To migrate data from TWCloud 18.5 (any service pack) to TWCloud 19.0 SP2: 

[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 sp2 DB schema Version 24, UML2.5.1]

  1. Stop TWCloud server if it is running.
  2. Make sure that Cassandra is running.
  3. Run the command: nodetool drain, to flush all memtables from the node to SSTables on disk. For more information about the nodetool drain command, see http://cassandra.apache.org/doc/latest/tools/nodetool/drain.html
  4. Stop Cassandra.
  5. Back up the Cassandra database on your machine.
  6. 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.
  7. If you are using TWCloud older than 18.5 SP4 version with Cassandra 2.2.x, uninstall the old version, 2.2.x, and install Cassandra 3.11.3 to upgrade your Cassandra.
  8. Start Cassandra and make sure that it is running.
  9. If you upgraded Cassandra from 2.2.x to 3.11.3 in step 7, run the command: nodetool upgradesstables. This process may take a while. For more information about the nodetool upgradesstables command, see http://cassandra.apache.org/doc/latest/tools/nodetool/upgradesstables.html
  10. Download the TWCloud 19.0 SP2 migration tool zip and extract the zipped file.
  11. 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.
  12. 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.
  13. Run the migration tool (from Step 11) again and wait for the migration process to complete.

If your database has already been migrated, a message will be displayed, stating that the database is up to date.


If you start TWCloud 19.0 SP2 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 24. 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] 

After successfully migrating the database and UML Specification, you must update the projects to enable project editing. Upgrading your CEDW 18.3, TWCloud 18.4 or 18.5 to TWCloud 19.0 SP1 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.

Migrating a UML meta-model in the database

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 SP2. If you do not migrate the UML meta-model prior to using TWCloud 19.0 SP2, the project will not load. You can download the migration tool to migrate the UML meta-model to version 2.5.1.

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 SP2 before running the migration tool, you will receive an error similar to the following "Cannot migrate. Database version is 18.5, expected 19.0 SP2. 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.

  1. Back up your Cassandra database.
  2. Migrate the database to TWCloud version 19.0 SP2.


To migrate database to UML v2.5.1 follow these steps

  1. Stop TWCloud server if it is running.
  2. Make sure that Cassandra is up and running.

  3. Run the UML migrator application (for Linux or for Windows).

  4. Open the Command Prompt (if using Windows) or Terminal window (if using Linux).
  5. Go to the migration tool directory.
  6. 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

  7. 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")


Upgrading TWCloud

You must migrate your data prior to upgrading to TWCloud 19.0 SP2. If you do not need your existing data, you can skip the migration and simply delete the Cassandra database folder from your machine.

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 SP2

  1. Stop the Teamwork Cloud Services

  2. (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.

  3. Uninstall CEDW 18.3, TWCloud 18.4, 18.5, 19.0 or 19.0 SP1  from your machine. Do not uninstall Cassandra.

  4. Install TWCloud 19.0 SP2 on Linux or on Windows.
  5. Start TWCloud.

Updating projects 

Once you have successfully migrated your data to TWCloud 19.0 SP2, 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. 


To migrate server projects automatically

  1. Start the modeling tool and log in to the TWCloud server.
  2. From the Collaborate menu, select Migrate Project to Version X. The dialog Migrate Project to Version X opens. 

  3. 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). 


  • 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 Resources permission)

  1. Start the modeling tool and log in to the TWCloud server.
  2. On the main menu, click Collaborate > Projects. The Manage projects dialog opens.
  3. Select a project and click Open. A dialog prompting you to update the System/Standard Profiles in the project to allow project editing opens.
  4. 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.

Note

You can open the Notification Window by pressing Ctrl + M or click Window > Notification Window.

Related pages