BizTalk Consume WebServices with SOAP Header

BizTalk Consume WebServices with SOAP Header

When working with Web Services, the common scenario is to pass in the credential in the SOAP Header.

In this post, I will provide the steps how to do this in BizTalk Orchestration.
This will be a simple flow like below screen shot :

Flow Detail :

1. Web Application will call an exposed web services by Biztalk Orchestration
2. The request object consists of 3 elements : UserName, Password, Message
   
3. BizTalk Orchestration will construct the SOAP Header Message with UserName and Password
4. BizTalk Orchestration will assign the Message as the body and assign the SOAP Header
5. BizTalk Orchestration calls the Web Services (WSSOAPHeader)
6. Web Services will read the SOAP Header message and return back some message
7. BizTalk will also return back the message to the web application

BizTalk Orchestration layout

One of the most crucial thing in here is the SOAP Header message.
To create the SOAP Header message schema :

1. Create a property schema file
2. In the schema properties, change the Target Namespace to http://schemas.microsoft.com/BizTalk/2003/SOAPHeaderSet the Node Name property to the SOAP Header Name and the Property Schema Base to MessageContextPropertyBase

After creating this property, we can assign the SOAP Header into the message like this below

varXMLSOAPHeader = msgSOAPHeader;
msgWSRequest(MyBizTalkApp.AuthenticationSOAPHeader) = varXMLSOAPHeader.OuterXml;

Note :

• When assigning the SOAP Header, it expects string value, that's why I assign the msgSOAPHeader into an XML document variable and get the string from OuterXml property.
• If the SOAP Header is not received by the web services even though you have assigned it in the code, make sure that you have followed each of the steps to create the SOAP Header message schema above, especially the namespace part. It caused me 2 days to notice this one in the end :P

You can find and download the whole VS 2005 solution at here :


Here is the link to the MSDN Site : Consuming Web Services with SOAP Headers

Spotlight on BizTalk 2006 Custom Functoid

A very important topic I will talk about which is how to develop a custom functoid. Especially Developing a Custom Referenced Functoid.

A Custom Referenced Functoid!!! You mean there are other types of custom functoid. 
Yes, there are three types. Let us define them

A Custom Referenced Functoid: Custom referenced functoids do not copy implementation code inline into the map. Instead, a reference to the assembly, class, and method is placed in the extension object file associated with the generated style sheet and called at run time.

A Custom Inline Functoid: Custom inline functoids provide functionality by copying implementation code directly into a map and not by referencing an assembly, class, and method name like a custom referenced functoid.

A Custom Cumulative Functoid: Use a custom cumulative functoid to perform accumulation operations for values that occur multiple times within an instance message.
Now after you knowing what the types of Custom Functoids are, let us develop our custom referenced functoid.

Note #1: all custom functoids must derive from the BaseFunctoid class. You must first override the constructor and make a set of calls that tell BizTalk Mapper about your custom functoid. Then you need to write the functoid logic
Fine, our custom functoid name Percentage, which will calculate the percentage where it takes two input parameters.

1) Fine, create a new project its type is class library and name it CustomFunctoid

2) Add a reference of Microsoft.BizTalk.BaseFunctoids you can find it here :
X:\Program Files\Microsoft BizTalk Server 2006\Developer Tools\Microsoft.BizTalk.BaseFunctoids.dll (where X the drive that holds the installation of BizTalk server 2006)

3) let you class implement from BaseFunctoid
public class Percentage : BaseFunctoid

4) let the constructor override the base
public Percentage(): base()

5) write the following line of code in the construction :

this.ID = 3003;
SetupResourceAssembl("CustomFunctoid.CustomFunctoidResource",System.Reflection.Assembly.GetExecutingAssembly());
SetName("PERCENTAGE_NAME");
SetTooltip("PERCENTAGE_TOOLTIP");
SetDescription("PERCENTAGE_DESCRIPTION");
SetBitmap("PERCENTAGE_BITMAP");
this.SetMinParams(2);
this.SetMaxParams(2);
SetExternalFunctionName(GetType().Assembly.FullName, "CustomFunctoid.Percentage", "CalculatePercentage");
this.Category = FunctoidCategory.Math;
AddInputConnectionType(ConnectionType.AllExceptRecord);
AddInputConnectionType(ConnectionType.AllExceptRecord);
this.OutputConnectionType = ConnectionType.AllExceptRecord;

Where: 

· ID: Assign a unique ID to the functoid 

· SetupResourceAssembly: Point to the resource assembly
NOTE #2: Include a resource file with your project. If building with Visual Studio, the resource assembly must be ProjectName.ResourceName. Example: Our resource file named CustomFunctoidResource which includes the value of name, tooltip , description, and the Icon of our custom Functoid , and our project named CustomFunctoid 

· SetName , SetTooltip , SetDescription, SetBitmap: set the name , tooltip , description and the icon of our custom functoid

· SetMinParams, SetMaxParams: Specify the number of parameters accepted , where SetMinParams is used to set the number of required parameters and the SetMaxParams is used to method to set the number of optional parameters

· SetExternalFunctionName: Tell BizTalk Server which methods to invoke for your functoid

· Category: Assign the functoid to one or more categories, for example Math, String, MassCopy…etc.
· AddInputConnectionType : Declare what can connect to your functoid

· OutputConnectionType : Declare what your functoid can connect to 

6)Now create the function that will calculate the percentage which is :

public float CalculatePercentage(float x, float y)
{
float c = float.MinValue;
c = (x / y) * 100;
return c;
}

7) Create a Strong key , and Assign it to your class library

8) Build the Class Library and copy the DLL to : X:\Program Files\Microsoft BizTalk Server 2006\Developer Tools\Mapper Extensions (where X is the drive that holds the installation of BizTalk Server 2006)

9) Add this dll it to the GAC ( open the Visual Studio 2005 Command Prompt and type GACUTIL –i X:\CustomFunctoid.dll)

10) Add it to the ToolBox in Visual Studio 2005 (right click on the ToolBox, choose Add/Remove items, click the Functoids tab and browse to the Customfunctoid.dll file and make sure it’s checked. 

you can download the whole project from here 

SSODB Configuration Store for BizTalk Orchestration

SSODB Configuration Store for BizTalk Orchestration

One of the aspect of the application design is the configuration module.

There are at least 4 repositories where we can store the configuration for BizTalk orchestration :

1. Custom config file
   
2. BizTalk config file
3. Windows Registry
   
4. Database

Since each company will have its own policy for the production environment, this will eventually lead into the configuration repository.

Each repository above has its own pros and cons to implement, but I would say that configuration files and registry will not scale for MultiServer / Clustering environment, since we need to replicate them to each of the BizTalk server. So it will be easier to use database since we can put the configuration information in one place and all the servers will access this central database.

But when it comes to the database, we will have the next question of where to store the connection string. Well, this is the point where SSODB comes in handy.

As we may notice, whenever we install BizTalk Server, the Enterprise Single Sign-on will need to be installed as well, and the Enterprise Single Sign-on has a database, named SSODB. This is mainly used for BizTalk to store all the internal configuration information.

This SSODB will be the ideal solution for the configuration repository since as far as i know.
Benefits :

1. SSO will be installed and running along with BizTalk server
   
2. It provides encryption
3. It provides a central configuration repository for multi server environment
   

Microsoft also provide a sample of how to use the SSO as configuration Store (http://go.microsoft.com/fwlink/?LinkId=99741)

How to configure our application configuration in SSODB
The SSO Installation comes some executable files in folder at C:\Program Files\Common Files\Enterprise Single Sign-On.
The executable which we're going to use is ssomanage.exe

As you can see in the screen shot above, there are some paramaters we can pass into the ssomanage.exe.

To create our custom application configuration :
1. Define our custom application configuration definition xml (below)
Note :
- When defining the fields, notice that the 1st field (ordinal=0) is a reserved field, so do not define any of your field in here, start defining our custom fields from the 2nd field (ordinal=1) afterwards.
- Use masked=true attribute to fields which need more security.

2. Save into xml file, e.g. BizAppTest1.xml

3. Run ssomanage.exe -createapps BizAppTest1.xml4. Go to C:\Program Files\Microsoft BizTalk Server 2006\SDK\Scenarios\Common\SSOApplicationConfig

5. Run Setup.bat to compile the tool, the executables should be generated in the bin folder (BTSScnSSOApplicationConfig.exe)

6. Use this tool to define our fields value :
Example :
BTSScnSSOApplicationConfig.exe -set BizAppTest1 "ConfigProperties" "ConnectionString" "Data Source=."

Note : Use "ConfigProperties" for the SSOIndentifierName parameter

7. Verify whether the value is correct
Example :
BTSScnSSOApplicationConfig.exe -get BizAppTest1 "ConfigProperties" "MaxInstances" 

Richard Seroter has created his own awesome SSO Config Store Application Manager as window client tool to do the configuration in SSODB. You may want to take a look at it and try it yourself. He also has a lot of great biztalk posts and bits ;)

Note : If you have any additional fields or you want to remove the fields from SSO, the only way i know right now is to delete the app (ssomanage.exe -deleteapp BizAppTest1) and then re-do all the steps to setup the configuration. I created some script in a batch file so it will be much easier to do and can be re-used for deployment to production as well.

How to retrieve the configuration from SSODB
Fear not, when we install the enterprise single-sign on, there is an installed interface component which will provide the functionality to access the SSODB database, so we don't need to take care about how and where to connect to the SSODB database.

After you download the BizTalk Sample file for SSO As configuration store http://go.microsoft.com/fwlink/?LinkId=99741, there is a utility cs file, named SSOConfigHelper.cs. You can either include this class or the dll into your project.

Then we can retrieve our custom configuration value by calling this static method from the SSOConfigHelper class :

Microsoft.SSO.Utility.SSOConfigHelper.Read("BizAppTest1", "ConnectionString");

Hope this helps :)

