Integrating Rational Software Architect with Rational Team Concert

Compare and merge UML models

Most software development organizations in systems and enterprise areas realize the benefits of Model-Driven Development (MDD) and Unified Modeling Language (UML) and take advantage of them by using the IBM® Rational® Software Architect family of products. IBM® Rational Team Concert™ is the next generation configuration-management environment that is designed with agile development in mind. Based on IBM® Rational® Jazz™ and Eclipse platforms, it provides the necessary resources to achieve success in a globally distributed organization by bringing together newest collaboration technologies, software development planning, source control, and change management functionalities.

The integration between Rational Software Architect and Rational Team Concert is provided from both sides by leveraging Eclipse shell sharing. The Rational Team Concert Eclipse client can be installed into the Rational Software Architect Eclipse shell which will allow you to use the Rational Team Concert functionalities, including source control, work item management, and administration in the Rational Software Architect. On the Rational Software Architect side, you can use visual compare-and-merge functionality for UML models under source control, create work items from problems resulted from validating models, and trace UML resources to Rational Team Concert work items.

The sections that follow illustrate in detail how to work with the integration by imitating a real-life parallel development scenario between two users. This parallel work will cause conflicting changes which need to be handled when the users integrate their work using the Rational Team Concert Client installed in their Rational Software Architect Eclipse shell. The two users will work on a UML project which contains single models, then they will use logical models.

Prerequisite software and knowledge

You need a basic understanding of UML modeling to follow this article and complete the example. Conceptual and practical understanding of configuration management with Rational Team Concert is assumed. The Rational Team Concert environment is configured and ready to use for collaborative development.

The following software must be available for the two hypothetical users in this scenario:

  • Rational Software Architect for WebSphere® Version 7.5.5 or later
  • Rational Team Concert Version or later installed into the Rational Software Architect shell

Connecting to the Rational Team Concert repository

To complete the integration, you will need to have access to a project area on a Rational Team Concert server. Two Rational Team Concert users, User1 and User2 in this example, have appropriate read/write access to the project area. For information how to set up Rational Team Concert, see the Getting Started section in the Information Center.

  1. Start Rational Software Architect for WebSphere in a new workspace.
  2. From the main menu, select Window > Show View > Other.
  3. Select Team > Team Artifacts, and click OK.
Figure 1. Team Artifacts view
Options shown in the Team Artifacts view
  1. Click the Connect to Project Area link.
  2. Click Next to create a new repository connection.
  3. Enter your Rational Team Concert connection information, along with your Rational Team Concert server URI and username and password, as shown in Figure 2.
Figure 2. Jazz Repository Connection
Wizard with connection information
Wizard with connection information
  1. Click the Next > button.
  2. Select your project area, and click the Finish button.

Comparing and merging UML models in Rational Software Architect

When using a configuration management tool such as Rational Team Concert, developers compare and merge files in their day-to-day activities because of parallel development. This becomes even more important when a team uses a more collaborative agile development approach, which often requires developers to continuously integrate their work with other project members' work.

Performing compare-and-merge operations for UML models is much more complex than for text-based files, such as C++ and Java™ code. Rational Software Architect uses an XML-based format for its models to satisfy UML2.0 requirements for its interconnections and semantics.

There are two types of models in Rational Software Architect: single and logical. A single model resides in a single file (.emx); whereas, a logical model is divided into subunits that are physically separated but logically related. In Rational Software Architect, subunits are called fragments and stored in *.efx files that are referenced by the main model (*.emx). Rational Team Concert Version or later supports the Rational Software Architect logical model when working with Rational Team Concert source control.

Importing a sample UML project from Rational Software Architect

User1 will import a sample project named PiggyBank UML models from the Rational Software Architect Samples Gallery. Later, the sample project will be shared with Rational Team Concert source control repository.

  1. From the main menu bar, select Help > Help Contents.
  2. Open Samples > PiggyBank application > PiggyBank UML models.
  3. Click the Import the sample link.
  4. Click the Finish button to import the sample PiggyBank UML model project. The PiggyBank UML project will appear on the Project Explorer view, as Figure 3 shows.
