Sunday, November 15, 2009

Using the BizTalk HTTPReceiver

During the creation of the ebMS Getting started environment i ran into problems with using IIS and the HTTPReceiver. Some problems that i had were:

- messages would not be picked up the the HTTP Receive Adapter

- messages remain in the dehydrated state

One of the most difficult things about the HTTPReceive Adapters is the dis-ability to do some hi-tech debugging…even the tool ‘DebugView’ / ‘Fiddler’ will not help when trying to find out what the problem is, TCP/IP Listeners might provide some help but the best thing you should be doing is to walk through all the MSDN steps.

Since i had some trouble finding the steps, hereby the steps for setting up the Adapter for IIS 6 en IIS7.

‘Creating the virtual directory for the HTTPReceiver’

The BizTalk HTTP Receive Adapter can be used in a http receive location configured in Internet Information Services (IIS) inside a virtual directory. Read the Microsoft guidelines for setting up an HTTP BizTalk Receive location (see reference ‘Enable the BTS ISAPI Filter’).

1.1.1 Internet information services 6

To enable the BTS ISAPI Filter perform the following actions:

1) Click Start, point to All Programs, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

2) In the IIS Manager dialog box, right-click Web Service Extensions, and then click Add a new Web service extension.

3) In the New Web Service Extension dialog box, enter BTS Http Receive ISAPI Filter in Extension Name.

4) Click Add.

5) In the Add file dialog box, browse to drive:\Program Files\Microsoft BizTalk Server <version>\HttpReceive. Select BTSHTTPReceive.dll, and then click Open.

6) In the Add file dialog box, click OK.


When you perform step 6, you may receive the following (or a similar) message: "This file is already required by HWSMessages HttpReceive." If you receive this message, click Cancel, and then click Cancel again. In this case, the BTSHTTPReceive.dll file is already required by another Web service extension, and you do not have to complete this "Add File" or "Add a new Web service extension" procedure.

7) In the New Web Service Extension dialog box, click OK.

8) In the Web Service Extension pane of IIS Manager, right-click BTS Http Receive ISAPI Filter, and then click Allow.

To create the virtual directory, perform the following actions:

Start Internet Information Services and select the Default Web Site. Right click and select New/Virtual Directory. The alias name is very important and must match the port configuration!

Type ‘ebMSReceive’ as shown in the figure below;


The HTTPReceive uses the BizTalk receive dll, this dll is located in the Program Files\BizTalk Server 2006\HttpReceive directory. Select the Web site context directory as shown in the figure below.


Select the permissions as shown in the figure below to allow access to the http location.


The properties of the virtual directory should look like the figure below


An Application Pool can contain one or more applications. This allows us to configure a level of isolation between different Web applications. In the example we have used the ‘DefaultAppPool’.

To ensure that the BizTalk HTTPReceive Adapter is able to process the messages, the identity of the application pool must be set to a user account that is a member of the ‘BizTalk Isolated Host users’. Right click the properties of the application pool under which the virtual directory is created. Go to the tab ‘Identity’ and configure the user to an account that is a member of the ‘BizTalk Isolated Host users’ as shown in the figure below;


Ensure that the correct port is used, in this screenshot port 8080 was used, to configure the website to use this port change the configuration of the appropriate web site. In this case we have chosen the Default Website, right click the default web site and select properties from the context menu. Modify the TCP port as shown in the figure below.


1.1.2 Internet information services 7

To enable the BTS ISAPI Filter perform the following actions:

1) Click Start, point to All Programs, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

2) Select the root Web server entry and in the Features View, double-click Handler Mappings and then in the Actions pane, click Add Script Map.


Configuring the script mapping at the Web server level will cause this mapping to apply to all child Web sites. If you wish to restrict the mapping to a specific Web site or virtual folder, select the target site or folder instead of the Web server.

3) In the Add Script Map dialog box, enter BtsHttpReceive.dll in the Request path field.

4) In the Executable field, click the ellipsis (…) button and browse to drive:\Program Files\Microsoft BizTalk Server <version>\HttpReceive. Select BtsHttpReceive.dll, and then click OK.

5) Enter BizTalk HTTP Receive in the Name field, and then click Request Restrictions.

6) In the Request Restrictions dialog box, select the Verbs tab and then select One of the following verbs. Enter POST as the verb.

7) On the Access tab, select Script, and then click OK.

8) Click OK and when prompted to allow the ISAPI extension, click Yes.

9) Right-click the BTSHttpReceive.dll entry, and then select Edit Feature Permissions.

10) Ensure that Read, Script and Execute are selected, and then click OK.

11) Click Features View, and then double-click ISAPI and CGI Restrictions.

12) Ensure that an entry for BTSHTTPReceive.dll exists, and that Restriction is set to Allowed.


