wm6431-vm6431xinst

V5.4

cover

Front cover

IBM WebSphere Message Broker V7.0 System Administration Workshop (Course code WM643 / VM643)

Instructor Exercises GuideERC 1.0

WebSphere Education

Instructor Exercises Guide

Trademarks

IBM® is a registered trademark of International Business Machines Corporation.

The following are trademarks of International Business Machines Corporation in the United States, or other countries, or both:

VMware® and the VMware “boxes” logo and design, Virtual SMP and VMotion are registered trademarks or trademarks (the “Marks”) of VMware, Inc. in the United States and/or other jurisdictions.

Adobe is either a registered trademark or a trademark of Adobe Systems Incorporated in the United States, and/or other countries.

Intel, Intel Core, Itanium and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Linux® is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT and Windows Vista are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX® is a registered trademark of The Open Group in the United States and other countries.

Other product and service names might be trademarks of IBM or other companies.

AIX® CICS® DataPower®DB2® developerWorks® Everyplace®HACMP™ IMS™ Informix®Language Environment® MQSeries® Notes®POWER® Rational® Redbooks®System z® Tivoli® VisualAge®WebSphere® z/OS® zSeries®

November 2010 edition

The information contained in this document has not been submitted to any formal IBM test and is distributed on an “as is” basis without any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer responsibility and depends on the customer’s ability to evaluate and integrate them into the customer’s operational environment. While each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will result elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk.

© Copyright International Business Machines Corporation 2010.This document may not be reproduced in whole or in part without the prior written permission of IBM.Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Instructor Exercises GuideV5.4.0.1

TOC
Contents
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Instructor exercises overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Exercises configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Exercises description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Exercise 1. WebSphere Message Broker setup and customization . . . . . . . . . . . . 1-1

Exercise 2. Using the WebSphere Message Broker Toolkit . . . . . . . . . . . . . . . . . . . 2-1

Exercise 3. Administering the broker runtime components . . . . . . . . . . . . . . . . . . 3-1

Exercise 4. Administering broker security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Exercise 5. Using trace facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Exercise 6. Identifying runtime problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Exercise 7. Accessing broker statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Exercise 8. Implementing web services and web services security . . . . . . . . . . . . 8-1

Exercise 9. Implementing a user-defined extension . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

Appendix A. Exercise solutions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

©Copyright IBM Corp. 2010 Contents iii



iv Message Broker System Administration ©Copyright IBM Corp. 2010

Instructor Exercises GuideV5.4

TMK
Trademarks
The reader should recognize that the following terms, which appear in the content of this training document, are official trademarks of IBM or other companies:

IBM® is a registered trademark of International Business Machines Corporation.

The following are trademarks of International Business Machines Corporation in the United States, or other countries, or both:

VMware® and the VMware “boxes” logo and design, Virtual SMP and VMotion are registered trademarks or trademarks (the “Marks”) of VMware, Inc. in the United States and/or other jurisdictions.

Adobe is either a registered trademark or a trademark of Adobe Systems Incorporated in the United States, and/or other countries.

Intel, Intel Core, Itanium and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Linux® is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT and Windows Vista are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX® is a registered trademark of The Open Group in the United States and other countries.

Other product and service names might be trademarks of IBM or other companies.

AIX® CICS® DataPower®DB2® developerWorks® Everyplace®HACMP™ IMS™ Informix®Language Environment® MQSeries® Notes®POWER® Rational® Redbooks®System z® Tivoli® VisualAge®WebSphere® z/OS® zSeries®


© Copyright IBM Corp. 2010 Trademarks v



vi Message Broker System Administration © Copyright IBM Corp. 2010


pref
Instructor exercises overview
The objectives of the exercises are for the students to successfully:

• Configure and customize a broker

• Perform the following functions:

- Use various administrative commands

- Back up and recover broker components

- Establish a publish/subscribe environment to collect statistics

- Use various problem determination tools and aids

- Set up SSL to use with web services

- Implement a user-defined extension

Many of the exercises depend on the previous exercises being successfully completed.

The objectives of these exercises are to have the students successfully configure the broker and run the administrative commands to successfully operate the broker.


© Copyright IBM Corp. 2010 Instructor exercises overview vii



viii Message Broker System Administration © Copyright IBM Corp. 2010


pref
Exercises configuration
In the exercise environment, individual students typically have their own systems and work independently.

Lab exercise files are provided in the C:\Labs directory.


© Copyright IBM Corp. 2010 Exercises configuration ix



x Message Broker System Administration © Copyright IBM Corp. 2010


pref
Exercises description
This course includes the following exercises:

• Broker setup and customization

• Using the WebSphere Message Broker Toolkit

• Administering the broker runtime components

• Administering broker security

• Using trace facilities

• Identifying runtime problems

• Accessing broker statistics

• Implementing web services and web services security

• Implementing a user-defined extension

In the exercise instructions, each step is prefixed by a line. Check off each step as you complete it to track your progress.

Most exercises include required sections which should always be completed as they might be required before performing later exercises. Some exercises might also include optional sections that you might want to perform if you have sufficient time and want an additional challenge.


© Copyright IBM Corp. 2010 Exercises description xi



xii Message Broker System Administration © Copyright IBM Corp. 2010


EXempty
Exercise 1. WebSphere Message Broker setup and customization
Estimated time

01:00

What this exercise is about

This exercise takes you through some of the installation and related setup procedures for WebSphere Message Broker V7.0.

What you should be able to do

At the end of the exercise, you should be able to:

• Configure a Windows XP system for use with IBM WebSphere Message Broker V7

• Get build and version information on all WebSphere Message Broker components

• Set up basic security

• Create a broker and execution group

• Navigate the workbench help function

Introduction

In this exercise, you set up a system to run WebSphere Message Broker V7.0. As a final step, you start a WebSphere Message Broker Toolkit (workbench) instance and examine the help function. Additional setup tasks are performed in Exercise 2.

Instructor hint

Sometimes, students make typographical errors with queue manager names during the creation of WebSphere Message Broker components. There are commands that you can use to review the current settings of the component services:

•mqsilist

•mqsiservice <broker_name>


© Copyright IBM Corp. 2010 Exercise 1. WebSphere Message Broker setup and customization 1-1


Mismatched parameters can sometimes be corrected with the mqsichange command. Otherwise, it might be necessary to delete the component (mqsidelete command) and recreate it (mqsicreate command).

Instructor note: Installed software versions

The base image for WM643 ERC 1.0 (September 2010) was created with the following product versions:

• WebSphere Message Broker V7.0.0.1 • WebSphere Message Broker Toolkit V7.0.0.1 • WebSphere MQ V7.0.1. • RfhUtil Build 7.0.2


1-2 Message Broker System Administration © Copyright IBM Corp. 2010


EXempty
Exercise instructions
A number of required programs, already installed on your system, include:

• WebSphere Message Broker • WebSphere Message Broker Explorer • WebSphere Message Broker Toolkit • WebSphere MQ

Your user ID has been registered with the Windows system as a member of the Administrators group.

The development default configuration with a broker named MB7BROKER and queue manager of MB7QMGR are already installed.

Important

Before you start any lab exercise, log in to your VMware Windows session with your Administrator user ID. The password is web1sphere

For all exercises in this course, use the names listed in the following table. All names are case-sensitive.

In addition, a directory (C:\Labs) has been set up that contains test tools, test files, and similar material.

Part 1: Getting build and version information

It is important to know the current software version and build level for all your software. In this part of the exercise, you verify the maintenance (fix pack) levels of the WebSphere Message Broker environment software.

User ID Administrator

Password web1sphere

WebSphere Message Broker installation directory

c:\Program Files\IBM\MQSI\7.0\

WebSphere MQinstallation directory

c:\Program Files\IBM\Websphere MQ

WebSphere Message Broker name DEVBROKER

WebSphere Message Broker queue manager name and listener port number

DEVQMGR, port 1416




__ 1. Get the software version information for the WebSphere Message Broker Toolkit.

__ a. Click Start > Programs > IBM WebSphere Message Broker Toolkit > WebSphere Message Broker Toolkit 7.0 > IBM WebSphere Message Broker Toolkit.

Note

You can also start the WebSphere Message Broker Toolkit from a command line as follows:

a. Start a Command Console session and change to the WebSphere Message Broker Toolkit directory C:\Program Files\IBM\WMBT700

b. Enter the following command: eclipse -product com.ibm.etools.msgbroker.tooling.ide

__ c. In the Workspace Launcher window, enter C:\Workspace\WMBAdmin for the workspace name, and then click OK.

__ d. After the toolkit starts, select Help > About WebSphere Message Brokers Toolkit - Message Broker. A window displays version information.

The Build ID identifies the latest fix pack that has been applied. In this example, the build ID is 7.0.0.1, IFIX 1 dated September 07 2010 (20100907).




EXempty
__ e. Click Configuration Details to display a text file containing WebSphere Message Broker Toolkit installation and version information. This file can be copied to a clipboard and archived.
Click Close to close the configuration details.

__ f. Click OK to close the About WebSphere Message Broker Toolkit window.

__ g. Leave the toolkit open (minimize it if you want), since you use it later in this exercise.

__ 2. Get the software version information for the WebSphere Message Broker.

__ a. Start a WebSphere Message Broker command console session by selecting Start > Programs > IBM WebSphere Message Broker > Command Console.

Important

When WebSphere Message Broker is installed, a special command console is also installed from which you run WebSphere Message Broker commands. It is a Windows command shell, but it sets a number of environment variables when it is started.

When the exercise instructions direct you to start a command console session, you cannot use a standard Windows Command Prompt window in its place.

__ b. Run the command: mqsiservice -v The response message should contain the version, product, level, and build type.

The “Version” and “CMVC Level” fields identify the latest fix pack that has been applied. In the example, the version is 7001; that is, Version 7.0.0.1. The fix pack is FixPack1 (FP01)




__ 3. Get the software version information for WebSphere MQ Explorer (and WebSphere Message Broker Explorer).

__ a. Select Start > Programs > IBM WebSphere MQ > IBM WebSphere MQ Explorer.

__ b. Select Help > About IBM WebSphere MQ Explorer.

The version information window is displayed.

Version indicates the product version number. In this example, the version is 7.0.

__ c. Click Configuration Details to open a text file containing detailed version and installation information that can be copied to a clipboard and archived.

Click Close to close the Configuration Details window.

__ d. Click OK to close the About IBM WebSphere MQ Explorer window.

__ e. Leave the WebSphere Message Broker Explorer open (minimize it if you want), since you use it in the next step.

__ 4. Get the software version information for WebSphere MQ.

__ a. In the WebSphere Message Broker Explorer (WebSphere MQ Explorer) Navigator view, click IBM WebSphere MQ to highlight it, then right-click and select Properties.

__ b. Click the Configuration information selection. The Configuration information window is displayed.




EXempty

The MQ Version parameter shows the latest fix pack that has been applied. In the example, the version is 7.0.1.0.

__ c. Click OK to close the window.




Part 2: Set up authorizations

__ 1. To administer the broker component, the broker service ID must be a member of the mqbrkrs security group. In this part of the exercise, you will verify that the mqbrkrs security group exists on your system and that your Administrator account is a member. If the mqbrkrs group cannot be found, you will create it and add your Administrator account as a member of that group.

__ a. Open Windows Computer Management by selecting Start > Settings > Control Panel > Administrative Tools > Computer Management.

__ b. Expand Local Users and Groups under the System Tools folder and select Groups.

__ c. If you are using the VMware image for this course, the mqbrkrs group exists.

Double-click the mqbrkrs group and verify that Administrator is listed as a member of the group.

Information

If you are not using the VMWare image for this course, and the mqbrks group does not exist, you can add it and then add your user ID to the Members list.

1. Right-click Groups and select New Group from the menu.

2. Enter mqbrkrs in the Group name field.

3. Click Add

4. Enter your account ID as the object name.

5. Click OK,

6. Click Create.

__ d. Click Cancel to close the mqbrkrs Properties window, but leave the Computer Management window open.

__ 2. The broker service ID must be a member of the Windows administration group mqm (which is created automatically during WebSphere MQ installation).

__ a. Verify that your user ID is a member of mqm group.

__ b. If necessary, add your account (Administrator) to group mqm.

__ c. Close the Computer Management window.




EXempty
__ 3. The service ID used to create the WebSphere Message Broker components must be authorized by the operating system to create services. To set (or verify) your user ID authorization:
__ a. Select Start > Settings > Control Panel > Administrative Tools > Local Security Policy

__ b. Expand Local Policies.

__ c. Select User Rights Assignment.

__ d. Double-click Act as part of operating system.

__ e. Verify that your user ID (Administrator) is in the list.

If it is not, click Add User or Group, enter your user ID (Administrator) as the object name, and then click OK.

__ f. Click OK to close the Act as part of operating system properties window.

__ g. Close the Local Security Settings window.

__ h. Close the Administrative Tools window.

Note

The mqsisetsecurity command can be used instead to create the Windows groups that WebSphere Message Broker requires for secure access to its runtime libraries and data.

Part 3: Create and set up WebSphere MQ queue managers

Developers can create a default broker (MB7BROKER) and queue manager (MB7QMGR) using the Default Configuration wizard. The default configuration has already been created on the VMware image for this course.

In this part and the next part of the exercise, you manually create a development broker and a queue manger named DEVQMGR, with a dead-letter queue and a listener on port 1416.

__ 1. Click Start > Programs > IBM WebSphere MQ > WebSphere MQ Explorer.

__ 2. When the WebSphere MQ Explorer window opens, right-click Queue Managers and then select New > Queue Manager.

__ 3. For the Queue manager Name, enter: DEVQMGR

__ 4. For the Dead-letter queue, enter: DEVQMGR.DLQ

__ 5. Click Next.

__ 6. For pages 2 and 3, make no entries; click Next.

__ 7. On page 4 of the Create Queue Manager wizard, check Create Listener configured for TCP/IP. For Listen on Port Number, enter 1416




__ 8. Click Finish.

Note

If you do not explicitly create the queue manager, the first mqsicreatebroker command that is issued automatically creates the queue manager that you specify in the command. However, many pertinent queue manager parameters are missing, for instance:

• A dead-letter queue is not assigned. • A listener is not activated. • The queue manager does not start automatically. • The queue manager is not the default.

To add the missing parameters, open the IBM WebSphere MQ Explorer (if not already open) and perform the following steps:

__ a. Right-click the top-level element in the Navigator view (that is, IBM WebSphere MQ) and select Properties. To make your queue manager the default, on the General page, type the name of your newly created queue manager in the space labeled Default queue manager name. Click Apply and then click OK.

__ b. From the Navigator view, right-click your new queue manager and select Properties.

__ c. On the General page, select Automatic from the Startup pull-down menu. Set the Type to Automatic

__ d. On the TCP page, set the TCP Port to 1416

__ e. Exit the Properties pages by clicking OK.

__ f. From the Navigator view, expand the Advanced options for your queue manager and select Listeners. Right-click and select New > TCP Listener.

__ g. A wizard starts, first asking you to name your listener; supply the name DEVQMGR.LISTENER and click Next.

__ h. On the General page, type over the zero for Port with 1416 and click Finish.

__ 9. Verify the results by examining the state of the queue manager in the WebSphere Message Broker Explorer.




EXempty
Part 4: Create a broker
Note

For the following steps, use a WebSphere Message Broker command console session. Remember that command arguments are case-sensitive.

__ 1. Enter the following command to create a broker named DEVBROKER on queue manager DEVQMGR using service ID Administrator. and password web1sphere:

mqsicreatebroker DEVBROKER -i Administrator -a web1sphere -q DEVQMGR

__ 2. Enter the following command to modify (reduce) the broker configuration timeout (-g) and configuration delay timeout (-k). The default values (300 seconds and 60 seconds) are too large for a local development environment.

mqsichangebroker DEVBROKER -g 60 -k 15

Part 5: Verify setup and start components

__ 1. Using the WebSphere Message Broker command console, list the local components and check the broker name, queue manager name, configuration timeout, and delay timeout by entering the following commands:

mqsilistmqsiservice DEVBROKER

__ 2. Start the broker service by entering the following command:

mqsistart DEVBROKER

It is also possible to start the components from the Windows Services application.

The Windows Services application also permits the startup property to be set to Automatic so that the services start automatically when Windows starts.

__ a. Click Start > Settings > Control Panel > Administrative Tools > Services.

__ b. Right-click IBM WebSphere Message Broker component DEVBROKER and select Properties > Startup type.

__ c. Set the Startup type to Automatic

__ d. Click OK.

__ e. Close the Services Control Panel window.

__ 3. From a WebSphere Message Broker command console, enter the following command to verify the broker and components.

mqsicvp DEVBROKER




You should see a number of successful verification messages for the broker and the broker queues.

__ 4. Verify that the services started correctly by examining the local error log using the Windows Event Viewer.

__ a. From Windows, select Start > Settings > Control Panel > Administrative Tools > Event Viewer.

__ b. Select the Application log view and examine the most recent entries.

Entries from the WebSphere Message Broker are identified in the Source column with the string WebSphere Broker V7nnn.




