Integrating applications: Bridge the gap with a functional specification

So you need to connect an application to an external system. Developers and IT architects know how to cover the technical side, with for example SOAP web services, REST APIs, or stored procedures. But there is more to integration than just a choice in technology. You also face a functional challenge: the relevant functionalities of multiple applications must seamlessly fit into each other.

Our advice? Write a functional specification for each integration point and use this as a basis for technical implementation.

An integration point is a touchpoint between applications: the junction where they have to cooperate to achieve a specific goal.

For instance, your billing application has to retrieve address information from the customer application, in order to print the correct address on invoices.

How do you write a functional specification for such an integration point? Start by answering three basic questions: Why? What? How?

1. WHY are you integrating?

Clarify the purpose and the context. An integration point is part of a bigger story: it will help to automate a step in a business process. Make a high-level overview of this business process, highlight the relevant step, and explain why the integration point is needed to automate it.

Also, write down a few specific real-life examples. These will help to explain the business process in concrete terms.

On May 2nd we calculate Alex's cell phone usage for April. We generate an invoice including his full address: Kerkstraat 234, 2000 Antwerpen, Belgium. The invoice is sent to this address. Finally, we collect the payment by asking Alex's bank to withdraw the money from his account.

2. WHAT data are you exchanging?

An integration point is about exchanging information. Application A is the central authority for all questions regarding a specific domain. Application B (or C, D, E ...) can ask a question to application A by sending input data (= the request). Application A answers the question by sending back output data (= the response) in a specific format and with a specific meaning.

• The customer application is the central authority for address information.
• The billing application sends a request to the customer application, asking for somebody's address.
• The customer application sends back a response containing the address information.

You will need a detailed understanding of the data that is exchanged. Start with an information model of application A's domain (or part of it). Such a model groups data into concepts that make functional sense and shows how they are linked to each other.

This basic model shows how Address information is represented in the customer application. It contains two concepts: Person and Address. A Person has an identification number, a first name, a last name and date of birth. A Person can have one, zero, or multiple addresses. An Address has a street name, house number, mailbox number, zip code, city and country. Furthermore, an Address can be somebody's official residence, or their correspondence address.

Here, too, it is a good idea to describe real-life examples that illustrate your model.

Once you understand application A's domain, you can identify the input data that have to be provided when asking a specific question.

When the billing application wants to retrieve address information for somebody, it has to send a request containing his or her identification number.

In the same way, you can define the format of the response that will be sent back.

When the customer application answers a request for address information for somebody, it sends a response containing the identification number of the Person, and all of his/her known Addresses.

3. HOW will you deal with each possible scenario?

The devil is in the detail. For an integration point, the standard scenario is easily identified. You send customer information, you get back an address. But what if things do not go according to plan? You need to identify the alternative scenarios that deviate from your standard flow. Ask as many 'what if' questions as you can think of. Go through your list with real-life examples to find cases that are slightly different.

• What if a Person has two Addresses? Which one will be used in the response and printed on the invoice?
• What if a Person has no known Address?
• ...

When making this exercise, also think of possible error situations. Unlike the cases above, these are scenarios where something goes wrong. This means that the request will never result in a valid response.

• What if the customer application is down and does not respond to requests?
• What if the billing application sends an invalid identification number?
• ...

Decide and document how you will handle each of these cases. Where necessary, add extra data to the model of the response (e.g. an error message).

• When there are two Addresses, we use the most recent one.
• When there is no known Address, a manual intervention will have to correct this.
• When the customer application does not respond within 5 minutes, we wait one hour and then try again.
• The customer application will check if the identification number is valid. If not, it will send back an error message.
  

Three final tips

Asking why, what and how will get you started with your functional specification. Here are three more tips to consider before making it final:

• Talk about it. When applications need to communicate with each other, so do the teams behind them. Ask them for input, and have them validate your specification.
• Test it. Is your information model correct and complete? Have you covered every possible scenario? The only way to be sure is by testing. Test as much as possible, as early as possible to avoid unpleasant surprises later on.
• Publish it. Other teams might profit from your work or they might have valuable input for you.

Got a question about integration or want to discuss your project? Our integration experts are happy to talk.