The ISAPI and CGI Restriction entry for BTSHTTPReceive.dll is created automatically when you create the script map.

13) Create the Virtual Directory. The procedure was described previously in this section.


That it….

Saturday, November 14, 2009

Using the Covast ebMS Adapter (part 3)

In the previous posts (part1 and part2) i have described some features of the Covast ebMS Adapter and the usage of pipelines to set the message properties and destination.

When using orchestrations, the message can be sent directly to the message box because the message context properties can be set inside the orchestration. This approach can be used to implement additional requirements in inter party communication such as error handling, correlation and other implementations where more dynamic control is required beyond the static configuration of pipelines.

Let’s build an orchestration using the ebMS context properties to send message to a specific party and collaboration protocol agreement (CPA).

‘Building an orchestration for ebMS messaging’

The orchestration in this scenario used message context properties to ensure that the correct collaboration protocol agreement was used during processing. The following paragraph, will explain the construction of this Orchestration.


The figure below shows the message context properties used in the scenario. These properties are set in an expression in the sample orchestration.


1.1.1 Create the solution

First we must create a new solution project. This must be of the type BizTalk project ‘Empty BizTalk Server project’. Name the project ‘GettingStarted’.


1.1.2 Add reference to Covast ebXML Message Service Adapter propertyschema

This orchestration will set the message context properties to control routing of the message. To make these properties visible to the orchestration, add a reference to the property schema in the BizTalk project as shown in the figure below. The location of the property schema is ‘C:\Program Files\Covast\ebXML Message Service Adapter\Pipeline\CovastEbmsPropertySchema.dll’.


1.1.3 Create the orchestration

The next step is to actually create the orchestration. This orchestration will be created step by step. The figure below shows how to create the orchestration.


1.1.4 Define a message type

The test message content is Xml. To accommodate this we have to create a new message type. This can be done by creating a multipart message, containing 1 part of type System.Xml.Xmldocument. Select the orchestration and go to the Orchestration view, expand types and create a message type as shown in the figure below.


1.1.5 Create messages

After creating the message types, the messages themselves must be created. One that represents the incoming message and another that represents the outgoing message. Both messages are of the type GetingStarted.ebMxmlMessage.


1.1.6 Create receive port

The orchestration starts at the moment a message is received. In BizTalk terminology, it is described as ‘instance activated’. In order to send and receive messages, we must define ports. Right click on the port surface and click ‘New Configured port’. Use the configuration as shown in the figures below.


The next step is to define the message type used for the ports as shown in the figure below.


Note: perform this step for all the ports

1.1.7 Create receive shape

To connect the message to the port, we must to create a Receive shape. Right click on the orchestration and select Receive.


After this, we can assign a message and operation to the receive shape as shown in the figure below.


1.1.8 Create receive shape

After the receive shape is created, we must assign the message that will be submitted to the messagebox. This can be done using a Message Assignment shape. Right click below the receive shape and select ‘Message Assignment’.


Configure the ‘Assign message’ shape to construct the outgoing message ‘clientMessage’ as shown in the figure below.


In the next step we can implement the code to configure the correct CPA by setting the context properties. The code is shown in the figure below and can be copy-pasted.


// CPA is imported from: CPA_gettingstarted_Orchestration.xml

clientMessage = clientRequest;

clientMessage(*) = clientRequest(*);

//configure the context properties based on the CPA

clientMessage(ebMSProperties.Action) = "RequestServiceOne";

clientMessage(ebMSProperties.Cpaid) = "urn:nl:covast:orchdemo:ebms";

clientMessage(ebMSProperties.PartyName) = "OtherParty";

clientMessage(ebMSProperties.ServiceName) =


//send the message to the retry orchestration

clientMessage(ebMSProperties.ToRetry) = true;


1.1.9 Create send port

To submit the message we must create a send port. This port is direct-bound to the BizTalk messagebox because the ebMS orchestrations must process this message later. Create the send port using the configuration steps shown in the figure below.


The next step is to define the message type used for the ports as shown in the figure below.


Note: assign the correct message type

1.1.10 Create correlation

Because the ebMS retry orchestration listens for messages using a direct-bound port with a filter on the property ‘ebMSProperties.ToRetry’, we need to ensure that the property is ‘promoted’ (the value of a property is present in the BizTalk message context at runtime).

We can ensure that this is the case by creating a correlation type and set using the aforementioned property. The configuration is shown in the figures below.

To create a correlation type, perform the following actions:

  • Go to the Orchestration view in the


  • Expand the ‘Types’ node
  • Right click the ‘Correlation Types’ node and click ‘New correlation type’
  • A Correlation properties dialog will appear. Expand the ebMSProperties node.


  • Select the ToRetry property and click Add


  • Click Ok
  • Select the created correlation type and change:
    • Identifier à ‘CorrelationType_ebMS’

