Sometimes you are in a position to develop a completely new, stand-alone system.  If this is the case you should consider yourself amongst the lucky few because the vast majority of developers must often integrate/interface to existing legacy information resources.  This could include anything from existing databases or files, existing systems, or even brand-new reusable web services.  This section presents a brief overview of legacy system analysis as well as the common problems that you may encounter.

The need to work with legacy systems constrains a development team.  It reduces your flexibility because you often cannot easily change the legacy systems to reflect the needs of your system.  For example, legacy data often doesn’t provide the full range of information required by your system because the existing data does not reflect your new requirements.  Similarly, legacy systems which implement functionality that you would like to reuse can often be “almost good enough” but not quite. 

Agile Modeling (AM) includes the Formalize Contract Models practice which is directly related to legacy system analysis.  The basic idea is that when you discover that your system requires access to an information resource then you need to put a “contract model” (often called an external interface specification) in place between your group and the external one.  Examples of contract models include the detailed documentation of an application programming interface (API), a file layout description, an XML DTD or a physical data model describing a shared database.  I call them contract models because they effectively form a contract between the owner of an information resource and the owners of other systems that use it – the owner can’t change the system without at least informing everyone else ahead of time or better yet negotiating any changes with them.  As with a legal contract, a contract model often requires you to invest significant resources to develop and maintain the contract to ensure that it’s accurate and sufficiently detailed. Your goal is to minimize the number of contract models for your system to conform to the AM principle of traveling light.

You often identify potentially legacy information sources that you need to work with as part of your deployment modeling efforts.  For each information source that your system must work with you will need to perform some form of legacy system analysis.  If you’re lucky accurate documentation already exists for the information resource, and if this is the case your entire analysis effort might be to talk to the system owners and read through the documentation to determine if the information source meets your needs.  In many cases you’ll discover that little or no documentation exists or it’s badly out of date.  When this is the case either you or the system owner, or both of you, will need to invest the time to analyze and sufficiently document the legacy information source.  This activity will often involve working closely with the owners to understand the legacy asset, poring through any pertinent source code, working with modeling tools which support reverse engineering documentation based on the existing source code, or simply working with the legacy information source to determine how it works.  This often proves to be a long and arduous process.

The most common style of contract model is an external interface (EI) specification which describes how to access an external system.  When I’m creating an external interface specification I like to capture the following information:

• Identifier. A unique identifier, for example EI-1701.

• Description.  A couple of sentences or a paragraph describing the external system interface.

• System owner.  The name(s) and contact information of the people who own the system.  Include both the project manager and the technical contact.

• Type.  The type of interface, e.g., XML, JMS, Java API, flat file transfer, etc

• Direction. List the direction of the transfer – Outwards, inwards, or bi-directional.  

• Frequency. Approximately how often this interface is exercised, e.g., once a week, 500 times a day, etc.

• Timing. Describe when the interface is used, for example 24/7, once a night at 2 a.m., and so on.

• Transfer rate. List known or required transfer rates, e.g., the file will be 50 megabytes on average or the records will be 125 bytes each.

• Security.  List known security issues, e.g., is a login required, is the source system protected by a firewall, is a secure socket layer used, …

• Format. Describe in detail the format of any data  transfer.  You may simply reference an XML schema definition, describe a file record layouts, or describe a C API.   The information in this section will vary depending on the interface specifics.

• Issues.  List any "to dos", concerns to be addressed, and so on.

• Decisions. List any important decisions made during the development of this interface.

You can download an EI specification template here.

Suggested Reading

• Artifacts for Agile Modeling: The UML and Beyond 
• Modeling Style Guidelines
• Why Extend the UML Beyond Object and Component Technology?

 

		This is a very good, high-level book which deals with how to transform legacy systems into high-quality reusable assets.
		The Object Primer 3rd Edition: Agile Model Driven Development with UML 2 is an important reference book for agile modelers, describing how to develop 35 types of agile models including all 13 UML 2 diagrams.  Furthermore, this book describes the techniques of the Full Lifecycle Object Oriented Testing (FLOOT) methodology to give you the fundamental testing skills which you require to succeed at agile software development.  The book also shows how to move from your agile models to source code (Java examples are provided) as well as how to succeed at implementation techniques such as refactoring and test-driven development (TDD).  The Object Primer also includes a chapter overviewing the critical database development techniques (database refactoring, object/relational mapping, legacy analysis, and database access coding) from my award-winning Agile Database Techniques book.
The Joy of Legacy Data		This essay explores many of the common issues that you may discover regarding legacy data.
		Agile Modeling: Effective Practices for Extreme Programming and the Unified Process is the seminal book describing how agile software developers approach modeling and documentation.  It describes principles and practices which you can tailor into your existing software process, such as XP, the Rational Unified Process (RUP), or the Agile Unified Process (AUP), to streamline your modeling and documentation efforts.  Modeling and documentation are important aspects of any software project, including agile projects, and this book describes in detail how to elicit requirements, architect, and then design your system in an agile manner.
		The Elements of UML 2.0 Style describes a collection of standards, conventions, and guidelines for creating effective UML diagrams. They are based on sound, proven software engineering principles that lead to diagrams that are easier to understand and work with.  These conventions exist as a collection of simple, concise guidelines that if applied consistently, represent an important first step in increasing your productivity as a modeler.  This book is oriented towards intermediate to advanced UML modelers, although there are numerous examples throughout the book it would not be a good way to learn the UML (instead, consider The Object Primer).  The book is a brief 188 pages long and is conveniently pocket-sized so it's easy to carry around.