OpenEAI Methodology

Owned by Stephen Wheat
Last updated: Nov 03, 2012Version comment
6 min read
Copyright © 2005–2012 OpenEAI Software Foundation.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Section being the first section entitled "Introduction", with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "Appendix 1: GNU Free Documentation License".  

Contents



Introduction

 
The purpose of the OpenEAI methodology is to bring order, discipline, and transparency to the practices of integration analysis, development, testing, and project management. While the OpenEAI methodology, analysis template, and related artifacts are tailored around some of the specifics of the OpenEAI concepts and technology, many aspects of this methodology add value to any integration project using any concepts and technology. The OpenEAI project encourages organizations to adapt the methodology and artifacts to their practices and technologies and appreciates feedback and suggestions to make the OpenEAI methodology more generally applicable and useful in a wide range of applications. 
 
Note that a number of different names can be used to refer to the defined discrete units of business data used to conduct enterprise messaging transactions: Enterprise Data Objects, Enterprise Message Objects, Enterprise Business Objects, and so on. In the introduction and overview, we'll simply use the term "enterprise objects" to refer to these business data objects.  

Perform Analysis

 Identify, in general, the systems that need to be integrated. Once those are identified, an analysis group comprised of business or functional experts and technical integration analysts complete the OpenEAI analysis template, or their organization's customized version of the template, for each application that is to be integrated. Among other things, the template:

  •  documents general integration requirements  
  •  identifies which new enterprise objects will be required 
  •  specifies which existing enterprise objects will be used  
  •  defines the structure of new enterprise objects  
  •  specifies which message actions of the OpenEAI Message Protocol will be required for each enterprise object  
  •  enumerates the messaging applications, gateways, and infrastructure that must be developed to implement the integrations, and  
  •  enumerates detailed message production and consumption logic   

Define Messages

Define any new enterprise objects needed and the message actions they require through the process of completing the OpenEAI analysis template. Technical integration analysts can then create XML message definitions for each of the new messages and their message actions and slot them into the organization's message hierarchy, and provide a sample message for each definition. This process allows organizations to share message definitions and communicate about them effectively internally and with trading partners. For more background on defining and sharing OpenEAI message definitions and enterprise object documents, see the OpenEAI Message Definition Document.

Generate Message Objects and Related Artifacts 

 Next, the message definitions are implemented as Java objects. A Java object must be created for every complex enterprise object defined. These Java objects are automatically generated using the OpenEAI MoaGenApplication, which also generates their corresponding enterprise object XML documents. This step is typically performed by EAI analysts, who should be well-suited to complete the enterprise objects documents with the appropriate rules based on the outcome of their EAI analysis. For more information on the Java message object API (MOA), see the Java message object section of the OpenEAI API Introduction Document. 

Develop, Document, and Test Messaging Applications

The details of this phase will vary from organization to organization: many organizations already have application development and testing practices established. However an organization chooses to implement them, the following guidelines should be considered.

  1.  Developers and analysts prepare detailed, technical stories for each messaging application and gateway listed in the completed analysis. These stories will draw heavily on the message production and consumption logic prepared by the subject matter experts and analysts included in the analysis template.
  2.  Developers implement the appropriate messaging applications and gateways listed in the template using OpenEAI foundation components, the message object API that was generated for the organization's enterprise objects, and the enterprise object documents completed by the subject matter experts and analysts. When developing an OpenEAI-based application or gateway, this means developing the commands needed to support the processes defined in the analysis. 
  3. While steps one and two above are proceeding, integration analysis staff can prepare OpenEAI TestSuiteApplication test suite documents for testing the message gateways that are to be developed. Test suite documents are XML documents made up of messaging test cases. The OpenEAI TestSuiteApplication can take a test suite document and execute all its test cases very rapidly: it sends test messages to a target application and compares the replies received and sync messages published by the target application with expected results, produces a detailed report, and can even tear-down any messaging artifacts or database entries created as a result of the TestSuite execution. Subject matter experts and analysts are typically the best equipped to prepare these test suite documents, because they are the people who know the business logic and they also specified the integration requirements, message production logic, and message consumption logic. Developers can perform this work, but if they do, the subject matter experts and analysts should review the test cases and certify they represent the requirements. It is useful for developers to have these test cases available to them during the development process. As they implement message support they can iteratively execute the test suite using the OpenEAI TestSuiteApplication to check their progress. As developers make changes they can use the test suites to verify they do not break any required behavior.  
  4. At this time, subject matter experts and analysts also prepare real-world online and batch scenarios to test the new messaging applications and gateways in combination with the rest of the messaging enterprise in a test environment. 
  5. All messaging applications and gateways pass both informal developer testing and all of the formal test suites executed using the TestSuiteApplication.

Update Documentation 

Practicing the OpenEAI methodology produces a number of documentation artifacts, including an analysis template for each application that interfaces with other applications, enterprise object definitions, message definitions, and javadoc for applications that implement support for each enterprise object. These artifacts should be posted in a web-accessible format. For example, message definitions and enterprise object documents should be posted on a web server so messages can be validated when necessary and so field-level business rules and translations can be applied by the Java implementation of the message objects at runtime. This practice allows you to build a web page to nicely document each messaging application or gateway, linking to and leveraging each of these artifacts that must be created anyway to support XML document validation and enterprise object validation. One example of how an organization can present this documentation is Emory University's EAI and SOA Overview Documentation.

Just as your organization may customize the analysis template or the OpenEAI methodology itself, you will likely choose to customize the web documentation template as well. This web documentation can be posted on your organizational web site or intranet. Posting this documentation helps managers, functional analysts, and technical analysts plan and prepare for new integrations. Additionally, many organizations have auditing or best-practice requirements that mandate the preparation of some type of formal documentation for each integration. Posting this documentation as a web page makes this information available to those who need it. In some cases, it can even be helpful to complete and post most of the template prior to or during the development phase.

Deploy in Production

There's not much to say about this step from an overview perspective, since if you get to this point, most of the work has already been done. If you follow the recommended OpenEAI practices for testing in pre-production environments, deploying in production should be anticlimactic. The OpenEAI Deployment Patterns document provides details on the minimum number of recommended environments you should set up for a messaging enterprise and how and when to promote messaging applications and gateways from one environment to the next.

Tracking Progress along the Way

 Two major risk categories inherent in integration projects are "real" and "perceived" failure. There are many ways to fail when integrating complex systems. The best way to avoid failure, or even the perception of failure, is to track progress and manage changing requirements, expectations, and timelines. The single most important benefit of a structured integration analysis template is that it breaks work into discrete tasks for which status can be recorded in the template and tracked by integration project managers in their overarching project plans. The OpenEAI integration analysis template supports this tracking and reporting by encouraging integrators and analysts to identify resources, estimate work, and set goals for every step along the way. These goals can be noted and tracked by project managers who can help escalate deficient resources or accelerate lagging progress before they become blocking issues or high risks for the integration project or the larger project under which this integration work is occurring. 

The OpenEAI Integration Template 

 The OpenEAI Project maintains an integration analysis template to serve as a recommendation for your organization. The template is available on this wiki and may be exported for customization and use in your local setting.