Can we migrate Teamwork Cloud directly from 2022x to 2026x or 2026x Refresh 1?

A question that keeps coming up is:

Can we migrate Teamwork Cloud directly from 2022x to 2026x or 2026x Refresh 1, or do we first have to migrate through 2024x?

The short answer is:

Yes. Teamwork Cloud and Magic Collaboration Studio can be migrated directly from 2022x to 2026x or 2026x Refresh 1.

There is no general requirement to first install Teamwork Cloud 2024x as an intermediate Teamwork Cloud version.

However, there is an important distinction between migrating the Teamwork Cloud infrastructure/database and migrating the models stored in Teamwork Cloud, particularly UAF models.

Teamwork Cloud Software Upgrade Path

The official Teamwork Cloud documentation contains a Teamwork Cloud Software Upgrade Path chart that shows the supported migration path across Teamwork Cloud versions and the associated Cassandra generations.

The documentation specifically states that you can upgrade directly between non-consecutive Teamwork Cloud versions. What you cannot skip are required database migration or Cassandra upgrade steps between the source and target versions.

Official documentation:
Teamwork Cloud — Upgrade and data migration

Teamwork Cloud Software Upgrade Path

For a migration from 2022x to 2026x, the Cassandra requirement is straightforward.

Teamwork Cloud 2022x uses Cassandra 4, whereas Teamwork Cloud 2026x requires Cassandra 5.

Therefore, as part of the migration, Cassandra must be upgraded from Cassandra 4 to Cassandra 5.

You can migrate:

Teamwork Cloud 2022x → Teamwork Cloud 2026x

or:

Teamwork Cloud 2022x → Teamwork Cloud 2026x Refresh 1

There is no requirement to first install Teamwork Cloud 2024x.

Why, Then, Do We Sometimes Recommend an Intermediate Version?

The primary reason is model migration, particularly UAF model migration.

A Teamwork Cloud environment may be running 2022x, but that does not necessarily mean that every project stored in the repository originated in 2022x or is already using the UAF profile version associated with 2022x.

This becomes particularly important with older UAF projects.

UAF Version Considerations

The major UAF profile versions associated with these releases are:

UAF 1.1 was supported beginning with 2021x. UAF 1.2 became fully supported in 2022x and continued through the 2024x releases. Beginning with 2026x, UAF 1.3 is supported, and 2026x Refresh 1 continues to use the UAF 1.3 plugin.

That means the migration path for an individual UAF project depends on the UAF profile version of the project, not simply the Teamwork Cloud server version where the project happens to be stored.

UAF 1.2 Projects

If a project is already using UAF 1.2, it can be migrated to UAF 1.3 using the 2026x modeling tool.

The documented path is:

UAF 1.2 → UAF 1.3

There is no requirement to migrate that project through a 2024x modeling tool simply because Teamwork Cloud is moving from 2022x to 2026x.

UAF 1.1 Projects

The important distinction is between the Teamwork Cloud server migration and the UAF project migration.

UAF projects cannot be migrated directly from UAF 1.1 to UAF 1.3. They must follow the supported migration path:

UAF 1.1 → UAF 1.2 → UAF 1.3

If the current environment is Teamwork Cloud 2022x, there is no need to deploy Teamwork Cloud 2024x as an intermediate step.

Before migrating Teamwork Cloud from 2022x to 2026x, verify that every UAF project is at UAF 1.2.

Legacy UAF 1.1 Corner Case

In practice, a UAF 1.1 project should only still exist in a Teamwork Cloud 2022x environment as a legacy corner case. This could occur if the project was originally created in 2021x using UAF 1.1 and stored in Teamwork Cloud 2021x. Teamwork Cloud was later upgraded to 2022x, but that specific UAF project was never migrated to UAF 1.2.

In 2022x, when a project is opened by a user with the Resource Manager role, the modeling tool prompts the user either to open the project in read-only mode or to continue with the migration to UAF 1.2. Therefore, the project would remain at UAF 1.1 only if it had never been opened since the Teamwork Cloud upgrade or had only been opened in read-only mode.

Once all UAF projects are confirmed to be at UAF 1.2, Teamwork Cloud can be migrated directly from 2022x to 2026x. The UAF 1.2 projects can then be opened with the 2026x modeling tool and migrated to UAF 1.3 using the standard documented UAF migration procedure.

In short: Teamwork Cloud 2024x is not required. You only need to identify and migrate any remaining legacy UAF 1.1 projects to UAF 1.2 before moving to Teamwork Cloud 2026x.

Recommended 2022x → 2026x Refresh 1 Migration Approach

At a high level, I recommend approaching the Teamwork Cloud migration as follows:

1. Back up the existing Teamwork Cloud database. Before beginning the upgrade, create a good, verified backup of the existing Teamwork Cloud/Cassandra database. For a production environment, I strongly recommend verifying the backup and restore process before beginning the migration.

2. Upgrade Cassandra from Cassandra 4 to Cassandra 5. Teamwork Cloud 2022x uses Cassandra 4, whereas Teamwork Cloud 2026x requires Cassandra 5. Therefore, Cassandra must be upgraded from Cassandra 4 to Cassandra 5 as part of the migration.

   The product documentation provides a Cassandra installation script and recommends using it to install and configure Cassandra. The script installs the necessary Cassandra packages and tools, creates the required firewall rules, and installs the required Java version.

   Cassandra installation documentation:
   Installing Apache Cassandra

   The installation script package is also available from the product's downloadable scripts page:
   Downloadable scripts

3. Install Teamwork Cloud 2026x or 2026x Refresh 1. After the Cassandra upgrade is complete, install the target Teamwork Cloud version. For a Linux installation, I strongly recommend using the installation scripts provided with the product rather than manually reproducing all of the installation and configuration steps.

   2026x Refresh 1 installation documentation: 2026x Refresh 1 — Installing services

4. Migrate the Teamwork Cloud projects using the target-version modeling tool. Once the Teamwork Cloud environment has been upgraded and is operational, the projects themselves must be migrated using the corresponding 2026x or 2026x Refresh 1 modeling tool.

The modeling tool allows you to select a group of Teamwork Cloud projects for migration, but this should not be treated as an unattended migration process. During migration, the modeling tool may display dialogs requiring user input to validate migration choices, address project-specific issues, resolve dependencies, or respond when a required plugin is unavailable.

For environments with a large number of projects, the migration workload can be divided among multiple users and performed in parallel. Each person should use a separate Teamwork Cloud user account, launch their own instance of the 2026X modeling tool, and migrate an assigned set of projects.

The migrations should remain actively monitored and should not be launched with the expectation that they can run completely unmanned.