Jazz Library Model Migration: Importing Rhapsody models into Rhapsody Model Manager to migrate from Rhapsody Design Manager
Author name

design-management,rhapsody-model-manager

Mon, 05 Nov 2018
5 min read
0

Model Migration: Importing Rhapsody models into Rhapsody Model Manager to migrate from Rhapsody Design Manager

Hirsch David, Persistent Systems
Last updated: 9 October 2018
Build basis: Rhapsody Model Manager 6.0.6

 

Introduction

Current customers of IBM Rhapsody Design Manager (RDM) are using it to manage their modeling data from IBM Rational Rhapsody.

While introducing Rhapsody Model Manager (RMM) as the new architecture management server that will eventually replace RDM, we must define the workflow to mig rate Rhapsody modeling data from RDM to RMM.

Rhapsody modeling data consists of Rhapsody models and OSLC links. Design Manager manages additional data that will not be imported. See more details in the Limitations section.

When you import a model into Rhapsody Model Manager, the source model is not changed in Design Manager; the import just exports the model and creates new OSLC links for the Rhapsody Model Manager artifacts. The original OSLC links to the Design Manager artifacts are preserved.

The Rhapsody client with the Rhapsody Model Manager Extension includes an additional feature for importing Design Manager models called the Rhapsody Design Manager Import Extension. Use this extension to connect to a running Design Management server and export the models and OSLC links.

The import process uses the Rhapsody client to connect to the Design Management server and extract the Rhapsody model to the local disk. As a second step, the user opens the local Rhapsody model, enables Rhapsody Model Manager, and finalizes the migration of the OSLC links.

Basic concepts

Rhapsody Design Manager models have two basic configuration management modes:

  1. Actively managed models: Rhapsody models are persistent with Design Manager. The import includes a basic step of exporting the models from Design Manager, including OSLC links in a given baseline.
  2. Externally managed models: Rhapsody models are persistent with another configuration management tool, and already available on the disk. The import from Design Manager exports only the OSLC links in a given baseline. The user needs to import the models from the external configuration management tool into Rhapsody Model Manager.

Import multiple configurations

The import process supports importing Rhapsody models and their OSLC links from a single configuration in Design Manager.

Important: We strongly advise importing only one single baseline (typically the latest) for a stream. Later, you can use RMM to split your streams and work with multiple configurations.

To import multiple baselines versions of the same stream, you can run the basic import steps for a single configuration iteratively.  However, this approach has the side effect of growing the repository in size. In this case, the multiple configurations do not reuse the data; the data is duplicated, and there are limitations in how diff/merge works for the life of the project area.

When you import two baselines from different streams of the same project area into two different streams in Rhapsody Model Manager, users have limited support for delivering change sets between the two RMM streams.

Rhapsody models

The import process copies the Rhapsody models from the Design Manager storage to the Rhapsody Model Manager storage. See Setup guidelines for dividing the models into components and updating the locations of referenced units. The import process does not make any changes to the Design Manager data.

During the import process, Rhapsody creates separate saved units for each of the following types: Class, Block, Object, Folder, Component, File and Diagram. This approach is in line with the default behavior in Rhapsody Model Manager.

Referencing models

When importing multiple Rhapsody projects with referenced packages between them, it is important to specify the order of import; we recommend importing first the Rhapsody projects containing the packages referenced by other Rhapsody projects.

Example:

Project 1: Pkg1

Project 2: Pkg2, Pkg1(REF)

Project 3: Pkg3, Pkg2(REF), Pkg1(REF)

Import order: Project 1, Project 2, Project 3

Rhapsody models often reference Rhapsody profiles. Therefore, you should import Rhapsody profiles before importing Rhapsody models. See also User profiles.

OSLC links

Introduction

Design Manager uses several types of links, based on configuration context and ownership, which is defined by repository storage location, such as IBM Rational Team Concert (RTC), IBM Rational DOORS Next Generation (DNG), or IBM Rational Quality Manger (RQM). We can differentiate the links by two criteria:

  1. Configuration managed environment: In a global configuration context with LDX support compared to in a single default stream context
  2. Link ownership: Storage location in Rhapsody Design Manager (RDM) or in the target application

Table 1 examines these criteria for OSLC links from Rhapsody Design Manager (RDM), and Table 2 shows how things change with Rhapsody Model Manager (RDM). 

Storage Location for RDM OSLC Links

Configuration Managed (GCs)

Not Configuration Managed

Link type

DNG

RDM

RDM

Derives from, Refines, Satisfies, Trace

DOORS

Not supported

