When upgrading to a new Capella product, your older models may not be compatible right away with this new version. In order to facilitate this transition, Capella offers a migration feature that allows you to migrate your models.
The migrated projects are not backwards compatible. This means that once they are migrated to the new version, they can not be opened with the previous Capella versions.
A Capella version ensures project migration of model coming from at least the previous major release versions and if any, from previous patches of the current version. (For instance, Capella 6.x version will be able to migrate models coming from previous major release versions (any 5.x) and previous patches of the current version). Capella 6.x also allows migration from models coming from version 1.4.x. If your model is too old, then you will have to install an intermediate Capella release to perform the migration.
We strongly recommend that you baseline your model in a version control system before performing the migration operation. Once this is done please continue with the following migration steps:
- Migrate any libraries towards which you model has any dependencies. If your libraries have dependencies towards other libraries then they must be migrated first. You should start your migration process with the library that has no external dependencies, and continue progressively to the top dependency.
- Migrate your projects.
The displayed dialog allows you to to make a versioned backup (baseline) of the model before running the migration. These backup files will allow you to recover your model in case of any migration problems, even if the model is not managed in a source control system.
We highly advise you to enable the option “Backup models before the migration”.
Some additional migration commands are available on semantic and diagram files allowing advanced migration processes by triggering a migration on each of these files kind separately. For more details see the Commands & User Profiles (online documentation) section.
| At the end of the migration process, we recommend you to run a manual global refresh on all the diagrams of the migrated project. For more details see the Diagram Refreshing Strategies (online documentation) section. |
For legacy models coming from older Capella releases that includes such legacy Capella requirements, you have to either:
- install the new addon Basic Requirement first and then run a standard project migration
- detach the legacy requirements if they are not used, using model detachment (see How to detach viewpoints) or continue to use this new addon to exploit the legacy requirements.
When doing the migration, the image that were previously used with absolute path will be copied into the project in the workspace. The "Error log" view will log the images that have not been found.
Then you can start the validation, and the I_46 and I_47 constraints will check that the images are reachable. The quick fix allows to select a new image among the available one in the workspace.
But before fixing the path to the image one by one, check that the set of images are properly located where it is supposed to be. Then you can restart the migration to properly copy the image from the full path location to the relative workspace path
As usual, and not specifically for the images, prefer starting the migration by the Capella libraries. The image migration process is the same for the Capella libraries and for the Capella project.
Most of the attention points are specific to the migration towards Capella 6.0.0.
Nevertheless, the migration error log messages, the usage of the validation and the quick fixes will remain useful after 6.0.0
1- Before starting the migration, make sure that the images, that are referenced by the Capella/aird model in the description tab, are at the proper location. The reference may be either an absolute path (used in 5.2.x) or a project relative path.
2- Start the Capella migration
- old base64 encoded images are converted into an image in the workspace (5.2.x to 6.x migration)
- old "absolute path" image are copied in the workspace (5.2.x to 6.x migration)
- old project relative path are made workspace relative (5.2.x to 6.x migration)
3- (optional) you may restart 1-2 steps if needed.
4- Make sure I_46 and I_47 constraints are checked according to your needs.
5- Start validation on the root Capella element.
6- Open "Information" view and check the errors about the image. (The messages start by "(Image)")
7- You may consider to 1-2 steps again
8- You can repair the image paths using the quick fix on the markers. It will allow to select a new image.
In addition, consider using a versioning tool like Git to be sure to save the whole content of the workspace including the libraries and the contained images.
Please refer to the document at Migration command line (online documentation) for more details about launching project migration in command line. An example of how to migrate projects in batch mode can be found at Migration command line in batch mode (online documentation).