UML Model Organization with Packages and the Package Diagram

May 21, 2013

It is no coincidence that the package element in UML is represented by a folder icon, similar to directories in a file system Graphical User Interface (GUI).  Packages are used to organize the elements of a model just as folders are used to organize files.  The contents of a package are any kind of element that is part of a model, including other packages.  Beyond that description there’s not much more information on how to use packages in the UML specification.  Since they are a general grouping thing, it is up to usage scenarios to suggest what the best practices are for using packages.  There are some practices that apply in most situations, and more that depend upon the modeling methodology or the purpose of the model.

First and foremost, use packages to organize your model, regardless of the model purpose.  Even the most trivial model quickly becomes unmanageable without some kind of organization.  There is no single correct way to organize a model.  A modeler may choose to organize around process or product or some combination of the two.   Second, use the package diagram to provide visualizations of that organization.   The model browser view below illustrates how even a simple model can begin to be confusing with no organization of the model elements.

A model with no organizing principle appliedno_org
The same model with an organizing principle appliedorg

In addition to being able to gather like items together to allow modelers to focus their attention on relevant elements and make those elements easier to find in the browser, packages provide a namespace for the elements they contain.  Namespaces allow modelers to create unambiguous named references to each of the elements in a model.  This is useful in situations such as when a modeler is evolving a system and creating an as-is and a to-be system model.   It is natural to have elements named the same in each model.  In order to disambiguate elements with the same name, they can be placed in different packages so that the fully-qualified names are different.

Packages can be placed on a UML package diagram.  The modeler might choose to do this to present a high-level view of a model or to show relationships among the packages of elements.  Three different package diagrams representing the model organization shown above are presented here.  Each of these diagrams uses the optional diagram frame, showing the diagram type (pkg) and diagram name (Use Case View).  Note that although  the diagram and the package have the same name (Use Case View) this is not required.  In the first diagram, the two high-level packages are shown.  As with many other modeling situations, only the details we need are presented, and the details of the package contents are elided.

pkg1

In the second diagram, the packages contained in the Actors package are shown.  The labels on the Human and Non-Human package describe the namespace of the containing package.  The containment relationship also serves to describe the namespace.  In this example, the fully qualified name of the Actor Operator is Use Case View::Actors::Human::Operator.

pkg2

In the third diagram, the contents of the packages are shown embedded in the package elements.  This representation is the third presentation option found in the UML specification.

pkg3

Your package diagrams will in all likelihood be some combination of each of these styles, as will your choice of organizing principles.  Choose the one that is appropriate for its intended use.

If you want to print this article there is a PDF attachment on the Sparx Community site –

Model Organization with Packages


Adapting SW Requirements Visualization to MBSE

October 25, 2011

I recently finished a nine-month assignment as a Product Manager working with Seilevel to define business requirements for several software projects.  Seilevel has an interesting approach to requirements visualization that they call the Requirements Modeling Language (RML®).  As I worked with their methodology I started to consider how the role of Product Manager or Business Analyst differed from the role of Requirements Engineer in the systems engineering world.  My initial conclusion is that they are very similar.  So similar in fact that I have begun to explore a mapping between the RML® diagrams and Unified Modeling Language (UML)/Systems Modeling Language (SysML) diagrams.  I will be presenting a tutorial on this topic at the INCOSE San Diego Chapter Mini-Conference on Nov. 18.  Here are some of my initial observations:

Advantages of RML®

  • The approach is inherently agile.  There are many types of diagrams but the descriptions include suggestions for when the requirements modeler should use each of the different diagram types and when they should not.
  • Requirements Visualization helps to eliminate ambiguity.  A picture is worth a thousand words, especially when the requirements modeler augments the picture with a few words of explanation.
  • RML® is not constrained to a requirements modeling language or tool, so it is very flexible.

