Top Banner
SPARX ENTERPRISE ARCHITECT GUIDELINES ARCHITECTURE DOCUMENT
19
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Page 1: Sparx Enterprise Architect Guidelines

SPARX

ENTERPRISE

ARCHITECT

GUIDELINES

ARCHITECTURE DOCUMENT

Page 2: Sparx Enterprise Architect Guidelines

Page 2 of 19

Page 3: Sparx Enterprise Architect Guidelines

Page 3 of 19

REVISION DOCUMENT HISTORY

Date Version Description Author

11/11/2011 1.0 Initial Document Harold Flores

Page 4: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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: Sparx Enterprise Architect Guidelines

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