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 team leader 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.