Evolving architectures and designs in parallel – A workflow for enabling parallel development using Rational Software Architect and Design Management
Rational Software Architect’s Design Management capability (RSADM) is a Jazz, server based application that centralizes and manages all kinds of design artifacts related to the software development lifecycle process. RSADM exposes these artifacts as linked data resources that can be collaborated on by web and desktop clients and manipulated by desktop clients.
The first release of RSADM (3.0) only permitted, what is called now, externally managed projects. A RSADM externally managed project is one where the authoritative owner of the resources and their life cycle is outside of RSADM. Typically this meant a Source Control Management System (SCM) such as Rational Team Concert (RTC) or Rational ClearCase working in cooperation with a desktop tool like Rational Software Architect. In this mode RSADM was only responsible for publishing the design artifacts as resources, enabling them to be viewed in a web browser, commented on and linked to other resources like requirements and work items.
The current release of RSADM (4.0), while not dropping the previous mode, has added significant capabilities for owning and managing the full life cycle of design resources. In this new mode of operation RSADM is the authoritative owner of the design resource, a file-based SCM system is no longer necessary. RSADM performs all the change control and configuration management capabilities including versioning, branching and merging at the model level.
In this article we will explain the parallel evolution of architectural design resources in RSADM using a scenario based example. We will also introduce the basic concepts of configuration and versioning enabled by RSADM 4.0. Although this article uses RSA the same Design Management capabilities are available with Rational Rhapsody as well.
Configurations
A configuration is a unique set of versions of design resources. There are two types of configurations: snapshot and workspace. A snapshot configuration is a read only version of a collection of design resources. This frozen set of versions can be relied on to act as a reference-able baseline for other configurations. While these resources are read only, they can still be commented on as comments are not considered part of a resource’s properties.
A workspace configuration is an editable set of resources. In a workspace resources can change over time (including deletion). Changes in a workspace are not visible outside of that workspace. A workspace is an area where one or more designers can make modifications to resources without disturbing other non-related work on those same resources. Snapshots are required as the base from which to create workspace configurations. To create a child workspace you must first create a snapshot in the parent workspace. Then create the new workspace as a child workspace to the one the snapshot was created in. The snapshot contains the initial versions of all the resources for the new workspace.
Workspaces use resource locking to prevent contention. As users edit resources on a workspace, resources are automatically (or manually) locked to allow multiple users to share a workspace without requiring merging. Changes to a resource are collected in a changeset. A changeset can, optionally, be referenced and associated with a change request. When a resource, in a specific workspace, is edited the changes are only visible to the user that is editing them in that changeset. Before another user can see the changes in the workspace, the changeset must be ‘shared’ with the workspace. Sharing a changeset to a workspace commits the changes to the workspace. No other modifications of the resources are permitted in the context of the changeset. They can of course be modified again, but that must be done in a new changeset, and shared again with the workspace.
There are two modes in which the changes get committed to the workspace. The first one is a ‘share on save’ mode. In this mode changes made to the resource get committed to the workspace when the user saves the resource. The other mode is explicitly using change sets which allow the user to combine multiple edits into a change set and then explicitly commit the changes to the workspace
A changeset can be ‘completed’. Completing a changeset freezes the changeset. The resource deltas cannot be altered. Explicitly completing a changeset is often done when you want to review the changes with others to get their opinion on them. The changes are made read only so that a reviewer of the changes can be assured that the changes won’t be modified again after the review has been completed. A completed changeset can be shared back into a workspace.
Changesets can be explicitly created and even named. Making changes directly to a resource in the context of workspace with the web UI, however will create an implicit changeset and automatically share it with the workspace. So if you want to accumulate multiple changes to multiple resources in the same changeset, possibly for a review, while in the web UI you must explicitly create a changeset and change your default configuration to that changeset.
A RSADM resource is identified with a single URI. This URI, not including any query part, is a unique identifier for all versions of a resource. This resource may have different properties depending on the configuration you view it in. We identify a specific version of a resource with its URI and a query part that references the configuration, which is either a snapshot or workspace.
https://example.com:9443/dm/models/123?rmps.context=https://example.com:9443/dm/streams/8
After the work is done in a workspace, it is often desired to merge the changes into a common, team or integration workspace. This common workspace must be an ancestor workspace (parent, or parent’s parent, etc.). All or a subset of the changes to resources are copied into the ancestor workspace. Rational Software Architect provides a visual merge editor to help select which changes are to be copied.
A Parallel Development Scenario
The following example demonstrates how two different designers (or design teams) can asynchronously edit model resources and when finished merge those changes together into a common configuration. To keep this scenario focused on RSADM’s new capabilities and to keep it as simple as possible; we do not have the other applications (RTC/RRC/RQM) in the Rational solution for Collaborative Lifecycle Management (CLM) participating, however they would compliment this scenario very well.
In this scenario manager Deb, and designers Al and Bob collaborate to make changes to a design. The overall scenario is as follows:
- Create snapshot and workspace configurations
- Deb creates workspaces in the JKE Sample project for Al and Bob to separately work in. In each workspace she adds comments to some of the resources with suggestions for changes. She also creates work items for each to track the effort.
- Make changes in Account Management Workspace
- Al, in his RSA desktop, connects to the Account Management workspace, views the new work item and comments and makes changes to the model. Al completes his changeset, and requests a review by Deb before sharing them to his workspace.
- Make changes in Logging Workspace
- Bob, also in his RSA desktop, goes to the Logging workspace, views his work item and comments. He creates and names his changeset and shares it to his workspace.
- Share Logging Workspace into Parent
- Bob shares his changes from the Account Management workspace to the main team stream. This invokes the RSA merge editor.
- Merge Account Management Changes into Parent
- Al shares the changes he made in the Logging workspace to the main team workspace, merging them into the updated configuration that already has Bob’s changes.
In this scenario Bob and Al will be the only ones working out of the Account Management and Logging workspaces respectively. However RSADM workspaces are not limited to an individual and instead there could be sub-teams working together on the changes in the child workspaces
Create snapshot and workspace configurations
We begin the scenario with the user Deb, creating a snapshot in the main configuration of the RSADM example project: JKE Banking Sample Project. The configurations menu in the upper right corner of the DM web UI provides options for setting, searching and switching configurations.
This puts Deb in the Configuration Management application. From here Deb selects the create snapshot action in the configuration explorer. The configuration explorer includes all projects managed by the server. Configurations are not bound to a single project. A configuration can be shared by many projects.
The new snapshot is named, and a description is added.
With a snapshot created it is now possible for Deb to create the workspaces that her team will use to modify the models independently. The configuration explorer provides actions to create workspaces directly off of a snapshot.
Workspaces are named and can have an optional description.
Two workspaces are created and named, ‘Account Management Workspace’ and ‘Logging Workspace’.
With the workspaces created, Deb can now goes back to the Design Management application using the link at the top of the page and switches to one of the new workspaces to start adding comments to resources in it. When a comment is made to a resource, the comment is only visible in that configuration. Deb uses the configuration menu to select the Account Management Workspace as the default configuration.
With the configuration selected, its name appears as the label for the configuration menu.
Deb navigates to the Login Unsuccessful sequence diagram, and adds a comment describing the work she wants done.
She does something similar to the JKE Overview diagram in the Logging Workspace configuration.
Make changes in Account Management Workspace
Al, a designer on the team, configures his RSA desktop application to connect to the RSADM repository, and specifically to the Account Management Workspace.
While in this configuration, Al sees the comments Deb made on the sequence diagram.
Al can explicitly lock the diagram resource with the popup menu in the Design Explorer view.
When a resource is locked it is done so in the context of a changeset, which gets implicitly created, and is displayed in the Design Changes view. By default the name of the changeset is date and time. The name of an active changeset can be changed at any time.
One of RSA DM Client preferences is to automatically share changes that are saved. To help explain the individual steps of what is happening in this scenario, Al has turned that option off. If it was on, every time Al saved a change by pressing the Save button on a diagram or resource the changes would be saved to the changeset, and the changeset would be ‘shared’ with the workspace. With this option off, only the changeset is updated. Others working in the workspace would not see the updates.
Al makes many changes to the diagram. These include adding a new operation to a component. RSADM will automatically lock all resources in the configuration that are being changed.
Saving the diagram adds the changes to the changeset. Al changes the name of the changeset to ‘Account Lockout’
Al decides to have Deb review these changes before sharing then to the workspace. From the context menu in RSA, Al creates a review. This action pops up a web browser, which Al must log in through, and the new review is displayed.
The resources changed in the changeset are automatically added to the review. Al adds a description for the review, and selects Deb as a reviewer before saving the review and then starting it
Make changes in Logging Workspace
Meanwhile at the same time as Al is doing his work, Bob also uses RSA in the other configuration to view the comments Deb made in the overview diagram.
Bob makes changes to the diagram as requested, and saves them to the changeset.
Share Logging Workspace into Parent
Bob decides not to have the changes review and just shares them to the workspace.
These changes are now visible to anyone viewing resources in the Logging Workspace configuration. The next step is to share the workspace with the main parent workspace. Using the context menu on the workspace, Bob select the Share with parent workspace.
This action causes the merge editor to display showing the differences between the main configuration and the workspace. The changes are minimal, and Bob accepts all the changes and shares them with the main configuration.
Once the changes have been reviewed and accepted, Bob is prompted to commit the merge. Now anyone looking at the resources in the JKE Banking Sample Project configuration will see these changes as well.
Merge Account Management Changes into Parent
Meanwhile Deb reviewed Al’s changes and gave permission to share them with the main configuration. This time when the merge editor is displayed differences in both configurations are displayed (left changes and right changes). A three way merge is available for Al.
For simplicity Al, accepts all changes and merges all his work into the main configuration. Now all work done by Al in the Account Management Workspace, and all work done by Bob in the Logging Workspace are merged together in the main configuration for everyone to observe.
Summary and Next Steps
Rational Software Architect Design Manager has full support for parallel development of RSA models (Sketches, UML and related profiles, BPMN and Topologies). Teams can work asynchronously in isolated workspaces thereby minimizing the impact on each other. The changes can be managed and carefully merged into a main or integration configuration. Changes can be reviewed before they are made visible to the rest of the team.
RSADM 4.0 new parallel development capabilities make it possible to speed up development of designs by allowing asynchronous development and collaboration. These capabilities support very simple ‘share on save’ type collaboration, allow grouping in change sets and also provide isolation with workspaces allowing simple to complex change management.
The Design Management project on jazz.net offers a 60 day trial so you can download and try it out. The trial includes design artifacts for a sample application call Money That Matters that makes it easy to try out the features covered in this article. Additionally the library section on jazz.net contains articles, videos and other resources you may find helpful in learning more.
Copyright © 2012 IBM Corporation