I wanted to share some thoughts on Sparx Systems’ Enterprise Architect software. As the name implies, this is primarily a tool for supporting life cycle modeling for business and IT systems. But Sparx also targets general software and systems engineering efforts. I’m interested in the development of large and complex products using the tool.
A quick online search provides a lot of great information about modeling systems and software with EA, and the Sparx website offers a tremendous amount of information to help one get started. Many articles focus on a single EA instance supporting a large number of projects, but developing a single large EA project is different. While both scenarios might have hundreds of software elements, perhaps thousands of class definitions, developing a single large project implies a common set of system-level requirements, a large number of distinct models and a higher level of integration between them.
How Large?
The idea of a large project is subjective. A set of web applications, database structures and related back-end services can represent a large, substantial project. Projects like space shuttles or battleships are very large projects.
Let’s consider a large project to be several complex systems working together to deliver a well-integrated product having mechanical and electrical elements as well as software. Smaller than a battleship but a bit larger than most web service offerings. Each of the subordinate systems could be considered large in their own right.
A physically large system could be modeled as containing any number of systems with each of those being modeled as a large system. The challenge is organizing those models to provide viewpoints within each subordinate system as well as viewpoints describing an integrated result.
Sparx promotes EA as providing support for full life cycle modeling and although they provide a tremendous number of training documents and examples, they don’t really explain how to bring those examples together. This isn’t a problem with smaller projects, but larger ones become difficult to navigate and almost impossible to learn for new people on the project.
Target the New Stakeholder
The examples shown below model a generic Proton Therapy System intended to treat cancer. That system is meant to deliver a radioactive dose to a cancerous target volume while providing minimal damage to surrounding healthy structures in the body. You can find more design information here. This is our example of a System of Systems; such a product will contain a particle accelerator having multiple systems itself, but will also contain a variety of clinical systems, supporting infrastructure and more.
Organizing all of this information is best done with a new user in mind, someone unfamiliar with the details of the product and its technology. This is especially important in a regulated environment where auditors will want to look for artifacts relating to specific development activities. And a large project implies a lot of people coming up to speed after initial concepts and requirements are developed. They’ll need to understand where to find information and how to contribute. Experienced users can make use of bookmarks to go directly to their work areas.
A Package Hierarchy
Enterprise Architect allows multiple “root nodes” to exist in a single database, representing multiple projects. The large system shown here is in a single root node containing multiple packages. The package is a basic element of EA, able to contain multiple elements and diagrams.
The suggestion is that three broad types of packages be presented when first accessing the data.
- Startup and General Information
- Models for Each of the Product Development Phases
- A Library of All Product Components
In Figure 1 we can see the Startup and General Information category contains a Start Here entry followed by a package showing the types of users and the context in which they will work, and project documents. Generating documents on demand is an important feature of EA. The Documents folder acts as a repository of the most common documents so users don’t need to generate the same ones repeatedly.
Figure 1. The Browser Window Shows EA Packages
The next set of packages shows various models, described below. The final package in Figure 1 contains the System Libraries, which describe the specific elements needed to model the system and its various versions.
Although the browser will show this list when a new user accesses the system, the main display should contain some navigation help. I suggest setting Enterprise Architect to open a default page when starting. Afterwards, each user can select a default page to display for themselves.
Figure 2. A Sample Start Screen as a Table of Contents
In this example, each major system package contains a Contents diagram containing navigation cells to guide the user. By default, this database shows the Contents diagram from the topmost “Start Here” package as a starting point. This is only recommended for each of the top-level packages.
Rather than being presented with a potentially large list of elements in the browser, the user is guided through the breadth of the system in a more controlled and (ideally) understandable way.
Each package from the Browser list is typically represented on the welcome screen.
Models Aligned With Product Development Phases
Various tools can be used to model the system and these models are ultimately meant to communicate its design, typically delivered in specific phases of a development process. The requirements of each subsystem, the interactions between the components and the testing process can all be modeled and should all be communicated hierarchically, targeting specific stakeholders.
Rather than organizing that communication by component, each one having requirements, designs, test plans and so forth, its recommended to organize by development phase or deliverable. Have all the requirements modeled in one hierarchy, all of the system architecture and design models placed in another, and so forth.
The reason is that stakeholders will often want to focus on specific types of deliverables. An engineer will want to see designs; the requirements, tests, deployment models are all important as well, but a breadth of design models will be the first focus. A marketing expert will want to look at requirements and need not focus on design or testing details, interested in the breadth of requirements relating to a sellable product.
Enterprise Architect allows models to be built with references to components in other packages. The suggestion is that all components be kept in a library package and models referring to them be kept separate. The models describing a component will be updated as the component changes.
Modeling elements from different perspectives satisfies stakeholder needs, and EA provides dependencies to be captured between all components and models. For example, If one wants to discover everything relating to motion control software, they can start with design models, deployment diagrams or requirements, and easily trace all related information through relevant models, components and documents.
System Libraries
The package at the end of the Browser list contains the System Libraries. It contains the master, current versions of all system content including content for each subordinate system. Previous versions and ongoing development versions are also kept here. It’s important to understand that almost all library elements will be referenced in other packages outside the library, so any changes will be immediately reflected and stakeholders can see potential impact on their work.
Requirements and other artifacts are also defined here along with the system elements. Each library entry will have a well defined state such as Proposed, Approved or Implemented. In fact, it might be more appropriate to label this as Product Libraries because Use Cases, test plans and vendor specifications can be kept here.
Each element in the library has text and diagrams describing that element. This text can be extracted by EA and included in the documents that it generates, along with diagrams and other material such as Tables of Contents, Cover Pages, company style sheets and more.
All Elements Produced, Not All Elements Shipped
It’s important to note that all systems, currently available or planned for the future should be represented here. All elements with which any product offering can be built should be represented here. For example, a Proton Therapy System has a particle accelerator to produce protons. The System Libraries shown here have four different types of accelerators, but only one of those would exist within a specific product offering.
As a hierarchy of packages, each subordinate system should contain packages representing everything being constructed for that system. The hierarchies can become quite large and EA provides a useful search tool for finding specific components. Not all hardware components need be represented here and the level of detail is determined by your needs. If your systems will be maintained and serviced you might consider limiting the depth of the hierarchy to include field-replaceable units. If your system contains hardware purchased off-the-shelf from known vendors, you can limit the hierarchy to those elements.
It’s also important to understand that product component lists such as Bills of Materials will not have the same contents as the System Libraries. While a Bill of Materials contains everything needed for manufacturing a specific product, the System Libraries here represent everything that can be used in any and all of your products and will probably include more detail if you’re developing those elements in-house.
As suggested above, ongoing design and development work should also be represented in the library package. Any changes to these elements will be reflected in all models that reference them, so only a few people on larger projects will have the ability to change currently released component information. Engineers and other team members would have access to the versions of those components currently under development.
More Enterprise Architect Information
Sparx Systems has several great tutorial articles for learning Enterprise Architect, describing how to set up accounts, enable secure concurrent work, create a central repository for your information, provide remote access and much more. For advanced and customized needs, I also recommend visiting the website of Geert Bellekens at https://bellekens.com. Geert is an EA expert and has some great tools for supporting and extending Enterprise Architect.
