HOW TO: Set Up and Test the BizTalk Adapter for MQSeries (821489)

SUMMARY

Prerequisites

1. Log on to your computer running BizTalk Server as the local Administrator.
2. Install MQSeries Server 5.2 or MQSeries 5.3 on your computer running BizTalk Server. When the installation has completed, run the IBM MQSeries Default Configuration Wizard to set up the Default Cluster and Queue Manager. To run the Default Configuration Wizard, click Start, click Programs, click IBM MQSeries or IBM WebSphere MQ (for MQSeries 5.3), click MQSeries First Steps, and then click Default Configuration.
3. If you have installed MQSeries Server 5.2:
   1. Set the IBM MQSeries Service to Manual, and then restart the computer.
   2. Download and then install CSD04 for MQSeries 5.2. To do this, visit the following IBM Web site:

      ftp://ftp.software.ibm.com/software/mqseries/fixes/winnt52/U200163/U200163A.exe

4. Set the IBM MQSeries Service to Automatic, and then restart the computer.
   
   Note If you do not restart the computer at this step, the BizTalk Adapter for MQSeries will not install correctly.
5. Install the BizTalk Adapter for MQSeries 1.0. To start the setup process, locate the setup folder, and then double-click BizTalkAdapterForMQS.msi. When installation has completed, verify that the BizTalk Adapter for MQSeries service is set to Manual, and then restart the computer.

Set Up BizTalk Server to Send to MQSeries

1. Create a local queue in MQSeries to receive documents from BizTalk Server (for example, FROMBTSTOMQSERIES).
2. In the Messaging Manager, create a BizTalk port that has the following properties:
   • A Name: of ToMQSeries
   • From an Organization
   • Primary Transport is AIC
   • Select AICMQ AIC component from the list
3. Create a channel for the port. Name the channel ToMQSeries, and at the end of the channel wizard, click Advanced to view the Override options dialog box.
4. In the Override options dialog box, click the Primary Transport tab.
5. On the Primary Transport tab, click Properties.
6. In the Properties dialog box, type the following information:
   • Servername The NetBIOS name of the computer running MQSeries (for example, testbox01).
   • Queue Manager The name of the queue manager you are using to hold the queue (for example, QM_testbox01).
   • MQ Series Queue Name The name of the local queue that you created in step 1 (for example, FROMBTSTOMQSERIES).
7. Start the DirectIntegration.exe sample to send a document to the channel that you created in steps 3 through 6. The DirectIntegration sample is located in the \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\DirectIntegration\EXE\ folder on your computer running BizTalk Server. Verify that the document has arrived in the destination MQSeries Local queue. To do this, double-click the queue in the MQSeries Queue Manager.

Set Up MQSeries to Send to BizTalk

1. Open the Microsoft Management Console (MMC) for the BizTalk Adapter for MQSeries.
2. Right-click the MMC, click New, and then click Job.
3. Type the following information:
   • MQSeries Host Name The NetBIOS name of the computer running MQSeries (for example, testbox01).
   • Queue Manager Name The Queue Manager name that was created when you installed MQSeries. Typically, this name is QM_computername (for example, QM_textbox01).
   • Transmission Queue Name This is the name of the transmission queue that is created after this job is exported to MQSeries. To reduce confusion, make this a descriptive name such as XMITTOBIZTALK. This is the MQSeries queue that is used to transmit documents to the BizTalk Adapter for MQSeries mqhelper component.
4. After you create this job, it may be helpful to rename the job. You can use a name for the job that logically represents the mqhelper version of an IBM MQSeries queue manager. The mqhelper uses its version of the queue manager to send documents from MQSeries to BizTalk. Therefore, a name such as BIZTALKQM may be easy to remember.
5. After you create and then rename this job, right-click the job, click All Tasks, and then click Export MQS definitions. Save this job to a file named BIZTALKQM.mqs.
6. At a command prompt, change to the directory where you saved the BIZTALKQM.mqs file.
7. Type the following command at the command prompt, and then press ENTER:
   • For MQSeries Server 5.2, type

     Runmqsc QM_testbox01 BIZTALKQM.mqs output.txt

   • For MQSeries Server 5.3, type

     runmqsc QM_testbox01 < BIZTALKQM.mqs

   Substitute the correct MQSeries queue manager name for QM_testbox01 when you run this command. This command creates two queues in MQ Series, one remote definition queue named BIZTALKQM, and one local MQSeries queue named XMITTOBIZTALK.
8. Right-click the BIZTALKQM remote definition queue, and then click Properties.
9. Type a value for Remote Queue Name. Because BIZTALKQM logically represents the mqhelper version of an IBM MQSeries queue manager, the value for Remote Queue Name logically represents the mqhelper version of an IBM MQSeries queue. It may be helpful to use a descriptive name such as BIZTALKQ.

Create a Channel and a Port in the BizTalk Messaging Manager

Create a Mapping for the Job in the BizTalk Adapter for MQSeries

1. Open the MMC for the BizTalk Adapter for MQSeries.
2. Right-click the BIZTALKQM job, click New, and then click Mapping.
3. Type the following information:
   • MQSeries Queue Name This must be the same as the Remote Queue Name that you used to configure the BIZTALKQM MQSeries remote definition queue in step 9 of the "Set Up MQSeries to Send to BizTalk" section (for example, BIZTALKQ).
   • Channel Name The name of the BizTalk Messaging channel that you want MQSeries to pass the document to (and an envelope if the document is not an XML document). In this example, select the channel that you created in the "Create a Channel and a Port in the BizTalk Messaging Manager" section (for example, ToBizTalk).
   • For this example, enable the Submit with a pass-through flag option because the document that you will be receiving from MQSeries will be only one line of text.
4. Start the BizTalk Adapter for MQSeries Service.

Write a Test Message to the MQSeries Queue

1. On the computer running MQSeries, run the AMQSPUT sample application from a command prompt (the AMQSPUT sample application must be in your path environment variable). AMQSPUT takes two parameters, the queue name (for example, BIZTALKQM) and the MQSeries queue manager name (for example, QM_testbox01).
2. If the AMQSPUT sample application runs successfully, the following output appears:

   Sample AMQSPUT0 start 
   target queue is BIZTALKQM

3. Type a line of text as sample data (for example, This is a test to verify the MQSeries Adapter Receive function), and then press ENTER.
4. View the folder that you specified in the BizTalk Messaging port to file that you created in the "Create a Channel and a Port in the BizTalk Messaging Manager" section to receive documents from MQSeries. A file that contains the text that you typed in step 3 appears in this folder.
5. Press CTRL+C to quit the AMQSPUT sample application.