BizTalk SSO Configuration Data Storage Tool

Published September 21, 2007 BizTalk , General Architecture 

If you’ve been in the BizTalk world long enough, you’ve probably heard that you can securely store name/value pairs in the Enterprise Single Sign-On (SSO) database. However, I’ve never been thrilled with the mechanism for inserting and managing these settings, so, I’ve built a tool to fill the void.

Jon Flanders did some great work with SSO for storing configuration data, and the Microsoft MSDN site also has a sample application for using SSO as a Configuration Store, but, neither gave me exactly what I wanted. I want to lower the barrier of entry for SSO since it’s such a useful way to securely store configuration data.

So, I built the SSO Config Store Application Manager.

I can go ahead and enter in an application name, description, account groups with access permissions, and finally, a collection of fields that I want to store. “Masking” has to do with confidential values and making sure they are only returned “in the clear” at runtime (using the SSO_FLAG_RUNTIME flag). Everything in the SSO database is fully encrypted, but this flag has to do with only returning clear values for runtime queries.

You may not want to abandon the “ssomanage” command line completely. So, I let you export out the “new application” configuration into the SSO-ready format. You could also change this file for each environment (different user accounts, for instance), and then from the tool, load a particular XML configuration file during installation. So, I could create XML instances for development/test/production environments, open this tool in each environment, and load the appropriate file. Then, all you have to do is click “Create.”

If you flip to the “Manage” tab of the application, you can set the field values, or delete the application. Querying an application returns all the necessary info, and, the list of property names you previously defined.

If you’re REALLY observant, and use the “ssomanage” tool to check out the created application, you’ll notice that the first field is always named “dummy.” This is because if every case I’ve tested, the SSO query API doesn’t return the first property value from the database. Drove me crazy. So, I put a “dummy” in there, so that you’re always guaranteed to get back what you put in (e.g. put in four fields, including dummy, and always get back the three you actually entered). So, you can go ahead and safely enter values for each property in the list.

So how do we actually test that this works? I’ve included a class, SSOConfigHelper.cs (slightly modified from the MSDN SSO sample) in the below zip file, that you would included in your application or class library. This class has the “read” operation you need to grab the value from any SSO application. The command is as simple as:

string response = SSOConfigHelper.Read(queryName, propertyName);

Finally, when you’re done messing around in development, you can delete the application.

