SPARX ENTERPRISE ARCHITECT GUIDELINES ARCHITECTURE DOCUMENT
Oct 26, 2014
SPARX
ENTERPRISE
ARCHITECT
GUIDELINES
ARCHITECTURE DOCUMENT
Page 2 of 19
Page 3 of 19
REVISION DOCUMENT HISTORY
Date Version Description Author
11/11/2011 1.0 Initial Document Harold Flores
Page 4 of 19
TABLE OF CONTENTS
Contents
CONTENTS ............................................................................................................................................... 4
1 INTRODUCTION ...................................................................................................................... 5
1.1 OBJECTIVE .................................................................................................................................... 5
2 ENTERPRISE ARCHITECT MODEL STRUCTURE ......................................................... 5
3 WORKING IN A DISTRIBUTED TEAM WITH VERSIONED CONTROL
ENVIRONMENT ................................................................................................................................ 8
4 USING COMMON PACKAGES ........................................................................................... 12
5 USING TRACEABILITY TOOLS ........................................................................................ 13
6 CREATING HYPERLINK FOR PUBLISHED DOCUMENTS ...................................... 15
7 MISCELLANEOUS RECOMMENDATIONS .................................................................... 17
Page 5 of 19
1 INTRODUCTION
1.1 Objective
The objective of these guidelines is to provide a summary of recommendations supported at Axcess
Financial for helping Software Engineers, Business Analysts and Architects in the utilization of
Sparx Enterprise Architect.
Sparx EA is adopted at Axcess Financial as a Modeling Tool for design and construction of software
applications, business and systems models, and different elements that help to visualize current
and planned systems and processes.
2 ENTERPRISE ARCHITECT MODEL STRUCTURE
It is recommended that Enterprise Architect Models maintain the following structure for software
projects. We are using the definition of Views to help the understanding of system structure and
behavior. In addition some sub-folders are suggested for creation and use depending of the scope
and level of detail required.
‘ABC’ Model
Analysis View
(Include Analysis, Classes and Activity Diagrams)
Suggested sub-folders are:
Business Rule Model
(It supports the modeling of conceptual business rules to a logical level of detail)
Business Objects Model
(Contains a domain model of all objects of interest and their respective data
utilized in main business activities)
Business Workflows
(It reflects the main business activities in which the system is involved)
Requirements
(Include Requirements Diagrams)
Suggested sub-folders are:
Functional requirements
Non-functional requirements
Security
Performance
Scalability
Page 6 of 19
Availability
Fault-Tolerance
Legal, etc
Agility Requirements
Extensibility
Efficiency
Flexibility
Maintainability
Adaptability
Use Case View
(Include Analysis, and Use Case Diagrams)
Suggested sub-folders are:
Actors
Use Cases
Use Case Model
Business Use Cases
System Use Cases
In addition the analysts could create sub-folders separating the system functions for
better understanding of the modules.
Dynamic View
(Include Use Case Realizations based on State and Sequence diagram)
Analysts could create sub-folders related to Use Cases or Domain Classes for
better understanding of the model
Logical View
(It is a Logical model of the software system under construction)
Include Package, Class Diagram, Object and State Diagrams,
Reverse/Forward Engineering Class Diagrams which are being built or
designed as part of the current model.
Normally the folders created under a logical view are mapped to classes and
artifacts created at the source code level.
Examples of sub-folders are:
Page 7 of 19
Project 1 (Source Folder in Code Management Repository).
com
axcessfinancial
„abc‟
web
domain
service
eis
dao
esb
…
…
Project 2 (Source Folder in Code Management Repository)
com
axcessfinancial
„def‟
web
domain
service
eis
dao
esb
…
…
Other Project Package Folders and relevant dependencies would be added
here.
Framework Support
(Include Package, Class, State, Activity, and Component Diagrams
of classes and components that are referenced by other folders and have
Page 8 of 19
been implemented based on Java, C#, and Open Source technologies:
Mule, Spring, Hibernate, etc)
Component View
(Include Component Diagrams, indicates how low level elements, classes, artifacts are
connected, as well as the interfaces that are exposed)
Deployment View
(Include Deployment Diagrams, indicates how and where the system and various
dependencies will be deployed. Include views to reflect the integration of the system
with other applications.)
A typical system in Axcess Financial would have the following distribution:
3 WORKING IN A DISTRIBUTED TEAM WITH VERSIONED CONTROL ENVIRONMENT
1. In Axcess Financial the scenario utilized for Enterprise Architect is defined as distributed teams
using local copies of the model in a Versioned Control Environment.
2. In this configuration, each editor maintains a local copy of the model as an EAP file or local
database and periodically updates their copy from a shared Version Control Repository.
Page 9 of 19
Software Architect Business Analyst Software Engineer
EA
Client
EA
Client
EA
Client
Version Control
Repository
(Subversion)
3. In this environment it is required to apply Version Control to all the sub models and packages
defined in the application model.
Our version control tool is Subversion. For a description in how to configure Subversion (SVN)
and Enterprise Architect, it would be important to review:
https://peru.axcess-financial.com/share/page/site/softwareengineering/wiki-page?title=Enterprise_Architect_-_Version_Control&listViewLinkBack=true
Another important source for evaluation is the PDF document of best practices from Enterprise Architect located at this URL: https://peru.axcess-financial.com/share/proxy/alfresco/api/node/content/workspace/SpacesStore/4f45335b-308c-4010-ab5c-2231849af471/Version_Control_Best_Practices_Sparx_EA.pdf
4. There are a couple of important concepts in Enterprise Architect to consider:
a. Model Branch file (*.EAB) simplify the process of exporting and importing the
package hierarchies from one model to another.
Applying version control to an Enterprise Architect model can result in many XMI files
placed under version control. It could then be hard to locate and import the file
corresponding to the root of a particular model branch. Enterprise Architect's Model
Branch Files (.EAB files) overcome this problem by simplifying the retrieval of model
hierarchies for use in other models.
Page 10 of 19
b. A Baseline is a snapshot of a package or a model branch at a particular point in time,
which you determine. You can use the Baseline as a distribution mechanism for changes
to the model, but the main use is to enable you to compare the current model with a
previous stage, and detect what changes have been made since the Baseline was
captured.
If you do not want a change to remain in the model, you can roll the affected elements
back to the state they had in the Baseline. Therefore, if you maintain your requirements
in a specific package or branch, you can capture Baselines of the package and ensure
that changes conform to your change management process or, if not, can be reversed.
5. Every EA model would have the following folder structure in a Subversion source control
repository:
‘ABC’_Model_EA
o trunk
Trunk folder contains the list of XMI files as result of applying version control on the
packages of the model.
o baselines
This folder contains Baseline files (*.xmi) generated by the team when there is a
need to review recent history of changes. These files would have the following
convention:
<Model_Name>-<View>-X.X.X.X.xmi
Where Model Name refers to the name of the system, including also the name of the
View and finally X.X.X.X corresponds to the version number.
o branches
It would contain a versioned copy (using subversion) of the Enterprise Architect files
from the trunk folder. Their utilization is recommended in case there is a need to
really make modifications to trunk files of the model without having all other teams
to perceive these modifications yet. Merging into the trunk after operation is
completed would be executed trough a baseline merging process. Folder‟s name has
the following standard:
<Model_Name>_X.X.X.X : Where Model Name is the reference to a system name
and X.X.X.X corresponds to the version number.
Important: The use of subversion branches of the model and the merging
process should be carefully handled. Reason given is that when comparing a
baseline file against the model would show only differences between
elements and links but not modifications in diagrams.
It is most recommended to execute changes to the models in the trunk
folder.
6. Under version control all EA models should have a corresponding Version Control Id to be
distributed among team members.
Page 11 of 19
Indicate the Version Control Id under this format: <Model Name>_EA_ID
7. Enterprise Architect offers the possibility to create Model Branch files (*.EAB) which allows a
convenient reference for a sub-tree in the model.
Applying this concept to our described EA Structure we will have the following convention for
the „ABC‟ Project.
Package Model Model Branch file name (*.EAB)
Root Model „ABC‟ – Root.EAB
Requirements Model „ABC‟ – Requirements.EAB
Use Case View „ABC‟ – Use Case View.EAB
Class View „ABC‟ – Class View.EAB
Component View „ABC‟ – Component View.EAB
Deployment View „ABC‟ – Deployment View.EAB
Analysis View „ABC‟ – Analysis View.EAB
Logical View „ABC‟ – Logical View.EAB
The following diagram could display a sample of the hierarchy indicated above.
Page 12 of 19
4 USING COMMON PACKAGES
1. Building a software solution would require the creation of re-usable modules. The following
graphic indicates a typical relationship between software modules.
pkg Axcess Financial System
Financial Lending ModuleAccounting Module
Party Pattern module Product Pattern module
General Ledger module
2. These common packages would be normally shared across several EA models.
The suggestion in order to simplify maintenance would be to include these common models as
additional Root Folders in the Enterprise Architect Model.
Example:
Stars Lending Products Model
Logical View
Financial Lending Model
Axcess Accounting System
Logical View
Accounting Module
Party Pattern Model
Logical View
A typical view of related modules would be seen in Enterprise Architect as follows:
Page 13 of 19
5 USING TRACEABILITY TOOLS
Enterprise Architect allows the understanding of how a feature of a system has been implemented
through the review of traceability of different elements of the models like Use Cases,
Requirements, Classes, Sequence Diagrams, State Diagrams, etc.
There are a set of traceability tools to accomplish the above objective.
a. Traceability Window
It is available as a separate window in Sparx EA to explore the relationship chain between
elements.
At any point a modeler could create a Traceability Diagram or other model and execute actions
that would display information in the traceability window.
When you click on an element, it immediately becomes the top point in the
Traceability window.
When you click on the background of a diagram, all elements in the diagram are
listed in the Traceability window, and you can follow the threads starting at each
element through the diagram.
Let‟s view the following example of a simple traceability diagram created manually by the
modeler where he/she has indicated the realization of a requirement, and has also indicated a class that trace back to a Use Case definition.
Page 14 of 19
custom Traceability Diagram
FR-01 Review Customer
Data
(from PayDayLoan)
A
(from InitialRelease)
UC01-Rev iew
Customer Data
Business Object
Model::Customer
- FirstName :String
- LastName :String
- TaxID :String
Review Data
(from PayDayLoan)
«trace»
If the user does a click on the background of the diagram the view of the Traceability Window (using menu View | Traceability) would display the following information:
b. Relationship Matrix
The Relationship Matrix is a convenient method of visualizing relationships quickly and
definitively.
It also enables you to create, modify and delete relationships between elements with a single
mouse click - another quick way to set up complex sets of element relationships with a minimum of effort.
On the Relationship Matrix, you select:
A source package
A target package
The relationship type and
Page 15 of 19
The relationship direction
Enterprise Architect identifies all the relationships between source and target elements by:
Listing the source package elements down the side of the matrix
Listing the target package elements across the top of the matrix and
If a relationship exists between a source and target element, highlighting the
intersecting grid square and displaying an arrow indicating the direction of the relationship
Following our previous example, we could have access to the Relationship Matrix (using Menu
View | Relationship Matrix) and evaluate the link between Use Cases and Requirements in
our Financial Lending Model. Sparx EA allows the display of the association between the
selected source and target elements.
6 CREATING HYPERLINK FOR PUBLISHED DOCUMENTS
Different stages in the software development at Axcess Financial create various artifacts and
documents that extend the understanding and comprehension of the internal structure of a system.
E.g. Analysis phase would provide a Business Requirement Document and a set of Business Use
Case Documents.
Axcess Financial would store these artifacts and documents in an Enterprise Content Management
System like AlFresco share.
Sparx EA offers the option to create Hyperlinks to diagrams and it would be recommended to use
this feature in order to have more elements available when understanding the system‟s structure
and behavior.
Example:
A requirement diagram has a link to access to a spreadsheet document that indicates system
functionality.
Page 16 of 19
For creating this relation, there is a “Hyperlink” tool under common function of the tool box in
Sparx, as the following figure indicates.
The modeler could input the URL address of the document in AlFresco Share and indicate a proper
Alias for review of the reader:
Finally the hyperlink would be available in the diagram:
Page 17 of 19
7 MISCELLANEOUS RECOMMENDATIONS
Here is a list of general recommendations to be considered when utilizing Enterprise Architect in
Axcess Financial:
1. When executing forward/reverse engineering utilize the creation of and Identifier for the
Local Path where you are extracting or generating the source code.
The system option that allows that configuration can be found in the menu option: Settings >
Local Paths …
Example:
If a Software Engineer is doing a reverse engineering of the AxcessFinancial-Core project and
the location of the source code in his/her machine is c:\axcessfinancial\axcessfinancial-core-
1.0.0, then he/she would have to create a local path id in enterprise architect as the following:
AXCESS_CORE_PATH = c:\axcessfinancial\axcessfinancial-core-1.0.0\src\main\java
If later the source code location has changed the Software Engineer only would have to update
the Identifier created as AXCESS_CORE_PATH.
2. It is important to remember that all team members (Software Engineers, Software Architects,
Business Analysts, PMs and Quality Engineers) with access to the model and source code would
have to create the local path identifiers based on a catalog to be provided by the Software
Engineering Lead of the application per module.
3. It is recommended to always execute a verification of the model in order to ensure its integrity
and eliminate void references.
For that reason is recommended to utilize the option in Sparx Enterprise Architect handled by:
Tools > Data Management > Project Integrity Check ..
Page 18 of 19
Execute this checking through both actions: Report Only and Recover/Clean.
8 ENFORCEMENT
Project teams need to be self governing organizations; therefore, PMs should enforce the
observance of these guidelines throughout the entire project by conducting a series of review
sessions with their stakeholder and project teams.
In addition, the Enterprise Architecture department will conduct Enterprise Architecture compliance
reviews to:
o Ensure the accuracy and consistency of NextStar models; making sure they depict current
architecture (production) and transition architectures (upcoming releases)
o Preserve application of best practices in:
o UML notation and
o Object oriented analysis and design
These recommendations have been indicated in the guidelines document created by
Architecture team and available at this URL:
https://peru.axcess-
financial.com/share/proxy/alfresco/api/node/content/workspace/SpacesStore/4f88027f-
9ec7-4e7f-9c63-0c249b448438/Software%20Engineering%20Modeling%20Guidelines.pdf
Page 19 of 19
A regular review process would be executed as follows:
a. At least 2 weeks in advance the project team will be notified that a regular review of
compliance to Enterprise Architect guidelines would take place.
b. The agenda of the review would be provided. Unless indicated otherwise the agenda would
indicate:
o Check of EA model structure under subversion control.
o Review of Analysis, Logical, Dynamic, Deployment and Component Views,.
o Verification of integrity of the model
o Reuse of common modules
o Publishing of the models through HTML format
c. The time for revision would accommodate between 4 – 6 hours