Disadvantages of RML® in Model Based Systems Engineering (MBSE)

  • It is not constrained to a modeling language or tool, so the reader may misunderstand the semantics of the visualization.
  • Requirements Traceability is a separate model that can not take advantage of modeling tool capabilities.

Every system architecture or development methodology that I am familiar with (e.g. VAP, OOSEM, INCONIX) all have requirements as an initial input.  One of the often stated advantages of SysML was the ability to use models for developing those requirements, but most of the tutorial material seems to emphasize the interface between the modeling tools and the requirements management tools.  RML® seems to offer a proven methodology for using models to fulfill the vision of those developing SysML.  Future posts will include my thoughts as I work through how to adapt it to MBSE.



Requirements Metadata Attributes – part 2

September 8, 2010

To recap from part one, the essential attributes (aka metadata) to be associated with a requirement include Requirement ID, Source ID, Requirement Text, Date, Effectivity and Verification Method.

Beyond these essential attributes there are some that I have found to be very desirable, at least in some situations.  These highly desirable attributes include:

  • Requirement Short Text – An abbreviated text of the requirement can be useful when tracing the requirement, either within the requirement set, or into the design and implementation.
  • Type – A code identifying the type of requirement.  A common type set is that identified by the acronym FURPS+.
    • Functional – includes things like feature set, capabilities and security
    • Usability – includes things like human factors, aesthetics, consistency and documentation
    • Reliability – includes things like mean time to failure, recoverability from failure, predictability, accuracy and availability
    • Performance – includes things like speed, efficiency, through-put, response time
    • Supportability – includes things like testability, extensibility, adaptability, maintainability, configurability, installability and localizability
    • The plus includes constraints, physical, interface, and implementation requirements
  • Risk – this attribute allows you to identify the relative risk level of each requirement.  Requirements identified as high-risk should be evaluated for inclusion in the technical performance measures.
  • Verification Level – The level at which the requirement will be verified.  Some requirements may be evaluated at the component or sub-system level in order to reduce the amount of time and effort in full system evaluation.

There are an additional set of attributes or metadata that might be employed to support metrics collection and analysis.

  • Funded – An indication that the requirement was a funded change.  It may also be advisable to track the reason for an unfunded change.
  • Deleted – Requirements that are deleted are one indication of volatility.  While some volatility is expected and may mean increased understanding of the problem, too much volatility may indicate the project is in trouble.
  • Modified – a Boolean value that is another indication of volatility.
  • Verification Issue – a general category used to track verification problems and concerns.

All of these requirements metadata elements may not apply to your particular system development situation.  On the other hand, each of them should be considered for inclusion as you work through the requirements development process.  Part three of this series will conclude with some occasionally useful attributes that you may wish to consider.



Change Case Analysis

August 21, 2009

A while back, another architect mentioned the topic of change cases to me when we were discussing ways to evaluate software architectures.  That was the first time I had ever heard the term, and I assumed it was a new technique.  I filed it away as a topic to research later.  Recently I was asked to provide some training on the topic of architecture evaluation and I decided to do that postponed research.

The two years I spent as a Guide at About.com taught me a lot about internet searches, so I was surprised when I was unable to turn up much in the way of relevant material (if you need to change text from upper to lower case or vice versa, I can tell you where to look).  The only truly relevant information was on Scott Ambler’s Agile Modeling site – http://www.agilemodeling.com/artifacts/changeCase.htm.  The most significant thing there was a link to the book Designing Hard Software by Douglas W. Bennett (http://www.amazon.com/exec/obidos/ASIN/0133046192), an out of print 1997 book.  The only reasonable thing for me to do was buy one of the used books available on Amazon.

Bennett does a good job of identifying categories of change cases.  Even if some of the specific examples seem a little out-dated, the concepts translate quite readily into problems being faced by systems under development today.  What’s missing is any indication of what the content of the change case should be, and how they should then be used in the evaluation of a software system architecture and design.  Scott Ambler offers the following as a change case template:

  • Name:  (One sentence describing the change)
  • Identifier (A unique identifier for this change case, e.g. CC17)
  • Description (A couple of sentences or a paragraph describing the basic idea)
  • Likelihood (Rating of how likely the change case is to occur (e.g. High, Medium, Low or %))
  • Timeframe (Indication of when the change is likely to occur)
  • Potential Impact (Indication of how drastic the impact will be if the change occurs)
  • Source (Indication of where the requirement came from)
  • Notes

That is a start on an answer to the first question – what is the content of a change case?  But that content list raises a question of its own – how do we decide on the potential impact?   Also, we still need to consider how we use this information.  Is there a structured format for evaluating the impact of a change case?

One possibility is a variation on Robustness Analysis.  This technique comes from some of Ivar Jacobson’s early work, as elaborated by Doug Rosenberg in the ICONIX process.  In addition to the books that include this topic (http://iconixprocess.com/books/) there’s an article on the ICONIX web site (http://iconixprocess.com/iconix-process/analysis-and-preliminary-design/robustness-analysis/) and one on the Dr. Dobb’s web site (http://www.ddj.com/architect/184414712).  Robustness Analysis is applied to use cases in order to verify their completeness.  A variation on this technique might help to identify what objects/components will need to have additional responsibilities and what new components might need to be added where it doesn’t make sense to change or extend an existing component.

A less structured approach might be to emulate the analysis of growth scenarios in the SEI’s Architecture Trade-off Analysis Method (ATAM)  (http://www.sei.cmu.edu/architecture/ata_method.html).  SEI evaluators often talk about pulling a thread to drill down wherever it is necessary to determine whether or not the architecture will support the growth.  This approach works well for the experienced evaluators at the SEI, but may be quite challenging for someone without their level of experience.

My plan is to experiment with these techniques.  If you have any suggestions for an alternative method, or a way to apply these two techniques, then please feel free to comment.


SAC 21 Workshop: What was right, what was wrong, and what was missing.

June 12, 2009

Now I know the answer to the question of what will it take for me to actually start writing in this blog.  Now I need to figure out how WordPress works.  In the meantime, here’s a really long post.

On June 8th I attended the Software Architecture Challenges for the 21st Century workshop (http://csse.usc.edu/csse/event/2009/Arch-Workshop/pages/program.html) held at the University of Southern California.  The IEEE Software blog (http://www2.computer.org/portal/web/computingnow/sac21) described the event this way:

“Members of IEEE Software’s editorial board and faculty from USC’s Center for Systems and Software Engineering and the University of California, Irvine’s (UCI’s) Institute for Software Research came together for a wide-ranging discussion of the role and value of architecture in software development in the age of grid, cloud, Web, and volunteer computing.”

On the three hour drive home from USC I decided that I wanted to say something about the workshop.  The more I thought about it, the more I realized I had a lot to say about what I liked and where I saw room for improvement.

What Was Right

There was a reasonably large group split between academicians and practitioners.

In general, the speakers were erudite and articulate and the event was relatively information dense.  Thankfully, there were differing opinions on several topics so we got a chance to consider the different viewpoints.

Several speakers made the point that agile software development does not mean don’t do or have architecture.  Philippe Kruchten made the point that he was both an architect and a co-founder of Agile Vancouver.  That was especially interesting to me as I was teaching both  an architecture class and an agile software development class in the spring quarter at UCSD Extension.  My experience has been that requirements and architecture provide the necessary foundation and context for agile software development to be effective.

I am especially indebted to Kruchten for his point about two different kinds of architects – Architectus Reloadus and Architectus Oryzus.  I have explored that topic in more detail already, reading Martin Fowler’s IEEE Software article – “Who Needs an Architect?” (http://www.martinfowler.com/ieeeSoftware/whoNeedsArchitect.pdf) and going through a set of comments on that article from Venkat Subramaniam’s students at the University of Houston (http://www2.cs.uh.edu/~svenkat/fall2006SE/yousaid/yourcommentsonwhoneedsanarchitect.html).

What Was Wrong

SAC 21 wasn’t really a workshop, it was more like a mini-conference.  What was missing was sufficient time for discussion and serious interaction between the attendees and the hosts/presenters.

In talking about UML, many of the presenters focused on the documentation aspects of UML.  Grady Booch went so far as to state that he threw away some UML diagrams.  Andre Van der Hoek presented a tool that was intended to capture whiteboard style sketches.  In the first case, one must (might?) assume that there was value in creating the UML that was discarded.  Just as people learn differently, so some people design differently.  For one, text and table might be sufficient.  For others, visualization is the key to understanding.  UML provides the syntax and semantics necessary for such visualization.

Once understanding has been achieved, it is reasonable to limit the maintained documentation to summary level descriptions.  I would argue that rather than throw away the rest of the model, it should be maintained in a CM repository for possible future use.  On the other hand, I often create a robustness analysis diagram as a preliminary design step.  Once we have created the diagram, we have developed sufficient confidence in our understanding of that part of the problem, and the diagram can be discarded.  The value of the diagram is in the creation.

One participant asked a question about executable architectures.  The question was answered as if it was regarding executable UML.  There is a significant difference between the two.  Executable architecture (aka simulation) is a technique that supports early system verification and validation.  To the extent that the execution can be tightly coupled to the architecture models, then we can avoid translation errors in developing the simulation.  There is significant value in avoiding such errors in complex system development (think FCS combat vehicle http://www.globalsecurity.org/military/systems/ground/fcs-mgv.htm).

Executable UML (http://en.wikipedia.org/wiki/Executable_UML) offers an opportunity to do model-based development, with transformation of the Platform Independent Model to the implementation model.  As it is explained in the Wikipedia article, xUML does have a limited scope, unlike executable architecture.

What Was Missing

The most glaring omission was methodology.  Philippe had one slide on the topic that didn’t say much.  Others ignored the topic.  This is possibly the most crucial aspect of what architects need – a method like the Visual Architecting Process from Bredemeyer Consulting.  I recommend the article “Less is More with Minimalist Architecture” by Ruth Malan and Dana Bredemeyer, published in IEEE’s IT Professional, September/October 2002, as well as the VAP.

Systems Architecting!  Software Architecture can no longer be considered as a specialty engineering element to be addressed after the systems engineering has been completed.  I totally agree with Mark Maier (http://search.barnesandnoble.com/booksearch/isbnInquiry.asp?r=1&ISBN=9781420079135&ourl=The-Art-of-Systems-Architecting-Third-Edition%2FMark-W-Maier) when he says that architecting of software must begin early, before the system architecting is complete.  USC needs to lead in this area.  They are, after all, the Center for SYSTEMS and Software Engineering, offer an MS in System Architecture (http://www.usc.edu/dept/publications/cat2006/schools/engineering/systems_architecture.html#masters), and are leaders in the Systems Engineering Research Center.

  • During his presentation, Booch mentioned a satellite system that he is working on where software architecture has been negatively impacted by systems decisions regarding the number of processors made before the software architects got involved.
  • One systems engineer attendee asked the same question several times – how long does the software architecture last?  The answers he got were a little non-specific (e.g as long as the system lasts).  One of my colleagues suggested that perhaps the answer should have been another question – how long does the system architecture last?
  • The Software Engineering Institute (http://www.sei.cmu.edu) has recognized the need to expand their focus.  They invited John Zachman and Mark Maier to offer their perspectives on Enterprise and System architecting respectively, at the 2009 SEI Architecture Users Network conference (http://www.sei.cmu.edu/architecture/saturn/2009/).  The theme of SATURN 2009 was “architecture at all scales.”

What Now?

The time has come for a holistic architecting approach.  Software pervades our modern systems and we need to learn how to work concurrently and cooperatively, as effectively and efficiently as possible.  A lofty goal but one I believe is achievable.