Page tree

Teamwork Cloud 19.0 LTR SP3 Documentation


This page includes the following:

 

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: 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
19.0 SP326

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, 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]

  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 SP3 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 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]

  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, 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.
  8. Start Cassandra and make sure that it is running.
  9. 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 SP3 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 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] 

After successfully migrating the database and UML Specification, you must update the projects to enable project editing.

Note

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.


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 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

  • 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.

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


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
    • WindowsMigrator -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 SP3. 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 SP3


  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, 19.0 SP1, or 19.0 SP2 from your machine. Do not uninstall Cassandra.

  4. Install TWCloud 19.0 SP3 on Linux or on Windows.

    Note

    If you have changed the default Administrator username and password, you must update the twc.admin.username and twc.admin.password parameters, in the web application configuration file at <TWCloud install folder>/WebAppPlatform/shared/conf/webappplatform.properties.

  5. Start AuthServer, TeamworkCloud, and WebApp services.

Updating projects 

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. 

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.



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.

  • No labels