This step-by-step guide provides detailed instructions on how to migrate a project from one itemis SECURE version to another. For clarity, we define the
current version as the version of itemis SECURE the project is currently using, and the
target version as the version to which you wish to migrate the project. This guide assumes that the project is managed with
Git (or a comparable version control system), and will instruct you to create snapshots of your project at key stages to ensure you do not lose any progress in the unlikely event that the migration fails. Other forms of backups, such as file-system-based backups (e.g., a plain copy of the project folder), are acceptable but must be properly managed by you. It is ideal to begin this guide with the project in a clean (committed) state in your version control system.
We assume that you know which version of itemis SECURE was last used to edit the project. This is the
current version. If you’re unsure, you can identify the itemis SECURE version
without opening the project by using the Version Mapping Table found at the end of the release notes. This process requires some familiarity with directly opening and reading configuration or data files without using the itemis SECURE interface. This is generally the least intrusive way to determine the project’s version, as opening the project in a version other than the
current version may lead to unwanted alterations. However, if proper versioning is in place, any alterations can typically be reverted.
Secondly, we assume that both versions of itemis SECURE are already installed and ready to use. You do not need to have both versions open at once, and we strongly recommend operating in only one version at a time. This helps prevent situations where the same project is loaded in multiple versions simultaneously, which could lead to conflicts over write privileges and potential corruption of the project (similar to how opening the same document in multiple office applications could cause problems).
Finally, we assume that migrating from the
current version to the
target version is directly possible. If the gap between these versions is too large, itemis SECURE may not support a direct migration. You can determine this from the release notes, and if the migration is not possible, itemis SECURE will notify you when you try to open the project in the
target version. In such cases, you may need to perform the migration in multiple smaller steps, ensuring that the
current version and
target version in the step-by-step guide match the individual migration step, not just the final outcome.
This guide is designed to help you anticipate potential stumbling blocks when performing a migration. You don’t need to follow every step rigidly if you’re familiar with the process.
current version and perform a few checks to ensure a smooth migration.
Migration → Run Migration Assistant. This should usually complete immediately and display a message indicating that no migration is required. This ensures that any necessary migrations have been applied at least once.
Migration → Migrations → Execute Re-Runnable Migrations. This ensures that any edits made to the project since the last migration are in the correct model format and style.git status to check for pending changes.target version) is perfectly acceptable.
current version of itemis SECURE and open the project in the
target version of itemis SECURE.
current version and the
target version is too large, you’ll need to migrate in multiple smaller steps. itemis SECURE will notify you if an incompatible version is detected. Pay attention to the message, download and install the necessary intermediate versions, and repeat the process as needed. Ideally, revert any automatic changes made by the incompatible version using the Git console after closing itemis SECURE.
current version but you see error messages upon opening it in the
target version, these are typically non-critical and should be resolved during the migration process.
target version for the first time (and every time until the migration is performed), a dialog should inform you of required migrations. If this dialog doesn’t appear automatically and you’re sure you’re using a newer version of itemis SECURE, go to
Migration → Run Migration Assistant in the main menu.
Missing: <script for version x>, this indicates a migration is missing. In such cases, either attempt to handle the migration in smaller steps or contact us for guidance.
target version. However, we recommend taking a few extra minutes to complete these additional steps. Feel free to snapshot between steps and especially after the final step to keep these changes distinct from your model edits.
target version or the Migration Assistant dialog reported errors, it’s crucial to verify that all issues have been resolved after the migration. If errors persist and you cannot fix them yourself, please contact us. Even if no errors were reported, it’s always a good idea to periodically check for issues, so why not do it now?