Wednesday, April 14, 2004

Working with Enumerations in a Web Service within Orchestration 

Well, this had me scratching my head for some time until the lightbulb lit up in my brain! How was I going to call a web service within an orchestration that used an enumeration as one of its parameters?

The answer is surprisingly simple but very consistent with the way that orchestration works in BizTalk Server 2004 with respect to web services.

When you want to call a web service from within orchestration you can either do one of 2 things:

  • Write a wrapper in .NET that calls the web service and call the wrapper from within an Expression shape
  • Add a web reference to the BizTalk project and then create a configured port based on the web port for the web service

So, what's wrong with the first option? Well, you will need to write code for starters just to call the web service, and then once created, then you need to expose the web methods you require access to in order for them to be invoked from orchestration.

Here's the rub though: while this isn't a particularly desirable route to calling a web service from within orchestration, sometimes it's absolutely necessary that it is done this way. There are 2 very good reasons for this:

  • You don't want to go through the message box every time you call the service (which is what happens if you call the web service through a web port in orchestration).
  • More importantly, the web service interface uses parameter names that are on the XLANG/s reserved keywords list. That's right! You can't name a parameter anything and just get away with it when using that web service from orchestration! Therefore if you have no control over the web service interface that you're calling, you will need to create a wrapper in order to be able to call it from orchestration.

So, in most circumstances you'll probably want to go the second route. When you add the web reference into the BizTalk project in Visual Studio.NET, instead of a proxy class in C# (or VB.NET if that's your preference) being generated behind the scenes, a BizTalk Orchestration is created as the proxy. Cool!

But, what happens when the web service method that you're calling contains a parameter that is based on an enumeration? Fortunately, when the web reference is added, any enumerations that are exposed in the web service definition (WSDL) are turned into schemas that are available in the project under the web reference itself.

So, with this information to hand, all we need to do is to create an XLANG/s message based on the enumeration schema, populate it with the right enumeration value, and then pass this message as a parameter to the web method.

The following code snippet shows how this is done and is located in the Message Assignment shape that sets up the request message for the call to the web service. If you take a look at the sample code, this particular web service method expects 4 parameters, one of which is a parameter based on an enumeration (which I've set up with a call to the XmlIfy static utility method). In addition, I made the enumeration value field in the schema a distinguished field by modifying the schema that was generated automatically when adding the web reference to the BizTalk project. Don't forget, if you update the web reference, you will need to promote the field as a distinguished field again otherwise the project won't compile! Note that you also need to construct the enumeration message as well as the web service request message in the Construct shape.

notifyRequestMessage.address = registrationMessage.escalation.sendTo;
notificationType = BizTalkUtility.XmlIfy( "<NotificationTypeEnum xmlns='http://somenamespace/notify' />" );
notificationType.NotificationTypeEnum = "SMTPEmail";
notifyRequestMessage.type = notificationType;
notifyRequestMessage.subject = "My Subject";
notifyRequestMessage.content = "My Content";

Note: Whenever I work on a BizTalk project, I always have a utility library written in C# that allows me to perform various useful little functions like turning an XML document into a string, and a string into an XML document. Highly useful!

About the Author

You may be wondering who I am (or may not!), but I've been in the industry 16+ years working on a variety of systems from IBM mainframes as a CICS systems programmer, to developing on Unix and Windows based systems. At the moment, I'm currently working for a Microsoft Gold Partner in the UK called Solidsoft who specialise in systems integration using BizTalk Server. My position is generally dictated by what I'm doing, but normally as a solutions architect/consultant helping clients with their integration projects involving, yes you guessed it: BizTalk Server.

Disclaimer: all the views expressed here are my own and do not necessarily represent the views of Solidsoft Ltd or indeed any other company.