This is the third installment of a multiple-part article (as outlined below) that demonstrates using Rational's tools in a distributed, J2EE-based project.

• Part 1: project introduction; high-level planning
• Part 2: detailed planning; risk management; requirements management
• Part 3: Rational Rose model creation and access control; requirements analysis
• Part 4: use-case refinement; report generation; tool and technology selection
• Part 5: architecture and design
• Part 6: detailed design; early development; round-trip engineering; early unit tests
• Part 7: continued development; early builds; demonstrations
• Part 8: strategies for unit testing; function tests; GUI test scripts
• Part 9: system builds and testing; defect tracking; product acceptance
• Part 10: project results; conclusions; future work

The fictional premise of the article is that we're a software company, Lookoff Technologies Incorporated, and our customer, Audiophile Speaker Design, Inc. (ASDI), has hired us to meet their burgeoning IT requirements. For a more detailed introduction to the project, see Part 1.

This Part 3 installment addresses our early efforts with modeling in Rational Rose. First we modeled the existing ("as is") system at ASDI, through business use cases and business objects showing how things were currently working. We moved from there to creating a system model that addressed ASDI's requirements for their new ("to be") system and would be used as a basis for building the software.

Accompanying this article are two presentations (from Rational User Conference 2000) that touch on subjects discussed here: "Maintaining an Analysis Model in Synch with Multiple Design Models" by Yves Holvoet, and "Structuring Your Rational Rose Model" by Robert Bretall. The latter presentation is accompanied by a Rose model.

Capturing the "As Is" System

Too many new and improved IT systems are started before the existing system is understood. Even when the existing system is devoid of any IT components, there needs to be an analysis of how things are currently done before alternatives and improvements are suggested. Although it's tempting to skip or rush this step, doing so can lead to problems like these:

• incomplete understanding of customer needs, slowing down future analysis
• incorrect interpretation of requirements
• inability to gauge the impact of the new solution, leading to adoption shock when the software is delivered to the customer and requiring a complete rework of current operating procedures
• inconsistent terms and concepts, resulting in miscommunication or confusion in interactions with the customer

Creating a business model to capture the "as is" system can be a fairly quick task and can yield useful analysis clues that will simplify definition of the "to be" system. One thing that helped us in creating this model was the statement of work (SOW). Although the SOW primarily described requirements of the "to be" system, it also provided useful background information on ASDI's current business processes.

In the Rational Unified Process (RUP), there are a number of ways that business modeling can be done as part of the RUP inception phase (and therefore in our project's Phase 1). Working with ASDI to create an IT system, we needed an "as is" model that captured the paper flow and interactions of their current system. We created the following RUP artifacts in Rational Rose as part of this modeling effort:

• a business use-case model, modeling the functions of the "as is" business.
• a business object model (sometimes called a domain model), modeling the objects that perform the business functions and the interactions between these objects. A business object model might show how an invoice is generated and routed through the system, or the path a purchase request takes from start to finish.

Note that on some previous projects, we'd skipped the business modeling step because we were building an entirely new system, or because we knew the existing business model extremely well. But since we were new to ASDI's business, we felt this step was important.

We also considered developing a business glossary (using the RUP template for that artifact), but we found that most of our terminology was fairly standard and unambiguous and was adequately captured in our business object model. More complex or rigorous projects would benefit from creating a business glossary to ensure consistency across all artifacts.

When we did our modeling in Rational Rose, we felt that simply creating diagrams wasn't enough. In the past we'd found that the meaning of such diagrams, while immediately obvious to the diagram creator, was rarely obvious to the reader. Consequently, we accompanied each diagram with documentation (by clicking on the diagram and then typing text into a documentation window). We also accompanied each item in the diagram -- use case, business object, user, or whatever -- with a line or two of text describing that item's purpose.

Creating the Model

As a starting point for our new model file (ASDI.mdl), we used the Rose template that follows the structure defined by the RUP (see Figure 1). Because we were largely working within the RUP framework, this worked well for us. The RUP model template is one of several that are accessible through the wizard you see when you start up Rose, or you can find it in the Frameworks directory within the Rose program folder.

Figure 1: RUP model template

We made changes to the template structure to suit our needs and preferences. For example, we immediately made the following modifications:

• Instead of tracking included use cases separately from the other use cases, we grouped them in whichever package logically included their function. We felt that the <<include>> stereotype combined with the reporting capabilities of Rational SoDA would allow us to easily identify included use cases as necessary.
• We removed Analysis Model under Logical View. You can read about the pros and cons of analysis framework reuse and analysis/design use cases in Yves Holvoet's presentation. We didn't feel that such a layered analysis model was necessary, because we didn't expect to reuse much of the business model of the ASDI system in future projects. Instead we'd allow the use cases to evolve throughout the project.
• We partitioned the design model by business component first and then by layer (often not the same thing), rather than by layer first.

Later we had to add a schema area to the model to track data modeling efforts by the database architect.

Managing the Model

Divvying up the Rose model into packages that map to different team members' responsibilities always requires effort. The package structure should make it relatively easy to share responsibilities among team members by isolating different parts of the system: analysis (through use cases and business objects, for example), architecture, and design.

Our team wasn't very large, but we still had to think about collaborating on the model. We had a few floating licenses for Rational Rose that would allow all of us to have access to the model, but we also needed to enable concurrent access to certain portions of the model. Consequently, we used Rose's "unit control" feature to break up the model as appropriate.

The roles in our team structure (as described in Part 2) that would have input or update responsibilities for parts of the model are as shown in Table 1. Furthermore, other members of the team, such as the junior developer and the project engineer, would need read-only access to the model to stay abreast of developments.

We broke the model up as shown in the Rose diagram in Figure 2. This model structure would serve our needs at the time, since only three people would be directly manipulating the model. In the future, as the team and project grew, this structure could easily decompose into more *.cat files.

Figure 2: Breaking up the model

Additional information on divvying up a Rose model can be found in Robert Bretall's presentation. Here are a few key points worth noting from his discussion of model structure:

• It's best not to place contents at the top level of the model. (In our case, all information went into controlled *.cat files.)
• Consider having layers of analysis if you plan to reuse aspects of your system model in future projects. (You'll also find more on this subject in Yves Holvoet's presentation.)
• Rational's tools (SoDA, REI scripts, and so on) more effectively interact with a model if it's structured according to RUP guidelines.

Breaking up the model into separate *.cat files was easy with Rational Rose. As shown in Figure 3, we simply right-clicked the package we wanted to control in a separate file; then, in the context menu that appeared, we chose Units > Control Use-Case Model, enabling us to control that package and all its children. Later on in the project, we reorganized some *.cat files into several smaller controlled packages to further distribute the modeling effort.

Figure 3: Creating separate *.cat files in Rose

Modeling Users and Interfaces

An actor is someone or something outside the system that interacts with it; this can be either a person using the system or some other type of interface. Modeling a system's users and interfaces and their dependencies can be tremendously useful; not only does it give you a complete view of the system, but it can also provide you with good information for future security and role modeling efforts.

Figure 4 shows how we worked actors into our business model in Rose -- specifically, in a use-case diagram associated with customer service that's an excerpt from our business use-case model. Two special stereotyped classes were used: business actors and business use cases. Rose can assign custom icons based on the stereotype, and we chose this approach to give the icons for the use cases and actors a subtly different appearance -- that is, with a slash added -- because we felt it was important to differentiate the business model from the system model that would be used to build the software.

Figure 4: Business use-case model excerpt for customer service

(click here to enlarge)

As we fleshed out the business use-case model, a number of objects emerged that were good candidates for the business object model. Although creating a business model of the "as is" system may seem to take a lot of effort (mainly, generating diagrams), we felt it was worth it. In the past our "as is" model would have consisted of a large number of notes in lab books and informal technical notes. Investing a fraction more effort into capturing this information in Rose made for a much clearer and complete picture of the existing business processes.

Understanding System Interactions

Sometimes it's tempting to focus on the individual pieces of the system, when really the interactions between the pieces are just as important. Fully thinking through the interactions makes the commonalities between the pieces and the possibilities for integrating them more obvious. This is one reason why we later used collaboration diagrams (which show these interactions) to validate our design; this was critical to identifying the flaws and gaps inherent in our analysis and design.

The interactions we focused on in this early stage of our project were:

• actors to business use cases (what individuals and interfaces had access to the various business tasks we'd identified)
• business object to business object (how the various business objects interacted with each other, and what sorts of information they shared)
• use case to use case (what tasks depended on each other, and what common tasks were shared by a number of procedures)

We spent some time in Rose capturing our understanding of the current business organization and processes, resulting in a business object model that was very useful in understanding the existing system. The diagrams in the object model (one of which is shown in Figure 5) were similar to standard class diagrams, except they made use of special stereotyped classes: business entities, business controls, and business actors. Business entities represent passive domain objects such as invoices or reports, and business controls are objects that perform functions, perhaps representing alarms or machinery. (Business actors were discussed earlier.)

Figure 5: Business object model excerpt

We started the business object model soon after the business use-case modeling effort. The text of the business use cases identified a number of suitable business objects. Things that were mentioned across multiple use cases, such as "purchase requests" and the "product," "product queue," and "shipping queue," were identified as key objects in the business domain. Sometimes we'd remove a business object if we realized it was inappropriate or already covered by another object. In this way, we quickly honed in on the tasks (use cases) and things (business objects) relevant to ASDI's business.

In some cases, the business object model evolved into system classes. This was especially true for entity objects, which often mapped to container classes or database tables. In other cases, the business object model simply served as a consistent point of reference for understanding the customer's domain. We made sure the customer fully understood the diagramming notation and the contents of each diagram, since their review and approval was critical.

All in all, we tried not to spend too much time working on the business object model. It didn't have to be elegant or complete, but only to give us adequate insight into the current business processes. We rarely referred to the business model after the first month or two of the project, but we felt it was time well spent, since it was a necessary step in moving toward a system model for the "to be" system. As new members joined the team, we'd walk them through the business model to help them understand the new domain; however, once familiar with it, they rarely revisited it except to clarify terminology from time to time.

Back to top

Moving from the SOW to Use Cases

Looking ahead to the "to be" system, we needed to move from the SOW requirements we'd compiled in text form (as discussed in Part 2) to carefully thought-out use cases. In other words, with the creation of business use cases for the "as is" system behind us (as described earlier), we were ready to come up with detailed use cases for the "to be" system. This wouldn't be a quick step, but one that would take place over a couple of weeks. (In RUP terms, this move reflected a gradual transition from the inception phase to the elaboration phase.) The work we'd done on business modeling, gaining experience with the current system and grouping its functions into business use cases, would help quite a bit. (The RUP documentation shows the evolution from business use-case model to business object model and system use-case model; we found this to be quite accurate and helpful.)

The reason we hadn't bothered to map the SOW requirements to the business use cases for the "as is" system is that many of the SOW requirements didn't exist in the current system. The business model we created earlier was merely a temporary artifact serving to ensure that we, as a team, understood ASDI's current system.

Use Cases Versus Text Specifications

A number of books and articles (including those listed later under "References and Other Resources") explain the benefits of use cases for modeling and understanding requirements. We've found many of the promised benefits to be true, although defining the contents of a use case is not a trivial task. If use cases are poorly designed, they'll certainly be of less use to you than well-written textual specifications.

Here are some of the mistakes we made when we started out with use cases:

• creating use cases that were too big or too small
• not being consistent in use cases across the team
• poorly planning the packages into which to group use cases
• controlling access to the model inappropriately, such that analysts were clashing in their attempts to collaborate
• putting too much detail into use cases, trying to define everything before entering into prototype, design, and development tasks
• putting too little detail into use cases, leaving requirements open to too much interpretation by the engineering team

As a result, we decided that use-case modeling standards and guidelines needed to be defined by the team lead. These included the following guidelines:

• Use cases would typically capture 10 to 20 days of development and unit test. This isn't a RUP rule, but it served as a good rule of thumb for us. If we found use cases much larger or smaller than this, we'd spend extra time looking at them to make sure they had the right scope.
• The engineering team had to agree on the package structure early on. This structure could change, but changes would have to be discussed with the team first.

When deciding what to include in our use cases, we followed the guidelines outlined in the article "Fine Tuning Rose to Complement Your Process":

• identification -- name, unique ID, stereotype, traceable requirement, and overview
• description -- start state, end state, description of main flow, and variations
• notes -- temporary "scratchpad" notes

Evolving from "As Is" to "To Be"

As we moved from "as is" to "to be," many of our business actors evolved into true users and interfaces within the system, although significant restructuring was required. This was natural, since the new IT solution consolidated some of the old roles while redefining others. Some business entities disappeared as abstract concepts, while others mapped to classes via the schema or detailed design.

The diagrams in Figures 6 through 9 show our early efforts on a portion of the use-case model for the "to be" system. It would mature over time, with the help of screen mockups, collaboration and sequence diagrams, and further analysis details.

Figure 6: Early actor model

Figure 7: Core customer service use cases

Figure 8: Customer ordering use cases

Figure 9: System management use cases

As the RUP states, "the most important purpose of a use-case model is to communicate the system's behavior to the customer or end user." However, at the risk of adding complications that our customer might not feel comfortable with, we often found it valuable to introduce the more advanced relationships of inclusion and extension into our uses cases as we fleshed them out. Included and extended use cases frequently emerged during detailed review of our use-case model. We found that even after we understood the external interface's view of the system (including users), grouping functionality within use cases through inclusion and extension yielded significant planning, architectural, and testing benefits. However, after seeing that the customer was less confident about reviewing these advanced relationships, we sometimes kept noncritical included and extended use cases out of the review packages.

Back to top

Summary

We now had a clear picture of the existing processes and entities at work in ASDI's business, and a good start on a system model for the tasks and roles of the system we'd be building for them. Although there had been some discussion among the team about skipping the business modeling effort, we felt that the effort had paid off. Among other things, it eased the customer into use-case modeling at a comfortable and relatively nontechnical level.

Use-case modeling varies significantly from project to project; the definition of a use case, use-case relationships, level of detail, and so on, are all subject to debate. In the end, we found consistency and frequent reviews to be key to success when presenting our use-case model to the customer.

Looking Ahead

We needed to get the technical thrust moving. The customer was pushing us for more information about the user interface, code prototypes, and tool selection than we were ready to provide at this time. We had just gotten to the point of having screen mockups and were beginning to think about appropriate technologies; now it was important to start working with more tangible, technical artifacts and getting buy-in on tools (especially if we were going to need more training).

Although we hadn't yet delved into the architecture, we knew the system had to be Web-based and cross-platform and had to scale up from a prototype to an enterprise-level solution. We were already leaning toward J2EE, and ASDI's recently hired IT manager strongly preferred it as well. Consequently, we felt it would be wise to start exploring the costs and capabilities of J2EE. Our team wouldn't require significant training in this area, which was another plus. The data store would require more thought, however, because the IT manager was pushing very hard for an object-oriented database (OODB) solution. Since we were a hard-core RDBMS shop, this would be a stretch for us, but we did agree to look into OODB solutions as well.

We'd been informally walking our customer through the artifacts, but it was time for a formal review. In the next few weeks we'd set up our Rational SoDA templates so that we could provide our first formal deliverable: the detailed software requirements. We agreed that this document would consist of both use cases and nonfunctional requirements (reliability, usability, and so on).

Our use cases were starting to stabilize, to the point where traceability to the SOW would be appropriate. We needed to use Rational RequisitePro to ensure that we were maintaining the map between the SOW and our use cases.

Our direction for the immediate future, then, would be as follows:

• making progress on the technical front, especially tool and technology selection
• setting up Rational SoDA as necessary to generate our first formal document
• refining our use cases to add traceability to the SOW

Major Risks

We still felt that the schedule was very tight and there was little contingency in the schedule or budget -- and our risk list was growing, even though we hadn't started any serious technical exploration yet. Among the new risks that emerged were these:

• Too many stakeholders had competing and sometimes contradictory input on the functionality of the system. We needed to clarify the decision process with the customer.
• If we chose an OODB solution, we'd be a bit out of our depth, so it would force training and uncertainty into the engineering team's schedule.
• The customer was pushing significant formality and detail into this first phase, when we were only supposed to be working on a proof of concept. We were still in the process of communicating the RUP to the customer and trying to increase their comfort in many of the artifacts and notations used in the RUP.

Back to top

References and Other Resources

• UML Distilled, Second Edition: A Brief Guide to the Standard Object Modeling Language by Martin Fowler with Kendall Scott (Addison-Wesley, 1999)
• The Unified Modeling Language User Guide by Grady Booch, James Rumbaugh, and Ivar Jacobson (Addison-Wesley, 1998)
• The Rational Unified Process: An Introduction, Second Edition by Philippe Kruchten (Addison-Wesley, 2000)
• Rational User Conference 2000 presentations downloadable from this article:
• "Maintaining an Analysis Model in Synch with Multiple Design Models" by Yves Holvoet
• "Structuring Your Rational Rose Model" by Robert Bretall

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Capturing the "As Is" System
• Moving from the SOW to Use Cases
• Summary
• References and Other Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers