Copy of Message Broker v6.1 Red Book

ibm.com/redbooks Redpaper

Front cover

Using the New Features in WebSphereMessage Broker V6.1

Sunil Mathew GeorgeRosaline Makar

Sambasivarao NanduriLara Payne

Wolfgang ReismannCarla Sadtler

Introduction to WebSphere Message Broker

Overview of features added in V6.1

Details on select features

http://www.redbooks.ibm.com/


International Technical Support Organization

Using the New Features in WebSphere Message Broker V6.1

January 2009

REDP-4458-00

© Copyright International Business Machines Corporation 2009. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp.

First Edition (January 2009)

This edition applies to WebSphere Message Broker V6.1.

This document was created or updated on January 30, 2009.

Note: Before using this information and the product it supports, read the information in “Notices” on page vii.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixThe team that wrote this paper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1. Introduction to WebSphere Message Broker V6.1. . . . . . . . . . . . . . . . . . . . . 11.1 WebSphere Message Broker V6.1 feature overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.1.1 Universal connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.1.2 Routing and transformation capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.1.3 Simple programming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.1.4 Operational management and performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2 Available editions of WebSphere Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.1 WebSphere Message Broker Trial Version V6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.2 WebSphere Message Broker Starter Edition V6.1 . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.3 WebSphere Message Broker for Remote Adapter Deployment V6.1 . . . . . . . . . . . 51.2.4 WebSphere Message Broker V6.1 Enterprise Mode . . . . . . . . . . . . . . . . . . . . . . . 7

1.3 Technical overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.3.1 Message flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.3.2 Message flow processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.3.3 Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.3.4 Data formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3.5 Messaging mediation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.4 Usage patterns for WebSphere Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.4.1 Service enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.4.2 Service virtualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.4.3 Message enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.4.4 Message brokering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.4.5 File processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.4.6 Event processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2. New features in WebSphere Message Broker V6.1 . . . . . . . . . . . . . . . . . . . 192.1 Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.2 File transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.3.1 Message-based authentication and authorization. . . . . . . . . . . . . . . . . . . . . . . . . 212.3.2 WS-Security support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3.3 DataPower integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2.4 EIS connectivity with JCA adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5 Web 2.0 support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6 TCP/IP nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.7 WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.7.1 New features for existing nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.7.2 Compatibility with WebSphere MQ V7 publish and subscribe . . . . . . . . . . . . . . . 282.7.3 Improved administration with MQ via the Message Broker Explorer Eclipse

Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292.8 JMS transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

© Copyright IBM Corp. 2009. All rights reserved. iii

2.9 WebSphere Transformation Extender. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.10 Common Event Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.10.1 Enabling event emission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.10.2 Integration with WebSphere Business Monitor and Modeler . . . . . . . . . . . . . . . 31

2.11 IBM Tivoli Composite Application Manager for SOA 7.1. . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 3. Web services support in WebSphere Message Broker V6.1 . . . . . . . . . . . 333.1 Web services overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

3.1.1 Web services core technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.1.2 SOAP messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3.2 SOAP nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.3 Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

3.3.1 Web service provider and consumer (SOAP Nodes sample) . . . . . . . . . . . . . . . . 373.3.2 Dynamic Web services (WSRR Connectivity sample) . . . . . . . . . . . . . . . . . . . . . 403.3.3 Asynchronous Consumer sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.4 Node details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.4.1 SOAPInput node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.4.2 SOAPReply node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.4.3 SOAPRequest node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463.4.4 SOAPAsyncRequest and SOAPAsyncResponse nodes . . . . . . . . . . . . . . . . . . . 463.4.5 SOAPExtract node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.4.6 SOAPEnvelope node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3.5 SOAP domain and parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513.6 Web services extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

3.6.1 SOAPInput and SOAPReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533.6.2 SOAPRequest node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553.6.3 SOAPAsyncRequest and SOAPAsyncResponse nodes . . . . . . . . . . . . . . . . . . . 56

3.7 Improved WSDL integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563.8 Integration with WebSphere Service Registry and Repository . . . . . . . . . . . . . . . . . . . 60

3.8.1 EndpointLookup node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613.8.2 RegistryLookup node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653.8.3 Dynamic search criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 4. File processing support in WebSphere Message Broker V6.1 . . . . . . . . . . 694.1 File processing overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704.2 File processing nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

4.2.1 FileInput node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724.2.2 FileOutput node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

4.3 Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874.3.1 Simple file transfer example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874.3.2 Large file handling and bulk transfer example . . . . . . . . . . . . . . . . . . . . . . . . . . . 894.3.3 Aggregator and splitter pattern example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904.3.4 Content-based routing pattern example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934.3.5 File processing nodes used with WebSphere MQ File Transfer Edition . . . . . . . . 944.3.6 File Adapter for z/OS sequential files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

4.4 References and additional information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 5. EIS adapter support in WebSphere Message Broker V6.1 . . . . . . . . . . . . . 975.1 EIS adapter overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985.2 Adapter nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

5.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995.2.2 Incorporating EIS adapters into a message flow. . . . . . . . . . . . . . . . . . . . . . . . . . 99

5.3 Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015.3.1 Samples Gallery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

iv Using the New Features in WebSphere Message Broker V6.1

5.3.2 Using the SAP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Chapter 6. Security support in WebSphere Message Broker V6.1 . . . . . . . . . . . . . . . 1096.1 Identity-based authentication and authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

6.1.1 Security profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116.1.2 Message identity processing at input nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146.1.3 Message identity processing at output and request nodes. . . . . . . . . . . . . . . . . 116

6.2 WS-Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166.2.2 WS-Security example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

6.3 Using DataPower appliances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131How to get Redbooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Contents v

vi Using the New Features in WebSphere Message Broker V6.1

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

© Copyright IBM Corp. 2009. All rights reserved. vii

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml

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

AIX®CICS®DataPower®DB2®

Everyplace®IBM®MQSeries®Redbooks®

Redbooks (logo) ®Tivoli®WebSphere®z/OS®

The following terms are trademarks of other companies:

Oracle, JD Edwards, PeopleSoft, Siebel, and TopLink are registered trademarks of Oracle Corporation and/or its affiliates.

BAPI, SAP, and SAP logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries.

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

Active Directory, Microsoft, Windows, and the Windows logo 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.

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

Other company, product, or service names may be trademarks or service marks of others.

viii Using the New Features in WebSphere Message Broker V6.1

http://www.ibm.com/legal/copytrade.shtml

Preface

WebSphere® Message Broker V6.1 was released in December of 2007. This IBM® Redpaper publication discusses the new features and editions available with this release. It highlights several of the new features and provides information on how they can be used to enhance your messaging solutions.

This paper is of interest to architects who are building messaging or enterprise service bus (ESB) solutions, as well as to the implementers of WebSphere Message Broker solutions.

The team that wrote this paper

This paper was produced by a team of specialists from around the world working at the International Technical Support Organization, Raleigh Center.

Sunil Mathew George has a Bachelor of Electrical and Electronics Engineering degree from R.E.C - Trichy (2000 batch). He has over 8+ years of experience in J2EE™ programming, with exposure to Telcom and Business Integration domains. He has experience in developing SCA based JCA 1.5 based adapters and is a developer of the WebSphere Adapter for Flat Files and WebSphere Adapter for Email adapters. He is presently a member of the WebSphere Adapter for SAP® Software team. As part of the adapter team he has developed the Enterprise Metadata Discovery (EMD 1.0) specification compliant module for the Flat Files adapter and was involved in the prototyping work for the EMD 1.1 compliant adapters. Sunil is a Sun™ Certified Java™ 1.4 Programmer with special interest in the field of Business Integration and Service Component Architecture.

Rosaline Makar is a software engineer in IBM Egypt, Cairo Technology Development Center (C-TDC). She earned a B.Sc. in Computer Engineering and an M.Sc. in Computer Science. Rosaline’s areas of expertise include Web services, WebSphere Integration Developer, WebSphere Process Server, WebSphere Enterprise Service Bus, WebSphere Message Broker, and WebSphere Service Registry and Repository.

Sambasivarao (Rao) Nanduri has been working as an IBM staff software Engineer in the L2 Support Team for WebSphere Message Broker since 2006 September. He received his Ph. D in Physical Sciences in 1994. He has several years of experience within and outside of IBM in UNIX® (AIX® and SOLARIS) Systems, IBM middleware products (WebSphere and Portal) and database (DB2®) administration. He has co-authored several research articles and has a number of IT certifications.

Lara Payne is an IT Specialist who works with IBM Business Partners in Channel Technical Sales, United Kingdom and Ireland. She earned a Bachelor degree in Biological Sciences and also went on to study for a Masters Degree in Computer Science at Birkbeck College, University of London. Lara works with Business Partners who specialize in WebSphere Business Process Management products as well as WebSphere MQ and WebSphere Message Broker.

© Copyright IBM Corp. 2009. All rights reserved. ix

Wolfgang Reismann is an IT Architect for WebSphere in IBM Software Group Vienna, Austria. As part of the technical presales team, he provides guidance to IBM clients and project teams on Application and Integration Middleware product capabilities and the business value of AIM. Wolfgang has worked with IBM for 19 years in numerous technical areas and in national and international customer middleware projects. He is a certified IT Architect and holds a Master degree in Computer Science from the University of Applied Sciences Vienna. His areas of expertise include project management, high availability and performance tuning, and middleware products such as WebSphere Application Server, WebSphere MQ, WebSphere Message Broker/ESB, and WebSphere Service Registry and Repository.

Carla Sadtler is a Consulting IT Specialist at the ITSO, Raleigh Center. She writes extensively about WebSphere and Patterns for e-business areas. Before joining the ITSO in 1985, Carla worked in the Raleigh branch office as a Program Support Representative, supporting MVS customers. She holds a degree in Mathematics from the University of North Carolina at Greensboro.

Thanks to the following people for their contributions to this project:

Penny HillIBM US

Matt LucasIBM UK

Anthony O’DowdIBM UK

Become a published author

Join us for a two- to six-week residency program! Help write a book dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You have the opportunity to team with IBM technical professionals, Business Partners, and Clients.

Your efforts can help increase product acceptance and customer satisfaction. As a bonus, you can develop a network of contacts in IBM development labs, and increase your productivity and marketability.

Find out more about the residency program, browse the residency index, and apply online at:

ibm.com/redbooks/residencies.html

x Using the New Features in WebSphere Message Broker V6.1

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html

Comments welcome

Your comments are important to us!

We want our papers to be as helpful as possible. Send us your comments about this paper or other IBM Redbooks® publications in one of the following ways:

� Use the online Contact us review Redbooks form found at:

ibm.com/redbooks

� Send your comments in an e-mail to:

[email protected]

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. HYTD Mail Station P0992455 South RoadPoughkeepsie, NY 12601-5400

Preface xi



http://www.redbooks.ibm.com/contacts.html

xii Using the New Features in WebSphere Message Broker V6.1

Chapter 1. Introduction to WebSphere Message Broker V6.1

WebSphere Message Broker is a powerful enterprise service bus (ESB) with extensive connectivity and message handling capabilities. It offers significant value by extending existing applications through new connectivity. This connectivity extends to packaged applications and file-based processing. Everything can be connected, so that batch-oriented and online processing can operate in a secure infrastructure that is fully integrated with the application life cycle.

1

© Copyright IBM Corp. 2009. All rights reserved. 1

1.1 WebSphere Message Broker V6.1 feature overview

WebSphere Message Broker is a powerful information broker that allows both business data and information, in the form of messages, to flow between disparate applications and across multiple hardware and software platforms. Rules can be applied to the data that is flowing through the message broker in order to route, store, retrieve, and transform the information.

1.1.1 Universal connectivity

WebSphere Message Broker is known for its any-to-any connection capabilities that provide simplified application integration in a flexible and dynamic infrastructure. Support for a variety of transport protocols is provided through built-in nodes. Connectivity options span a wide range of protocols, including JMS, MQ, CICS®, TCP/IP, MQe, and MQ telemetry, user-defined transports, and more. Message Broker includes native support for SAP, Siebel®, and PeopleSoft® adapters.

Support for file processing, including FTP, is delivered in V6.1 through built-in nodes. This support allows large files to be handled without using excessive storage. It provides comprehensive support for record detection and sophisticated record identification that allows specific records to be identified in a larger flow.

Support for Web services includes SOAP nodes to support both provider and consumer scenarios, WS-Security and WS-Addressing support, and integration with DataPower® appliances for Web service security.

1.1.2 Routing and transformation capabilities

WebSphere Message Broker provides routing and transformation capabilities that can move messages from anywhere, to anywhere.