Figure 3. PiggyBank UML project structure
Project Explorer view
Project Explorer view

Sharing a project with Rational Team Concert in Rational Software Architect

Now that you have the sample project, User1 will first create a new Rational Team Concert workspace with a component on the server. This workspace will be used to share the project imported in the previous section with Rational Team Concert source control.

  1. Right-click the project, and select Team > Share Project.
  2. Select Jazz Source Control and then click the Next button.
Figure 4. Share Project window options
Select a repository type with 3 options
Select a repository type with 3 options
  1. Select Create a new repository workspace named, and give your repository a name, such as User1Respository.
  2. Select Share with a component from an existing stream.
  3. Select your component under you project area's stream. If you don't have a component, you can click New Component to create a new one.
    Note: If you create a new component, make sure that your user has appropriate Rational Team Concert permissions.
  4. Click Finish.
  5. In the Pending Changes view, right-click User1Workspace, and select Deliver.
    User1 must be a member of the target team and the project area to be able to perform the Deliver operation.

Importing a project from Rational Team Concert

User1 delivered the PiggyBank UML Models project to the project area's stream so that this project is available for other team members. In the following section, User1 will import the project from the main stream into his Rational Team Concert workspace.

  1. Start a new instance of Rational Software Architect that will be used by User2.
  2. Follow the same steps as in the Connecting to Rational Team Concert repository section to log in to the repository as User2.
  3. Select Show View > Other from the main menu bar.
  4. Select Team > Team Artifacts and click Ok button
  5. In the Team Artifacts view, right-click MyProjectArea > Source Control > Team 1 Stream (Team1), and select New > Repository Workspace. Select your project area and stream name according to your configuration. This example uses MyProjectArea for the project area name and Team 1 Stream for the stream name.
  6. Give your repository workspace a name, such as User2Workspace.
  7. Click Finish.
  8. Select Find and load Eclipse projects as shown in Figure 5, and click Finish
Figure 5. Load the repository workspace
Load Repository Workspace view options
Load Repository Workspace view options


The PiggyBank Models project is loaded into the local workspace.

Delivering nonconflicting changes

User2 will make some changes to the models and deliver them to the main stream. As User1 has not yet modified the models, the changes will be non-conflicting. The changes that will be delivered by User2 to the source control repository will also create model validation problems.

  1. Create fragments for packages in the use case model by right-clicking on the model and selecting Refactor > Fragment All Sub-Packages.
  2. Click the OK button to update references.
  3. Now you will change the actor's name from Customer to Client. Right-client and select Use Case Model > Account Operations > Customer, and then, from the drop-down menus, select Refactor > Rename.
  4. Type Client to replace Customer in the dialog, and click OK.
  5. Now you will create a new model for the project, which will be not added to the Rational Team Concert repository. Right-click and select PiggyBank Models > Models in the Project Explorer view and select Create Model from the drop-down menus.
  6. Select the Standard template, and click the Next button.
  7. Create a Use Case Package model by selecting the Requirements category and Use Case Package template, as Figure 6 shows.
Figure 6. Creating a Use Case Package model
UML model template selection window
UML model template selection window
  1. Click Finish.

The requirements model that you just created is automatically added as a candidate to be checked in to Rational Team Concert source control. Now you'll add the model to the Ignore list so that this model will not be checked in or delivered to the source control repository.

  1. Right-click the model and select Team > Add to Ignore List.
  2. Leave these default selections:
    • What to Ignore: Resources with selected name
    • Where to Ignore: Only ignore items in the same directory
  3. Click OK in the dialog window shown in Figure 7.
