Monday, January 25, 2010

MQSC Adapter…BizTalk against IBM MQ + SSL

This article will go into detail about one of the possible approaches to connect from BizTalk to IBM MQ.

  • Note: This is not the only or best approach and this article serves as an example for the few out there facing the problem in setting up MQSC Adapter for IBM MQ + Certificates.

For starters i would like to quote a fellow BizTalker that spoke at the BTUG last week and said that in order to do SAP with BizTalk you would have to fulfill requirement #1: ‘Search for a SAP buddy’.

Well although i think this will apply to other adapters as well (e.g. Dynamics AX 2009!) it is a good general rule to have someone at the other side for support. It can get tough!


When communicating with IBM MQ there are a number of scenarios, although i might forget some, i believe the following are possible:

1) MQ Server hosted within your BizTalk environment

This would require the use of the MQSeries Adapter.

2) MQ Server hosted outside your BizTalk environment

This would be possible using 2 implementations:

- MQ Series Bridge as an MQ interface + Internal MSMQ (or another protocol)

- MQSC Adapter that directly communicates with the MQ Server & MQ Client in the BizTalk environment

  • Note: In this article i will discuss the latter, a Microsoft employee informed me later that the MQ Series Bridge is the most flexible and underpriced option when more interfaces are expected in the future.

MQSC Adapter

For my client we were obligated to use MQ, we received a license for the MQ Client (transactional) and received the configuration (tab) file to communicate with the MQ Server.

Although we could have implemented the API of the MQ Client, or extended the example .Net application we figured, why don’t use the free MQSC Adapter included in the ‘BizTalk Server Adapters for Host Systems’ (free in combination with a BizTalk license).

The Adapter assumes a Server on the outbound side that communicates with a MQ Client on the inbound side. The communication on MQ is performed on port 1414, the session is initialized by the client which requires an firewall configuration on port 1414 from inbound to outbound.

To enable communication with the B2B interface (BizTalk) with the MQ Client a dedicated MQ Client Adapter is required. The MQSC Adapter is a component of the ‘BizTalk 2006 - Adapters for Host Systems’ package. This adapter is known to only officially support MQ Client version


In this article the installation is explained, i will go into detail of the relevant steps;

Connection Name

Name of the MQSeries Server that contains the Queue Manager and Queues that the BizTalk Adapter receives messages from. For the TCP transport type, the format to specify is SERVERNAME(PORT). Port number is equivalent to the port number defined in the Listener associated with the Queue Manager.

Value: <ip>(port) e.g.

Channel Name

Name of the channel defined on the MQSeries Server computer that the client communicates with. This must be a ‘Server Connection’ Channel type (case sensitive property).


MQSeries queue from which the adapter will receive (MQGet) or send messages to (MQPUT).

Queue Manager

Name of MQSeries Queue Manager that contains the Queues from which the adapter will retrieve messages.


When using SSL in a scenario where the outbound is responsible for the Server this means that;

- Client certificates are provided by this party

- User for which the client certificates are requested MUST BE the same user under which BizTalk host the Adapter runs!*

- SSL Key repository is the most flexible and easy way to configure the certificates (no client installation required, only the path to the SSL Key repository has to be configured

The following additional adapter settting must be configured

- SSL Cipher specification

This is a fixed value, defining the algorithm e.g. : NULL_MD5

- SSL Key Repository location

This is the location where the repository is stored.

  • Note: do not provide the extension, only provide the path in the form of C:\SSL\qmkeys

- SSL Peer name

This is a fixed value, this should be provided to you by the party that provided the key repository.


Since the certificate is requested for a specific user, this user must also set up the connection, otherwise the certificate can not be found. Since we use MQ through the MQSC Adapter, the host under which this adapter runs must also run under this user.

Reference [Error codes]

Relevant facts

- Only version of the MQ Client is supported due to adapter limitations.

- The Certificates should be provided by the external party

- The required port for MQ Communication 1414 is configured in the firewall that communicates from inbound to outbound. Because the MQ Client initiates communication the firewall doesn’t have to be configured bi-directional (this might make some administrators less worried about security ;)

- The Certificates are requested for a specific user, this has the implication that all future MQ communication must be set up for this specific user!

- Due to the aforementioned restriction the MQSC Adapter should run under the user specified in the certificate.

  • After contact with Microsoft the suggested approach when multiple parties require MQ Communication, is to introduce a MQ Bridge.

This means that outside the BizTalk environment MQ is used between the Bridge and the customer and internally MSMQ is used to communicate between the BizTalk environment and the Bridge.

  • Additional advantages: MQBridge is included in the BizTalk license / Extended MQClient is costly.


Suggestions to setup the communication

- MQ Client incorporates some command line tools (PUTC / GETC) to test the channel.

- Telnet can indicate whether communication is possible

- When ‘standard’ BizTalk-IBM MQ communication has been achieved, it does not mean you are there, the extra effort for SSL might consume more time than initial communication!

- A trial MQ Server can be used to understand MQ Client / Server architecture

- When using SSL first determine under which account you want to run the Adapter (forever!) and communicate this with all client

- Keep in mind that when multiple MQ clients are expected in the future the MQ Bridge is the logical way to implement MQ Communication

- Find an IBM MQ Buddy :)


Have fun!

No comments: