Posted by Viktor Grgic in the wee hours: April 5th, 2007
Requirements engineering and design of services that your company need to provide to other companies is quite different from reqs. engineering for an interactive website, or other systems where an actor is a real person. In case of B2B services, the actor is always another system. Mostly you also know who your actors / other companies will be, unless you are Amazon or Google.
These recommendations will give you some tools and ideas how to deal with requirements engineering and design of B2B services.
1. Use an iterative process for defining requirements, but don’t build and deploy services too quickly.
You will probably never get the quality requirements in one go after asking the customer “What are your requirements?”. Requirements for B2B services are also usually harder to gather than requirements for an interactive web application. It takes many iterations and workshops with the customers to cover all aspects and details.
Iterative software development is the way to go today, but having incomplete requirements when building and deploying a service could cause the following situations:
- one customer uses a service, while another wants almost the same service. You have several options: create another service, which is almost the same as the first one; create another version of the existing service and hope that the first customer wants to spend the money (without gains) in switching to the new version; convince/force the second customer to use the existing service. Besides, having multiple versions of the same service could have significant impact on your back-end systems.
- refactoring: adjustments are harder to organize because they impact two or more organizations.
2. A well defined ubiquitous language is crucial for proper requirements engineering.
Maintaining one set of terms and having everyone understand the same within one company when saying: “Vehicle object” is difficult enough. Having all your customers using the same definition is another level of complexity. Still, striving for ubiquitous language pays off really fast.
3. Understand the process at the customer side in which your web service will be used.
It is same as for any requirements gathering. Until you understand customer’s domain, the chances of getting quality requirements are slim. One way of understanding their processes is having them explained in a workshop. During this workshop the requirements for services will already pop up, but be cautious and ask “Why?” five times – as Tom Gilb would say. Sometimes it is better having the customer change their processes instead of making very complex services. You really want to maximize loose coupling across organizations.
4. Define a domain model for your services
This one is similar to ubiquitous language. Domain-driven design can be applied very well when defining services. It is a very powerful way of creating a common base and having everyone use the same concept.
5. Try to involve as many customers as possible in the first iterations of requirements gathering, but dive into details with a few that really depend on your services.
Consulting a limited number of consumers could put you on the wrong path and therefore unintentionally exclude other consumers. On other hand, getting all necessary details from all consumers (e.g. 20) is a daunting task, especially if most of the consumers cannot give you details right away. This is mostly because they don’t have a clear picture of their own processes and needs yet.
6. Use cases are good enough for describing interaction between the customer’s system and a web service.
Your system which provides services is just like any system, and consumers’ systems are actors. And there are also interactions. The only problem is that interactions can be very limited. E.g. “Actor sends the message X and….that’s it”. Your use case can also describe error handling and alternative flows. Nevertheless use cases alone are not enough. Here are some of documents I’ve come along:
- communication model where mainly interactions are described
- canonical, data or domain model where the objects/messages are described
7. Use asynchronous messaging rather than synchronous if no direct response needed (fire-and-forget).
Synchronous messaging (e.g. REST, SOAP) creates a direct dependency between two companies. Picture 20 companies all directly depending their IT systems on your services over the internet!
Asynchronous messaging brings you a number of possibilities to lower this dependency, but requires more development effort.
8. The complexity begins with details which must be implemented and are often underestimated.
It always looks simple in the beginning. “We’ll send you these objects according to this XSD whenever objects change or are created. How hard can it be?!” Some overlooked ‘details’ are: application level acknowledgment messages, records locking when message order gets out-of-sync, message tracing, ‘correction’ messages when nothing really changed but someone made a mistake, repeated messages. Most of these have to do with situations when something happens that is not part of the normal flow. A good resource for solving these problems is the book Enterprise Integration Patterns, Hohpe and Woolf.
9. Make a template which helps describe each of your services in all details.
I’m not really a fan of all kinds of templates. But in this situation a template brings you very important consistency between services, especially if you have many services. The people concerned with defining these services shouldn’t be IT people. At the same time, these designers find such templates very useful in order to know what answers IT needs before implementing a service.
The most important information in the template is the exact name and the purpose of the service and definition of transfer objects (input and output)
10. Use application level acknowledgment messages in addition to the out-of-the-box messaging protocol.
Confidence of your customers that you will provide high quality of service is important. But when something goes wrong, you’ll want to be able to prove that nothing went wrong on your side. Having application level acknowledgment messages does not solve this problem completely, but helps a lot.
The conclusion is that you really need to think first before starting the implementation, because the impact later on is huge. The consequences of bad design are mostly manifested during the maintenance where request-for-changes look more like a redesign of the system.
