I am sure many of you have a range of requirements definition template documents that you use (or are forced to use for those landed with inappropriate corporate standard documents – you know, the ones where the first five pages seem to consist of health warnings, caveats and opaque quality clichés. Also, why do most of them proscribe obscure fonts or boring old Times New Roman?).
For projects that may well be delivered by Service Oriented Architecture (possibly using Service Oriented Analysis – see previous article), I would suggest that you may need to consider different or additional ways of documenting your requirements and specifications. The reason for this is that the way you shape your requirements needs to encompass both the holistic nature of SOA, as well as the new terminology and delivery mechanisms (see many previous articles on SOA).
Image © Joachim Wendler - Fotolia.com
I will describe below a set of documentation that is well suited to support SOA delivery. This approach also fits well with ITIL service management principles.
Inputs
Of course you will all be starting with an Approved Business Case detailing: Introduction with stated project / new service objectives, key assumptions, financial cost / benefit analysis, methods and assumptions made, risks and issues identified and recommendations. If not, you are in the majority, and you will have to gently tease out this information to give yourself a chance to succeed. Make sure this includes the Service Level Requirements.
Also of value at this stage is an Architectural Policies, Principles & Patterns Document defining the architectural principles and policies that should be either considered or adhered to in any architecture development or solution design. Patterns are standard reusable template solutions, jointly agreed, for an end to end service or part of (which may span components from multiple service vendors). This is where you may start seeing some differences both in terminology and artefacts in an SOA world. If the Architecture standards are not pushing SOA, you can effectively ignore the rest of this article as you are not being asked to deliver a Service based solution.
Another key input document is the Service Catalogue defining all of the services available for the business, from all Service Providers (both internal and external). This is where you can determine what is currently available as a service (Business, IT or Component service) to help build your solution. Be aware that most service catalogs out in the wild today contain only component services. There are some with composite IT services, but very few with full business services. Don’t let this get you down. Use what you have and push for improvements to the service catalogue.
Outputs
Something that may well be novel for you here is the Business Process Model, which describes graphically (i.e. with pictures, not luridly) the process and information flow required to meet the business requirements. It will show the inputs, outputs and transformations for each process step, and the potential service requests required, using existing services from the service catalogue, or specifying new or changed services to be developed or sourced. The process model is a powerful communication tool between the business users and the delivery function and in my experience is the ‘missing link’ of requirements documents. The process model can be enriched with meta-data describing the required metrics, known data models and transformations, roles and actors describing its use, and direct reference to existing services in the Service Catalogue or Registry.
In conjunction with this I would expect you to have to create a Service Requirements Document (SRD) to capture and communicate the detailed functional and non-functional business requirements.
The SRD will allow the High Level Service Design (HLSD) to be completed in conjunction with the Service Designers from your delivery function who understand the specific service oriented architecture available to meet the requirements. The HLSD will be used to define the specific service characteristics required for each service, along with the required Non-Functional Requirements (NFRs).
There are many other standard requirements and programme documents that you will almost certainly need, but the list above gives you some idea of the differences to be found in SOA situations. Of course, what you may be faced with in real life will almost certainly differ significantly, as IT still suffers from NII (Not Invented Here) Syndrome. Still remember the principles above and you will be fine!
Author: John Moe is Head of Business Integration at Tori Global, and writes and presents widely on SOA and BPM. With over 25 years experience delivering application development and business transformation programmes, John has made most of the mistakes you will ever make and is keen to pass on this knowledge to help you avoid them yourself. In return he just expects undying gratitude and free drinks wherever he goes.