I have plenty of situations coming up where the development team will need to secure store passwords and connection strings and I didn’t like the idea of trying to encrypt the BizTalk configuration file, or worse, just being lazy and embedding the credentials in the code itself. Now, with this tool, there’s really no excuse not to quickly build an SSO Config Store application and jam your values in there.

You can download this tool from here.

Consuming And Publishing Web Services in BizTalk Server using SOAP and WCF Basic Http Adaptor

Consuming Web Services In BizTalk:

Steps for Consuming Web Services:

1) Add Web Reference, When you add a Web reference to your project, BizTalk creates an orchestration Web port type, Web message types, Reference.map (map file), Reference.odx (orchestration file), <WebService>.disco (discovery file), and <WebService>.wsdl (Web Service Description Language file) to your project.

Constructing Web Messages

When you add a Web reference, BizTalk automatically creates Web message types, which BizTalk creates based on the Web methods from the added Web service. You add a Web message to your orchestration, setting the message type to one of the Web message types.

Web messages types

Web message types are identical to a normal message type, except you cannot modify, rename or delete them. To delete a Web message type, you must remove the Web reference from your BizTalk project.

BizTalk creates one request and one response Web message type for each Web method in the added Web service. If the Web method is a one-way operation, BizTalk only creates a request Web message type. A request Web message type contains one message part for each input parameter of the Web method. A response Web message type contains one message part for the return value and one message part for each output parameter of the Web method.

Depending on the Web method parameter (input or output), BizTalk creates a Web message type from a primitive .NET type or a schema type. If the Web method parameter is a primitive .NET type, the message part uses a primitive .NET type. If the Web method parameter is a schema type, BizTalk adds the schema type to the BizTalk project as a schema in Reference.xsd. The schema is the basis for the message part. You can find Reference.xsd in the Web references folder.

Alternatively, you can create both primitive and schema .NET types by calling a .NET class. For more information on creating message types by using a .NET class, see Constructing Messages in User Code.

Web messages

Web messages are the messages you use when you consume (call) a Web service. You add a Web message to an orchestration the same way that you add a regular message, except that you set the message type to one of the Web message types that BizTalk created when you added a Web reference.

Message parts

After you create the Web message, you construct the individual message parts. If your message part uses a primitive .NET type, you use a Message Assignment shape. If your message part uses a schema type, you use a Transform shape.

Determining a Web Message Part Type

You can determine if a Web message part type is a primitive .NET type or a schema type by using the Properties window for a given Web message type.

To determine a Web message part type

1.       With an orchestration open, on the View menu, click Other Windows, and then click Orchestration View.

2.       Expand the Multi-part Message Types node, and then expand a Web message type.

3.       Select a message part.

A Web message part signature that begins as <project default namespace>.<Web reference name>.Reference.<schema root>is a schema type. The <schema root> part of the type is the root element of the Web reference schema that constructs the Web message part. Otherwise, the message part signature is a primitive .NET type such as System.String or System.Int32.

Constructing a Web Message Part from a Primitive .NET Type

You create a Web message part from a primitive .NET type by using a Message Assignment shape. Alternatively, you can create a Web message part from a primitive .NET type by using a .NET helper class to set the parts

ItemAvailRequestInstance.Item_ID = "This is Item_ID.";

Constructing a Web Message Part from a Schema Type

You create a Web message part from a schema type by using a Transform shape.

You are saying there will be no WSE 3.0 adapter for BizTalk. Why?

WCF will be released soon after BizTalk 2006 is released. The WCF adapter for BizTalk will be wire compatible with both WSE 3.0 and WCF callers and endpoints. Once released, the WCF adapter for BizTalk Server will provide a single solution for WSE 2 and 3 standards. In the meantime, there are partners that provide WSE 3 adapters today.

 

 

BizTalk 2006 R2 - consume an .ASMX webservice using WCF-BasicHttp adapter

 

Normally when we need to consume a .asmx web service in BizTalk 2004/2006 (NOT R2) inside an orchestration, we add a web reference, which will create all the multi-part message and web port type required to consume the orchestration. You construct the orchestration and configure the SOAP adapter in the send port to consume the web service. I suppose that's the normal route any BizTalk developer will take when you are put under a circumstance to consume an .asmx webservice using WCF-BasicHttp adapter.