Message Broker a variety of nodes that allow you to manage the flow of messages. These nodes provide routing capabilities that allow you to manage the processing that occurs within the message flow or to select a destination for the output of the message flow. Routing can be based on the content of the message or content retrieved from a database. WebSphere Message Broker also provides integrated support for WebSphere Service Registry and Repository, which provides a central repository of documents describing services, service interfaces, and associated policies that control access mechanisms (for example, WS-Policy documents. Message flows can perform lookup on the registry to determine the location of a service.

Messages that enter a message flow in one format might need to exit the message flow in a different format. WebSphere Message Broker provides support for a broad range of data formats, for example, binary (C/COBOL), XML, industry (SWIFT, EDI, HIPAA, and so on), and user-defined formats. Transformation options include graphical mapping, Java, extended SQL (ESQL), Extensible Stylesheet Language (XSL), and WebSphere Transformation Extender.

1.1.3 Simple programming

Message flows process and route messages in WebSphere Message Broker. A message flow contains a series of connected nodes that have the required integration logic that is used to operate on messages as they flow through the broker. Each node is configured with properties that define how data is interpreted and processed. These nodes provide support for interactions and operations that allow you to route, filter, transform, enrich, monitor, distribute, decompose, correlate, and more.

2 Using the New Features in WebSphere Message Broker V6.1

As messages enter a message flow, parsers create a message tree structure that carries the data through the message flow. Message trees describe the data in a format independent manner, making it easy to manipulate within the message flow. The message flow nodes provide an interface to query, update, or create the content of the tree.

Development is done with the Message Brokers Toolkit, an Eclipse-based development environment. Creating a message flow can be as simple as dropping nodes from a palette to a canvas and configuring the node properties.

1.1.4 Operational management and performance

WebSphere Message Broker contains extensive administration and systems management facilities for developed solutions.

From an operational perspective, WebSphere Message Broker artifacts can be deployed to various systems from Microsoft® Windows® to z/OS®, and includes UNIX and Linux® on different hardware and software platforms. The run time is always integrated with the operating system platform to provide an operational experience consistent with the users of the platform. However, the run time also provides consistent behavior, enabling users to make a true platform choice between and within deployments. The WebSphere Message Broker run time provides a highly scalable environment and extensive administration and systems management facilities for developed solutions, giving operational staff far-reaching control over deployed resources.

1.2 Available editions of WebSphere Message Broker

WebSphere Message Broker V6.1 offers four new modes of operation that allow users to progressively adopt Message Broker in intuitive functional (and price) increments:

� WebSphere Message Broker Trial Version� WebSphere Message Broker Starter Edition� WebSphere Message Broker for Remote Adapter Deployment� WebSphere Message Broker Enterprise

A single package is delivered for all modes. The same toolkit is used for all modes of operation and the same service package is used for all modes to simplify maintenance. The mode you can operate in is determined by your license and is set when you create a broker. Administration tooling icons and start-up messages are provided for operational clarity.

Upgrades from one edition to another are made simple. You can start at one level and grow the capacity of your Message Broker as your integration needs grow, without reinstalling the product.

You can change your operation mode by purchasing or upgrading to the proper license and then using the mqsimode command. A separate IBM Tivoli® License Manager (ITLM) file for each mode enables a compliance check. A change to an unlicensed mode fails gracefully, reporting the reason.

1.2.1 WebSphere Message Broker Trial Version V6.1

The Trial Version allows you to become familiar with WebSphere Message Broker on your own time at your own pace. The Trial Version contains the full functionality of WebSphere Message Broker and is ideal for educational or proof of concept purposes.

Chapter 1. Introduction to WebSphere Message Broker V6.1 3

The trial is free, though registration is required. The product is valid for 90 days.

You can download the trial version from IBM DeveloperWorks:

http://www.ibm.com/developerworks/downloads/ws/wmb/learn.html

The WebSphere Trial Program provides limited free online support designed to help you with problems or questions. For more information, see:

http://www.ibm.com/developerworks/downloads/ws/wmb/trialsupport.html

Platform supportThe Trial Version is available for all distributed platforms.

Upgrade optionsYou can upgrade the Trial Version to any other version of WebSphere Message Broker. No re-install is necessary and your work is preserved.

1.2.2 WebSphere Message Broker Starter Edition V6.1

WebSphere Message Broker V6.1 Starter Edition enables you to adopt WebSphere Message Broker with limited capacity at a lower entry price.

The Starter Edition is ideal for:

� Small and medium businesses that want to implement an ESB at a reasonable cost for just a few applications.

� Departments of large enterprises that need multiple ESBs. The Starter Edition would allow an ESB for local autonomy.

� Entry level projects.

Like the Trial Version, the Starter Edition contains the full range of WebSphere Message Broker functionality. However, it has the following restrictions (Figure 1-1):

� The broker is limited to ten message flows and one execution group. An execution group is a grouping of message flows in the broker runtime environment.

Figure 1-1 WebSphere Message Broker Starter Edition

TenBroker

MessageFlows

OneBroker Execution Group

WebSphereMessage BrokerStarter Edition 6.1

TenBroker

MessageFlows

OneBroker Execution Group

WebSphereMessage BrokerStarter Edition 6.1




Platform supportThe Starter Edition is available for all distributed platforms.

Upgrade optionsThe Starter Edition can be upgraded to a full WebSphere Message Broker license. Any configuration that was done in the Starter Edition is preserved with the upgrade.

1.2.3 WebSphere Message Broker for Remote Adapter Deployment V6.1

WebSphere Message Broker V6.1 for Remote Adapter Deployment is ideal for customers or business partners that have packaged applications that need to be integrated with other applications but do not need the full functionality of an ESB. This mode of operation is also idea for use as a migration path from the MQSeries® for R/3 link products.

The functionality of the Remote Adapter Deployment is a subset of the full functionality provided by WebSphere Message Broker (Figure 1-2).

The focus of this edition is the connectivity between applications. With Remote Adapter Deployment, you have the following connectivity options:

� Input/output transports provided with Message Broker, including SOAP, HTTP, WebSphere MQ, Generic JMS providers, File.

� WebSphere JCA adapters for SAP, Siebel, PeopleSoft (requires a license for the adapters). You have the ability to run multiple JCA adapters.

� Adapters built using the WebSphere Adapter Toolkit.

� WBI adapters (not provided with Message Broker). Existing WBI Adapter customers are required to purchase this in order to continue to deploy remote adapters.

� Industry data format packs with WebSphere Transformation Extender (not provided with Message Broker).


Figure 1-2 WebSphere Message Broker for Remote Adapter Deployment

The message flow capabilities are limited in this edition to the following subset:

� Protocol-specific input and output nodes (for example, MQInput), to allow on/off ramp to the EIS.

� Timeout Control and Timeout Notification nodes

� Java Compute transformation node for customization of messages

The broker is limited to two execution groups.

PlatformsThe Remote Adapter Deployment Edition is available for all distributed platforms.

Upgrade opportunitiesIt is possible to upgrade to the Enterprise mode without re-installing the WebSphere Message Broker software.

Why adapters are usedThe focus for adapters in SOA is the reuse of existing and new investments in business applications, enabling a services approach for new, more flexible composite applications. Adapters augment your standard and advanced ESB to connect to certain non-standard environments (such as packaged applications like SAP and PeopleSoft). WebSphere Adapters link business applications to the ESB to participate in a service-oriented architecture, without coding, and without expert skills in the underlying application.

Expanding Packaged Applications WebSphere Message Broker for Remote Adapter Deployment

IBM WebSphereAdapterforSAP

IBM WebSphereAdapterforSiebel

IBM WebSphereAdapterforPeopleSoft

Partner Adaptersbuilt usingthe WebSphereAdapter Toolkit

IBMWebSphere

Adapters

File

Generic JMSProviders

WebSphere MQ

HTTP

SOAP

WebSphere MQ Queue Manager

Abilityto run

WebSphereAdapters

WebSphere Message Brokerfor Remote Adapter Deployment V6.1

JavaCompute

Input/output transports

PartnerAdapters for IBM

WebSphere


WebSphere Adapters provide:

� Service oriented approach to integrating business applications, enabling coarse grained encapsulation of business logic, and embodying key principles of loose coupling.

� Provide a consistent framework for access to back-end systems and technologies

� An abstraction from wire protocols, application APIs, or data transformation between domains

� Consistent configuration, deployment, and administration

1.2.4 WebSphere Message Broker V6.1 Enterprise Mode

The Enterprise Mode (or full license) has the full range of WebSphere Message Broker function. You get everything that you get in the other versions, plus the broker is unlimited in the number of execution groups and message flows

Enterprise Mode should be used for all major ESB implementations and larger integration projects.

Platform supportFull license support includes all distributed platforms, as well as z/OS.

1.3 Technical overview

This section expands on the concepts discussed earlier. It provides an insight into how rich the features of WebSphere Message Broker are in supporting a wide range of application integration scenarios.

1.3.1 Message flows

Processing logic in WebSphere Message Broker is implemented via message flows. Through message flows, messages from business applications can be transformed and routed to other business applications. Message flows are created by connecting nodes together. A wide selection of built-in nodes are provided with WebSphere Message Broker. These nodes are used to perform tasks that are associated with message routing, transformation, and enrichment. The base capabilities of WebSphere Message Broker are enhanced by SupportPacs that provide a wide range of additional enhancements.


Message flows are developed as simple wiring diagrams (Figure 1-3) that depict how applications are connected. A message flow is composed of the processing nodes, each of which performs a specific function in the flow, such as accepting an input request, transforming a message, or accessing a database.

Figure 1-3 Message flow diagram

A message tree data structure describes the request data in a format-independent manner using built-in parsers. With data format-independence, designers do not have to be concerned with the details of a particular request when they connect applications together. Data format-independence also enables a broad range of processing nodes, including specific nodes that allow custom skill sets, such Java, extended SQL (ESQL), Extensible Stylesheet Language Transformation (XSLT), and WebSphere Transformation Extender, to act upon a request as the request passes through a message flow. There are also graphical mapping capabilities for non-programmers.

1.3.2 Message flow processing

The message flows are executed in a broker. Message flows are grouped into execution groups for a specific broker. The broker enforces a degree of isolation between message flows in distinct execution groups by ensuring that they run in separate address spaces, or as unique processes (Figure 1-4).


Figure 1-4 Message flow processing

1.3.3 Connectivity

WebSphere Message Broker supports various transport protocols as shown in the following list. If your protocol is missing from this list, WebSphere Message Broker provides the ability to write user-defined nodes in C or Java.

� WebSphere MQ

The WebSphere MQ Enterprise Transport supports WebSphere MQ applications that connect to WebSphere Message Broker to benefit from message routing and transformation options.

� Java Message Service (JMS) 1.1

WebSphere Broker JMS Transport is used to send and receive JMS messages using destinations accessible through a JMS provider. The built-in JMS nodes act as JMS clients. Support includes the ability to transform JMS messages to MQ and vice versa.

The JMS nodes work with the WebSphere MQ JMS provider, WebSphere Application Server Version, and any other JMS provider that conforms to the Java Message Service Specification, version 1.1.

� SOAP-based Web services

Web services support includes SOAP nodes to support both provider and consumer scenarios, WS-Security and WS-Addressing support, and integration with DataPower appliances for Web service security. Standards supported include SOAP 1.1/1.2, WSDL 1.1, MTOM/XOP, SOAP with Attachments, Basic Profile 1.1 compliant.

� HTTP and HTTPS

The WebSphere Broker HTTP Transport connects applications using the HTTP protocol. Message flows can use the HTTP transport to work with SOAP-based Web services, other Web services standards, such as REST or XML-RPC, and general HTTP messaging, where the payload might, or might not, be XML.

In the case of SOAP-based Web services, several advantages exist if you use the SOAP domain instead of the HTTP transport nodes. Using the SOAP domain and nodes gives you the following advantages:

– Support for WS-Addressing, WS-Security and SOAP headers – A common SOAP logical tree format, independent of the actual bitstream format – Runtime checking against WSDL

Broker

Exec

utio

nG

roup

Mes

sage

Sets

Application

Application

Application

Application

Message Flow


� File

File processing support, including FTP, is delivered in V6.1 through built-in nodes. This support allows large files to be handled without using excessive storage. It provides comprehensive support for record detection and sophisticated record identification that allows specific records to be identified in a larger flow.

� JCA adapters for SAP, Siebel, and PeopleSoft

You can connect to Enterprise Information Systems using the integrated WebSphere Adapter nodes. Enterprise Metadata Discovery (EMD) is used for key data structure discovery and accelerated message set generation. A license for these adapters is required.

TwineBall nodes are provided as sample nodes with their own EIS for learning about how the WebSphere Adapter nodes work.

� TCP/IP sockets

Nodes for TCP/IP support allow you to connect existing applications that use raw TCP/IP sockets for transferring data.

� WebSphere MQ Mobile Transport

This service connects mobile and wireless applications that use WebSphere MQ Everyplace®

� WebSphere MQ Multicast Transport

This transport connects dedicated JMS application clients and is optimized for high volume, one-to-many publish/subscribe topologies.

� WebSphere MQ Real-time Transport

This lightweight protocol is optimized for use with nonpersistent messaging. It is used exclusively by JMS clients that participate in publish/subscribe scenarios, sending messages over IP connections to other internet and intranet applications.

� WebSphere MQ Telemetry Transport

This is a lightweight publish/subscribe protocol flowing over TCP/IP for remote sensors and control devices through low bandwidth communications.

1.3.4 Data formats

Transports and protocols used in message flows require support for multiple data formats including binary data formats, such as those found in C and COBOL applications, text-based industry formats (such as SWIFT, EDI, HIPAA, HL7) and support for XML.

As messages enter the message flow, the format of the message must be known so it can be parsed and converted into a message tree for manipulation by a message flow. After the message has been processed by the message flow, the broker converts the message tree back into a message bit stream.

You can model a wide variety of message formats so that they can be understood by WebSphere Message Broker message flows. Message format definitions are stored in message sets. Typically, application message formats described by XML DTD, XML Schema, WSDL Files, C structures, COBOL structures, or EIS systems are imported into message sets and edited to reflect the format of your message bit stream during transmission. Alternatively, you can create an empty message definition file and create your messages using just the editor. These message definitions can then be generated in a form that can be used by a broker, parser, or application.


This might be in one of the following forms:

� A message dictionary for deployment to a broker � An XML Schema for use by an application to validate XML messages, or for deployment

to a broker � Web Services Description Language (WSDL) for a web services client, or for deployment

to a broker � Documentation to give to programmers or business analysts

The message set specifies which message domains the message set supports. This determines which parsers are used when you parse and write messages that are defined within that message set. Each parser is suited to a particular class of messages (for example, fixed-length binary, delimited text, or XML) known as a message domain.

WebSphere Message Broker provides built-in support for messages in the following message domains by providing the message body parsers that are listed below. You can also define your own parsers.

� MRM (MRM parser and domain) � XMLNSC, XMLNS, and XML (XML parsers and domains) � SOAP (SOAP parser and domain) � DataObject (DataObject parser and domain) � JMSMap and JMSStream (JMS parsers and domains) � MIME (MIME parser and domain) � BLOB (BLOB parser and domain) � IDOC (IDOC parser and domain) � WebSphere Message Broker also provides parsers for the following message headers,

which your applications can include in input or output messages:

WebSphere Message Broker also provides parsers for the following message headers, which your applications can include in input or output messages:

� WMQ MQMD (the MQMD parser) � WMQ MQMDE (the MQMDE parser) � WMQ MQCFH (the MQCFH parser) � WMQ MQCIH (the MQCIH parser) � WMQ MQDLH (the MQDLH parser) � WMQ MQIIH (the MQIIH parser) � WMQ MQRFH (the MQRFH parser) � WMQ MQRFH2 and MQRFH2C (the MQRFH2 and MQRFH2C parsers) � WMQ MQRMH (the MQRMH parser) � WMQ MQSAPH (the MQSAPH parser) � WMQ MQWIH (the MQWIH parser) � WMQ SMQ_BMH (the SMQ_BMH parser) � JMS header (representation of messages across the JMS Transport) � HTTP headers (HTTP headers)

1.3.5 Messaging mediation

In the following sections, we summarize the mediation patterns that WebSphere Message Broker supports.

Message routing and filteringPackaged with WebSphere Message Broker are a variety of nodes through which connectivity is provided for both standards and non-standards-based applications and services. Routing can be point-to-point, based on matching the content of the message with a pattern, or based on the contents of a database.


Aggregation is an advanced form of message routing. With aggregation, a request message is received, and multiple new different request messages are generated. Each new message is routed to its destination using a request-reply interaction. WebSphere Message Broker tracks the process, collecting each response and recomposing them into a single output message.

Transport protocol conversionWebSphere Message Broker provides universal connectivity between applications that use disparate transport protocols. WebSphere Message Broker enables connectivity between applications or business processes that use transport protocols such as SOAP, HTTP(S), Java Message Service (JMS), MQ, CICS, TCP/IP, and FTP, MQe, MQ telemetry, and user-defined transports.

WebSphere Message Broker supports WebSphere Business Integration Adapters. For more information about available adapters, see the WebSphere Adapters page at:

http://www-306.ibm.com/software/integration/wbiadapters/

Message transformation and enrichmentOne of the key capabilities of WebSphere Message Broker is the transformation and enrichment of in-flight messages. This capability enables business integration without the need for any additional logic in the applications. For example, an application that generates messages in a custom format can be integrated with an application that only recognizes XML. This capability provides a powerful mechanism to unify organizations, because business information can now be distributed to applications that handle completely different message formats.

In WebSphere Message Broker, message transformation and enrichment are dependent upon a broker understanding the structure and content of the incoming message. Self-defining messages, such as XML messages, contain information about their own structure and format. However, before other messages, such as custom format messages, can be transformed or enhanced, a message definition of their structure must exist. The Message Brokers Toolkit contains facilities for defining messages to the message broker.

Using parsers and message sets, WebSphere Message Broker can validate and check that incoming messages comply with the format that is defined in the message set. A flow can be constructed to reject and handle non-compliant messages. Additionally, complex manipulation of message data can be performed using extended SQL (ESQL) or Java facilities that are provided in the Message Brokers Toolkit.

WebSphere Transformation Extender can be integrated into the WebSphere Message Broker ESB solution to extend the existing capabilities and simplify transformation development.

Also, XSL Transformation and graphical mapping (and WTX, via WTX Extender) are other transformation options.

1.4 Usage patterns for WebSphere Message Broker

WebSphere Message Broker has a wide range of functionality and connectivity features. It is to be expected that you would also see a variety of patterns for use that take advantage of these features. This section discusses common usage patterns.



1.4.1 Service enablement

The service enablement pattern (Figure 1-5) exposes function from a variety of applications through an SOA interface. It provides clients (service requesters) with a standard service interface to applications, masking the details of the connection requirements and message structure. This pattern takes advantage of the ability of Message Broker to connect to a wide range of applications and platforms.

Service requesters access the services through Message Broker using Web services protocols (SOAP/HTTP or SOAP/JMS). Message Broker invokes the requested services from the back-end applications using WebSphere MQ or adapters.

Message flows in the broker can provide extra value through routing and endpoint selection capabilities.

Figure 1-5 Service enablement

This pattern can be used to provide:

� A service façade for messaging systems� A messaging system interface to service providers� A service based invocation of application function� Application function request mapping to a service invocation

Service enablement usage scenario:

An enterprise that has existing applications and data on a mainframe wants to make these available to a new business process running in WebSphere Process Server using a Web services interface. Access to these applications has traditionally been through native interfaces and to messaging applications through WebSphere MQ.

While WebSphere Process Server can access these applications using a messaging interface, making these applications available through a Web services interface would allow wider access to these services from non-messaging based applications. WebSphere Message Broker is used to provide a Web services interface to these applications.

Application

Broker

Application

ApplicationCompose


1.4.2 Service virtualization

The service virtualization pattern (Figure 1-6) provides true loose coupling between service requesters and service providers by providing additional levels of indirection through an ESB. This addresses the requirements of mediation between services in a service-oriented model.

Service requesters and providers connect to Message Broker using Web services protocols (SOAP/HTTP or SOAP/JMS).

In addition to the routing and endpoint selection capabilities seen in the service enablement pattern, message flows can be used to provide sophisticated mapping capabilities between input and output messages.

Figure 1-6 Service virtualization

This pattern can be used to provide the following functionality:

� Service proxy� Service selector� Service translator� Service normalizer� Service retry

1.4.3 Message enablement

The message enablement pattern (Figure 1-7) allows messaging applications to access a variety of applications and services through the broker.

The client application sends the request using WebSphere MQ, while the broker accesses the requested function or application using any connectivity supported. Message flows are used to provide limited routing.

Service virtualization usage scenario:

An enterprise that has existing Web services would like to compose business processes by assembling these services into a larger application. These services reside on a variety of platforms and application types. Allowing one service to interact with another requires transformation of data to ensure compatibility among services. WebSphere Message Broker provides the ESB transformation and routing capabilities required to allow these Web services to interact seamlessly.

Service

Broker ServiceRoute

Service

OR

OR

OR


Figure 1-7 Message enablement

This pattern can be used to provide the following functionality:

� Message-based invocation of application function� Application function request mapping to message-based request

1.4.4 Message brokering

The message brokering pattern (Figure 1-8) extends an existing messaging infrastructure by providing routing, logging and transformation services in the ESB. Any messaging protocol can be used to connect the applications. Sophisticated mapping is used to transform messages to the appropriate format.

Figure 1-8 Message brokering

Message enablement usage scenario:

An enterprise with a significant investment in messaging based applications would like to extend these applications to take advantage of additional services that are only available through non-messaging technologies.

WebSphere Message Broker provides a messaging interface to these applications, reducing the investment needed to incorporate these new services into the existing application. The messaging application continues to request services using the messaging interface, while WebSphere Message Broker provides the access and transformation services required to satisfy the requests.

Database

File

Queue

Web Service

MessagingApplication

GETPUT

Broker

PUT

GET



GET

PUT

Broker

RouteTransform


This pattern can be used to provide:

� Content based routing

� Aggregation (advanced routing that splits requests to multiple applications and collects the responses to return to the requester)

� Protocol converter (bridge between different products/ technologies)

� Transformation hub

� Messaging cache

1.4.5 File processing

The file processing pattern (Figure 1-9) facilitates the integration of file based applications and providing a managed execution environment for the processing of files. It also provides a bridge between batch-orientated applications and transactional models of execution.

File processing can be used to move or copy files between messages and file storage. Message flows can be used to perform mapping between data formats, and to aggregate information from multiple messages or files.

Figure 1-9 File processing

Message brokering usage scenario:

An enterprise with a significant investment in messaging based applications would like to extend these applications to build a higher level of service. Currently each messaging application acts as its own entity and is accessed by consumers separately. As these applications are connected in ways intended to streamline business processes, WebSphere Message Broker is used to provide the additional logic to make the connection complete.

For example, a single request from an application can be parsed and routed using advanced logic to multiple applications for a response. The responses can be combined or modified for return to the requester.

A travel reservation request can have the hotel request sent to one application, car rental to another application, and flight reservation to a third. The resulting reservation information can be returned as one package to the requester.

UOW 1

MessageBroker

File

UOW n

File

UOW 1 UOW n File


This pattern can be used to:

� Dump a file to a message� Create a file from message input� Assemble a file from multiple messages� Move or copy a file� Convert a file –translate format of individual file records from binary to XML for example

1.4.6 Event processing

The event processing patterns (Figure 1-10) provides a managed execution environment for the processing of events, including distribution of events in real time, processing of events from physical devices, simple information distribution and detection of temporally orientated event patterns.

Message flows can be used for mapping and aggregation of events.

Figure 1-10 Event processing pattern

This pattern can be used for:

� Event distribution (such as telemetry feeds to EIS and monitoring systems)� Detection of fraudulent transaction patterns� SLA monitoring

File processing usage scenario:

An enterprise with a significant amount of business information stored in file format would like to access that information from business applications. WebSphere Message Broker is used to integrate those business files into business processes for client access.

Event processing usage scenario:

A financial services enterprise needs to minimize credit card fraud. To do this, it must be able to monitor card transactions as they occur in near real-time; batch processing is simply not adequate. It must be possible to recognize when multiple transactions for the same card occur within 10 minutes of each other and are incurred at a distance of greater than 100 miles.

Using the complex event processing capability in WebSphere Message Broker, it is possible to establish a set of business rules that define the circumstances under which two or more transactions are deemed to be fraudulent. By continually testing the rules against the incoming stream of events or messages that represent card transactions, fraudulent activity can be detected as it occurs. This can lead to the generation of another event that is used to notify an operator or block the card for example.

(Route, Trigger) (Analyze, Detect)

Capture


Chapter 2. New features in WebSphere Message Broker V6.1

Message Broker version 6.1 builds on the success of Version 6. It introduces significant new opportunities for high performance integration. Version 6.1 is able to co-exist with version 5 and version 6 and enables incremental migration.

In this chapter we take a look at some of the highlights in WebSphere Message Broker V6.1. We cover some of these new features briefly in this chapter and expand on others in more detail in the later chapters.

In addition to the specific features discussed in this chapter, multiple areas have been enhanced. These enhancements include:

� Reduced time to get started

� Simplified development tasks

� Manageability improvements

� Platform support for 64bit linux

� JDBC™ XA support

� Java5

� High performance XML parser

� Real-time graphical performance analysis

� Performance improvements on all platforms

� Migration support from V5 and V6, including compatibility, event broker migration, and rollback support)

� CVP/IVP on all platforms to check the broker and configuration manager configuration on startup

2


2.1 Web services

Web services play an important role in Service Oriented Architecture (SOA). A Web service is a set of related application functions that can be programmatically invoked over the Internet. Businesses can dynamically mix and match Web services to perform complex transactions with minimal programming. Web services allow buyers and sellers all over the world to discover each other, connect dynamically, and execute transactions in real time with minimal human interaction.

As an ESB, it is to be expected that message flows in WebSphere Message Broker can act as a provide of services, a requester of services, or as a intermediary between requester and provider. While WebSphere Message Broker Toolkit V6.0 provided this support, it has been greatly enhanced in V6.1.

WebSphere Message Broker Toolkit V6.1 adds native support for SOAP messages with new nodes. As a Web service provider, a message flow now has the ability to receive SOAP messages as input and to reply with SOAP messages. As a Web service consumer, a message flow can send SOAP requests synchronously and asynchronously. New nodes have also been added to simplify the processing of SOAP payload and headers. Enhancements have been made to support the model-driven parsing of SOAP messages, including SOAP with Attachments (SwA) and Message Transmission Optimization Mechanism (MTOM). Support for WS-Addressing and WS-Security is now provided. Tools for working with WSDL files have been improved to simplify the development process. And finally, support for accessing service information from WebSphere Service Registry and Repository has been added. This allows for dynamic access to service information and location. Message flows that invoke a service can obtain the service information at runtime.

The new features for Web services support are discussed in more detail in Chapter 3, “Web services support in WebSphere Message Broker V6.1” on page 33.

2.2 File transfer

Files are one of the most common methods used to store data, and file transfers of this data form the backbone of many business IT systems. With the simplicity of FTP concepts aligned with intuition and lack of needed technical skills, FTP continues to be the “lowest common denominator” for integrating heterogeneous systems. With WebSphere Message Broker V6.1, it is now possible for the native Message Broker product to read and write files from file systems and FTP servers and to process those files (native function for processing files).

Two new nodes, the FileInput and FileOutput, provide the capability for file processing. These nodes are supported on all of the broker run-time platforms. The FileInput node processes messages which are read from files. It scans a specified directory for files that match a certain specification. When the broker finds a file which matches this specification, it reads the file and propagates a message, or messages, using the contents of the file. The FileOutput node writes messages to files in the broker's file system. When a message is received on the node's In terminal, it creates and writes a file as a series of one or more records. These two nodes can be combined with any of the other processing nodes supplied with WebSphere Message Broker V6.1, so it is easy to perform processing patterns such as:

� File to queue� Queue to file� File to file� File to database


Existing message parsers supplied with WebSphere Message Broker have been extended to add what is referred to as stream parsing. This is essentially a technique by which part of a record or file can be read into WebSphere Message Broker and processed. This means that the whole of the file does not have to be read into memory before processing of the file can commence. The appropriate broker parsers have been enhanced to request data on demand.

The processing of large, complex files is simplified with comprehensive support for record detection. This allows very large files, gigabytes in size, to be easily processed with WebSphere Message Broker without using excessive storage. It is possible to use simple delimiting strategies such as separation by line feed (LF), end of line (EOL), carriage return line feed (CRLF), fixed length, whole-file or user-defined boundaries. Alternatively you can use a more complex delimiting technique which is to use a message parser to determine the end of a record from an input file. The parser takes as its input an existing message definition and the sequence of data in the file.

File name patterns are supported for determining the files to process. You can specify a pattern of .TXT for example, in which case only files with a TXT suffix would be processed. Files with other suffixes would be left untouched.

Transactional processing of files is not supported in the same way as it is for persistent WebSphere MQ messages. File processing is not transactional but recovery processing is supported. There is a configurable retry mechanism which allows different levels of retry and recovery processing to be selected. This includes moving processed files to an archive directory and moving partially processed files to a back-out directory.

The new features for file processing support are discussed in more detail in Chapter 4, “File processing support in WebSphere Message Broker V6.1” on page 69.

2.3 Security

WebSphere Message Broker V6.1 adds powerful features to enhance the runtime security of messages.

