1. Problem
You want to call a web service from within your business process, using the standard SOAP adapter.
2. Solution
When calling a web service,
the first item that is needed is the Web Services Description Language
(WSDL). The WSDL contains the interfaces indicating how a web service
can be called. BizTalk imports this WSDL and turns it into a schema that
can be read in the same way as a standard XSD, with each web method
defining its own schema. This solution will walk through the steps
required to reference a WSDL, create a message to post to a web service
(via a web method), and get the web service result message.
Open a BizTalk project in Visual Studio.
In the Solution Explorer, right-click the References node under the project header, and select Add Service Reference.
In
the Add Service Reference dialog box, you can manually enter the URL of
the WSDL into the URL box at the top of the window. This can be a
standard web URL (http://) or a file
path to a WSDL or SVC file (useful for developing in a disconnected
environment). Alternatively, use any of the other Browse methods to
locate the service.
After entering a valid URL path, all available web services will be displayed (see Figure 1).
Select the desired web service from this list. Make sure that the
namespace shown in the text box is appropriate (usually, you will want
to rename this to something more descriptive than the default; the name
entered here will be how the web service is referred to in the rest of
the project)
Click the OK button. The newly referenced web service should now appear under the Service References folder in the Solution Explorer (see Figure 2).
In
an orchestration, right-click Port Surface, and select New Configured
Port. This will start the Port Configuration Wizard. Use the following
settings to configure the new port.
Name the port appropriately.
For
Port Type, select Existing Port Type. In the window that appears,
highlight the web port that is a post (as opposed to a response back),
and then click Next.
The
final screen should be automatically configured indicating that BizTalk
will always be set to sending a request and receiving a response, with
the port binding set to Specify Now. There is no need to make any
changes. Click Next, and then click Finish.
NOTE
Web service calls can be
request/response (two-way) or simply request (one-way). Some of the
parameters in the configuration will be slightly different in the case
of a one-way web service.
In
the orchestration, add a new Send shape. This shape will require a
message to be associated with it. You will want to create a message that
has the same type as the outgoing port you configured in step 6, as
follows:
In the Orchestration View window, right-click the Messages folder, and select New Message.
Give this message an appropriate name, such as msgRequest.
In the Properties window of the message, click the Message Type drop-down list, expand Web Message Types, and select the message type that corresponds to the port type you indicated in step 6.
Set the Send shape Message Type property to this message.
Connect the Send shape to the outgoing method on the port created in step 6.
Drop
a Receive shape on the orchestration, immediately after the Send shape
created in step 7. You will need to create a message that has the same
type as the response back from the web service call, as follows:
In the Orchestration View window, right-click the Messages folder, and select New Message.
Give this message an appropriate name, such as msgResponse.
In the Properties window of the message, click the Message Type drop-down list, expand Web Message Types, and select the message type that corresponds to the response of the web service web method indicated in step 6.
Set the Receive shape Message Type property to this message.
Create an instance of the message that you are sending to the web service (msgRequest). This can be done through a map or a Message Assignment shape. The following steps will show how to do this through a map.
Drop
a Transform shape in the orchestration immediately before the Send
shape created in step 6. This will automatically create a Construct
Message shape.
In the Properties window of the Construct Message shape, click the Messages Constructed property, and select the message created in step 6 (msgRequest).
Double-click the Transform shape. In the Transform Configuration dialog box, the target document should be msgRequest,
and the source document can be any document (you will need to create a
message, not included in these steps, of any given schema type and set
it to the source).
After setting the source and target schemas, click OK. The map should open, and you can map fields as needed.
3. How It Works
The complexity around
calling and mapping to web services is greatly reduced by using a
BizTalk orchestration, the standard SOAP adapter, and the steps
described in this solution. However, there may be times when these steps
do not provide the result needed. In cases where the called web service
is too complex a structure to consume, the web service could be called
from an external .NET component, removing the complexity of calling it
from BizTalk altogether.
Calling a web service from
an external assembly lets developers use the full functionality of .NET
to make the call. While complex web services with arrays or strongly
typed data sets can be called from an orchestration, moving the call to
an external component may be easier.
There are important benefits
to calling a web service with the BizTalk SOAP adapter and following
the steps described in this solution. The ability to turn the WSDL into a
schema, the ability to have retries automatically occur, and the
simplicity of creating the message through the BizTalk Mapper are all
excellent reasons to invoke the web service from within an
orchestration.