Figure 7. Adding a UML model to the What to Ignore list
Options for what and where
Options for what and where
  1. Add a UML actor to the created model by right-clicking on the model and selecting Add UML > Actor. Name it ATM.
  2. Open the Actors Overview diagram from Use Case Model > Overviews.
  3. Drag the ATM actor to the diagram.
  4. Save all models by clicking File > Save All.
  5. In the Pending Changes view, expand your repository workspace component, as Figure 8 shows.
Figure 8. Pending changes view
Incoming and outgoing changes to the controlled elements
Incoming and outgoing changes to the controlled elements
  1. Right-click the Unresolved folder and select Check in and Deliver.
  2. Enter relevant comments under "Change set comment," and then click Finish, as Figure 9 shows.
Figure 9. Check-in and Deliver dialog window
Change set comment field and response
Change set comment field and response

Accepting nonconflicting changes and creating work items from model validation

Now User1 will synchronize his workspace with the main development stream. The main development stream now contains the model changes that User2 delivered in the previous steps. User1 will accept those changes that were delivered by User2 to his workspace. And finally User1 will validate a model and create Rational Team Concert work items from the model validation errors.

  1. In User1's Rational Software Architect window, open the Pending Changes view, and click the Refresh button.
  2. Expand your workspace/component. Accept All incoming changes by clicking on the A icon with the arrow icon in the Pending Changes view.
  3. Open PiggyBank Models > Use Case Model in the Project Explorer. You will see an error message that the model contains one broken reference that might be automatically repairable.
  4. Click the Ignore button.
  5. Validate the Use Case Model by selecting the model in the Project Explorer and clicking Modeling > Run Validation on the main menu bar.
  6. In the Problems view, select the error resulted from validation. Right-click and select Create work-item.
Figure 10. Creating a work item
Work Item Type selection window
Work Item Type selection window
  1. Select Defect as the work item type, and click Finish.

Your list of work item types might be different from the one on Figure 10, because it depends on your Rational Team Concert server's work item template configuration.

  1. Fill out the mandatory fields in the Work Item editor.
  2. Choose the owner of this work item to be User2. Click the Owned By field and select More.
  3. Search for User2, and click OK to set the user as the work item owner.
  4. Save the work item by clicking the Save button.

Merging conflicting changes: nonlogical merge

You have already learned how to compare and merge nonconflicting changes. In the next steps, you will learn how to merge conflicting model changes by using the Rational Software Architect Compare and Merge functionality.

  1. Find work items that are assigned to User2 by opening the Team Artifacts view and selecting MyArea > Work items > Shared Queries > Predefined > Open assigned to me.
  2. In the work items view, shown in Figure 11, double-click the work item to open it.
Figure 11. Rational Team Concert query result
The work item list resulting from a query
The work item list resulting from a query
  1. Now that User2 knows the problem, which is shown on the defect's description, you will add the missing artifacts to Rational Team Concert source control to fix it.
  2. Remove the Use Case Model from the Rational Team Concert "Ignore" list by right-clicking the model in the Project Explorer and selecting Team > Remove from Ignore List from the drop-down menu.
  3. Click OK button.
    Note: You can click the model resource links in the description to browse the UML elements in the Project Explorer.
Figure 12. Work item description
The work item description section
The work item description section
  1. Resolve the defect by changing its status and state to Resolve and Fixed, respectively.
  2. Save the work item.
  3. Now, make changes to the PiggyBank Design Model. Expand PiggyBank Design Model > PiggyBankImplementationDesigns in the Project Explorer view.
  4. Rename PiggyBankImplementationDesignPackages to PiggyBankUser2Design by right-clicking on the diagram and selecting Refactor > Rename from the drop-down menu.

Delivering the changes

  1. Now you are ready to deliver the changes. Open the Pending Changes view. Check in and deliver the unresolved changes.
  2. Assign the defect assigned to User2 to the change set created in earlier. When prompted to provide comments for the change set, click Next.
  3. Check the Show resolved check box so the defect that was resolved will be listed, as Figure 13 shows.