RDM

Refines, Satisfies, Trace

RQM

RQM (LDX)

RQM (back link in RDM)

Validated by

RTC CCM (work items)

RTC (LDX)

RTC (back link in RDM)

Elaborates

RDM

RDM

RDM

All types + custom link types

External web page

RDM

RDM

External web page

Table 1: Storage locations for OSLC links from RDM to the supported applications

Storage location for RMM OSLC Links

Configuration Managed (GCs)

Not Configuration Managed

Link type

DNG

RHP files

RHP files

Derives From, Refines, Satisfies, Trace

DOORS

Not supported

RHP files

Refines, Satisfies, Trace

RQM (test cases)

RQM (LDX)

RQM

Validated By

RTC CCM (work items)

RTC (LDX)

RTC

Elaborates

RDM/RMM

Not supported [see note]

Not supported

All types + custom link types

External web page

RHP files

RHP files

External

Table 2: Storage locations for OSLC links from RMM to the supported applications

Note: As of RMM 6.0.6, all RMM-to-RMM links are local or native, not OSLC links. With back links each artifact stores a link that points to the other artifact.

RDM-to-RMM link mappings

It is clear from these tables that we can easily map most kinds of links between RDM and RMM.

RDM-to-DNG links:

  • Create an OSLC link with the same link type: Derives From, Refines, Satisfies, Trace.
  • Store the links in RHP files.

RDM-to-DNG links and RDM-to-DOORS links (only configuration-managed links are supported):

  • Create an OSLC link with the same link type: Refines, Satisfies, Trace.
  • Store the links in RHP files.

RDM-to-RQM links:

  • Create an OSLC link with a similar link type (see below): Validated By.
  • During migration re-create the link in RQM (with or without a global configuration context).

RDM-to-RTC CCM (work items):

  • Create an OSLC link with the same link type: Elaborates.
  • During migration re-create the link in RTC (with or without a global configuration context).

RDM-to-an external web page:

  • Create an OSLC link with a similar link type: External.
  • Store the links in RHP files.


Here is how migration handles some exceptions.

RDM-to-RQM links

RQM added support for creating OSLC links to architecture elements in version 6.0.6. Earlier, RQM supported only requirement elements. RDM acted as a requirements provider to support links to RQM.

The Design Manager links to RQM are of the type Validated By <oslc_rm::validatesRequirement>, and the links from Rhapsody Model Manager to RQM are of the type Validated By <oslc_rm::validatesArchitectureElement>.

Because both link types have the same label, the main difference for the user is in the RQM client, where the links appear in the Architecture Element Links section and not in the Requirements Links section.

RDM supported OSLC links to any of the RQM artifact types. RMM supports OSLC links only to RQM test cases. Link migration to artifacts other than RQM test cases fails, but you can migrate them as external links.

RDM-to-RDM links

RMM does not support OSLC links to model elements in either RDM or RMM. RDM-to-RDM OSLC links are converted to OSLC links of the type “External”, pointing to the original RDM model element URI (without any context). The link goes to the element in the default stream in that project area. To point to the correct local or global configuration, you must manually add the correct link.

Typically, users prefer to use native Rhapsody dependencies to link between two Rhapsody artifacts.

See more about OSLC link limitations.

Diagnostics and validation

The import process provides some basic diagnostics to validate the completeness of the import process.

  • You can compare the number of model artifacts by type in the Design Manager model with the number of model artifacts in the Rhapsody Model Manager model.
  • You can compare the number of exported OSLC links from Design Manager with the number of migrated OSLC links in Rhapsody Model Manager.

Preparation

  1. Before you begin:
    1. Install IBM Rational Rhapsody Client version 8.3.1 with the Rhapsody Model Manager Extension and the Design Manager Import Feature.
    2. Upgrade the Design Management server to Design Manager 6.0.6.
    3. Install the RTC Eclipse client. (See the RTC topic on Installing Rational Team Concert clients.)
  2. Create an RMM target project area that will match the Design Manager source project area.
    1. Plan which Rhapsody Design Manager projects and configurations you want to import to RMM.
    2. Plan the configuration management settings (enable Configuration Management) for the RMM project area.
      Note: In RMM version 6.0.6, the creation of OSLC links requires the source and target applications to have the same configuration management settings.
    3. Create matching projects and streams in RMM with the right configuration management settings, project associations, and global configuration contributions. See more at RMM setup guidelines.
  3. Add associations between the Rhapsody Model Manager project area and the projects in other applications, equivalent to the associations of the Design Manager project area. Use the following association types:
    • DNG (RM):
      • Uses – requirements
    • DOORS (DWA):
      • Uses – requirements
    • RTC CCM (work items):
      • Uses – change requests (for linking RMM architecture elements to RTC CCM work items)
      Uses – change sets (for linking RTC SCM change sets to RTC CCM work items)
    • RQM:
      • Provides – Architecture Elements
  4. Add the RMM target streams as contributors to all the global configuration streams that have contributions from the Design Manager source streams.
  5. Create an RTC repository workspace (sandbox) for the target streams to store and deliver the imported models.
  6. Define the order of dependencies of the Rhapsody projects (see Referencing models), including dependencies on Rhapsody profiles.

