S PA R X E N TE R PR I S E A RC HITE C T G U I D EL I N E S

ARCHITECTURE DOCUMEN T

Page 2 of 19

REVISION DOCUMENT HISTORY

Date 11/11/2011 Version 1.0 Description Initial Document Author Harold Flores

Page 3 of 19

TABLE OF CONTENTS
Contents
CONTENTS ............................................................................................................................................... 4 1 INTRODUCTION ...................................................................................................................... 5 1.1 2 OBJECTIVE .................................................................................................................................... 5

ENTERPRISE ARCHITECT MODEL STRUCTURE ......................................................... 5

3 WORKING IN A DISTRIBUTED TEAM WITH VERSIONED CONTROL ENVIRONMENT ................................................................................................................................ 8 4 5 6 7 USING COMMON PACKAGES ........................................................................................... 12 USING TRACEABILITY TOOLS ........................................................................................ 13 CREATING HYPERLINK FOR PUBLISHED DOCUMENTS...................................... 15 MISCELLANEOUS RECOMMENDATIONS .................................................................... 17

Page 4 of 19

1 1.1

INTRODUCTION 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.

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 5 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 6 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 7 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:

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 8 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/wikipage?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.axcessfinancial.com/share/proxy/alfresco/api/node/content/workspace/SpacesStore/4f45335b308c-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 9 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. Folders 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 10 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 Root Model Requirements Model Use Case View Class View Component View Deployment View Analysis View Logical View Model Branch file name (*.EAB) ABC Root.EAB ABC Requirements.EAB ABC Use Case View.EAB ABC Class View.EAB ABC Component View.EAB ABC Deployment View.EAB ABC Analysis View.EAB ABC Logical View.EAB

The following diagram could display a sample of the hierarchy indicated above.

Page 11 of 19

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 Module Accounting Module

General Ledger module Party Pattern module Product Pattern 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 12 of 19

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.

Lets 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 13 of 19

custom Traceability Diagram Review Data (from PayDayLoan)

FR-01 Review Customer Data (from PayDayLoan)

UC01-Rev iew Customer Data

Business Obj ect Model::Customer

A

trace

(from InitialRelease)

FirstName :String LastName :String TaxID :String

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 14 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.

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 systems structure and behavior. Example: A requirement diagram has a link to access to a spreadsheet document that indicates system functionality.

Page 15 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 16 of 19

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-core1.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 17 of 19

Execute this checking through both actions: Report Only and Recover/Clean.

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) Preserve application of best practices in: o o UML notation and 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.axcessfinancial.com/share/proxy/alfresco/api/node/content/workspace/SpacesStore/4f88027f9ec7-4e7f-9c63-0c249b448438/Software%20Engineering%20Modeling%20Guidelines.pdf

Page 18 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 o o o o Check of EA model structure under subversion control. Review of Analysis, Logical, Dynamic, Deployment and Component Views,. Verification of integrity of the model Reuse of common modules Publishing of the models through HTML format

c. The time for revision would accommodate between 4 6 hours

Page 19 of 19