EXempty
Part 6: Create an execution group
__ 1. Enter the following command to create an execution group named EXGRP1 on the broker DEVBROKER:

mqsicreateexecutiongroup DEVBROKER -e EXGRP1

Note

As an option, you can create the execution group in WebSphere Message Broker Explorer by right-clicking the broker under the Brokers folder, selecting New > Execution group, and then entering the execution group name.

__ 2. Open WebSphere Message Broker Explorer, if it is not already running, and verify that the execution group has been created and is running.

__ 3. Check the messages in the Application log in the Event Viewer for the messages that indicate the execution group has been created and started.

Part 7: Explore the help system

__ 1. Take the quick tour of WebSphere Message Broker.

__ a. In the WebSphere Message Broker Toolkit Welcome page, select the Get Started (globe) icon. You are offered the option to Take the Quick Tour.

Note

If the Welcome window is not open already, select Help > Welcome.

__ b. Click Take the Quick Tour and follow the instructions to take the animated tour.

__ 2. Familiarize yourself with the WebSphere Message Broker Help system.

__ a. From the menu bar, select Help > Help Contents.

This method for accessing the Help System opens a separate window for the Information Center.

__ b. Close the Welcome window.

__ c. In the WebSphere Message Broker Toolkit, change the focus (either hover the mouse pointer or left-click) to an object or view in the workbench (such as a view title) and press F1 on the keyboard.

This method opens topics related to the current location of your cursor. You can double-click the tab to expand the view within the WebSphere Message Broker




Toolkit window. Double-clicking the tab a second time returns the window to its original size and location in the toolkit.

END OF EXERCISE




EXempty
Exercise review and wrap-up
This exercise provided an opportunity to set up the various WebSphere Message Broker components. It might take you some time to really grasp what each component does.

Additionally, the exercise provided the chance to set up the workspace and start the WebSphere Message Broker Toolkit. You will be using the WebSphere Message Broker Toolkit in later exercises, which are intended to familiarize you with the features and functions it provides.




EXempty
Exercise 2. Using the WebSphere Message Broker Toolkit
Estimated time

01:00


The WebSphere Message Broker Toolkit provides the developer with a number of administrative functions for the development environment. In this exercise, you will become familiar with the basic administrative tasks that can be performed in the WebSphere Message Broker Toolkit.


At the end of the exercise, using only the WebSphere Message Broker Toolkit, you should be able to:

• Establish a connection to a broker

• Import, deploy, and test a message flow

Introduction

WebSphere Message Broker V7 administration is performed through the WebSphere Message Broker Explorer, and command-line interface. Some basic administration functions are available in the WebSphere Message Broker Toolkit.

In this exercise, you use the WebSphere Message Broker Toolkit to perform some basic post-installation configuration tasks. You also import, deploy, and test a message flow so that you have a good understanding of the administration tasks that are usually performed by a developer.

The message flow you use in this exercise matches the message flow seen in the lecture material. The message flow is already written. The message flow is shown in the following figure.


© Copyright IBM Corp. 2010 Exercise 2. Using the WebSphere Message Broker Toolkit 2-1


The intent of this simple message flow is to accept a basic XML message from a WebSphere MQ queue of the form:

<InMsg><Version>2</Version></InMsg>

The message flow then validates the value of <Version> in a filter node as follows:

• If <Version> equals 2, send the message out the True terminal, add a current time stamp, and return the augmented message to the caller through a reply-to queue (EX2_REPLY queue)).

• If <Version> equals 1 or 3, send the message out the False terminal to the FALSEQ node (FALSE queue).

• If <Version> does not equal 1, 2, or 3, send the message out the Unknown terminal to the UNKNOWNQ node (UNKNOWN queue).

You complete the exercise by deploying and testing with a provided message flow. You deploy and test using the WebSphere Message Broker Toolkit; first by importing a broker archive (.bar) file and then testing the message flow.

If the incoming message contains the string <Version>2<Version>, the resulting transformed message should contain the addition of a time stamp, that is:

<OutMsg> <Version>2</Version> <TimeIs>current time stamp</TimeIs> <DateIs>current date stamp</DateIs> </OutMsg>




EXempty
Required materials
The exercise requires the fully configured workstation from Exercise 1. Exercise 1 must be completed successfully before this exercise can be attempted.

Instructor exercise overview

Introduce this exercise as one intended to do nothing more than to give the student an exposure to a message flow and the administration options available to the developer.

The exercise is structured in four parts. Since Unit 3 is a rather large lecture unit, you can begin this exercise after completing Topic 2. The sections on post-install activity and message flow familiarization (Parts 1 and 2) can be assigned independently of the later two sections on deployment and testing (Parts 3 and 4). In this manner, students are offered a break between lecture and exercise and have the opportunity to work on the exercise while the corresponding lecture material is still fresh in their minds.

Encourage the students to work through the exercise with their Student Notebooks open to the lecture page that corresponds to the step they are working on. By comparing the images on their workstation with the screen captures included in the Student Notebook, they can obtain immediate feedback that they are progressing through the exercise in a positive manner. If they make a mistake, their error should become immediately obvious, giving them a chance to make corrections before the error cascades into a disaster.

The optional portion of the exercise is for those students that complete the exercise ahead of schedule. Time has not been allotted in the agenda for the optional portion of the exercise.





Notes

• This exercise presumes successful completion of Exercise 1. Consult with your instructor if you have doubts about your success with Exercise 1.

• Having completed Exercise 1, an instance of the WebSphere Message Broker Toolkit should be running.

• This exercise maps directly to the order of the lecture material as it appears in Unit 3 of your Student Notebook.

Part 1: Work with a simple message flow

Hint

See topic 2 of Unit 3 in your Student Notebook.

__ 1. Import a message flow project into your workspace.

__ a. Switch to the WebSphere Message Broker Toolkit, and, if not already open, open the Broker Application Development perspective. One way is to click Window > Open Perspective > Other > Broker Application Development.

__ b. From the menu bar, select File > Import.

__ c. In the Import window, expand Other.

__ d. Click Project Interchange from the list and then click Next.

__ e. Click Browse next to From zip file and go to the C:\Labs\Lab2\resources directory.

__ f. Click EX2_PROJECT.zip and then click Open.

__ g. Check EX2_PROJECT.

__ h. Click Finish.

WebSphere Message Broker imports the project and constructs the workspace. The EX2_PROJECT should now appear in your Broker Development navigator view.

__ 2. Expand the EX2_PROJECT by clicking the plus (+) sign and examine its contents. Double-clicking an object in the Navigator view causes the corresponding editor to open the object in the editor pane.

__ a. Fully expand the Flows subtree in the Broker Development navigator until the message flow file Ex2Flow.msgflow is displayed.




EXempty
__ b. Open the Message Flow editor by double-clicking Ex2Flow.msgflow. The Message Flow editor initializes in the Editor pane.
__ 3. Examine the message flow. Verify that it agrees with the figure that appears at the beginning of the exercise.

__ 4. The properties of each node in the message flow have been preset to perform the transformation described in the beginning of the exercise. Node properties should agree with the following table.

__ a. You can verify (or change) a property by right-clicking a node and selecting the Properties view.

__ b. Node properties are grouped in pages. The Basic page is initially visible.

Part 2: Deploy a message flow with a broker archive file

Hint


__ 1. The project you imported does not contain a Broker Archive file (.bar).

Import the broker archive file, Ex2.bar, that contains the Ex2Flow.msgflow in a form suitable to be delivered to a broker.

__ a. From the menu bar, select File > Import.

Node name Node type Properties

EX2_IN MQInput (Basic) Queue name = EX2_IN(Input Message Parsing) Message Domain =XMLNSC (Advanced) Transaction mode = Yes

TraceExList Trace (Basic) Destination = User Trace

REPLYQ MQReply no changes

FAILUREQ MQOutput (Basic) Queue name = FAILURE

Test_Version=2 Filter ESQL (see node properties)

Add_Date_Time Compute ESQL (see node properties)

CATCHQ MQOutput (Basic) Queue name = CATCH

UNKNOWNQ MQOutput (Basic) Queue name = UNKNOWN

FALSEQ MQOutput (Basic) Queue name = FALSE




__ b. In the Import Select window, expand General.

__ c. Click File System from the list and then click Next.

__ d. Click Browse for the From directory and go to the C:\Labs\Lab2\resources directory.

__ e. Click OK.

__ f. Check the box next to Ex2.bar. Use the second Browse button (beside the Into Folder text entry box) to go to your workspace, select the EX2_PROJECT, and then click OK.

__ g. On the Import File System window, click Finish.

WebSphere Message Broker imports the broker archive file into the project under the Broker Archives subtree.

__ 2. Examine the BAR file, Ex2.bar, that contains the Ex2Flow.msgflow in a form suitable to be delivered to a broker:

__ a. In the Navigator, fully expand the Broker Archives subtree.

__ b. Open the Broker Archive editor by double-clicking the file Ex2.bar.

__ c. The Broker Archive editor should open on the Manage tab; if not, click the Manage tab to show the BAR file contents.

The top-level component in the BAR file is the compiled message flow (.cmf).

__ d. View the contents of message flow file by clicking the plus (+) sign. The BAR file should contain one message flow named Ex2Flow.

__ e. View the contents of message flow by clicking the plus (+) sign next to Ex2Flow. You should see an entry for each node in the message flow. The nodes are listed in alphabetic order.

__ f. Look at the contents of the Properties tab as you click each node in the Broker Archive editor. These are the node properties that can be overridden in the BAR file.

__ 3. Deploy the broker archive file (.bar) from the Broker Development Navigator view.

__ a. In the Broker Development Navigator view, right-click Ex2.bar and then select Deploy from the context menu.

__ b. Select the execution group named EXGRP1 as the target for the deployment.

__ c. Click Finish.

A Deploying message should be displayed.

__ 4. Verify success through the WebSphere Message Broker Toolkit using the Brokers view and the Deployment log.

__ a. Click the Brokers tab.




EXempty
__ b. Expand the Brokers tree in the Brokers view until you see the message flow, Ex2Flow, as a child element of the EXGRP1 execution group for broker DEVBROKER.
If the icon next to message flow is a green, up arrow, the flow has been successfully deployed and is running.

If the icon is a yellow triangle, examine the Problems view (to the right) for additional status information. It might be that the message flow is deployed but not yet running. The icon might disappear on its own (it might take several seconds) or the flow might require a manual start (right-click Ex2Flow and select Start).

__ c. Click the Deployment log tab. The Deployment log shows whether the BAR file has been deployed successfully.

__ d. Expand the message in the Deployment log by clicking the plus sign (+). BIPnnnns messages preceded with a blue icon imply success; a yellow icon serves as a warning, and a red icon indicates a failure.

Part 3: Test the message flow

There are two main test tools available for testing message flows: the WebSphere Message Broker Toolkit Integrated Test Client and RfhUtil. For this exercise, you will use WebSphere Message Broker Explorer and the RfhUtil program contained in SupportPac IH03.

Hint


__ 1. Use the WebSphere MQ runmqsc command to define the queues required for this exercise. A script has been prepared for this purpose.

__ a. Start a WebSphere Message Broker command console.

__ b. Change to the C:\Labs\Tools directory: cd C:\Labs\Tools

__ c. Enter the command: runmqsc DEVQMGR < Ex2_Q_Defs.txt

__ d. Examine the screen and verify success. The following queues required by the message flow should have been created: EX2_IN, EX2_REPLY, FAILURE, UNKNOWN, FALSE, and CATCH. A seventh queue, EX6_IN, used in a later exercise is also created.

__ 2. The message flow is waiting for a message to appear on the EX2_IN queue. After it does, the message flow dequeues the message and sends it through the message




flow. You use RfhUtil to read a message from a file and put the message on the queue to start the process.

__ a. In the WebSphere MQ Explorer navigator pane, under the DEVQMGR queue manager, click Queues.

__ b. Examine the EX2_IN queue. The Open input count value is 1. This means that an application (message flow) is waiting for a message to be put on that queue.

__ 3. Start RfhUtil by double-clicking rfhutil.exe in the C:\Labs\Tools directory or the shortcut icon on the Windows desktop.

__ 4. Enter the following parameters on the Main tab in RfhUtil:

• Queue Manager Name: use the drop-down list to select DEVQMGR • Queue Name: use the drop-down list to select EX2_IN

__ 5. Click Open File. A file selection window is displayed.

__ 6. Go to C:\Labs\Lab2\data, select the file Test_V2_msg.xml, and then click Open.




EXempty
__ 7. The RfhUtil Main tab should now be displayed.
The message reports that 35 bytes were read from the file.

__ 8. Examine the data that was read into RfhUtil by switching to the Data tab.

The input file name and byte count are displayed in the message above the data display window. Based on the format, the data appears to be XML. To the right of




the data window is a set of radio buttons labeled Data Format. Select XML and note how the data format changes. Try some of the other formats to see the other formats that are available.

__ 9. In the message flow, the REPLYQ message flow node is an MQReply node. A message routed to an MQReply node must have an MQ queue name included in the message (as part of the MQMD) so that the MQReply node knows where to send the message.

You can specify that value (and any other MQMD values) in RfhUtil in the MQMD tab. Switch to the MQMD tab.

For Reply To Queue, enter: EX2_REPLY.

__ 10. You are ready to send the test message to the queue for processing by the message flow. Before you do, re-examine the message flow diagram. Given the test data that you are about to send to the queue, what do you think the message flow will do with the message? Where will the message end up? ________________________________________________________________ _______________________________________________________________

__ 11. To send the test data:

__ a. Switch to the Main tab.

__ b. Since you want to write the test data to the queue you have specified, click Write Q. Note the message that reports the number of bytes written and to which queue.

__ 12. Based on your answer to step 10, where did the message go? The possible destination queues are EX2_IN, EX2_REPLY, UNKNOWN, FALSE, CATCH, and FAILURE.

Use WebSphere MQ Explorer to determine the location of your test message. One way to determine which queue was the destination is to examine the Current queue depth column. A queue depth greater than zero indicates a message is waiting on that queue, as shown here:

Reminder: WebSphere MQ Explorer automatically refreshes its display. The default refresh interval for queue managers is 15 seconds. (To change the refresh interval, right-click the queue manager you want to change in the Navigator view and select




EXempty
Select Refresh Interval. Enter the wanted refresh frequency in seconds and click OK.)
__ 13. You can browse the data in the queue using either WebSphere MQ Explorer or RfhUtil:

__ a. To browse using WebSphere MQ Explorer:

• Right-click the queue to be browsed • Click Browse messages

__ b. To browse using RfhUtil:

• Click the desktop shortcut icon to start a second instance of RfhUtil (you can use the instance you already have open, but when you are testing and working with several queues at one time, it can be more efficient to have a separate instance of RfhUtil open for each queue you are working with).

• Enter the queue manager and queue name you want to browse.

• Click Browse Q. Note the message that appears to report the size of the message you are browsing. You can instead click Read Q instead of Browse Q. What is the difference between the two operations? ______________________________________________________________ _____________________________________________________________

• Switch to the Data tab to view the data. Again, click the appropriate Data Format radio button to display the data in the wanted format.

Using this test data, the resulting message should appear as follows:


__ 14. The message should have appeared on the EX2_REPLY queue. If your message is not on EX2_REPLY, perform the following checks:

- Is the message still on the EX2_IN queue?

YES NO • Is there a message flow running that

consumes messages from EX2_IN (Open Input Count= 1)?

• The message flow might be deployed, but in a stopped state. Check the Brokers view in the WebSphere Message Broker Toolkit or WebSphere MQ Explorer. Examine the icon next to the message flow. If necessary, start the message flow.




- Is the message on the CATCH queue? If so, check the Windows Event Log to determine the cause of the runtime error.

- Is the message on the FALSE or UNKNOWN queue? If so, check your test message. Is the <Version> field present? Does <Version> = 2?

__ 15. Test your message flow with the other test files that exist in the C:\Labs\Lab2\Data directory.

Given the data in the message you submit for each test, you should be able to predict how the message flow will process the message and where the message ends up.

__ 16. As a further test, use WebSphere MQ Explorer to set the Put Message property of the EX2_REPLY queue to Inhibited; then repeat the test using the original (<Version> =2) test message. To what queue will your message be routed? Where else might your message end up? Can you explain why? The upcoming unit on Problem determination will help with the answer.

__ 17. After you have completed testing, stop the message flow by right-clicking the message flow in the Brokers view and selecting Stop from the menu.

__ 18. Remove the message flow from the execution group by right-clicking the message flow in the Brokers view and selecting Delete from the menu.

END OF EXERCISE

• Is the message backout counter > 0 and increasing?

• If Open Input Count for EX2_IN = 0, but the deployment was successful, then you might have a typographical error in the input queue name of the MQInput node. This should also be visible in the Windows Event Log.

• Is the message backout counter > 0 and increasing?

• If Open Input Count for EX2_IN > 1, there are multiple message flows consuming messages from EX2_IN. In this case, input messages are randomly processed by different flows (this is more likely to happen in later exercises, should you duplicate one flow to serve as a starting point for another).




