When building an infrastructure-type system like an ESB, often the architects and developers tend to naturally focus on the technical challenges. Ultimately, they reach a point where the code is done, functionality is complete, all unit tests pass, and everything has been deployed into production. Then an email goes out letting everyone know that the project goals have been met. We’re done, right?

Most of the time, I would say no, we are not done. Infrastructure services generally are not a case of “if you build it they will come”? Maybe, but not likely. Developers are creatures of habit. They get used to doing something a certain way, and stick to it. When deploying something like an ESB, you need to educate them. You’re deploying powerful capabilities, but the team needs to understand the implications and benefits in order to ensure adoption. With adoption, organizational benefits will be realized. Without adoption, you’ve just wasted a lot of effort.

For the project I am on, as part of our rollout, we are doing “brown bags” where people can learn about what the ESB is, and what it means to them and their applications. This is a great start and a great way to “socialize” the technology, and raise organizational awareness of infrastructure services.

However, I felt the need to provide developers with something more, something that would guide them and ease their adoption of ESB capabilities. Something that would continue on after I rolled off the project. It was this thinking that lead to the Core Engine SDK.

The Core Engine SDK will consist of:

– a naming conventions document
– sample programs
– a “Developer’s Guide to the ESB Core Engine” (more details later in this post)

Naming Conventions: what’s in a name?
Experienced BizTalk developers do all their work in virtual machines. In that isolated world, it doesn’t matter what you name things, if there are collisions or conflicts you’ll be able to figure them out. You’re likely only working with a small amount of artifacts. However, once you deploy into staging/production environments, your solution enters into a shared environment. In a large organization with a lot of BizTalk artifacts, a structured naming convention is required in order to ease management of the environments. Without one, chaos will ensue.

So, I created a naming conventions document that is based on best practices gleaned from past projects and other projects done by people I know. The resulting naming conventions document something that developers need to follow. In fact, although it may seem draconian, they MUST adhere to it or their application will not get deployed. Compliance to the naming conventions is a key part of the “on-boarding process” we will be implementing. I will do a future post on what I see this process as being.

Samples: show me how it’s done
The sample programs are examples of how the ESB Core Engine capabilities may be used in a solution. Knowing that the target audience will be BizTalk developers, these samples will follow the model of the BizTalk SDK in that they will have setup/cleanup batch files to quickly get a sample running, and to quickly remove it. We are creating a business scenario that will be used across all the samples, the idea being we want a readily understood business-specific scenario so developers don’t waste cycles trying to grasp some made-up business need, and focus instead on the techniques being shown. Our goal is that the samples will be very function-focused, each sample will address one (and where possible only one) aspect of something an application may need to do with the ESB.

As an example, I am writing “The Ultimate Handler for ESB Exceptions” (future post coming here, it is sooooo cool), but the first SDK sample will be how to write a highly targeted exception handler. This will show developers how they can incorporate our exception handling mechanism into their applications.

The Developer’s Guide: tell me what I need to know.
A project the scope of the ESB I am on will of course generate a bazillion documents and diagrams. However, in my opinion, one of the key documents, and in fact one of the keys to the success of the whole project, is the document I created for the developers and architects charged with building applications that will run on the ESB. I can’t post the document (of course!), but I thought posting the table of contents would at least show the sections that I felt it was important to address. This is not documentation for the ESB itself, that’s a whole other document aimed at developers who will be maintaining and extending the ESB. This documentation is targeted at the *users* (developers) of the ESB.

In the following listing, I have replaced the client’s name with “xxxxx”. I have left page numbers in so you get a sense of depth.

Introduction 4
– Overview 4
– Target Audience 4
– Revision History 4
Introduction to the xxxxx ESB 5
– What is it? 5
Introduction to the ESB Core Engine 6
– What is it? 6
– How is it architected? 6
– How should you architect your BizTalk solutions? 7
Working with the Iteration 1 xxxxx ESB Core Engine 8
– Functionality Provided 8
– Scenarios 9
Getting Started with the Core Engine 11
– How it works 11
– Installing the ESB in your virtual machine 11
– Installing the CtxSetGeneric Pipeline Component 12
– Installing the JMS Pipeline Components 13
Developing BizTalk Solutions with the Core Engine 14
– Naming Conventions and Rules 14
– The ESB On-Ramp: Receiving and Creating Messages for ESB Processing 14
— Using the CtxSetGeneric Pipeline Component 15
— Using a Property Schema 15
— Getting access to ESB Metadata Properties by Assembly Reference 17
– The ESB Off-Ramp: Creating Subscribers 19
– Working with JMS Messages over MQ Series 21
Dynamic Mapping 23
– Overview 23
– Order of Selection 23
– Dynamic Mapping Errors 23
Exception Handling 24
– Overview 24
– Core Engine Exception Handling 24
– Creating Custom Exception Handlers 24
Core Engine Roadmap 26
– Overview of Iteration 2 and beyond 26
– Protocol Hops 26
– Defined Processing Steps 26
– Increased Map Selection Capabilities 26
– Enhanced Exception Handling 26
– “Per instance” Receive Location Control 26
Appendix 1: ESB Metadata Schema 27
Appendix 2: Exception Message Schema 28

Many developers hate writing docs, but if you’re on an ESB project, the table of contents shown above could serve as a valuable guide to creating an effective and easily understood way to get developers up to speed and using the ESB.

Now all you have to do i