How to Change a Teamscale Project ID since 7.1
Teamscale supports a flexible project ID system that was introduced with its 7.1 release version. Setting and changing these IDs manually is an expert feature that is not necessary during regular operation. However, experienced project administrators may use it to deal with several complex use cases.
Use Case Example: Managing Project Copies
Special circumstances may make it necessary to transparently create a copy of a Teamscale project on the same Teamscale instance as the original project, and to switch between these two projects in a way that is transparent to the end user.
For example, sometimes a prolonged reanalysis of a project may not be feasible because of availability requirements. If a change to the analysis profile of such a project needs to be performed, instead a new project can be created that duplicates the settings of the original project (but with an adapted analysis profile).
After analysis of the new project is completed, the switch from old to new project is performed, after which the user will access the new project rather than the old one. In this way, the necessary changes to the analysis profile can be made without any downtime.
Teamscale Project ID Paradigms
Each Teamscale project is associated with a project ID. This is also referred to as the primary public project ID. In the Teamscale project configuration, it is displayed in the Advanced Settings as the Project ID option. This ID is the only one an end user will typically see, as it is the one that is used to define the URL where the project can be accessed. Additionally, this ID will be used in the UI to refer to this project whenever an ID needs to be displayed (for example, in the system logs view).
In addition to the primary project ID, a project may also have alternative project IDs. These can be set in the field directly below the primary ID. A project may have any number of alternative IDs, although these are completely optional.
The only difference between the primary ID and the alternative IDs is the UI behavior of Teamscale. End users will only see the primary ID of a project, but not the alternative IDs. In all other respects the IDs behave interchangeably. In particular, alternative IDs can be used in REST API calls in place of the primary project ID, and they may be used in URLs to link to the respective Teamscale project. Hence, alternative IDs can be used to preserve backwards compatibility of external systems that reference such URLs.
The primary and the alternative IDs of a project can be changed freely, as long as they don't conflict with any other project ID. In other words, project IDs are globally unambiguous over the complete Teamscale instance. ID changes take effect immediately and do not require a reanalysis of the project.
Implications of Project ID Changes
WARNING
Even though project IDs can be changed freely, it is not always advisable to do so.
In particular, changing a project ID from original-id to new-id means that end users who have bookmarked the URL https://<teamscale-server>/findings.html#/original-id will no longer be able to access this endpoint, until they have changed it to the new https://<teamscale-server>/findings.html#/new-id. In such cases, it may make sense to add original-id to the set of alternative project IDs when renaming it to new-id, allowing the user to keep the old bookmark. Indeed, preserving backwards compatibility for such URLs is the primary use case of the alternative project IDs. Keep in mind that project ID references may crop up in unexpected places, such as the merge request comments Teamscale can perform in code collaboration platforms, or in automated CI pipeline scripts that upload external data to a specific Teamscale project. Hence, project ID changes should be kept to a minimum to avoid unintentional consequences.
Another aspect to keep in mind is the issue of project permissions. For example, if a specific user group is granted the view permission on a specific project, this will be done by project ID. If this project ID is changed, then the users will no longer be able to view the project. If the same project ID is entered as primary or alternative project ID of a second project, then the user group will be able to view the second project, but not the original one. This is the desired behavior for the example scenario mentioned above (migrating a user base transparently from one project to another), but it may not be appropriate for all use cases. Hence, permissions should be checked (and adapted as required) after changing any project ID.