EXempty
Optional exercise
Instructions for optional exercises are intentionally brief in this exercise. Refer to the Student Notes, previous exercises, and the Information Center for additional information.

__ 1. Redeploy the Ex2.bar file to EXGRP1 on DEVBROKER.

__ 2. Use the WebSphere Message Broker Toolkit to create an additional execution group named Ex2TestGrp.

__ 3. Use the WebSphere Message Broker Toolkit to deploy the .bar file to the Ex2TestGrp and verify that the deployment succeeded.

__ 4. Use RfhUtil to retest with the <Version> = 2 test message. Change the MQMD Reply To Queue name to EX2_OUT (and create that queue using WebSphere MQ Explorer).

Will the transformed message end up on EX2_OUT rather than EX2_REPLY? Retest a number of times and observe results. It is likely that the test messages do not consistently reach only one of the two output queues. If that is the case, what must you do to correct the situation?

__ 5. Override the input queue name in the EX2.bar file in the Broker Archive editor.

__ a. Open the .bar file and click the Manage tab.

__ b. Expand the .cmf file until the nodes are listed.

__ c. Select the input node EX2_IN.

__ d. On the Properties tab, change Queue name to IN_QUEUE (remember to create the queue using WebSphere MQ Explorer).

__ e. Save the .bar file.

__ 6. Start a command console session, change directory as needed, and deploy the .bar file using the mqsideploy command (shown here with a subset of parameters and options):

mqsideploy <broker_name> -e <ExGrp_Name> -bar <BAR_file_name>

See the online help for details about the mqsideploy command.

Ensure the .bar file is in the directory from which the mqsideploy command is issued. A suggestion is to work from \<install_directory>\bin\.

__ 7. Retest with the <Version>=2 message. Be sure to change RfhUtil to submit the test message to IN_QUEUE rather than EX2_IN. Verify that the output goes to EX2_OUT.

__ 8. After you have completed testing, stop the message flows in the EXGRP1 and Ex2TestGrp execution groups and then remove the message flows from the execution groups.

__ 9. Delete the Ex2TestGrp execution group.




END OF OPTIONAL EXERCISE




EXempty
In the first part of this exercise, you performed the required post-installation tasks so that the WebSphere Message Broker Toolkit instance can interact with a broker. This post-installation task is a fundamental requirement for administrators.

You then performed some developer tasks in the WebSphere Message Broker Toolkit such as developing a message flow and testing a message flow. However, when you stop and think about the isolated environment in which developers operate and the more global environment of the administrator, it is obvious that tasks that seem to have a development significance, such as creating queues and queue managers, might also be important to the administrator.




EXempty
Exercise 3. Administering the broker runtime components
Estimated time

01:30


This exercise is designed to give you an opportunity to work with the command-line interface and WebSphere Message Broker Explorer to manage and manipulate WebSphere Message Broker components.

Although it is not an explicit objective of this exercise, you will also use the CMP API Exerciser that is provided with WebSphere Message Broker to perform some basic administration and create scripts.

Finally, you are guided through creating a backup of the broker and configuration data.



• Administer WebSphere Message Broker components using WebSphere Message Broker Explorer and commands

• Back up and restore the broker and its configuration data

Introduction

WebSphere Message Broker administrators can manage and manipulate the WebSphere Message Broker components using WebSphere Message Broker Explorer. However, it is also possible to use a command-line interface to perform the same tasks. While WebSphere Message Broker Explorer is easier to use and more intuitive, the command-line implementation offers the ability to fully automate the management tasks using command scripts. Using the Application API, it is also possible to further extend those capabilities.

Required materials

The fully configured workstation used in the previous exercise is required to successfully complete this exercise.


© Copyright IBM Corp. 2010 Exercise 3. Administering the broker runtime components 3-1



The first part of this exercise has students start the command console and use various commands to operate and manage various WebSphere Message Broker components. The second part of the exercise has students use WebSphere Message Broker Explorer to perform similar administration tasks as with the command line. Then, students briefly work with the supplied CMP API Exerciser. There is no programming using the API itself; just the use of the Exerciser.




EXempty
Notes

All exercises depend on the availability of specific equipment in your classroom.

This exercise assumes that Exercises 1 and 2 have been successfully completed. It depends on having existing, running resources that can be manipulated. Recall that you have used several of the command-line functions in Exercise 1 when you set up your broker environment.

Part 1: Getting started

__ 1. Record the following information in the space provided:

__ a. Your user ID: ________________________________

__ b. Your broker name: ____________________________

__ c. Your broker queue manager name: ____________________

__ d. Your broker queue manager listener port number: 1416

__ 2. Create two new local queues called ADMIN_IN and ADMIN_OUT:

__ a. In WebSphere Message Broker Explorer, expand the DEVQMGR queue manager.

__ b. Right-click Queues and then click New > Local queue.

__ c. In the New Local Queue dialog, enter ADMIN_IN for the queue name, and click Finish. The new queue is created.

__ d. Repeat process in steps c and d to create a local queue named ADMIN_OUT.

__ 3. In the WebSphere Message Broker Toolkit, create a project named EX3_PROJECT into which you import an existing broker archive file:

__ a. From the toolbar, select File > New > Project.

__ b. In the New Project wizard selection window, expand General, click Project, and then click Next.

__ c. In the New Project dialog, enter EX3_PROJECT as the project name. Leave the Use default location box checked, and click Finish.

__ 4. Import the Admin1.bar file from the C:\Labs\Lab3\resources folder to the EX3_PROJECT project It will be used for later deployment.

__ a. From the toolbar, select File > Import.

__ b. In the Import selection window, expand General, click File System, and then click Next.

__ c. In the File system import window, for the From directory field, browse to C:\Labs\Lab3\resources and then click OK.




A resources folder is displayed in the left pane, and the Admin1.bar is displayed in the right pane.

__ d. Check the box by the resources folder which should also cause the box beside the Admin1.bar file to be checked.

__ e. If the Into folder is not EX3_PROJECT, click Browse and select EX3_PROJECT and then click OK.

__ f. Click Finish to import the .bar file.

Part 2: Use the command console

In this part of the exercise, you use the WebSphere Message Broker command console to check the status and configuration of the broker, execution groups, and message flows.

__ 1. The WebSphere Message Broker environment supplies a special command console from which you run WebSphere Message Broker commands. To show what happens if you try to work outside of the command console, open a standard DOS command prompt window.

__ a. From Windows, select Start > Run

__ b. Enter CMD in the Open field and then click OK.

__ 2. Enter the command: mqsilist DEVBROKER

__ 3. You know that your broker is deployed and running, so what might be causing this problem?

In the lesson, you learned that there is an mqsiprofile.cmd that must be run to set up the environment for the various components. Do not run that now.

__ 4. Look at the mqsiprofile.cmd file in the C:\<Broker Install Path>\bin directory.

By using the command console in a Windows environment, the environment is automatically set up and it is not necessary to run the mqsiprofile.cmd.

__ 5. Start the WebSphere Message Broker command console: Start > All programs > IBM WebSphere Message Brokers 7.0 > Command Console.

__ 6. Get a list of running execution groups and message flows by entering the command: mqsilist DEVBROKER -d2

Note

For most commands, you can enter the command followed by a question mark character (?) to get a summary of the command syntax.

What message flows are running?___________________________________




EXempty
__ 7. Now, create an execution group for your broker using the command console. Name it DEVEX3, as shown:
mqsicreateexecutiongroup -i localhost -p 1416 -q DEVQMGR -b DEVBROKER -e DEVEX3

Note

The syntax for the commands in this part of the exercise specify a host ID (-i) and port (-p). These options are not required if you are referencing a local broker. They are provided here to give you an understanding of the syntax required to work with remote components.

__ 8. Deploy the Admin1.bar file to the new DEVEX3 execution group.

__ a. When deploying a BAR file, the mqsideploy command looks for it in the current directory (the one from which the command is run) by default. If the BAR file is not located in that directory, you must specify the full path.

Change directories to the directory containing the BAR file (C:\Labs\Lab3) before entering the command:

cd C:\Labs\Lab3

__ b. Enter the command to deploy the Admin1.bar file:

mqsideploy -i localhost -p 1416 -q DEVQMGR -b DEVBROKER -e DEVEX3 -a Admin1.bar

__ c. Enter the command to view the contents of the BAR file:

mqsireadbar -b Admin1.bar

__ 9. Verify that the flow was successfully deployed.

mqsilist DEVBROKER -e DEVEX3

__ 10. Remove the deployed message flow from the DEV3EX3 execution group.

mqsideploy -i localhost -p 1416 -q DEVQMGR -b DEVBROKER -e DEVEX3 -d Admin1




Hint

To save on typing, press the up arrow key on your keyboard in the Command Console window to retrieve a previous command, edit the portion of command that has changed (if necessary), and then press Enter.

For example, the command you enter in the next step is identical to the command you entered in step 7b. Press the up arrow key until the mqsideploy command is displayed and then press Enter to reissue the command.

__ 11. Redeploy the Admin1.bar file to the DEVEX3 execution group.

mqsideploy -i localhost -p 1416 -q DEVQMGR -b DEVBROKER -e DEVEX3 -a Admin1.bar

__ 12. Now, stop the message flow that you have deployed from the command console:

mqsistopmsgflow -i localhost -p 1416 -q DEVQMGR -b DEVBROKER -e DEVEX3 -m Admin1

__ 13. Restart the message flow:

mqsistartmsgflow -i localhost -p 1416 -q DEVQMGR -b DEVBROKER -e DEVEX3 -m Admin1

__ 14. Answer the following questions:

__ a. What happens if you leave out the -m flag on the mqsistartmsgflow and mqsistopmsgflow commands?______________________________________

__ b. What does the -w flag mean on the mqsistartmsgflow and mqsistopmsgflow commands?______________________________________

Part 3: Use WebSphere Message Broker Explorer

In this part of the exercise, you use WebSphere Message Broker Explorer to complete many of the same tasks that you completed in Parts 1 and 2 of this exercise. In addition, you use WebSphere Message Broker to examine the BAR file contents and message flow properties.

__ 1. If it is not already running, start WebSphere Message Broker Explorer by selecting Start > Programs > IBM WebSphere Message Broker 7.0 > IBM WebSphere Message Broker Explorer.

__ 2. Expand the subtrees under the Brokers folder.

The icon symbols and colors indicate the current state of the brokers, execution groups, and message flows.

__ 3. Select DEVBROKER under the Brokers folder and examine the properties in the Connection QuickView, Status QuickView, and Properties QuickView.




EXempty
__ 4. Create an execution group named MBX3 for the broker MB7BROKER using WebSphere Message Broker Explorer.
__ a. Right-click the broker named MB7BROKER in the Brokers subtree.

__ b. Select New > Execution Group.

__ c. Enter the name of the new execution group.

After a brief pause, the new execution group is created and started.

__ 5. Import the Admin1.bar file into WebSphere Message Broker Explorer and BAR file contents and message flow properties.

__ a. Right-click the Broker Archive Files folder in the WebSphere Message Broker Explorer Navigator.

__ b. Select New > Broker Archive Folder from the menu.

__ c. Enter MyBars as the folder name and then click Finish.

__ d. Open Windows Explorer.

__ e. Go to the C:\Labs\Lab3\resources folder.

__ f. Drag the file Admin1.bar from Windows Explorer to the MyBars folder in WebSphere Message Broker Explorer.

__ g. Expand the MyBars folder and verify that Admin1.bar had been added.

__ h. Right-click Admin1.bar and select Open with > Broker Archive Editor.

__ i. On the Manage view expand the Admin1.cmf compiled message file.

__ j. Right-click the ADMIN_IN node and select Configure. The Properties view should open displaying the properties that can be overridden.

__ 6. Deploy the message flow to the newly created execution group named MBX3 by dragging the file Admin1.bar from the MyBars folder to the execution group in the Navigator.

__ 7. Check the Administration Log in WebSphere Message Broker Explorer for a message indicating the message flow was deployed successfully.

__ 8. Select the execution group and examine the execution group Properties QuickView and Deployed Flows and Flow Resources QuickView.

The QuickView shows the message flow properties such as queues used, user trace status, and node names.

__ 9. Select the message flow and examine the flow properties in the Properties QuickView.

The QuickView shows the message flow properties such as queues used, user trace status, and node names.




__ 10. Remove the deployed message flow from the MBX3 execution group.

__ a. Stop the message flow by right-clicking the message flow and selecting Stop from the menu.

__ b. Delete the message flow by right-clicking the message flow and selecting Delete from the menu.

__ c. Select Yes on the confirmation message.

__ 11. Stop the MBX3 execution group by right-clicking the execution group in the Navigator and selecting Stop from the menu.

Part 4: Creating broker sets

In this part of the exercise, you create a broker set that automatically contains all brokers that are stopped.

__ 1. In the WebSphere Message Broker Explorer, right-click the Brokers folder and select Broker Sets > New Broker Set.

__ 2. Enter Stopped for broker set name.

__ 3. Click the Automatic radio button so that any broker in the ‘stopped’ state is automatically displayed in this broker set.

__ 4. Click Next.

__ 5. Select brokerStatus:Stopped in the Available filters column and then click Add---> to move it the Selected filters column.

__ 6. Click Finish.

__ 7. Two new categories are displayed under the Brokers folder:

• All contains all the brokers.

• Stopped contains only the brokers in the ‘stopped’ state.

__ 8. To test the broker set, stop the broker MB7BROKER by right-clicking the broker and selecting Stop > Broker.

The broker should be displayed in the Stopped broker set.




EXempty
Part 5: Using the CMP API Exerciser
__ 1. Start the CMP API Exercise by selecting Start > Programs > IBM WebSphere Message Broker 7.0 > Java Programming APIs > CMP API Exerciser.

__ 2. Connect to your local broker by right-clicking and selecting the Connect to Local Broker.

__ 3. Select the broker DEVBROKER from the drop-down list and then select Submit.

__ 4. After a connection is established, note the status information displayed in the lower part of the Exerciser screen.

__ 5. In the upper part of the screen is information about the broker. Highlight the message flow (Admin1.cmf) you deployed to the new execution group DEVEX3.




__ 6. By right-clicking the flow, you can see that it is possible to turn on tracing, start and stop, delete, and find some additional information.

For now, try stopping and then starting the flow. Verify that the flow is stopped and restarted by looking in the WebSphere Message Broker Explorer Navigator.




EXempty
__ 7. Assume that you want a new execution group with a different name. First, delete the execution group called DEVEX3.
Deleting the execution group can be done on the command line or in WebSphere Message Broker Explorer; in this exercise you will use the CMP API Exerciser.

Right-click the execution group and select Delete.

The delete is performed without confirmation.

__ 8. Next, you record a script of an operation, which captures it for reuse. The script can then be run against other broker environments. From the Scripting pull-down list, select Record New Script...

__ 9. Give the script a useful name: CreateNewEG.xml Store it in your root directory (C:).

Scripting is now active.

__ 10. Highlight the broker name (DEVBROKER), right-click it, and select Create execution group.

__ 11. Name the new execution group EX3B and then click Submit.

__ 12. After you see the new execution group (you can verify its presence in the WebSphere Message Broker Explorer), stop the script recording by selecting Scripting > Stop Recording.

__ 13. Now, either from the CMP API Exerciser or from the WebSphere Message Broker Explorer, delete the execution group.




__ 14. Select Scripting > Play Back Recorded Script to watch the recreation of the execution group. You must browse to the root directory (C:\), find the XML file used for the recording, and then click OK.

__ 15. Right-click the new execution group and select Deploy BAR to deploy the broker archive called Admin1.bar.

__ 16. Go to C:\Labs\Lab3\resources and select the Admin1.bar file. Click Open and wait for the deployment to complete.

__ 17. You can confirm the deployment of the flow by looking at the log entries in the API Exerciser or the Administration Log in the WebSphere Message Broker Toolkit.

__ 18. After you have confirmed that the message flow has been successfully deployed, stop the Admin1 message flow and delete the EX3B execution group.

__ 19. Close the CMP API Exerciser.

Part 6: Back up and restore the broker

In this part of the exercise, you back up the broker. Although it is not necessary to stop the broker to back up, you stop the broker and broker services in this exercise.

__ 1. Normally, you would want to back up this information to a separate drive. But, for this exercise, you create a local folder and back up to that location.

Create a folder named MQSIBackup in the root (C:\) directory.




EXempty
__ 2. Open a WebSphere Message Broker command console and back up the broker to the new folder. (There is a -a flag to name the archive, but do not use it here, so that you can see what the default file name is.)
mqsibackupbroker DEVBROKER -d C:\MQSIBackup

The command should return a message like the following example: BIP125I: Creating backup file ‘C:\MQSIbackup\DEBVROKER_ccmmdd_hhmmss.zip’ for broker ‘DEVBROKER’.BIP8071I: Successful command completion.

Where ccyydd is the year, month, and day and hhmmss the hour, minute, and second of the backup file creation time.

__ 3. Open a Windows Explorer window and browse to the MQSIBackup folder.

