Consuming webservices from within BizTalk

BizTalk 2006 allows some really good interacting with webservices. If it is a simple webservice, we can very well consume it by adding a reference to it and then consuming it using the orchestrations. Here are some interesting scenarios that I encountered when dealing with webservices.


Can I consume the service?

Although Biztalk offers fairly good support for consuming webservices, there are some considerations that might affect the way these interactions are developed. 

For instance, the Add Web Reference feature in BizTalk does not understand the import element in the WSDL. Multi dimensional arrays are not supported from within BizTalk & so on. An elabortate list of these considerations can be  found here.

In some cases, you might run into one of these limitations - most probably when using non .net webservices. There can be a couple of ways in which we can deal with this scenario. This webservice call can be either wrapped within a .Net component or a webservice that can in turn be consumed by BizTalk.


Using SOAP Headers when consuming the webservice

When consuming a webservice with SOAP headers, the headers need to be written to the context of the web request message. In order to consume these webservices from within an orchestration We need to promote a property with same name as the SOAP Header & assign it to the message context. To achieve this, create a new property schema with target namespace as Each root element in this schema must match the name in the defined SOAP Header. Also, each root element that corresponds to the SOAP header should have its "Property Schema Base" property set to "MessageContextPropertyBase". Setting this property ensures that the element is visible in the list of elements in the message context.

Once done, then this property can be used in the expression editor to set the property on the request message as -


myWebserviceRequestMsg(MyPropSchemaName.MyHeaderName) = "<?xml version='1.0'?> <MySOAPHeaderName xmlns='http://SOAPHeaderSchemas.MyHeader'> <HeaderInfo>abcxyz</HeaderInfo></MySOAPHeaderName>"


The myWebserviceRequestMsg can now be sent directly to the webservice along with the associated SOAP Header.


Using Webservice request & response messages in Mapper

Most of the times, you need to resort to transformation either for the request message - before sending to the webservice or the response message after recieving from the service. In atrading sceanrio, where the trader hosts the suppliers catalog, the orchestration would need to get the catalog from the webservice & then use the transformation to include catalog in the traders database. However, if you are thinking of creating the map directly by adding a new map, the mapper UI does not allow specifying the webmessages as source or desctination parameters.

To overcome this, we can simply use the transform shape to create a new map for us. Specifying the web response message as the input to the transform shape allows it to create a new map with the web response schema. So instead of creating a new map, just drop a transform shape in the orchestration, create two message - one with the web response schema & other of your destination schema. Open the transformation configuration page & just select new map option there. After specifying your source & destination message, a new map will be created by using those schemas.


Hope this alleviates some blues for anyone trying to deal with webservices from BizTalk.


Comments (13)
  1. Rakesh Kumar says:

    I am trying to set soap header using this method described in MSDN e.g.

    getting an error.

    myWebserviceRequestMsg(MyPropSchemaName.MyHeaderName) = "<?xml version=’1.0′?> <MySOAPHeaderName xmlns=’http://SOAPHeaderSchemas.MyHeader‘> <HeaderInfo>abcxyz</HeaderInfo></MySOAPHeaderName>"

  2. Sanket B says:

    What is the error that you are getting?

    Can you provide some more details?

  3. Amy says:

    Our Biztalk webservice is consumed by a Siebel system. Previously, we’re publishing the whole orchestration as a webservice.

    1. What’s the difference if we just publish the schema to a webservice instead of the whole orchestration?

    2. What changes are required in the Biztalk side and should there be changes in the way Siebel consumes the webservice now that it’s based on a schema, not an orch?

  4. If I get: “: The request failed with HTTP status 403: Forbidden.”. I guess it is the webService tha t is talking to me, but is there anything other i mights do to be accepted ?

  5. Sanket B says:

    Hi Eirik,

    As you rightly pointed out, HTTP 403 would be a HTTP status message when you request a particular webservice.

    This is much before even Biztalk would be in the picture.

    The problem here seems to be that the client who is accessing the webservice does not seem to have enough security permissions to access it.

    If you are using Windows Authentication on the webservice (can be set on the virtual folder from within the IIS) and you are calling the webservice using a .net client, you can try setting the defaultCredentials on the webservice proxy. This will allow you to pass the credentials to the webservice and get authenticated.

  6. Sanket B says:


    Given that the underlying schemas are the same, The webservice will emit a similar WSDL.

    However, whenever an orchestration is exposed as a webservice, the Operations specified on the Port surface become the operations within the WSDL. As opposed to when the schemas are published, the operations are are automatically generated. The only purpose of publishing the schemas is to ensure that artifacts outside of Biztalk have access to the schemas and the schemas can still be managed centrally for the entire solution.

    IMHO, The difference here would be the operation name on the ports. I would suggest that in order to trigger the orchestration from the Siebel, the orchestration should be exposed as a webservice rather than the schema.

  7. Nitin says:

    Great article. Works too.


  8. Quinton says:


    I followed the design guides and did a small sample project. All works well untill I try and reference a webservice that returns an array. The Array in the xml is a complex type(which is not supported).

    Any idea which type of collection will work with BizTalk?


  9. Sanket B says:

    Hi Quinton,

    Maybe this link can help you with your problem.

    If not, do let me know and I can try to help you with this.

  10. Hari says:

    I need to consume a web service from BT Orchestration.The WSDL contains imports so it cannot be used as add web reference.

    I have created a class.

    This web service need authentication.

    I have given the authentication details under the SOAP send port.

    When I call the web service it gives the "login.aspx has moved " Error.

    How can I set the user name password from the orchestration?


  11. Sanket B says:

    Hi Hari,

    I am not sure if I understand your probalem correctly. If you are encapuslating the call to the webservice, where do you have the SOAP Send port in the picture?

    Also, what the is the type of authentication that your webservice expects? Are you looking at WSE authentication or are the credentials being passed as a SOAP HEader?

  12. Gokul says:

    Hi Sanket,

    I am trying to consume a web-service from an orchestration. The web-service is set to Integrated Windows Authentication.

    I have tried setting the username and password from the send port as well as inside the orchestration using the message assignment shape and code is as follows:

    MyWsMessage(SOAP.Username) = “Mydomain\Myusername”;

    MyWsMessage(SOAP.Password) = “MyPassword”;

    Still Iam getting the 401 Unauthorized. Please point me to some articles from where I can get this authenticated web-services to work.



  13. Sanket B says:

    Ho Gokul,

    When using the Integrated Authentication on the web services, your IIS is going to check the identity of the caller using Kerberos authentication. In order to make this work, you will have to provide permissions for your BizTalk host account to access the webservice.

    Hope this helps.


Comments are closed.

Skip to main content