Migrating UML models to the IBM Rational Software Architect 8.0 format

In this Technical Tip, you will learn how to efficiently migrate your models to the new format used by the IBM® Rational® Software Architect 8.0 solution. To take advantage of faster model opening times in this version of the Software Architect solution, you must first migrate your existing models to the Software Architect 8.0 format. The Technical Tip shows you how to make a smooth migration to the Software Architect development tool.


Wayne Diu, Software developer, IBM Canada

Wayne DiuWayne Diu is an IBM Rational software developer. He has designed and implemented Unified Modeling Language (UML) features on the Rational Modeling Platform, such as server integration and model search. In addition, Wayne was one of the developers responsible for establishing the metamodel integration framework platform. Wayne has also developed a diverse collection of other tool features such as printing, validation marker enhancements, and refactoring support.

developerWorks Contributing author

05 October 2010

Also available in Chinese

The IBM® Rational® Software Architect 8.0 solution offers performance enhancements when working with diagrams. To leverage this benefit, you must first migrate your models to the new format used by the Software Architect 8.0 design environment.

To migrate your models, you can open each model individually. Then, in the Model Editor, show the Details page. In the Model Operations section, click the Upgrade... button.

Figure 1. In the Model Editor, press the Upgrade... button to manually migrate your model
Picture shows the Model Editors Details section.

If you have numerous models you wish to migrate, you may find the above process time consuming. In order to work more efficiently, it's a good idea to batch migrate your models by migrating them before you begin working with them.

You can write a pluglet that uses public Application Programming Interface (API) from the Unified Modeling Language™ (UML) Modeler component of the Rational Software Architect development environment which will migrate your models automatically.

Enabling pluglet functionality

First, ensure you have pluglet functionality installed. Launch the IBM Installation Manager and choose the Modify option. Select the appropriate package group and click Next twice. You should see the screen below. From here, expand IBM Rational Software Architect and Extensibility and patterns-based engineering. Be sure the Pluglets checkbox is checked.

Figure 2. In the Installation Manager, ensure the Pluglets functionality is installed
Graphic depicts the Modify Packages page.

Larger view of Figure 2.

Second, to actually enable the pluglet functionality in the product, show the Preferences dialog and choose General, Capabilities. Then, click the Advanced… button and expand Development in the Capabilities tree. Check the Pluglet Development checkbox.

Figure 3. Ensure the Pluglet Development capability is enabled
Screenshot shows Advanced Capabilities Settings

Third, download the pluglet attached to this article and import it into your workspace using File, Import..., Existing Project into Workspace.

Running the pluglet

You are now ready to run the pluglet.

To run the pluglet, right click on MigrateModel.java and choose Run As, Pluglet from the context menu.

Figure 4. Choose Run As, Pluglet
Graphic shows the Project Explorer's context menu.

Note: If Run As, Pluglet does not appear, it is likely because you did not complete the first two steps from the previous section.

You will be prompted to either migrate open models only or everything in the workspace. Choose the appropriate option and wait for the migration to complete.

Migration errors

Migration status, including migration errors, will appear in the Console view. From there, you can see which models were migrated successfully and which encountered migration errors.

Figure 5. Migration status is shown in the Console view
Picture shows Migration Errors and the Console view.

Larger view of Figure 5.

By design, the migration will fail if you do not have all required profiles available in your workspace: pop up dialogs will also appear during migration if this is the case.

To remedy this situation, be certain you have those profiles in your workspace or unapply the profile from the affected models. To unapply the profile, open the model. From the Model Editor, show the Details page. Select the missing profile and press the Remove or Repair… button.

Figure 6. Unresolved profiles must be removed or repaired in order for migration to be successful
Graphic shows the Model Editor's Details section.

Larger view of Figure 6.

The pluglet may also fail when it encounters unmigrated models with numerous cross model references. You can follow the instructions in Technote 1443594 for a solution to this issue. Once the model has been successfully migrated, it is no longer to follow the steps described in the Technote.

Understanding the pluglet

The pluglet decides which models are to be migrated by prompting the user to migrate all models, or only the open models. If the user selects to migrate only the open models, the public API call UMLModeler.getOpenModelRoots() is used. Alternatively, if the user chooses to migrate all the models, we consult the workspace root for the projects and recursively go through to find .emx (model) files.

For each of the files to migrate, we run the public API UMLModeler.forceMigrate(String) inside an AbstractTransactionalCommand. It is necessary to run the migration inside an AbstractTransactionalCommand because model elements will be modified by the migration process.


Having followed the steps outlined above, you are now able to successfully migrate models into the Software Architect 8.0 environment. By leveraging features that help you quickly open models, your team is better able to work more productively.


The author wishes to thank Dusko Misic and Michael Hanner for reviewing this article.


Puglet for this articlecom.ibm.xtools.migration.zip4KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=Migrating UML models to the IBM Rational Software Architect 8.0 format