You now have all the necessary information to restore your broker. This folder can be compressed and stored elsewhere (on some type of external media) or, at a minimum, on a separate drive from where the domain exists.

Next, you simulate a system failure by deleting the broker and broker components. After you have completed the system failure simulation, you will restore the broker and components using the backup file you created in Step 2.

__ 4. Disconnect from the broker:

__ a. In the WebSphere Message Broker Explorer, right-click the broker DEVBROKER.

__ b. Select Disconnect from the menu.

__ 5. Close any applications that might be connected to the broker or broker queue manager including WebSphere Message Broker Explorer, WebSphere Message Broker Toolkit, and RfhUtil.

__ 6. From a WebSphere Message Broker command console, stop the broker if it is still running:

mqsistop DEVBROKER

Note

You can also stop the broker services using the Windows Services control panel. Click Start > Settings> Control Panel > Administrative Tools > Services

Scroll to the IBM WebSphere Message Broker component for the broker and click Stop.




__ 7. Simulate a failure of the broker by completely removing the broker and queue manager.

From a command console session, enter the following command:

mqsideletebroker DEVBROKER

Important

The broker backup and restore commands do not back up resources required by message flows to function correctly such as WebSphere MQ queues and data stored in user databases, transient information for inflight aggregations or collections, and executable code, including resources that are associated with user-defined extensions (nodes, parsers, and exits).

__ 8. Attempt to start the broker from a command console.

mqsistart DEVBROKER

You should receive a message saying that the component does not exist.

__ 9. From WebSphere Message Broker Explorer recreate the broker DEVBROKER

__ a. Right-click Brokers in the Navigator and select New > Local broker.

__ b. For the New Broker name, enter DEVBROKER and then click Next.

__ c. For the Queue manager, enter DEVQMGR and then click Finish.

__ 10. Using the command console, restore the broker with the same name.

mqsirestorebroker DEVBROKER -d C:\MQSIbackup -a <archive_file>

where <archive_file> is the name of the archive file that was created by mqsibrokerbackup command you entered in Step 2.

After the restore completes, you will receive a message indicating that the broker has been restored.

__ 11. Finally, attempt to start the broker using the WebSphere Message Broker Explorer or command line.

__ 12. Test that the broker is properly restored by going to the WebSphere Message Broker Explorer connecting to the broker, and attempting to stop and then start one of the message flows.

Be sure to check your event log to ensure that everything worked properly.

END OF EXERCISE




EXempty
This exercise provided you with an opportunity to use the command-line interface to issue commands using the command console. It also exposed you to the CMP API Exerciser. This CMP API allows customization of administrative functions, but that is a programming task, not covered in this exercise.

Backing up the broker is an important exercise for administrators. In the exercise, you learned how to back up and restore all necessary broker components.




EXempty
Exercise 4. Administering broker security
Estimated time

01:00


This lab exercise is designed to give students the opportunity to set and test WebSphere Message Broker access control for the brokers, execution groups, and message flows.



• Activate administration authority

• Assign security permissions for brokers, execution groups, and message flows using WebSphere Message Broker Explorer and MQSI commands.

• Test the secured environment using the Configuration Manager Proxy (CMP) API Exerciser

Introduction

WebSphere Message Broker uses a special set of queues on the broker queue manager to control access to each entity that must be secured in terms of administrative access. Each administrative action, such as creating an execution group, and deploying or stopping a message flow, is mapped to one of three categories; read, write, or execute. These categories are mapped to WebSphere MQ security properties as follows:

Inquire ----> Read

Put ----> Write

Set ----> Execute

One or more of the WebSphere MQ security permissions are set on a particular queue to control access to the object that queue represents; a broker or an execution group. This design uses a familiar, already present mechanism (queue security) and provides excellent granularity and flexibility.


© Copyright IBM Corp. 2010 Exercise 4. Administering broker security 4-1


Administrative security is turned off by default when a broker is created. It must be turned on using the mqsichangebroker command. A flag is also provided on the mqsicreatebroker command that turns on security as part of the creation process.

Requirements

You use the fully configured workstation from Exercises 1 and 2. Exercises 1 and 2 must have been successfully completed before this exercise can be attempted.

• Admin_Security_Test1.bar and Admin_Security_Test2.bar A copy of the Project interchange file and a BAR file are located in the C:\Labs\Lab4\resources folder.

• Runas_No_Auth_ID_For_CMP.bat Windows batch script, located in the C:\Labs\Lab4\resources folder. This batch script starts a session as user No_Auth_ID.

• Microsoft Windows user named No_Auth_ID and group named Test_1 with WebSphere Message Broker permissions as shown in part 1 of the exercise.

• WebSphere Message Broker default configuration




EXempty
Preface

To effectively test administrative security you must have some way to run under a different user ID other than the administrator ID because the administrator ID has full access to the broker environment by default. Logging out of Administrator and logging in as another user is not a good solution on Windows as that starts a different or unique configuration of installed software. The solution is to use a Windows facility called runas with which you can open a command window and launch programs under a different user ID.

You will use the runas tool in this lab to run under an alternate user ID. The broker tool that you start from the command window that is using an alternate ID, is the CMP API Exerciser. One feature of the CMP API Exerciser is that it provides a window at the bottom of the interface that shows frequent and detailed status. The window shows the results from a test, including error messages, without having to use another tool.

A script has been provided that starts runas using an alternate ID and then starts the CMP API Exerciser for you.

While this lab uses the CMP API Exerciser, it is important that you understand that in WebSphere Message Broker V7, all tools, such as WebSphere Message Broker Explorer, and the WebSphere Message Broker Toolkit, are subject to security checking when administrative security is active.


The first part of this exercise has students set up user and group authorities of a specific non-privileged Windows user. That same user ID is used in testing the next parts of this lab.

Part 1: Setting user and group security

A new user, No_Auth_ID, has been added to a new group, Test_1. In this part of the exercise, you grant the Test_1 group-specific WebSphere MQ privileges.

This exercise also uses the default broker (MB7BROKER) and queue manager (MB7QMGR) created by the Default Configuration wizard.

__ 1. Start the Windows Computer Management application by selecting Start > Settings > Control Panel > Administrative Tools > Computer Management.

__ 2. Expand Local Users and Groups and click Users.

A list of all users is displayed in the right pane. You will be using the No_Auth_ID as user ID which has no prior authorization.




__ 3. Click Groups.

In this exercise, you are setting all authorities at the Group level and the No_Auth_ID user ID inherits its authorities from the Group.




EXempty
Note
While it is possible to assign authorities at the user level in Windows, most other operating systems do not support this capability.

__ 4. This exercise uses a group named Test_1. Double-click Test_1 to open it.

The user No_Auth_ID is the only member. Click OK.

__ 5. If it is not already running, start WebSphere Message Broker Explorer.

__ 6. In WebSphere Message Broker Explorer, grant the group Test_1 Connect and Inquire privileges for queue manager MB7QMGR:

__ a. Under the Queue Managers folder, right-click MB7QMGR and select Object Authorities > Manage Authority Records from the menu. The Manage Authority Record dialog is displayed.

__ b. On the Groups tab, click New.

__ c. For Entity name, enter Test_1, and select the Connect and Inquire boxes.

__ d. Click OK, then click OK again on the result dialog box.

__ e. The Test_1 group should now be displayed in the Groups list with Connect and Inquire authority.

__ f. Click Close.

The group Test_1 now has Connect and Inquire authority for the queue manager. This is one of the elements in the set of required authorities for a user running in an unsecured broker if you want them to be able to perform normal activities.

__ 7. Grant the group Test_1 Put privileges on the SYSTEM.BROKER.DEPLOY.QUEUE so that they can deploy:

__ a. Under the MB7QMGR subtree, double-click Queues, and then click the Show System Objects icon in the upper right so that the system queues are displayed.




__ b. Select SYSTEM.BROKER.DEPLOY.QUEUE, right-click, and select Object Authorities > Manage Authority Records from the menu.

__ c. Expand Specific Profiles and then select SYSTEM.BROKER.DEPLOY.QUEUE.

__ d. On the Groups tab, click New.

__ e. For Entity name, enter Test_1, and select the Put box.

__ f. Click OK, then click OK again on the result dialog box.

__ g. Click Close.

The group Test_1 now has Put authority on this queue. This is the second element in the set of required authorities for a user running in an unsecured broker if you want them to be able to perform normal activities.

__ 8. Following the same procedure as described in Step 7, grant the group Test_1 Put and Get privileges on the SYSTEM.BROKER.DEPLOY.REPLY queue.

This is the third element in the set of required authorities for a user running in an unsecured broker if you want them to be able to perform normal activities.

__ 9. Import the BAR files used in this lab into WebSphere Message Broker Explorer under a Broker Archive Files folder named Server.

__ a. In the WebSphere Message Broker Explorer Navigator, right-click Broker Archive Files and select New > Broker Archive Folder.

__ b. Type Server and click Finish.

__ c. Right-click the new Servers folder and select Import Broker Archive Files.

__ d. Click Browse for the From directory and go to C:\Labs\Lab4\resources then click OK.

__ e. In the right pane, select (check) the Admin_Security_Test1.bar file and Admin_Security_Test2.bar file.

These are basic MQInput to MQOutput message flows. They are not actually run in the lab but must be deployed at certain points.




EXempty

__ f. Click Finish.

The BAR files should now appear in the WebSphere Message Broker Navigator under the Broker Archive Files/Servers folder.


This part of the exercise demonstrates what a user who has minimal security can do within the WebSphere Message Broker environment.

Part 2: Testing the default unsecured environment

The steps in this part of the exercise demonstrate that the No_Auth_ID user can successfully operate in the broker environment given the base set of authorities you configured in the part 1 of this exercise.




__ 1. So that you can run as another user without having to log off and back on, you use the runas facility in Windows. A command file has been provided so that you can conveniently use this facility.

__ a. Start Windows Explorer.

__ b. Go to the C:\Labs\Lab4\resources directory and double-click the Runas_No_Auth_ID_For_CMP.bat file and then click Run.

__ c. A Command Prompt window opens and you are prompted to enter the password for the No_Auth_ID.

Enter passno for the password and press the Enter key.

After a few moments, the CMP API Exerciser starts.

__ 2. It is necessary to adjust the timeout values for CMP API Exerciser if you are running this exercise on a VMware image.

__ a. Select File > Set Timeout Characteristics.

__ b. Enter the timeout values as follows and then click Submit:

- Set Maximum wait time for BAR deployment to 60

- Set Maximum wait time for execution group creation to 60

- Set Maximum wait time for other requests to 20

__ 3. The next steps assume that the broker is running.

If the broker MB7BROKER is not running, start it now from WebSphere Message Broker Explorer or from the command console.

__ 4. The CMP API Exerciser is running under No_Auth_ID and gets all permissions from the settings for that user and group, which is Test_1.

This tool must be connected to a broker to function.

__ a. Right-click and select Connect to Local Broker from the menu.

__ b. Select MB7BROKER and click Submit.

__ 5. Verify that Administrative Security is turned off in MB7BROKER.




EXempty
__ a. Click MB7BROKER in the CMP API Exerciser navigator (left pane) to highlight it.
__ b. Scroll to the bottom of the data window (right pane).

__ c. Verify that isAdminSecurityEnabled() shows false, indicating that administrative security is disabled.

When the CMP API Exerciser is connected to the broker, information about the broker is displayed under the broker in the navigation pane,

The fact that an execution group is displayed implies that a certain level of access has been granted to the user. In this case, the No_Auth_ID user has Read access to the broker.

__ 6. Try to deploy a BAR as the No_Auth_ID user:

__ a. Select the default execution group in the CMP API Exerciser navigator (left pane), then right-click and select Deploy BAR from the menu.

Note

You must be sure that an entity is selected before right clicking it in the CMP API Exerciser,

__ b. Go to the C:\Labs\Lab4\resources directory and select Admin_Security_Test1.bar and then click Open.

The request should have been successful as indicated in the status log in the bottom pane of the CMP API Exerciser.

__ 7. Test to see if this user can stop a message flow.

__ a. Expand the default execution group in the navigator.

__ b. Expand Admin_Security1_MsgFlow.bar under the default execution group.

__ c. Right click Admin_Security1_MsgFlow.cmf and select Stop from the menu.




__ d. Verify that the message flow stopped by selecting the message flow and scrolling to the bottom of the displayed data.

The last entry was produced using the isRunning method of the CMP API with a result of false which means that the flow has stopped.

__ 8. Restart the flow by right clicking Admin_Security1_MsgFlow.cmf and selecting Start from the menu.

__ 9. Verify that the flow has started by checking that the last entry in the CMP API Exerciser is the isRunning method with a result of true.

Testing of the unsecured environment is finished.

You have seen that, given a minimum set of authorizations, the No_Auth_ID has access to the broker.

__ 10. Disconnect the CMP API Exerciser from the broker by right-clicking MB7BROKER in the navigation pane and selecting Disconnect.

Note

Do not shut the CMP API Exerciser down; it is used again in the next part of the exercise.


In the next part of the lab, WebSphere Message Broker security is activated, and the same non-privileged user ID is used to demonstrate that the user cannot perform any functions in the WebSphere Message Broker environment.

Part 3: Activating administration security and testing the secured environment

__ 1. Activate broker administrative security from a command line.

__ a. Start a WebSphere Message Broker command console.

__ b. Enter the following command to stop the broker so that you can make the necessary configuration change:

mqsistop MB7BROKER

__ c. Verify that the broker is stopped:

mqsilist MB7BROKER

__ d. Enter the following command to activate security:

mqsichangebroker MB7BROKER -s active




EXempty
Note
The number of setmqaut commands that are displayed in the command console windows after running the mqsichangebroker command depends on the number of defined execution groups.

__ e. Verify that administration security is active for MB7BROKER:

mqsireportbroker MB7BROKER

The last line in the report indicates the administration security status.

__ f. Enter the following command to restart the broker:

mqsistart MB7BROKER

__ 2. In WebSphere MQ Explorer, right-click Queues under MB7QMGR queue manager. Confirm that the queue SYSTEM.BROKER.AUTH.default exists.

__ 3. Connect to the MB7BROKER in the CMP API Exerciser.

The MB7BROKER is displayed in the navigation pane, because the NO_AUTH_ID was able to connect to its queue manager. However, there are no broker details displayed in the navigator pane, and a lock icon appears next to the broker name. The lock icon indicates a security issue has occurred.

__ 4. Verity that a BrokerProxy Method of getLastBIPMessages is displayed in the method list with an authorization error in the result column. The error message explains that the No_Auth_ID user was not authorized to perform the “view” operation against the broker (which would have been used to populate the broker properties in the navigation pane).

This is evidence that administrative security is active.

__ 5. A Broker Administration Error is displayed if you have WebSphere Message Broker Explorer running. Click OK to acknowledge the message.




__ 6. In the WebSphere MQ Explorer, right-click the SYSTEM.BROKER.AUTH queue on MB7QMGR and select Object Authorities > Manage Authority Records from the menu.

__ 7. Expand Specific Profiles and select SYSTEM.BROKER.AUTH.

The group Test_1 is not displayed in the profiles list, so it has no permissions on the SYSTEM.BROKER.AUTH queue. This is the reason that the queue manager and execution group did not appear in the CMP API Exerciser which requires that the user group have Read permissions.

__ 8. Enable Read permissions on the SYSTEM.BROKER.AUTH queue for the Test_1 group:

__ a. Click New at the bottom of the window, under the Groups tab.

__ b. Enter Test_1 as the Entity name.

__ c. Select the Inquire check box.

__ d. Click OK.




EXempty

__ e. Click OK in the confirmation pop-up window.

__ f. There should now be an entry in on the Group tab Test_1 with a check in the Inquire column.

__ g. Click Close.

__ 9. In the CMP API Exerciser, right-click MB7BROKER and select Refresh from the menu.

With the security change, the queue and execution group now appear in the navigation pane; however the default execution group has no contents and there is a lock next to the execution group name.

To list the contents of an execution group, a user must have Read access to the execution group.

__ 10. In WebSphere MQ Explorer, enable Read (Inquire) access to the execution group named default for the Test_1 group:

__ a. In the list of queues, right-click SYSTEM.BROKER.AUTH.default queue and select Object Authorities > Manage Authority Records from the context menu.




__ b. Expand Specific Profiles and select SYSTEM.BROKER.AUTH.default.

__ c. Click New to add a new entry for Test_1.

__ d. Enter Test_1 as the Entity name.

__ e. Check the Inquire check box

__ f. Click OK and then click OK again to close the confirmation window.

__ g. There is now an entry for group Test_1 in the authorities record for the default execution group queue.

__ h. Click Close.

__ 11. Return to the CMP API Exerciser. Right click the default execution group and select Refresh from the menu. You should now see the contents of the default execution group and the Result column for the getLastBIPMessages method result should be blank.

__ 12. Next, try to deploy a flow from the CMP API Exerciser.

__ a. Right click the default execution group and select Deploy BAR from the context menu.

__ b. Go to the C:\Labs\Lab4\resources directory and select Admin_Security_Test2.bar