But when you are going to use the WCF-BasicHttp adapter, "Add Web Reference" is not going to work, and we need to take advantage of the hidden "Consume WCF Service" wizard, which comes as part of BizTalk 2006 R2. The wizard will generate required schemas, multi-part messages, orchestration port types, and also binding files for both basicHttp and custom binding. I'll put the steps here to consume a basic .asmx webservice in BizTalk 2006 R2 with WCF-BasicHttp adapter.

The sample webservice we are going to use contains a very simple webmethod as shown below.

[WebMethod]
public string ConcatName(string firstName, string lastName)
{
return firstName + " " + lastName;
}

The below walk-through is based on the sample webservice, which comes as part of the download.

1.      Create a blank BizTalk Project

2.      Right-Click on the project and select Add->Add Generated Items->Consume WCF Service

3.      Select the option "Metadata file (WSDL and XSD)", Click "Next"

4.     

5.      Open an instance of a browser and navigate to your ".asmx?WSDL" file and save it somewhere in your harddrive (Example: c:\Service.wsdl).

6.      Click on the "Add" button (next step in the wizard after the one shown above), browse to the .WSDL file you saved in Step 4, Click "Next" (Accept defaults), Click "Import" and then Click "Finish" to complete the wizard.

7.      Once you click "Finish" the following files will be added to your project (File name will depend on the name of the .WSDL file you selected)
Service.BindingInfo.xml
Service.odx
Service_Custom.BindingInfo.xml
Service.tempuri_org.xsd

8.      Open the Service.odx file, inside the orchestration view create 2 messages as shown below
WSRequest - Multi-part Message Type - ConsumeWebService.ConcatNameSoapIn
WSResponse - Multi-part Message Type - ConsumeWebService.ConcatNameSoapOut

9.      Right-Click on the orchestration "Port Surface", Click "Next", In the port properties page Click "Next", In the "Select a Port Type" page select "Use an existing Port Type" and select "ConsumeWebService.ServiceSoap", In port binding page select "I'll be sending a request and receiving a response." for port direction and "Specify later" for port binding. Click "Next" and then "Finish".

10.  Construct an orchestration as shown in the below figure
Receive_1 -> Activate=true, Message= WSRequest
Send_1 -> Message = WSRequest
Receive_2 -> Message = WSResponse
Send_2 -> Message = WSResponse

11. 

12.  I created a FILE Receive and FILE Send (Specify Now) port binding for port_2 and port_3

13.  Assign a key file to the project and set the "Application Name" to "ConsumeWebService". Build and Deploy the project.
Open BizTalk Administration Console, Right-Click on the application and select "Import Binding". Browse to the auto generated binding file "Service.BindingInfo.xml" and select it.

14.  Bind your Orchestration to the correct ports and host. For the .asmx webservice logical port, select the auto generated "WcfSendPort_Service_ServiceSoap". (Start the application)

15.  Create a sample message by right-clicking on "Service_tempuri_org.xsd" file and clicking "Generate Instance". Drop the message in the folder you configured for port_2 in the orchestration, you should see the output result in folder you configured for port_3 in your orchestration.

 

BizTalk Questions With Answers Part 3

Direct binding can be used to send messages from one  

Orchestration to another.  It can also be used to send messages directly into  

]the message box.

Dynamic binding is used if the URL to which the file has to be posted is  

decided at runtime.

 

Call Orchestration: Makes a synchronous call to another orchestration

 

Start Orchestration: Makes an asynchronous call to another orchestration.

 

What is a Convoy?

Convoys are a messaging pattern and not a feature of BizTalk Server 2004.    

Convoys occur because of a business requirement to process messages in a way that the traditional publish and subscribe messaging system inside BizTalk Server 2004 cannot handle

Convoy processing can be additionally broken out into two separate categories as shown in the following list:

i). Sequential convoy - Items that are in a order, one after another

ii). Parallel convoy - Items that are in any order, but must all be present before   

something occurs.

 

What is a Message Type?

Message Type is a BizTalk System property that is promoted inside a Pipeline.   

It is made up of Document Name Space # Root Node Name.

 

 

Target Namespace in the XML contains the Solution name. The messages in the 

BizTalk are identified based on their namespace.

 