To create the correlation set (this is an instance of the correlation type), perform the following actions:

  • Right click on Correlation Set and select ‘New correlation set’
  • Select the create correlation set and change the following information:
    • Identifier à ‘Correlation_ebMSRetry’
    • Correlation Type à select the create correlation type ‘CorrelationType_ebMS’


1.1.11 Create send shape

The final step is to link the port, correlation set and message together using a send shape. Right click on the last element in the orchestration and create a Send shape.


After this, we can assign a message, operation and correlation set to the send shape as shown in the figure below.


  • Choose the initializing correlation Set ‘Correlation_ebMSRetry’
  • Choose the message ‘clientMessage’
  • Change the name to ‘SendToRetryOrchestration’


1.1.12 Deployment setting

After creating the solution, the orchestration must be deployed. Go to the solution properties and configure the deployment settings as shown in the figure below.

BizTalk requires that all assemblies are signed with a strong name. This can be generated, but the GettingStarted package already contains a strong name key. This can be found in:

C:\GettingStarted\Scenarios\Scenario with Orchestration context properties\Solution\ GettingStarted.snk


When the configuration is complete, the solution can be deployed. This will create the application if it did not already exist.

Note: it is recommended to close the BizTalk Administration console during deployment.


1.1.13 Configure the application

When the application is deployed, the orchestration is unbound. This means that the logical ports are not mapped to physical ports. This can be done by opening the orchestration properties in the BizTalk Administration console.

Select the correct receive location as shown in the figure below.


1.1.14 Starting the application

To start the application, perform the following actions:

  • Right click on the application ebMS.GettingStarted
  • Select ‘Start’ from the context menu


  • Select ‘Start’ in the popup dialog


Using the Covast ebMS Adapter (part 2)

As described in my previous post on the Covast ebMS Adapter (part1) there are 2 ways of leveraging the functionality of the ebMS Adapter

1) Pipelines

2) Orchestration

Using pipelines

The ebXML Messaging Service pipeline components can be configured to use a specific collaboration protocol agreement (CPA) when assembling, encrypting and signing or disassembling and authenticating the ebXML message. This configuration is performed when the pipeline is selected for usage in a BizTalk port.

This requires that pipeline properties are configured so that they match the corresponding properties of the collaboration protocol agreement (CPA). The configuration is used at runtime to process messages. When a message arrives, the properties of the message, in addition to the pipeline properties, are used to locate the correct CPA and to apply the settings during message exchange.

For instance: the CPA can dictate the requirement to return an Acknowledge message and the message destination. The CPA is also used to authenticate the point of origin for the message and the identity of the sender.

1) Configure the ebMS Receive pipeline

The receive pipeline removes the message envelope, logs transaction activity to the Communication Tracking Data table, promotes message properties and passes the BizTalk compatible XML message back to the pipeline to be published to the BizTalk messagebox. The configuration phase of the installation process deploys the receive pipeline to the chosen BizTalk application where it can then be selected for use in a receive port.

2) Configure the ebMS Send pipeline

The primary purpose of the ebMS Send Pipeline is to envelope an XML message to meet ebXML transmission standards. The send pipeline serves several additional purposes.

  • Envelopes the BizTalk XML message to meet ebMS messaging standards.
  • Handles message payload encryption and signing.
  • Creates ebMS standard acknowledgements in response to incoming messages.
  • Generates the Ping and Pong message types.
  • Generates detail into the Communication Tracking Data table.

The ebMSSend pipeline uses the CPA contract to determine how to process the message, whether to expect acknowledgements etc.

When a message is passed through a port that uses the ebMSSend pipeline this message will be picked up by the ‘PickupMessagesToSend’ orchestration. This orchestration will set the required retry flag to ensure correct processing and passes the message through to the ‘RetryOrchestration’ that will submit the message to the outbound destination


The properties should match the CPA configuration for the message exchange that is required from the port. The Action and Party determines which configuration record is used and how the message is exchanged.

Note: the URI is overruled in the pipeline based on the CPA configuration

Note2: the ping property can be used to test connections between ebMS parties.

3) Acknowledgements

Messages that need to be acknowledged should be routed to a send port with the ebMSSendpipeline configured. The pipeline recognizes that an acknowledgment should be generated and replaces the payload of the message with the ebXML acknowledgment.

The sendpipeline will use the context properties (ReceiveCPaId,….) to determine the recipient of the acknowledgment. A filter must be added to the send port configuration for the condition “AckResponseNeeded” = “True”.


Using the Covast ebMS Adapter (part 1)

Getting started with the Covast ebMS adapter

