Friday, January 2, 2009

Integration Projects Usual Madness

Joel Spolsky wrote a classical article about writing better code. The 12 Joel's rules are below summarized:
  1. Do you use source control?
  2. Can you make a build in one step?
  3. Do you make daily builds?
  4. Do you have a bug database?
  5. Do you fix bugs before writing new code?
  6. Do you have an up-to-date schedule?
  7. Do you have a spec?
  8. Do programmers have quiet working conditions?
  9. Do you use the best tools money can buy?
  10. Do you have testers?
  11. Do new candidates write code during their interview?
  12. Do you do hallway usability testing?
EAI projects pose additional serious challenges in terms of project management and quality assurance. Even if the term "EAI" seems to be out of fashion nowadays, I think the majority of projects which have been labelled as "SOA efforts" are, in facts, still plain, old EAI.

EAI Quality Assurance and Testing

Especially when doing EAI, unit testing is not enough. Joel is in favour of developer's unit testing and personally I think using a tool such as JUnit can prevent a huge numbers of bugs, but unit-testing integration flows is often much harder than unit-testing regular applications. This is due to the fact that when implementing EAI it is necessary to deal with a multitude of external systems which are out of our domain of control. Mocking those systems is often very hard or even impossible, it could lead to write and maintain more mocks than actually manageable and, additionally, the quality and realism of those mocks could be at least questionable.

Testing activities for EAI teams is a matter of organization and operations, because often it could be a cross-department issue. For example, testing SAP BAPI interfaces requires some commitment and lot of assistance from the SAP team, which in the meanwhile could have different priorities. The same for other legacy technologies. This clearly scales to a management issue, the EAI team has to be allowed to orchestrate the testing and validation process with all the involved external parties. Cross-department activities are usually difficult for organizational reasons, not much for technical ones.

Critical Success Factors

While at SeeBeyond we had some specifically integration-related rules, which were useful to establish what we called "Critical Success Factors":
  • The executive sponsorship must be established up front to facilitate timely decision making, appropriate resource allocation and removal of business barriers.
  • Establish an integration team with a balanced mix of IT, end business, management and consultants who will work together toward the main goal of a successful implementation
  • Provide just-in-time training and coaching to the appropriate people on operation of the product components, keeping them ahead of the learning curve,
  • Field level buy-in to the implementation is critical to the success of the project
  • Executive management must communicate their commitment to the new technology and illustrate this commitment through their actions.
  • Availability of key stakeholders to facilitate the decision making process and to keep the implementation moving forward.
  • A complete test and validation plan should prepared in advance. It is not up to the single developer to validate his own work, QA is an overall function.
  • As this is an integration project, all interfaces must be defined before starting the implementation.
  • Changes have to be accommodated into a change management process which takes care of the deadline. All the interfaces should be unit-testable and end-to-end testable as being part of a higher level process.
  • Implementation will proceed by very short iterations of analysis, design, development, test and deployment. At the end of each iteration a working prototype should be ready to run functional validation tests.
Regarding SOA, reports say that most SOA initiatives are failing because of inadequate business involvement and commitment. EAI is a better understood discipline (really?), but still projects tend to fail for exactly the same reason as newer SOA efforts.

Missing Deployment Plan

Just after the functional specs and scope, it is important to define a Deployment Plan and a Deployment Architecture:

"The deployment project plan establishes a baseline reference plan. It is your road map for the deployment project. The roles and responsibilities of each organization, the schedule of tasks, and any estimates must be defined in this plan.
Deployment Architecture (DA), together with Requirements Analysis, is the most important component of your plan, and should be documented carefully. Deployment begins when you plan and schedule how, in view of your analysis and allocated resources, you want to implement your environment. During this phase, you set up the operation procedure and schedule for the entire deployment project. DA provides guidance to the successive design and implementation phase, so DA creation always must precede it. In fact, developers needs to use the DA document as a guide for implementing their flows, adapting services communication to the DA. Of course, sometime it is necessary to adjust the DA to accommodate design needs emerging after some development, but if this happens frequently then it is a sign of a bad original DA, so it is time for a deep review.
Poor analysis and planning can cause major problems during the later phases. Thorough, comprehensive analysis and planning can make the deployment project easier, more efficient, and less costly.

The above is a mix of statements from the Java CAPS documentation plus some comments of mine.

Organizational Issues

In my experience most of the issue I have encountered during Integration projects are organizational and operational:
  • Lack of organizational information
  • No complete specifications
  • Not enough back-end information to fill the specifications
  • Lack of coordination
  • Frequent changes in project organization (document store moving, too many documents everywhere, anonymous doc.)
  • Huge integrations are thrown to single developers
  • Lack of commitment
  • Sometime is difficult to understand who is in charge
  • Developers are frustrated by changing deadlines
  • Bad or totally missing test data!!!
Missing Domain Model

You wouldn't write SQL queries before modelling any database relationship, would you?
An usual requirement for Services is to build first a Domain Model as a common, business oriented standard communication device. This is very close to good Object-Oriented programming practices, but Service-Oriented is focused on exchanging documents instead of objects. A domain model can be designed by normal entity-relationship diagrams and, for example, implemented through XML-Schemas.

Common Misunderstandings

  • Integration projects are like software development projects
>> No! they are very different!
>> Integration projects are cross-department projects
>> Need more involvement
>> Need more cross-management
  • Bugs in software are all the evil
>> No! Half of bugs are not real platform's bugs but behaviour due to bad design/assumption.

Integration project with any vendor will fail if there are no clear specifications...

Inter-team communication madness

  • Every team has its own life
  • Not coordinated at all
  • No motivations to help
  • Mostly Anonymous functional and technical documents !?!
Finally... Some Recommendations
  • Long term strategy but short delivery cycles
  • Top-down, business-driven analysis
  • Short iterations, deliver value within few weeks
  • Break big projects into smaller pieces
  • Stick to deadlines! Avoid changing a deadline!
  • Instead, what features can fit into the deadline?
  • Adopt a Project Management methodology!
Some of the above statements could seem controversial. What about deadlines? there is nothing more frustrating for a developer than working 80 hours per week, weekends also, just to discover that a couple of days before deployment some manager decides that the feature is not really that important and can be delayed. Boy, you are not going to catch me anymore! So my advice is: fix the deadline and instead move in and out features, keep the pace, sustain the mood.

Always ask ourself why? "Why?" is extremely powerful: before start fighting to solve a technical issue one should ask why I'm doing this? Is there any better, cleaner design which could alleviate or even cancel the technical issue? Do I really have all the necessary information? Am I answering a question nobody asked for?


Integration projects are somehow quite different from application development projects:
  • Interfaces and meta-data must be clearly defined
  • Service contracts must be defined (SLAs)
  • Test data must be readily available!
  • External systems experts must be available!
  • An architectural board in charge of taking decisions needs to be established.
It seems that the above list is exactly what we need in case of any project, application development or integration. But badly-managed dependencies with the external world can sink any integration project regardless of how good is the team and its internal process. Integration is about connecting existing interfaces: what can I do if interfaces are fuzzy and undefined? Frustration, that is....

Thanks goes to my friend Juraj Kazda of Sun, for discussing and writing down these issues while working together in several projects.