In V6.0, the authorization of a client to send a message to a broker is handled by the transport that the message travels on, for example WebSphere MQ, or by an external security manager such as DataPower. SSL is available to ensure that messages entering and leaving Message Broker are encrypted. The stream of data passed between point-to-point is protected in its totality and is not differentiated for individual messages.

Message Broker V6.1 adds the following features to enhance the security of messages that enter and exit message flows. Theses new features are discussed in more detail in Chapter 6, “Security support in WebSphere Message Broker V6.1” on page 109.

2.3.1 Message-based authentication and authorization

WebSphere Message Broker V6.1 adds a new security manager that enables the broker to manage runtime authentication, authorization, and identity mapping security tasks. Individual messages entering the message flow over HTTPInput, SOAPInput, or MQInput nodes can be examined for an identity field. The identity is used as is, or can be mapped to an alternate identity. This identity used to ensure that the client is authorized to access the message flow. Authentication and authorization are performed using an LDAP V3 compatible security provider or Tivoli Federated Identity Manager V6.1. The Tivoli provider can also be used for identity mapping. The type of security actions to be taken (authentication, authorization, and mapping) and the external provider to use are controlled by security profiles defined for the broker.

Chapter 2. New features in WebSphere Message Broker V6.1 21

The SOAP nodes behave in two different ways depending on whether the WS-Security protocol is being used by the message. If WS-Security is not being used, then security behavior is exactly the same as in the HTTP nodes

2.3.2 WS-Security support

WS-Security is a communications protocol that specifies how integrity and confidentiality can be applied to individual Web service messages. WS-Security consists of multiple interrelated specifications. Message Broker version 6.1 focuses on the part of the WS-Security specification known as WS-Security Policy.

The WS-Security support provided in V6.1 deals with authentication and message protection. Authentication is performed based on a username and password combination, or with a certificate. Message protection can be achieved using either a digital signature, or using encryption. You can encrypt only a part of the message, or encrypt parts of the message with different keys. WS-Security within Message Broker is configured through policy sets, which build on top of WS-Security Policy providing enhanced usability. WS-Security requires a key store and / or trust store to be present before message flows can be deployed that require policy sets.

WS-Security is supported by the SOAP nodes in Message Broker V6.1. If you are using HTTP nodes, you need to use DataPower as an intermediary for WS-Security.

2.3.3 DataPower integration

Two DataPower appliance models, the XS40 and the XI50, can be used as an intermediary between a client that supports WS-Security and an HTTP node in WebSphere Message Broker.

In this scenario, the DataPower appliance is used as a front-end security gateway to decrypt the body of SOAP messages before they are sent to the message flow. The DataPower appliance is also used to encrypt the output message from the message flow before the reply is sent to the requesting application. A firewall within the DataPower appliance is required for this processing to occur.

While you can administer the configurations of both DataPower and Message Broker separately, the task can be made much easier through the use of the IS02 SupportPac. This SupportPac provides a plug-in to the WebSphere MQ Explorer that has access to your broker instances (like the Broker Administration view in the Message Broker Toolkit) and also has access to DataPower systems. The SupportPac can use information from the broker to create a configuration in DataPower that allows the two products to work together.

2.4 EIS connectivity with JCA adapters

Prior to WebSphere Message Broker V6.1, connectivity to EIS systems was accomplished using IBM WebSphere Business Integration adapters. These adapters were not integrated into the message flow, but operate as stand-alone adapters running outside the broker runtime. Message flows connected to these adapters using a JMS binding.


With WebSphere Message Broker V6.1, JCA-based WebSphere Adapters are delivered as built-in message flow nodes to provide connectivity to three major EIS systems, SAP, Siebel, and PeopleSoft systems. Providing this connectivity as nodes simplifies management and improves performance for key integration scenarios. Support is provided for inbound (EIS event to message flow) and outbound (message flow request to EIS) scenarios.

Using the adapter nodes allows you to integrate EIS systems into your business solutions through your ESB. The message flows provide the transitional capabilities to allow communication between the EIS systems and other components of the solution.

The new features for connecting to EIS systems are discussed in more detail in Chapter 5, “EIS adapter support in WebSphere Message Broker V6.1” on page 97.

2.5 Web 2.0 support

WebSphere Message Broker V6.1 adds full support for Representational State Transfer (REST), a Web 2.0 technology that has evolved to simplify XML data exchange between IT systems and end-user applications. With this enhancement, a message flow can now pass Web service request messages between lightweight clients and enterprise applications. The broker can now also act as a REST client itself, allowing you to hook REST services into your existing message flows.

With the new REST capabilities, the following verbs: POST, PUT, GET, and DELETE HTTP and methods are fully understood (Figure 2-1).

Figure 2-1 Web 2.0 support

In inbound scenarios the inbound REST request is handled using the HTTP Input/HTTP Reply nodes. The REST verb is captured in the LocalEnvironment. Message flows are able to handle multiple request types, both static (design-time) and dynamic (run-time) REST invocations.

Flexible URL definitions are supported with URL list and wildcard support for diverse noun capabilities, allowing you to handle these in one flow. For example:

http://example.com/noun/object1,object2,object3


Outbound scenarios allow message flows to handle multiple request types. For static URLs specified at design-time, the URL and verbs are declared on the request node. With dynamic REST invocations, the URLs and verbs are set in the LocalEnvironment at runtime to override the node settings.

There is also additional HTTP request node enhancements which include increased LocalEnvironment overrides such as HTTP request timeout and SSL parameters.

2.6 TCP/IP nodes

With Message Broker V6.1, six new TCP/IP nodes are provided that can connect applications that transfer data through raw TCP/IP sockets. Existing applications that use raw TCP/IP sockets for transferring data can now use the TCP/IP nodes to connect directly to the applications. There is no longer a requirement to use WebSphere MQ to enable the applications.

The six new nodes support TCP sockets, and consist three client nodes and three server nodes. The nodes can be categorized into two sets. One set is made up of four input and output nodes, which because TCP/IP is bi-directional, corresponds to the end points you have in a bi-directional flow. The other set is made up of two receive nodes. The receive nodes are placed in the middle of a message flow to carry out a GET procedure equivalent to an MQGET.

These nodes can be used in the following ways:

� To connect existing TCP/IP client applications with MQ, use the TCPIPClientInput, TCPIPClientRequest, and TCPIPClientOutput nodes

� To connect existing applications to TCP/IP server programs, use the TCPIPServerInput, TCPIPServerRequest, and TCPIPServerOutput nodes

The TCP/IP nodes have been developed to provide full protocol support, including handshakes, request-reply and many more. These nodes are based on stream technology, exploiting stream based parsing to interpret stream data as messages, as TCP/IP is a stream based protocol. This is based on the IA98 SupportPac with some additional development.

In a simple interaction pattern, the input nodes read on the input stream and the output nodes send out to the output stream. Figure 2-2 shows simple request/reply interaction patterns.

Figure 2-2 Request/Reply pattern

Incoming request

Outgoing request


The routing of TCP/IP messages in a synchronous or asynchronous manner can be achieved using a combination of nodes. Figure 2-3 shows message flow patterns for routing synchronous and asynchronous TCP/IP requests.

Figure 2-3 Redirecting TCP/IP

More complex interactions using TCP/IP nodes in combination with additional nodes can occur, where a series of nodes are working on the same connection, such as a three-way handshake. Figure 2-4 shows a three-way handshake pattern.

Figure 2-4 Complex interactions

In Figure 2-4, data is received in the flow on a server connection. The flow sends an acknowledgement to the client and waits for the client to send back a reply to signal it can continue. The flow then does some processing (in this case it sends an MQ request/reply message). When the reply is received, the flow sends it data back to the client and then waits for an acknowledgement from the client. When the acknowledgement is received, the flow sends a reply to tell the client to continue processing.

Countless other complex patterns can be achieved that require arbitrary sending or receiving data on a connection.

Synchronous routing

Asynchronous routing

Three-way handshake


2.7 WebSphere MQ

WebSphere MQ is the IBM universal messaging backbone for Service Oriented Architecture (SOA). WebSphere MQ is supported as a transport for sending and receiving messages in a message flow, and provides the underlying messaging capability of Message Broker. In version 6.1, Message Broker provides new enhancements for interoperability with WebSphere MQ.

2.7.1 New features for existing nodes

Three new features provide additional support for existing nodes:

� The browsing of MQ messages with MQInput and MQGet nodes� The use of an MQOutput node without an MQMD message header� The provision of additional message instances on the MQInput node

Browsing MQ messages with the MQInput and MQGet nodesIn previous versions of Message Broker, when the MQInput or MQGet node accessed a message on a queue, the message was always removed from the queue by a destructive MQGET call.

In Message Broker V6.1, you have the ability to browse a queue. This means that you can access the contents of a message but the message itself remains on the queue allowing its reuse by the same or other applications. This ability to browse is useful when configuration data or constants are stored on a queue and used multiple times, or when applications need to examine the content of a message before deciding whether to remove it from the queue.

To specify that the MQGET operation should browse the queue, rather than issuing a destructive MQGET operation, you need to select the check Browse Only property box on the Advanced tab for each MQINPUT node. If using an MQGet node, the option is found on the Request tab. This option sets the OutputLocalEnvironment.MQ.GET.Browsed setting to “true”, indicating messages on the queue are to be browsed, rather than using a destructive GET (false) to take a messages off the queue.

The “Provide a value for Reset browse timeout (ms)” option on the MQInput node can be used to reset the Browse curser after a period of inactivity. This addresses message priority issues that might occur, where messages can come in before the browse curser and these messages might have been missed. This allows a re-browse of messages to see which ones have been missed.


Scenario: Using a single message to serve multiple message flowsFigure 2-5 illustrates how a single message can serve multiple MQInput or MQGet nodes when using this browse capability.

Figure 2-5 Browsing messages on a queue

Scenario: Browse, then get a messageA common usage is to examine the contents of a message before deciding whether to remove it from the queue or not. This can be achieved by an MQInput-MQGet or MQGet-MQGet node combination, with the first node in each case browsing the queue and the second removing it.

To achieve this result, the “Get by Message ID” option is set on the second node and the browsed message’s message ID must be present in the MQMD (or another message tree location as indicated by request options on the second MQGet node).

In addition, the “Include Message Contents in Output Message Assembly” option must be unset on the second node. This offers performance improvements because the message (already in the local tree from the browse operation) is only removed from the queue and not completely read and parsed for a second time.

To decide whether the or not to message should be removed. some logic would be required between the two nodes. Because context information cannot be saved if the message is only browsed, the Pass_All option on MQOutput nodes is not valid. The context information is still written to the message tree and so can be set using Set_All. This happens automatically if Pass_All is set.

Figure 2-6 illustrates this a scenario.

Figure 2-6 Browsing a queue and then removing the message

Browse

MQBROWSE_IN

MQBROWSE_IN

MQBROWSE_IN

Configure

Configure

Configure

MQBROWSE_IN

• Browse then Get• Ensure that the browsed

message ID is set in the tree’s configured MQMD location

• Uncheck ‘Include message ’ to avoid re

• Browse then Get• Ensure that the browsed

message ID is set in the tree’s configured MQMD location

• Uncheck ‘Include message…’to avoid re-obtaining same data

MQInput Compute MQGet

Browse Only Browse Only

Get by message ID

Include message contents in output message assembly


The use of the MQOutput node without an MQ message descriptorIn previous versions of Message Broker, the use of an MQOutput node required the presence of a valid MQ Message Descriptor (MQMD) message header in the message assembly. In Message Broker V6.1 the MQOutput node applies a default MQMD if one does not exist. Users are therefore not required to add a Compute node to create an MQMD manually.

For example, in the Timeout Processing sample shown in Figure 2-7, a Timeout Notification node operating in automatic mode generates messages without MQMD headers. Previously a Compute node (Add MQMD) was used to add a default MQMD. This step is no longer required as this processing is now done automatically by the MQOutput node. Messages generated by a Timeout Notification node in automatic mode no longer require an MQMD before they can be output by an MQOutput node:

Figure 2-7 Timeout processing sample

Additional instances on the MQInput nodeIn the case of message flows that contain more than one input node, the pool of additional message instances is normally shared between all the input nodes. There is therefore no guarantee which nodes get the additional instances, and in some cases, one node might get them all, resulting in what is termed thread starvation.

With Message Broker V6.1, additional instances can now be set at a node level rather than just at a message flow level, thus avoiding thread starvation. In situations when you are unable to avoid the use of multiple input nodes within a single flow, and you want to ensure that each input node has a minimum number of instances, additional instances can be set at a node level on the MQInput node's properties. If, however, a node is instructed to take additional instances from its own pool, then it is no longer entitled to additional instances from the message flow pool.

2.7.2 Compatibility with WebSphere MQ V7 publish and subscribe

Since the release of Message Broker V6.1, WebSphere MQ V7 has been released, and with it come new enhancements that include a major extension to the Publish and Subscribe (pub/sub) capability. Message Broker V6.1 is built on MQ V6, but interoperates with all previous versions of MQ and all new MQ releases, including MQ V7.

In versions of WebSphere MQ prior to V7, pub/sub messaging was controlled using a command message interface. This prior support is often referred to as queued pub/sub. In V7, pub/sub messaging is now controlled using new function in the WebSphere MQ API, integrating the pub/sub function into the queue manager. This new support is often referred to as MQ V7 pub/sub.

Automatic TIMEOUT_SAMPLE_OUT_1

LogError

AddMQMD

SET OutputRoot = InputRoot;CREATE NEXTSIBLING OF OutputRoot.Properties DOMAIN 'MQMD';SET OutputRoot.MQMD.Version = MQMD_CURRENT_VERSION;


The pub/sub engines in WebSphere MQ V7 and Message Broker V6.1 can work together without alteration. This is not an exploitation of the new WebSphere MQ pub/sub engine, but a toleration (Figure 2-8).

Figure 2-8 WebSphere MQ and WebSphere Message Broker pub/sub engine co-existence

The options for this environment are as follows:

� Allow WebSphere Message Broker v6.1 and MQ V7 to work together.

� Disable the WebSphere Message Broker pub/sub capability.

Disabling the Message Broker pub/sub capability allows message flows in a broker to exploit WebSphere MQ's queue-based pub/sub capabilities and to take advantage of other MQ features such as its consolidated security model.

Managing the pub/sub engine selection with PSMODE The PublishSubscribe configurable service properties include a psmode setting in the broker. This setting controls whether the pub/sub engine in Message Broker is enabled or disabled (the default is enabled). You can set the psmode setting with the mqsichangeproperties command. For example:

mqsichangeproperties WBRK61DEFAULTBROKER -c PublishSubscribe -o Interface -n psmode -v disabled

If you set psmode to disabled, you cannot use pub/sub within Message Broker (via the Publication node). However, you can use WebSphere MQ V7's queue based pub/sub engine for the specified queue manager.

There is also a psmode setting in the queue manager. When a broker has been associated with a queue manager, this setting should not (and cannot) be used. If a user directly enables MQ's queue based pub/sub engine through the queue manager settings (it is an invalid configuration to have both pub/sub engines enabled together), Message Broker disables it. The broker's configuration always takes precedence.

2.7.3 Improved administration with MQ via the Message Broker Explorer Eclipse Administration

The Message Broker Explorer Plug-in SupportPac (also referred to as IS02), enhances the MQ Explorer with the ability to administer a WebSphere Message Broker network. This allows you to manage WebSphere MQ and WebSphere Message Broker from one administration facility. This new management ability includes a multi Execution Group Deployment feature, which allows message flows to be separated for isolation, scalability and a more resilient implementation. However, it should be noted that in the case of the Message Broker V6.1 Starter Edition, you are limited to the deployment of one execution group and up to 10 message flows for that group and with the Message Broker V6.1 for Remote Adapter Deployment, you are limited to the deployment of message flows in two execution groups.

Message Broker

MQ V7 MQ V6

Choice


2.8 JMS transport

WebSphere Message Broker can bridge between JMS 1.1 compliant providers to achieve JMS interoperability. This allows you to unify processing across disparate JMS domains and share information ordinarily restricted to particular technology silos using a particular provider. With Message Broker, you can integrate your JMS application messaging with all of the other application types in an enterprise. For example, an enterprise can use the MQ and JMS nodes to bridge a JMS provider to the MQ network. Alternatively, it could use the SOAP and JMS nodes to expose those JMS applications as Web services.

To improve the JMS transport support in Message Broker, a new node, the JMSReply node was introduced. This JMSReply node is used to send a message to the recipient specified in the JMS header (JMSReplyTo field) of the message. Essentially this node provides similar functionality to the MQReply node, but for the JMS transport.

Also provided with Message Broker V6.1 is an enhancement to JMS's runtime security model which provides full security support for MQ, HTTP and SOAP nodes, extended connectivity with JMS XA, and support for BEA WebLogic applications to enable exploitation of BEA's specific transaction verbs.

2.9 WebSphere Transformation Extender

WebSphere Message Broker supports a wide range of transformation technologies including ESQL, Java, Graphical Mapping, XSLT and WebSphere Transformation Extender (WTX). WebSphere Transformation Extender complements and extends the Message Broker capability to transform messages. At its core is the Transformation Extender engine that executes maps built from an extensible library of ready-to-use functions. These functions can be combined using graphical tools to validate both structure and content logic of the most complex, XML and non XML data formats.

In the previous version of Message Broker, the Transformation Extender Maps were executed within the Message Broker using a plug-in. With the installation of WebSphere Transformation Extender V8.2 for Message Broker v6.1, comes with a new WTX Map node that allows new and existing adapters to be executed as part of the message flow. This new node identifies the maps to be used in a message flow and these maps run natively in Message broker. The WTX node updates both the runtime and toolkit to use the 8.2 libraries and updates the toolkit to use the 8.2 design studio.

Another new feature is the integration of the launcher, an event-driven software model for linking and executing maps. The development and deployment environment of the launcher has been integrated with the Message Broker Toolkit. The TX assets are deployed in the Message broker Archive.

When you have a message flow that contains a WTX Map node that is preceded by a Collector node, multiple events can trigger the WebSphere Transformation Extender map to run. The Collector node in a message flow groups together multiple messages that arrive at its input terminals, and runs the rest of the flow when triggering criteria that you have defined are met.


2.10 Common Event Infrastructure

The Common Event Infrastructure (CEI) provides the facilities for the generation, propagation, persistence, and consumption of events. It does not define the events themselves. Instead, application developers and administrators define event types, event groups, and correlation.

An event is a message published by a message flow when something interesting happens. The message contains information about the source of the event, the time of the event, and the reason for the event. The message can include the message bitstream, and can also include selected fields from the message body. These fields can be used to correlate messages that belong to the same transaction. Events are represented using the Common Base Event model, a standard, XML-based format defining the structure of an event, and are used to support transaction monitoring, transaction auditing and business process monitoring.

2.10.1 Enabling event emission

Message flows can emit CEI events. The event emission options can be set up during the message flow design, where the new CEI nodes are configured to specifically identify business relevant data. Or, event emission can be enabled as part of message flow administration. The types of nodes which can be used to emit events are:

� MQInput� JMSInput� SOAPInput� SOAPAsyncResponse� HTTPInput

The reporting of events can be based of the following: Simple conditional expression, Simple Specification of data elements captured, or a Reason qualifier (Success or Failure).

2.10.2 Integration with WebSphere Business Monitor and Modeler

The events published by a Message Broker can be monitored by WebSphere Business Monitor. Important fields in the message payload can be added to the events emitted by your message flows, allowing them to be monitored. The following items can be used with WebSphere Business monitor to monitor the message flows:

� Message Driven beans: Events must be submitted to the CEI repository in order for WebSphere Business Monitor to monitor them. A message driven bean is supplied for this purpose. The message driven bean subscribes to the event topic and writes events that match its subscription to the CEI repository.

� WebSphere Business Monitor Model: Message Broker includes an example Monitor Model for use with WebSphere Business Monitor. This model allows simple flow entry and flow exit events to be monitored. It can be extended to allow monitoring of events which include one or more fields from the message payload. This model is supplied as an IBM Supplied Message.


2.11 IBM Tivoli Composite Application Manager for SOA 7.1

WebSphere Message Broker V6.1 provides close integration with ITCAM for SOA, allowing ITCAM to monitor service interactions involving message flows. Information such as response times, message counts and size are measured. Support is provided for Web Services (SOAP), MQ, JMS, HTTP transports. With its dynamic views, ITCAM for SOA can reveal which applications call WebSphere Message Broker and which applications the broker calls. This provides information on how WebSphere Message Broker fits into your application connectivity infrastructure. For example, this information can help you determine which component spends the most time handling a Web service request when multiple components are involved in a complex business request.

Enhancements in the Service Management Automation area provide support for thresholds and automatic responses. There are built-in and extensible alerts, situations, and workflows.

The delivery of ITCAM integration features with Message Broker V6.1 has the following characteristics:

� It requires ITCAM for SOA 7.1.

� The support is provided as message tracking exits in Message Broker.

� No flow design changes are required; control is administrative.

� Control is on a per flow basis.


