Documenting the Interfaces

  • Strategy – High level scope of what interfaces are needed and their intended purpose. In order to establish this – an as-is and to-be system landscape is needed. Also intermediate system landscapes may be needed in case there is a transition period. The transition period may drive the need for additional intermediate interfaces as well. For SOA interfaces the source system may be unknown or multiple known. At strategy level business object complexity, prerequisites, frequency and volumes must be known in order to drive the Plan. Frequency may be driven by business events especially when its a SOA interface. This document is produced by the interface manager and must be signed-off by high level management like CIO and/or CFO and interfaces impacts business performance and controls like Sarbanes Oxley.
  • Plan – Estimate in time and money based on the above Strategy including dependencies between interfaces where prerequisites must be in place. This document is produced by the interface manager.
  • Functional Specification – This specifies how to interface and both manual and automated processes must be described. A process diagram may be helpful at this point indicating the intended business process. The functional specification should also sections on security and controls and how to implement these. With point to point interfaces this is normally a reconciliation of the transfer and/or regular balance check and with SOA interfaces this is typical a handshake returned to the originating system. This document is normally produced by an functional consultant.
  • Technical Specification – Specification of how the above deliverables will be produced. This may include pseudo code, flow charts and entity relationship diagrams. This document is produced by the developer or development management.

All of the documents above mainly specify functional information. Of course some technical input may be required – however the main focus is on the functional approach and the technical part is business as usual.

Except for the Technical Design all the above documents should be owned by a functional person  – ideally an experienced person that can engage top management as well as obtaining the technical information required.

The above documents will be described more detailed in a later post.