Setup guidelines

Before you import data from Rhapsody Design Manager to Rhapsody Model Manager, you should plan how to structure the data in RMM in project areas, streams, and components.

By default, you can match the RDM structure with the RMM structure. It is probably simpler if you first align with the Design Manager structure and later restructure the models after the import is complete.

RDM

RMM

Comments

Project area

Project area

Map 1-to-1

Stream

Stream

Map 1-to-1

Baseline

Snapshot

An RTC snapshot encapsulates multiple component baselines.

Single component

Multiple component

You can split up the Rhapsody models between multiple components to optimize read/write access control, concurrent model editing, etc.

Create project areas

Create matching target project areas in Rhapsody Model Manager for every source project area in Rhapsody Design Manager that you want to import at this time.

For each RTC project area add project associations, just as you would with an RDM project. The associations will resolve the OSLC links when the project is imported to RMM.

In RMM version 6.0.6, specify whether or not to enable configuration management for the project area. You can create OSLC links only between matching applications. For example, if you specify that the project area is enabled for configuration management, you can create OSLC links to DNG requirements in configuration management-enabled project areas, but not to requirements in DOORS (DWA), because that project doesn’t support configuration management.

Create streams

Create a matching initial target stream in RMM for every stream in Rhapsody Design Manager that you are importing. You can import multiple streams from Design Manager.

For each stream, run a data import of all the models in the latest baseline. To include older baseline versions of the model, import the models from the older baselines first, and then import the final latest baseline version of the stream.

See more at Import multiple streams and baselines.

Create components

You can split up the models into multiple components.

Follow the guideline of RMM component usage to choose between:

  • A single Rhapsody model per component
  • Multiple Rhapsody models per component
  • Multiple components per Rhapsody model
Note: RTC version 6.0.6 limits the maximum number of components to 2500.

Global configurations

To validate the OSLC links to your global configurations, you need to add matching RMM configurations to the global configurations. For each global configuration stream with a Design Manager stream contribution, add a contribution for a matching stream from Rhapsody Model Manager.

Be careful about the sequence: only after you import can you remove the Design Manager contribution from the global configuration.

User profiles

Design Manager advises users to create a domain from the Rhapsody profile. The domain is a duplication of the profile used by the Design Management server to define the metamodel structure. The Rhapsody profile itself is externally managed in an external configuration management tool or actively managed by the Design Management server.

The import process does not import the domain itself. You must import the model that manages the profile Rhapsody element by following the standard procedure for importing Rhapsody models.

Consider whether Rhapsody models in multiple projects will share the same profile. To manage the profile versions used by different models, you can store the profiles in a separate component (with its own baseline versioning).

Rhapsody models commonly reference Rhapsody profiles. Therefore, we recommend importing the Rhapsody profiles before importing the Rhapsody models. See also Referencing models.

Common Rhapsody units (referenced and external)

Consider storing commonly used Rhapsody units, like a common profile (such as MyProfile.sbsx) or a common package defining types (such as CommonTypes.sbsx) in their own RTC component or even RTC project area. The different Rhapsody models can reference them or include them as external units.

 

Import workflow

Import Design Manager actively managed models in a single stream

Before you begin: Install Rhapsody 8.3.1 with Rhapsody Model Manager and the Design Manager Import Feature.

  1. Define the order of dependencies of the Rhapsody projects (see Referencing models).
  2. Create an RMM target project area with the same associations as the Design Manager project area (associations with DNG, DOORS, RQM, and CCM).
  3. Plan the Rhapsody projects, streams, and baselines that you will import.
  4. Create a matching initial target stream in RMM. Plan your components accordingly.
  5. For each target stream, create an RTC sandbox (repository workspace) to store the imported models.
  6. Open the Rhapsody client. For each Rhapsody project managed on the server:
    1. Select File > Import from Design Manager.
    2. Specify the location of the model on the Design Management server.
      To import OSLC links from an RQM or RTC project area that has configurations enabled, open the model from the correct global configuration baseline.
    3. Fill in the import options:
      1. Make sure both check boxes are selected (the default).
      2. Specify the target directory on the disk to save the Rhapsody model (it is best to store it directly in the RTC Repository Workspace – Sandbox).
    4. Click Finish. A progress bar shows the following steps:
      • Opening the model in Design Manager
      • Loading the entire model
      • Retrieving Design Manager local links
      • Retrieving Design Manager remote links (if you’re in a global configuration context)
      • Saving the model locally
      • Closing the model
      • Reopening the model
    5. Use the wizard to specify the local location of all referenced packages and profiles that are not found.
    6. All OSLC links that still need to be migrated are shown in the Rhapsody Client as dependencies with a special icon marking them “still to be migrated.”

    7. You are prompted to Enable Rhapsody Model Manager if you haven’t already.
    8. Migrate the OSLC links. You can also do it later by right-clicking a project and selecting Migrate OSLC Links.
      • The links are grouped by target server and by link type. Decide how to handle each group. You see a detailed description of the current action and status in each section as you go.
        • To be Migrated: The links are migrated to Rhapsody Model Manager and stored locally or in a remote application. You can specify which global configuration should include them
        • To be Skipped: The links are not migrated, but users can migrate them later.
        • To be Discarded: The links are discarded, and they can’t be migrated later.
      • If OSLC links are not supported in RMM, you can migrate them as external links. See RDM-to-RMM link mappings.
    9. Click Migrate all OSLC Links (the default). All links are migrated to Rhapsody Model Manager according to the migration policy (see RDM to RMM link mappings).

Import externally managed models from Design Manager

Before you begin: Install Rhapsody 8.3.1 with “Rhapsody Model Manager” and the “Design Manager Import Feature”

  1. Define the order of dependencies of the Rhapsody projects (see Referencing models)
  2. Create an RMM project area, with the same associations as the Design Manager project area (associations with DNG, DOORS, RQM, and CCM).
  3. Plan the Rhapsody projects, streams and baselines that you will import.
  4. Create a matching target stream in RMM. Then plan your components accordingly.
  5. Create a matching initial stream in RMM. Then plan your components accordingly.
  6. For each target stream, create an RTC sandbox (repository workspace) to store the external managed models.
  7. Import all your Rhapsody models from your original configuration management tool into the RTC repository workspace (sandbox). Fix the paths of referenced packages.
  8. Open the Rhapsody client. For each Rhapsody project externally managed on the server:
    1. Open the Rhapsody project locally from the RTC sandbox (imported in step 6 above)
    2. Select File > Import from Design Manager.
    3. Specify the location of the model on the Design Management server (externally managed project area):
      1. Baseline configuration only.
      2. To import OSLC links from an RQM or RTC project area that is enabled for configurations, specify the location of the model from the correct global configuration baseline.
      3. You can only select the model with the same name as the active Rhapsody project (the one you selected in step 8a).
    4. Specify the import options: Select the Import OSLC Links check box.
    5. A progress bar shows the following steps:
      • Connecting to the imported model from Design Manager
      • Retrieving Design Manager local links
      • Retrieving Design Manager remote links (if you are in a global configuration context).
      • Saving the updated model locally
      • Closing the model
      • Reopening the model
    6. In the Rhapsody client you can see all the OSLC links that still need to be migrated as dependencies with a special icon marking them “still to be migrated”.

    7. You are prompted to Enable Rhapsody Model Manager if you haven’t already.
    8. Migrate the OSLC links. You can also do it later by right-clicking a project and selecting Migrate OSLC Links. 
      • The links are grouped by target server and by link type. Decide how to handle each group. You see a detailed description of the current action and status in each section as you go.
        • To be Migrated: The links are migrated to Rhapsody Model Manager and stored locally or in a remote application. You can specify which global configuration should include them.
        • To be Skipped: The links are not migrated, but users can migrate them later.
        • To be Discarded: The links are discarded, and they can’t be migrated later.
      • If the OSLC links are not supported in RMM, you can migrate them as external links. See OSLC links.
    9. Click Migrate all OSLC Links (the default). All links are migrated to Rhapsody Model Manager according to the migration policy. (See RDM-to-RMM link mappings.)

Import multiple streams and baselines