Chapter 3. Web services support in WebSphere Message Broker V6.1

Web services are self-contained, self-describing modular applications that can be published, located, and invoked across the Web. They are a key element in a SOA solution. Web services perform encapsulated business functions, ranging from simple request-reply to full business process interactions. These services can be new applications or just wrapped around existing legacy systems to make them network-enabled. A Web services can rely on other services to achieve their goals.

In this chapter we discuss the enhancements to Web services support in WebSphere Message Broker V6.1

3


3.1 Web services overview

In WebSphere Message Broker Toolkit V6.0, no nodes support Web services natively. HTTP nodes (HTTPInput, HTTPRequest, and HTTPReply) are used to transfer SOAP messages. Some additional support for Web services is provided through SupportPacs. The IA9O SupportPac provides the SOAPEnvelope and SOAPExtract nodes. Also, the IA9Q SupportPac provides WebSphere Message Broker V6.0 with nodes and related capabilities that interface with WebSphere Service Registry and Repository to access service metadata for use in mediation message flow (Figure 3-1).

WebSphere Message Broker Toolkit V6.1 has enhanced support for Web services to include:

� New SOAP nodes for native support of Web services. Message flows can act as a Web service consumer or provider

� New SOAP domain and parser for support of model-driven parsing of messages

� Web services extensions, including WS-Addressing and WS-Security

� Improved WSDL integration

� WebSphere Service Registry and Repository nodes that allow dynamic retrieval of service artifacts at runtime

Figure 3-1 Web services message flow

3.1.1 Web services core technologies

The following core technologies are used for Web services:

� XML (Extensible Markup Language): The markup language that underlies most of the specifications used for Web services. XML is a generic language that can be used to describe any kind of content in a structured way, separated from its presentation to a specific device.

Web Service Client

Message flows

Web Service Provider


� SOAP (Simple Object Access Protocol): A network, transport, and programming language and platform-neutral protocol that allows a client to call a remote service. The message format is XML.

� WSDL (Web Services Description Language): An XML-based interface and implementation description language. The service provider uses a WSDL document in order to specify the operations that a Web service provides and the parameters and data types of these operations. A WSDL document also contains the service access information.

3.1.2 SOAP messages

A SOAP message is an envelope containing zero or more headers and exactly one body as shown in Figure 3-2.

Figure 3-2 SOAP envelope

� SOAP Envelope: The top element of the XML document, providing a container for SOAP headers and body.

� SOAP Header: Contains control information, such as quality of service attributes.

� SOAP Body: Contains the message payload.

3.2 SOAP nodes

WebSphere Message Broker v6.1 has full support for Web Services provider and consumer scenarios with the addition of five new SOAP nodes:

� Provider nodes: SOAPInput node, and SOAPReply node

� Consumer nodes: SOAPRequest node, SOAPAsyncRequest node, and SOAPAsyncResponse node

These nodes can be combined to provide a Web service intermediary.

WebSphere Message Broker v6.1 simplifies the processing of SOAP payload and headers with two additional new SOAP nodes:

� SOAPEnvelope node� SOAPExtract node

SOAP Envelope

SOAP Header SOAP Header ……. SOAP Body

Optional Mandatory

Chapter 3. Web services support in WebSphere Message Broker V6.1 35

Figure 3-3 shows a summary of the new nodes, their function, and their icons in message flow.

Figure 3-3 New SOAP nodes by function

These SOAP nodes act as points in the flow where Web service processing is configured and applied. Properties on the SOAP nodes control the processing carried out and can be configured by supplying a WSDL definition, or by manually configuring properties, or both.

The new nodes are contained in the WebSphere Message Broker Toolkit V6.1 Web services palette (Figure 3-4).

Figure 3-4 New SOAP nodes in the toolkit palette

Note: The SOAP nodes are not considered a replacement for the existing HTTP nodes. There are scenarios where either the HTTP or the SOAP nodes can be used. SOAP nodes are used when you want to use the new SOAP domain or the new WS- capabilities (WS-Addressing and WS-Security).


3.3 Scenarios

WebSphere Message Broker toolkit v6.1 samples gallery demonstrate how you can use WebSphere Message Broker. Three samples are included to illustrate the Web services features: SOAP Nodes, WSRR Connectivity, and Asynchronous Consumer. These samples can be found in the Technology samples section under Web Services (Figure 3-5).

Figure 3-5 Web services samples in the Samples Gallery

3.3.1 Web service provider and consumer (SOAP Nodes sample)

The SOAP Nodes sample shows how the SOAPInput, SOAPReply and SOAPRequest nodes can be used to both provide and consume a Web service. The starting point for the sample is a WSDL file that defines a simplified ordering service. The Web service always returns a response indicating the part order is available.

The sample uses two message flows. One message flow provides a Web service and the other consumes a Web Service.


Web service provider flowThe provider message flow is described in Figure 3-6.

Figure 3-6 SOAP Nodes sample: Provider message flow

1. The SOAP Input node receives incoming SOAP messages, and if they are valid, passes them down the message flow to the OrderService_Extract subflow. The OrderService_Extract subflow is created by the Start from WSDL and/or XSD files wizard.

2. The SOAP Extract node takes a SOAP message and removes the SOAP envelope. In this sample, removing the SOAP envelope leaves an XML message in the XMLNSC domain, that can be used in the Compute node. The SOAP Extract node then routes the message to a label based on the Web Service operation that is being invoked.

3. When the XMLNSC message leaves the subflow and returns to the main provider message flow, it enters a Compute node. Using the Compute node, you can now reference the original SOAP body as XML, and perform ESQL operations on the data in the message. In the sample, the data in the message is ignored, and valid XML data is created from scratch.

4. This data is then sent to the SOAPReply node, which constructs a SOAP message to return to the Web Service consumer that initiated the Web Service call.


Web service consumer flowThe Web Service consumer message flow is described in Figure 3-7.

Figure 3-7 SOAP Nodes sample: Consumer message flow

Here is the message flow:

1. The Web Service consumer flow is initiated by an MQ message arriving on the queue monitored by the MQInput node. The message is an XML message in the XMLNSC domain.

2. The message enters a Compute node where the incoming data is used to create the XML data to send to the Web service.

3. The message is then passed down the flow to the Invoke_submitPO subflow. The Invoke_submitPO subflow is created by the Start from WSDL and/or XSD files wizard.

4. The SOAP Request node takes the incoming XML data and uses it to build a valid SOAP message to send to the Web service defined by the node properties.

5. If a valid response is received, it is passed to a SOAP Extract node, which removes the SOAP envelope from the response, returning the message to the XMLNSC domain.

6. The message is then routed to the ws_submitPOResponse label and exits the subflow.

7. In the main consumer flow, the message is sent to an MQOutput node that writes the XML data to the specified MQ queue.


3.3.2 Dynamic Web services (WSRR Connectivity sample)

The WSRR Connectivity sample is based on a scenario where a business wants to use the WebSphere Service Registry and Repository to dynamically choose a Web service to be invoked at runtime. The message flow is shown in Figure 3-8.

Figure 3-8 WSRR Connectivity sample

The nodes in the main message flow have the following functions:

1. The WSRR_IN input node gets the input message from the input queue.

2. The SetVersion Compute node overrides the "Version" property. The "Version" tag exists in the input message, therefore the LocalEnvironment tree is updated causing the EndpointLookup node to return the specified WSDL version from the Service Registry.

3. The EndpointLookup node connects to the Service Registry and retrieves the requested WSDL document. The message is propagated to one of the three wired nodes as determined by the successful (or otherwise) retrieval of a matching WSDL document from the Service Registry. Because the EndpointLookup node is configured to retrieve only "One" matching WSDL document, there is no need to follow this node with a Compute node. If the EndpointLookup node is configured to retrieve "All" matching WSDL documents, follow this node with a Compute node to interrogate the retrieved documents. You can use the Compute node to select the document to send to the SOAPRequest node as shown in the architecture figure above.

4. The message is propagated to the InformFailure node if WebSphere Message Broker encounters errors either connecting to, or while connected to the Service Registry.

5. The message is propagated to the SOAPRequest node if the EndpointLookup node successfully retrieved the requested WSDL document from the Service Registry. The node sends the SOAP message to the Web service determined by the endpoint in the WSDL.

6. Upon successful invocation of the Web service, the InformWSResult node converts the HTTP headers in the message to MQMD headers in order to propagate the response to the MQ Output node.

7. The message is propagated to the InformNoMatch node if the Service Registry could not find a matching WSDL document.

8. The WSRR_OUT node puts the message on the WSRR.OUT output queue.


3.3.3 Asynchronous Consumer sample

The Asynchronous Consumer sample demonstrates the use of the asynchronous SOAP nodes when calling Web services. A SOAPAsyncRequest node is used to demonstrate an order request to a Web service. The response from the Web service is asynchronously received using a SOAPAsyncResponse node paired with the SOAPAsyncRequest node. The flow is shown in Figure 3-9.

Figure 3-9 Asynchronous Consumer sample

1. A Web service request is constructed from an MQ message using the Compute Request node in the SOAP domain.

2. The Web service operation is invoked using the SOAP Asynchronous Request node and the paired SOAP Asynchronous Response node receives the response.

3. Finally the Format Response node formats the response as an MQ message.

3.4 Node details

This section goes into more detail on how the new nodes are configured.

3.4.1 SOAPInput node

The SOAPInput node is used to process client SOAP messages, thus enabling the broker to be a SOAP Web services provider. Figure 3-10 shows the node with its three terminals (Failure, Out, Catch), and the case in which the message is propagated to each of these terminals. The SOAPInput node is usually associated with a SOAPReply node.

Figure 3-10 SOAPInput node

If a failure is detected when themessage is propagated to the Out flow(such as a message validation failure)

If the message has been propagatedsuccessfully, and if further processingis required within this message flow

If an exception is thrown downstreamand caught by this node

Failure

OutCatch


The properties of the node are organized in the following tabs:

� Description� Basic� HTTP Transport� Advanced� WS-Extensions� Input Message Parsing (Parser Options)� Error Handling� Validation� Instances� Retry

The Basic, HTTP Transport, and Input Message Parsing tabs contain the main properties for SOAPInput, and they are discussed in this section. The WS-Extensions tab contains the WS-Security settings (to be discussed in the Security chapter) and WS-Addressing, which is discussed in a later section in this chapter. For more information about the other properties, see SOAPInput node at:

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/index.jsp?topic=/com.ibm.etools.mft.doc/ac56170_.htm.

Basic tabThis tab (Figure 3-11) contains the WSDL-related properties, including: WSDL file name, port type, binding, and service port.

Figure 3-11 SOAPInput node Basic tab properties

There are two methods to add the WSDL file from the message set:

� You can use the Browse button shown in Figure 3-11.

� Or, you can drag and drop the WSDL file on the SOAPInput node and the WSDL properties (WSDL file name, port type, binding, and service port) are populated automatically as shown in Figure 3-12.

Note: The WSDL file plays an important role in ensuring that the operation received in the incoming SOAP message is defined. Before configuring the WSDL file on this node, you must have a message set with a deployable WSDL resource.


http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/index.jsp?topic=/com.ibm.etools.mft.doc/ac56170_.htm

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/index.jsp?topic=/com.ibm.etools.mft.doc/ac56170_.htm

Figure 3-12 Drag and drop a WSDL file to the SOAP Input node

HTTP Transport tabThe HTTP transport tab contains the following properties:

� URL Selector: This is the address of the SOAPInput node. It identifies the message flow to which the messages are to be sent. This property is automatically set from the <soap:address> element of the selected Service port. if you override the value in the URL Selector, then your value persists, and the URL is no longer updated from the service port as shown in Figure 3-13.

Figure 3-13 SOAPInput node: HTTP Transport tab

Notes:

� When you select a WSDL file for the WSDL file name field, the WSDL is validated to ensure that it is WS-I compliant.

� Only deployable WSDL (that has a binding part) can be used to configure the SOAP nodes.

� Only HTTP transport is supported for the import binding.

� The WSDL binding should have at least one operation.

Note: The SOAPInput node has one listener per execution group (while the HTTP node has one listener per broker). You can use the mqsichangeproperties command to change port ranges for the execution groups. See:

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/index.jsp?topic=/com.ibm.etools.mft.doc/an09140_.htm


http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/index.jsp?topic=/com.ibm.etools.mft.doc/an09140_.htm

� Use HTTPS: This property is also automatically configured from the <soap:address> element of the selected Service port. If the address contains an https URL, the check box is selected, otherwise it is not. However, if you manually override this property value, it is no longer updated from the corresponding service port.

� Maximum client wait time (sec): Enter the Maximum client wait time timeout interval in seconds. The SOAPInput node is typically used in conjunction with the SOAPReply node. This property specifies the length of time that the TCP/IP listener that received the input message from the Web service client waits for a response from the SOAPReply node in the message flow. If a response is received within this time, the listener propagates the response to the client. If a response is not received in this time, the listener sends a SOAP Fault message to the client indicating that its timeout has expired.

Input Message Parsing tabIn this tab, the properties are automatically set when the WSDL file property is configured as shown in Figure 3-14.

Figure 3-14 SOAPInput node: Input Message Parsing tab

� The message domain field is set to the SOAP domain (default).

� The Message set field is set to the message set that has the WSDL file when the WSDL is associated with the node.

3.4.2 SOAPReply node

The SOAPReply node is used to send SOAP messages from the broker to the originating client in response to a message received by a SOAPInput node. Figure 3-15 shows the node with its three terminals (In, Out, Failure), and the case in which the message is propagated to each of them.

Figure 3-15 SOAPReply node

The input terminal thataccepts a message forprocessing by the node.

If a failure is detected when themessage is propagated.

If the message has beenpropagated successfully, andif further processing is requiredwithin this message flow.

Failure

Out

In


The SOAPReply node cannot be a stand-alone node, it must be associated with SOAPInput node. It sends the reply message to the originating client (that sent the request to the SOAPInput node) using the ReplyIdentifier field in the LocalEnvironment folder (LocalEnvironment.Destination.SOAP.Reply.ReplyIdentifier). This identifier is propagated from the SOAPInput node to the SOAPReply node, hence, it is important to preserve this field during the message propagation, so that it can be used by the SOAPReply node, as shown in Figure 3-16.

Figure 3-16 ReplyIdentifier field

Note: The SOAPReply node can accept SOAP and non-SOAP formats such as MRM, XMLNS, and so on.


3.4.3 SOAPRequest node

The SOAPRequest node (Figure 3-17) is used to send a SOAP request to a remote Web service. The node is a synchronous request and response node and blocks after sending the request until the response is received.

Figure 3-17 SOAPRequest node

Like the SOAPInput node, this node is associated with a WSDL file. The Web service URL is set in HTTP Transport tab, but it can be overridden at runtime by setting the value of OutputLocalEnvironment.Destination.SOAP.Request.Transport.HTTP.WebServiceURL.

3.4.4 SOAPAsyncRequest and SOAPAsyncResponse nodes

The SOAPAsyncRequest and SOAPAsyncResponse (Figure 3-18) nodes are used to construct a message flow (or pair of flows) that calls a Web service asynchronously.

Calling a Web service asynchronously means the SOAPAsyncRequest node sends a Web service request, but the request does not block the message flow while waiting for the associated Web service response to be received. The Web service response is received at a SOAPAsyncResponse node in a separate flow.

The message flows containing the SOAPAsyncRequest and SOAPAsyncResponse nodes must be in the same execution group. The Node Correlator identifies the logical pairing of the responses against the original requests. Multiple requests can, therefore, be handled in parallel. However, the SOAPAsyncRequest node does wait for the HTTP 202 acknowledgement before continuing with the message flow, and the SOAPAsyncRequest node blocks if the acknowledgement is not received.


SOAP fault messages will be directeddown the Fault terminal.

If the message has been propagatedsuccessfully, and if further processing is required within this message flow.

Failure

FaultOut


In


Figure 3-18 SOAP asynchronous request and response

The SOAPAsyncRequest node properties (Figure 3-19) are similar to SOAPRequest node. The only difference between this node and the SOAPRequest node is the Unique identifier that is used to identify the associated SOAPAsyncResponse node.

Figure 3-19 SOAPAsyncRequest node: Basic properties tab




InFail

ure

Fault



SOAP fault messages will be directeddown the Fault terminal.

If an exception is thrown downstreamand caught by this node.

FaultFa

ilure

Out

Catch


The SOAPAsyncResponse node also has the Unique identifier field for correlation with the SOAPAsyncRequest node as shown in Figure 3-20.

Figure 3-20 Correlating an asynchronous request with the response

3.4.5 SOAPExtract node

The SOAPExtract node has two main functions:

� Extract function: The default behavior is to detach the SOAP envelope to a standard location (LocalEnvironment.SOAP.Envelope) in the LocalEnvironment tree. Alternatively, you can specify an explicit location using an XPath expression. Any existing SOAP envelope at the chosen location is replaced.

� Routing function: The SOAP message is routed to a Label node within the message flow as identified by the SOAP operation within the message. The SOAP operation is identified within the SOAP body tag.

Note: The SOAPAsyncRequest node is WSDL-driven, while the SOAPAsyncResponse node is not WSDL-driven.


Figure 3-21 shows these two main functions and their impact on the message structure.

Figure 3-21 SOAPExtract node

This node can work with the following domains: SOAP, XMLNSC, MRM, XMLNS, because they can handle namespaces. Figure 3-22 shows the message before and after the SOAPExtract node.


Figure 3-22 Message processing in the SOAPExtract node

3.4.6 SOAPEnvelope node

The default behavior of the SOAPEnvelope node (Figure 3-23) is to attach the SOAP envelope from a standard location (LocalEnvironment.SOAP.Envelope) in the LocalEnvironment tree to the message; you can specify an explicit location by using an XPath expression. You can also use the node in a flow without a corresponding SOAPExtract node; the node has an option to create a default SOAP envelope.

Figure 3-23 SOAPEnvelope node




InFail

ure

Out


3.5 SOAP domain and parser

A SOAP message domain has been added to support the model-driven parsing of SOAP messages, including SOAP with Attachments (SwA) and MTOM, in support of the new SOAP nodes. The SOAP parser creates a common logical tree representation for all SOAP-based Web services and validates the message against a WSDL definition. If a runtime message is not allowed by the WSDL, an exception is thrown, otherwise the portType and operation names from the WSDL are saved in the logical tree.

The SOAP domain offers WS-processing, together with a canonical tree shape that is independent of the wire format (XML or MIME).

The SOAP tree created by the SOAP domain is shown in Figure 3-24.

Figure 3-24 SOAP tree created by the SOAP domain

Note: The SOAP parser invokes the XMLNSC parser to parse and validate the XML content of the SOAP Web service.

Root

Set=myMS Type Format ContentType=top-level C-T

SOAPProperties Transport headers

operationportTypeportservicefileNameoperationType= ='REQUEST_RESPONSE' | 'ONE_WAY'SOAP_Version='1.1'|'1.2'Namespace

prefix=urlXMLDeclaration

Context Header

fred(subtree)

bill(subtree)

harry(payload subtree)

Body

ID0 ID1 IDN

as ID0 as ID0

Content-Type=Content-Transfer-Encoding=Content-Id=

MIME_Headers

BLOB(=X'…')

BLOB

XMLNSC

Contains information set by the SOAP

parser on input based on WSDL Envelope.Header Envelope.Body

Attachment

SwA message in theirnon-encoded format

Created bySOAP Parser

User can re-parseas required – e.g.,


3.6 Web services extensions

The new SOAP nodes support WS extensions such as WS-Addressing and WS-Security. WS-Addressing support are discussed in this chapter, while WS-Security is discussed in the Security chapter.

Web Services Addressing (WS-Addressing) is a Worldwide Web Consortium (W3C) specification that aids interoperability between Web services by defining a standard way to address Web services and provide addressing information in messages. The WS-Addressing specification introduces two primary concepts: endpoint references (EPRs), and message addressing properties (MAPs). See http://www.w3.org/Submission/ws-addressing/

EPRs provide a standard mechanism to encapsulate information about specific endpoints. EPRs can be propagated to other parties and then used to target the Web service endpoint that they represent. MAPs are a set of well defined WS-Addressing properties that can be represented as elements in SOAP headers and provide a standard way of conveying information, such as the endpoint to which message replies should be directed, or information about the relationship that the message has with other messages. Figure 3-25 shows a sample of the WS-Addressing header in a SOAP message.

Figure 3-25 WS-Addressing header in a SOAP message

In the following sub-sections, we discuss WS-Addressing support for the SOAPInput, SOAPRequest, SOAPReply, SOAPAsyncRequest, and SOAPAsyncReply nodes.

Notes:

� The content of the Body subtree depends on the WSDL style.

� The attachments for an MTOM message are represented inline as part of the SOAP content in a base 64 representation.

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="http://www.w3.org/2005/08/addressing">

SOAP HeaderAddress to sendthe message

Address tosend the reply

MessageUnique ID

URL that uniquelyidentifies thesemantics of themessage

SOAP Body

<S:Header>

<wsa:To>http://fabrikam.example/Purchasing</wsa:To>

