Migrate schemas and XEngines

There are two types of migrations during a Tricentis Tosca upgrade:

A schema migration updates your repository database schema to the latest version.
An XEngine migration updates existing Standard subset Modules and their connected TestCases to the latest version.

You may not need both types of migration every time you upgrade Tricentis Tosca.

Before you start

You can do migrations manually or, if you use the Tosca Administration Console, directly in the console.

However, the Tosca Administration Console is part of Tosca Server. If you want to migrate via console, you need to perform a few preparatory steps first:

Install an upgraded version of the Tosca client on the server machine.
Upgrade Tosca Server.

Other things you need to consider:

Migrations run on the repository version of all objects. Make sure that all users have checked in their local changes before you migrate. If you migrate objects that are checked out by other users, you lose all local changes.
Migrated schemas, Modules, and TestCases are not backward compatible. You can't revert a migration. If you migrate and suddenly find that you need to go back to your earlier schema, you have to restore your backup.

Perform schema migrations

Tosca stores project data in a database, which serves as your repository. This database has a specific data structure, or "schema". If the schema changes between Tosca versions, you need to migrate.

Find out whether you need a migration

In a single-user environment, you don't need to perform schema migrations. Tosca automatically migrates when you open the workspace for the first time after the upgrade.

In a multi-user environment, you may need to perform schema migrations. Here's how to find out whether you do:

If you use the Tosca Administration Console, check the project's Version in the Projects Overview. If you see a , the project has an outdated schema. The Schema version in the header shows the schema of the latest Tosca version you've installed. That's the schema you need to migrate to.
If you don't use the Tosca Administration Console, check the schema version table. Compare the schema of your previous Tosca version to the version you upgrade to. If there's a difference, you need to migrate.

Trigger the schema migration

How you trigger the schema migration depends on whether you use the Tosca Administration Console or not.

You don't use the Tosca Administration Console.

If you don't use the console, you have to migrate your schema manually.

Before you start, consider these things:

Make sure you have a database user with all necessary rights. To migrate, you need a connection string to your repository database. The user in this connection string must have ALTER, CREATE, and DELETE rights to create tables, delete indexes, and create new indexes.
Make sure you test the database migration on a test database first. Only migrate your productive database if you successfully migrated your test database. We recommend that you create a test environment and do trial runs of your most important TestCases to make sure the test migration was successful.

To migrate a schema, follow these steps:

Create a backup of your database. If the migration fails, you must load the backup before you can make another migration attempt.
Go to %COMMANDER_HOME%.
Open the Command Prompt window and run the following command:

DbRepositorySchemaMigrator.exe "<database type>" "[schema name]" "[tablespace name]" "<connection string>"
- Replace <database type> with the database type of your repository: Oracle, MS SQL Server, DB2, or SQLite.
- Optionally, replace [schema name] with the database schema name.
- Optionally, replace [tablespace name] with the tablespace name of your database. The name of the tablespace depends on which database you use: Tablespace (DB2), Userspace (Oracle), FileGroup (MS SQL).
- Replace <connection string> with a connection string to connect to your repository database. For SQLite repositories, enter the absolute path to the CommonRepository.db file.
- Optionally, add -s at the end of your command. This allows you to perform the migration in silent mode, without user interaction.

Here are two examples for migration commands.

This command migrates the schema of your SQLite repository database:

DbRepositorySchemaMigrator.exe "SQLite" "C:\Tosca_Projects\Tosca_CommonRepositories\GUItests\CommonRepository\CommonRepository.db"
This command migrates the schema of your DB2 database in silent mode. The schema name is my_common_schema:

DbRepositorySchemaMigrator.exe "DB2" "my_common_schema" "Server=111.111.111.111:5050;Database=myDataBase;UID=myUsername;PWD=myPassword;" -s

Once it's done, DbRepositorySchemaMigrator.exe displays a message that indicates whether the migration was successful or not. For detailed migration results, check the log file SchemaMigration_<File name>.txt, located at %APPDATA%\TRICENTIS\TOSCA TestSuite\7.0.0\Temp\TCTempLog.

You can now open your multi-user workspaces in Tosca. Tosca migrates workspaces when you open them for the first time after the schema migration.

Perform XEngine migrations

An XEngine migration updates existing Modules of the Standard subset and their connected TestCases to the latest Tosca version you've installed.

Keep the following things in mind:

A Tosca version may have changed Modules, but still not need a migration. Not every change to a Module in the Standard subset requires an XEngine migration.
A migration doesn't automatically import any new Modules that we've added to the new version's Standard subset. To get access to these new Modules, you need to import the new Standard subset.

Find out whether you need a migration

The table in this section tells you which Tosca versions include changes that require a migration.

However, even if a version has these changes, you still may not need to do an XEngine migration:

If you don't use any of the changed Modules in your tests.
If you only use one or two changed Modules in your tests. In this case, we recommend a faster alternative approach: import the new Standard subset and merge the affected Modules.

Tosca version	Changes that require an XEngine migration
2023.2 LTS	None.
2023.1 LTS	None.
16.0 LTS	None.
15.2 LTS	None.
15.1 STS	None.
15.0 LTS	None.
14.3 STS	Excel 1:1 File Compare Module: changed value of ModuleAttribute Include Sheets to string.
14.2 LTS	None.
14.0	None.
13.4	None.
13.3	Various TestData Modules: changed "record" to "item" in Module and ModuleAttribute names. TestData - Find & provide item Module: new ModuleAttributes Position, Query, and Sorting. TestData - Expert Module: new ModuleAttributes Position, Query, and Sorting.
13.2	Receive Mail - Expert Module: fixed cardinality for ModuleAttribute Folder, updated ValueRange for ModuleAttribute Result->Mail, updated descriptions for various ModuleAttributes. Connect to Mail Server Module: updated description. Send Mail Module: updated description.
13.1	Receive Mail - Simple Module: new ModuleAttribute Number of Emails to examine. Receive Mail - Expert Module: new ModuleAttribute Number of Emails to examine. All TestData Modules that have the ModuleAttribute TDS type: changed ValueRange from <CATEGORY> to <TYPE>. TestData - Expert Module: updated ValueRange for the Test data task ModuleAttribute: Create;ReadOnly;Find;Update;DeleteRecord;DeleteType;DeleteAll;ConsumeRecord;UnconsumeRecord;ConsumeType;UnconsumeType

Keep in mind that new Tosca versions include all changes from previous versions. Let's say you upgrade from Tosca 14.2 to 16.0. While 16.0 doesn't have changes that require an XEngine migration, 14.3 does. These changes are also in 16.0. Consequently, if you use the 1:1 File Compare Module extensively in your tests, you need a migration.

Trigger the XEngine migration

How you trigger the XEngine migration depends on whether you use the Tosca Administration Console or not.

You don't use the Tosca Administration Console.

If you don't use the console, you have to migrate manually:

Open any workspace that's connected to the common repository.
If you're in a multi-user environment, check out the project root element.
Right-click the project root element and select XEngines Migration->Update project to current version from the context menu.
In the Backup dialog, choose whether to create a backup. We recommend that you do, just to be on the safe side. In this case, Tosca creates one of the following objects in %TRICENTIS_ALLUSERS_APPDATA%\Automation\MigrationBackup:
- A .tde backup for multi-user repositories.
- A .tsu backup for single-user repositories.

Once the migration is done, Tosca displays a migration report that indicates whether or not the migration was successful. If you accidentally close the report, you can find it again at %APPDATA%\TRICENTIS\TOSCA TestSuite\7.0.0\logs\Automation\ToscaDIMigration.