__ c. The deployment should fail, and a message indicating that the user does not have authorization should be displayed in the log area of the CMP API Exerciser.

The ability to deploy requires Write (Put) permission on the execution group.

__ 13. In WebSphere Message Broker Explorer, add Write (Put) permissions to the execution group queue SYSTEM.BROKER.AUTH.default.

__ a. Right click SYSTEM.BROKER.AUTH.default queue and select Object Authorities > Manage Authority Records

__ b. Expand Specific Profiles and select SYSTEM.BROKER.AUTH.default.

__ c. Select the Test_1 group record and click Edit.

__ d. Check the Put check box, then click OK.

The Test_1 group should now have both Inquire (Read) and Put (Write) permissions.

__ e. Click Close.

__ 14. Now try to deploy the Admin_Security_Test2.bar in the CMP API Exerciser.

Verify that flow successfully deployed by reviewing the messages in the CMP API Exerciser status log.

__ 15. Stop the message flow from the CMP API Exerciser.




EXempty
__ a. Expand Admin_Security_Test2.bar in the navigation pane.
__ b. Right click Admin_Security2_MsgFlow.cmf and select Stop from the menu.

The stop request fails, because the group to which the user belongs does not have Set (execute) authority, which is required to issue a stop or start command.

__ 16. In WebSphere Message Broker Explorer, modify the permissions for the Test_1 group to include Set (Execute) permissions on the SYSTEM.BROKER.AUTH.default queue.

__ 17. In the CMP API Exerciser, try to stop the message flow now that the permissions have been modified.

__ 18. To verify that the flow stopped, scroll to the last entry in the MessageFlowProxy Method list. The last entry in the Result column should be the isRunning method with a result of false which indicates that the flow has stopped.

__ 19. Try to create an execution group in the CMP API Exerciser.

__ a. Right click MB7BROKER and select Create execution group from the menu.

__ b. Enter Admin_Security_EG for the New execution group name and click Submit.

__ c. The requested action should fail because the Test_1 group does not have Write (put) permission on the broker queue.

__ 20. In WebSphere MQ Explorer, add Write (Put) permissions to the SYSTEM.BROKER.AUTH queue for Test_1.

The Test_1 group should now have both Read (Inquire) and Write (Put) permissions.

__ 21. Following the procedures in Step 18, try to add the Admin_Security_EG execution group to MB7BROKER.

__ 22. Attempt deployment of the Admin_Security_Test1.bar file located in the C:\Labs\Lab4\resources directory to the Admin_Security_EG execution group.

You should receive a security violation because the user No_Auth_ID does not have sufficient authority to deploy to the new execution group.

The deployment operation requires Put (Write) authority on the SYSTEM.BROKER.AUTH.Admin_Security_EG queue.

Note

The process of creating the execution group Admin_Security_EG automatically creates the queue SYSTEM.BROKER.AUTH.Admin_Security_EG but it does not automatically create access to the execution group.




__ 23. To supply the required authority, you must modify permissions on the SYSTEM.BROKER.AUTH.Admin_Security_EG queue in WebSphere MQ Explorer to grant Put (write) authority to group Test_1.

As seen in previous steps, the group would also need Inquire (read) permission to see the artifacts that have been deployed to the execution group.

__ 24. In the CMP API Exerciser, disconnect from the broker by right clicking MB7BROKER and select Disconnect.

__ 25. Close the CMP API Exerciser.

__ 26. Close the Windows Command Prompt window by entering the command exit.

__ 27. Disable administrative security from a command line in the WebSphere Message Broker command console.

__ a. Stop the broker and verify that it has stopped:

mqsistop MB7BROKER

mqsilist MB7BROKER

__ b. Disable administration security:

mqsichangebroker MB7BROKER -s inactive

__ c. Verify that administration security is inactive then restart the broker:

mqsireportbroker MB7BROKER

mqsistart MB7BROKER

__ 28. In WebSphere Message Broker Explorer:

__ a. Delete the execution group Admin_Security_EG.

__ b. Delete all flows and resources from the default execution group.

End of exercise




EXempty
Exercise 5. Using trace facilities
Estimated time

00:30


This exercise has you use the various tracing and debugging tools to identify problems in message flows, enable and disable trace nodes, and use a user and service trace to capture information.



• Enable and disable a trace node within a message flow

• Activate a user trace and service trace to capture information

• Administer trace nodes and the message flow debugger

Introduction

You will use various problem determination tools to administer message flows with trace nodes and use administration tools to generate and control tracing.

This exercise uses a flow like the message used in Exercise 2 but with the addition of a trace node.


© Copyright IBM Corp. 2010 Exercise 5. Using trace facilities 5-1


Required materials

A fully configured workstation, as used in previous exercises.

EX5_PD.bar The broker archive file for the message flow, located in the C:\Labs\Lab5\resources folder.




EXempty
Part 1: Import the BAR file into WebSphere Message Broker Explorer

In this part of the exercise, you import an existing BAR file that contains a message flow that is identical to the message flow you used in Exercise 2 except that it has a Trace node.

After you import the BAR file, you will examine the Trace node properties and then deploy the BAR file to the DEVBROKER.

__ 1. In the WebSphere Message Broker Explorer, right-click the Broker Archive Files/Servers folder in the Navigator and select Import Broker Archive Files.

__ 2. Click Browse for the From directory and go to the C:\Labs\Lab5\resources directory and then click OK.

__ 3. In the right pane select the BAR file EX5_PD.bar and then click Finish.

The BAR file should appear in the WebSphere Message Broker Explorer Navigator under the Broker Archive Files/Servers folder.

__ 4. Open the message flow and examine the Trace node properties.

__ a. Double-click the EX5_PD.bar file in the WebSphere Message Broker Explorer Navigator to open the Broker Archive Editor.

__ b. Expand the SimpleFlowWithTrace.cmf file until all the nodes are displayed.

__ c. Select the Trace node labeled Trace to display its properties in the Properties view.

The developer specified that the Trace node should create a trace file. Based on this setting at design time, the only property that can be changed by the administrator in WebSphere Message Broker Explorer is the location of the trace file. In this exercise, trace file location (filePath) is set to C:\Labs\Lab5\SimpleFlowtrace.txt.

__ 5. In WebSphere Message Broker Explorer, verify that you have an execution group named default on DEVBROKER; if not create it now.




__ 6. Deploy the EX5_PD.bar to the default execution group in broker DEVBROKER.

__ a. Select the EX5_PD.bar file in the Navigator.

__ b. Drag it onto the default execution group under DEVBROKER in the Brokers folder.

__ c. Check the Administration Log view to verify that the message flow has been deployed successfully.

You should also see the message flow under DEVBROKER in the Brokers folder under the default execution group.

Part 2: Send a test message to the message flow

__ 1. Start RfhUtil by double-clicking the desktop shortcut icon.

__ 2. Enter the following parameters on the Main tab in RfhUtil:

• Queue Manager Name: use the drop-down list to select DEVQMGR. • Queue Name: use the drop-down list to select EX2_IN.

__ 3. Click Open File. A file selection window is displayed.

__ 4. Go to C:\Labs\Lab5\data and select file Test_V2_msg.xml. Click Open.

__ 5. Select the MQMD tab.

__ 6. Update the following fields as noted:

__ a. Use the drop-down list to set the MQ Message Format field to MQSTR (signifying the message is string data) on the drop-down menu

__ b. Use the drop-down list to set the MsgType field to 1 Request (signifying the message is a WebSphere MQ request message).




EXempty
• Set the Reply To Queue name to EX2_REPLY so that the MQReply node routes the message to that queue.
__ 7. Switch back to the Main tab, and click Write Q to send the test message to the EX2_IN queue.

__ 8. Open another RfhUtil instance and check the Reply To Queue EX2_REPLY.

__ a. Enter the following parameters on the Main tab in RfhUtil:

• Queue Manager Name: use the drop-down list to select DEVQMGR. • Queue Name: use the drop-down list to select EX2_REPLY.

__ b. Click Read Q.

__ c. Switch to the Data tab and click XML as the Data Format.




__ d. When viewed as XML the message should appear as follows:


__ 9. Do not close the RfhUtil session, as you use it later in this lab.

Part 3: User trace and trace node output

__ 1. In WebSphere Message Broker Explorer, activate UserTrace (Debug) for the SimpleFlowWithTrace.msgflow running in the default execution group.

__ a. In the Navigator view, expand the broker DEVBROKER and the default execution group.

__ b. Right-click the SimpleFlowWithTrace message flow and select UserTrace > Debug.

__ c. Verify that tracing is active in the Administration Log view. You might have to wait briefly, but you will see a message that indicates the user TraceLevel has changed from ‘none’ to ‘debugTrace’.

__ 2. When you select the execution group, the execution group Properties QuickView also indicates that tracing is enabled and has a performance affect.




EXempty
__ 3. Send another test message by clicking Write Q in RfhUtil.
Did a message arrive on the EX2_REPLY on queue manager DEVBROKER?

__ 4. Retrieve the user trace data and deactivate tracing by running the GETTRACE script.

Open a WebSphere Message Broker command console window and run this command: C:\Labs\Tools\GETTRACE.cmd <brokername> <execution group name> where <brokername> is the name of your broker (in this case, DEVBROKER) and <execution group name> is the name of the execution group (in this case, default). Remember that the parameters are case-sensitive. This command file runs several WebSphere Message Broker commands:

- mqsireadlog, which reads the binary trace data that was gathered by the trace node

- mqsiformatlog, which translates the binary trace data into human-readable format

- mqsichangetrace, which disables tracing (and can also be used from the command line to start tracing or change trace parameters)

The command file then starts Windows Notepad to display the trace output.

__ 5. Review the user trace output. You should find all the runtime events (or errors) in the trace.

__ 6. In WebSphere Message Broker Explorer, refresh the message flow to verify that user trace has terminated. If it has not stopped automatically, you can manually disable it.

__ a. In the Navigator view, right-click the message flow and select Refresh.

The message flow Properties QuickView shows the current state of User Trace.




__ b. To manually turn off trace, right-click the message flow and select User Trace > None.

__ 7. Now review the output from the trace node from the file you indicated in the trace node properties, for example, C:\Labs\Lab5\SimpleFlowTrace.txt

__ a. Use Windows Explorer to locate the trace node output file.

__ b. Open the file and examine the contents. You see the contents of the entire message at the end of the file if you specified ${Root} for the pattern.

Part 4: Enable a service trace

Service trace provides more detailed tracing, and generates a large amount of output. In this exercise, you are given the option of using a command line or WebSphere Message Broker Explorer to enable and disable a service trace.

Option 1: Enable a service trace from a command line

__ 1. In the WebSphere Message Broker command console, issue the following command to start a service trace for the default execution group. The -r flag resets trace to ensure only information collected is from this instance of tracing.

mqsichangetrace DEVBROKER -t -e default -l debug -r




EXempty
__ 2. Now, to see what tracing is active, issue the following command:
mqsireporttrace DEVBROKER -t -e default You should see a response like the following:

__ 3. Switch to the RfhUtil session and send another message to the EX2_IN queue by clicking Write Q.

__ 4. Disable the service trace by switching to the command console session and entering the following command:

mqsichangetrace DEVBROKER -t -e default -l none

Option 2: Enable a service trace from WebSphere Message Broker Explorer

__ 1. In WebSphere Message Broker Explorer, right-click the default execution group for the DEVBROKER and then select Service trace > Debug.

A warning message is displayed in the Execution Group properties view indicating that there is a performance affect and the Service Trace property is set to Debug.

__ 2. Switch to the RfhUtil session and send another message to the EX2_IN queue by clicking Write Q.

__ 3. Disable the service trace, by right-clicking the default execution group and selecting Service Trace > None.

Part 5: Process the service trace output

Regardless of the method you used to activate a service trace, you must retrieve the service trace data into a file. For this exercise, a command file getsvctrace.cmd performs this function for you. The command file is like the gettrace.cmd that you used when retrieving the user trace data.

__ 1. Retrieve the service trace data from a WebSphere Message Broker command console session by running the following command:

C:\Labs\Tools\getsvctrace.cmd DEVBROKER default

__ 2. Review the service trace output in the Notepad session that is automatically opened by the getsvctrace.cmd.

The information captured in the service trace is more detailed and includes a great deal about the various component behaviors.




Part 6: Administering Trace nodes

As mentioned earlier in this exercise, Trace nodes generate trace records that you can use to monitor the behavior of a message flow. When a developer has tested the message flow and proved that its operation is correct, the Trace nodes should either be removed from the message flow or disabled.

__ 1. Check the status of the Trace nodes in the WebSphere Message Broker Explorer by selecting the SimpleFlowWithTrace message flow under the default execution group in the Navigator view.

The message flow Properties QuickView indicates the current state of the Trace nodes.

__ 2. If the Trace nodes are Enabled, disable them by right-clicking the message flow in the WebSphere Message Broker Explorer Navigator view and selecting Trace Nodes > Disable.

Part 7: Administering the message flow debugger

Developers can use the message flow debugger in the WebSphere Message Broker Toolkit to help diagnose unexpected behavior within message flows. Breakpoints can be set to pause execution and examine and change the contents of the message, ESQL, and Java variables and mappings. While this is usually a development application, you might be called on as an administrator to assist in setting up the debugging environment.

Since the Java runtime debug environment is used for debugging, you must configure the JVM debug port for the execution group in which the message flow is running.




EXempty
The debug port can be configured in the development environment using WebSphere Message Broker Toolkit or in the administration environment using WebSphere Message Broker Explorer. As an administrator, you also must be aware of the status of the debugger as it does affect performance. Since this is an administration course, you configure and manage the message flow debugger from WebSphere Message Broker Explorer.
Note

JVM debug port configuration must be completed one time for each execution group. The Execution Group Properties QuickView in WebSphere Message Broker Explorer identifies whether a debug port has been configured for an execution group.

__ 1. Check whether a debug port has been defined on the default execution group on DEVBROKER by right-clicking the execution group in the WebSphere Message Broker Explorer Navigator and selecting Flow Debug Port.

The Enable menu option is either followed by a flow debug port value, if one has already been configured, or the phrase (No port set) if not debug port has been defined.

The default execution group should not have a debug port set.

__ 2. To set the debug port, right-click the default execution group under the DEVBROKER and select Properties.

__ 3. Select Extended.

__ 4. Enter a value for the Flow Debug Port. For this exercise, enter 9997 and then click OK.




__ 5. Check the Administration Log to see if the execution group automatically restarted.

__ 6. The Execution Group Properties QuickView is updated to show that a debug port has been set but that it is disabled.

Note

You can also use the mqsichangeproperties command line to configure the JVM debug port:

mqsichangeproperties <brokerName> -e <executionGroup> -o ComIbmJVMManager -n jvmDebugPort -v <portNumber>

__ 7. To enable the debugger, right-click the execution group in the Navigator view and select Flow Debug Port > Enable.

The Flow Debug Port property in the Properties QuickView changes to Enabled(9997) and a warning message is displayed at the top of the Properties




EXempty
QuickView indicating that the flow debug port is active and that it affects performance.
__ 8. Disable the message flow debug port by right-clicking the execution group in the WebSphere Message Broker Explorer Navigator and selecting Flow Debug Port > Disable.

END OF EXERCISE





This exercise exposed you to some of the troubleshooting tools available to developers and administrators including the user trace and service trace facilities. It also showed you the tools that you, as an administrator, have available to monitor and manage the troubleshooting tools in any environment (development, pre-production, and production). Managing the troubleshooting tools in a production environment is especially important as many of these tools negatively affect performance.

In this exercise, you worked with a local broker; the same tools are also available for managing remote brokers after a connection has been established to the remote broker from WebSphere Message Broker Explorer.




EXempty
Exercise 6. Identifying runtime problems
Estimated time

01:00


This exercise consists of two parts.

Part one is a paper exercise and involves analyzing a message flow that encounters various runtime problems. Given what you know about component behaviors and how a message flow author can alter those behaviors, answer the question, Where can the affected message be found?

Part two provides you with a chance to analyze and correct some error situations that involve the WebSphere Message Broker and the WebSphere MQ queue manager running on your classroom workstation. Accordingly, you have an opportunity to employ the various problem determination tools discussed in class.

In part two, directions are intentionally brief. You are to draw on your lecture and exercise experiences of this week to come up with your solution.

For both parts, you might want to team up with another student.

The solutions to both parts of this exercise are given in Appendix A.



• Describe the symptoms of runtime and environmental problems

• Isolate a problem to a particular component

• Determine the exact nature of a problem and correct it

Required materials

The classroom workstation that you have been using along with exercise files located in these directories: C:\Labs\Lab6 and C:\Labs\Tools.


© Copyright IBM Corp. 2010 Exercise 6. Identifying runtime problems 6-1



Since transaction management is part of the exercise (Part 1), be prepared to discuss message in-doubt scenarios.

Part 2 challenges students with respect to their problem recognition and problem resolution capabilities. Note also that problem resolution may involve corrections to either the IBM WebSphere Message Broker, the IBM WebSphere MQ queue manager, or both.

