Geeks With Blogs
Jennifer Zouak JENNIFER · ZOUAK's · BizTalk · and · .NET · column
As an intro, I have been building a BizTalk 2006 adapter ( starting from the new framework and base adapter code. The adapter is a transport-type adapter.

One of the initial challenges was wrapping my head around the property definitions. With BTS, each adapter has two types of properties: Handler and Location (aka Port). In addition, at runtime there is the message content itself and the message "Context" properties which can be considered.

Once you add an adapter for use with BTS, the Handler properties are configured on the adapter for each of Send and Receive. These Handler properties are then global for all instances of the adapter. It is interesting to note that they will also be shared across all BizTalk "applications" (an application is a named grouping of artifacts) and throughout your cluster.

In contrast, the Location properties are configured on an individual port. Therefore, each port can have a unique set of values. Keep in mind that ports can also be dynamically created using an url known as the port's address.

Finally, with each message that is processed, there is the message content which can be a source of information to the adapter, as well as the message context. (TIP: messages received using the PassThroughReceive pipeline do not have a message context).

The adapter I have designed uses over a dozen properties when transmitting a message. Depending upon the subset of the transport protocol which is desired, there is a slightly different subset of properties needed. This at first seemed quite complex. For all messages, there are shared properties for the message destination, the priority, the method of delivery, acknowledgement, etc. So the problem was to decide which properties would be global, with the remaining properties configured on a per-port basis. In addition, I wanted to be able to override some items depending upon the individual message being processed, so I elected to use Context properties for this.

Another option I considered was writing a slew of adapters, one for each major subset of the transport protocol. This quickly would have resulted in loads of duplicate code with no clear added business value, so I junked it and made very robust property validators.

So here are the results:
Handler: remote server URLs, Licensing, Performance characteristics, Error handling, Languages and encoding
Location: choice of subset protocol and all properties related to these subsets, behaviour-specific properties such as timeout
Message Content: no dependency
Context: items likely to be variable such as message id, message destination, priority, content and timeout

Some of the key decisions were:
Message Context is optional: A message could be successfully transmitted based solely on the Handler+Location properties. This means that the context is not required and direct port-to-port messaging can be supported.

Message content is ignored: By being able to ignore the message content, I remove the need for an XML schema for the port. The adapter can literally be fed any stream of data and it will faithfully transmit this data. The setup for this would be to configure port-to-port messaging with no orchestration and use PassThroughReceive and Send pipelines.

Handler has minimal properties: The more properties the handler contains, the less flexible the adapter ends up being. Take for example an Enterprise deployment of Biztalk. There would be one biztalk instance shared by several departments and supporting many running applications. The Handler properties would need to make sense for all these applications and future applications as well. I decided that the handler should contain data that would be unlikely to change, plus the performance management characteristics of the adapter.

Dynamic Ports not supported: There are so many properties that I decided that trying to elaborate them all in a single URL/string format would be cumbersome and not very useful. Most scenarios with dynamic ports can be accomplished by setting the context properties. But still, if any customer asks for this features, I will definately add it.

Aside from property types, there is another thing I'd like to highlight. Properties can have "default" values and also can be "nillable". Be warned -- these two items are easily counterproductive.

Default values -- when you first install the adapter or create a new port, and you bring up the property pages you will see the defaults populated into the form. This is great to help along new users. The problem comes when a user clears a value that has a default. The user sees an empty value then closes the property page. Behind the scenes the engine goes --"Hmm a blank value! I know, I have a default, I'll just use that one instead LOL!" and so we have potential user confusion. And of course, when the user re-opens the property page, they will see the default value again. If you are going to use a default, then use it for selections (drop downs) and items that are no-brainers. If a propety is required, do NOT apply a default value as this can make it pass validation without the user entering any value.

Nillable values -- ok, so here it is: Only string type values are truly nillable. Second, the way to nill a value is to click off the value editor box, then right click on the value box and use the context menu to clear the value. Simply erasing all the chars in the value editor and hitting enter will bring up an error message. Third, for me, some of the properties can be empty and this is a valid state. For example, a property "Priority" may be neither or high/med/low, is it simply not set and therefore we want the destination system to apply its own default. To accomplish this, I create a selection type and have 4 valid choices "0-nothing", "1-low", "2-med", "3-high" with a default value of "0-nothing". Fourth, date/time types are not nillable -- use a string and then validate it for date format (the validator api is trigger when user clicks OK/Apply).

Posted on Monday, May 29, 2006 7:49 AM BizTalk Adapter Development | Back to top

Comments on this post: Defining BTS 2006 Adapter Properties

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

Copyright © Jennifer Zouak | Powered by: