Geeks With Blogs

News View Michael Stephenson's profile on BizTalk Blog Doc View Michael Stephenson's profile on LinkedIn
Michael Stephenson keeping your feet on premise while your heads in the cloud

I have been wanting to talk for a while about the approach we take to analysis of an application we are about to integrate with. In the past I have seen a lot of cases where analysis is undertaken by looking at the interface specification documents from an application vendor and then taking their contract (which hopefully is standards based) reading them numerous times and then we plough into the development. The big problem with this is that we make a number of assumptions about the application and its interface which could significantly affect our development if these assumptions prove to be incorrect or we have missed something.

One of the approaches I like to take is to understand the contract but to also consider the behaviour of the interface as much as the contract. I want to also test my assumptions and interpretation of how this interface will work. To do this I like to use SpecFlow which you may have seen me blog about on a number of occasions. As part of the analysis phase I would develop some tests using SpecFlow and visual studio which will describe the behaviour and assumptions we are making about how the application will work. You could imagine a scenario like the following:

Feature: Load a Journal Message into Peoplesoft

So that

I can Participate in the journal integration process

As a

BizTalk Application

I want to

Load a journal message into Peoplesoft

 

Scenario: Normal Case

Given

Peoplesoft is in a normal state

And

I have a standard journals message

When

I call the Peoplesoft API Journal Load

Then

Peoplesoft will accept the message

And

Peoplesoft will return an IBResponse message

And

The IBResponse message will contain a success status code

And

The journal will be in a processing state in Peoplesoft

 

Scenario: Invalid Journal Type

Given

Peoplesoft is in a normal state

And

I have a journals message which has an invalid journal type element

When

I call the Peoplesoft API Journal Load

Then

Peoplesoft will return an IBResponse message

And

The IBResponse message will indicate a status of FatalError

And

The journals message will be in a failed state in Peoplesoft

The above gives us a great yet simple and effective description of how we use the API.

A lot of the vendor API's I have come across tend not to go to this level of detail or it would often be buried in a huge documentation pack. What we want to do is extract this information and our assumptions about the behaviour of an API and how it relates to our requirements and present it in a simpler way. In some cases a feature we require may use two methods on an API so the above technique would be a good way to document this relationship.

Once we have defined the behaviour we expect from the API using the gherkin syntax and Specflow in Visual Studio we can then implement code behind each of the Gherkin statements which will implement this step. Suddenly we have some acceptance tests which will validate our assumptions that an application API behaves the way we expect it to. By doing this early in the analysis phase of your project you can save yourself a lot of problems later on by reducing the risk that your assumptions are incorrect.

The output of this approach is that we will have the following:

  1. Lightweight documentation of how we will use the API and what we expect it to do
  2. Tests which prove the API does what we want and can be used for regression testing

     

Real world Example

Now on to a real world example where this approach proved to be very valuable. At one customer I have worked with there was an application where we had used BizTalk to integrate with it. The customer also had 5 other legacy applications which integrated with it directly in a point to point fashion and not via a broker so they were tightly coupled to the application. There was a project to upgrade this application which the vendor had told us would be fully backwardly compatible and that none of our applications would be affected but the vendor did supply a new version of their interface specification which was a 50+ page document. All of the legacy application teams impact assessed the upgrade based on the interface specification and said that they would not be affected. We took a different approach. I told the project team that we would run our behaviour tests against the new version of the application which had been installed for a proof of concept. This would tell us if the application was backwards compatible. Based on the results of the tests we would then know how much detail we needed to go into around the interface specification and how risky we would view the upgrade to be. When we ran the tests surprisingly half of them failed with significant failures.

At this point we engaged with the vendor and begun to go through the test failures. We quickly found out the problem which the vendor replied "Oh you do it like that". It turned out that the vendor had architected part of their product and a feature which the BizTalk and all legacy applications mentioned above used had been removed from the product. The issue was dealt with from there and the solution isn't really relevant to the context of this post, but hopefully you can see the key point that without this approach the customer would have gone a significant way into this upgrade project and spent plenty of money before realising that they had a major compatibility problem whereas within 10 minutes of starting our impact assessment we identified this problem because the tests failed.

Needless to say the vendors backwards compatible statement wasn't accurate and their interface specification had been poorly maintained.

This approach can be can be used for simple or complex stuff and doesn't require a lot of investment but can save you a lot of time in the future.

Posted on Thursday, February 23, 2012 1:11 PM BizTalk | Back to top


Comments on this post: Considering the behaviour of your dependencies and not just the interface to them

No comments posted yet.
Your comment:
 (will show your gravatar)


Copyright © Michael Stephenson | Powered by: GeeksWithBlogs.net | Join free