The Covast ebMS Adapter for BizTalk Server 2006/2009 is a suite of components that can be used to develop and deploy BizTalk solutions, which require secure and reliable data transmission. A getting started package is included with the demo version of this adapter, using a loopback scenario to demonstrate the usage of this adapter. In this multipart series i will explain the 2 methods of using the adapter.

The Covast ebMS Adapter implements the specifications of ebXML Message Services.

To get started with the ebMS Adapter, the following steps have to be followed:

· Install the adapter

· Define the collaboration protocol agreement

· Configure the adapter using pipelines or context properties inside an orchestration

This part will explain the steps to follow for setting up the adapter….Here we go…

· Install the Covast ebMS adapter

The Covast ebMS Adapter consists of several components that aid in the development of ebMS solutions. The installation process consists of a wizard that installs the necessary components and configuration database. The ebMS Adapter installs resources to a BizTalk application that can be selected during the setup. When the installation is completed the following resources are installed:


· Covast.Ebxml.Retry.PickupMessageToSend

When messages are received, the ebXml Message Service Adapter Orchestration ‘PickUpMessagesToSend’ will process this message and ensure that it is processed and submitted into the message box.

· Covast.Ebxml.Retry.RetryOrchestration

The ebMS standard defines means of reliable messaging by using Acknowledge messages. To ensure that this standard is followed there is an orchestration that picks up messages submitted by the ‘PickUpMessagesToSend’ orchestration. This orchestration tries to send the message to the outbound destination.


· ebMSReceivePipeline.ebMSReceivePipeline

This pipeline is used to decode ebMS messages based on the CPA defined in the steps above.

· ebMSSendPipeline.ebMSSendPipeline

This pipeline is used to encode messages to ebMS messages based on the CPA defined in the steps above.

note: a filter in the port allows to require acknowledge messages; ebMSProperties.AckResponseNeeded == true


· ebMSProperties.CovastPropertyschema

This schema contains all the properties that can be used in the ebMS Adapter.

· Covast.Ebxml.Retry.StatusMessage

Schema that defines a status message.

· Define the collaboration protocol agreement

To be able to communicate between parties, a so called collaboration protocol agreement (CPA) must be configured. This collaboration protocol agreement defines the services and technical implementation between parties; where are the services located, is an acknowledgement required, how many retries are allowed before a message is considered to be failed. This collaboration protocol agreement can be defined in any ebMS supporting tool that is capable of exporting to xml.

To use the collaboration protocol agreement with the ebMS Adapter, the xml file should be imported using the ebMS Administration console.

Each collaboration protocol agreement defines roles, these are used to determine how to


Figure administration console: right click and select ‘Import CPA’ in the context menu


Figure select party: define for which role the CPA is imported



· Configure the adapter using pipelines or context properties inside an orchestration

The message is routed and processed based on the CPA properties. The message properties are contained in the BizTalk ‘message context’. The adapter supports two methods to set the message context properties, using Pipelines and by using an Orchestration to set the context properties….i will describe this in more detail in part2 and part3.

Thursday, November 12, 2009

Use an existing SQL Server for your BizTalk environment

Recently i had the ability to use 2 dedicated development machines, one for setting up BizTalk and i figured to use the other for SQL Server.

I sounds easy enough, be it that there are some steps that you should not forget.

Possible error to look for: “Cannot open database BizTalkMgmtDb on server <dummy>.Verify that you have the required security permissions and that communication between Distributed Transaction Coordinator services on the machines involved is not prevented by current DTC security,   firewall or authentication settings.”

Setting up the machines


o SQL Server is installed

o BizTalk is installed but not configured

Setting up the SQL Server machine

1) Start ‘SQL Server Surface Area Configuration’

o Enable remote connections

(Choose: TCP/IP or TCP/IP and named pipes, disable shared memory)

o Start the SQL Agent

o Start the SQL Browser

2) Start ‘SQL Server Configuration Management’

o Goto ‘Protocols for MSSQL Server’ to enable TCP/IP

· Set Active to ‘Yes’

· Set Enabled to ‘Yes’

· Enable named pipes

3) Configure DTC

a) Start ‘Component Services’

In the control panel, browse to ‘Administrative Tools’\’Component Services’

Right click on properties on the context menu under:

\Component Services\Computers\My Computer\Properties

b) Configure MSDTC

Check the following settings:

· Allow remote connections (remote administration is not required)

· No Authentication required

· Enable XA Transactions

· Enable TIP (not sure is this is required)

for more info see:

Setting up the BizTalk machine

o Manually create the required SSO groups

o For SSO: add user to the SSO Administrators group

o Add authenticated database users to the BizTalk Administrators group

o Repeat steps 3a-b for setting up DTC

Live writer.Enable = true;

Previous posts were published using the WYSIWYG webeditor of, hereby the first post using live writer:

Hello world….