Policy Chaining: Calling one policy from the other is called Policy chaining. This is   

not possible in Business Rules Engine but can be implemented using .net code.

Ex: Calling a .net code which in turn calls executes another policy.

 

Call Rules: It is used to call the rules in the Orchestration. It has to be hosted

in an atomic shape.

 

Party resolution in Receive pipeline:

 

Stages in Custom Receive Pipeline are as follows:

Decode, Disassemble, Validate and ResolveParty.

Decode: Decompression.

Disassemble: Conversion from one format to the other.

Validate: Validation.

ResolveParty: Resolving the party based on Certificates. (from TPM db).

 

Stages in Custom Send Pipeline are as follows:

Pre-Assemble, Assemble and Encode.

Pre-Assemble is used for validation against the schema.

Assemble is used to add new items i.e. to change the message contents.

Encode is used to encrypt/ to compress (changing the format of the message) the message.

 

Overheads of using Promoted fields against distinguished fields:

Since distinguished fields do not require a separate property schema, the evaluation of distinguished fields by the Orchestration engine consumes less overhead than the evaluation of Property fields by the Orchestration engine. The evaluation of Property fields requires an XPath query, the evaluation of distinguished fields does not require an XPath query as the pipeline disassembler populates the distinguished fields in the context and the orchestration engine gets the cached values

 

Why the ROOT Name and namespace combination in a schema has to be unique?

BizTalk sets a message context property called BTS.MessageType.  This is a concatenation of the document namespace and Root Node Name. This property is promoted by the disassembler pipeline components during message parsing and uniquely identifies a messagetype.Message types are basically message content properties (metadata) used for filter creation on send ports and orchestrations.

 

How do you develop a Custom Functoid? Which interface to use?

We can create a custom functoid by deriving from the Microsoft.BizTalk.BaseFunctoid class (implemented by Microsoft.BizTalk.BaseFunctoids.dll in the Developer Tools folder) and overriding certain methods.There are two implementation types for custom functoids: functoids that are added to the global assembly cache and called directly and those that export script source to a map file at design time(Inline Script Functoid).

 

What are the different transport types available in BizTalk Server 2004?

In all, there are eight native transport adapters :,FILE,Hypertext Transport Protocol (HTTP),File Transport Protocol (FTP),Microsoft Message Queue Transport (MSMQT),Simple Mail Transfer Protocol (SMTP),Simple Object Access Protocol (SOAP),Microsoft SQL Server (SQL),Electronic Data Interchange (EDI)

How do you call nested orchestrations in main orchestration?

An Orchestration can call other orchestration either Synchronously orAsynchronously. Synchronous call is made from Call Orchestration Shape and Asynchronous call is made from Start orchestration Shape. Input will be value type, reference type or correlation set and output will be only a Message/variable type.

What is BAS?

Business Activity Services (BAS) enables business users to manage trading partners and associated business processes through Microsoft Sharepoint Portal Server, Windows Sharepoint Services and MS Office.

How do you invoke a business rule in your orchestration?

The BizTalk orchestration engine does indeed have the capability to act as a host for rule sets. This is wrapped up for you in the Call Rules shape. The Call Rules shape must be hosted in an atomic transaction. This helps BizTalk dehydrate state to the dehydration database before turning the rule engine loose on the orchestration's data for a while. As always, this means that any orchestration using a Call Rules shape must be configured for a long-running transaction, and you must add an atomic transactional scope to your orchestration. With those preliminaries out of the way, you simply drop a Call Rules shape into the Scope shape, ensure it is selected, and turn your attention to the Properties view in Visual Studio .NET.A Call Rules shape has two properties you need to worry about. One is the Name and can be anything you want, but the other, Configure Policy, is essential to the success of your orchestration. Clicking the ellipsis button invokes the Call Rules Policy Configuration dialog box, will have 2 parameters. One is to select the Rules Policy you want to invoke, and the other is to populate any parameters that policy requires with data from the orchestration. The drop-down list labeled Select the Business Policy You Wish to Call is populated with the names of all the policies published in the development machine's Rule Store. After you've selected a policy, the dialog box is able to inspect the policy to determine what parameters are available for configuration.