Skip to content

Migration Guide

This step-by-step guide provides detailed instructions on how to migrate a project from one version of the SECURE RCP to another. For clarity, we define the current version as the version of the RCP 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.

Preparations

We assume that you know which version of the RCP was last used to edit the project. This is the current version. If you’re unsure, you can identify the RCP 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 SECURE RCP 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 the RCP 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, the RCP may not support a direct migration. You can determine this from the release notes, and if the migration is not possible, the RCP 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.

Steps to Perform

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.

  1. Confirm Project Readiness
    The first step for each migration is to open the project in the current version and perform a few checks to ensure a smooth migration.
    1. Run the Model Checker on the Entire Project
      In the “Project” tool window, select the root project node, right-click it, and select “Check Project”. The result should not list any “Errors”. Entries marked as “Warning” or “Info” are usually fine. Any “Errors” found will require changes to the model to resolve them. The specific actions required depend on the listed errors.
      A migration assumes that the project adheres to the norms and standards of the previous version. Therefore, an “Error” may cause the migration to misinterpret the model, leading to deviations from the original design.
    2. Execute Migrations
      In the main menu, select 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.
    3. Run Re-Runnable Migrations
      In the main menu, select 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.
      For instance, it will ensure that any data imported from XSAM after the last migration didn’t introduce outdated formats and definitions.
  2. Snapshot the Current Project State
    Before each migration, we strongly recommend creating a snapshot of the current state. This ensures that the migration history is recorded, and you can revert to this state if any issues arise.
    1. Check the Current Versioning Status
      For Git-managed projects, check the “Git” tool window in the RCP to see if there are any local changes. If using Git via the console, run git status to check for pending changes.
      If the status is clean, you can skip taking a dedicated “before migration X” snapshot.
    2. Create a Snapshot
      Examine any pending changes, then create a snapshot by committing the changes via the tool window or console. If the change list includes model changes, be sure to use a meaningful commit message. Otherwise, a message like “before migration X” (with “X” replaced by the target version) is perfectly acceptable.
  3. Initiate Migration
    Once you’ve confirmed the project is ready, you can begin the actual migration. Close the current version of the RCP and open the project in the target version of the RCP.
    1. Interrupt the Process if an Intermediate Migration Step is Needed
      If the gap between the current version and the target version is too large, you’ll need to migrate in multiple smaller steps. The RCP 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 the RCP.
    2. Ignore Error Messages for Now
      If the project worked perfectly in the 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.
    3. Perform the Migration
      Upon opening the project in the 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 the RCP, go to Migration → Run Migration Assistant in the main menu.
      1. Interrupt the Process if a Migration is Missing
        If an incompatibility checker fails to trigger and you see messages like 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.
      2. Execute the Migration
        In the Migration Assistant dialog, initiate the migration. You may be warned about errors in the project. If you’re confident these issues are due to the migration not being executed yet, or that the migration will resolve them, proceed and instruct the dialog to continue. The migration should complete successfully after a short period. Close the dialog once done. If any issues arise during the migration, feel free to reach out for assistance.
  4. Snapshot the New Project State
    After the migration is complete, we strongly suggest creating another snapshot of the project state. This ensures that the migration is reflected in the history and allows you to revert to this version without having to repeat the migration.
  5. Migration After-Care
    After performing the migration, you are ready to proceed in the 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.
    1. Run the Model Checker on the Entire Project
      If the 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?
    2. Run Re-Runnable Migrations
      Since all migrations should have been executed by now, this step is more of a precaution than a necessity. However, it can be beneficial to check if any migrations that didn’t immediately run might still optimize the project in some way.