Two error scenarios are presented, ranging from simple to complex. The first involves a mismatch between an output queue name, specified as an MQOutput node property, and the queues available on the broker’s queue manager. Students should experience a WebSphere MQ runtime error, specifically an MQPUT failure with MQRC_UNKNOWN_OBJECT_NAME (RC=2085). The initial symptom is that no messages appear on the anticipated output queue. However, the astute student will locate the message somewhere else, namely a CATCH queue. A correction can be applied one of two ways: create the (missing) queue so the name agrees with the message flow or (preferably) override the queue name using the Configure properties of the .bar file, identifying a queue that does exist on the broker. The astute student, who examines the supplied .bar file in advance, will likely detect and correct the queue name mismatch before the initial deployment.

The second scenario is more ambitious, and somewhat difficult to recognize. It may be desired (in the interest of time) to supply a hint that user trace will be a valuable tool in recognizing what is happening. The idea in this scenario is to deploy a message flow with instructions to the broker to launch additional instances in the event the rate of messages to the input queue justifies same. However, the queue is set (also through the running of a script) to Open Exclusive, thus preventing additional threads from being launched. Recognition of the problem is visible in a user trace where only one thread identifier appears — repeatedly — rather than several different thread identifiers. The goal here is for the students to isolate the problem to a mismatch between the deployed message flow properties (additional instances) with a conflicting queue property (open exclusive).




EXempty
Part 1: Analyzing message flow runtime failures

This part of the exercise presents eight message flows, each experiencing a runtime exception. Your task is to evaluate the runtime circumstances and determine where the affected message is likely to be located.

In each of the following scenarios, you are asked to determine what happens to the message being processed when the indicated exception is thrown by the designated processing node.

In each of the flows TxMode indicates the state of the nodes Transaction mode property.

__ 1. Queue manager dead-letter queue = DLQ; IN queue backout queue = IN_BOQ

Record your answer here:

The message is rolled back to the input queue. After rollbacks reach the backout threshold, the message is put to IN_BOQ.






The message is discarded because the flow is not transactional and therefore cannot be rolled back. The MQInput node’s Catch terminal is not wired; therefore, it is not an option to be considered.

__ 3. Queue manager dead-letter queue = DLQ; IN queue has no backout queue


The message is rolled back to the input queue. After the backout threshold is reached, the message is put to the DLQ. The MQInput node’s Catch terminal not wired.



The message is propagated through the Compute node’s failure terminal and is thus written to the Failure queue.




EXempty

The message is propagated through the Compute node’s Failure terminal; this fails, so is propagated to the Catch terminal and thus to the Catch queue, regardless of the transactional nature of the flow.



The message is written to the Failure2 queue (regardless of transaction mode).





Hint

The original exception was thrown in the Out node, but more exceptions occurred during explicit exception handling.


The message is put onto the IN_BOQ after 2*BackoutThreshold retries which failed in FAILURE2. If the IN_BOQ was full or PUT is disabled, the broker tries to put the message onto the DLQ. If that fails as well, the message loops between the MQInput node and the Failure2 MQOutput node.


Hint

The original exception was thrown in the Compute node, but more exceptions occurred during explicit exception handling.




EXempty


The message is discarded after the exception indicated in the Catch node. The Failure2 path is never taken because the flow is non-transactional; therefore no rollback beyond the Catch node occurs.

Part 2: Isolating and correcting problems

Instructions in this exercise are intentionally brief; otherwise, the goal of the exercise, for you to apply your accumulated product and problem determination knowledge, is compromised.

In Scenario 1, you are given a preconfigured BAR file and some information about its content and some information of what to expect, in terms of what constitutes successful execution. Some general hints and tips, however, can be provided.

• What is (or are) the expected result (or results) of the BAR file content? This result is likely to be the initial criteria to determine if all is well (or not).

• Recall that there are several components participating: WebSphere Message Broker Explorer, the broker, and the queue manager. When, and if, something goes wrong, error messages are likely to be generated. The question to ask is, from which component?

• What do you know, or what can you determine, about the message flow and its use of CATCH or FAILURE logic? What do you know about the broker queue manager in terms of a dead-letter queue? Keep this in mind when assessing the question “Where is the message?” in the context of the default behaviors discussed in the lecture.

• Also be aware that even though this is an WebSphere Message Broker class, the interaction, and dependency between the broker and the queue manager are significant. When it comes to problem recognition and problem resolution, there is considerable overlap between the two products.

• Although you have access to both WebSphere Message Broker Explorer and WebSphere Message Broker Toolkit in this class, the focus of the exercise is to use




WebSphere Message Broker Explorer and system tools as the primary troubleshooting aid.

Scenario 1

You will be working with a variation of the message flow used in Exercise 2 where XML test messages delivered to EX2_IN are modified with the addition of a time and date stamp and delivered to an output queue.

In this variation, the MQReply node has been replaced with an MQOutput node intended to provide equivalent function (recall the three choices of Destination Mode as an MQOutput node property) by returning messages directly to EX2_REPLY.

__ 1. Import the Ex6a.bar file from the C:\Labs\Lab6\resources folder to the Servers folder in WebSphere Message Broker Explorer.

__ 2. Delete all deployed message flows from the default execution group on DEVBROKER.

__ a. Under the Brokers folder, right-click the default execution group.

__ b. Select Delete All Flows and Resources.

__ 3. Deploy Ex6a.bar to the default execution group. The message flow Ex2Flow6a should be displayed as a running flow after the deployment is complete.

__ 4. Use RfhUtil to test the message flow. Use test message Test_V2_Msg.xml found in C:\Labs\Lab2\data.

Hint

If you do not remember the steps for testing the message flow, refer Exercise 2.

__ 5. Evaluate the results.

Use whatever problem determination tools you think are required to understand exactly what is taking place. Apply corrective action as you see fit. If there is a problem, can you correct it more than one way?

Consider your efforts successful when the transformed message appears on EX2_REPLY.

Scenario 2

In this part of the exercise, you deploy a supplied BAR file.

The BAR file is the same as the one from Scenario 1, only in this case you modify the Additional Instances property for the message flow (Ex2Flow6a.cmf) to indicate that the broker can run up to three (3) additional instances of the message flow based on the load on the input queue (EX6_IN).




EXempty
Hint
Remember to define queue EX6_IN on your broker queue manager.

__ 1. If it is not already open, open Ex6a.bar in the Broker Archive Editor.

__ 2. Right-click the message flow file (.cmf) and click Configure.

__ 3. Set the Additional Instances property to 3.

__ 4. To ensure that scenario 1 does not interfere, modify the node properties and set the queue name for the output node, EX2_REPLY, to EX2_REPLY and the queue name for input node, EX2_IN, to EX6_IN

__ 5. Deploy the modified Ex6a.bar file to the default execution group as before.

When prompted, click OK to save the changes to the BAR file.

__ 6. Message flow Ex2Flow6a should appear as a running message flow. Ensure that there are no other message flows running in this or any other execution group.

__ 7. Open a Windows Command Prompt window and change directory to C:\Labs\Lab6\data

__ 8. Use the WebSphere sample program amqsput to put several messages at one time to the input queue (EX6_IN). Use the test message file Test_Lab6_GroupMsg.txt found in C:\Labs\Lab6\data as shown here:

amqsput EX6_IN DEVQMGR < Test_Lab6_GroupMsg.txt

__ 9. The test file Test_Lab6_GroupMsg.txt contains 11 (duplicate) messages, so the same number should appear on EX2_REPLY, right? And by running amqsput with a batch of messages, the additional instances provision of the BAR file would likely activate. How can you make sure? And if additional instances were not started, how might it be corrected?

Hint

User trace is a good tool to use to verify the number of threads allocated to the Ex2Flow6a message flow.

WebSphere MQ Explorer can provide, from the Open Input Count, an indication of the activity on EX6_IN. The question is: If multiple threads are not being allocated, what could be the cause?

To answer this question, here is another hint, and it deals with the classic case of a mismatch between broker attributes and queue manager attributes. Can you determine which ones?




__ 10. Stop and remove the message in the default execution group.




EXempty
The first part of the exercise was concerned with understanding broker default behavior in the event of an error (that is, an exception) in a message flow. Message flow design and WebSphere MQ queue definitions and specifications have an effect on where affected messages are ultimately found.

Part two simulated, to a degree, the nature of runtime and environmental errors that are likely to be encountered in a typical installation. Probably the most important thing to remember is the close relationship between the WebSphere Message Broker and the queue manager. Although a problem might manifest itself in one product, the contributing cause could likely be the other.




EXempty
Exercise 7. Accessing broker statistics
Estimated time

01:00


This exercise introduces you to the WebSphere Message Broker statistics and performance monitoring tools. In the first two parts of this exercise, you enable broker statistics collection and view the statistics in WebSphere Message Broker Explorer.

In the second part of this exercisel you subscribe to the WebSphere Message Broker statistics and write them to a queque.



• Enable broker resource and message flow statistics

• View broker statistics in WebSphere Message Broker Explorer

• Set up a subscription for broker statistics

Required materials

This exercise uses the Ex2.bar file located in the C:\Labs\Lab2\resources directory.

A fully configured workstation, as used in previous exercises


This exercise combines the use of publish/subscribe with gathering statistics.


© Copyright IBM Corp. 2010 Exercise 7. Accessing broker statistics 7-1



Part 1: Enabling message flow and resource statistics

In this part of the exercise, you enable message flow and resource statistics from WebSphere Message Broker Explorer for the message flow you ran in exercise 2.

__ 1. Delete all existing flow and resources from the default execution group on DEVBROKER.

__ 2. Import the Ex2.bar file from C:\Labs\Lab2\resources in the Broker Archive Files/Server folder in WebSphere Message Broker Explorer.

__ 3. Deploy the Ex2.bar file to the default execution group on DEVBROKER.

__ 4. Enable the collection of message flow statistics on the Ex2Flow message flow running in the default execution group on DEVBROKER.

__ a. Right-click the Ex2Flow message flow in the WebSphere Message Broker Explorer Navigator view.

__ b. Select Statistics > Start Message Flow Statistics from the context menu.

__ c. Verify that statistics collection has been started on the message flow by checking that the Statistics property in the Flow Properties QuickView is set to Started.




EXempty
Note
You can also view the message flow statistics collection status by running the mqsireportflowstats command line from a WebSphere Message Broker command console.

For example, to view the message flow statistics collection status for the default execution group running on the DEVBROKER enter:

mqsireportflowstats DEVBROKER -e default -s -g -j

__ 5. Enable resource statistics collection on the default execution group running on DEVBROKER.

__ a. Right-click the default execution group in the WebSphere Message Broker Explorer Navigator view.

__ b. Select Statistics > Start Resource Statistics from the menu.

__ c. When resource statistics are being collected, the Resource Statistics Active property identifies the resources that are being monitored. In addition, a warning message is displayed at the top of the execution group properties view indicating that statistics collection has a performance affect.

Verify that resource statistics collection has been started on the default execution group by checking that the Resource Statistics Active property in the Properties QuickView.




Note

You can also view the resource statistics collection status by running the mqsireportresourcestats command line from a WebSphere Message Broker command console.

For example, to view the resource statistics collection status for the default execution group running on the DEVBROKER enter:

mqsireportresourcestats DEVBROKER -e default

Part 2: Viewing broker statistics

In this part of the exercise you view resource and message flow statistics, change filter settings, and pause statistics collection in WebSphere Message Broker Explorer.

__ 1. Click Window > Show View > Resource Statistics to open the execution group Resource Statistics view (at the bottom of the pane) and Resource Statistics Graph view (at the top of the pane). These two views are displayed together. If you close one of the views, the other view is also closed.

__ 2. Click the JVM tab on the execution group Resource Statistics view.

__ 3. On the Resource Statistics Graph view, click Filter.

__ 4. Clear the options for reporting statistics on InitialMemoryInMB and CumulativeNumberOfGCCollections.




EXempty

__ 5. Display the Sockets statistics by clicking the Sockets tab in the execution group Resource Statistics view.

__ 6. Click the Sockets tab and the click Filter on the Resource Statistics Graph view.

Statistics information varies for each resources. Click OK to close the Filter window.

__ 7. Click Window > Show View > Message Flow Statistics to open the Message Flow Statistics view and Message Flow Statistics Graph view. These two views are displayed together. If you close one of the views, the other view is also closed.

__ 8. If it is not already selected, select the Ex2Flow message flow in the WebSphere Message Broker Navigator.




The Message Flow Statistics Graph view (top pane) shows the performance statistics for the entire message flow. The message flow Flow Statistics for each node are shown in the bottom pane.

__ 9. On the Message Statistics Graph view, click Filter.

__ 10. Click Select All to enable all the graph metrics and then click OK.

__ 11. When you enable message flow accounting and statistics collection in WebSphere Message Broker Explorer, a subscription is automatically created for ResourceStatistics and Message Flow statistics.




EXempty
To view the subscriptions in WebSphere Message Broker Explorer,:
__ a. Select the MQ Explorer - Content tab.

__ b. Double-click Subscriptions under DEVQMGR.

You should see two subscriptions.

The first subscription, $SYS/Broker/+/StatisticsAccounting/SnapShot/#, is used by WebSphere Message Broker Explorer to collect the message flow and accounting statistics.

The second subscription, $SYS/BROKER/+/ResourceStatistics/#, is used by the WebSphere Message Broker Explorer to collect the resource statistics.

Part 3: Set up subscriptions for resource statistics

If you enable resource statistics collection for one or more execution groups on a broker, you can subscribe to the messages that the broker publishes at 20 second intervals on the following topic:

$SYS/Broker/brokerName/ResourceStatistics/executionGroupLabel

In this part of the exercise, you subscribe to the resource statistics topic.

__ 1. Create local queues for this lab on the broker queue manager (DEVQMGR) by running the following command from a command console session:

runmqsc DEVQMGR < C:\Labs\Tools\PUBSUB.tst

__ 2. In WebSphere Message Broker Explorer, right-click Subscriptions under DEVQMGR and select New > Subscription.

__ 3. For the subscription name enter GetResourceStatistics and then click Next.

__ 4. Configure the properties on the Change properties window:

__ a. For Topic name, click Select, select SYSTEM.BROKER.DEFAULT.SUBPOINT and then click OK.

__ b. For Topic string, enter: $SYS/Broker/+/ResourceStatistics/#

__ c. For Destination queue manager, enter: DEVQMGR

__ d. For Destination name, enter: SUBREPLY_QUEUE




__ e. Click Finish and then click OK on the confirmation window.

__ 5. Verify that you have created a subscription by displaying active subscriptions in WebSphere Message Broker Explorer, for DEVQMGR. Your subscription should be displayed in the list of subscriptions.




EXempty
Part 4: Retrieve and review collected statistics
In this part of the exercise, you view the resource statistics from the subscription destination message queue and create an XML file containing the resource statistics.

Note

You can automate this process by having a WebSphere Message Broker developer create a message flow that reads the messages from the queue and writes the data to a file.

__ 1. Open RfhUtil.

__ 2. Select DEVQMGR for the Queue Manager Name.

__ 3. Select SUBREPLY_QUEUE for the Queue Name.

__ 4. Click Browse Q.

__ 5. Click the Data tab. You should see the resource statistics.

__ 6. Under Data Format, select XML so the data can be viewed as XML data.

__ 7. To make it easier to read the statistics data, copy the data into Windows Notepad, save it as an XML file and launch it in a web browser.

__ a. Select the message data in RfhUtil and then right-click and select Copy.

__ b. Open Windows Notepad and right-click and select Paste.

__ c. Save the file in C:\Labs as Statistics.xml and then close Windows Notepad.

__ d. In Windows Explorer, double-click the Stastistics.xml file to launch a web browser window.




__ 8. When you are finished examining the statistics, close the web browser window.

__ 9. Stop resource statistics in WebSphere Message Broker Explorer by right-clicking the execution group and selecting Statistics > Stop Resource Statistics.

__ 10. Verify that resource statistics collection has stopped by checking for a message on the Administration Log and that Statistics Active property in the Execution Group Properties QuickView is set to None.

__ 11. Stop message flow accounting and statistics in WebSphere Message Broker Explorer by right-clicking the EX2Flow message flow and selecting Statistics > Stop Message Flow Statistics.

__ 12. Verify that message flow statistics collection has stopped by checking the Administration Log and that the Statistics property in the Flow Properties QuickView is set to Started.

__ 13. Stop and remove the Ex2Flow message flow from the default execution group by right-clicking the default execution and selecting Delete all Flows and Resources.

End of exercise




EXempty
In this exercise, you used the WebSphere Message Broker Explorer and command line to enable broker and message flow statistics collection.

Finally, you used the WebSphere Message Broker Explorer to create a subscription for statistics information that is being collected. You learned how to enable the collection of statistics and to check on the status of collection settings.




EXempty
Exercise 8. Implementing web services and web services security
Estimated time

01:00


This exercise has you import some existing message flows that implement web services to understand the configuration and administration requirements.

In this exercise, you use some tools to ensure the environment to support the web service flows is working properly; then you test a deployed flow. Finally, you learn how to use some supplied tools to set up an example of a web service that can accept information from or deliver it to a secure transport using secure HTTP (HTTPS).


