Recently, various discussion groups I participate in have been focusing on interface requirements. Given the importance of managing interfaces [see blog “Why are Interfaces Important?], it is critical that you get everything right.   By “right” I mean (1) you need to make sure you have identified all interfaces – both external and internal, (2) you have made sure the interactions across these interfaces have been defined and agreed-to in writing, and (3) that the interface requirements have been documented in your requirement document as well as in the requirement documents for those systems with which you are interacting.

If you are interacting with an existing system, there may not be any requirements dealing with your system specifically, but there is probably documentation on how individual interacting systems are to behave in order for an interface to work. Most commonly, this type of information is found in an Interface Control Document (ICD), or Application Program Interface (API) type document. If this is the case, you will have an interface requirement in your requirement document that details the type of interaction(s) needed and will include a reference to how to accomplish this interaction by referencing the applicable place in the existing systems’ ICD or API.

When you are interacting with systems that are being developed concurrently with yours, the problem becomes more complex.   Specifically, the definition on how your system will interact with the other system is often not completely known until the design is complete. Thus the interface requirement definition must evolve with the design.

That said, it is imperative that there are no holes (e.g., no missing identification of interfaces with other systems, no missing definitions, and no missing interface requirements) in both your requirement document and the requirement document for those systems you are interacting with. I know this because I speak from experience. A case study I was involved with revealed that when integrating all the interface diagrams for the components that made up the system, on an average, there was a 40% mismatch!!   One component showed an interaction with another component, yet the other component did not show that it was interacting with the first component. This meant that for the overall system, 40% of the internal interactions had not been defined and the resulting interface requirements were missing.   It is not surprising that once the results of this audit were made known, the Lead Systems Engineer made the statement “no wonder we have so many integration problems!”

To make sure this doesn’t happen, it is important that you conduct an interface requirement audit of your system. I have performed such audits on numerous occasions and each time, the audit findings proved that the effort was time well spent. .

My approach to an interface audit is relatively simple, I start with a spreadsheet, create three columns and label them as: “My System”, “Definition” and “Other Systems”.

I then find an external interface diagram for my client’s system or draw one if one doesn’t exist. If done correctly, the diagram should show all the other systems the client’s system is interacting with and what each of the interactions are. There can be multiple interactions with a single system. Each interaction needs its own interface requirement and corresponding agreed-to definition.   Also, it is important to understand that to completely define an interface, three things must be defined: (1) what each systems looks like at the interface, (2) the characteristics of the thing crossing the interface, and (3) the media involved.

With this knowledge, I look through my client’s requirement document and pull out all requirements that even hint there is an interaction between the client’s system and any other system and put the requirement text in column 1 “My System”. If there is an interaction, there is an interface! Note – if there are multiple interactions between two systems and you find a single requirement that reads: “My system shall interface with the other system as defined in ……….”, you pretty much have a useless requirement as I don’t know what has to happen between the two systems to achieve the interaction! There should be at least one interface requirement (there can be up to three requirements) for each interaction between the client’s system and the other system. So word of caution – the word “interface” should not appear in an interface requirement as either a noun or verb as that word just adds ambiguity!

Next, I look to see where the interaction is defined and, assuming it is defined, I put the definition in column 2, “Definition”. Any well-formed interface requirement needs to include a reference to where the interaction is defined. It is also helpful to include a reference to the other system you are interacting with and thus have an interface.   If the interaction is not defined, I say so under column 2, and put the text in “red”.

Finally, I fill out column 3, “Other Systems”. This involves going to the requirement documents for all the other systems my system has an interface with as indicated in the external interface diagram. Ideally, the other systems will have the complement interface requirement to my client’s interface requirement. Also, this complement will point to the same agreed-to definition that my client’s interface requirement points to. If the complement does not exist, I flag this in “red” in column 3. If the requirement points to different definition, I flag this as a problem, in “red” in column 2.

It is important to look at the interface diagrams and resulting interface requirements in the other system’s requirement documents to see if they may have identified an interaction with my client’s system, yet my client did not indicate that interaction and thus did not have a complement interface requirement in his/her’s requirement document – a missing interface requirement! When this happens, I mark this error in column 1- in “red”.

Now the fun begins!! When looking at the results, there will be a lot of “red” in all three columns!   These indicate problems that need to be looked into and resolved. This is what makes the audit worthwhile. You don’t want to wait until you start integration activities to find that you have these problems – the impact to cost and schedule can be significant.

I go into a lot more detail on managing interfaces in my paper “Everything you wanted to know about interfaces, but were afraid to ask.” I presented this paper at INCOSE several years ago. I will send a copy to whoever wants one. Just email me directly at: info@argondigital.com

Comments to this blog are welcome.

If you have any other topics you would like addressed in our blog, feel free to let us know via our “Ask the Experts” page and we will do our best to provide a timely response.