To import multiple baselines of a stream, you must plan the order of importing and re-create the baselines in the RTC sandbox while importing the models from the different baselines. Please note that there is no guarantee of incremental or minimal difference between the different imported baselines in RMM. See also Import multiple configurations.

  1. Plan which Rhapsody project, stream, and baselines to import
  2. Create a matching initial target project and stream in RMM. Plan your components accordingly.
  3. Create an RTC sandbox from the target stream to store the imported models.
  4. For every baseline to import (from oldest to newest, including the latest baseline):
    1. Import the Rhapsody models from the baseline (see the previous procedures).
    2. Create a new RTC baseline of the target stream

Automation

The import process provides basic automation capabilities to import Rhapsody models from the Design Management server to a Rhapsody Model server. Based on these capabilities you can automate the import process.

Java API

Detailed information about the interfaces and methods that are contained in the API can be found in the Javadoc output, which is located in the [Rhapsody installation directory]\Doc\java_api directory. The file index.html is the entry point to the reference material.

    IRPApplication
      loginToDesignManagerWithUsername(String serverURL, String userName, String password)
      importDesignManagerModel (String serverURL, String projectAreaName, String localOrGlobalBaselineName, String modelName, String saveasDirectory, int includeLinks).
      setHiddenUI(int value). This API silences the default wizards to enable Rhapsody Model Manager and Migrate OSLC Links.
    IRPProject
      enableRhapsodyModelManager ()
      setGlobalConfiguration (String globalConfigurationUri, String globaConfigurationName)
      migrateDesignManagerLinks()
      For links to RQM and RTC CCM work items, manually provide your login credentials in the Rhapsody client. You can trigger the login dialog with loginToRemoteArtifactServer() on the Remote Artifact Package. If the user is not logged in, migration will skip these links.
    IRPDependency
      isNeedToMigrate()
    IRPPackage
      loginToRemoteArtifactServer()

RTC client automation

RTC provides basic automation for the following elements and others: 

  • Creating project areas, streams, baselines, and components
  • Loading of local repository – sandboxes

See more at RTC source control command line reference.

 

Limitations

Configuration management limitations

  • You cannot import data history (change sets or version history)
  • There is no file version reuse between baselines and streams; the import of every configuration is done independently, without the reuse of RTC file versions.
  • Limited support is provided for deliveries between streams; every change set delivery from one stream to another shows up as having conflict changes and requires manual merging of the files.
  • RMM supports import only from Design Manager baselines. To import a stream, you must first create a baseline from it.

OSLC link limitations

  • Links belonging to all associated project areas are migrated (with limited filtering options).
  • There is no validation of the OSLC links after migration (from DNG or DOORS). As a result, OSLC links might reference deleted requirements. Design Manager views might filter out orphan links, but in Rhapsody Model Manager they still appear as unresolved target URIs.
  • When importing history baselines, the import process cannot create links to RQM or RTC CCM in the target application because they are read-only.
  • RDM-to-RDM links are migrated as external links to the original RDM URI. They lose their original link type.
  • In an RDM-to-RQM migration, test case artifacts are not migrated.
  • OSLC link descriptions are not imported, because RMM, aligned with the OSLC specification, does not support OSLC link descriptions.
  • The link validity status of OSLC links is not imported to RMM. All links start off as suspect (as soon as RMM supports link validity).
  • There is no automation support of login to RQM and to RTC CCM. To re-create OSLC links to RQM and RTC CCM work items, you must manually provide login credentials in the Rhapsody client.
  • The import process does not remove the original OSLC links from Design Manager to RQM or RTC from the views in those products; you must delete them manually.
  • The import process does not remove the original OSLC links from Design Manager to DNG or DOORS. If required, you can remove the project association between the project areas in Design Manager and DNG or DOORS to remove the links from the views in those products.

Data that is not imported

  • Model diagram images: Diagram images are not migrated, and need to be recreated with RMM.
  • Comments and markups: You can export them with a Rational Publishing Engine report.
  • Reviews: You can export them with a Rational Publishing Engine report.
  • Queries, impact analysis diagrams, and Explorer viewpoints.
  • Sketches, freeform diagrams, upload files, and documents.
  • Simulink data and models.
  • Modified time for changes to Rhapsody model elements.

Troubleshooting

Error handling

Actively managed models that fail to load

Rhapsody loads actively managed models on demand. As a result, in rare cases, the entire model might fail to load. Many possible cases are fixed, but some models could still fail.

You can try exporting models from the Rhapsody version that is currently used with Design Manager, and then importing only the OSLC links by using Rhapsody Model Manager Version 8.3.1.

For more information

About the author

David Hirsch is a Development Architect who leads the RMM Development team.


© Copyright IBM Corporation 2018

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Mon, 05 Nov 2018