At the end of the lab, you should be able to:

• Implement message flows that provide and consume a web service

• Configure web service support

• Implement a web services flow using HTTPS

Introduction

The notion of a web service, a callable program that resides at a web location, creates an almost infinite extension to the classic remote procedure call (RFC) paradigm. As standards have stabilized, web services of all types are becoming common.

Required materials

A fully configured workstation, as used in previous exercises


© Copyright IBM Corp. 2010 Exercise 8. Implementing web services and web services security 8-1



This exercise guides students through the process of importing two simple message flows, the first to serve as a (local) web service, the second to call it.

The flows uses three types of HTTP nodes available to the message flow developer. A web service is characterized by starting with an HTTPInput node and ending with an HTTPReply node. The characteristic of the calling message flow is an HTTPRequest node. The parameter that links the two message flows is the URL specified in the HTTPRequest node that (presumably) agrees with the HTTPInput node.

Changing the URL in the HTTPRequest node to any valid web service URL would route the request accordingly. As expected, the reply from the web service would be routed back to the message flow that issued the original HTTPRequest.

This is information for you, the instructor. You are dealing with administrators. Their interest is what they must do to properly implement these flows. However, you can recall for them a bit of the lecture that gave an overview of what happens.




EXempty
Part 1: Configuring the HTTP listener for broker use

__ 1. If closed, open WebSphere Message Broker Toolkit so that you can import an existing project containing the message flows for this exercise.

__ a. Select File > Import.

__ b. From the list in the wizard, expand General

__ c. Select Existing Projects into Workspace and click Next.

__ d. Browse to the C:\Labs\Lab8\resources\WebSvc folder and then click OK.

__ e. Make sure the folder check box for WebSvc is selected.

__ f. Check the box Copy projects into workspace.

__ g. Click Finish.

__ 2. In WebSphere Message Broker Explorer create two local queues named PING_IN and PING_OUT under the DEVQMGR queue manager.

Note

You should already have a local queue named FAILURE on DEVQMGR. If not, create that as well.

__ 3. In the next step, you need a port to be used by the HTTPListener component of the broker.

__ a. Open a Windows Command Prompt window and enter: netstat -an

__ b. Examine the list of assigned and active port numbers and verify that port number 7085 is not already in use.

__ 4. In a WebSphere Message Broker command console session, set up the port to be used by the HTTPListener component of the broker:

mqsichangeproperties DEVBROKER -b httplistener -o HTTPConnector -n port -v 7085

__ 5. The broker must be stopped and restarted after issuing the mqsichangeproperties command in order for the changes to take effect.

Stop the broker by entering: mqsistop DEVBROKER

__ 6. Restart the broker by entering: mqsistart DEVBROKER




Part 2: Reviewing the message flows

__ 1. In the WebSphere Message Broker Toolkit, open and examine the CallWebSvc message flow under the WebSvc project. Ensure that it matches the following figure.

__ 2. Note the names of the MQInput node (PING_IN) and MQOutput nodes (FAILURE and PING_OUT). They reflect the queue names specified as properties and should match the queues you created.

__ 3. Click the HTTP Request node to view its properties.

In the Basic properties pane, view the entry for Web service URL. The format of the URL is as follows:

http://<machine_name>:<broker_listener_port_number>/<path>

Where the value of <path> is expected to agree with a similar value that is specified in the properties of the HTTPInput node in the target web service message flow. The default port number of 7080 is the broker default (but you are using 7085).

The HTTP Proxy Location property (on the HTTP Settings tab) is optional. If specified, it takes the form <machine_name>:<broker_listener_port_number>.

Do not make any changes but remember these values.

__ 4. Now, open the HTTPProtocol message flow. It should contain three nodes as shown in the following figure.

__ 5. Click the HTTPInput (7085) node to see its properties.




EXempty
Note the Path suffix for URL value. It must exactly match URL in the previous flow (the HTTPRequest node in that flow is starting this flow using that URL).
__ 6. Close both of the message flows.

Part 3: Creating and deploying a BAR file containing both message flows

__ 1. In the WebSphere Message Broker Toolkit, create a broker archive file called WebService.bar.

__ a. Select File > New > Message Broker Archive.

__ b. Select WebSvc as the Project.

__ c. For the Name, enter: WebService.bar

__ d. Click Finish. The new BAR file is opened in the Broker Archive editor.

__ 2. Add both of the message flows to the BAR file.

__ a. Check the boxes for CallWebSvc.msgflow and HTTPProtocol.msgflow.




__ b. Click Build broker archive.

__ c. Click OK on the success message. The message flows are added to the .bar file. Do not save the .bar file yet.

__ 3. You can change the queue names used by the message flow by editing the broker archive node properties using the Broker Archive Editor Manage tab and then modifying the node properties in the Properties view. You can also change the properties of the HTTP nodes.

Examine the values for the HTTPRequest and HTTPInput nodes in the BAR file:

__ a. While still in the Broker Archive editor, click the Manage tab.

__ b. Fully expand the two compiled message flows (.cmf files).

__ c. Click the HTTPInput node and HTTPRequest nodes in the tree to view their properties.




EXempty

During deployment, the URL for the target web service can be specified, thus overriding whatever value was used for development testing. Similarly, a simulation of a remote web service can be successfully tested locally.

To start the actual target web service, no changes are required to be made to the calling message flow. It is just a matter of specifying a different URL using the Broker Archive Editor Manage tab and redeploying the .bar file.

In this case, you use what has been provided for the connections.




Note

As seen in an earlier exercise, you can also edit the .bar file in WebSphere Message Broker Explorer by double clicking the .bar file, expanding the .cmf file, right-clicking the node, and then selecting Configure from the context menu.

__ 4. For this exercise, you will allow for more than one instance of the flow simultaneously.

While still on the Broker Archive Editor Manage tab, select HTTPProtocol.cmf.

__ 5. Change Additional Instances to 2.

__ 6. Change the Additional Instances parameter for the CallWebSvc.cmf to 2.

__ 7. Save your work by selecting File > Save All.

__ 8. Deploy the newly created broker archive to the default execution group.

__ a. Right-click the WebService.bar file in the Broker Development Navigator view and select Deploy from the menu.




EXempty
__ b. In the Deploy window, click default and then click Finish.
The message flows should appear under the default execution group in the Brokers view.

__ c. Use the Deployment Log to ensure the deployment was successful.

__ 9. Now, issue the netstat -an command again. The listener using port 7085 should now be displayed in the list.

The reason for the change is the deployment of the WebService flow. Since it contained an HTTPInput node, the broker compared the HTTP port number (7085) with that assigned to the broker, and since they matched, activated the broker listener.

Note

The mqsicreatebroker and mqsichangebroker commands can also be used to assign or change the broker listener port number by using the -P (HTTPPort) parameter. Be sure to use an uppercase “P” when entering this command as there is also a parameter which uses a lowercase “p”.

Later in this exercise, you learn how to configure Secure Sockets Layer (SSL) which uses a different port.

Part 4: Test your web service application

__ 1. To test the flow of the data between your two message flows, expand the WebSvc project until you find the TestEnq.enqueue file under the Enqueue subtree. Double-click to open it.

__ 2. Change the properties in the test client as follows:

__ a. Change the queue manager name to match your broker queue manager name (DEVQMGR).

__ b. Change the port to match the broker queue manager TCP port 1416 (not the HTTP port you have worked with).




__ c. Type CTRL+S to save your work.

When prompted, select WebSvc as the folder name and TestEnq1 as the file name.

__ 3. Click Send Message to put a message on the PING_IN queue.

The message flow starts, calls the WebService flow, obtains the response, adds a message descriptor, and delivers it to the output queue called PING_OUT.

Note

The only result you see at this point is “Message Sent to Queue..”. You do not see the response message until you complete the next step.

__ 4. Use the WebSphere MQ Explorer to see if the message is on the output queue. You can right-click the queue and use the Browse Messages... button to view the message on the queue.

You can also use RfhUtil to browse the PING_OUT queue, if you want.

The message data should contain the following text:

<OutMsg><NewText>The date/time is:</NewText><DateTime>date_and_time_you_ran_the_flow</DateTime></OutMsg>




EXempty
If you browse the queue, the message data will appear like the following example.
Part 5: Implement SSL for your Web service application

It is entirely possible that the developer has tested in an unsecured environment, but when you roll out the application to production, you want to take steps to secure it. HTTP can be run over SSL to ensure that there is no hacking of the data while it is transported.

Imagine, in this case, a scenario where you have the flow that calls a web service being permitted across non-SSL HTTP connections. However, others might want to start that same web service using an HTML form in a browser. In that case, you only want to permit trusted access. There is no requirement to change the message flows. You will set up a new archive file to make necessary changes to the one flow to allow this scenario to work.

First, you must set up SSL for use. In a real-world environment, it is likely that you would obtain certificates from an external certificate authority. However, for purposes of testing or internal only use, the keytool utility has been shipped with the WebSphere Message Broker. You will use it for this exercise.

__ 1. Open a Broker command console session.

__ 2. Enter the following command to display a list of all the possible parameters to be used by the keytool utility:

C:\”Program Files”\IBM\mqsi\7.0\jre16\bin\keytool

__ 3. Next, you must create a keystore.

__ a. Enter the following in the Broker command console:

C:\”Program Files”\IBM\mqsi\7.0\jre16\bin\keytool -genkey -keypass devkey -keystore dev.keystore -alias tomcat

This begins the process of creating your keystore to be used by the broker.

__ b. You are asked a series of questions; fill them in as shown (the name you use is not important if you prefer something other than Mary Smith). Press the Enter key where you see no response in the following:

Enter keystore password: devkey




Note

The password is masked. You do not see the password on your display. When prompted to re-enter the password, enter devkey.

What is your first and last name? [Unknown]: Mary SmithWhat is the name of your organizational unit? [Unknown]: WMBV70What is the name of your organization? [Unknown]:What is the name of your City or Locality? [Unknown]:What is the name of your State or Province? [Unknown]:What is the two-letter country code for this unit? [Unknown]: USIs CN=Mary Smith, OU=WMBV70, O=Unknown, L=Unknown, ST=Unknown, C=US correct? (type "yes" or "no") [no]: yes

The keystore is now in your Broker root installation folder C:\Program Files\IBM\MQSI\7.0

__ 4. Create a directory named C:\keystores and copy the dev.keystore keystore file you created from C:\Program Files\IBM\MQSI\7.0 to the new directory.

__ 5. You must tell the broker about the new keystore and how to access it. You also must tell the HTTPListener to use the SSL port (not the default HTTP port you used earlier).

__ a. Enter the following commands in the order shown. Be careful about the case of all entries.

Note

If any paths contain spaces, such as the broker installation path, the entire parameter value must be enclosed in double quotation marks.

To save on typing use the up arrow key in the command console to retrieve previous commands and then edit the command to create a command. For example, type the first command shown, then press Enter. Press the up arrow key to retrieve the statement and




EXempty
then change the last two parameters (-o, -n and -v) to the syntax required for the second command and then press Enter.
mqsichangeproperties DEVBROKER -b httplistener -o HTTPListener -n enableSSLConnector -v true

mqsichangeproperties DEVBROKER -b httplistener -o HTTPSConnector -n keystoreFile -v C:\keystores\dev.keystore

mqsichangeproperties DEVBROKER -b httplistener -o HTTPSConnector -n keystorePass -v devkey

This final command sets the SSL port for HTTP connections.

mqsichangeproperties DEVBROKER -b httplistener -o HTTPSConnector -n port -v 7083

__ 6. After you have completed these changes, you can use the mqsireportproperties to check the settings:

mqsireportproperties DEVBROKER -b httplistener -o HTTPSConnector -a

You should receive a lengthy response, part of which includes text like the following:

HTTPSConnector='' uuid='HTTPSConnector'keystoreFile='C:\keystores\dev.keystore'

keystorePass='********' port='7083'

__ 7. The broker does not recognize those changes until you stop and restart it. Stop, then start the DEVBROKER.

__ 8. The broker should be ready to handle deployments of message flows that use SSL (if they request the correct port). Remember, in this case, you are only going to use one of your two message flows.

In the WebSphere Message Broker Toolkit, create a broker archive called SSLArchive.bar. Add the message flow called HTTPProtocol to it. Do not add the other message flow (CallWebSvc).

__ a. Right-click Broker Archives in the Broker Development navigator.

__ b. Select New > Message Broker Archive from the context menu.

__ c. For the Project, click the drop-down list and select WebSvc

__ d. For the Name, enter: SSLArchive.bar




__ e. Click Finish. The new .bar file is opened in the Broker Archive editor.

__ f. Click the check box for HTTPProtocol.msgflow (do not include the CallWebSvc message flow).

__ g. Click Build Broker Archive. The message flow is added to the .bar file.

Note

If you received a message asking if you want to save the TestEnq.enqueue, select No.

__ 9. In the Manage tab, expand the HTTPProtocol.cmf structure until you see the HTTPInput (7085) node.

__ 10. Click the HTTPInput node on the Manage tab.

__ 11. Modify the node properties to use SSL as follows:

__ a. Change the Path suffix for URL to use port 7083 (SSL) instead of 7085.

__ b. Check the Use HTTPS box.

The configuration parameters should be displayed as shown in the following example.

__ 12. Since you want to let more than one connection to this flow without delay, change the number of instances to 5.

__ a. Select HTTPProtocol.cmf on the Manage tab.




EXempty
__ b. Change the Additional Instances parameter to 5.
__ 13. Save the archive by selecting File > Save.

__ 14. Create an execution group named SSLWebServices on DEVBROKER.

__ a. Right-click DEVBROKER in the Brokers view.

__ b. Select New Execution Group from the menu.

__ c. Enter: SSLWebServices

__ d. Click OK.

__ 15. Deploy the broker archive file SSLArchive to the SSLWebServices execution group.

Important

Do not deploy the SSLArchive.bar to the same execution group as you have the non-SSL flow running.

__ 16. Ensure the deployment worked properly by checking the Deployment Log.

__ 17. Check to see that there is now a listener for port 7083 by using the netstat -an command from a Windows Command Prompt window.

__ 18. Test the message flow.

__ a. Open Windows Explorer and go to the C:\Labs\Lab8\resources\WebSvc folder.

__ b. Double-click the WebSvcform.html file to open the file in a web browser.




__ c. Click Obtain Date/Time.

__ d. If you have set up the keystore correctly, you get a security message about the certificate being used.

__ e. To see the information you entered when you created the keystore file in Mozilla Firefox, click Technical Details,

To view the SSL values you entered during configuration, click Technical Details.




EXempty
__ f. To accept the certificate, expand I Understand the Risks and then click Add Exception.
This results in the path into the message flow being completed. The browser window is updated to show the message returned from the HTTPReply node in the flow.

__ 19. Close the web browser window.

__ 20. Stop the HTTPProtocol flow in the SSLWebServices execution group.

__ 21. Stop the CallWebSvc and HTTPProtocol flows in the default execution group.

END OF EXERCISE





While it might not be obvious, the combination of the two flows used in this exercise approximates a What time is it? application. The “calling” flow can be altered to call multiple different web services by changing the URL value in the broker archive before deployment.

As you saw, it is also possible to change how a message flow that behaves as a web service can be called in different ways. And you learned how to set up a broker to use SSL in addition to non-SSL HTTP transports.




EXempty
Exercise 9. Implementing a user-defined extension
Estimated time

00:30


A user-defined extension can take the form of a message processing node or a parser. Nodes can be written in the C or Java programming languages. Parsers can only be written in C. Writing the node is a programming exercise not covered in this class.

This exercise takes you through the process of implementing, that is, installing, a user-written processing node. The exercises use the sample nodes shipped with the product, and the online help, to finish this exercise.

As an administrator, it is likely that you are the individual who implements these extensions. However, the developer would usually provide the packages necessary for implementation.



• Describe how to implement an already-written message processing node so that it can run on one or more brokers and appear in one or more instances of the workbench

Introduction

The architecture of the IBM WebSphere Message Brokers product permits programming extensions in the form of message processing nodes and custom parsers. This feature has attracted the attention of many IBM Business Partners who offer complimentary products developed as user extensions. In addition, through SupportPacs, IBM supplies, at no cost, various nodes and parsers for consideration by IBM WebSphere Message Broker clients.

This exercise uses resources shipped with the IBM WebSphere Message Broker product. You are directed to pertinent sections of the online help as a source for instructions on how to finish the exercise.


© Copyright IBM Corp. 2010 Exercise 9. Implementing a user-defined extension 9-1


Two sample nodes are used in this exercise: SearchFilter and NumCompute.

Required materials

A fully configured workstation, as was used in previous exercises, provides the means of access to the online help and the Samples Gallery used in this exercise.


Students use the Samples Gallery to implement two user-written nodes supplied.

Keep in mind that this is a class for administrators, so the students should leave the class with an understanding that user extensions do not come with the product. They are usually purchased or developed in-house and then installed. It is the administrator who more than likely be called upon to do just that. It is therefore essential that the students have an understanding of what is needed (in terms of parts), where things go (in terms of directories) and on what server (broker or workbench). That is the goal of this exercise. It is not intended to explain how to create all the necessary parts since those would usually be provided by the developer.