<wsa:ReplyTo>

<wsa:Address>http://example/client1</wsa:Address>

</wsa:ReplyTo>

<wsa:MessageID>urn:uuid:020C911C16EB130A8F1204119836321</wsa:MessageID>

<wsa:Action>http://fabrikam.example/SubmitPO</wsa:Action>

</S:Header>

<S:Body>

...

</S:Body>

</S:Envelope>

Note: <wsa:Action> should have the value of the WSDL soapAction attribute so that the message can be accepted by the SOAPInput node.


http://www.w3.org/Submission/ws-addressing/

3.6.1 SOAPInput and SOAPReply

The SOAPInput node has a property for processing WS-Addressing information present in the incoming message called Use WS-Addressing. If you select this property, the WS-Addressing information is processed and the process itself is called engaging WS-Addressing.

If WS-Addressing is not enabled on the message flow, and the client uses WS-Addressing, the WSA headers are not processed. If these headers are marked must understand, a SOAP fault is returned.

Place WS-Addressing Headers into LocalEnvironment is a property that specifies whether the node puts WS-Addressing headers received in the message into the LocalEnvironment tree. WS-Addressing headers are not accessible to the flow if this check box is cleared because by default, all headers are processed and removed. These two properties are shown in Figure 3-26.

Figure 3-26 SOAPInput node WS-Addressing properties

Note: To benefit from the Place WS-Addressing Headers into LocalEnvironment property, you have to update your WebSphere Message Broker Toolkit and WebSphere Message Broker runtime to version 6.1.0.2 or higher.


Assuming that the WS-Addressing headers are valid and the Place WS-Addressing Headers into LocalEnvironment check box is selected on the SOAPInput node, all headers (including detectable inbound reference parameters) are removed from the inbound message tree and are placed into the LocalEnvironment tree under the SOAP.Input.WSA folder. The mapping between the input SOAP message (with WS-Addressing headers) and the LocalEnvironment is shown in Figure 3-27.

Figure 3-27 WS-Addressing header mapping to the message tree

The SOAPReply node uses WS-Addressing if WS-Addressing is engaged on the SOAPInput node that is referenced by the reply identifier of the message entering the reply node. The SOAPReply node uses addressing information in the Destination.SOAP.Reply.WSA folder of the LocalEnvironment to determine where to send the reply and with what MAPs. In the case where there are folders beneath the Reply.WSA folder, these are used to update the output message. This allows you to change, add, or remove parts of the default reply information generated by the input node because any changes you made to the tree are reflected in the outgoing message by the SOAPReply node.

Figure 3-28 summarizes the behavior of SOAPInput and SOAPReply nodes when WS-Addressing is enabled.


Figure 3-28 WS-Addressing summary

3.6.2 SOAPRequest node

SOAPRequest node has the same properties as SOAPInput node for enabling WS-Addressing. The node first looks at the Destination.SOAP.Request.WSA folder in the LocalEnvironment. If this folder is empty, the node automatically generates all required WS-Addressing MAPs in the outgoing message, using the following defaults:

� Action: From the WSDL configuration file. If this is not explicitly specified, this defaults to the value defined in the WSDL Binding specification.

� To: From the Web Service URL node property.

� ReplyTo: Using the special Anonymous address (assuming that the Operation being used is not a one-way message exchange program, in which case a ReplyTo using the special None address is specified).

� MessageID: A unique UUID is used.

If the Destination.SOAP.Request.WSA folder in the LocalEnvironment is not empty, any user supplied MAPs override the default ones listed previously on a property by property basis.

After the response to the request is received and if the Place WS-Addressing Headers into LocalEnvironment checkbox is selected on the SOAPRequest node, the SOAPRequest node removes all WS-Addressing headers from the response message and places them in the SOAP.Response.WSA folder. This folder allows you to query the headers in a similar manner to the way the SOAPInput node deals with the Input WS-Addressing headers.

