Itinerary Configurator


I had many web services to implement with BizTalk ESB Toolkit. All these web service would take input message, perform some mapping/enrichment on the input message call a web service on a LOB system. The LOB web service result would then be mapped to the result of the web service and returned to the caller.

Figure 1: Web service implemented as an Itinerary

If you look at and web service implemented as an itinerary if would look as in figure 1. The itinerary consists of:

  1. A two way on ramp that receives the message
  2. A call to a map to prepare the LOB web service message request
  3. A rout to the LOB web service send port
  4. Call the LOB web service through the send port
  5. Map the response from the LOB web service to the web service schema response
  6. Route the response to the two way receive location through the on ramp

Now I need to implement more than 50 web services that would be performing the same logic except for a different maps to transform to different LOB web service and a different send port for each LOB web service. I can create an itinerary for each web service but that would lead a numerous number of itineraries with the same structure. So I wanted to create a Kind of an itinerary template for all these services. Let us first examine in more detail how an Itinerary implements a web service.

Implementing a Web Service with and ESB Itinerary

For simplicity assume I want to implement a simple web service with BizTalk ESB toolkit that would take as input two number, call a web service that would perform addition or other mathematical operation on them and then return the result to the caller.

The first step is to define the schemas for the request, response in a BizTalk Project. Use the BizTalk WCF Service Publishing wizard to publish a two way web service with request that takes the request schema and a response with the defined schema.

Second step is to start a new blank itinerary and add an onramp service, and configure it to be the receive port defined step 1. You will also need to change the receive location pipelines to be the ESB Toolkit pipelines Itinerary select Receive XML for the receive pipeline and Itinerary Send Pass through for the send pipeline

Simplified BizTalk Content Based Routing for a Passthrough data

 I had simple task, I had image files that need to be routed (“copied”) to another location based on some field being set inside the image metadata. I devised a simple solution that consists of a simple pipeline component that promotes the filed into the Message Context, create a dummy schema with promoted field. Use the pipeline component in a custom pipeline. This solution would read the information and promote the field values if they exist without publishing the whole image into the message box database. Delivering performance similar to using the standard pass-throu pipeline. Bellow you can find the pipeline and the sample code of the component


/// Implements IComponent.Execute method.


<param name=”pc”>Pipeline context</param>

<param name=”inmsg”>Input message.</param>

<returns>Processed input message with appended or prepended data.</returns>


/// IComponent.Execute method is used to initiate

/// the processing of the message in pipeline component.


IBaseMessage Execute(IPipelineContext pContext, IBaseMessage pInMsg)




IBaseMessagePart bodyPart = pInMsg.BodyPart;

string imgsrc = null;

if (bodyPart != null)


Stream srcs = bodyPart.GetOriginalDataStream();

StreamReader tr = new

string contents;

string beginCapture = “<photoshop:Source>”;

string endCapture = “</photoshop:Source>”;

int beginPos;

int endPos;

contents = tr.ReadToEnd();

Debug.Write(contents.Length + ” chars” + Environment.NewLine);

beginPos = contents.IndexOf(beginCapture, 0);

if (beginPos > 0)


endPos = contents.IndexOf(endCapture, 0);

Debug.Write(“xml found at pos: “ + beginPos.ToString() + ” – “ + endPos.ToString());

imgsrc = contents.Substring(beginPos + beginCapture.Length + 1, (endPos – (beginPos + beginCapture.Length + 1)));

Debug.Write(“Xml len: “ + imgsrc.Length.ToString() + ” Imgsrc = “ + imgsrc);


// return the cursor to the start of the stream

srcs.Seek(0, SeekOrigin.Begin);