EXempty
Preface

This exercise presumes a successfully installed, configured, and running IBM WebSphere Message Broker instance.

Note

You can choose not to implement the message flows that use the nodes. In fact, you can skip those steps that implement the node in the WebSphere Message Broker Toolkit, if you want to. The nodes really need only be available as executable files in the runtime environment.

Part 1: Getting started

The objective of the exercise is to implement the two nodes that have been written and supplied for implementation, SearchFilter (a Java node) and NumCompute (a C node). There are also supplied message flows to test the implementation of the nodes. These message flows require some queues to be created for testing.

__ 1. Open a Windows Command Prompt window and run the following command:

runmqsc DEVQMGR < C:\Labs\Labs\UDE_QUEUES.tst

Important

The queue manager, DEVQMGR, must be running. Check the results of the command to be sure that it ran properly.

__ 2. In the WebSphere Message Broker Toolkit, open the Samples Gallery.

__ a. Select Help > Welcome

__ b. Click Samples.

__ c. Double-click the Sample and Tutorials tab so that you can see the entire window.

__ 3. Expand Application Samples.

__ 4. Scroll down the list until you see a sample named User-defined Extension sample.

__ 5. Click More information under User-defined Extension sample to open the sample.

Since nodes can be written in C or Java, this is a good sample since it has one of each. Click the link Read about the sample to learn what it entails. Be sure to follow




the links to see the details about each of the test message flows, including the queues they use (the ones you created).

There are two aspects of implementing a user extension. Each broker that is to support message flows that use, in this example, the SearchFilter and NumCompute nodes requires a suitable executable file to be installed. Similarly, each workbench instance intended to offer the nodes for use by message flow developers requires some code so that the nodes are displayed on the palette. You have an opportunity to set up both.

If you select one of the setup links in the Samples Gallery (Import and partially set up sample or Import the sample), the work is done for you. However, when it comes time for you to set up a node, you might not understand what is required. In addition, the setup done in the gallery actually adds more to the workspace than you would usually add (including the projects that have the source code for the nodes). To make this more realistic, you will take some of the compressed files provided in the sample and set up a separate lab area that more closely parallels the artifacts you would get in the “real world.”

__ 6. When you are done reading about the sample, double-click the Samples and Tutorials tab to return it to its original size.

Part 2: Extract and import the samples

Usually, a developer supplies you with several compressed files which contain the artifacts to be deployed. One contains the various files to be included in a project to implement the node in the workbench. The other is the executable files used to implement the nodes for the broker. Those are the only required files.

The sample actually has several projects associated with it:

1) UDESampleCCode.zip contains the source files for the NumCompute node

2) UDESampleJavaCode.zip contains the source files for the SearchFilter node

3) UDESampleLibraries.zip contains the executable files, a .lil file for the NumCompute sample, and a .jar file for the SearchFilter sample

4) UDESampleMessageFlowProject.zip contains files related to the message flows (including some enqueue files that are useful for testing)

5) UDESamplePlugInNodeProject.zip contains the properties definitions for the two sample nodes

You need the sample libraries file (3) and the sample plug-in node project file (5) to implement the node. If you also want to implement and test the message flow project (4), you can do that as well.

__ 1. In Windows Explorer, browse to the directory C:\Labs\Lab9\resources. Find the five compressed files seen above.




EXempty
__ 2. Still in Windows Explorer, extract the required files.
__ a. Right-click the UDESampleMessageFlowProject.zip file and select Extract All.

__ b. The Compressed Folder Extract wizard starts. Click Next.

__ c. The wizard suggests a file directory to extract the compressed files to (in this case, C:\Labs\Lab9\resources\UDESampleMessageFlowProject). Accept this directory by clicking Next, and the files are extracted.

__ d. Clear the Show extracted files box, and click Finish.

__ 3. Repeat step 2 for the UDESampleLibraries.zip file and UDESamplePlugInNodeProject.zip files, creating two new folders in the \Labs\Lab9 folder as follows:

• Extract UDESampleLibraries.zip into folder Labs\Lab9\resources\UDESampleLibraries

• Extract UDESamplePlugInNodeProject.zip into folder Labs\Lab9\resources\UDESamplePlugInNodeProject

Browse the newly created folders and examine the files that were extracted from the compressed files.

__ 4. In the WebSphere Message Broker Toolkit, select File > New > Message Flow Project.

__ 5. Name the project UDESampleMessageFlowProject and clear the box to Use default for location. This causes an error message to be displayed that states “Project location directory must be specified.”

__ 6. Click Browse and browse to C:\Labs\Lab9\resources, highlighting the folder called UDESampleMessageFlowProject.

__ 7. Click OK and then click Finish. The resource navigator pane is updated.

__ 8. Expand the newly created UDESampleMessageFlow project. You will see the message flows and other files that were imported into the toolkit. You will also see a red decorator on the Flows element.




Click the Problems tab to view the problems in detail.

These problems appear because the message flow was imported, but the two user-defined nodes (NumCompute and SearchFilter) that the message flow uses are not yet defined to the toolkit.

Since the nodes have not been defined to the toolkit, do not open the flows yet. You will import them in the next steps.

Note

Steps 9 through 13 are not required to create a user-defined node. They are provided in this exercise as a way to verify that the node has been implemented correctly.

__ 9. Click File > New > Project.

__ 10. After the wizard opens, expand the entry for Message Broker - Node Development and click User-defined Node Project.




EXempty

__ 11. Click Next. The User-defined Node project wizard starts.

__ a. When prompted for an existing palette category or new name, click Create a new category and enter UDESample.

__ b. For the Project name, enter: UDESamplePlugInNodeProject




__ c. The remaining fields are automatically populated automatically as soon you click the Plug-in ID field.

__ d. Click Finish. The wizard finishes.

__ 12. The final project is the library containing the executable files.

__ a. Select File > New > Project.

__ b. When the wizard opens, browse to the General folder and expand it

__ c. Click Project, and click Next. The New Project dialog opens.

__ a. For Project name, enter: UDESampleLibraries

__ b. Clear the Use default location box which causes an error message to appear that states “Project location directory must be specified.”

__ c. Click Browse, browse to the C:\Labs\Lab9\resources folder, and select the folder called UDESampleLibraries. Click OK.

__ d. Click Finish to complete the project creation.




EXempty
__ 13. In your toolkit, browse the contents of the imported projects in the resource navigator pane in the Broker Development perspective.
Do not yet attempt to open any components. There is one more step before the nodes can be used. There are still errors reported in the Problems tab.

__ 14. Exit the WebSphere Message Broker Toolkit.

Part 3: Implement the nodes

The two new message flow nodes are not yet defined to the WebSphere Message Broker Toolkit. In this step, you make them known.

__ 1. Use Windows Explorer to copy the UDESamplePlugInNodeProject folder from C:\Labs\Lab9\resources to C:\Program Files\IBM\WMBT700\plugins (copy the entire folder; this will bring along all the subfolders as well). This makes the nodes visible in the palette for the application developer.

__ 2. Restart the WebSphere Message Broker Toolkit and select your workspace.

__ 3. Notice that the errors on the Problems tab are still present, even though you defined the plug-in nodes in step 1. This is because the toolkit is not yet aware of the presence of the plug-in nodes.

To fix this problem, clean all the projects.

__ a. Select Project > Clean to invoke the cleanup utility and rebuild the projects.

__ b. In the Clean dialog, select Clean all projects and then click OK.

The errors in the Problems tab should disappear. You might need to run the clean utility more than once.

Note

The project clean utility is a useful tool for developers to use if errors or warnings occur due to inconsistencies in the project that may occur due to errors in the development process.




__ 4. Now the user-defined nodes are defined to the toolkit. Verify that nodes are available in the development palette.

__ a. In the Broker Development Navigator view, expand the UDESampleMessageFlowProject.

__ b. Expand the message flows, and double-click NumCompute.msgflow.

The message flow opens in the Message Flow editor.

__ c. Scroll to the bottom of the drawing palette. You should see the entry for the UDESamplePlugInNodeProject.

__ d. To view the nodes within the project, click it. The NumCompute and SearchFilter nodes should appear under the UDESamplePlugInNodeProject category.




EXempty
The appearance of the custom nodes in the developer’s palette verifies that the plug-in node has been properly implemented in the WebSphere Message Broker Toolkit.
__ 5. Next, you must implement the broker runtime components for the user-defined nodes.

__ a. In the WebSphere Message Broker Toolkit navigator, expand the project named UDESampleLibraries.

__ b. Expand the WindowsSpecific folder.

__ c. You should now see the NumComputeNode.lil file, and the UDESampleJavaCode.jar file.

__ d. Press and hold the Ctrl key and highlight both of these files; no other files should be highlighted.

Note

You must only highlight the two files mentioned. They appear at different levels in the hierarchy so be sure to expand and then highlight only those two files.




__ e. With NumComputeNode.lil file, and the UDESampleJavaCode.jar files highlighted, select File > Export > General > File System and export these files into a directory named C:\UDELibraries,

__ f. You are asked if you want to create the directory if it does not exist. Click Yes.

__ g. Using Windows Explorer, verify that the NumComputeNode.lil file, and the UDESampleJavaCode.jar files are in the C:\UDELibraries directory and that no additional folders or files have been copied into the directory.

__ 6. Next, the broker must be updated so that it can access the files at run time.

From a broker command console, issue the following commands to implement the runtime nodes.




EXempty
Note
The flag in the second command is a lowercase “L”. The directory is the To directory you specified in the previous step.

mqsistop DEVBROKER mqsichangebroker DEVBROKER -l C:\UDELibraries mqsistart DEVBROKER

Part 4: Deploy and test

__ 1. In the WebSphere Message Broker Toolkit, create a broker archive file.

__ a. Select File > New > Message Broker Archive.

__ b. For Project, click New.

__ c. In the New Project dialog:

- Enter WM64UDE as the project name. - Leave the Use default location box checked. - Click Finish to return to the Message Broker Archive dialog.

__ d. For the broker archive file name, enter: UDE_Flows.

__ e. Click Finish. The broker archive file editor opens.




__ 2. In the Broker Archive editor Prepare tab:

__ a. Scroll down to and click the NumCompute.msgflow and SearchFilter.msgflow items In the list of deployable artifacts.

__ b. Click Build broker archive to add those files to the .bar file.

__ 3. Select File > Save All to save the .bar file.

__ 4. Verify that the UDE_Flows.bar file has been created under the WM64UDE folder in the navigator.

__ 5. Right-click the UDE_Flows.bar file, and select Deploy from the menu.

__ 6. Select the default execution group on DEVBROKER and click OK. The .bar file is deployed to the execution group.

In a few moments, you should see the two message flows appear under the default execution group in the Brokers view.

__ 7. Check the status of the deployment by looking at the Deployment Log.




EXempty
__ 8. After the flows appear under the execution group, you can confirm they are active by going to the IBM WebSphere MQ Explorer and checking that the two input queues (UDESAMPLE.NUMCOMPUTE.IN and UDESAMPLE.SEARCHFILTER.IN) have been opened; the Open Input count for them should be one, not zero.
__ 9. Test the flows in WebSphere Message Broker Explorer.

__ a. Expand the UDESampleMessageFlowProject.

__ b. Expand the Flow Tests subtree to reveal two test files.

__ c. Double-click the UDESampleSearchFilterMessage.mbtest file to open it.

__ d. In the Message Flow Test Events pane, an Enqueue and a Dequeue event appear. Click the Enqueue event.




__ e. Under the Detailed Properties, change the Port and Queue Manager values to correspond to your broker queue manager (DEVQMGR) and port.

__ f. Click Send Message to send the test message to the queue.

__ g. In the Message Flow Test Events pane, click the Dequeue event.

__ h. Under the Detailed Properties, change the Port and Queue Manager values to correspond to your broker queue manager (DEVQMGR) and port, as you did in step e for the enqueue event.

__ i. Click Get Message to retrieve the message from the queue.

__ j. The message should appear in the Message pane.




EXempty

If you want, you can perform other tests on this message flow and the UDESampleNumComputeMessage message flow.

See the tests as described in the “Run the sample” section of the Samples Gallery (that you saw in the first part of this exercise). Usually, the administrator would be responsible for the deployment of the user-defined nodes, while the application developer would be responsible for testing the components after deployment.

End of exercise





This exercise exposes the extensibility of WebSphere Message Broker. Extensions are permitted in the form of custom nodes and parsers, the source of which might be in-house, a vendor, or an IBM SupportPac.

Regardless of the source, it is the installation process that ensures the broker can access the code when called for by a message flow. For a user-written node, the installation process also lets the developer see the node in a workbench instance.



Instructor Exercises GuideV1.2.2

AP
Appendix A. Exercise solutions
Exercise 2, Using the WebSphere Message Broker Toolkit

Part 3, Step 11:

The input data file contains the string <Version>2<Version>. Assuming all other syntax is correct, the message should be transformed and sent to the EX2_REPLY queue.

Part 3, Step 14b:

In RfhUtil, Read Q is equivalent to a GET operation which removes the message from the queue; Browse Q does not remove the message from the queue.

Exercise 6, Identifying runtime problems

Part 1

1. Queue manager’s dead-letter queue = DLQ; IN queue’s backout queue = IN_BOQ

Answer:

The message is rolled back to the input queue. After rollbacks reach the backout threshold, the message is put to IN_BOQ.

.


© Copyright IBM Corp. 2010 Appendix A. Exercise solutions A1


AP
Answer:

The message is discarded because the flow is not transactional (TxMode=No) and therefore cannot be rolled back. The MQInput node’s Catch terminal is not wired; therefore, it is not an option to be considered.

3. Queue manager’s dead-letter queue = DLQ; IN queue has no backout queue

Answer:

The message is rolled back to the input queue. After the backout threshold is reached, the message is put to the DLQ. The MQInput node’s Catch terminal not wired.




AP
Answer:

The message is propagated through the Compute node’s failure terminal and is thus written to the Failure queue.


Answer:

The message is propagated through the Compute node’s Failure terminal; this fails, so is propagated to the Catch terminal and thus to the Catch queue, regardless of the transactional nature of the flow.




AP
Answer:

The message is written to the Failure2 queue (regardless of transaction mode).


Answer:

The message is put onto the IN_BOQ after 2*BackoutThreshold retries that failed in FAILURE2. If the IN_BOQ was full or PUT is disabled, the broker will try to put the message onto the DLQ. If that fails as well, the message will loop between the MQInput node and the Failure2 MQOutput node.




AP
Answer:

The message is discarded after the exception indicated in the Catch node. The Failure2 path will never be taken because the flow is non-transactional; therefore no rollback beyond the Catch node will occur.

Part 2

Scenario 1

After submitting the test message, you will note two problems that occur in the Windows (application) error log:

• The warning message in the log is from Windows: “Operating system error: The system cannot find the path specified. opening trace file 'c:\MQ641\Lab2\ExListTrace.txt' for trace node 'Ex2Flow6a.TraceExList'.”

This indicates the message flow contains a trace node that is attempting to write its output to a directory which does not exist. To correct this, you need to create the specified directory or modify the .bar file to change the path. Recall that if a trace node is sending its output to a file, the directory path specified in the trace node properties must exist, or the file will not be created. Note that if you correct this problem before correcting the next error in the log, the trace output that is written to the file will provide further details on the error.


© Copyright IBM Corp. 2010 Appendix A. Exercise solutions A-5


To modify the path in the .bar file:

a. Select the Ex6a.bar file in the Navigator and select Open Broker Archive Editor.

b. Expand the configuration file (.cmf) until you see the list of nodes.

c. Right-click the TraceExList node and select Configure.

d. In the Properties view for TraceExList, change the path to C:\Labs\Lab6\ExListTrace.txt

e. Save the .bar file.

f. Redeploy the .bar file.

• The error message in the log is the message flow failing with a reason code 2085 when it attempts to write to queue EX2_REPLYx, which does not exist. To correct this, you must define this queue to the queue manager or modify the queueName property for the EX2_REPLY node to a queue name that exists.

Again, if you corrected the trace node problem first and reran the message flow, you would see details on the missing queue problem in the trace output.

Scenario 2

This scenario is much more ambitious than the first, and it can be challenging to diagnose the problem.

One hint is that a user trace is a valuable tool in recognizing what is happening. The idea in this scenario is to deploy a message flow with instructions to the broker to launch additional instances in the event the rate of messages to the input queue justifies it. However, the queue is set (through the running of a script) to “open exclusive” mode, thus preventing additional threads to be launched.

Recognition of the problem is visible in a user trace where only one thread identifier appears, repeatedly, rather than several different thread identifiers. The goal here is to isolate the problem to a mismatch between the deployed message flow properties (specifically the Additional instances property) with a conflicting queue property (the Open exclusive property).


A-6 Message Broker System Administration © Copyright IBM Corp. 2010

V5.4

backpg
Back page

wm6431-vm6431xinst

Documents