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 126.96.36.199 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.
- Start Rational Software Architect for WebSphere in a new workspace.
- From the main menu, select Window > Show View > Other.
- Select Team > Team Artifacts, and click OK.
Figure 1. Team Artifacts view
- Click the Connect to Project Area link.
- Click Next to create a new repository connection.
- 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
- Click the Next > button.
- 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 188.8.131.52 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.
- From the main menu bar, select Help > Help Contents.
- Open Samples > PiggyBank application > PiggyBank UML models.
- Click the Import the sample link.
- 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
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.
- Right-click the project, and select Team > Share Project.
- Select Jazz Source Control and then click the Next button.
Figure 4. Share Project window options
- Select Create a new repository workspace named, and give your repository a name, such as
- Select Share with a component from an existing stream.
- 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.
- Click Finish.
- In the Pending Changes view, right-click User1Workspace, and select Deliver.
Note: 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.
- Start a new instance of Rational Software Architect that will be used by User2.
- Follow the same steps as in the Connecting to Rational Team Concert repository section to log in to the repository as
- Select Show View > Other from the main menu bar.
- Select Team > Team Artifacts and click Ok button
- 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
MyProjectAreafor the project area name and
Team 1 Streamfor the stream name.
- Give your repository workspace a name, such as
- Click Finish.
- Select Find and load Eclipse projects as shown in Figure 5, and click Finish
Figure 5. Load the repository workspace
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.
- Create fragments for packages in the use case model by right-clicking on the model and selecting Refactor > Fragment All Sub-Packages.
- Click the OK button to update references.
- 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.
Clientto replace Customer in the dialog, and click OK.
- 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.
- Select the Standard template, and click the Next button.
- 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
- 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.
- Right-click the model and select Team > Add to Ignore List.
- Leave these default selections:
- What to Ignore: Resources with selected name
- Where to Ignore: Only ignore items in the same directory
- Click OK in the dialog window shown in Figure 7.
Figure 7. Adding a UML model to the What to Ignore list
- Add a UML actor to the created model by right-clicking on the model and selecting Add UML > Actor. Name it
- Open the Actors Overview diagram from Use Case Model > Overviews.
- Drag the ATM actor to the diagram.
- Save all models by clicking File > Save All.
- In the Pending Changes view, expand your repository workspace component, as Figure 8 shows.
Figure 8. Pending changes view
- Right-click the Unresolved folder and select Check in and Deliver.
- Enter relevant comments under "Change set comment," and then click Finish, as Figure 9 shows.
Figure 9. Check-in and Deliver dialog window
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.
- In User1's Rational Software Architect window, open the Pending Changes view, and click the Refresh button.
- Expand your workspace/component. Accept All incoming changes by clicking on the A icon with the arrow in the Pending Changes view.
- 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.
- Click the Ignore button.
- Validate the Use Case Model by selecting the model in the Project Explorer and clicking Modeling > Run Validation on the main menu bar.
- In the Problems view, select the error resulted from validation. Right-click and select Create work-item.
Figure 10. Creating a work item
- 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.
- Fill out the mandatory fields in the Work Item editor.
- Choose the owner of this work item to be User2. Click the Owned By field and select More.
- Search for User2, and click OK to set the user as the work item owner.
- 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.
- 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.
- In the work items view, shown in Figure 11, double-click the work item to open it.
Figure 11. Rational Team Concert query result
- 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.
- 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.
- 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
- Resolve the defect by changing its status and state to Resolve and Fixed, respectively.
- Save the work item.
- Now, make changes to the PiggyBank Design Model. Expand PiggyBank Design Model > PiggyBankImplementationDesigns in the Project Explorer view.
- Rename PiggyBankImplementationDesignPackages to PiggyBankUser2Design by right-clicking on the diagram and selecting Refactor > Rename from the drop-down menu.
Delivering the changes
- Now you are ready to deliver the changes. Open the Pending Changes view. Check in and deliver the unresolved changes.
- Assign the defect assigned to User2 to the change set created in earlier. When prompted to provide comments for the change set, click Next.
- 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
- Click the Finish button.
Now we will make changes that will create conflicts in the UML model.
- Start Rational Software Architect with User1's workspace.
- Repeat Steps 6 and 7 but rename the diagram to
PiggyBank User1 Designthis time. This will create conflicts with changes made by User1 that should be merged manually.
- Save the model.
- 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
- Accept all incoming changes by clicking Accept all in the Pending Changes view.
- Click the Auto-Resolve button.
- Click OK on the dialog where it states that none of the conflicts can be automatically resolved.
- Manual merge of the models is required now to resolve the conflicts. Double-click the Design model.emx (Modified > Modified).
- Figure 15 shows the Compare and Merge editor. Accept changes from User1. User2's changes will be overwritten.
- Expand all of the conflicts. Right-click the appropriate conflict and select Accept.
- Click the Resolve as Merged button.
- 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.
- 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
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.
- Select Window > Preferences from the main menu bar.
- Select Team > Jazz Source Control > Model Enablement.
Figure 16. Jazz source control model enablement preferences
- Select these check boxes:
- Allow modeling tools (for example, UML) to participate in file content during Accept,
- Logical Models
- Click Apply and then OK.
- 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.
- 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.
- Give it a new name of
Deposit Check, and click OK
- Deliver the unresolved changes to the stream. Repeat steps 16–18 from the Delivering nonconflicting changes section to complete this.
- As User2, repeat the preceding steps, from "Check Allow…" through "selecting Refactor > Rename," but name the use case
Cash Cheque). This will create a conflict in the logical model.
- Open the Pending Changes view, and check in all unresolved changes that you created in the previous step.
- Accept all incoming changes from User2.
- Click Auto-Resolve conflicting changes.
- 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
- Accept the changes that User1 created by right-clicking and selecting Conflicts > Conflicting Modifications > Accept in the drop-down menus.
- 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.
- Learn more about:
- Find out about IBM Rational Team Concert features and benefits:
- Rational Team Concert Information Center
- IBM developerWorks page for Rational Team Concert, with links to many other resources
- Webcast: Using Rational Team Concert in a globally distributed team
- Demo: Dashboards and reports
- Podcast: IBM Rational Team Concert and Jazz
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management. You can find product manuals, installation guides, and other documentation in the IBM Rational Online Documentation Center.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
Get products and technologies
- Get the Rational Software Architect for WebSphere Software trial download
- Rational Software Architect Standard Edition trial download
- Rational Team Concert trial downloads (free):
- Download trial versions of IBM Rational software.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
- Join the discussion in the Rational Development Tools forum.
- Join the discussion in Jazz.net forums.
- Check out developerWorks blogs and get involved in the developerWorks community.