pInMsg.Context.Promote(“Source”, @”http://MoustafaRefaat.ImagingPipeLine.PropertySchema.PropertySchema&#8221;, imgsrc);


catch (Exception ex)




return pInMsg;


If you have any questions I would love to hear from you

Secure Messaging Solution

We are sending end receiving sensitive information over the internet. We want to secure all the messages we are exchanging with our partners.

Technical Background

Microsoft® BizTalk® Server relies heavily on the security provided by certificates. By using certificates for encryption and digital signatures, BizTalk Server can send and receive data that can be trusted. By using certificates for encryption and digital signatures, BizTalk Server can:

  • Send and receive data that can be trusted.
  • Make sure that the data it processes is secure.
  • Make sure that authorized parties receive its messages.
  • Make sure that it receives messages from authorized parties.

Creating the Certificates

We will need to create a certificate to use for encrypting and decrypting our secure messaging example.
MakeCert Test Certificate
A MakeCert test certificate is an Authenticode digital certificate that is created by the MakeCert tool. A MakeCert test certificate is a self-signed, root certificate. To create a MakeCert test certificate, use the MakeCert tool as follows:

MakeCert -r -pe -ss TestCertStoreName -n “CN=CertName”  CertFileName.cer 


  • The -r option specifies that the certificate is self-signed, that is, the certificate is a root certificate.
  • The -pe option specifies that the private key that is associated with the certificate can be exported.
  • The -ss TestCertStoreName option specifies the name of the certificate store that contains the test certificate.
  •  The -n “CN=CertName” option specifies a name for the certificate that can be used with the SignTool command-line tool to identify the certificate. It is recommended that you use a certificate name that clearly identifies the certificate as a test certificate, for example, “WDK Driver Testing Cert – for in-house use only.” If the certificate name is not supplied, the default name of the certificate is “Joe’s Software Emporium.
  • “CertFilename.cer is the file name that contains a copy of the test certificate. The certificate file is used to add the certificate to the Trusted Root Certification Authorities certificate store and the Trusted Publishers certificate stores.
    Storing the Certificates
  • Depending on the purpose of a certificate (signing messages, verifying signatures, decrypting messages, encrypting messages, or party resolution), it must be installed in a specific certificate store. BizTalk Server uses two Windows® certificate stores – the Other People certificate store (in the Local Computer folder) for public keys, and the Personal certificate store (in the Current User folder) for the service account of each host instance for private keys.

Other People certificate store. Public key certificates, as their name implies, are public and accessible by anyone with access to the computer on which they are stored. BizTalk Server retrieves from this store the public key certificates to encrypt messages and to verify the digital signatures for incoming messages. All users can read and use the certificates in this store. The following figure shows the Other People certificate store that BizTalk Server uses for public key certificates.

Figure 1: Other People certificate store

Personal certificate store: BizTalk Server uses private key certificates to decrypt incoming messages and sign outbound messages. Every Windows account enabled to log on interactively on a computer has a personal certificate store that only that account can access. BizTalk Server uses the personal certificate store for the service account of each host instance to access the private key certificates to which each service account has access. The private key certificates must be stored in the Personal certificate store for the service account for each host instance on each computer that has a running host instance that requires the certificate for decryption or for signing outbound messages.
Note: The personal certificate store is also named the MY certificate store when it is used for programmatic operations, such as scripting the importing and exporting of certificates. The following figure shows the Personal certificate store that BizTalk Server uses for private key certificates.

Figure 2: Personal certificate Store

For more information about the certificate stores and the Certificate snap-in for the Microsoft Management Console (MMC), search for “Certificate console” in Windows XP, Windows Server™ 2003, or Windows 2000 Server Help.
Certificates That You Need in Each Store
The following table describes the certificates that you must install in each Windows certificate store.

Table 1 Certificates for each Windows certificate store

Certificate purpose Certificate type Certificate store
Signing Own private key Personal store for each service account of a host instance that has a send pipeline with a MIME/SMIME Encoder pipeline component configured to sign messages (Add Signing Cert To Message property set to True).
Verifying signature Partner’s public key Other People store on each computer that has a host instance that has a receive pipeline with a MIME/SMIME Decoder pipeline component.
Decrypting Own private key Personal store for each service account of a host instance that has a receive pipeline with a MIME/SMIME Decoder pipeline component.
Encrypting Partner’s public key Other People store on each computer that has a host instance that has a send pipeline with a MIME/SMIME Encoder pipeline component configured to encrypt messages (Enable encryption property set to True).
Party resolution Partner’s public key Other People store on the administration computer from which you are configuring party resolution.


Figure 3: Solution Concept

The solution consists of creating two pipelines. A receive pipeline that decrypts the incoming messages and a send pipeline that encrypts the outgoing messages. The example in this solution uses four ports, two for the encryption scenario and two for decryption scenario.

  1. Plain Receive port that consumes files in a directory to be encrypted. This receive port uses one receive location that uses the standard “Microsoft.BizTalk.DefaultPipelines.XMLReceive” pipeline.
  2.  Enc Send Port that subscribes to the receive plane text port. This send port uses the “PracticalBTS.EncryptPipeLine.EncSendPipeline” pipeline. The figure below shows the configuration. Notice that in the “Outbound Encryption” certificate name is set to the certificate in “other people certificates store” for the receiver.

Figure 4: Send Encrypted port settings.

  1. Enc Receive Port that consumes files in a directory that are encrypted and we want to decrypt them. This receive port uses one receive location that uses the “PracticalBTS.EncryptPipeLine.DecReceivePipeline” pipeline. The figure below shows the configuration.

Figure 5: End Receive Location port configuration

Notice that we do not specify the certificate to use to decrypt the message. As BTS uses the certificate defined for the BTS group as shown in the figure below

Figure 6: BizTalk Group properties certificate settings

  1. Plain Send Port this port subscribes to the Enc Receive Port and just save the output in a file so we can check it

Pipelines Implementation

Receive Decryption Pipeline

Figure 7: Receive Decryption Pipeline

The figure above shows the receive pipeline. As you can see we insert into the decode phase the MIME/SMIME pipeline component. And into the Disassemble pipeline the XML disassembler pipeline component. There are no special settings for any component in this receive pipeline we just accept the default settings.

Send Encryption Pipeline


Figure 8: Encryption Send Pipeline

The figure above shows the Encryption send Pipeline. In this pipeline we have the standard XML Assembler pipeline component in the assemble phase and the MIME/SMIME encoder component in the encode phase.

Figure 9: Encoder Pipeline Component Settings
The figure above shows the settings for the MIME/SMIME encoder pipeline component where we enable the encryption and we choose the “DES3” encryption algorithm. In this example we are not going to sign the messages so we select “NoSign” for the signature sign.
Deploying the solution
1. Installing the certificate
2. Compiling and deploying the solution

Use the secure message deployment script to deploy the solution.


To test the configuration, copy a sample xml file from the “Data Folders\Sample XML Files” or any other valid XML file and drop it in the folder “Data Folders\SecureMessaging\Encryption\In” after BTS process the message you will find the encrypted file at “SecureMessaging\Encryption\Out” the encrypted file should look like

Figure 10: Sample encrypted message

Copy the encrypted message to “Data\SecureMessaging\Decryption\In” and after BTS process the message you will find the plain message at “Data\SecureMessaging\Decryption\out”

Possible Issues

Certificate authorization

A message received by adapter “FILE” on receive location “EncReceive Location” with URI “…\*.txt” is suspended.
Error details: There was a failure executing the receive pipeline: “PracticalBTS.EncryptPipeLine.DecReceivePipeline, PracticalBTS.EncryptPipeLine, Version=, Culture=neutral, PublicKeyToken=e56921b90feec973” Source: “MIME/SMIME decoder” Receive Port: “EncReceivePort” URI: “\SecureMessaging\Decryption\In\*.txt” Reason: Could not validate the Trust Chain of the encryption certificate. The certificate issuing authority may not be a trusted Certificate Authority.
MessageId: {9C0C7B4B-D2B7-489F-A343-6355F5BFA9AC}
InstanceID: {67753340-9C17-4C7B-8364-501BFD5F2FD3}


Make sure you have installed the certificate in the trusted Authority folder.