*anonymous refers to W3C standard format (http://www.w3.org/2005/08/addressing/anonymous) to return the reply to the original requester.

SOAPRequest

"Reply To"address is set to "anonymous"

"Reply To"address is set to "Client2" address

Web Service Client 1 Web Service Client 2

WS-Addressing headerspopulated into LocalEnv.

LocalEnv. populated intoWS-Addressing headers


3.6.3 SOAPAsyncRequest and SOAPAsyncResponse nodes

The SOAPAsyncRequest and SOAPAsyncResponse nodes require WS-Addressing in order to work. Therefore the remote Web service must understand WS-Addressing in order to correctly process the WS-Addressing headers that are sent from the SOAPAsyncRequest node, and to allow the response to be sent back to the corresponding SOAPAsyncResponse node, which is specified in the address property of the ReplyTo message addressing property (MAP). For more information on how they operate, refer to the following articles:

� WS-Addressing with the SOAPAsyncRequest and SOAPAsyncResponse nodes

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/topic/com.ibm.etools.mft.doc/ac64530_.htm

� WS-Addressing information in local environment

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/topic/com.ibm.etools.mft.doc/ac56600_.htm.

3.7 Improved WSDL integration

The SOAP nodes use WSDL files contained in message sets. Three new features improve the development experience when working with Web services in message flows:

� A new wizard helps you create a message definition from a WSDL file

� Message flows for Web services can be initialized by dragging and dropping a WSDL file to the editor.

� You can generate a WSDL from an existing message set definition.





A wizard has been added to create a new message definition file from a WSDL file. The wizard can be started by selecting File → New → Message Definition File From... → WSDL file, shown in Figure 3-29.

Figure 3-29 New message definition file wizard

After completing the wizard, the WSDL file that is used in the message definition file creation appears under Deployable WSDL in the workbench.

The WSDL file in the Deployable WSDL folder (Figure 3-30) is annotated to keep track of message definition files created by the importer, and keep WSDL files synchronized with Message Definition files. Schema type definitions referenced externally or defined in-lined are changed to reference mxsd files in the message set.


Figure 3-30 WSDL file in a message set

After Importing the WSDL file into the message set, this file can be used within the message flow (either for exposing message flow as Web service, or invoking a Web service from message flow). This can be achieved by dragging and dropping the WSDL file on the editor as shown in Figure 3-31.

Figure 3-31 Drag and drop WSDL to the editor


The output message flows that result from selecting either the Expose message flow as web service or Invoke web service from message flow settings are shown in Figure 3-32.

Figure 3-32 Message flows that result from dropping WSDL files to the editor

To generate WSDL from a Message Set definition, right click on the message set folder, and select Generate → WSDL Definition (Figure 3-33).

Figure 3-33 Generating a WSDL file from a message set definition


3.8 Integration with WebSphere Service Registry and Repository

The WebSphere Service Registry and Repository is a central repository of documents describing services, service interfaces (for example, SOAP over HTTP), and associated policies that control access mechanisms (for example, WS-Policy documents associated with either of the previous two).

WebSphere Service Registry and Repository allows a message flow to dynamically retrieve artifacts from the repository at runtime, and to use and expose those artifacts within the message flow. This allows you to defer the decision about which artifacts you want to use until runtime, rather than making the decision at deployment time.

Generic XML documents, WSDL, SCDL, and all other formats that are supported by the WebSphere Service Registry and Repository, can be stored in the repository. However, some queries that you might submit to the repository might only apply to certain document types, for example, a query for a port type can only be applied to WSDL documents.

WebSphere Message Broker toolkit supports WebSphere Service Registry and Repository by providing two new nodes (the EndpointLookup and RegistryLookup nodes) to create message flows that use the repository to retrieve artifacts dynamically according to the search criteria provided either on the node, or dynamically within the LocalEnvironment. This allows the succeeding nodes to use the information retrieved from the repository (Figure 3-34).

Figure 3-34 Using an EndpointLookup node to access the service repository

The WebSphere Service Registry and Repository profile, DefaultWSRR, should be configured with the endpointAddress value of the repository using mqsichangeproperties.

Note: WebSphere Message Broker V6.1.0.2 only supports WebSphere Service Registry and Repository V6.1. Previous versions of the product are not supported.

WebSphere Message Broker

Message Flow

WSRR


Example 3-1 Changing the endpoint address of the repository

mqsichangeproperties WBRK613_BROKER -c ServiceRegistries -o DefaultWSRR¬† -n endpointAddress -v http://localhost:9081/WSRR6_1/services/WSRRCoreSDOPort

The description of this command is shown in Figure 3-35.

Figure 3-35 mqsichangeproperties command

The broker should be restarted for changes to take effect.

As for caching artifacts retrieved from the repository, see Caching artefacts from the WebSphere Service Registry and Repository at:

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/topic/com.ibm.etools.mft.doc/ac56270_.htm.

3.8.1 EndpointLookup node

The EndpointLookup node is generic in that it retrieves service endpoint information related to a WebSphere Service Registry and Repository service, for example, WSDL. The EndpointLookup node is independent from any other domain context, and support is currently limited to querying endpoints for Web services. The EndpointLookup node provides a query interface that enables you to select a single or all endpoints, and to set up environment parameters to enable Web service invocation nodes to submit requests to the selected services.

Figure 3-36 shows the terminal behavior for the EndpointLookup node.

Figure 3-36 EndpointLookup node

mqsichangeproperties WBRK613 BROKER

-c ServiceRegistries

-o DefaultWSRR

-n endpointAddress

-v http://localhost:9081/WSRR6_1/services/WSRRCoreSDOPort

Configurableservice name

Object name

Broker name

Property name

Property value


If a matching endpoint is found.

If no matching endpoint isfound based on the specifiedvalues.

Failure

OutNoMatch


In




The EndpointLookup node supports the SOAPRequest, SOAPAsyncRequest, and HTTPRequest nodes. The Basic properties for the EndpointLookup node are shown in Figure 3-37.

Figure 3-37 EndpointLookup node properties

This node queries the repository by using one or more of the following types of information:

� PortType information (Mandatory): at least one of portType name, portType namespace, or portType version must be defined to uniquely identify a WSDL service portType defined in the repository. The mapping between the portType information in the EndpointLookup node properties and the published service portType in the repository is shown in Figure 3-38.

PortType information

Port user-definedproperties

Port classificationURL

Match Policy(One/All)


Figure 3-38 EndpointLookup node properties - port type

� User Properties (Optional): port user-defined properties. The mapping between the user properties in the EndpointLookup node and the published service Port in the repository is shown in Figure 3-39.

Figure 3-39 EndpointLookup node properties - user-defined port properties


� Classification (Optional): The Web Ontology Language (OWL) classification system property. Each classifier is a class in OWL, and has a Uniform Resource Identifier (URI). Using classifications in the registry can help to make objects easier to find and can also add meaning to custom objects that are unique to a particular system. The mapping between the classification in the EndpointLookup node properties and the published service Port classification in the repository is shown in Figure 3-40.

Figure 3-40 EndpointLookup node properties - classification properties

The EndpointLookup node uses the information defined within its properties to query the repository. One or more results are returned depending on whether you set the Match Policy property value to One or All.

If the Match Policy is set to One, the EndpointLookup node sets the endpoints so that service information is correctly placed in the domain context, ensuring that existing WebSphere Message Broker built-in nodes correctly invoke the service as shown in Figure 3-41.


Figure 3-41 Match policy of “one” results

If Match Policy is set to All, the EndpointLookup node returns multiple endpoints if applicable. In the case of multiple endpoints, a compute node must be placed after the EndpointLookup node to determine which endpoint to be invoked.

3.8.2 RegistryLookup node

The RegistryLookup node is used to access service metadata that resides in WebSphere Service Registry and Repository. The RegistryLookup node does not perform additional filtering or selection other than that specified by the property matching. When you use this node, the entity matching the required search criteria is stored within the LocalEnvironment. The actual message is not changed by the RegistryLookup node, although the LocalEnvironment is updated to reflect the search results.

Figure 3-42 shows the terminals for the RegistryLookup node.

Figure 3-42 RegistryLookup node

HTTPRequestnode URL

SOAPRequest/SOAPAsyncRequestnode URL

WSRR Information


If a matching registry informationis found.

If no matching entity is found based on the specified values.

Failure

OutNoMatch


In


The node properties are shown in Figure 3-43.

Figure 3-43 RegistryLookup node basic properties

This node queries the repository by using one or more of the following types of information:

� Entity information (Mandatory): At least one of WSRR entity name, namespace, or version must be defined to uniquely identify a WSRR artifact defined in the repository.

� Template (Optional): Refers to the template or artifact type that you want to return from the repository. WSRR provides a simple template model that allows User Defined properties and relationship names to be applied consistently. These templates are defined as complex types within an XSD document with attributes being used to represent the property and relationship names expected for entities created from the templates.

� Classification (Optional): This is the same as discussed in EndpointLookup node.

Entity information

WSRR Templatename

Entity user-definedproperties

Entity classificationURL

Match Policy(One/All)


The message coming out of this node is shown in Figure 3-44.

Figure 3-44 RegistryLookup node results

3.8.3 Dynamic search criteria

You can use the RegistryLookup and EndpointLookup nodes to accept queries specified within the LocalEnvironment. The LocalEnvironment overrides the search criteria properties set on the preceding WebSphere Service Registry and Repository node. The search criteria properties can be set in the LocalEnvironment using a Compute node before the RegistryLookup and EndpointLookup nodes as shown in Figure 3-45.

WSRR Entityinformation


Figure 3-45 Dynamic search for a service

Dynamically overridesearch criteria

Notes:

� Template property is only valid for the RegistryLookup node. This property is ignored by the EndpointLookup node.

� Repeating values of the User Properties property are appended to the current User Properties value defined in the RegistryLookup or EndpointLookup node unless the value is NULL, in which case the User Properties value is removed.

� For the Classification property, repeating values are always appended; you cannot remove a value that is set in the WebSphere Service Registry and Repository node properties.


Chapter 4. File processing support in WebSphere Message Broker V6.1

The purpose of this chapter is to show the inbound and outbound file manipulation support added in WebSphere Message Broker V6.1.

With WebSphere Message Broker V6.1, it is now possible for the native Message Broker product to read and write files from file systems and FTP servers and to process those files (native function for processing files). Files are one of the most common methods used to store data, and file transfers of this data form the backbone of many business IT systems.

In this chapter we explain these new features and also show some common file handling options. This information is intended to help Message Broker developers to implement file handling scenarios with the new nodes.

4


4.1 File processing overview

WebSphere Message Broker, in its role as an enterprise service bus, supports a variety of communication protocols, including HTTP, JMS, WebSphere MQ, Web Services, XML (SOAP), and WebSphere Adapters. It is built for universal connectivity, routing, and transformation of data in heterogeneous IT environments. The new File Processing nodes support the communication between service requestor and service provider with files instead of messages. Two new file processing nodes, FileInput and FileOutput, provide a rich functionality to process files during a read from a file system and during a write to a file system on distributed platforms.

The FileInput and FileOutput nodes can be used together or with other Message Broker nodes to provide:

� File to file processing� Large file handling and bulk transfer� Stream parsing� Propagation to many nodes or input from many nodes� File to queue or queue to file processing� Batch processing

There is a clear differentiation between file processing and file transfer:

� File processing is done by the new Message Broker nodes. Actions can be defined upon the data or the data structure

� Reliable file transfer and message transfer are done by the underlying product WebSphere MQ or the new announced WebSphere MQ FTE (File Transfer Edition). These products are classical MOMs. File transfer can also be done by FTP and other third party vendor products.

The following definitions are used in combination with the new file processing nodes:

� A file is a collection of related data or records stored as a unit with a single name in a file system.

� Processing means to perform a certain operation or operations on the data in the file.

A file, or record within a file, is analogous to a message in a queue. The directory that contains the file is analogous to a message queue.


Figure 4-1 illustrates how the file processing nodes interact with the file system.

Figure 4-1 File processing overview

The FileInput node polls new files from a local file system directory or from an FTP server directory. Settings in the FileInput node determine whether it looks for files by a certain name or by pattern. When the node finds a file it has not processed, it reads the file and parses it according to the settings in the node. The file is then propagated to the next node in the message flow as a whole file or as a sequence of individual records.

The FileOutput node receives data from the previous node in the message flow. The node can receive the data as a whole file or as a sequence of individual records. Settings in the FileOutput node determine where it writes the data to the local file system or FTP server directory. The data can be written as a whole file or as a sequence of records as long as a message arrives that indicates the end of the file.

4.2 File processing nodes

WebSphere Message Broker V6.1 is the first release to provide file handling capability out of the box as part of the core product. Message flows can be created to process data in files, accepting data in files as input message data, and producing output message data for file-based destinations. SupportPacs or other plug-in solutions were used in the past, but the new FileInput and FileOutput nodes should now be the first choice when implementing file interfaces with Message Broker for both new and existing message flows.

In the following sections we discuss the file processing options available with the new FileInput and FileOutput nodes. These new nodes are contained in the File drawer of the palette when building a message flow in the Message Brokers Toolkit.

WebSphere Message Broker

File System

Message flow

File System

Chapter 4. File processing support in WebSphere Message Broker V6.1 71

4.2.1 FileInput node

A single file can be read as an entire file or as a set of individual records from the file system. Depending on the file, and how it is read, one or more messages are created and each message is propagated as a separate transaction. The properties on the FileInput node determine how the records in a file are identified.

The FileInput node is represented in the workbench by the following icon (Figure 4-2):

Figure 4-2 FileInput node

The FileInput node has the following terminals:

� Failure: In case of an error, the message is routed to the output terminal first and then propagated to the out terminal. Messages propagated to this terminal are not validated.

� Out: Standard output terminal for messages if they have been successfully extracted from the input file.

� End of Data: Output terminal for the End of Data message. This terminal is used for the End of Data message after the last propagation and is initiated only if this terminal is attached.

� Catch: Output terminal for messages if an exception is thrown downstream and caught by this node. Used only if this terminal is attached.

FileInput node processingThe FileInput node can select the files to process in one of the following ways:

� All files

� Files with a specific name

� Files with that follow a specified pattern. Character or string substitution is indicated with wildcards (*, ?).

The FileInput node reads files from a specified directory called the input directory. It propagates messages based on the contents of these files. The FileInput node also offers select actions on these files. The files can be deleted or put in an archive subdirectory, which is automatically created within the input directory. A check box is available for replacing duplicate archive files.

Failure

OutEnd of Data

Catch

File System


These settings are contained in the Basic tab for the FileInput node (Figure 4-3).

Figure 4-3 FileInput node basic properties

A deployment of the message flow starts an initial scan of the specified input directory and processes the oldest file first with the correct file name or pattern. Subsequent reads from the input directory are done at polling intervals. Each file is parsed by the FileInput node using a single thread. The file is sent as a whole file via the terminal out. No other definitions are necessary for a basic usage of the FileInput node within a message flow.

Options for propagation of content from a fileSeveral methods are available under the Records and Elements tab (Figure 4-4) to read content from a file and propagate it:

� Whole File: The entire file is read and propagated in one propagation.

� Fixed Length: Each record is parsed and sent out one at a time. The FileInput node determines how much data constitutes a record by counting its length, determined by a length attribute. Delimiters are not required to separate each propagation.

� Delimited: Like fixed length, each record is parsed and sent out one at a time. Delimiter characters are used to separate each propagation. The delimiter can be set to either DOS carriage return and line feed character (<CR><LF>), on UNIX with a line feed character (<LF>), or a custom delimiter (z/OS newline X'15').

� Parsed Record Sequence: No delimiters are required; the parser has to detect the end of a propagation and the start of new propagation.


Figure 4-4 FileInput node properties: Records and Elements tab

Record detection optionsFigure 4-5 summarizes the different record detection options that can be selected under the Records and Elements tab:

Figure 4-5 Record detection options

Fixed Length PropagationFile Input node counts lengthand splits each propagation

Propagation 1

Propagation 1

Propagation 2

Propagation 3

Propagation 1

Propagation 2

Propagation 3

Record is Whole File

Delimited PropagationFile Input node splits each propagation based on delimiter characters

Parsed Record Sequence PropagationParser dedects record structure and splits each propagation

Delim

iter characters

Propagation 1

Propagation 2

Propagation 3


Whole file versus recordsThe decision to make is how much data from the file should be sent through the message flow with the propagation of the whole file or the propagation of each record (defined with fixed length or with delimiter). While there is no solution that fits all requirements, there are some recommendations. Although it makes sense for smaller files to be propagated as a whole, larger files, files with a heterogeneous dataset, or files with different recipients of data within the file can benefit from being propagated in multiple parts. The record detection parameter fixed length uses a default value of 80 but the value can be vary between 1 byte and 100 MB.

Homogeneous data files, data in files that belong together, and files that are not very big can be propagated as a whole file as shown next. In this case, the FileInput node does not perform record detection and does no parsing of the file. It propagates the file as a single record. The file is sent as a Binary Large Object (BLOB).

Figure 4-6 illustrates a file sent in one propagation:

Figure 4-6 Whole file sent in one propagation

Heterogeneous data files, data in files that do not logically belong together, and large files can be divided by delimiters or parsed and propagated in several records. For example, one propagation occurs for each ItemDescription. A delimiter is a sequence of characters (or one character) used to specify the boundaries in data streams or files.

Delimiters represent one of various means to specify boundaries in a data stream. There are alternate means as well. Declarative notation, for example, is an alternate method that uses a length field at the start of a data stream to specify the number of characters that the data stream contains.

MessageBroker

File System

Message


Figure 4-7 illustrates a file divided by fixed length, delimiters, or parsed, and sent in many propagations.

Figure 4-7 File propagated in parts

Message parsing optionsThe previous sections discuss how files are read from a file system and how those files are propagated. All files and records are sent as Binary Large Objects (BLOBs), which is the default option under the Input Message Parsing tag.

Message Broker also offers the concept of message domains. The message domain parameter determines which parser is to be used when analyzing messages. Message Broker provides several parsers for analyzing and writing the format of data. A parser is a piece of software that interprets the bitstream of an incoming message and produces an internal representation of the message in a tree structure. The parser also generates another bitstream for an outgoing message on the basis of the internal representation in the message tree. Each parser is linked to a specific message class (for example, binary with a fixed length, with limiter text, or XML).

The FileInput and FileOutput parsed record sequence setting support in Message Broker V6.1 defines the following parsers to carry out record detection:

� XMLNSC domain parser� MRM TDS domain parser� MRM CWF domain parser

MessageBroker

File System

Message 1 .. n

Message End of Data


The relationship between native data bindings, messages, and message domains is shown in Figure 4-8.

Figure 4-8 Native bindings, messages, and message domains

The FileInput node can treat messages in the following message domains:

� MRM (MRM parser and domains)� XMLNSC, XMLNS and XML (XML parser and domains)� SOAP (SOAP parser and domains)� DataObject (DataObject parser and domains)� JMSMap and JMSStream (JMS parser and domains)� MIME (MIME parser and domains)� BLOB (BLOB parser and domains)� IDOC (IDOCparser and domains)

MQ Native Data Binding MQ Message (Header + Body) Message Domain

Serialized as XML

Serialized as Java Object

Unstructured Text Message

Unstructured Binary Message

MQMD MQRFH2

MQMD

MQMD

Java Object

MQMD MQRFH2 XML Message (Namespaced)

Unstructured Text Message

Unstructured Binary Message

XMLNSC MRM (XML)

BLOB

MRM (TDS)

MRM (CWF)


Figure 4-9 shows the Input Message Parsing tab for the node, where these settings can be configured.

Figure 4-9 FileInput node properties: Parser options

When the FileInput node reads and parses a file with an XML structure, the data arrives in the form of an input stream. This input stream must be converted into a logical message tree before it can be processed by the message flow. The parser must understand both the format of the bit stream and its logical structure in order to create the message tree. In the following example you can see the results of the conversion of an XML structure, OrderMsg, to a message tree. This conversion is stored as a message definition file with the .mxsd extension (Figure 4-10).


Figure 4-10 Input stream converted to a message tree format

Validation of inputUse the Validation tab of the FileInput node to provide validation based on the message set for predefined messages (Figure 4-11).

Using an FTP server for inputThe FileInput node can be used to execute a poll of an FTP server in order to retrieve files. Select the FTP tab to configure the properties. Select the FTP check box and type in the FTP address of the server, the port number and the server directory.

Before deploying the message flow, ensure that the user name and password used for FTP authority are correct. The Security identity property causes the Message Broker to get the user name and password from its security store. The mqsisetdbparms command with the prefix ftp:: is used to configure these settings (stop the runtime broker before calling the command).

The syntax is:

mqsisetdbparms <Brokername> -n <Resource> [-u <userid>] [-p <password>]

For example:

mqsisetdbparms MyBroker -n ftp::myidentity -u myuserid -p mypassword


Figure 4-11 FileInput node: FTP properties

Polling propertiesThe Polling tab contains a property allowing you to set the polling interval. This interval defines the frequency with which the node looks for files to process in the defined file system. Set the polling interval according to the application requirements; the default value is 5 seconds.

Retry propertiesUse the Retry tab (Figure 4-12) to specify what actions should be carried out in case a message flow fails. You can set the following retry mechanism: The file can be moved to a backout subdirectory or it can be deleted. Additionally, a timestamp can be appended to the file name if the file is moved to the backout directory.

Figure 4-12 FileInput node properties: Retry


Instances tabUse the Instances tab to control the additional instances (threads) that are available for a node. The default value for additional instances is 0, but up to 256 threads can be used from the Message Broker to service the message flow.

4.2.2 FileOutput node

The FileInput node can propagate messages as single transactions or many related transactions. The FileOutput node receives one or more messages from those message flow transactions and writes them to the file system. The properties on the node specify how the FileOutput node treats the data and determines the records in a file. Each message is converted to a record and then written to a file. The write can be done as a whole file (a whole file is a record) or individually as long as no more records are left to process. The FileOutput node is represented in the workbench by the following icon (Figure 4-13).

Figure 4-13 FileOutput node

The FileOutput node has the following terminals:

� In: The input terminal receives a message from the message flow for processing.

� Finish File: The input terminal receives a message that triggers the finishing of a file.

� Failure: The output terminal to which the message is routed if a failure is detected when the message is propagated.

� Out: The message received on the In terminal is propagated to this terminal if the record is written successfully. The message is unchanged except for status information in the Local Environment.

� End of Data: The message received on the Finish File terminal is propagated to this terminal if the file is finished successfully.

File processingThe FileOutput node receives a file through the In terminal and writes the entire file, using a specified name or name pattern to an output directory. The file can be replaced, created, or appended with or without timestamp. The FileOutput node also receives records of a file via the In terminal and writes those records to a file as long as the file is not finished (determined by input to the Finish File terminal) and closed.

File System

In

Finish File

Failure

Out

End of Data


The FileOutput node uses subdirectories within the output directory to create files during processing and to move files after processing. All of these subdirectories begin with the prefix "mqsi".

� Message Broker creates an mqsitransit directory to temporarily store files. Records are not accumulated directly into a file in the output directory but are accumulated in a file in the transit directory. Files are moved from the transit directory to the output directory when finish processing occurs.

� Message Broker creates an mqsiarchive directory if a file is moved to the output directory and a file with the same name is already in the output directory. The file in the output directory can be deleted or moved to the mqsiarchive directory (with the same name or renamed before being moved).

These settings are contained in the Basic tab.

The entire file is written to the file system specified using the file name or pattern specified. There is also a check box available for replacing duplicate archive files (Figure 4-14).

Figure 4-14 FileOutput node basic properties

Methods to write content to a fileThe FileOutput node can write files as a sequence of one or more records to a file system. Each record is generated from a single message received on the In terminal of the node. As a default, each file is composed of a single record, and finish processing occurs immediately after the record is written. In other cases, properties of the FileOutput node Records and Elements tab specify that the file is composed of multiple records and specifies how these records are accumulated in a file (Figure 4-15).

Figure 4-15 FileOutput processing

MessageBroker

File System

Message 1 .. n

Message Finish File


Records can be accumulated in a file in the following ways (Figure 4-16):

� Record is unmodified data: The record from each message is appended (concatenated) unmodified to the file. The file is finished when a message is received on the Finish File terminal.

� Record is fixed length data: Each record is adjusted to be a specific length and padded with a padding byte, if necessary, before being appended to the file. The file is finished when a message is received on the Finish File terminal.

� Record is delimited data: A delimiter is used to separate or terminate the records as they are appended to the file. The file is finished when a message is received on the Finish File terminal.

Figure 4-16 FileOutput node properties: Records and elements


Figure 4-17 summarizes the different record definition options that can be selected under the Records and Elements tab:

Figure 4-17 Record definition options

Output data specificationsThe Request tab of the FileOutput node lets you specify the location of data or which data should be written to the file system. It also provides control information overriding the basic tab's directory and file name or pattern properties. Properties on this tab can be specified as XPath or ESQL expressions.

The data location parameter specifies the location in the input message tree that contains the record to be written to the output file. The default value is $Body, which means that the entire message body ($InputRoot.Body) is written. By clicking Edit you can see the XPath expression builder and the structure of the message, as shown in Figure 4-18.

The Request directory property location and the Request file name property location parameters let you override the information set in the basic tab with an XPath expression.

Record is Unmodified Data

Propagation 1

Propagation 1

Propagation 2

Propagation 3

Propagation 1

Propagation 2

Propagation 3

Propagation 1

Propagation 2

Propagation 3

Record is Whole File

Record is Fixed Length DataFile Output node splits each propagation to a required length and adds padding bytes

Record is Delimited DataFile Output node splits each propagation and adds delimiter characters

Delim

iter charactersP

adding bytes


Figure 4-18 FileOutput node properties: Request

ValidationUse the properties in the Validation tab to provide validation based on the message set for predefined messages. Validation applies only to messages that you have modeled and deployed to the Message Broker. The Message Broker does not provide any validation for self-defining messages. Message domains that support validation are MRM, XMLNSC, SOAP, and IDOC. MRM and XMLNSC are important for the file processing nodes:

� MRM parsers validate predefined messages against the message dictionary generated from a message set

� XMLNSC domains validate predefined messages directly against XML Schema generated from a message set

Using an FTP server for outputThe FileOutput node can be used to connect to an FTP server in order to write files to a FTP server directory. The settings are found in the FTP tab and are similar to those for the FileInput node (Figure 4-19).


Figure 4-19 FileOutput node properties: FTP

TransactionalityAlthough the FileInput node is not transactional, this property affects whether the rest of the nodes in the message flow should be executed under syncpoint or not. Setting the Transaction mode property to “yes” means that flow updates (for example, inserting in a database, and writing a message to a WebSphere MQ queue) should be treated transactionally if possible (Figure 4-20).

The interactions between a message flow containing a file handling node (input or output) and the file system itself are not transactional. This kind of coordination would only be possible with the support of a truly transactional file system. Therefore the file writes, moves, deletes and appends which are choreographed through the configuration of the file handling nodes in message flows, are never backed out or committed in batches under the control of the flow.

Figure 4-20 Transactionality of file processing

Message Flow

Not transactional

Transactional


4.3 Scenarios

Scenarios discussed in this section provide usage patterns for file processing (Figure 4-21). You can use a single pattern or a combination of different patterns to meet your requirements. The FileInput node and the FileOutput node can be used with any other node provided by Message Broker. Some usage patterns are introduced here and additional samples can be found in the Message Broker toolkit v6.1 Samples Gallery under technology samples.

Figure 4-21 File processing scenarios

4.3.1 Simple file transfer example

This sample illustrates using the FileInput and FileOutput nodes to read and write files, to propagate files as whole files and as records, and message parsing.

Whole file transferThe flow shown in Figure 4-22 takes a file as input from one directory and writes it identically to another directory. The Compute node between the FileInput node and the FileOutput node is optional. A Trace node can be used to provide useful output of the propagated data from the FileInput node.

Figure 4-22 Simple file transfer example

In this example, the file is sent as a whole file using the default message domain BLOB, with no parsing. Table 4-1 shows the properties specified in the FileInput and FileOutput nodes that determine where the file is read from and where it is written to.

Table 4-1 File processing node settings for whole file transfer

Transfer by recordTo change this flow so files are sent by records, select either the fixed length option or the delimiter option under the Records and Element tab. If the file should be analyzed by a parser,

File Input node parameter

values File Output node parameter

values

Basic tab: Input directory

your input directory Basic tab: Directory your output directory

Basic tab: File name or pattern


your file name or pattern


select Parser Record Sequence and choose the correct Message domain under the Input Message Parsing tab. For XML files use the XMLNSC parser domain.

Table 4-2 shows the settings used to propagate an XML file by records and to use message parsing.

Table 4-2 Property settings to transfer files by record

Figure 4-23 shows the processing flow. Note that when transferring records, you connect the End of Data on the FileInput node with the Finish File terminal on the FileOutput node.

Figure 4-23 Transfer by record

In this flow the following activities occur:

1. The FileInput node reads a file by name or by pattern from the defined file directory.

2. The FileInput node analyzes the file and optionally parses the file depending on the definitions (Records and Elements / Input Message Parsing)

3. The FileInput node determines the type of propagation (records based on the record detection settings and sends each record of the file via the out terminal.

4. The FileInput node sends End of Data after the last record.

5. The FileOutput node receives the records and writes them to the file system



values

Basic tab: Input directory

your input directory Basic tab: Directory your output directory



your file name or pattern

Records and Elements tab: Record detection

Parsed Record Sequence

Records and Elements tab: Record definition

Record is Unmodified Data

Input Message Parsing tab: Record domain

XMLNSC


This Parse timing property (Figure 4-24) controls when an input message is parsed. It is set on the Parser Options tab. Valid values are:

� On Demand� Immediate� Complete

Figure 4-24 FileInput node properties: Parse timing

4.3.2 Large file handling and bulk transfer example

Bulk transfer can be used to divide a file in smaller parts and send it with more than one propagation to one or more receiving nodes in the message flow. Use the settings in the FileInput node to set the fixed length record detection to a value between 1 byte and 100 MB. Use the default message domain, BLOB, under the Input Message Parsing tag.

Example: Divide a large file with 1 GB to 100 propagations (messages) of 10 MB each. Send the small files (10 MB each) to one or more receiving nodes in the message flow. See Figure 4-25.

Note: A warning sign is displayed in the top left corner of the FileInput node if the record detection is not set to whole file (under Records and Elements tab) and the End of Data terminal is not connected.

This warning sign also appears in the top left corner of the FileOutput Node if the record definitions are not set to whole file and the Finish File terminal is not connected.

Important: For performance reasons, be aware of the syntax analysis parser option timing. Performance of message flows can be improved by on demand parsing; an input message bit stream is parsed only as far as necessary to satisfy the current reference. This parameter is valid for MRM and XML (XMLNS, XMLNSC) parsers. The Immediate and Complete options both override partial parsing and parse the entire message and the message headers.


Figure 4-25 Large file processing

You can use the FileOutput node to receive the records of a file, as long as no message appears at the Finish File terminal, and build one file. In the FileOutput node Records and Elements tab, select Record is Unmodified Data for the Record detection setting to concatenate the record from each message unmodified to the file.

Table 4-3 shows the settings for a file transfer of a large file.

Table 4-3 FileInput and FileOutput node settings for transfer of a large file

4.3.3 Aggregator and splitter pattern example

The previous examples illustrate file transfer using a file as both input and output. The FileInput and FileOutput nodes are used in pairs. In these examples of aggregator and splitter patterns, the input or output is not necessarily a file (Figure 4-26).

Aggregator exampleIn the aggregator pattern, multiple input messages are aggregated into one file.

Example: Three MQInput nodes receive messages. Those messages are all written to the same single output file.

MessageBroker

File System or FTP Server

Large file 1GB Small file 10MB Small file 10MB. . .



values

Records and Elements tab: Record detection

Fixed Length Records and Elements tab: Record definition

Record is Unmodified Data (or Record is Fixed Length Data)

Records and Elements tab: Length (bytes)

10000000 Records and Elements tab: Length (bytes)

10000000, if Record detection is fixed length

Input Message Parsing tab: Record domain

default value


Figure 4-26 Aggregating messages into a file

In this example:

1. The MQInput nodes propagate messages to the Compute node.

2. The Compute node has to send a message to the Finish File terminal of the FileOutput node to close the file. The content of this last message is not important, as long as the Finish File terminal receives a message. Use ESQL to direct the messages and create the last message.

Example 4-1 Compute node setting

PROPAGATE TO TERMINAL 'out' DELETE NONE;PROPAGATE TO TERMINAL 'out1' DELETE NONE;

3. The FileOutput node closes the file and moves it from the mqsitransit directory to the output directory.

The following example (Figure 4-27) is taken from the Message Broker Samples Gallery technology samples. The FileBatchProcessingSampleFlowProject has three company branches that send their input to Message Broker. A Compute node counts the propagations and sends an End of Data message after the third data propagation.

Figure 4-27 FileBatchProcessingSampleFlowProject sample message flow


Example 4-2 shows the Compute node content.

Example 4-2 Compute node content

DECLARE messageCount SHARED INTEGER 0; CREATE COMPUTE MODULE FileAggrSampleBranchCompute CREATE FUNCTION Main() RETURNS BOOLEAN BEGIN SET messageCount = messageCount + 1; -- the third message is the last received so propagate the End of Data message -- to the Finish File terminal IF messageCount = 3 THEN SET messageCount = 0; RETURN TRUE; ELSE RETURN FALSE; END IF;

END; CREATE PROCEDURE CopyMessageHeaders() BEGIN DECLARE I INTEGER 1; DECLARE J INTEGER; SET J = CARDINALITY(InputRoot.[]); WHILE I < J DO SET OutputRoot.[I]= InputRoot.[I]; SET I = I + 1; END WHILE; END; CREATE PROCEDURE CopyEntireMessage() BEGIN SET OutputRoot = InputRoot; END; END MODULE;


Splitter patternIn the splitter pattern, a file is sent as multiple messages for output.

Example: A file is propagated to three MQOutput nodes. The Out terminal of the FileInput node propagates the same data three times to the message queues (Figure 4-28).

Figure 4-28 Splitter pattern

4.3.4 Content-based routing pattern example

The content based routing pattern example (Figure 4-29) is an extension to the splitter pattern. The Out terminal of the FileInput node propagates data to the Compute node and the Compute node makes a routing decision based on the received data. Several scenarios are possible, for example:

� The data is propagated to one MQOutput node depending on the content of the data.

� The data is changed (enriched) and sent to all MQOutput nodes.

Example 4-3 shows the content of a Compute node that routes the file to one MQOutput node based on the value of the customerNumber field.

Example 4-3 Compute node

IF InputRoot.XMLNSC.OrderMsg.customerNumber = '1' THEN PROPAGATE TO TERMINAL 'out' DELETE NONE; END IF;


Figure 4-29 Content-based routing pattern

4.3.5 File processing nodes used with WebSphere MQ File Transfer Edition

WebSphere MQ File Transfer Edition (MQ FTE) V7.0 provides centralized management and monitoring of all file transfers. MQ FTE needs a coordination queue manager with MQ version 7 but does support agents on MQ version 6.

MQ/FTE provides the following features:

� Full audit ability to meet regulatory compliance� Full transfer history to meet internal audit requirements� Comprehensive ACL based security

Figure 4-30 shows the architecture and the relationship between MQ FTE and Message Broker. MQ FTE does the reliable file transfer with messages, and Message Broker does the file processing, for example with the FileOutput node.


Figure 4-30 Using WebSphere Message Broker and MQ FTE

In this example, files from several branches could be transferred according to a defined schedule with MQ FTE to a Message Broker queue. The data on the queue could be processed and written to a file.

This file transfer is file based versus message based. Future support might be provided for message-based transfer.

4.3.6 File Adapter for z/OS sequential files

While the Broker V6.1 File nodes can operate on z/OS, they are restricted to UNIX-style files in the UNIX System Support environment (USS) (that is, files in the Hierarchical, z/OS, Network, and Temp File Systems: HFS, ZFS™, NFS, and TFS). They cannot use conventional record-oriented z/OS sequential files.

The IA11 SupportPac provides support for QSAM files on z/OS, and can exploit regular MVS datasets. It can be used to integrate batch applications using message flows. The File Adapter (Figure 4-31) plug-in nodes add the capability of reading and writing messages from and to z/OS sequential files (QSAM data sets).

Figure 4-31 File Adapter

Coordination QMPub/SubWMQ V7

MessageBroker

V6.1

WMQV6+

MessageBroker

V6.1

WMQV6+

WMQFTEAgent 1

WMQFTECommand

Agents

Publish / Submitnew transfer

request

WMQFTEAgent 2

WMQMessage Channel

Agents

WMQ/FTE Explorer

File Transport

File Processing


You can find information about the SupportPac at:

http://www-01.ibm.com/support/docview.wss?rs=171&context=SSFKSJ&dc=DA400&uid=swg27007197&loc=en_US&cs=UTF-8&lang=en&rss=ct171websphere#5

The File Adapter plug-in nodes can be used in the same way as the file processing nodes. The File Adapter plug-in nodes are designed to be used in message flows that represent the following scenarios (Figure 4-32):

� Read records from an input file, propagate the records as messages, transform the messages, and write them to one or more output files.

� Read records from an input file, propagate the records as messages, transform the messages, and put them on WebSphere MQ queues.

� Get WebSphere MQ messages from a queue, transform the messages, and write them to one or more output files.

Figure 4-32 IA11 File adapter nodes

The File Read node reads from a sequential file and propagates each record as a message through the Out terminal. The input file process is triggered when an open input file action message arrives at the Action terminal. The File Write node receives data messages on the In terminal and writes them as records in an output file (QSAM data set in z/OS). Status messages are propagated to the Status terminal when an output file is opened or closed.

The Support Pac IA11 with the File Adapter nodes can be installed on the following Message Broker versions:

� WebSphere Message Broker V6.1 with fix pack 1 or above (z/OS V1R7 and above).

� WebSphere Message Broker V6.0 with fix pack 1 or above (z/OS V1R5 and above).

The Message Broker Support Pac IA13 provides five built-in message-processing nodes that can used in a message flow to read, write, delete, and update records in VSAM (Virtual Storage Access Method) data sets.

4.4 References and additional information

For additional information, see:

� File handling in WebSphere Message Broker V6.1:

http://www.ibm.com/developerworks/websphere/library/techarticles/0806_mcmullan/0806_mcmullan.html

� Message modeling and parsing enhancements in WebSphere Message Broker V6.1:

http://www.ibm.com/developerworks/websphere/library/techarticles/0810_hanson/0810_hanson.html






Chapter 5. EIS adapter support in WebSphere Message Broker V6.1

WebSphere Message Broker V6.1 now supports three JCA-based WebSphere application adapters for connectivity to the following EIS systems:

� SAP� Siebel� PeopleSoft

A fourth adapter, TwineBall, is also included for demonstration purposes.

The application adapters are packaged with the Message Broker Toolkit and included in the palette as nodes. While you can develop message flows with the new nodes, a license for the adapters is required to deploy them. In addition, JAR and dll files from the EIS provider are required to be made available to the broker before deploying a message flow using these new nodes.

5


5.1 EIS adapter overview

WebSphere Message Broker V6.1 supports inbound (input) and outbound (request) connectivity to three EIS systems, SAP, Siebel, and PeopleSoft. Inbound scenarios are those where events are coming from the EIS system to the message flow. Outbound scenarios are those where requests are being sent from the message flow to the EIS system.

Figure 5-1 EIS Adapter inbound and outbound message flows

Support includes input and request nodes to provide the adapter functionality and a wizard to assist in building the elements required for connectivity. The wizard implements Enterprise Metadata Discovery (EMD) for key data structure discovery and accelerated message set generation. The use of the native message broker tree provides high performance access to the EIS using WebSphere Adapters.

5.2 Adapter nodes

In this section we describe the nodes used by WebSphere Message Broker V6.1 for inbound (input) and outbound (request) scenarios.

EIS

Message flows

EIS


5.2.1 Introduction

WebSphere Message Broker V6.1 provides support for EIS adapters with the following nodes for inbound (input) and outbound (request) scenarios:

� SAP adapter nodes:

– SAPInput– SAPRequest

� Siebel adapter nodes:

– SiebelInput– SiebelRequest

� PeopleSoft adapter nodes:

– PeopleSoftInput– PeopleSoftRequest

� TwineBall adapter nodes:

– TwineballInput– TwineballRequest

TwineBall input and request nodes are provided as sample nodes with their own EIS for learning about how the WebSphere Adapter nodes work.

5.2.2 Incorporating EIS adapters into a message flow

Incorporating an adapter into a message flow involves the following steps.

Step 1: Discovery of EIS objects and servicesAn adapter connection wizard is provided to discover metadata information from the EIS system. This wizard complies with the Enterprise Metadata Discovery specification.

The message flow developer uses the wizard to connect to the EIS system and build the artifacts for use in a message flow. The following information is fed into the wizard to determine how the artifacts are created:

� The interaction pattern (inbound or outbound) for connection.

� The connection properties for the EIS server, for example, host name, user ID, password.

� The interface to use. The options are specific to the type of adapter.

� The business objects or services in the EIS system to access. The wizard discovers the objects and services available and allow you to select from a list.

� The operations to perform on those objects or services. For example, update, create, and delete operations. The operations available depend on the adapter.

The wizard imports the metadata and creates the artifacts needed to build a message flow.

� Message flow project containing a message flow.

� The message set project containing:

– The message set file (.mset) and message definitions (.mxsd) that describe the messages exchanged with thee EIS system

– The adapter component required to access the EIS system (inbound or outbound).

Chapter 5. EIS adapter support in WebSphere Message Broker V6.1 99

For example, Figure 5-2 shows the artifacts generated for the TwineBall adapter for an inbound scenario.

Figure 5-2 Artifacts generated for the TwineBall inbound adapter

It includes the message set projects required to interact with the EIS data and the adapter component file. This artifact generation effectively takes the place of the majority of the node configuration that you would normally do with other node types. The adapter components created by the wizard are used during message flow development to add the adapter nodes to a message flow, and are basically pre-configured based on the input to the wizard.

Step 2: Incorporate the adapter node into the message flowUsing the artifacts generated in Step 1, the message flow developer incorporates the adapter into a message flow by dragging and dropping the adapter component to the flow. This creates the appropriate adapter input or request node and associates the message set and adapter component with it.

When you create a new input node in this manner, the node is wired to a subflow node. The subflow node contains a route to label node, which forwards the incoming message to the appropriate label node. The number of label nodes available depends on the number of operations you choose when configuring the adapter.

You can change configuration parameters for the input and request nodes in the message flow. For request nodes, the EIS method to invoke and the location of the output data location can be configured. For input nodes, the $LocalEnvironment/Adapter/MethodName variable is set to the name of the business method corresponding to the enterprise information system event that triggered the message delivery.


Step 3: Make the provider JAR files available to the brokerThe administrator configures the broker so that it has access to the EIS provider JAR files and native libraries. The mqsichangeproperties command can be used to accomplish this task.

Step 4: Create the broker archive (BAR) file and deploy it to the brokerThe deployment artifacts for the message are put in a BAR file and deployed to the broker. The artifacts include the message flow, the message set, and an adapter component.

5.3 Scenarios

Here are three common uses for the EIS adapters:

� Scenario 1: Allow legacy applications to interact with an EIS system.

WebSphere Message Broker supports a variety of legacy systems over WebSphere MQ. Integration can be achieved through a message flow using WebSphere MQ nodes to communicate with the legacy systems and the adapter nodes to communicate with the EIS systems.

� Scenario 2: Enable an EIS system as a Web service.

Web services clients can access an EIS system via a message flow. HTTP or SOAP nodes provide inbound access to the message flow for the clients. The adapter nodes provide outbound access to the EIS systems.

� Scenario 3: Enable integration between two EIS systems.

Two EIS systems can be synchronized through a message flow. An update to one generates an event that starts a message flow. The message flow makes corresponding updates to the second EIS system.

5.3.1 Samples Gallery

The Samples Gallery contains an SAP example with two message flows to illustrate the use of an adapter. The samples are located in Technology samples → Message Broker → Transports and connectivity → SAP connectivity.

The first sample illustrates an inbound scenario where a message flow is used to receive IDocs from the SAP Material Master. The data is sent to an MQ output queue for processing by another message flow or application (Figure 5-3).

Figure 5-3 Inbound scenario


The second sample illustrates an outbound scenario where a message flow is used to create a customer record in SAP and afterwards, to update and retrieve the customer details (Figure 5-4).

Figure 5-4 Outbound scenario

1. A message is sent to the MQInput node containing fields necessary to create a Customer object in SAP.

2. The first SAP Request node (Create) invokes a Customer Create BAPI® (BAPI_CUSTOMER_CREATEFROMDATA1) and SAP returns the unique identifier of the Customer object created.

3. A Compute node (Set Update Msg) uses the returned identifier (customer number) and constructs a message that allows the new Customer to be updated.

4. The second SAP Request node (Update) sends this data to a Customer Update BAPI (BAPI_CUSTOMER_CHANGEFROMDATA1) and SAP sends back a return code.

5. A Compute node (Set Retrieve Msg) uses the Customer identifier to construct a message that requests SAP to return the updated Customer object.

6. The final SAP Request node (Retrieve) uses this data to invoke a Customer Retrieve BAPI (BAPI_CUSTOMER_GETDETAILS1) and SAP returns the Customer object, which is output to an MQ queue as an XML message.

If there is a problem with the flow, the original message header and exception list data are put into an XML message and sent to a failure MQ queue.

5.3.2 Using the SAP adapter

This section takes a closer look at the SAP adapter in order to illustrate the features available.

The adapter supports ALE and BAPI flows on inbound and outbound connections. An Application Link Enabling (ALE) interface is used to exchange data between SAP and non-SAP systems. Business Application Programming (BAPI) is an interface that provides access to processes and data in business application systems such as R/3. The SAP adapter can invoke remote enabled BAPIs, either the standard or the custom BAPIs.


SAP inbound operationsThe SAP Adapter is capable of connecting to an SAP EIS system and listening for events. The adapter does this through the SAP JCO APIs provided by SAP. Currently, version 2.1.8 of the SAP JCO is supported by the adapter. After the event is sent by SAP, the adapter can read the events and convert them from native SAP EIS format to a format for processing in the message flow.

As part of the adapter connection wizard, the EIS objects in SAP are discovered and message sets are generated based on the object structures. The SAP Adapter can connect and retrieve IDOCs, extract the data from the IDOC, and populate a message to pass on to the next node in the flow.

An SAPInput node is used to read the data from SAP. The various interfaces of SAP that are supported by the SAPInput Node are described in the Inbound scenarios section below.

Inbound scenarioIn this scenario, a message flow is used to receive IDocs from the SAP Material Master. The data is sent to an MQ output queue for processing by another message flow or application.

In all cases of Inbound scenarios, the data that is received by the SapInput node is sent to the consumer in a formatted form like a fixed structure or a structure that matches the data sent by SAP.

The SAPInput node is wired as shown in Figure 5-5. The output of the adapter is sent to an MQOutput queue.

Figure 5-5 SAP inbound scenario

The properties of the SAPInput node (Figure 5-6) can be viewed and modified by double-clicking on the icon in the message flow.


Figure 5-6 SAPInput node properties

The following interfaces are supported as part of the SAPInput node.

AEPThe SAPInput node uses the Advanced Event Processing (AEP) interface polling mechanism to retrieve events from the event table in the SAP system. These events are processed by the adapter and sent to the message flow. After the events are retrieved and processed, they are archived in the SAP system.

A regular time interval is specified, during which the adapter checks for arrival of new events and keeps polling the SAP system as per the time interval specified. The time interval is specified as part of the Adapter Connection Wizard run for Inbound interfaces.

ALEThe ALE interface can be selected when a push model of inbound processing is required. When ALE is selected, the structured IDoc is sent out by the adapter. This is usually done when the downstream component in the message flow expects data in a structured format.

The adapter starts listener threads that listen for IDOC events on a particular RFC program ID of SAP. The moment the IDOC arrives at the destination configured on SAP, the adapter processes the events and packages the data into the discovered message format file and sends it across to the end point.

The ALE received by the SapInput node is populated into the message definition of the IDOC.


ALE pass through IDOCThis interface is selected when the integration scenario only requires the raw IDOC byte stream and not the structured IDOC format. The adapter packages the IDOC contents in a hex binary stream and packages it into the discovered object structure before sending it to the end point.

The wiring is the same as that of the ALE case. The only difference is that the structure of the data emitted out is the same, that is, a byte stream.

BAPI or the Synchronous call back interfaceThis interface is used to execute BAPIs on the inbound. In the case of Message Broker, this feature executes BAPIs asynchronously via the qRFC and tRFC protocol. This feature is available as of Message Broker runtime version 6.1.0.3 onwards. The capability to execute BAPIs synchronously in Message Broker is not available.

In this case the adapter does not wait for the BAPI to be executed by the other component (for example, another SAP System).

SAP outbound operationsThe outbound mode of operation can be used in scenarios where data has to be loaded to or retrieved from SAP.

For all Outbound requests, the Adapter receives data from an external source and then suitably updates or retrieves the data into the SAP system. The adapter transforms the message tree into the JCA CCI record that it requires to perform the outbound operation. The format of the message is something that gets discovered as part of the discovery when the Adapter connection wizard is run.

The SAPRequest node supports several outbound scenarios that are described in the following section.

SAP outbound scenariosIn this scenario, a message flow is used to create a customer record (business partner) in SAP and afterwards, to update and retrieve the customer details (Figure 5-7).

Figure 5-7 SAP outbound scenario


The SAPRequest node properties () can be viewed and modified by double-clicking on the icon in the message flow (Figure 5-8).

Figure 5-8 SAPRequest node properties

This scenario can be implemented using any one of the supported interfaces, as we discuss next.

Advanced Event Processing (AEP)In this scenario the SAPRequest node is used to fetch data from SAP tables. Operations such as Create, Update, Delete, and Retrieve can be performed on a table. The adapter requires input regarding where the data should be fetched from. This is provided by the caller of the SapRequest node.

ALEUsing the ALE interface, the adapter sends IDOCs to the SAP system by discovering the IDOC as part of the connection wizard's Outbound flow.

ALE pass-through IDOCUsing the ALE pass-through IDOC interface, the adapter sends IDOCs to the SAP system. The data is in the form of a byte stream as opposed to a structured content.


BAPIUsing the BAPI interface, the SAPRequest node executes an RFC enabled SAP BAPI. The data required to execute the BAPI is supplied to the adapter via the message set. The adapter then executes the BAPI. If there is a response, the adapter converts it back into business object format, and sends it to the broker.

An MQInput node is used to feed the input data to the SAPRequest node. This input data, in fact, consists of the import parameters that the BAPI expects the adapter to provide. If the BAPI has any export parameters (return values), they are sent back to the adapter from SAP and the adapter populates these return values into the response business object, which is then sent to the MQOutput Queue.

With the 6.1.0.3 version of the Adapter, it can execute BAPIs asynchronously by using the qRFC protocol.

BAPI work unitWhen there is a requirement to execute a set of BAPIs in a single request, one after the other, this feature is used. The adapter also provides the option to have a commit call at the end of all the BAPIs so that the changes are permanently committed to the EIS. For example, if there are 2 BAPIS and the second one expects a value that was created in the first one, then the first BAPI sets these values in a global variable. Then the second BAPI reads this value from that global variable, and then finally the commit statement is issued. In the work unit message flow, a series of BAPIs are executed as part of a single request and all those BAPIs have to be selected as part of the wizard run.

Query Interface for SAP Software (QISS)The Query interface for SAP Software retrieves data from specific SAP application tables. It can return the data or check for the existence of the data. You can use this type of interaction with SAP if you need to retrieve data from an SAP table without using an RFC function or a BAPI.

The message flow is the same as that of the BAPI flows. The input received contains selection criteria with which the adapter fetches data from the SAP data tables.


Chapter 6. Security support in WebSphere Message Broker V6.1

In V6.0 the emphasis in security is on authorization to access broker runtime resources, and authorized deployment of developmental resources to broker and message transport security involving SSL authentication or controlled proxy access. Access Control Lists (ACLs) are defined at the configuration manager. With SSL transport security, the stream of data passed between point-to-point is protected in its totality and is not differentiated for individual messages, because typically all the data is encrypted or authorized.

With Message Broker V6.1, message flow level security can be implemented. This allows identity-based control processing of the individual messages in a message flow.

6


6.1 Identity-based authentication and authorization

The identity is a piece of information that can uniquely identify an individual or an object. It is usually located within the message header. The security manager is used to configure the identity based end-to-end processing of incoming messages. The identity can be authenticated as is, or mapped to an alternate identity using an external security provider. The resulting identity is used for authorization to access the message flow. The alternate or original identity can be propagated with the outbound message. These functionalities are configured via new security profiles created by the broker administrator. The profiles are accessed by security manager at run time.

LDAP (Light Weight Directory Access Protocol) servers and the Tivoli Federated Identity Manager (TFIM) are supported by Message Broker for this centralized security framework. An LDAP server can be used for authentication and authorization. TFIM can be also be used for authentication and authorization, and in addition, for identity mapping. LDAP and TFIM are the policy decision points (PDP), where the control and policy decisions in response to a request are taken.

Three input nodes of the Message Broker, the MQInput, HTTPInput and SOAPInput nodes, are the first point of contact for incoming messages. This is where the security profile can be configured to call the security manager. These input nodes act as the policy enforcement point (PEP) for a message flow, by unpacking the necessary attributes from the incoming message and making them available to the PDP entities for making the policy decisions.

Policy sets and policy bindings are repositories that need to be created on a broker to provide WS-security for Web services. Message Broker provides Web services support via SOAP nodes. These nodes need to be configured with the appropriate policy set and binding information to implement Web services security.

Figure 6-1 illustrates the available security enforcement (PEP) and configuration repository (PDP) locations for a broker.

Figure 6-1 Security enforcement overview

Input Nodes

SecurityManager

• Keystore• Truststore

• Policy Sets• Policy Set Binding

AuthenticationServer

TFIM or LDAP

MappingServerTFIM

AuthenticationServer

TFIM or LDAP

Policy Decision Point(PDP)

Policy Enforcement Point(PEP)


6.1.1 Security profiles

The new security manager in Message Broker V6.1 can extract the identity from the input message and authenticate it within the broker purview, instead of delegating it to an external agency like DataPower or another security manager. The security manager can generate a security profile that enables the message flows to take control of the individual message processing based on the message identity.

Thus creation of a security profile is the first step in implementation, as this defines how the message flow handles its security processing activity. The security profiles can be created using either the mqsicreateconfigurableservice command or from the Security Profiles window opened from the Domain view in the Broker Administration perspective of the Message Broker Toolkit (Figure 6-2).

Figure 6-2 Open the Security Profiles window to define the security profiles

Security profile configuration involves the use of one of the two external security providers, an LDAP server or TFIM. IBM Tivoli Directory Server, OpenLDAP or Microsoft Active Directory® are the LDAP servers that Message Broker currently supports. TFIM 6.1 is required for any TFIM specific security profile configuration. The Default profile that comes with the installation of WebSphere Message Broker is useful to extract and propagate an identity without any security enforcement or mapping (Figure 6-3).

Chapter 6. Security support in WebSphere Message Broker V6.1 111

Figure 6-3 Defining security profiles

Alternatively, the mqsicreateconfigurableservice command can be used to create a security profile that uses LDAP for authentication, authorization, or both.

mqsicreateconfigurableservice WBRK61DEFAULTBROKER -c SecurityProfiles -o LDAP -n authentication,authenticationConfig,authorization,authorizationConfig -v "LDAP,\"ldap://ldap.acme.com:389/ou=sales,o=acme.com\",LDAP, \"ldap://ldap.acme.com:389/cn=All Sales,ou=acmegroups,o=acme.com\""

For example, the following command can be used to create a security profile that uses TFIM for mapping:

mqsicreateconfigurableservice WBRK61DEFAULTBROKER -c SecurityProfiles -o TFIMProfile -n mapping,mappingConfig -v TFIM, http://tfimserver.mycompany.com:9080

The TFIM or LDAP server URLs should be identical when creating the security profile, if one server is used for multiple operations (authentication, authorization, and mapping).

To view the values in a security profile (Figure 6-4), use one of the following commands:

� mqsireportproperties <broker_name> -c SecurityProfiles -o <SecurityProfile> -r

� mqsireportproperties <broker_name> -c SecurityProfiles -o allReportableEntityNames -r


Figure 6-4 Viewing a security profile

The following command can be used to modify the property values in a security profile:

mqsichangeproperties <broker_name> -c SecurityProfiles -o <profile_name> -n <property_name_list> -v <property_value_list>

The following command can be used to delete a security profile:

mqsideleteconfigurableservice <broker_name> -c SecurityProfiles -o <profile_name>

The security profile is configured in the broker archive (BAR) file (Figure 6-5). If there is an entry in the Security profile property, then it indicates that a runtime security is configured.

Figure 6-5 Security profile information in the BAR file

>mqsireportpropertiesWBRK61_DEFAULT_BROKER –c SecurityProfiles –o AllReportableEntityNames -r

SecurityProfilesDefault_Propagationauthentication='NONE'authenticationConfig="authorization='NONE'authorizationConfig="keyStore='Reserved for future use'mapping='NONE'mappingConfig="passwordValue='PLAIN'propagation='TRUE'trustStore='Reserved for future use'

SecurityProfile_1authentication='LDAP'authenticationConfig='ldap://localhost:389/ou=users,o=ibm.com?uid'authorization='LDAP'authorizationConfig='ldap://localhost:389/cn=wmb,ou=groups,o=ibm.com'keyStore='keystore.jks'mapping='TFIM'mappingConfig='http://localhost:9080'passwordValue='PLAIN'propagation='TRUE'trustStore='Reserved for future use'

BIP8071l: Successful command completion.


6.1.2 Message identity processing at input nodes

The security manager extracts the identity information from the input message and saves it in eight properties in the properties folder of the message tree structure. These properties define two identities in the broker: source and mapped. For both the source and mapped identities, values are held for Type, Token, Password, and IssuedBy properties. The source identity information could be in a message header or in the message body itself, or a mixture of the two (Figure 6-6).

Figure 6-6 Message identity tokens

� The Type property defines the format of the token. Valid values are Username, Username and Password and X.509 Certificate. The Type property can also have a value of Transport Default which indicates the default for the transport should be used (Username for WebSphere MQ and Username and Password for HTTP).

Username and Username and Password tokens are supported for LDAP authentication and authorization. TFIM supports Username, Username and Password and X.509 Certificate tokens for authentication and authorization, while Username to Username and X.509 Certificate to Username are supported for identity mappings.

� The Token property holds the actual token, such as username or certificate.

� The password field contains the associated password for a Username and Password token.

� The IssuedBy field defines where the Token was created. For example, for an X.509 Certificate this could be "IBM" (the Common Name of the Certifying Authority). For Username and "Username and Password" formats, it is transport specific unless the IssuedBy property is set on the node.

The properties of the source identity are set on the input node using the Security properties tab, or can be set using a Compute node. However these values are used only when a security profile is present in the input node.

Authentication

Identity Mapping

Authorization

Properties

IdentitySourceType

IdentitySourceToken

IdentitySourcePassword

IdentitySourceIssuedBy

IdentityMappedType

IdentityMappedToken

IdentityMappedPassword

IdentityMappedIssuedBy


From a debugger snapshot, you can see how the field values in the input message are transmitted into message tree by appropriately configuring the security properties on the MQInput node. A subset of Security Identity Propagation sample from the Samples Gallery is shown in Figure 6-7.

Figure 6-7 Message identity mapping on input nodes


6.1.3 Message identity processing at output and request nodes

If the Security Profile property is configured on output or request nodes in the BAR file, the identity fields can be propagated to the outgoing message. Thus MQOutput, HTTPRequest, SOAPRequest and SOAPAsyncRequest nodes support identity propagation.

6.2 WS-Security

In this section we introduce WS-Security and describe its functions.

6.2.1 Introduction

WS-Security is a comprehensive security specification based on XML Signature and XML Encryption as fundamental components. The OASIS draft defines a qualitative security model for SOAP messaging and hence, the WS-security mechanism via message integrity, confidentiality and single message authentication:

http://www.oasis-open.org/specs/index.php#wssv1.1

SOAP is an XML message with an envelope-like structure enwrapping an optional header and a mandatory body (Figure 6-8). The envelope is a container to hold the XML data in it and can be carried by variety of transport protocols. It is this layer of the SOAP message that prevents applications from worrying about the transport. The SOAP body contains the message payload or the business information that is transmitted between the applications. The SOAP headers usually contain the information about the SOAP message, helpful for managing and securing the message. WS-Security definitions are incorporated within this SOAP envelope, particularly in its header. The content of the header and body is typically controlled by WSDL.

Figure 6-8 WS-Security

Figure 6-9 shows how the WS-Security specifications can be packaged within the SOAP skeleton. The SOAP envelope is presented within the outermost <Envelope> element, containing the namespace URL for the SOAP. In this outermost envelope element, there are two SOAP sub-elements, namely Header and Body. WS-Security elements are defined under the additional security element <wsse:Security>, either in the existing or a new SOAP Header element.

+SOAP Envelope SOAP Envelope

SOAPMessage

WS-SecurityExtension

SOAPMessage WS-SecurityExtension



Figure 6-9 SOAP message with WS-Security

SOAP message processing architecture involves accessing any service that the underlying network transport protocols (like HTTP, SMTP, TCP or WMQ) provide. This is done with SOAP binding specifications.

The SOAP Web service messages that pass through the SOAP nodes are supported by the WS-Security specifications. WS-Security guarantees their integrity (via XML signature) and confidentiality (via XML encryption and authentication).

The large family of WS-Security standards stack built on SOAP is summarized in Figure 6-10. The layers on top of the WS-Security are specifications for interoperability, trust and integration. Only a limited subset of these specifications (highlighted) are supported by the Message Broker in the current release. Of the Username and X.509 Certificate Token standards of the OASIS draft, the Username token is not supported for encryption, decryption, signing, or verifying configurations. However it can be used for authentication and authorization.

SOAP message with WS-Security:

<Envelopexmlns="http://schemas.xmlsoap.org/soap/envelope/"><Header>

<wsse:Security<!.. ws-security namespace ..!>

xmlns:wsse="http://schemas.xmlsoap.org/ws/2003/07/secext"><!.. Security Information for Authentication or

XML Signature or XML Encryption is included here..!>

<!.. Username token for Authentication looks like this..!><wsse:UsernameToken wsu:ID="myToken">

<wsse:Username>IBM</wsse:Username><wsse:Password>p@$$w0rd</wsse:Password>

</wsse:UsernameToken><!...XML Digital Signature entries looks...!>

<wsse:BinarySecurityToken EncodingType="wsse:Base64Binary">AllGQtCC7ZxO5tlgerPcid1z ... [truncated]

</wsse:BinarySecurityToken><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">....signature data....</ds:Signature>

<!...XML Encryption entries looks like...!><xenc:EncryptedData xmlns:dsig="http://www.w3.org/2000/09/xmldis#">

<xenc:EncryptValue>akdfaknqerandfauydfrajndfh3k973...(Truncated)</xenc:EncryptValue></xenc:EncryptData>

</wsse:Security></Header><Body> ............. </Body>

</Envelope>


Figure 6-10 WS-Security standards

For additional restrictions that the broker imposes while implementing the WS-Security, refer to the WebSphere Message Broker information center article at:


The WS-Security implementation on all the SOAP nodes of the Message Broker is done by defining policy sets and bindings.

Message Broker can act like a service provider or a consumer. The SOAPRequest and SOAP AsyncRequest/SOAP AsyncResponse nodes are used when broker is acting as a consumer or as a message initiator. The SOAPInput and SOAPReply nodes are used when the broker is the service provider or message recipient. The partner server or client for the broker can be another broker or an external provider or consumer other than a broker.

Figure 6-11 illustrates how WS-Security is integrated into these provider and consumer scenarios. Inbound and outbound messages are signed and encrypted.

� In a service requestor scenario, the initiator uses the recipient's public encryption token to encrypt the message, and its own private signature token to sign the message. The recipient uses its own private encryption token to decrypt the message and initiator's public signature token to verify the signature.

� In the case of a service response scenario, the recipient uses the initiator's public encryption token to encrypt the message, and its own private signature token to sign the message. The initiator uses its own private encryption token to decrypt the message and the recipient's public signature token to verify the signature.

WS-Security (framework)

SOAP Message Layer

XML Encryption

XML Signature

X509

Username

Kerberos

Mobile

SAML

XrML

WS-PrivacyWS-Policy WS-Trust

WS-AuthorizationWS-SecureConversation WS-Federation



Figure 6-11 WS-Security in service provider and consumer scenarios

6.2.2 WS-Security example

In this section we use the Addressbook sample in the Samples Gallery to demonstrate WS-security implementation. In this example, message integrity is obtained using RSA cryptography digital signature to sign the body. Message confidentiality is achieved with the encryption of the body, signature, and signature elements using the WS-Security specifications.

Initiator Recipient

RecipientEncryption

Token

Public

InitiatorSignature

Token

Private

InitiatorEncryption

Token

Private

RecipientSignature

Token

Public

RecipientEncryption

Token

Private

InitiatorSignature

Token

Public

InitiatorEncryption

Token

Public

RecipientSignature

Token

Private

Encryption

Signature

Encryption

Signature

WebSphereMessage Broker

SOAPAsyncRequest

SOAPAsyncResponse

SOA

P R

eque

st

WebSphereMessage Broker

SOAP Input

SOAP Reply

Client orConsumer

Server orProvider


The example has both a consumer and a provider message flow, shown in Figure 6-12.

Figure 6-12 Address book example message flows

The SOAP input node of the provider flow verifies and decrypts the incoming message as per the policy set and policy binding configuration definitions. The subsequent nodes in the flow process the un-encrypted message. The SOAPReply node encrypts and signs the appropriate parts of the message.

The SOAPRequest node of the consumer flow packages the outgoing request message with appropriate encryption and signature as per the WS-security standards.

Setting up the keystore and truststoreBefore deploying any message flows that use WS-security, you must configure a keystore or a truststore. Message broker supports Java Keystore (JKS) for the trusted certificates and private or public Key material stored in Truststore or Keystore locations. A broker can be configured to use one keystore and one truststore. Usually the private and public key certificates (PKCs) are stored in the keystore location, while trusted root certificate authority (CA) certificates that are used for authenticating the inbound public key certificates.

Keytool or ikeyman tools that come up with WebSphere Message Broker are helpful in administering the keystore files.

Displaying a keystore fileYou can display the contents of a keystore file using the following command:

keytool -list -keystore <full-path>/<keystore filename> -storepass <password> -v

Where:

� <full-path> is the directory where the server.keystore or client.keystore files are located

� <keystore filename> is the name of the file

� <password> is the keystore password.

Provider

Consumer


Associating a truststore or keystore to an execution groupYou can associate the truststore or keystore files to an execution group using the following three mqsichangeproperties commands:

� mqsichangeproperties <broker_name> -e <Execution_Group> -o ComIbmJVMManager -n [truststoreFile | keystoreFile] -v <Server or Client truststore or keystore file Location>

� mqsichangeproperties <broker_name> -e <Execution_Group> -o ComIbmJVMManager -n [truststoreType | keystoreType] -v JKS

� mqsichangeproperties <broker_name> -e <Execution_Group> -o ComIbmJVMManager -n [truststorePass | keystorePass] -v <Execution_Group>::password

Associating a truststore or keystore to a brokerInstead of associating the files to each execution group, you can set up keystore and truststore files at the broker level using the following commands:

� mqsichangeproperties <broker_name> -o BrokerRegistry -n brokerKeystoreFile -v <full-path/keystore file>

� mqsichangeproperties <broker_name> -o BrokerRegistry -n brokerTruststoreFile -v <full-path/truststore file>

Displaying keystore and truststore settingsTo display the keystore or truststore settings (Figure 6-13) at the broker or execution group level, use the following commands:

� mqsireportproperties <broker_name> -o BrokerRegistry -a

� mqsireportproperties <broker_name> -e <Execution_Group> -o ComIbmJVMManager -a

Figure 6-13 Display of truststore and keystore settings

ComIbm.JVMManageruuid='ComIbmJVMManager'userTraceLevel='none'traceLevel='none'userTraceFilter='none'traceFilter='none'jvmVerboseOption='none'jvmDisableClassGC='false'jvmNativeStackSize='-1'jvmMinHeapSize='33554432'jvmMaxHeapSize='-1'jvmDebugPort='0'keystoreType='JKS'keystoreFile='C:\keystores\server.keystore'keystorePass='default::password'truststoreType='JKS'truststoreFile='C:\keystores\server.keystore'truststorePass='default::password'

BIP8071I: Successful command completion.


Setting passwords to access the keystore and truststorePasswords are required to access the keystores and truststores. The location of these passwords can be set at the execution group level or broker level.

To use these passwords at the broker level, use the following command:

mqsisetdbparms <broker_name> -n brokerKeystore::password -u <userID> -p <password>

Where userID can be any name and need not require to access the keystore.

In the sample, the provider flows are deployed to default execution group and the consumer flow is deployed to the EX1 execution group. To use the passwords at the execution group level for these flows, use the following commands.

� mqsisetdbparms WBRK61DEFAULTBROKER -n default::password -u temp -p server

� mqsisetdbparms WBRK61DEFAULTBROKER -n EX1::password -u temp -p client

The private keys in the keystore can have their own individual passwords. These can be configured based on alias names that are specified for the key in the policy sets and binding editor. If a key password based on the alias is not found, the keystore password is used. The alias Key password can be updated using the command:

mqsisetdbparms <broker_name> -n brokerTruststore::keypass::encKey -u <userID> -p <password>

Creating the policy set and policy binding filesWS-Security within Message Broker is configured by creating Policy Set and Policy Set Binding files. The policy set is the container for the WS-Security policy type. The policy set binding is associated with a policy set and contains the information that is specific to the environment and platform such as keys. These files are used to define:

� Authentication for both UserName Token and X.509 certificates� Asymmetric encryption for confidentiality� Asymmetric signature for integrity.

Creating policy setsThe easiest way of putting all this configuration information together in a Policy Set is by using the Policy Set editor. This editor can be opened by selecting the Open Policy Sets option in the context menu for the broker in the Domains view.

A default policy set and policy set binding with the name WSS10Default are defined with the broker installation. These default policy set and binding are configured for a Username Authentication token. Because these default settings are non-editable, you can generate a new policy set and binding by clicking the Add button on the Policy Set Editor (Figure 6-14).


Figure 6-14 Defining a new policy set and binding

After the policy set is created, it can be configured to define the authentication tokens and the parts of the message to be encrypted and signed for inbound and outbound messages. Figure 6-15 shows the sub-menu options that are available for the newly added policy.

Figure 6-15 Menu options for the policy configuration

Token Name, SOAP Message, WS-Security VersionParameters are defined for

UserName and X.509 authentication tokens

Selects message Level Protectionto enable encryption and signing in this policy

Defines parts of the message to be encryptedand signed


Creating policy set bindingsA policy set binding must be associated with an existing policy set. In the example, the WSSPolicy policy set is associated with WSConsumer policy set binding (shown in Figure 6-16) for consumer SOAP nodes. The same policy set is associated with the WSProvider policy set binding (not shown in the figure) for the provider SOAP nodes.

Figure 6-16 Policy set bindings for consumer type SOAP nodes

As an example, Figure 6-17 shows the binding settings in the provider policy set.

Figure 6-17 Policy set binding settings

The encryption or signing tokensare defined in the policy set

for the part of the protected message

Key and authentication tokensin the associated policy set


The administrator can edit, import or export, and save policy sets and bindings, with the help of Policy Set editor, the mqsichangeproperties command, or using the configuration manager Proxy API Exerciser.

Displaying policy sets and policy set bindingsThe policy sets and policy set bindings that are available for a Message Broker can be displayed on broker command console using the mqsireportproperties command, as shown in Figure 6-18.

Figure 6-18 Displaying the policy set and policy set bindings

The configuration details of the Policy Set and Policy Set Binding can be viewed using the following commands:

� mqsireportproperties <broker_name> -c PolicySets -o <PolicySet> -n ws-security

� mqsireportproperties <broker_name> -c PolicySetBindings -o <PolicySetBinding> -n ws-security

Importing policy set and policy set bindingsPolicy sets and bindings can be exported and imported for movement between brokers. If you use the import method shown below, the registry is automatically updated. These are not for packaging in the bar file to deploy.

To import policy sets and policy set bindings, use these commands:

� mqsichangeproperties <broker_name> -c PolicySets -o <policyset name> -n ws-security -p <file>

� mqsichangeproperties <broker_name> -c PolicySetBindings -o <policysetbinding file> -n ws-security -p <file>

The policy set and policy set binding files are stored as XML files with name ws-security in their respective policy set or binding name folders on the file system, in a location specified in the registry (Figure 6-19).

For example, in a Windows operating system, these files are stored in the C:\Documents and Settings\All Users\Application Data\IBM\MQSI\components\<broker_name>\config directory.

>mqsireportproperties WBRK61_DEFAULT_BROKER –c PolicySets –o AllReportableEntityNames –a

PolicySetsWSS10DefaultWSSPolicy


>mqsireportproperties WBRK61_DEFAULT_BROKER –c PolicySetBindings –o AllReportableEntityNames –a

PolicySetBindingsWSS10DefaultWSSConsumerWSSProvider


Attention: We recommend that you do not attempt to edit these files.


Figure 6-19 Policy set and policy set binding files stored in a Windows host for the broker

Assigning the policy set to the message flowA policy set and binding can be assigned to a message flow using the Broker Archive Editor. When the BAR file is opened using the archive editor, the compiled message flow (cmf) appears with all the modifiable properties of the top level message flow nodes in the Configure tree tab.

There are four new properties, as highlighted in Figure 6-20, to select the policy set information. To change the policy set or binding policy set, select the Edit button. This launches a dialog box that allows you to choose from the list of previously defined policy set and policy set bindings.

Figure 6-20 WS-Security settings in the BAR file


For the SOAP nodes in the flow, you can select the Node level Policy Set and Policy Set Binding properties as shown in Figure 6-21. This provides a finer granularity of security. A node level selection overrides the message flow level selection.

Figure 6-21 Associating policy set and bindings at the node level

Managing WS-Security via Configuration Manager ProxyThe Configuration Manager Proxy tool, included with WebSphere Message Broker installation, can be used for limited management of the broker policy set and bindings. This tool allows you to import, retrieve and delete the policy set and policy set bindings as shown in Figure 6-22. These tasks are available in the menu that appears when you right-click on the name of the broker.

The available policy set and policy set bindings can be viewed in the right side of the screen. They appear in the Result column beside the getPolicySetNames() and getPolicySetBindingsNames() methods.

Figure 6-22 Configuration Manager Proxy API Exerciser


6.3 Using DataPower appliances

DataPower appliances play a key role in high-throughput requirement scenarios. These appliances can act as a security gateway, off-loading some of the CPU-intensive processing workload. Integration with WebSphere Message Broker V6.1 is made possible with the WS-Security and WS-Addressing support.

The XML firewall services of the DataPower XS40 or XI50 appliance can be configured to decrypt incoming SOAP or HTTP messages that have the body encrypted using WS-Security. The un-encrypted message is passed to the broker using secure HTTPS protocol. The response from the broker is sent back to DataPower for encryption and then sent on to the client. See Figure 6-23.

The following article outlines the procedure for this integration:

� Integrating WebSphere DataPower XML Security Gateway XS40 with WebSphere Message Broker:

http://www.ibm.com/developerworks/websphere/library/techarticles/0710_crocker/0710_crocker.html#download

Figure 6-23 DataPower appliance integration with WebSphere Message Broker

As shown in Figure 6-23, the authentication of the UsernameToken (user name and password in the SOAP header) and the authorization of the user to access resources can be carried out using DataPower.

DataPower uses Tivoli Access Manager or Tivoli Directory Server client object in its implementation of authentication, authorization, and audit policy service.

Responsevia SSL

Decrypted msgvia SSL

EncryptedSOAP/HTTP

Encrypted

Authentication/Authorization

WebProxy

•TAM•TDS

2

Client

1XML

Firewall



For information on how to configure DataPower to use TAM authentication and authorization, see:

� IBM WebSphere DataPower SOA Appliances Part II: Authentication and Authorization

http://www.redbooks.ibm.com/redpapers/pdfs/redp4364.pdf

DataPower SOA appliances can be integrated using the security wizard of Message Broker Explorer (IS02 Support pack).

Tip: The Message Broker Explorer SupportPac (IS02: WebSphere Message Broker Explorer Plug-in) extends the WebSphere MQ Explorer administrative interface to allow you to administer WebSphere MQ, Message Broker, and DataPower SOA appliance security features from a common administrative console. More information about IS02 can be found at: http://www-01.ibm.com/support/docview.wss?uid=swg24012457.


http://www.redbooks.ibm.com/redpapers/pdfs/redp4364.pdf

http://www-01.ibm.com/support/docview.wss?uid=swg24012457

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper.

IBM Redbooks

For information about ordering these publications, see “How to get Redbooks” on page 132. Note that some of the documents referenced here might be available in softcopy only.

� Using IBM WebSphere Message Broker as an ESB with WebSphere Process Server, SG24-7527

� IBM WebSphere DataPower SOA Appliances Part II: Authentication and Authorization, REDP-4364

Online resources

These Web sites are also relevant as further information sources:

� WebSphere Message Broker V6.1 Information Center:

http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/index.jsp

� Trial version of IBM WebSphere Message Broker V6.1: Learn:


� Trial version of IBM WebSphere Message Broker V6.1: Support page:


� WebSphere Adapters:


� Release Notes for WebSphere Transformation Extender for Integration Servers V8.2.0.3:

http://www-01.ibm.com/support/docview.wss?rs=2320&context=SSVSD8&q1=8.2.0.3&uid=swg27012654&loc=en_US&cs=utf-8&lang=en

� Web Services Addressing (WS-Addressing):

http://www.w3.org/Submission/ws-addressing/

� Support:


� File handling in WebSphere Message Broker V6.1:


� Message modeling and parsing enhancements in WebSphere Message Broker V6.1:



http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r1m0/index.jsp




http://www-01.ibm.com/support/docview.wss?rs=2320&context=SSVSD8&q1=8.2.0.3&uid=swg27012654&loc=en_US&cs=utf-8&lang=en




� OASIS Standards: Web Services Security v1.1


� Integrating WebSphere DataPower XML Security Gateway XS40 with WebSphere Message Broker


� Support


How to get Redbooks

You can search for, view, or download Redbooks, Redpapers, Technotes, draft publications and Additional materials, as well as order hardcopy Redbooks, at this Web site:

ibm.com/redbooks

Help from IBM

IBM Support and downloads

ibm.com/support

IBM Global Services

ibm.com/services







http://www.ibm.com/support/

http://www.ibm.com/support/

http://www.ibm.com/services/

http://www.ibm.com/services/

®

REDP-4458-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information:ibm.com/redbooks

Redpaper™

Using the New Features in WebSphereMessage Broker V6.1Introduction to WebSphere Message Broker

Overview of features added in V6.1

Details on select features

WebSphere Message Broker V6.1 was released in December of 2007. This IBM Redpaper publication discusses the new features and editions available with this release. It highlights several of the new features and provides information on how they can be used to enhance your messaging solutions.

This paper is of interest to architects who are building messaging or enterprise service bus (ESB) solutions, as well as to the implementers of WebSphere Message Broker solutions.

Back cover




Copy of Message Broker v6.1 Red Book

Documents

Transcript of Copy of Message Broker v6.1 Red Book