Figure 13. Checking in and delivering change set that is attached to a work item
Associate Work Item dialog window
Associate Work Item dialog window
  1. Click the Finish button.

Handling conflicts

Now we will make changes that will create conflicts in the UML model.

  1. Start Rational Software Architect with User1's workspace.
  2. Repeat Steps 6 and 7 but rename the diagram to PiggyBank User1 Design this time. This will create conflicts with changes made by User1 that should be merged manually.
  3. Save the model.
  4. When you open the Pending Changes view, you should see both Unresolved and Incoming changes. Right click Unresolved and select Check in all from the main menu.
Figure 14. Pending Changes view with Incoming and Outgoing changes
Pending Changes view that show conflicts
Pending Changes view that show conflicts
  1. Accept all incoming changes by clicking Accept all in the Pending Changes view.
  2. Click the Auto-Resolve button.
  3. Click OK on the dialog where it states that none of the conflicts can be automatically resolved.
  4. Manual merge of the models is required now to resolve the conflicts. Double-click the Design model.emx (Modified > Modified).
  5. Figure 15 shows the Compare and Merge editor. Accept changes from User1. User2's changes will be overwritten.
  6. Expand all of the conflicts. Right-click the appropriate conflict and select Accept.
  7. Click the Resolve as Merged button.
  8. Go to the Pending Changes view and enter a comment for the outgoing change set by clicking on it. An editable text box will appear.
  9. Deliver the merged model to the repository by right-clicking on Outgoing changes and selecting Deliver from the drop-down menu.
Figure 15. Model Compare and Merge Editor view
Design Model.emx tab view
Design Model.emx tab view

Enabling logical model compare and merge

To be able to compare and merge UML models with Rational Team Concert within Rational Software Architect, special options need to be enabled. After completing the following steps you will be able to use logical models with Rational Team Concert.

  1. Select Window > Preferences from the main menu bar.
  2. Select Team > Jazz Source Control > Model Enablement.
Figure 16. Jazz source control model enablement preferences
Model Enablement view in the Preferences window
Model Enablement view in the Preferences window
  1. Select these check boxes:
    • Allow modeling tools (for example, UML) to participate in file content during Accept,
    • Logical Models
  2. Click Apply and then OK.
  3. Repeat the steps for both users' workspaces.

Performing a logical model merge

Next, User1 and User2 will create conflicts in the logical model. Later, those conflicts will be resolved.

  1. As User1, rename the Cash Check use case under Use Case Model > Account Operations package by right-clicking on the use case and selecting Refactor > Rename.
  2. Give it a new name of Deposit Check, and click OK
  3. Deliver the unresolved changes to the stream. Repeat steps 16–18 from the Delivering nonconflicting changes section to complete this.
  4. As User2, repeat the preceding steps, from "Check Allow…" through "selecting Refactor > Rename," but name the use case Cash Check (or Cash Cheque). This will create a conflict in the logical model.
  5. Open the Pending Changes view, and check in all unresolved changes that you created in the previous step.
  6. Accept all incoming changes from User2.
  7. Click Auto-Resolve conflicting changes.
  8. When the Logical Merge dialog appears (Figure 17), double-click Logical Models > PiggyBank Models > IBM Rational Logical Model [Root file: Use Case Model.emx] (Full Context Merge).
Figure 17. Logical merge window
Jazz Source Control Model Merge window
Jazz Source Control Model Merge window
  1. Accept the changes that User1 created by right-clicking and selecting Conflicts > Conflicting Modifications > Accept in the drop-down menus.
  2. Save the merged model by clicking the Commit Merge button.

For more information about Rational Software Architect and Rational Team Concert, see the citations in the Resources section.

Downloadable resources

Related topics

Zone=Rational, DevOps
ArticleTitle=Integrating Rational Software Architect with Rational Team Concert