Websphere Service Registry and Repository Handbook: Front Cover

Front cover
WebSphere Service
Registry and Repository
Handbook
Best practices
Sample integration scenarios
SOA governance
Chris Dudley
Laurent Rieu
Martin Smithson
Tapan Verma
Byron Braswell
ibm.com/redbooks
International Technical Support Organization

WebSphere Service Registry and Repository
Handbook
March 2007
SG24-7386-00
Note: Before using this information and the product it supports, read the information in
Notices on page xv.
First Edition (March 2007)

This edition applies to Version 6, Release 0, Modification 0.1 of IBM WebSphere Service Registry
and Repository (product number 5724-N72).
Copyright International Business Machines Corporation 2007. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Part 1. SOA overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1. Introduction to SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Service-oriented architecture - a business view . . . . . . . . . . . . . . . . . . . . . 4
1.1.1 What is a service in service-oriented architecture? . . . . . . . . . . . . . 5
1.1.2 The SOA Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.3 SOA lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.4 SOA reference architecture model . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.1.5 Supporting elements of the SOA reference architecture. . . . . . . . . . 14
1.2 Service-oriented architecture - an IT view . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.2.1 Definition of a service-oriented architecture . . . . . . . . . . . . . . . . . . . 18
1.2.2 SOA terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.2.3 Drivers for SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.2.4 What is a service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.2.5 Web services and SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.2.6 Core technologies of Web services. . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.2.7 Enterprise Service Bus and SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
1.2.8 Definition of an Enterprise Service Bus. . . . . . . . . . . . . . . . . . . . . . . 30
1.2.9 Enterprise requirements for an ESB . . . . . . . . . . . . . . . . . . . . . . . . . 32
1.2.10 Service registry and repository in an SOA . . . . . . . . . . . . . . . . . . . 34
1.3 SOA governance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
1.3.1 What is SOA governance? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
1.3.2 SOA governance in practice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.3.3 Aspects of SOA governance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
1.4 SOA summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Part 2. WSRR concepts and architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Chapter 2. Concepts and architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.1 Overview of WebSphere Service Registry and Repository . . . . . . . . . . . . 54
2.1.1 What is WebSphere Service Registry and Repository? . . . . . . . . . . 55
Copyright IBM Corp. 2007. All rights reserved.
iii
2.1.2 The limits of WebSphere Service Registry and Repository . . . . . . . 59

2.2 Architecture of WebSphere Service Registry and Repository . . . . . . . . . . 66
2.2.1 Overview of main components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
2.2.2 Information model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
2.2.3 Interfaces and APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
2.2.4 Governance enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Chapter 3. Information model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
3.2 Service description entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
3.2.1 Physical documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.2.2 Logical derivations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.2.3 GenericObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.3 Service description metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
3.3.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
3.3.2 Relationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.3.3 Classifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.3.4 Classifications in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
3.4 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
3.5 Document types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
3.5.1 XML Schema Definition (XSD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.5.2 Web Services Description Language service definitions . . . . . . . . . 94
3.5.3 Service Component Architecture (SCA) modules . . . . . . . . . . . . . . . 96
3.5.4 XML metadata files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
3.5.5 Service Policy (WS-Policy) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
3.6 XPath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
3.7 Service Data Objects (SDO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
3.7.1 Data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
3.7.2 Data graphs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
3.8 BaseObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.9 Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
3.9.1 Types of query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.9.2 Searching and querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
3.9.3 More query examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
3.9.4 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Chapter 4. Interfaces and APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
4.1 Java API (EJB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4.1.1 Creating a Java client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4.1.2 Creating content in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
4.1.3 Retrieving content from WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
4.1.4 Updating content in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
4.1.5 Deleting content from WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
iv
WebSphere Service Registry and Repository Handbook
4.1.6 Querying content in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

4.2 Web services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
4.2.1 Creating a Web services client . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
4.2.2 Ontology Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.2.3 SOAP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
4.3 Web user interface (Web UI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
4.3.1 Web user interface layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
4.3.2 Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
4.3.3 View queries and navigation trees . . . . . . . . . . . . . . . . . . . . . . . . . 150
4.3.4 Collection views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
4.3.5 Detail views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
4.4 Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
4.5 Admin (JMX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Chapter 5. SOA governance enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
5.2 Lifecycles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
5.2.1 State machine terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
5.2.2 Lifecycle definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
5.2.3 WSRR default lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.2.4 GovernanceRecords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
5.3 WSRR security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.3.1 J2EE security roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.3.2 User defined roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
5.3.3 Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5.3.4 Extensible Access Control Markup Language (XACML). . . . . . . . . 196
5.4 WSRR plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
5.4.1 Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
5.4.2 Notifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
5.4.3 Packaging plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
5.4.4 Configuring plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
5.5 Impact analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
5.5.1 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
5.5.2 Specifying modelled dependency relationships . . . . . . . . . . . . . . . 218
5.5.3 Specifying user defined dependency relationships . . . . . . . . . . . . . 243
Part 3. Planning and installing WSRR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Chapter 6. Possible topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
6.1 WSRR requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
6.1.1 Supported platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
6.1.2 Supported databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
6.1.3 Prerequisite software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
6.1.4 Topology selection criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Contents
6.2 Database topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

6.2.1 Local database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
6.2.2 Remote database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
6.3 WebSphere Application Server topologies . . . . . . . . . . . . . . . . . . . . . . . 251
6.3.1 Standalone server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
6.3.2 Distributed server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Chapter 7. Installing and deploying. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
7.1 Install WebSphere Application Server V6.0 . . . . . . . . . . . . . . . . . . . . . . 254
7.2 Install WebSphere Application Server V6.0 refresh pack 2 (V6.0.2) . . . . 254
7.3 Install WebSphere Application Server V6.0.2 fix pack 11 (V6.0.2.11) . . 255
7.4 Install DB2 Universal Database Enterprise Server Edition . . . . . . . . . . . 256
7.5 Install WebSphere Service Registry and Repository. . . . . . . . . . . . . . . . 258
7.6 Deploy WebSphere Service Registry and Repository . . . . . . . . . . . . . . . 265
7.6.1 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
7.7 Installing WSRR with a remote database . . . . . . . . . . . . . . . . . . . . . . . . 275
7.8 Installing WSRR using the WebSphere Application Server Network
Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
7.9 Upgrading WSRR to a new fixpack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
7.9.1 Upgrade from previous version . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
7.9.2 Direct Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
7.10 Installation troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Chapter 8. Administering WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
8.1 Administration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
8.1.1 Administrative scripting (wsadmin) . . . . . . . . . . . . . . . . . . . . . . . . . 282
8.1.2 Administrative (JMX) interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
8.1.3 Command line administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
8.1.4 Configuration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
8.2 WSRR configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
8.2.1 Supported configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
8.3 Security considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
8.4 Administering WSRR using wsadmin . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
8.4.1 Setting up wsadmin for managing WSRR . . . . . . . . . . . . . . . . . . . . 285
8.4.2 Locating the WSRR MBean with wsadmin . . . . . . . . . . . . . . . . . . . 286
8.4.3 Discovering WSRR MBean operations using wsadmin . . . . . . . . . 286
8.4.4 Discovering WSRR MBean notifications using wsadmin . . . . . . . . 289
8.4.5 Invoking operations on WSRR MBean using wsadmin . . . . . . . . . . 289
8.4.6 Troubleshooting WSRR administration with wsadmin . . . . . . . . . . 291
8.5 Administering WSRR using JMX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
8.5.1 Using ServiceRegistryRepositoryProxy.java JMX client . . . . . . . . . 293
8.5.2 Invoking WSRR MBean operations with the Java JMX client . . . . . 295
8.5.3 Exception handling with the Java JMX client . . . . . . . . . . . . . . . . . 296
vi
8.6 Administering WSRR using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

8.6.1 Configuring scripting environment. . . . . . . . . . . . . . . . . . . . . . . . . . 299
8.6.2 Scripting elements and objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
8.6.3 Sample scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
8.7 Ontology administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
8.7.1 Creating an ontology system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
8.7.2 Removing an ontology system . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
8.8 Access control administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
8.8.1 Overview of access control within WSRR . . . . . . . . . . . . . . . . . . . . 309
8.8.2 Administering the WSRR access control policy . . . . . . . . . . . . . . . 310
8.9 Import/Export. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
8.9.1 Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
8.9.2 Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
8.9.3 Import and export with the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
8.9.4 Processing import / export files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
8.10 Environment promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
8.10.1 Promotion mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
8.10.2 Sample script for promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
8.11 Administration scripts (wsadmin). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
8.11.1 Scripts for managing configuration . . . . . . . . . . . . . . . . . . . . . . . . 322
8.11.2 Scripts for managing ontologies . . . . . . . . . . . . . . . . . . . . . . . . . . 322
8.11.3 Scripts for import and export of WSRR entities. . . . . . . . . . . . . . . 322
8.11.4 Scripts for managing access control policy . . . . . . . . . . . . . . . . . . 322
8.11.5 Scripts for managing lifecycles . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Part 4. Using WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Chapter 9. Getting started with WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
9.2 Navigating the Web UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
9.2.1 Quick search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
9.2.2 Unified Service Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
9.2.3 Service Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
9.2.4 Service Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
9.2.5 Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
9.2.6 Classification systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
9.2.7 My Service Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
9.2.8 Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
9.3 Publishing documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
9.4 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
9.4.1 Adding a new custom property . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
9.4.2 Editing a property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
9.4.3 Deleting a custom property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Contents
vii
9.5 Relationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

9.5.1 Creating a new relationship. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
9.5.2 Editing an existing relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
9.5.3 Deleting a relationship. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
9.6 Classifying objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
9.6.1 Loading an OWL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
9.6.2 Browsing classifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
9.6.3 Removing a classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
9.6.4 Classifying an entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
9.7 Searching the registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
9.8 Deleting artefacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
9.9 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
9.9.1 Defining a concept template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
9.9.2 Classifying a complex type as a template . . . . . . . . . . . . . . . . . . . . 371
9.9.3 Viewing templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
9.9.4 Creating a concept from a template . . . . . . . . . . . . . . . . . . . . . . . . 374
9.9.5 Viewing the details of a concept . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
9.9.6 Deleting a concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Chapter 10. Customizing the Web UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
10.2 View query definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
10.2.1 Using alternative views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
10.2.2 Querying by property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
10.2.3 Querying by relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
10.2.4 Querying by classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
10.3 Navigation trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
10.4 Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
10.4.1 A skeleton perspective definition. . . . . . . . . . . . . . . . . . . . . . . . . . 395
10.4.2 Adding name, title and roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
10.4.3 The navigation tree and weight . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
10.4.4 Collection and detail view mappings . . . . . . . . . . . . . . . . . . . . . . . 398
10.4.5 Perspective resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
10.5 Collection views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
10.5.1 Collection view areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
10.5.2 A skeleton collection view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
10.5.3 Adding name, title and description . . . . . . . . . . . . . . . . . . . . . . . . 403
10.5.4 Collection view columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
10.5.5 Collection view buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
10.5.6 Collection view button action values . . . . . . . . . . . . . . . . . . . . . . . 410
10.5.7 Adding collection view resources . . . . . . . . . . . . . . . . . . . . . . . . . 410
10.6 Managing UI customization configurations . . . . . . . . . . . . . . . . . . . . . . 411
10.6.1 Manage configurations with MBean operations . . . . . . . . . . . . . . 412
viii
Chapter 11. Using the WSRR Eclipse plug-in . . . . . . . . . . . . . . . . . . . . . . 415

11.1 WSRR Eclipse user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
11.2 Installing the Eclipse user interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
11.3 Configuring the Eclipse user interface. . . . . . . . . . . . . . . . . . . . . . . . . . 428
11.4 Searching for objects in WSRR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
11.5 Importing documents into your local workspace . . . . . . . . . . . . . . . . . . 435
11.6 Publishing documents to WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
11.7 Adding properties to objects in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . 440
11.8 Defining relationships between objects in WSRR . . . . . . . . . . . . . . . . . 442
11.9 Creating concepts for objects in WSRR . . . . . . . . . . . . . . . . . . . . . . . . 445
11.10 Creating concepts using local documents. . . . . . . . . . . . . . . . . . . . . . 448
Chapter 12. Scenarios description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
12.1 Services description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
12.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
12.3 Solution overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
Chapter 13. Configuring governance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
13.1 Configuring security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
13.1.1 Modifying the J2EE security role mappings . . . . . . . . . . . . . . . . . 463
13.1.2 Removing the AllAuthenticatedUsers principal from the WSRR
Administrator role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
13.1.3 Adding roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
13.1.4 Adding permissions to roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
13.1.5 Mapping users to roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
13.2 Using lifecycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
13.2.1 Making an object governable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
13.2.2 Transitioning the lifecycle state of a governed object . . . . . . . . . . 479
13.2.3 Removing governance from an object . . . . . . . . . . . . . . . . . . . . . 481
13.3 Developing custom plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
13.3.1 Developing a custom validator . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
13.3.2 Developing a customer notifier . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
13.3.3 Deploying custom plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
13.3.4 Configuring custom plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
13.4 Performing impact analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
13.4.1 Analyzing dependencies between physical document objects . . . 500
13.4.2 Analyzing dependencies between physical document objects and
derived objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
13.4.3 Analyzing dependencies between derived objects . . . . . . . . . . . . 507
Chapter 14. Integrating WSRR with WebSphere ESB . . . . . . . . . . . . . . . 511
14.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
14.2 WebSphere ESB overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
14.2.1 Key terms in WebSphere Enterprise Service Bus. . . . . . . . . . . . . 514
Contents
ix
14.3 Structure of WebSphere Enterprise Service Bus . . . . . . . . . . . . . . . . . 515

14.3.1 Mediations, service consumers, and service providers. . . . . . . . . 515
14.3.2 Mediation modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
14.3.3 Mediation flow components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
14.3.4 Mediation flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
14.3.5 Mediation primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
14.4 Related technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
14.4.1 Service message objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
14.5 Endpoint Lookup mediation primitive . . . . . . . . . . . . . . . . . . . . . . . . . . 525
14.5.1 Match policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
14.5.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
14.5.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
14.5.4 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
14.5.5 SOAP/HTTP example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
14.5.6 SOAP/JMS example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
14.5.7 SCA default binding example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
14.5.8 Dynamic endpoint selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
14.6 Managing access from WESB to WSRR. . . . . . . . . . . . . . . . . . . . . . . . 536
14.6.1 Registry definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
14.6.2 General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
14.6.3 Connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
14.6.4 Connecting to a secure WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
14.7 Integration scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
14.7.1 Interaction between WESB and WSRR . . . . . . . . . . . . . . . . . . . . 544
14.7.2 Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
14.7.3 Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
14.7.4 Installation of sample Web services . . . . . . . . . . . . . . . . . . . . . . . 546
14.7.5 Publish the ItemPrice service to WSRR . . . . . . . . . . . . . . . . . . . . 555
14.7.6 Configure WSRR definition in WESB . . . . . . . . . . . . . . . . . . . . . . 568
14.7.7 Scenario 1: Dynamically fetch the service endpoint . . . . . . . . . . . 574
14.7.8 Scenario 1 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
14.7.9 Publish ItemPriceDiscounted service metadata in WSRR . . . . . . 590
14.7.10 Scenario 2: Fetch endpoint based on custom property. . . . . . . . 597
14.7.11 Scenario 2 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
14.7.12 Scenario 3: Use the Lookup primitive to get both endpoints . . . . 612
14.7.13 Scenario 3 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
Chapter 15. Integrating WSRR with ITCAM for SOA . . . . . . . . . . . . . . . . 625
15.1 SOA management and WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
15.1.1 Introduction to SOA management. . . . . . . . . . . . . . . . . . . . . . . . . 626
15.1.2 Managing the SOA Foundation architectural layers . . . . . . . . . . . 629
15.1.3 The role of a service registry and repository in SOA management631
15.2 IBM Tivoli IT Service Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
15.3 IBM Tivoli solutions for SOA management . . . . . . . . . . . . . . . . . . . . . . 633

15.3.1 IBM Tivoli Composite Application Manager . . . . . . . . . . . . . . . . . 634
15.3.2 IBM Tivoli Enterprise Monitoring framework . . . . . . . . . . . . . . . . . 636
15.4 IBM Tivoli Composite Application Manager for SOA. . . . . . . . . . . . . . . 640
15.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
15.4.2 Product features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
15.4.3 Product components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
15.5 WSRR and ITCAM for SOA integration scenarios . . . . . . . . . . . . . . . . 654
15.6 Discovery and display of service information . . . . . . . . . . . . . . . . . . . . 654
15.6.1 Discovery of services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
15.6.2 Displaying of service information . . . . . . . . . . . . . . . . . . . . . . . . . 663
15.7 Service status information forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . 677
15.7.1 Detection and processing of service related situations . . . . . . . . . 678
15.7.2 Propagation, capture and processing of situation events . . . . . . . 687
15.7.3 Use of service status information . . . . . . . . . . . . . . . . . . . . . . . . . 690
15.8 Discovery and display of service information: working example . . . . . . 692
15.8.1 Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
15.8.2 Assumptions and prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
15.8.3 Logical architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
15.8.4 Operational architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
15.8.5 Monitoring services using ITCAM for SOA . . . . . . . . . . . . . . . . . . 698
15.8.6 Understanding WSRR Discovery Library Adapter . . . . . . . . . . . . 702
15.8.7 Installing WSRR Discovery Library Adapter . . . . . . . . . . . . . . . . . 705
15.8.8 Configuring WSRR Discovery Library Adapter . . . . . . . . . . . . . . . 708
15.8.9 Using WSRR Discovery Library Adapter. . . . . . . . . . . . . . . . . . . . 714
15.8.10 Reconciling service information using ITCAM for SOA . . . . . . . . 719
15.9 Forwarding service status information - working example . . . . . . . . . . 727
15.9.1 Understanding ITCAM for SOA Event Handler . . . . . . . . . . . . . . . 728
15.9.2 Installing ITCAM for SOA Event Handler . . . . . . . . . . . . . . . . . . . 729
15.9.3 Configuring ITCAM for SOA Event Handler . . . . . . . . . . . . . . . . . 731
15.9.4 Configuring Tivoli Enterprise Monitoring Framework to send events to
the Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
15.9.5 Triggering situations and forwarding service status information . . 754
15.9.6 Using service status information in ESB infrastructure . . . . . . . . . 770
Chapter 16. Integrating WSRR with WMB . . . . . . . . . . . . . . . . . . . . . . . . . 771
16.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
16.2 About WebSphere Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
16.2.1 Application integration and WebSphere Message Broker. . . . . . . 772
16.2.2 WebSphere Message Broker overview . . . . . . . . . . . . . . . . . . . . . 773
16.2.3 Capabilities of WebSphere Message Broker . . . . . . . . . . . . . . . . 774
16.2.4 Components of WebSphere Message Broker. . . . . . . . . . . . . . . . 776
16.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
Contents
xi
16.3.1 Download the SupportPac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779

16.3.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
16.3.3 Install the SupportPac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
16.4 WebSphere Message Broker Client for WSRR . . . . . . . . . . . . . . . . . . . 786
16.4.1 WSRR nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
16.4.2 WMB Client cache for WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
16.4.3 Client runtime access to WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . 788
16.4.4 WMB Client and WSRR deployment. . . . . . . . . . . . . . . . . . . . . . . 789
16.5 WSRR nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
16.5.1 Introducing the nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
16.5.2 SRGetVirtualService node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
16.5.3 SRProcessVirtualService node . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
16.5.4 SRDispatchVirtualService node . . . . . . . . . . . . . . . . . . . . . . . . . . 794
16.5.5 SRRetrieveITService node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
16.5.6 SRRetrieveEntity node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.6 WMB Client Cache for WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
16.6.1 Cache logical topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
16.6.2 Cache loading strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
16.6.3 Setting cache load strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
16.6.4 Cached items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
16.6.5 Cache synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.7 WMB Client support for SOA patterns. . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.7.1 Transcoder pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.7.2 Router pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
16.8 Setting up your environment for the patterns . . . . . . . . . . . . . . . . . . . . 809
16.8.1 Configuring WMB for the patterns . . . . . . . . . . . . . . . . . . . . . . . . . 810
16.8.2 Configuring WSRR for the patterns. . . . . . . . . . . . . . . . . . . . . . . . 810
16.8.3 Configure the test client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
16.8.4 Run the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
16.8.5 Test message flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
16.8.6 Optional: Importing the test scenario into WMB toolkit . . . . . . . . . 823
Chapter 17. Integrating WSRR with CICS . . . . . . . . . . . . . . . . . . . . . . . . . 825
17.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
17.2 What is CICS?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
17.2.1 CICS product portfolio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
17.2.2 CICS Transaction Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
17.2.3 CICS tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
17.2.4 CICS connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
17.2.5 CICS TXSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
17.2.6 Why interoperate CICS and WebSphere? . . . . . . . . . . . . . . . . . . 829
17.2.7 CICS and WebSphere in an SOA . . . . . . . . . . . . . . . . . . . . . . . . . 831
17.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
xii
17.3.1 Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831

17.3.2 Downloading and installing the CICS SupportPac . . . . . . . . . . . . 832
17.4 Publishing WSDL files from z/OS batch to WSRR . . . . . . . . . . . . . . . . 834
17.4.1 Running DFHWS2SR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
17.4.2 Job control statements for DFHWS2SR . . . . . . . . . . . . . . . . . . . . 837
17.5 Publishing WSDL files from CICS to WSRR . . . . . . . . . . . . . . . . . . . . . 842
17.5.1 Running the CWSP transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 843
17.6 Retrieving WSDL files from WSRR using z/OS batch . . . . . . . . . . . . . . 847
17.6.1 Running DFHSR2WS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
17.6.2 Job control statements for DFHSR2WS . . . . . . . . . . . . . . . . . . . . 850
17.7 Security considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854
17.7.1 Configuring SSL between the z/OS batch utilities and WSRR . . . 854
17.7.2 Configuring SSL between CICS and WSRR . . . . . . . . . . . . . . . . . 855
Part 5. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
Appendix A. IBM product descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
IBM products used to model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
IBM products used to assemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
IBM products used to deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
IBM products used to manage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
IBM Tivoli Composite Application Manager family products . . . . . . . . . . . 872
Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
System requirements for downloading the Web material . . . . . . . . . . . . . 878
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
Online resources and product documentation . . . . . . . . . . . . . . . . . . . . . . . . 888
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
Contents
xiii
xiv
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.
xv
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
alphaWorks
developerWorks
i5/OS
z/OS
z/VSE
zSeries
z9
AIX
Candle
ClearCase
CICS
DataPower
Domino
DB2 Universal Database
DB2
IBM
IMS
MQSeries
NetView
OMEGAMON Monitoring Agent
OMEGAMON
OS/2
Passport Advantage
Rational
Redbooks
Redbooks (logo)
RACF
REXX
SupportPac
System z
Tivoli Enterprise
Tivoli Enterprise Console
Tivoli
TXSeries
WebSphere
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.
SAP NetWeaver, SAP, and SAP logos are trademarks or registered trademarks of SAP AG in Germany and
in several other countries.
Oracle, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates.
ITIL is a registered trademark, and a registered community trademark of the Office of Government
Commerce, and is registered in the U.S. Patent and Trademark Office.
DataStage, are trademarks or registered trademarks of Ascential Software Corporation in the United States,
other countries, or both.
Enterprise JavaBeans, EJB, Java, Java Naming and Directory Interface, JavaBeans, JavaServer,
JavaServer Pages, JDBC, JDK, JMX, JRE, JSP, JVM, J2EE, J2SE, Solaris, Sun, Sun Microsystems, and all
Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or
both.
Active Directory, Expression, Microsoft, Visio, Windows Server, Windows, and the Windows logo are
trademarks of Microsoft Corporation in the United States, other countries, or both.
Intel, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel
Corporation or its subsidiaries 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.
xvi
Preface
Service-oriented architecture offers the promise of business agility and resilience
through reuse, loose coupling, flexibility, interoperability, integration and
governance. These are realized by separating service descriptions from their
implementations, and using this descriptive metadata across the service
lifecycle. Standards-based service metadata artefacts, such as Web Service
Description Language (WSDL), XML schema, policy or Service Component
Architecture (SCA) documents, capture the technical details of what a service
can do, how it can be invoked, or what it expects other services to do. Semantic
annotations and other metadata can be associated with these artefacts to offer
insight to potential users of the service about how and when it can be used, and
what purposes it serves.
A service registry and repository handles the management of service
descriptions and serves as the system of record for this information throughout
the complete lifecycle of a service.
IBM WebSphere Service Registry and Repository is the master metadata
repository for service interaction endpoint descriptions. Because WebSphere
Service Registry and Repository is the integration point of service metadata, it
establishes a central point for finding and managing service metadata. Once
service metadata is placed in WebSphere Service Registry and Repository,
visibility is controlled, versions are managed, proposed changes are analyzed
and communicated, and usage is monitored.
This IBM Redbook discusses the architecture and functions of IBM WebSphere
Service Registry and Repository along with sample integration scenarios that
can be used as examples for implementing WebSphere Service Registry and
Repository in a customer service-oriented architecture environment.
The team that wrote this redbook

This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, Raleigh Center.
xvii
The team
Chris, Martin, Laurent, Tapan, Byron
Byron Braswell is a is a Networking Professional at the ITSO, Raleigh Center.

He received a Bachelor of Science degree in Physics and a Master of Computer
Science degree in Computering Sciences from Texas A&M University. He writes
extensively in the areas of networking, application integration middleware, and
personal computer software. Before joining the ITSO, Byron worked in IBM
Learning Services Development in networking education development.
Chris Dudley is a Software Engineer working in the Application Integration
Middleware area for IBM Software Group in the U.K. After he received his degree
in Civil Engineering in 1999, he joined IBM Software Group and worked on
several IBM products including IBM WebSphere MQ and IBM WebSphere
Message Broker. He worked in IBM Emerging Technology Services before
joining the IBM WebSphere Service Registry and Repository development team
at its inception in late 2005, where he has worked ever since.
Laurent Rieu is an IT Architect working for the SOA Advanced Technology team
(formerly known as Enterprise Integration Solutions) within IBM Software Group.
As part of this worldwide team Laurent is acting as an EMEA Lead Solution
Architect and is helping to drive and enhance IBM software strategy around
service-oriented architecture through customer engagements, field-based
development, asset harvesting, and thought leadership. He has eight years of
experience in the IT industry and has been working at IBM for seven years in
various industries, such as insurance, telecommunications, distribution, public
sector, and utilities. Before joining IBM Software Group, Laurent worked for IBM
Global Business Services. His areas of expertise are service-oriented
architecture, business integration, Patterns, Web services, and J2EE platform.
xviii
Before joining IBM, he worked for one year as Technical Support for Socit
Gnrale in New York City, USA. He graduated (MS) from Ecole Suprieure
dElectricit in 1998.
Martin Smithson is a Senior IT Specialist working on the WebSphere Service
Registry and Repository product at IBM laboratory in Hursley, England. He has
11 years of experience working in the IT industry, five of which he spent working
as a technical consultant for the EMEA IBM Software Services for WebSphere
team. His areas of expertise include the architecture, design, and development of
J2EE applications; he is also an expert on IBM WebSphere Application Server.
He has authored several developerWorks articles and co-authored several
Redbooks: WebSphere Application Server V6 System Management and
Configuration Handbook, SG24-6451, WebSphere Application Server V6.1:
System Management and Configuration, SG24-7304, and CCF Connectors and
Database Connections Using WebSphere Advanced Edition Connecting
Enterprise Information Systems to the Web, SG24-5514. Martin also developed
the IBM Client Application Tool for JMS that is available for download from IBM
alphaWorks Web site.
Tapan Verma is an Advisory IT Specialist at IBM Software Services for
WebSphere in India. He has more than 10 years of experience in the IT Industry,
five of those years working with IBM Software Group in India on WebSphere
consultancy, designing, integration, installation, configuration, and
troubleshooting. His areas of expertise include WebSphere Application Server,
WebSphere Process Server and WebSphere Enterprise Service Bus. He has
product certifications on WebSphere Application Server, WebSphere Process
Server, WebSphere Studio Application Developer and DB2. He also conducts
training and workshops about WebSphere and related topics.
Thanks to the following people for their contributions to this project:
Carla Sadtler
Margaret Ticknor
Linda Robinson
Carolyn Sneed
Tamikia Barrow
ITSO, Raleigh Center
Mark Allman
IBM United Kingdom, Software Group, WebSphere ESB Development
Janet S. Andersen, Rohit I. Badlaney
IBM RTP, Software Group, ITCAM for SOA Development
Tom Bailey, Tim Baldwin, Rob Breeds, Steven Gallacher, Ian Heritage, Chris
Jenkins, Kevin Marsh, Jamie Orchard, Mike Ricketts, Phil Rowley, Andrew
Preface
xix
Rutherford, Dave Seager, Ian Shore, Philip Taunton, Gary Whittingham, Stephen
Willoughby
IBM United Kingdom, Software Group, WebSphere Service Registry and
Repository Development
Duncan Clark, John Colgrave, Barbara McKee
IBM United Kingdom, Software Group, Service Registry Chief Architect
Kim Clark
IBM United Kingdom, Software Group, WebSphere SOA Foundation Product
Specialist
Mark Cocker, Daniel Millwood, Peter Seddon
IBM United Kingdom, Software Group, IBM CICS Development
David Currie
IBM United Kingdom, Software Group, Senior IT Specialist, Pan-IOT Software
Lab Services Software Development Engineer
Arnauld Desprets, Michael Ellis, Bobby Woolf
IBM Software Services for WebSphere
Lisbeth Dineen
IBM Pittsburgh, Software Group, WebSphere Process Integration Technical
Enablement and Support Planning
Raymond Ellis, Subhash Kumar, Bob Patten
IBM United States, Software Group, SOA Advanced Technology US Design
Center
Guy Hochstetler
IBM USA, Software Group, Consulting I/T Specialist
David D. H. Lin
IBM Austin, Software Group, Tivoli Argus Lead Architect
Sunil Murthy
IBM San Jose, Software Group, Product Management, WSRR
Simon Rachman
IBM United Kingdom, Software Group, Service Registry Development Manager
Rosalind Radcliffe
IBM RTP, Software Group, SOA Management Architect
xx
Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbook
dealing with specific products or solutions, while getting hands-on experience
with leading-edge technologies. You'll have the opportunity to team with IBM
technical professionals, Business Partners, and Clients.
Your efforts will help increase product acceptance and customer satisfaction. As
a bonus, you will 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
Comments welcome
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Send us your comments
about this or other Redbooks in one of the following ways:
Use the online Contact us review redbook form found at:
ibm.com/redbooks
Send your comments in an email to:
redbooks@us.ibm.com
Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400
Preface
xxi
xxii
Part 1
Part
SOA overview
Chapter 1.
Introduction to SOA
Service-oriented architecture (SOA) is an approach to defining integration
architectures that are based on the concept of a service. Applications collaborate
by invoking each others services, and services can be composed into larger
sequences to implement business processes.
This chapter introduces service-oriented architecture from a business
perspective and from an IT perspective in the following sections:
1.1, Service-oriented architecture - a business view on page 4
1.2, Service-oriented architecture - an IT view on page 18
1.3, SOA governance on page 40
1.1 Service-oriented architecture - a business view

The primary goal of service-oriented architecture (SOA) is to align the business
world with the world of information technology (IT) in a way that makes both more
effective. SOA is about the business results that can be achieved from having
better alignment between the business and IT.
SOA starts from the premise that all businesses have a business design. A
business design describes how that business works the processes that it
performs; the organizational structure of the people and finances within that
business; the business near-term and long-term goals and objectives; the
economic and market influences that affect how that business achieves its goals;
the rules and policies that condition how the business operates.
Most businesses have a written form of their high level business plan the high
level definition that states the business purpose. Few businesses, however, have
a written form of their business design. Many of those who have documented
their business design have trouble keeping their design up to date with what they
actually practice. Business processes evolve as businesses respond to shifts in
the marketplace, regulations, or product innovations; this evolution usually
happens without reflecting those changes in the formal design of the business.
However, even if the business design has not been documented, or even if what
is documented is now obsolete, there is nonetheless a business design in effect.
A fundamental premise of SOA is that if the business design can be transcribed
and maintained there is a potential for leveraging that captured design
information.
Even if the business design is not used to communicate between the business
and IT organizations, it can nonetheless be a valuable tool to help businesses
understand what they are doing and how. Beyond that, however, the business
design becomes an essential tool in communicating requirements between the
business and the IT organization. The business can identify those elements of
the design that should be automated and what within that design should be
performed by people, creating a blueprint of the information systems that are
created to support that automation.
By deriving the information system design from the business design you can
more easily drive changes into the information system at the rate and pace of
change in the business design. Furthermore, the information system can be used
as a catalyst for change in the business design. It is from this correspondence
that SOA delivers on the promise of more flexible businesses through more
flexible IT.
This correspondence is represented as the SOA Lifecycle, in which the business

process is modeled, assembled, deployed and monitored in an iterative manner.
This transforms the information system from being one of merely a cost of doing
business to a fundamental tool for enabling a business to be more competitive,
profitable and responsive to changes in the marketplace.
To achieve this synergism between the business and IT domains we need to
employ a number of capabilities:
A formalism and language for capturing the business design
A methodology for translating the business design into a set of information
system artefacts to implement that design
An infrastructure for hosting those implementation artefacts that is as flexible
to changes in its marketplace as the business itself needs to be
A place for retaining the correlation between the business design and the
information system that can be used to identify and fix failures in executing on
the goals and constraints of the business design
A means by which we can manage the system to ensure those goals are met.
These capabilities improve the flow of the business process through SOA
Lifecycle iterations.
1.1.1 What is a service in service-oriented architecture?

We refer to the practice of deriving an information system design from a business
design as service-oriented architecture. The business process and the tasks
from which it is composed can be collectively thought of roughly as services.
Thus, the business design is essentially a composition of services and the
policies and conditions that must be applied to their use which form the
information system design.
However, there remains the question of what is a service? Is it a function within
an application? Are all application functions services? Does SOA include system
services? Coming up with a single, mathematically precise definition that applies
universally to all situations can be hugely complicated. In practice, such precision
is not necessary to achieving value and success from SOA.
An underlying premise in the application of SOA to information technology is the
principle of loose coupling that is, avoiding or at least encapsulating temporal,
technological and organizational constraints in the information system design.
This same principle applies also to the definition of service the rules used to
define services in one context may not be applicable in another. What is
important is that whatever definition we arrive at, it should originate from the
primary concerns and constraints of that context. As a generalization, a service is
Chapter 1. Introduction to SOA
a repeatable task within a business process. So, if you can identify your
business processes, and within that, the set of tasks that you perform within the
process, then you can claim that the tasks are services and the business process
is a composition of services.
However, note that certain tasks can be decomposed into business processes in
their own right. The order-entry process includes, amongst other things, a task to
confirm availability of the items being ordered. The confirm-availability task is
itself a business process that includes, for example, the tasks of checking the
on-hand inventory, verifying the supply pipeline, and possibly creating a
background request and determining its availability. Thus, business processes
are themselves services; there is a principle of recursive decomposition implied
in the term service. If taken far enough we could easily claim that everything is a
service. This, obviously, is not useful at some point treating everything as a
service would yield an incredibly inefficient over-generalization of the problem
space. You should exercise this principle of recursive decomposition only to the
extent that you legitimately need flexibility within your business design.
From this definition of service, service-orientation is a way of integrating your
business as a set of linked services. If you can define the services in each of your
vertical and horizontal lines-of-business, you can begin to link those LOBs by
composing their services into larger business processes. Likewise, you can
decompose the main services of your LOBs into a set of more basic services that
can then be easily recomposed either to change LOB processes, or to interlink
your LOBs at a lower level of their capabilities. Similarly, you can use the same
principles of composition to create links with your business partners to both
automate those relationships and to gain more efficiency from them. One
consequence of service orientation is flexibility: you gain the ability to iteratively
optimize your business design, unhampered by inflexible IT structures.
A service-oriented architecture, then, is an architectural style for creating an
Enterprise IT Architecture that exploits the principles of service-orientation
to achieve a tighter relationship between the business and the information
systems that support the business.
1.1.2 The SOA Foundation

What should be clear is that SOA is not just about technology. IBM views SOA as
a holistic relationship between the business and the IT organization. SOA
encompasses the tools and methodologies for capturing business design, and
using that design information to help improve the business. It also encompasses
the tools, programming model and techniques for implementing the business
design in information systems. It encompasses the middleware infrastructure for
hosting that implementation. SOA encompasses the management of that
implementation to ensure availability to the business, and to ensure efficient use
of resources in the execution of that implementation. It encompasses the

establishment of who has authority and the processes that are used to control
changes in the business design and its implementation in the information system.
And ultimately, SOA accelerates the time-to-value for these benefits.
The SOA Foundation is a comprehensive architecture and set of offerings,
technologies, and practices that address all of these things about SOA. To avoid
the connotation that SOA is only about technology we deliberately choose not to
use the term SOA Platform.
1.1.3 SOA lifecycle

The SOA lifecycle (see Figure 1-1) begins with modeling your business
(capturing your business design) including the key performance indicators of
your business goals and objectives, translating that model into an information
system design, deploying that information system, managing that deployment,
and using the results coming out of that environment to identify ways to refine the
business design. It is a premise of the lifecycle that feedback is cycled to and
from phases in iterative steps of refinement and that the model may actually be
built using reverse-engineering techniques or other means to facilitate the needs
of the business.
Figure 1-1 SOA lifecycle
The lifecycle is then layered on a backdrop of a set of governance processes that

ensure that compliance and operational polices are enforced, and that change
occurs in a controlled fashion and with appropriate authority as envisioned by the
business design.
Model
Modeling is the process of capturing your business design from an
understanding of business requirements and objectives and translating that into
a specification of business processes, goals and assumptions creating an
encoded model of your business.
Capturing your business design using a rigorous approach offers the potential to
gain better insight into your business, by, for example using tools to reason about
the design and its supporting rationale. In particular, we can use the model to
simulate how your business processes will actually run. A sophisticated modeling
approach lets you perform what-if scenarios that reflect your understanding of
the actual number of process instances, contacts, quantities, incoming traffic,
and so on, that you may experience in your business. The process can then be
simulated using those parameters to predict the effect that process will have on
your business and on your IT systems. If you do not achieve the intended results
then you can change your process definition to try to improve your results. You
can go on to refine your processes as you have modeled them to optimize your
business performance even before ever investing in an implementation of those
processes.
Your model will also capture key performance indicators business metrics that
are important measurements of your business. This could include, for example, a
measure of the new accounts that you have opened in a given month. These key
performance indicators are input to the assembly of your application and later,
when the application is in production, collected and reported back to you. You will
be able to use that information to determine how well your business is
performing. You can use the correlation between your business design in your
actual implementation in the information system to determine whether
bottlenecks in your performance are due to limitations in your business design or
limitations in the information system that automates your design.
For more information, go to the following Web site:
http://www.ibm.com/developerworks/webservices/library/ws-soa-design1
Assemble
You can use your business design to communicate with the IT organization to
assemble the information system artefacts that will implement the business
design. The enterprise architect working with the business analyst can begin to
convert the business design into a set of business process definitions and
activities deriving the required services from the activity definitions. They can
work with the software architect to flesh out the design of the services.
During the process of resolving a design and implementation of your modeled
business processes and services, you should search your existing asset
inventories your existing programs to find application components that
already meet your needs. Some application components will fit perfectly; some
will have to be re-factored; and some will have to be augmented to meet the
requirements of the design. These existing assets should be rendered as
services for assembly into composite applications.
It is also possible that some of your existing applications are so heavily bound
into a tight relationship with presentation and data logic and other business
functions that you simply cannot extract any re-usable componentry from those
programs. In these cases you will have to decide whether and how to rewrite
these functions as new services, and how to migrate the processes that depend
on those old programs.
Any new services required by the business design will have to be created.
Software developers should use the SOA programming model to create these
new services.
Final assembly includes applying the set of policies and conditions to control how
your applications operate in your production environment. This might include, for
example, business and government regulations, but can also include critical
operational characteristics such as packaging, localization constraints, resource
dependency, integrity control, and access protection.
For more information, go to the following Web sites:
http://www.ibm.com/developerworks/websphere/library/techarticles/051
1_flurry/0511_flurry.html
http://www.ibm.com/developerworks/webservices/library/ws-soa-enter4/
index.html
Deploy
The deploy phase of the lifecycle includes a combination of creating the hosting
environment for your applications and the actual deployment of those
applications. This includes resolving the applications resource dependencies,
operational conditions, capacity requirements, and integrity and access
constraints.
A number of concerns are relevant to construction of the hosting environment
including the presence of the already existing hosting infrastructure supporting
existing applications and pre-existing services. Beyond that, you need to
consider appropriate platform offerings for hosting your user interaction logic,
business process flows, business-services, access services, and information
logic.
You need to consider the techniques you will employ for ensuring availability,
reliability, integrity, efficiency, and service ability.
http://www.ibm.com/developerworks/webservices/library/ws-soa-enter1/
http://www.ibm.com/developerworks/webservices/library/ws-enter5/inde
x.html
http://www.ibm.com/developerworks/library/ws-soa-enter6/index.html
Manage
Turning now to the manage phase of the lifecycle, you need to consider how to
maintain the operational environment and the policies expressed in the assembly
of the SOA applications deployed to that environment. This includes monitoring
performance of service requests and timeliness of service responses;
maintaining problem logs to detect failures in various system components;
detecting and localizing those failures; routing work around them; recovering
work affected by those failures; correcting problems; and restoring the
operational state of the system.
The manage phase also includes managing the business model tuning the
operational environment to meet the business objectives expressed in the
business design, and measuring success or failure to meet those objectives.
SOA is distinguished from other styles of enterprise architecture by its correlation
between the business design and the software that implements that design, and
its use of policy to express the operational requirements of the business services
and processes that codify the business design. The manage phase of the
lifecycle is directly responsible for ensuring those policies are being enforced,
and for relating issues with that enforcement back to the business design.
Managing the system also involves performing routine maintenance,
administering and securing applications, resources and users, and predicting
future capacity growth to ensure that resources are available when the demands
of the business call for it.
http://www.ibm.com/developerworks/webservices/library/ws-sla4/
10
http://www.ibm.com/software/tivoli/products/composite-application-mg
r-soa/
http://www.ibm.com/software/tivoli/solutions/application-management/
http://www.ibm.com/software/tivoli/products/prov-mgr/
http://www.ibm.com/software/tivoli/products/identity-mgr/
Lifecycle flow
Progression through the lifecycle is not entirely linear. In fact, changes to key
performance information in the Model phase often need to be fed directly in to
the Management phase to update the operational environment. Constraints in
the Deploy phase, such as limiting assumptions about where resources are
located in the system, may condition some of the Assembly phase decisions.
And, occasionally, information technology constraints established in the
Assembly phase will limit the business design created during the Model phase
for example, the cost of wide-area wireless communication with remote hand
held devices may be prohibitive to deploying a field force to rural locations and
therefore needs to be reflected back into the business design.
1.1.4 SOA reference architecture model

The SOA reference architecture model attempts to decompose the functional
underpinnings of your application design. Notice white space between
architecture elements in Figure 1-2 on page 12. This is intended to imply our
emphasis on maintaining a clean separation of concerns. The separation
enables us to focus attention on the special skills that are required for each
section of the overall architecture enabling you to optimize your resources to
the skills required for a given topic. This specialization avoids the situation that
everyone on the team needs to understand everything about the entire system to
be effective at anything they do in part of it. This should lower the cost of training,
enable more efficient implementations, and enable the construction of tools
optimized for specific skill sets.
The reference architecture model attempts to be comprehensive spanning all
of the requirements of the SOA Foundation. The parts in light-green in Figure 1-2
on page 12 are the parts in which you will deploy application software to capture
the domain logic specific to your business design. These are the boxes labeled
Interaction Services, Process Services, Information Services, Partner
Services, Business Application Services and Access Services.
The other parts of the architecture exist to assist the rest of the SOA lifecycle.
You use these other parts in the modeling of your business design, construction
11
and assembly of your software, deployment of your applications, and

management of your operational system and the business design you have
implemented. You may even customize these other parts with metadata or
software you write to control or optimize those environments, but generally not
with logic that is specific to your business design.
Business Innovation & Optimization Services
Integrated
environment
for design
and creation
of solution
assets
Interaction Services
Process Services
Information Services
Enable collaboration
between people,
processes & information
Orchestrate and
automate business
processes
Manages diverse
data and content in a
unified manner
ESB
Enables interconnectivity between services
IT Service
Management
Development
Services
Provide for better decision-making

With real-time business information
Security
Policy
Partner Services
Business App Services
Access Services
Connect with trading

partners
Build on a robust,
scaleable, and secure
services environment
Facilitate interactions
with existing information
and application assets
IT
Monitoring
Infrastructure Services
Optimizes throughput,
availability and performance
Figure 1-2 SOA reference architecture model
Interaction services are about the presentation logic of the business design
components that support the interaction between applications and end-users.
Also we recognize that interactions with the external world are not limited to just
interactions with humans. In some cases, interaction logic orchestrates the
interface to industrial robots, vehicles, sensors, RFID devices, environmental
control systems, process control equipment, and so on.
Process Services
Process services include various forms of compositional logic the most notable
of which are business process flows and business state machines (finite-state
machines for business composition). We consider both kinds of composition
mechanisms, plus other forms such as business rules and decision tree
processing, as well as more ad-hoc forms of composition, to be equally valid
approaches to choreographing service composition.
12
For more information about this topic, see the following Web sites:
http://www.ibm.com/developerworks/webservices/library/ws-choreograph
y/index.html
http://www.ibm.com/developerworks/library/ws-soa-progmodel3/
Business Application Services

Business application services implement your core business logic. These are
service components created specifically as services within a business model and
that represent the basic building blocks of your business design services that
are not decomposable within the business model, but that can be composed to
form higher level services.
Information services contain the data logic of your business design. This logic
exists at two levels. On the surface, information services provide access to the
persistent data of your business. This can include query statements for retrieving
the information you care about or referential integrity checks on the information
manipulated by these services. These data services are available to the business
application as services often constructed with specific domain model
semantics so that they appear for all intents and purposes as business
application services.
http://www.ibm.com/developerworks/webservices/library/ws-soa-ims2/in
dex.html
Access Services
Access services are dedicated to integrating existing applications and functions
into the service-oriented architecture. This includes simple wrapping of those
functions and rendering them as services (in the case where the existing function
is a good match with the semantic requirements of the business model in which it
will be used), or in more complex cases augmenting the logic of the existing
function to better meet the needs of the business design. In the latter case, the
access service may in fact invoke multiple current functions to achieve the
semantic requirements of the service. In other architectures we have often
referred to these access services as adapters.
http://www.ibm.com/developerworks/webservices/library/ws-buildebay/
13
Partner Services
Partner services capture the semantics of partner interoperability that have a
direct representation in the business design. This can, for example, include the
policies and constraints that other businesses must conform to work with your
business including business vertical requirements such as the need to conform
to specific industry message and interchange standards like EDIFACT, SWIFT,
RosettaNet, and so on. It can involve the business logic of managing how
partners are selected, and which ones are used as a preference over others in
particular circumstances.
1.1.5 Supporting elements of the SOA reference architecture

The remaining portions of the reference architecture are directly relevant to the
SOA Foundation, and in fact may even be aspects that you can contribute code
to or customize to meet your needs, but generally will not contain functional
aspects of the business design and the application logic that goes directly to
implementing that business design. In general, these areas of the functional
architecture have more to do with the exploitation of information technology as a
means for implementing the business design. They in effect represent
information technology concerns within the overall architecture. See Figure 1-3.
Integrated
environment
for design
and creation
of solution
assets
Process Services
Enable collaboration
between people,
Orchestrate and
automate business
processes
Manages diverse
unified manner
Enables interconnectivity between services
ESB
Registry/Repository
Security
Policy
Partner Services
Access Services

partners
Build on a robust,
Figure 1-3 SOA reference architecture model with registry and repository
14
IT Service
Management
Development
Services

With real-time business information
IT
Monitoring
Enterprise Service Bus

The Enterprise Service Bus (ESB) is a silent partner in the SOA reference
architecture. Its presence in the architecture is transparent to the services of your
SOA application. However, the presence of an ESB is fundamental to simplifying
the task of invoking services making the use of services wherever they are
needed, independent of the details of locating those services and transporting
service requests across the network to invoke those services wherever they
reside within your enterprise.
Access services (see Access Services on page 13) that wrap existing
applications may exist wherever that application has been deployed on different
servers, in different departments, in different data centers. The enterprise service
bus simplifies the task of incorporating these disparate systems so that you can
exploit them in your business design.
See 1.2.7, Enterprise Service Bus and SOA on page 28 for additional
information.
9_flurry1/0509_flurry1.html
http://www.ibm.com/developerworks/websphere/techjournal/0509_reinitz
/0509_reinitz.html
http://www.ibm.com/developerworks/webservices/library/ws-esbia/index
.html
http://www.ibm.com/developerworks/library/ws-soa-progmodel4/
Registry/Repository
Like the Enterprise Service Bus, service registry and repository is a silent partner
in the SOA reference architecture. Note the highlighted Registry/Repository
function in Figure 1-3 on page 14. Even though Figure 1-3 on page 14 makes it
appear that the service registry and repository function is part of the Enterprise
Service Bus, it is not. The service registry and repository function is a separate
entity from the Enterprise Service Bus.
descriptions and serves as the system of record for this information throughout
the complete lifecycle of a service. The service registry and repository is used to
find, publish, manage and subscribe to services with the assurance that the
underlying policies associated with correct usages of these services are enforced
and governed. It supports the following functions:
15
Find
Search/browse for services with varying degrees of criteria driven

by any metadata associated with the service
Publish
Add new services through an approval process to be available and

managed in an enterprise-wide scale
Subscribe
Register to listen to any changes to the metadata associated with

the services
Manage
Provide customizable processes to manage the lifecycle of

services in the registry enabling access control, promote/retire and
analyze changes to services through impact analyses
In the Model phase (refer to Model on page 8) and Assemble phase (refer to
Assemble on page 8), the service registry and repository serves two main
functions. First the service registry and repository can store or capture the
interfaces and messages used by a new service when it is modeled, or a
composite service or process when it is assembled. Second, the service registry
and repository makes the service information searchable to encourage reuse of
common services. A common example of service information gathered or
searched in these phases would be documents conforming to the Web Services
Description Language (WSDL) or XML Schema Definition (XSD) standards.
Architects and developers can also annotate this technical information in the
registry and repository with extra information using formal classification
techniques, such as using the Web Ontology Language (OWL) standard, or by
adding other content defined following XSD standards. Such classification of
services allows for meaningful groupings of the services based on business
objectives.
The service Deployment phase (refer to Deploy on page 9) adds additional
information to the service registry and repository including the connectivity,
security and reliability characteristics of the deployed service. This extra
information builds on the information from the Model and Assembly phases and
differentiates each deployed service instance in the service-oriented
architecture. The deployment information may be expressed in terms of new
WSDL content or through the use of policy statements defined using the
WS-Policy specifications.
In Deploy and Manage phases of the lifecycle, the service registry and repository
serves as a point of integration for the SOA environment by reflecting a system of
record for each deployed service. The relationships, dependencies and
interaction of the services can be documented and exploited in these phases.
See 1.2.10, Service registry and repository in an SOA on page 34 for additional
information.
16

http://www.ibm.com/developerworks/webservices/library/specification/
ws-servregrep/
The purpose of this redbook is to focus on the IBM service registry and
repository product, WebSphere Service Registry and Repository. For more
detailed information about WebSphere Service Registry and Repository
(WSRR), see Part 2, WSRR concepts and architecture on page 51.
Business Innovation and Optimization Services

These services primarily represent the tools and the metadata structures for
encoding your business design, including your business policies and objectives.
Business innovation and optimization is achieved by capturing your business
design and then introspecting on that design to improve it through a combination
of iterative refinement and analysis of real-time business metrics.
Business innovation and optimization services exist in the architecture to help
you capture, encode, analyze and iteratively refine your business design. The
services also include tools to help you simulate your business design and to use
those results to predict the effect that design, or changes to that design, will have
on your business. In addition, these services include tools to help you define your
key performance indicators that is, those business objectives and general
metrics that you want to monitor.
http://www.ibm.com/developerworks/webservices/library/ws-odbp7/index
.html
http://www.ibm.com/developerworks/webservices/library/ws-odbp8/index
.html
http://www.ibm.com/developerworks/webservices/library/ws-cei/index.h
tml
IT Service Management
Once your application has been deployed to the information system, it needs to
be managed along with the IT infrastructure on which it is hosted. IT service
management represents the set of management tools used to monitor your
service flows, the health of the underlying system, the utilization of resources, the
identification of outages and bottlenecks, the attainment of service goals, the
enforcement of administrative policies, and recovery from failures.
17

http://www.ibm.com/software/tivoli/features/it-serv-mgmt/
http://www.ibm.com/developerworks/autonomic/library/ac-prism1/
Infrastructure services form the core of the information technology environment
for hosting SOA applications. It is through these services that we are able to build
a reliable system to provide efficient utilization of resources, ensure the integrity
of the operational environment, balance workload to meet service level
objectives, isolate work to avoid interference, perform maintenance, secure
access to confidential business processes and data, and simplify overall
administration of the system.
1.2 Service-oriented architecture - an IT view

In the previous section, we described service-oriented architecture from a
business point of view. In this section, we describe SOA from an IT point of view.
1.2.1 Definition of a service-oriented architecture

Following are a few definitions of SOA. Note the common terms used in the
definitions.
Component model
Service-oriented architecture is a component model that interrelates an
applications different functional units, called services, through well-defined
interfaces and contracts between these services. The interface is defined in a
neutral manner that should be independent of the hardware platform, the
operating system, and the programming language in which the service is
implemented. This allows services, built on a variety of such systems, to interact
with each other in a uniform and universal manner.
This feature of having a neutral interface definition that is not strongly tied to a
particular implementation is known as loose coupling between services. The
benefit of a loosely-coupled system is its agility and ability to survive evolutionary
changes in the structure and implementation of the internals of each service that
makes up the whole application.
18
Application architecture
Service-oriented architecture is an application architecture in which all functions,
or services, are defined using a description language and have invocable
interfaces that are called to perform business processes. Each interaction is
independent of each and every other interaction and the interconnect protocols
of the communicating devices (that is, the infrastructure components that
determine the communication system do not affect the interfaces). Because
interfaces are platform-independent, a client from any device using any operating
system in any language can use the service.
Though built on similar principles, SOA is not the same as Web services, which
indicates a collection of technologies, such as SOAP and XML. SOA is more
than a set of technologies and runs independent of any specific technologies.
Integration architecture
Service-oriented architecture is an integration architecture approach based on
the concept of a service. The business and infrastructure functions that are
required to build distributed systems are provided as services that collectively, or
individually, deliver application functionality to either end-user applications or
other services.
SOA specifies that within any given architecture, there should be a consistent
mechanism for services to communicate. That mechanism should be coupled
loosely and should support the use of explicit interfaces.
1.2.2 SOA terms

Figure 1-4 highlights the key terms used to describe a service-oriented
architecture.
19
a service?
service orientation?
A repeatable
business task e.g.,
check customer credit;
open new account
A way of integrating your

business as linked
services
and the outcomes that
they bring
service oriented
architecture (SOA)?
a composite
application?
An IT architectural
style that supports
service orientation
A set of related &

integrated services that
support a business
process built on an SOA
Figure 1-4 Definition of key terms for a service-oriented architecture
A service is representative of a repeatable business task. Services are used to

encapsulate the functional units of an application by providing an interface that is
well defined and implementation independent. Services can be invoked
(consumed) by other services or client applications.
Service orientation defines a method of integrating business applications and

processes as linked services.
Service-oriented architecture (SOA) can be different things to different people

depending on the persons role and context (business, architecture,
implementation, operational). From a business perspective, SOA defines a set of
business services composed to capture the business design that the enterprise
wants to expose internally, as well as its customers and partners. From an
architecture perspective, SOA is an architectural style that supports service
orientation. At an implementation level, SOA is fulfilled using a standards based
infrastructure, programming model and technologies such as Web services.
From an operational perspective, SOA includes a set of agreements between
service consumers and providers that specify the quality of service, as well as
reporting on the key business and IT metrics.
A composite application is a set of related and integrated services that support a
business process built on an SOA.
20
Basic components of an SOA

At the most basic level, an SOA consists of the following three components:
Service provider
Service consumer
Service registry
Each component can also act as one of the two other components. For instance,
if a service provider needs additional information that it can only acquire from
another service, it acts as a service consumer. Figure 1-5 on page 21 shows the
operations each component can perform.
Service
Registry
Discover
Service
Consumer
Application-A
- Travel Agent
- Retail Bank
- Publishing House
Flight Reservation
Car Hire
Hotel Booking
Mortgage Lending
Office Supplies
1
Invoke
Request/Response
Publish
Service
Provider
Application-B
- Airline/Car Rental/Hotel Chain
- Mortgage Specialist/Investment Banks
- Office Supplies Company
Figure 1-5 SOA components and operations
The service provider creates a service and in some cases publishes its interface
and access information to a service registry.
Each provider must decide which services to expose, evaluate trade-offs
between security and easy availability, determine how to price the services or
determine how to exploit the value of the services if they are free. The provider
also has to decide in which category the service should be listed, and what sort
of trading partner agreements are required to use the service.
21
The service registry is responsible for making the service interface and
implementation access information available to service consumers. This is a
searchable registry of service descriptions where service providers publish their
service descriptions. Service requestors find services and obtain binding
information (in the service descriptions) for services during development for
static binding, or during execution for dynamic binding. For statically bound
service requestors, the service registry is an optional role in the architecture,
because a service provider can send the description directly to service
requestors. Likewise, service requestors can obtain a service description from
other sources besides a service registry, such as a local file, FTP site, Web site,
and so on.
The implementers of a service registry must consider the scope with which the
registry will be implemented. For example, there are public service registries
available over the Internet to an unrestricted audience, as well as private service
registries that are only accessible to users within a company-wide intranet.
See Registry/Repository on page 15 and 1.2.10, Service registry and
repository in an SOA on page 34 for additional information.
The purpose of this redbook is to focus on the IBM service registry product,
WebSphere Service Registry and Repository. For more detailed information
about WSRR, see Part 2, WSRR concepts and architecture on page 51.
The service consumer locates (discovers) entries in the service registry and then
binds to the service provider in order to invoke the defined service.
1.2.3 Drivers for SOA

The main driver for SOA is to define an architectural approach that assists in the
flexible integration of IT systems. Organizations spend a considerable amount of
time and money trying to achieve rapid, flexible integration of IT systems across
all elements of the business cycle. The drivers behind this objective include:
Increasing the speed at which businesses can implement new products and
processes, can change existing ones, or can recombine them in new ways
Reducing implementation and ownership costs of IT systems and the
integration between them
Enabling flexible pricing models by outsourcing more fine-grained elements of
the business than were previously possible or by moving from fixed to variable
pricing, based on transaction volumes
Simplifying the integration work that is required by mergers and acquisitions
Achieving better IT utilization and return on investment
22
Achieving implementation of business processes at a level that is

independent from the applications and platforms that are used to support the
processes
SOA prescribes a set of design principles and an architectural approach to
achieve this rapid flexible integration.
1.2.4 What is a service?

Having outlined SOA as being an architectural approach to defining integration
architectures based on services, it is important to define what is meant by a
service in this context in order to fully describe SOA and to understand what can
be achieved by using it. A service can be defined as any discrete function that
can be offered to an external consumer. This function can be an individual
business function or a collection of functions that together form a process.
There are many additional aspects to a service that we must also consider in the
definition of a service within an SOA. The most commonly agreed-on aspects are
that services:
Encapsulate reusable business functions
Are defined by explicit, implementation-independent interfaces
Are invoked through communication protocols that stress location
transparency and interoperability
Reusable business functions

A service can be any business function. In an SOA, however, it is preferable that
the function is genuinely reusable. The goal of a service in an SOA is that it can
be used and reused by one or more systems that participate in the architecture.
For example, while the reuse of a Java logging API can be described as design
time (when a decision is made to reuse an available package and bind it into
application code), the intention of SOA is to achieve the reuse of services at:
Runtime
Each service is deployed in one place and one place only and is invoked
remotely by anything that must use it. The advantage of this approach is that
changes to the service (for example, to the calculation algorithm or the
reference data on which it depends) need only be applied in a single place.
Deployment time
Each service is built once but redeployed locally to each system or to the set
of systems that must use it. The advantage of this approach is increased
flexibility to achieve performance targets or to customize the service (perhaps
according to geography).
23
Explicit implementation independent interfaces

The use of explicit interfaces to define and to encapsulate service function is of
particular importance to making services genuinely reusable. The interface
should encapsulate only those aspects of process and behavior that are used in
the interaction between the service consumer and the service provider. An
explicit interface definition, or contract, is used to bind a service consumer and a
service provider. It should specify only the mutual behavior that is required for the
interaction and should specify nothing about the implementation of the consumer
or the provider.
By explicitly defining the interaction in this way, those aspects of either system
(for example the platform on which they are based) that are not part of the
interaction are free to change without affecting the other system. This
implementation-independent interface allows either system to change
implementation or identity freely.
Figure 1-6 illustrates the use of explicit interfaces to define and encapsulate
services functions.
SYSTEM 1
Internal code
and process
Service definition of reusable

business function
INTERFACE
Code definition of reusable

business function
Internal code
and process
SYSTEM 2
Figure 1-6 Service implementation in SOA
24
Communication protocols that stress location transparency

SOA does not specify that any specific protocol be used to provide access to a
service. A key principle in SOA is that a service is not defined by the
communication protocol that it uses but instead, should be defined in a
protocol-independent way that allows different protocols to be used to access the
same service.
Ideally, a service should only be defined once, through a service interface, and
should have many implementations with different access protocols. This type of
definition helps to increase the reusability of any service definition.
1.2.5 Web services and SOA

SOA represents a conceptual architecture of how to integrate applications. Web
services are a specific set of standards and specifications that are one method of
enabling SOA.
Web services technology is a collection of standards (or emerging standards)
that can be used to implement a service-oriented architecture. That is not to say
that Web services and SOA are intrinsically linked, because they can be
implemented separately.
In fact, many significant SOAs are proprietary or customized implementations
that are based on reliable messaging and Enterprise Application Integration
middleware (for example, IBM WebSphere MQ and IBM WebSphere Message
Broker) do not use Web services technologies. Also, most existing Web services
implementations consist of point-to-point integrations that address a limited set of
business functions between a defined set of cooperating partners.
The logical links between Web services and SOA are:
Web services provide an open-standard model for creating explicit,
implementation-independent descriptions of service interfaces.
Web services provide communication mechanisms that are
location-transparent and interoperable.
Web services are evolving, through Business Process Execution Language
for Web Services (WS-BPEL), document-style SOAP, Web Services
Description Language (WSDL), to support the implementation of
well-designed services that encapsulate and model reusable function in a
flexible manner.
25
1.2.6 Core technologies of Web services

Web services are self-contained, modular applications that can be described,
published, located, and invoked over networks. Web services encapsulate
business functions, ranging from a simple request-reply to full business process
interactions. The services can be new or can wrap around existing applications.
Figure 1-7 shows the relationship between the core elements of Web services in
an SOA.
Figure 1-7 Web services core elements in SOA
Core elements
The following are the core technologies used for Web services.
Extensible Markup Language (XML)
XML is the markup language that underlies most of the specifications used for
Web services. XML is a generic language that can be used to describe the
content in a structured way, separated from its presentation to a specific
device.
26
Simple Object Access Protocol (SOAP)

SOAP is a specification for the exchange of structured XML-based messages
between the service provider, service consumer, and service registry,
consisting of three parts:
The format of a SOAP message is an envelope containing zero or more
headers and exactly one body. The envelope is the top element of the XML
document, providing a container for control information, the addressee of a
message, and the message itself. Headers contain control information
such as quality-of-service attributes. The body contains the message
identification and its parameters.
Encoding rules are used for expressing instances of application-defined
data types. SOAP defines a programming language independent data
type schema based on an XML Schema Descriptor (XSD), plus encoding
rules for all data types defined to this model.
RPC representation is the convention for representing remote procedure
calls (RPC) and responses.
SOAP, in principle, is a protocol-independent transport. Consequently, it can
potentially be used in combination with a variety of protocols such as HTTP,
JMS, SMTP, or FTP. Currently, the most common way of exchanging SOAP
messages is through HTTP, which is also the only protocol supported by WS-I
Basic Profile 1.0.
XML Schema Definition (XSD)
XSD is a language for describing XML files that contain XML schema. It
defines an XML document with respect to constraints on what elements and
attributes may appear, in addition to their relationship to each other, what
types of data may be in them, and so on. The description can then be used to
verify that each content item in a document agrees to the description of the
element where the content is to be placed.
Web Services Description Language (WSDL)
WSDL is 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. A WSDL document contains the following main elements:
Types is the container for data type definitions using a type system such as
an XML Schema.
An abstract, typed definition of the data being communicated, a message
can have one or more typed parts.
27
An operation is an abstract description of an action supported by the

service that defines the input and output message and optional fault
message.
The binding is a concrete protocol and data format specification for a
particular port type. The binding information contains the protocol name,
the invocation style, a service ID, and the encoding for each operation.
The service is a collection of related ports.
The port is a single endpoint, an aggregation of a binding and a network
address.
A port type is an abstract set of one or more operations supported by one
or more ports.
Universal Description, Discovery, and Integration (UDDI)
UDDI is both a client-side API and a SOAP-based server implementation that
can be used to store and retrieve information on service providers and Web
services.
It will become clear in the next chapter that IBM WebSphere Service Registry
and Repository is intended to replace UDDI in an SOA environment.
Web Services Inspection Language (WSIL)
WSIL is an XML-based specification that locates Web services without using
UDDI. However, WSIL can also be used with UDDI, that is, it is orthogonal to
UDDI and does not replace it.
As stated previously in the UDDI definition, IBM WebSphere Service Registry
and Repository is intended to replace WSIL in an SOA environment.
1.2.7 Enterprise Service Bus and SOA

Successfully implementing an SOA requires applications and an infrastructure
that can support the service-oriented architecture principles. Applications can be
enabled by creating service interfaces to existing or new functions that are
hosted by the applications. The service interfaces should be accessed using an
infrastructure that can route and transport service requests to the correct service
provider. As organizations expose more and more functions as services, it is
vitally important that this infrastructure should support the management of SOA
on an enterprise scale.
The Enterprise Service Bus (ESB) is a middleware infrastructure component that
supports the implementation of SOA within an enterprise. Figure 1-8 on page 29
shows where the Enterprise Service Bus fits in the SOA reference architecture.
28
Integrated
environment
for design
and creation
of solution
assets
Process Services
Enables collaboration
between people,
Orchestrate and
automate business
processes
Manages diverse
unified manner
ESB
IT Service
Management

with real-time business information
Enable inter-connectivity between services
Partner Services
Access Services

partners
Build on a robust,
Apps &
Info Assets
Development
Services
Manage
and secure
services,
applications
&
resources
Figure 1-8 ESB in the SOA reference architecture
The need for an ESB can be seen by considering how it supports the concepts of
SOA implementation by:
Decoupling the consumers view of a service from the actual implementation
of the service
Decoupling technical aspects of service interactions
Integrating and managing services in the enterprise
Decoupling the consumers view of a service from the actual implementation
greatly increases the flexibility of the architecture. It allows the substitution of one
service provider for another (for example, because another provider offers the
same services for lower cost or with higher standards) without the consumer
being aware of the change or without the need to alter the architecture to support
the substitution.
This decoupling is better achieved by having the consumers and providers
interact via an intermediary. Intermediaries publish services to consumers. The
consumer binds to the intermediary to access the service, with no direct coupling
to the actual provider of the service. The intermediary maps the request to the
location of the real service implementation.
In an SOA, services are described as being loosely coupled. However, at
implementation time, there is no way to loosely couple a service or any other
29
interaction between systems. The systems must have some common

understanding to conduct an interaction. Instead, to achieve the benefits of loose
coupling, consideration should be given to how to couple or decouple various
aspects of service interactions, such as the platform and language in which
services are implemented, the communication protocols used to invoke services,
the data formats used to exchange input and output data between service
consumers and providers.
Further decoupling can be achieved by handling some of the technical aspects of
transactions outside of applications. This could apply to aspects of interactions
such as:
How service interactions are secured
How the integrity of business transactions and data is maintained (for
example, through reliable messaging, the use of transaction monitors, or
compensation techniques)
How the invocation of alternative service providers is handled in the event that
the default provider is unavailable
These aspects imply a need for middleware to support an SOA implementation.
Some of the functions that might be provided by the middleware are:
Map service requests from one protocol and address to another
Transform data formats
Support a variety of security and transactional models between service
consumers and service providers and recognize that consumers and
providers might support or require different models
Aggregate or disaggregate service requests and responses
Support communication protocols between multiple platforms with
appropriate qualities of service
Provide messaging capabilities such as message correlation and
publish/subscribe, to support different messaging models such as events and
asynchronous request/response
This middleware support is the role of an ESB.
1.2.8 Definition of an Enterprise Service Bus

An ESB provides an infrastructure that removes any direct connection between
service consumers and providers. Consumers connect to the bus and not the
provider that actually implements the service. This type of connection further
decouples the consumer from the provider. A bus also implements further value
add capabilities. For example, security and delivery assurance can be
30
implemented centrally within the bus instead of having this buried within the
applications.
Integrating and managing services in the enterprise outside of the actual
implementation of the services in this way helps to increase the flexibility and
manageability of SOA.
The primary driver for an ESB, however, is that it increases decoupling between
service consumers and providers. Protocols such as Web services define a
standard way of describing the interface to a service provider that allow some
level of decoupling (as the actual implementation details are hidden). However,
the protocols imply a direct connection between the consumer and provider.
Although it is relatively straight forward to build a direct link between a consumer
and provider, these links can lead to an interaction pattern that consists of
building multiple point-to-point links that perform specific interactions. With a
large number of interfaces this quickly leads to the build up of a complex
spaghetti of links with multiple security and transaction models. Routing control is
distributed throughout the infrastructure, and probably no consistent approach to
logging, monitoring, or systems management is implemented. This environment
is difficult to manage or maintain and inhibits change.
A common approach to reducing this complexity is to introduce a centralized
point through which interactions are routed, as shown in Figure 1-9.
Hub and Spoke
Direct Connection
Service
Consumer
Service
Provider
Service
Consumer
Service
Consumer
Service
Provider
Service
Consumer
Service
Consumer
Service
Provider
Service
Consumer
Service
Provider
Hub:
ESB
Service
Provider
Service
Provider
Figure 1-9 Direct connection and central hub integration styles
A hub and spoke architecture is a common approach that is used in application

integration architectures. In a hub, the distribution rules are separated from
applications. The applications connect to the hub and not directly to any other
application. This type of connection allows a single interaction from an
application to be distributed to multiple target applications without the consumer
being aware that multiple providers are involved in servicing the request. This
connection can reduce the proliferation of point-to-point connections.
31
Note that the benefit of reducing the number of connections only truly emerges if
the application interfaces and connections are genuinely reusable. For example,
consider the case where one application needs to send data to three other
applications. If this is implemented in a hub, the sending application must define
a link to the hub, and the hub must have links that are defined to the three
receiving applications, giving a total of four interfaces that need to be defined. If
the same scenario was implemented using multiple point-to-point links, the
sending application would need to define links to each of the three receiving
applications, giving a total of just three links. A hub only offers the benefit of
reduced links if another application also needs to send data to the receiving
applications and can make use of the same links as those that are already
defined for the first application. In this scenario, the new application only needs to
define a connection between itself and the hub, which can then send the data
correctly formatted to the receiving applications.
Hubs can be federated together to form what is logically a single entity that
provides a single point of control but is actually a collection of physically
distributed components. This is commonly termed a bus. A bus provides a
consistent management and administration approach to a distributed integration
infrastructure.
1.2.9 Enterprise requirements for an ESB

Using a bus to implement an SOA has a number of advantages. In an SOA
services should, by definition, be reusable by a number of different consumers,
so that the benefits of reduced connections are achieved. In addition, the ESB:
Supports high volumes of individual interactions.
Supports more established integration styles, such as message-oriented and
event-driven integration, to extend the reach of the SOA. The ESB should
allow applications to be SOA enabled either directly or through the use of
adapters.
Support centralization of enterprise-level qualities of service and
manageability requirements into the hub.
32
Figure 1-10 show a high-level view of the ESB.
Figure 1-10 The Enterprise Service Bus
SOA applications are built from services. Typically, a business service relies on
many other services in its implementation. The ESB is the component that
provides access to the services and so enables the building of SOA applications.
Mediation support
The ESB is more than just a transport layer. It must provide mediation support to
facilitate service interactions (for example, to find services that provide
capabilities for which a consumer is asking or to take care of interface
mismatches between consumers and providers that are compatible in terms of
their capabilities). It must support a variety of ways to get on and off the bus,
such as adapter support for existing applications or business connections, that
enable external partners in business-to-business interaction scenarios. To
support these different ways to get on and off the bus, it must support service
interaction with a wide variety of service endpoints. It is likely that each endpoint
will have its own integration techniques, protocols, security models and so on.
This level of complexity should be hidden from service consumers. They need to
be offered a simpler model. In order to hide the complexity from the consumers,
the ESB is required to mediate between the multiple interaction models that are
understood by service providers and the simplified view that is provided to
consumers.
33
Protocol independence
As shown in Figure 1-10 on page 33, services can be offered by a variety of
sources. Without an ESB infrastructure, any service consumer that needs to
invoke a service needs to connect directly to a service provider using the
protocol, transport, and interaction pattern that is used by the provider. With an
ESB, the infrastructure shields the consumer from the details of how to connect
to the provider.
In an ESB, there is no direct connection between the consumer and provider.
Consumers access the ESB to invoke services, and the ESB acts as an
intermediary by passing the request to the provider using the appropriate
protocol, transport, and interaction pattern for the provider. This intermediary
connection enables the ESB to shield the consumer from the infrastructure
details of how to connect to the provider. The ESB should support several
integration mechanisms, all of which can be described as invoking services
through specific addresses and protocols, even if in some cases the address is
the name of a CICS transaction and the protocol is a J2EE resource adapter
integrating with the CICS Transaction Gateway. By using the ESB, the
consumers are unaware of how the service is invoked on the provider.
Because the ESB removes the direct connection between service consumer and
providers, an ESB enables the substitution of one service implementation by
another with no effect to the consumers of that service. Thus, an ESB allows the
reach of an SOA to extend to non-SOA enabled service providers. It can also be
used to support migration of the non-SOA providers to using an SOA approach
without impacting the consumers of the service.
1.2.10 Service registry and repository in an SOA

Service-oriented architecture promotes business agility and resilience through
reuse, loose coupling, flexibility, interoperability, integration and governance.
These are realized by separating service descriptions from their
implementations, and using this descriptive information across the service
life-cycle. Standards-based service information artefacts capture the technical
details of what a service can do, how it can be invoked or what it expects other
services to do. Information, annotations and classifications from the service
providers can be associated with these artefacts to offer insight to potential users
of the service on how and when it can be used, and what purposes it serves.
descriptions and serves as the system of record for this information. A populated
and maintained service registry and repository is the place in an organization
that catalogs all of the services deployed or used by an organization.
34
Another function of a service registry and repository is to support the governance

of the service lifecycle (see 1.1.3, SOA lifecycle on page 7) including promotion
of services through phases of that life-cycle, controlled access to service
information, and impact analysis and socialization of changes to services with
interested parties.
Service registry and repository integration within SOA

A service registry and repository provides a place to organize, manage, find and
govern the service descriptions. In heterogeneous deployment environments that
are typical in SOA, the service registry and repository provides a standard,
interoperable means for access, query and manipulate the service descriptions.
The service registry and repository plays a central role throughout the SOA
lifecycle. Therefore, it is important to note that it be integrated with applications
from the service development lifecycle, change and release management,
service runtimes, service management (operational efficiency and resilience)
and other service registries and repositories. These integration points are shown
in Figure 1-11.
Service
Development
Lifecycle
Model
Service Endpoint
Registries /
Repositories
Build
Discover
Assemble
Service Registry and Repository
Change and
Release
Management
ESB
Operational
Efficiency and
Resilience
Test
Manage
Mediate
Bind
Deploy
Runtime Integration
Figure 1-11 Service registry and repository integration points in an SOA
35
The Service Development Lifecycle box in Figure 1-11 represents the

development time uses for a service registry and repository. Newly developed
services are published to the service registry and repository. At the same time,
the service registry and repository can be used to discover and reuse services
that can serve as building blocks for new composite applications.
The Change and Release Management box in Figure 1-11 on page 35
represents the lifecycle management of services and their service descriptions.
This is the point at which service metadata is usually placed into the service
registry and repository, assessed, administered, and made available to a broader
constituency. The service registry and repository can be used to govern deployed
services to ensure changes are authorized and service integrity is maintained. In
addition, it can notify clients of changes to services.
The Runtime Integration box in Figure 1-11 on page 35 represents the
execution environment where the service registry and repository is accessed at
runtime to dynamically select a service provider, or to dynamically enforce an
invocation policy. It manages information that enables dynamic binding of service
requestors to service providers (see Figure 1-5 on page 21) and allows the
infrastructure to enforce registered policies.
The Service Endpoint Registries/Repositories box in Figure 1-11 on page 35
represents the interactions between this service registry and repository and other
distributed repositories to acquire service metadata for applications that may
have services distributed over multiple registries and repositories.
The Operational Efficiency and Resilience box in Figure 1-11 on page 35
represents the access to the service registry and repository to obtain additional
information about services that are encountered during monitoring, to find out
about new services that are candidates for monitoring, and for policies for
monitoring and assessing the performance of services. Mediations in this area
take advantage of the knowledge gained through monitoring and operational
management.
Service registry and repository in SOA management

A service registry and repository stands as the source of service information and
metadata in an organization. As such it plays a double role in the overall domain
space of SOA management.
It provides the SOA management infrastructure with detailed information
about the registered services
It supports the enrichment of service information with operational data
observed and processed by the SOA management infrastructure
36
Figure 1-12 provides a high-level overview of a service registry and repository in

the SOA management space.
Service
Consumer
Information on
Provided
Services
Service
Registry
& Repository
Consume
Services
Service
Provider
Register
Provided
Services
Observe &
Manage
Services
Information on
Registered
Services
Information on
Operational
Services
Monitoring &
Management
Figure 1-12 Service registry and repository and SOA management components
37
Figure 1-13 abstracts away the notion of Service Consumer and rather focusses
on the other relevant roles.
Service
Provider
Provided
services are
registered in
SRR
Services are
observed by
the Monitoring
and
Management
infrastructure
Information on
registered services is
made available
Service
Registry
& Repository
Monitoring &
Management
Operational data on
observed services
is fed back
Operational data enriches

the service information and
metadata
Information on registered
services is reconciled with that
collected from observed
services and is used to
augment the understanding of
the management domain
Figure 1-13 The role of service registry and repository in SOA management
Registered services are managed in the service registry and repository. This
information is accessed by multiple actors, including the Service Provider
(registering services) and the Service Consumer (looking for services to
consume).
The Monitoring and Management infrastructure uses this information about
registered services to enhance its understanding of the topology and
characteristics of the services in the monitored SOA. Such information can
include immediate details on service endpoints. It can also consist of some
meaningful description of service interfaces and behavior, or it can provide a
38
formal description of relationships across services and other SOA citizens such
as business processes, consumers and providers. Based on this information the
Monitoring and Management infrastructure can enhance its view of the managed
resources and their topologies.
The Monitoring and Management infrastructure then feeds back some
operational data it collects about the observed services to the service registry
and repository. This data has been captured and collected at runtime by the
observation points from the running services that are part of the managed
resources. Various elements of the runtime behavior of the services can be
collected, such as the average response time, the fault rate, the size and
frequency of the messages, and so on.
These operational elements are used to further enrich the service information
model managed by the service registry and repository, therefore allowing other
actors in the SOA to use this information. For example, ESB infrastructures could
use indications on the observed quality of interaction a service supports (average
response time, fault rate, availability...) to perform smart routing decisions to the
best available service. The same reasoning could be applied to any service
consumers which would base their consumption decisions on the observed
operational behavior of the service. Another example could be when planning for
the migration of services based on their utilization.
This collaboration between the service registry and repository and the SOA
management infrastructure expands the management domain so that it can
embrace the overall service lifecycle and reflect the operational dimension of the
services as first class citizen in an SOA environment.
Note: Figure 1-13 on page 38 does not include any integration fabric
middleware such as the ESB. However, it is arguable that, at a conceptual
level, such a component can be considered as both a service consumer (it
consumes the actual services provided by dedicated service components or
systems) and a service provider (it exposes these virtualized services).
In the former case, it can decide which service to consume based on the
operational behavior of those services (routing scenario).
In the latter case, the services it exposes (or virtualizes) can themselves be
considered as managed resources and, consequently, subject to runtime
observation by the management infrastructure.
See Registry/Repository on page 15 for additional information about a service
registry and repository.
39
The purpose of this redbook is to focus on the IBM service registry and
repository product, WebSphere Service Registry and Repository. For more
detailed information about WSRR, see Part 2, WSRR concepts and
architecture on page 51.
1.3 SOA governance

SOA is a compelling technique for developing software applications that best
align with business models. However, SOA increases the level of cooperation
and coordination required between business and information technology (IT), as
well as among IT departments and teams. This cooperation and coordination is
provided by SOA governance, which covers the tasks and processes for
specifying and managing how services and SOA applications are supported.
1.3.1 What is SOA governance?

In general, governance means establishing and enforcing how a group agrees to
work together. Specifically, there are two aspects to governance:
Establishing chains of responsibility, authority, and communication to
empower people, determining who has the rights to make what decisions.
Establishing measurement, policy, and control mechanisms to enable people
to carry out their roles and responsibilities.
Governance is distinct from management in the following ways:
Governance determines who has the authority and responsibility for making
the decisions.
Management is the process of making and implementing the decisions.
To put it another way, governance says what should be done, while management
makes sure it gets done.
A more specific form of governance is IT governance, which does the following:
Establishes decision-making rights associated with IT.
Establishes mechanisms and policies used to measure and control the way IT
decisions are made and carried out.
That is, IT governance is about who's responsible for what in an IT department
and how the department knows those responsibilities are being performed.
SOA adds the following unique aspects to governance:
40
Acts as an extension of IT governance that focuses on the lifecycle of

services to ensure the business value of SOA.
Determines who should monitor, define, and authorize changes to existing
services within an enterprise.
Governance becomes more important in SOA than in general IT. In SOA, service
consumers and service providers run in different processes, are developed and
managed by different departments, and require a lot of coordination to work
together successfully. For SOA to succeed, multiple applications need to share
common services, which means they need to coordinate on making those
services common and reusable. These are governance issues, and they're much
more complex than in the days of monolithic applications or even in the days of
reusable code and components.
As companies use SOA to better align IT with the business, companies can
ideally use SOA governance to improve overall IT governance. Employing SOA
governance is key if companies are to realize the benefits of SOA. For SOA to be
successful, SOA business and technical governance is not optional, it is
required.
1.3.2 SOA governance in practice

In practice, SOA governance guides the development of reusable services,
establishing how services will be designed and developed and how those
services will change over time. It establishes agreements between the providers
of services and the consumers of those services, telling the consumers what
they can expect and the providers what they're obligated to provide.
SOA governance does not design the services, but guides how the services will
be designed. It helps answer many thorny questions related to SOA: What
services are available? Who can use them? How reliable are they? How long will
they be supported? Can you depend on them to not change? What if you want
them to change, for example, to fix a bug? Or to add a new feature? What if two
consumers want the same service to work differently? Just because you decide
to expose a service, does that mean you're obligated to support it forever? If you
decide to consume a service, can you be confident that it will not be shut down
tomorrow?
SOA governance builds on existing IT governance techniques and practices. A
key aspect of IT governance when using object-oriented technologies like Java 2
Platform, Enterprise Edition (J2EE) is code reuse. Code reuse also illustrates the
difficulties of IT governance. Everyone thinks reusable assets are good, but
they're difficult to make work in practice: Who's going to pay to develop them?
Will development teams actually strive to reuse them? Can everyone really agree
on a single set of behavior for a reusable asset, or will everyone have their own
41
customized version which isn't really being reused after all? SOA and services
make these governance issues even more important and thus, their
consequences even more significant.
Governance is more of a political problem than a technological or business one.
Technology focuses on matching interfaces and invocation protocols. Business
focuses on functionality for serving customers. Technology and business are
focused on requirements. While governance gets involved in those aspects, it
focuses more on ensuring that everyone is working together and that separate
efforts are not contradicting each other. Governance does not determine what
the results of decisions are, but what decisions must be made and who will make
them.
The two parties, the consumers and the providers, have to agree on how they're
going to work together. Much of this understanding can be captured in a
service-level agreement (SLA), measurable goals that a service provider agrees
to meet and that a service consumer agrees to live with. This agreement is like a
contract between the parties, and can, in fact, be a legal contract. At the very
least, the SLA articulates what the provider must do and what the consumer can
expect.
SOA governance is enacted by a center of excellence (COE), a board of
knowledgeable SOA practitioners who establish and supervise policies to help
ensure an enterprise's success with SOA. The COE establishes policies for
identification and development of services, establishment of SLAs, management
of registries, and other efforts that provide effective governance. COE members
then put those policies into practice, mentoring and assisting teams with
developing services and composite applications.
Once the governance COE works out the policies, technology can be used to
manage those policies. Technology doesn't define an SLA, but it can be used to
enforce and measure compliance. For example, technology can limit which
consumers can invoke a service and when they can do so. It can warn a
consumer that the service has been deprecated. It can measure the service's
availability and response time.
A good place for the technology to enforce governance policies is through a
combination of an enterprise service bus (ESB) and a service registry. A service
can be exposed so that only certain ESBs can invoke it. Then the ESB/registry
combination can control the consumers' access, monitor and meter usage,
measure SLA compliance, and so on. This way, the services focus on providing
the business functionality, and the ESB/registry focuses on aspects of
governance.
42
1.3.3 Aspects of SOA governance

SOA governance is not just a single set of practices, but many sets of practices
coordinated together. The sections that follow provide a brief overview of the
various aspects of SOA governance.
Service definition
The most fundamental aspect of SOA governance is overseeing the creation of
services. Services must be identified, their functionality described, their behavior
scoped, and their interfaces designed. The governance COE may not perform
these tasks, but it makes sure that the tasks are being performed. The COE
coordinates the teams that are creating and requiring services, to make sure
needs are being met and to avoid duplicate effort.
Often, it is not obvious what should be a service. The function should match a set
of repeatable business tasks. The service's boundaries should encapsulate a
reusable, context-free capability. The interface should expose what the service
does, but hide how the service is implemented and allow for the implementation
to change or for alternative implementations. When services are designed from
scratch, they can be designed to model the business; when they wrap existing
function, it can be more difficult to create and implement a good business
interface.
An interesting example of the potential difficulties in defining service boundaries
is where to set transactional boundaries. A service usually runs in its own
transaction, making sure that its functionality either works completely or is rolled
back entirely. However, a service coordinator may want to invoke multiple
services in a single transaction (ideally through a specified interaction like
WS-AtomicTransactions). This task requires the service interface to expose its
transaction support so that it can participate in the caller's transaction. But such
exposure requires trust in the caller and can be risky for the provider. For
example, the provider may lock resources to perform the service, but if the caller
never finishes the transaction (it fails to commit or roll back), the provider will
have difficulty cleanly releasing the resource locks. As this scenario shows, the
scope of a service and who has control is sometimes no easy decision.
Service deployment lifecycle

Services do not come into being instantaneously and then exist forever. Like any
software, they need to be planned, designed, implemented, deployed,
maintained, and ultimately, decommissioned. The application lifecycle can be
public and affect many parts of an organization, but a service's lifecycle can have
even greater impact because multiple applications can depend on a single
service.
43
The lifecycle of services becomes most evident when you consider the use of a
registry. When should a new service be added to the registry? Are all services in
a registry necessarily available and ready for use? Should a decommissioned
service be removed from the registry?
While there is no one-size-fits-all lifecycle that is appropriate for all services and
all organizations, a typical service development lifecycle has five main stages:
1. Plan
A new service that is identified and is being designed, but has not yet been
implemented or is still being implemented.
2. Test
Once implemented, a service must be tested. Some testing may need to be
performed in production systems, which use the service as though it were
active.
3. Active
This is the stage for a service available for use and what we typically think of
as a service. It is a service, it is available, it really runs and really works, and it
has not been decommissioned yet.
4. Deprecate
This stage describes a service which is still active, but will not be for much
longer. It is a warning for consumers to stop using the service.
5. Sunset
This is the final stage of a service, one that is no longer being provided.
Registries may want to keep a record of services that were once active, but
are no longer available. This stage is inevitable, and yet frequently is not
planned for by providers or consumers.
Sunsetting effectively turns the service version off, and the sunset date should be
planned and announced ahead of time. A service should be deprecated within a
suitable amount of time before it is sunsetted, to programmatically warn
consumers so that they can plan accordingly. The schedule for deprecation and
sunsetting should be specified in the SLA.
One stage which may appear to be missing from this list is maintenance.
Maintenance occurs while a service is in the active state; it can move the service
back into test to reconfirm proper functionality, although this can be a problem for
existing users depending on an active service provider.
Maintenance occurs in services much less than you might expect; maintenance
of a service often involves not changing the existing service, but producing a new
service version.
44
Service versioning
No sooner than a service is made available, the users of those services start
needing changes. Bugs need to be fixed, new functionality added, interfaces
redesigned, and unneeded functionality removed. The service reflects the
business, so as the business changes the service needs to change accordingly.
With existing users of the service, however, changes need to be made judiciously
so as not to disrupt their successful operation. At the same time, the needs of
existing users for stability cannot be allowed to impede the needs of users
desiring additional functionality.
Service versioning meets these contradictory goals. It enables users satisfied
with an existing service to continue using it unchanged, yet allows the service to
evolve to meet the needs of users with new requirements. The current service
interface and behavior is preserved as one version, while the newer service is
introduced as another version. Version compatibility can enable a consumer
expecting one version to invoke a different but compatible version.
While versioning helps solve these problems, it also introduces new ones, such
as the need to migrate.
Service migration
Even with service versioning, a consumer cannot depend on a service, or more
specifically, a desired version of that service, to be available and supported
forever. Eventually, the provider of a service is bound to stop providing it. Version
compatibility can help delay this day of reckoning but will not eliminate it.
Versioning does not obsolete the service development lifecycle, but it enables the
lifecycle to play out over successive generations.
When a consumer starts using a service, it is creating a dependency on that
service, a dependency that has to be managed. A management technique is for
planned, periodic migration to newer versions of the service. This approach also
enables the consumer to take advantage of additional features added to the
service.
However, even in enterprises with the best governance, service providers cannot
depend on consumer migration alone. For a variety of reasons, for example
existing code, manpower, budget, priorities, some consumers may not migrate in
a timely fashion. Does that mean the provider must support the service version
forever? Can the provider simply disable the service version one day after
everyone should have already migrated?
Neither of those extremes is desirable. A good compromise is a planned
deprecation and sunsetting schedule for every service version, as described in
Service deployment lifecycle on page 43.
45
Service registries
How do service providers make their services available and known? How do
service consumers locate the services they want to invoke? These are the
responsibilities of a service registry. It acts as a listing of the services available
and the addresses for invoking them.
The service registry also helps coordinate versions of a service. Consumers and
providers can specify which version they need or have, and the registry then
makes sure to only enumerate the providers of the version desired by the
consumer. The registry can manage version compatibility, tracking compatibility
between versions, and enumerating the providers of a consumer's desired
version or compatible versions. The registry can also support service states, like
test and deprecated, and only make services with these states available to
consumers that want them.
When a consumer starts using a service, a dependency on that service is
created. While each consumer clearly knows which services it depends on,
globally throughout an enterprise these dependencies can be difficult to detect,
much less manage. Not only can a registry list services and providers, but it can
also track dependencies between consumers and services. This tracking can
help answer the age-old question: Who's using this service? A registry aware of
dependencies can then notify consumers of changes in providers, such as when
a service becoming deprecated.
Service message model

In a service invocation, the consumer and provider must agree on the message
formats. When separate development teams are designing the two parts, they
can easily have difficultly finding agreement on common message formats.
Multiply that by dozens of applications using a typical service and a typical
application using dozens of services, and you can see how simply negotiating
message formats can become a full-time task.
A common approach for avoiding message format chaos is to use a canonical
data model. A canonical data model is a common set of data formats that is
independent of any one application and shared by all applications. In this way,
applications do not have to agree on message formats, they can simply agree to
use existing canonical data formats. A canonical data model addresses the
format of the data in the message, so you still need agreement around the rest of
the message format, for example header fields, what data the message payload
contains, and how that data is arranged, but the canonical data model goes a
long way toward reaching agreement.
A central governance board can act as a neutral party to develop a canonical
data model. As part of surveying the applications and designing the services, it
can also design common data formats to be used in the service invocations.
46
Service monitoring
If a service provider stops working, how will you know? Do you wait until the
applications that use those services stop working and the people that use them
start complaining?
A composite application, one that combines multiple services, is only as reliable
as the services it depends on. Since multiple composite applications can share a
service, a single service failure can affect many applications. SLAs must be
defined to describe the reliability and performance consumers can depend on.
Service providers must be monitored to ensure that they're meeting their defined
SLAs.
A related issue is problem determination. When a composite application stops
working, why is that? It may be that the application head, the UI that the users
interface with, has stopped running. But it can also be that the head is running
fine, but some of the services it uses, or some of the services that those services
use, are not running properly. Thus it is important to monitor not just how each
application is running, but also how each service (as a collection of providers)
and individual providers are also running. Correlation of events between services
in a single business transaction is critical.
Such monitoring can help detect and prevent problems before they occur. It can
detect load imbalances and outages, providing warning before they become
critical, and can even attempt to correct problems automatically. It can measure
usage over time to help predict services that are becoming more popular so that
they can run with increased capacity.
Service ownership
When multiple composite applications use a service, who is responsible for that
service? Is that person or organization responsible for all of them? One of them;
if so, which one? Do others think they own the service? Welcome to the
ambiguous world of service ownership.
Any shared resource is difficult to acquire and care for, whether it is a
neighborhood park, a reusable Java framework, or a service provider. Yet a
needed pooled resource provides value beyond any participant's cost: Think of a
public road system.
Often an enterprise organizes its staff reporting structure and finances around
business operations. To the extent that an SOA organizes the enterprise's IT
around those same operations, the department responsible for certain
operations can also be responsible for the development and run time of the IT for
those operations. That department owns those services. Yet the services and
composite applications in an SOA often do not follow an enterprise's strict
47
hierarchical reporting and financial structure, creating gaps and overlap in IT

responsibilities.
A related issue is user roles. Because a focus of SOA is to align IT and business,
and another focus is enterprise reuse, many different people in an organization
have a say in what the services will be, how they will work, and how they'll be
used. These roles include business analyst, enterprise architect, software
architect, software developer, and IT administrator. All of these roles have a stake
in making sure the services serve the enterprise needs and work correctly.
An SOA should reflect its business. Usually this means changing the SOA to fit
the business, but in cases like this, it may be necessary to change the business
to match the SOA. When this is not possible, increased levels of cooperation are
needed between multiple departments to share the burden of developing
common services. This cooperation can be achieved by a cross-organizational
standing committee that, in effect, owns the services and manages them.
Service testing
The service deployment lifecycle includes the test stage, during which the team
confirms that a service works properly before activating it. If a service provider is
tested and shown to work correctly, does the consumer need to retest it as well?
Are all providers of a service tested with the same rigor? If a service changes,
does it need to be retested?
SOA increases the opportunity to test functionality in isolation and increases the
expectation that it works as intended. However, SOA also introduces the
opportunity to retest the same functionality repeatedly by each new consumer
who doesn't necessarily trust that the services it uses are consistently working
properly. Meanwhile, because composite applications share services, a single
buggy service can adversely affect a range of seemingly unrelated applications,
magnifying the consequences of those programming mistakes.
To leverage the reuse benefits of SOA, service consumers and providers need to
agree on an adequate level of testing of the providers and need to ensure that
the testing is performed as agreed. Then a service consumer need only test its
own functionality and its connections to the service, and can assume that the
service works as advertised.
Service security
Should anyone be allowed to invoke any service? Should a service with a range
of users enable all users to access all data? Does the data exchanged between
service consumers and providers need to be protected? Does a service need to
be as secure as the needs of its most paranoid users or as those of its most
lackadaisical users?
48
Security is a difficult but necessary proposition for any application. Functionality

needs to be limited to authorized users and data needs to be protected from
interception. By providing more access points to functionality (that is, services),
SOA has the potential to greatly increase vulnerability in composite applications.
SOA creates services that are easily reusable, even by consumers who ought not
to reuse them. Even among authorized users, not all users should have access
to all data the service has access to. For example, a service for accessing bank
accounts should only make a particular user's accounts available, even though
the code also has access to other accounts for other users. Some consumers of
a service have greater needs than other consumers of the same service for data
confidentiality, integrity, and nonrepudiation.
Service invocation technologies must be able to provide all of these security
capabilities. Access to services has to be controlled and limited to authorized
consumers. User identity must be propagated into services and used to
authorize data access. Qualities of data protection have to be represented as
policies within ranges. This enables consumers to express minimal levels of
protection and maximum capabilities and to be matched with appropriate
providers who may, in fact, include additional protections.
https://www.ibm.com/software/solutions/soa/gov/
http://www.ibm.com/developerworks/ibm/library/ar-servgov/
http://www.ibm.com/developerworks/rational/downloads/06/plugins/rmc_
soa_gov/overview.html
http://www.ibm.com/developerworks/wikis/display/woolf/SOA+Governance
?showChildren=false&decorator=printable
1.4 SOA summary

Service-oriented architecture and Web services enable new opportunities for
more flexible, rapid, and widespread integration in a model that is consistent with
the exposure of business function as services. SOA and Web services offer the
choreography of those services into processes that can be modeled, executed,
and monitored with features such as:
SOA defines concepts and general techniques for designing, encapsulating,
and invoking reusable business functions through loosely bound service
interactions. Most of the techniques have been proven individually in previous
49
technologies or design styles. SOA unites them in an approach that is

intended to bring encapsulation and reuse to the enterprise level.
Web services provide an emerging set of open-standard technologies that
can be combined with proven existing technologies to implement the
concepts and techniques of service-oriented architecture.
Industry support for Web services standards, interoperability among different
implementations of Web services, and the infrastructure technology that is
required to support a service-oriented architecture give technology customers
increasingly mature and sophisticated technologies that are suitable for
service-oriented architecture implementation.
These techniques and technologies give you the tools that are required to
implement flexible service-oriented architectures and to evolve toward an on
demand business model. However, SOA is an architectural approach, not a
technology or a product. In order to implement an SOA, you must have the
infrastructure to support the architecture, such as an Enterprise Service Bus and
a service registry and repository.
http://download.boulder.ibm.com/ibmdl/pub/software/dw/webservices/ws
-soa-whitepaper.pdf
50
Part 2
Part
WSRR concepts
and architecture
51
52
Chapter 2.
Concepts and architecture

This chapter provides an overview of WebSphere Service Registry and
Repository concepts and architecture:
2.1, Overview of WebSphere Service Registry and Repository on page 54
2.2, Architecture of WebSphere Service Registry and Repository on
page 66
53
2.1 Overview of WebSphere Service Registry and

Repository
IBM WebSphere Service Registry and Repository (WSRR) is a tool that enables
better management and governance of your services. Through its registry and
repository capabilities and its integration with IBM SOA Foundation (see to 1.1.2,
The SOA Foundation on page 6), WebSphere Service Registry and Repository
is an essential foundational component of a service-oriented architecture (SOA)
implementation.
WSRR enables you to store, access, and manage information about services
and service interaction endpoint descriptions (referred to as service metadata) in
an SOA. This information is used to select, invoke, govern, and reuse services as
part of a successful SOA.
This service information includes traditional Web services that implement Web
Services Description Language (WSDL) interfaces with SOAP/HTTP bindings as
well as a broad range of SOA services that can be described using WSDL, XML
Schema Definition (XSD) and policy decorations, but might use a range of
protocols and be implemented according to a variety of programming models.
Note: For more information about the IBM SOA programming model and how
it relates to the notion of service, see the Introduction to the IBM SOA
Programming Model at:
http://www.ibm.com/developerworks/webservices/library/ws-soa-prog
model/
You can use WebSphere Service Registry and Repository to store information
about services in your systems, or in other organizations' systems, that you
already use, that you plan to use, or that you want to be aware of. For example,
an application can check with WSRR just before it invokes a service to locate the
most appropriate service that satisfies its functional and performance needs.
This capability helps make an SOA deployment more dynamic and more
adaptable to changing business conditions.
WebSphere Service Registry and Repository includes:
A service registry that contains information about services, such as the
service interfaces, its operations, and parameters
A metadata repository that has the robust framework and extensibility to suit
the diverse nature of service usage
54
The following sections give more detail on what WSRR is and what its functions
are in a service-oriented architecture, and just as importantly, what WSRR is not
intended for.
2.1.1 What is WebSphere Service Registry and Repository?

As the integration point for service metadata, WebSphere Service Registry and
Repository establishes a central point for finding and managing service metadata
acquired from a number of sources, including service application deployments
and other service metadata and endpoint registries and repositories, such as
Universal Description, Discovery, and Integration (UDDI). It is where service
metadata that is scattered across an enterprise is brought together to provide a
single, comprehensive description of a service. Once this happens, visibility is
controlled, versions are managed, proposed changes are analyzed and
communicated, usage is monitored and other parts of the SOA foundation can
access service metadata with the confidence that they have found the copy of
record.
WebSphere Service Registry and Repository does not manage all service
metadata, and it does not manage service metadata across the whole SOA
lifecycle. It focuses on a minimalist set of metadata that describes capabilities,
requirements, and the semantics of deployed service endpoints. It interacts and
federates with other metadata stores that play a role in managing the overall
lifecycle of a service.
In summary, WebSphere Service Registry and Repository:
Provides awareness of service associations and relationships while
encouraging reuse of services to avoid duplication and reduce costs.
Enhances connectivity with dynamic service selection and binding at runtime.
Enables governance of services throughout the service lifecycle.
Ensures interoperability of services with a registry and repository built on
open standards. Use other standard registries and repositories to ensure a
unified view across a variety of service information sources.
Helps institute best practices and enforce policies in SOA deployments.
Registry and repository

System of records for service information and metadata
Service metadata artefacts exist across an enterprise in a variety of
heterogeneous development and runtime stores which often provide information
about a service tailored towards use cases in a particular phase of the SOA
life-cycle. Examples include Asset Management systems in the development
Chapter 2. Concepts and architecture
55
space or Configuration Management systems in the runtime space (see

Reusable business functions on page 23).
Service metadata plays a key role in an SOA as it can be used to describe and
enrich SOA concepts such as services, providers, consumers or contracts.
These elements provide contextual as well as operational information about the
overall system and can influence the way it is behaving. An example of such
information is the definition of service endpoints to be used in a service
interaction, indication of service ownership, or elements of service performance
such as the average response time or the error rate for a particular service.
In this context, WSRR mostly focuses on handling the metadata management
aspects of operational services and provides the system of record of these
metadata artefacts the place where anybody looking for a catalogue of all
services deployed in or used by the enterprise would go first.
To fully support this role of a system of record for service related information and
metadata, WSRR exhibits both registry and repository capabilities:
It provides registry functions supporting publication and retrieval of metadata
about services, their capabilities, requirements and semantics of services that
enable service consumers to find services or to analyze their relationships.
And it provides repository functions to store, manage and version service
information and metadata. In that respect, WSRR really owns part of the
service information and metadata and is able to play a key role in the overall
SOA governance by governing and controlling the entities it manages.
Metadata and policy driven SOA

Part of the metadata stored and managed by WSRR may constitute policies that
constrain and drive different aspects of the SOA. For example, you might want to
define security policies and relate them to the services that are defined in
WSRR. Another example would be to describe Service Level Agreements (SLA)
and bind them to service providers and consumers as part of the overall service
information model managed by WSRR.
Such policies would influence and drive the behavior or the overall SOA by
constraining or relaxing some of the aspects of this system of services. For
example, defining security policies to control access and usage of services and
storing them in WSRR would help in the implementation of an overall security
model applied to an ecosystem of services. Defining service providers
capabilities and service consumers expectations in the form of Service Level
Agreements and relating these definitions to service interactions would also
contribute to the ability to control and manage the overall SOA.
As a system of record for service information and metadata, WebSphere Service
Registry and Repository is a natural fit for the definition, the promotion and
56
possibly the application of service oriented policies (service oriented in the

sense that these policies apply to services) across the different actors and
components of the SOA. In that context WSRR might take care of different
aspects:
The definition of service-oriented metadata and policies by leveraging a rich
and extensible information model
The promotion of service-oriented policies and metadata across the multiple
actors and components of an SOA by providing extended access capabilities
to retrieve the pieces of information (see Integration point with other SOA
components on page 57)
The enforcement of some service-oriented policies in relation with the overall
governance model of the SOA (see Enabler for SOA governance on
page 57 for more information)
Integration point with other SOA components

WebSphere Service Registry and Repository provides extended capabilities to
promote service information and metadata across all the components of the
architecture.
The type of information exchanged depends on the context of the integration and
the stage in the SOA Foundation lifecycle where it takes place. The alignment
between a service registry and repository and the other SOA components has
already been described in the text following Figure 1-11 on page 35. More details
on these possible integration scenarios are provided later in this book.
To enable this integration and the promotion of service information and metadata
among a broad community of components, environments and stages, WSRR
provides the following capabilities:
Various interfaces and APIs supporting different interaction contexts,
protocols and technologies such as EJB, Web Services, JMX, GUI and
command line
Complete security model to control these integration cases and restrict
access to the managed resources
Auditing mechanism to trace the operations taking place as part of these
integration cases
Enabler for SOA governance

For a service-oriented architecture to be successful, it requires an expanded
scope of governance centered around the reconciliation of multiple points of view
and interest, such as business versus IT and development versus operations,
and across different lines of business with different priorities. Coming up with a
consistent service process model to meet these reconciled objectives is also key.
57
SOA governance tasks serve the entire SOA lifecycle, insuring service
cooperation, service technology compatibility, and proper service investment and
reuse.
WebSphere Service Registry and Repository plays a key role in the end-to-end
SOA governance. While the scope of SOA governance is definitively broader
than what WSRR provides support for, it is important to stress the fact that
WSRR must be considered as an enabler for SOA governance. WSRR supports
governance of service metadata throughout the lifecycle of a service from its
initial publication in the development space to deployment to service
management.
The support for SOA governance that WSRR provides is the subject of
Chapter 5, SOA governance enablers on page 157. The following is a brief
summary of the main mechanisms WSRR provides to support SOA governance:
WSRR is a registry/repository that allows customers to both store and register
standards-based service metadata including WSDL, XSD and policy. This
gives customers the ability to have a copy of record for all service metadata
and thus ensure consistency throughout their enterprise.
The publication of service metadata through tooling, UI or API allows
customers to socialize their high value or standardized shared services
encouraging interoperability and reuse.
The ability to query and find service metadata is used at development time
through tooling, for reuse of interfaces and schemas as well as static binding
of service endpoints. At runtime WSRR service queries through the API allow
infrastructures such as the ESB to make dynamic endpoint selection
decisions based on metadata in the registry.
The capture of service dependencies allows the impact of changes to be
assessed. Consumers of services that are impacted by the change can be
notified and thus take advantage of improvements and ensure that no
degradation in quality of service occurs.
WSRR provides a basic mechanism for associating policies to services which
allows the infrastructure (for example, ESB, Tivoli) or application code to
interpret and enforce the policy. This gives agility since policy is configured in
the registry which can be changed quickly (without redeployment) but is still
subject to governance.
WSRR allows client applications (and other middleware) to extend the
metadata that can be represented beyond the out-of-the-box
standards-based metadata. By providing user defined classifications,
properties and relationships, WSRR can be extended to support any
enterprise service metadata model.
58
WSRR supports validation plugins that can be configured to run whenever

actions are performed against the registry. This means service metadata
updates can be validated ensuring metadata integrity and (JMS) events
generated to allow external applications to respond to the changes.
For more information about SOA governance, see 1.3, SOA governance on
page 40.
2.1.2 The limits of WebSphere Service Registry and Repository

In the previous section, we give a broad overview of what WebSphere Service
Registry and Repository is, and what functions it can perform in a
service-oriented architecture environment. In this section, we continue to define
what WSRR is, while at the same time pointing out specific functions or aspects
of an SOA that WSRR does not address.
Analyzing what a component is not designed to do helps to frame and emphasize
the scope of its responsibilities and capabilities. In the light of the elements
previously described, we can now briefly list features and function not included in
the WSRR scope of responsibility:
WSRR is not a broker component to mediate/route service interactions
WSRR is not a generic policy decision/enforcement point
WSRR is not a generic content management solution
WSRR is not a source configuration/asset management solution
WSRR is not an enterprise wide metadata repository
WSRR is not the definitive SOA governance tool
WSRR is not a UDDI registry
WSRR is not a system management solution
Not a broker component

WebSphere Service Registry and Repositorys main responsibility is to stand as
a system of records for service oriented information and metadata. It does not
replace any service broker component such as the Enterprise Service Bus
(ESB), but rather complements these with extensive capabilities to query service
information and metadata which would then be leveraged by these middleware
components to route service requests and enforce service oriented policies.
WSRR does not route service requests on its own nor does it act as an
intermediary in the service invocation chain.
59
For a further detail, see 1.1.5, Supporting elements of the SOA reference
architecture on page 14 and 1.2.7, Enterprise Service Bus and SOA on
page 28.
Not a generic policy decision/enforcement point

While WebSphere Service Registry and Repository can store and manage
service oriented policies as described in Metadata and policy driven SOA on
page 56, it should not be considered as a generic policy decision/enforcement
point. The responsibilities of WSRR in regard to service oriented policies are the
following:
Description, management and promotion of service oriented metadata and
policies across the different components of the SOA: one can leverage
WSRR information model to capture and store service oriented metadata and
policies. WSRR query capabilities and interfaces provide access to that
information to the different components of the SOA (for example, ESB,
Service Gateway, Security Components...) which would then use it to enforce
service oriented policies.
Decision and enforcement point for some service oriented policies: while
WSRR is definitively not a generic policy decision and enforcement point,
some policies might be best enforced in WSRR itself. Examples might include
some policies related to the governance and service lifecycle model as
described here:
Compliance policies (for example, compliance with WS-I profiles or
compliance with organization specific rules)
Security policies (for example, constrained access to service information
and metadata to represent structured service ownership and visibility
model)
Not a generic content management solution

WebSphere Service Registry and Repository is SOA and service centric in
nature. It has not been designed to act as a generic content management
solution and does not provide extended capabilities around information
capturing, indexing or archiving.
WSRR is specifically targeted at service information and metadata and cannot
replace existing enterprise content management solutions. However,
relationships can be described to materialize potential links that might exist
between service oriented content managed in WSRR and pieces of information
residing in other sources of data.
60
Not a source configuration/asset management solution

WebSphere Service Registry and Repository is not a source configuration/asset
management solution in that it does not try to address the usual requirements for
these solutions:
It does not aim to store all the artefacts (including source code, deployment
descriptors...) that make up a service, but rather only to manage service
description and metadata.
It does not try to capture services as packaged assets (including associated
documentation, deployment scripts, test scripts...) but should rather focus on
the minimalist amount of information necessary to describe, classify and
access these services.
However, as pointed out in the previous section (Not a generic content
management solution), links can be described in WSRR to materialize possible
relationships between the service registry and repository and other source of
information such as source code or asset management solutions. These links will
become obvious depending on the context WSRR is used in, and specifically on
the positioning of WSRR in the service lifecycle.
As illustrated in Figure 2-1 WSRR must clearly be considered to span the overall
service lifecycle, including development and operational activities, and has to, in
that respect, integrate with other sources of information targeted at specific parts
of that lifecycle.
WebSphere
Integration
Developer
WebSphere
Service
Registry and
Repository
Info
Services
Director
WebSphere
Business
Modeler
Rational
Application
Developer
Figure 2-1 WSRR and service oriented information and metadata exchange in the SOA
lifecycle
61
Development and modeling tools such as WebSphere Integration Developer,

WebSphere Business Modeler or Rational Application Developer all deal with
service information and metadata in the context of their usual scope of
application in the overall SOA lifecycle. To do so they have to exchange elements
of information with WSRR in a bi-directional fashion:
For example, service development requires use of and writing to a different
kind of repository, such as an asset repository. However once a service exits
development, often at deployment to a post-development environment, the
service metadata will usually be copied to WSRR.
On the other hand, consuming a service in a development environment also
requires service description and information to be retrieved from WSRR.
These interaction points are usually mandated at different stages within the
service lifecycle or triggered as the result of specific events, in order to keep track
and govern the notion of service and its different perspectives throughout the
overall SOA lifecycle.
Not an enterprise wide metadata repository

While WebSphere Service Registry and Repository does provide information and
metadata management capabilities, it does not aim to stand as the single source
of service information in the enterprise. The service oriented information is
spread across multiple sources as a result of multiple aspects of a SOA such as:
Multiple delivery channels (twin consumer/provider tracks): information
related to service consumers and providers is often physically separated and
might not be easily reconciled into a single repository
Extended scope of service lifecycle: as pointed out earlier, because of the
rather large scope of the service lifecycle in an enterprises processes WSRR
cannot accommodate all service related information and metadata but rather
references external sources of data
Organizational and governance constraints: SOA spans lines of business, this
might imply that the information owned by these LoB and governed as part of
separate governance domains is defined and managed in different
repositories used and operated by different people.
Operational and regulatory constraints: service information may span multiple
environments within an organization, leading to the need to have physically
separate repositories to accommodate various constraints between these
environments (for example, security, connectivity...). This might also be the
result of some regulations imposing a requirement that pieces of information
and metadata be physically stored and managed in specific locations or
geographies.
Technical constraints: multiple products and technologies can be used to
manage information and metadata, depending on both functional (for
62
example, the availability of a predefined information model for a specific

industry) and non-functional (for example, scalability, quality of information...)
requirements.
As a matter of fact, WSRR can be considered to mostly focus on the operational
aspects of services in a SOA, while the rest of the information is owned and
managed by other sources such as asset management, configuration
management, identity management or generic information management
solutions.
The logical reconciliation of these islands of information usually follows a master
and satellite topology where master copies of records are centrally managed
and exchange information with satellites sources dedicated to specific aspects of
the information lifecycle.
Figure 2-2 on page 64 describes and extends these notions in the context of
information services built using the IBM software portfolio. Two master copies of
records, namely WebSphere Service Registry and Repository and WebSphere
Metadata Server exchange information with their respective satellites. These two
masters also exchange service information between them as part of the service
lifecycle. Figure 2-2 on page 64 illustrates these interactions using the following
use cases:
Expose information services using WebSphere Information Server and
publish it to WebSphere Service Registry and Repository
Discover information services and associated metadata using WebSphere
Integration Developer from the information managed by WebSphere
Information Server
63
IBM Information Server

Unified Deployment
Understand
Clense
Info Svc 1:
ValidateAddress
Discover, model, and

govern information
structure and content
Transform
Info Svc 2:
OrderHistory
Standardize, merge,
and correct
information
Combine and
restructure information
for new uses
Transform
Info Svc 3:
AccountInfo
Publish
Information
Service
Combine and
for new uses
Publish
Enrich
Find
Manage
Govern
Unified Metadata Management

Parallel Processing
Rich Connectivity to Applications, Data and Content
WebSphere
Integration
Analyzer
WebSphere
Integration
Developer
3rd
Party...
WebSphere
QualityStage
Sharing of
Service Metadata
WebSphere
Metadata
Server
WebSphere
Service
Registry and
Repository
Info
Services
Director
RDA
Info
Services
Director
WebSphere
DataStage
WebSphere
Business
Modeler
Rational
Application
Developer
IBM Information Server

Unified Deployment
Understand
Clense
Info Svc 1:
ValidateAddress
Discover, model, and

govern information
structure and content
Transform
Info Svc 2:
OrderHistory
Standardize, merge,
and correct
information
Combine and
for new uses
Transform
Info Svc 3:
AccountInfo
Combine and
for new uses
Discovery of Services
and metadata
Unified Metadata Management

Parallel Processing
Rich Connectivity to Applications, Data and Content
Figure 2-2 Sharing of service metadata across masters and satellites
Not the definitive SOA governance tool

While WebSphere Service Registry and Repository and SOA governance are
closely related, it must be clearly understood that the aim of WSRR is not to
provide support for the entire enterprise wide SOA governance framework, but
rather to enable parts of it. In that respect, WSRR really focuses on the service
lifecycle as a prime governed domain.
By leveraging WSRR capabilities such as the following:
defining permission rules on the information model
customizing the service lifecycle model to drive and enforce the state of
governed entities as they transit through this model,
or implementing validation points to ensure compliance and correctness of
parts of the information model,
64
WSRR helps enable an overall SOA governance framework.

See Enabler for SOA governance on page 57 for more information. See
Chapter 5, SOA governance enablers on page 157 for additional detail on SOA
governance.
Not a UDDI registry

Universal Description, Discovery and Integration (UDDI) provides a standardized
API and model to describe, classify and access service information and
metadata. It also provides corresponding methods to manipulate and query the
UDDI model. The UDDI V3 specification was ratified as an OASIS Standard in
February 2005. The UDDI specification defines a registry that evolved from an
Internet service directory to a Web services registry specification. The SOA
requirements described in Chapter 1, Introduction to SOA on page 3 go beyond
the capabilities of UDDI, specifically in that SOA requires integration with
repository and service lifecycle.
Specifically, the UDDI specification falls short of what is required for a complete
service registry and repository solution:
UDDI is satisfactory for simple endpoint lookups.
UDDI is not well suited for more advanced, general service metadata artefact
retrieval. From the inception of UDDI, the focus was on finding services,
usually Web services, and usually by humans at development time. Typical
use cases for UDDI would not include runtime usage by demanding
middleware. This is reflected in cumbersome and inefficient APIs for routine
runtime use (creative artefact decomposition and mapping to the UDDI model
often leads to inefficient search and retrieval paths, often requiring repeated
use of different parts of the UDDI API).
Emerging SOA use cases require that metadata and relationships be
associated with pieces of service descriptions not originally foreseen by
UDDI, such as associating policy with individual messages bound to
operations. The UDDI information model does not allow fine grained
description and manipulation of smaller pieces of service related elements
such as operations, messages and policies.
Because UDDI is not a repository with fine grained search of artefacts,
searchable metadata must be extracted from referenced artefacts and
mapped to the UDDI data model to be able to be queried. This would require
proprietary decomposition and mapping conventions for emerging artefact
types, relationships between artefacts, increasing artefact granularity,
consumer SLA requirements and governance support.
Also, the lack of repository capabilities prevents UDDI from actually storing
and owning the artefacts, and thus from acting as a master copy of records of
65
the service artefacts. This severely limits its ability to control and govern their
change.
Note: For more information about UDDI, refer to:
http://www.uddi.org/
Not a complete system management solution

WebSphere Service Registry and Repository stores and manages service
information and metadata. This may include operational information about
service behavior, status and compliance with predefined SLA. Such information
would have been provided by external dedicated components in the SOA
infrastructure such as management and monitoring solutions.
However, WSRR is not in itself a complete system management solution as it
does not exhibit the capabilities to actually monitor service execution at runtime.
Integration between WebSphere Service Registry and Repository and IBM Tivoli
Composite Application Manager for SOA is described in Chapter 15, Integrating
WSRR with ITCAM for SOA on page 625 and provides a good example of this
type of collaboration between a service registry and repository and some SOA
management solution.
2.2 Architecture of WebSphere Service Registry and

Repository
Figure 2-3 on page 67 provides a brief overview of how all the key building blocks
fit together within the WebSphere Service Registry and Repository architecture.
66
User
User
Interface
Interface
Web
Eclipse
Plug-in
External
Systems
ESBs
Process
Servers
Appliances
Monitors
3rd
Party
Registries &
Repositories
Events
Generated
Programming
Programming
Interfaces
Interfaces
Content models
RDB
Extensions
Extensions &
&
Integrations
Integrations
SOAP
Java
Registry
Registry &
& Repository
Repository
Admin
Admin
Governance
Governance
Create
Create
Retrieve
Retrieve
Update
Update
Delete
Delete
Query
Query
JMX
Import
Import // Export
Export
Configure
Configure
Transition
Transition
Validate
Validate
Notify
Notify
Impact
Impact Analysis
Analysis
Audit
Audit
Validation
Access Control
Lifecycle
Notification
Classifications
Validators
Events
Generated
Figure 2-3 Overview of WebSphere Service Registry and Repository architecture
WebSphere Service Registry and Repository is essentially a Java 2 Platform

Enterprise Edition (J2EE) application that runs on WebSphere Application
Server. As such, it takes advantage of the role-based access control provided by
the application server. When WSRR is deployed as an enterprise-wide
application in your environment, it is recommended that security be turned on.
This enables role-based views and access control, and this is tied to many of the
WSRR governance capabilities.
This J2EE application provides a core group of functions such as registry and
repository, governance, and administration, all of them supported by shared
access control and classification capabilities (see Figure 2-3). As mentioned
previously, some of these features rely on the infrastructure services provided by
the J2EE environment WSRR is running in.
WebSphere Service Registry and Repository uses a relational database as a
backend store for service information and metadata persistence. WSRR contains
service information and metadata artefacts that are in the form of XML
documents. You can put any XML document into WSRR, but there are some
types that are special, such as WSDL and XSD. These special types are
modeled, and when one of these special types of document is loaded into
WSRR, it is parsed into a finer-grained information model.
67
You can also define non-XML pieces of information (referred to as

GenericObjects) that represent service metadata entities that are not backed by
a document in WSRR.
To manipulate service information and metadata you can use the programming
and user interfaces to perform basic Create, Retrieve, Update, and Delete
(CRUD) operations on the content, and flexible queries based on XPATH
expressions against the content.
You can use J2EE Stateless Session Beans or Web services to interact with
WSRR programmatically. You can also use a Web application or an Eclipse
plug-in to interact with service metadata stored and managed by WSRR through
dedicated user interfaces.
2.2.1 Overview of main components

The following sections introduce the key elements of the WebSphere Service
Registry and Repository architecture. Refer to Figure 2-3 on page 67 to
determine where each of the components fit in the WSRR architecture.
Note: These architectural elements and the use cases they support are
elaborated in more details in the remaining chapters of this book.
Registry and Repository

WebSphere Service Registry and Repository offers both registry and repository
capabilities for service metadata. The repository allows users to store, manage
and query service metadata artefacts holding service descriptions (WSDL, XSD,
WS-Policy, SCDL or XML documents). It not only takes good care of the
documents containing service metadata, but it also provides a fine-grained
representation of the content of those documents (for example, ports and
portTypes in WSDL documents). In addition, it provides registry functions for
decorating registered service declarations and elements of the derived
information models with user-defined properties, relationships, and classifiers.
WSRR provides a rich query interface that makes use of those decorations when
you want to find a service endpoint or service interface.
Whenever a change to registry or repository content is detected by WSRR, it
invokes all validation and notification plugins that are registered. Both kinds of
plugins are considered extension mechanisms that you can use to customize
how you want Registry and Repository to react to changes. You can write and
register validation functions that WSRR will then execute when changes are
made to the content. For example, you can write and register a validation
function that checks for completeness of a service definition. You can also write
and register notification functions to communicate changes in the content of the
68
repository. WebSphere Service Registry and Repository comes with an

out-of-the-box JMS notification plugin which posts notification messages to a
JMS queue. By registering listeners to that queue it is possible to consume these
messages and turn them into context or channel specific actions and
notifications (for example, e-mail or SMS). WSRR also has a subscription
capability that allows your users to register their interest in consuming
notifications.
Governance functions
WebSphere Service Registry and Repository supports a rich set of extensible
governance functions, including the ability to model your own service lifecycle
model for governed entities, define valid transitions between service states, write
and plugin validators to guard the transitions between states, and designate
(notification) actions to be taken as result of the transition. It also provides
interfaces to analyze the impact of changes to WSRR content, and provides
auditing of such changes.
Classifications
Classifications play a major role in many interactions with WebSphere Service
Registry and Repository. They allow you to annotate service descriptions and
parts of service definitions with your corporate vocabulary and extend the service
information model with additional information which are relevant to your particular
context. For example, you can use classifications to segregate service endpoints
that are deployed in different environments. Classifications are also used by
WSRR to capture the governance state. WebSphere Service Registry and
Repository classification systems are captured as ontologies in Web Ontology
Language (OWL) documents that you load into WSRR using the administrative
interface. You can then classify managed entities with values from these
classification systems, which allows you to perform classification-based queries,
and restrict access based on classification.
69
Note: In computer science, an ontology is a data model (a model that

describes in an abstract way how data are represented in a business
organization) that represents a domain (the relevant set of entities that are
being dealt with by quantifiers) and is used to derive conclusions about the
objects in that domain and the relations between them. An ontology is a
description of the concepts and relationships that can exist for an agent or a
community of agents. It is generally written as a set of definitions of formal
vocabulary.
OWL stands for Web Ontology Language. Where earlier languages have been
used to develop tools and ontologies for specific user communities
(particularly in the sciences and in company-specific e-commerce
applications), they were not defined to be compatible with the architecture of
the World Wide Web in general, and the Semantic Web in particular.
OWL uses both URIs for naming and the description framework for the Web
provided by RDF (Resource Description Framework) to add the following
capabilities to ontologies:
Ability to be distributed across many systems
Scalability to Web needs
Compatibility with Web standards for accessibility and internationalization
Openness and extensibility
OWL builds on RDF and RDF Schema and adds more vocabulary for
describing properties and classes: among others, relations between classes
(for example, disjointedness), cardinality (for example, exactly one), equality,
richer typing of properties and characteristics of properties (for example,
symmetry), and enumerated classes.
For more information about OWL, visit the following URL provided by W3C as
part of the Semantic Web Activity:
http://www.w3.org/2004/OWL/
Access control model

In addition to the role-based access control provided by the underlying
WebSphere Application Server, WebSphere Service Registry and Repository
supports a fine-grained access control model that allows you to define which
user roles can perform specific types of actions on corresponding artefacts. You
can capture Access Control Rules in XACML and reference lifecycle states and
semantic annotations such as classifications, and properties. This allows you to
restrict visibility of services by business area or to restrict which user roles can
transition services to certain lifecycle states.
70
Administration interfaces
These interfaces support the import and export of WSRR content for exchange
with other repositories and provide a JMX-based API for configuration and basic
administration. These support interactions with the Access Control model and
with the Classification Systems.
Programming interfaces
You can use Java and SOAP APIs to interact programmatically with WSRR.
These APIs provide basic CRUD (create. retrieve, update, and delete)
operations, governance operations, and a flexible query capability based on
XPath. You can use the SOAP API to communicate content using XML data
structures or the Java API to communicate content using SDO data graphs.
User interfaces
Two user interfaces are provided that enable you to interact with WebSphere
Service Registry and Repository.
A servlet-based Web User Interface (UI) is the main way for your users,
representing different roles, to interact with WSRR. This UI supports look-up and
publish scenarios, metadata management and analysis scenarios, and functions
that support SOA governance.
Your developer roles can also work with WSRR using an Eclipse plug-in that
supports look-up, retrieval, and publishing of service metadata from your
Eclipse-based development tools or management consoles.
Command line interface

A command line interface is provided to perform a mix of regular and
administration operations using scripting capabilities.
2.2.2 Information model

This section provides a brief description of WebSphere Service Registry and
Repositorys information model. A complete description of this model is provided
in Chapter 3, Information model on page 79.
Other documentation may to the WSRR information model as a content model.
In this redbook, we use the term information model.
The WebSphere Service Registry and Repository information model has
elements representing service description entities (such as WSDL) and service
description metadata (such as Classifications). All WSRR elements have a
WSRR-assigned URI, a name and a description.
71
Service description entities are artefacts and documents created and managed
in WSRR, both physical and logical, and describe the service. For example
WSDL, PortType.
Service description metadata is used to decorate service description entities with
attributes like Properties and Relationships with other elements.
Figure 3-1 on page 80 depicts an overview of WSRRs content model. See
Chapter 3, Information model on page 79 for more information.
2.2.3 Interfaces and APIs

You can use the programmatic and user interfaces that WebSphere Service
Registry and Repository provides to interact with and manage its content.
Using WSRR, you can create, retrieve, update and delete documents and
GenericObjects managed by it. However, you cannot modify entities in the logical
model. You can only change these by updating the document that contains the
logical entity. GenericObjects can be created, retrieved and deleted. You can also
change all semantic decorations on all entity types. Last but not least, you can
govern services and related information elements as they go through their
lifecycle.
Query interface
You can interact with the WebSphere Service Registry and Repository query
interface in two ways:
You can use one of the predefined queries that are configured via parameters
(for example, all WSDL documents with classifier X).
You can write your own XPath-based query.
You can use XPath expressions in the Query API to perform searches for coarse
and fine-grained queries. Queries can be performed using semantic annotations,
properties, and all or parts of the physical service metadata artefacts. You can
request that fragments of metadata be returned (such as endpoints), all
metadata be returned, and both metadata and documents be returned. In
addition to free-form XPath-based queries, a set of pre-canned queries are
available for you to use to address common paths through the WSRR information
model.
When you use the XPath-based query interface, you create an XPath expression
that identifies the type of managed entity to be returned and a filter that captures
the managed elements related to the desired object. Extensions are provided for
you to include classification annotations in a query. For example, if you are
looking for all WSDL Services that have a port that refers to a binding referring to
72
a portType named StockQuotePortType, the following query expression would be

used:
//WSDLService[port/binding/portType/@name='StockQuotePortType'];
See 3.6, XPath on page 99 for additional information about XPath. See 3.9,
Query on page 103 for additional information about the Query interface.
User interfaces
Two user interfaces (refer to Figure 2-3 on page 67) are provided to access
WSRR:
A Web user interface
An Eclipse plug-in
Web user interface

The main interface is a Web application deployed with the WSRR runtime. This
supports all of your user roles, offering lookup, browse, retrieve, publish, and
annotate capabilities, as well as governance activities, such as import/export and
impact analysis.
The Web user interface supports customizable views of WSRR content
represented to a user. A set of user interface definition files describes the content
and layout of the various components that make up the Web user interface. The
concept of user-role-specific perspectives is supported. WebSphere Service
Registry and Repository comes with a set of predefined perspectives for the
most common user roles, but you can customize the predefined ones or
introduce new, role-specific perspectives.
See 4.3, Web user interface (Web UI) on page 144 and Chapter 10,
Customizing the Web UI on page 381 for additional information.
Eclipse plug-in
A subset of this user interface is offered as an Eclipse plug-in to meet the needs
of your developer and analyst users that use Eclipse based-tooling. The Eclipse
plug-in is used primarily for lookup, browse, retrieve and publish capabilities.
See Chapter 11, Using the WSRR Eclipse plug-in on page 415 for additional
information.
The Eclipse plug-in is not shipped with the WebSphere Service Registry and
Repository product distribution. It is available as a download from the following
URL:
http://www.ibm.com/support/docview.wss?rs=3163&context=SSWLGF&dc=D40
0&uid=swg24013925&loc=en_US&cs=UTF-8&lang=en
73
Command line interface

Interactive and scripted administration of WSRR is possible with the
Jython-based command line interface The command line interface provides full
support for all of the WSRR programmatic APIs, including all administrative
operations. It may be used from a standalone Jython or Jacl interpreter, or it may
be run inside wsadmin and used in conjunction with the facilities available there.
The command line interface uses both the JMX API and the SOAP API to
communicate with WSRR.
See 4.4, Command Line Interface on page 154 for additional information.
Supported APIs
End-users can interact directly with WSRR using a Web-based console
application or an Eclipse-based plug-in as mentioned previously. In addition,
applications can fully interact with WSRR using one or more of its application
programming interfaces (APIs) as shown in Figure 2-3 on page 67 and below:
A J2EE-based Java API (EJB)
A Web service SOAP-based API
An administration JMX-based API
Usage APIs
Note: We refer to both the EJB API and the SOAP API as usage APIs to
emphasize the fact that these APIs directly support WSRR regular use cases,
as opposed to administration operations which are performed via the JMX
API.
WebSphere Service Registry and Repository provides three different usage APIs
with dedicated scope and exposition as summarized in Table 2-1.
Table 2-1 WebSphere Service Registry and Repository usage APIs
74
API
Scope
Exposed
as EJB
Exposed as SOAP
Web service
Core
Create, Retrieve, Update, Delete,

Query
Yes
Yes
Ontology
Lookup of Ontology Classes and

Systems (Read only)
Yes
Yes
Governance
Make objects governable, transition

them, find the transitions that can be
made on the objects
Yes
No
Both the EJB and SOAP APIs support publishing (creating and updating)
service metadata artefacts and metadata associated with those artefacts,
retrieving service metadata artefacts, deleting the artefacts and their
metadata, and querying the content of WSRR through the Core API.
Read-only manipulation of ontologies and classification systems is provided
to EJB and SOAP clients through the Ontology API. Modification of ontology
and classification systems must be performed using the Web interface.
Governance operations are restricted to J2EE clients as the governance API
is exposed only as an EJB at the time of writing.
The EJB programming API uses Version 2 of Service Data Objects (SDO) to
capture the data graphs inherent in the information model, allowing access to
physical documents, logical parts of the physical documents, and
GenericObjects.
The SOAP API uses XML documents to similarly represent Service Data Objects
to communicate content structures in both the physical and logical model.
See 4.1, Java API (EJB) on page 120 and 4.2.3, SOAP API on page 139 for
additional information.
The governance API lets you analyze the impact of changes to specific artefacts.
A set of predefined impact queries is available to help you navigate through the
WSRR content according to popular patterns, such as which WSDL files import
or use a specific XSD.
Administration API
WebSphere Service Registry and Repository also provides a JMX-based
Administration API that supports basic configuration and loading and managing
of metadata in support of repository content, such as classification and lifecycle
management.
The Administration API allows you to load definitions of state machines to be
used to model the lifecycle of governed entities, and to load classification
systems described in OWL.
In addition, the Administration API supports registration of plugins for Validation
functions or additional Notification providers.
See 4.5, Admin (JMX) on page 155 for additional information.
75
2.2.4 Governance enablers

WSRR plays a key role in the end-to-end governance underpinnings of the SOA
lifecycle. WSRR enables governance of service metadata by leveraging some
built-in mechanisms:
The definition and the enforcement of service lifecycle for governed objects
The validation and notification of operations and events related to changes
and evolution in the service lifecycle or service information model
The definition, enforcement and accountability of security policies
constraining the visibility of the service information model and the operations
performed on it
Service lifecycle
WebSphere Service Registry and Repository provides support for the definition
and the enforcement of a lifecycle which is applied to each governed entity.
For each governed entity a state machine is defined that describes the lifecycle
states the entity can take on, the transitions between those states, conditions for
the transitions to be taken and actions to be taken should a transition be
performed. While WSRR provides a set of out-of-the-box lifecycle models, you
can define your own state machines to match with your requirements.
Validation
WSRR allows you to register validation functions that are run when basic CRUD
operations are executed against its content, and also in the context of the
governance model when lifecycle state transitions are operated on governed
objects. Validation functions must not have side-effects and must return a
Boolean result that can be used to veto the update.
An example of validation scenarios could include WS-I compliance checking for
services managed in WSRR.
Notification
WebSphere Service Registry and Repository provides basic event notification
features to allow exploiters to register their interest in any changes to WSRR
content. Initially notification will be based on JMS publication of events. These
events identify the type of the change and contain a pointer to the object that was
changed.
WSRR ships a default notification handler that publishes change events on a
JMS topic. The event specifies the type of event (create, update, delete or
transform), the artefact impacted (identified via its URI) and a few more bits of
information about the artefact. To avoid violating access control rules, the actual
76
content of the artefact in question is not shipped with the event and must be
retrieved separately.
Examples of notification scenarios could include an e-mail notification feature
that allows users to request an e-mail to be sent when an interesting event
happens such as the publication or the revocation of services in the overall
lifecycle.
Auditing
A simple Audit capability is provided that logs information about WSRR updates.
See Chapter 5, SOA governance enablers on page 157 for additional
information.
77
78
Chapter 3.
Information model
This chapter describes the information (metadata) model used in WebSphere
Service Registry and Repository (WSRR). It explains different types of service
metadata stored in WSRR.
Other documentation may refer to the WSRR information model as a content
model. In this redbook, we use the term information model.
The topics covered are:
3.2, Service description entities on page 80
3.3, Service description metadata on page 84
3.4, Templates on page 88
3.5, Document types on page 89
3.6, XPath on page 99
3.7, Service Data Objects (SDO) on page 99
3.8, BaseObject on page 101
3.9, Query on page 103
79
3.1 Introduction
The WebSphere Service Registry and Repository information model has
elements representing service description entities (such as WSDL) and service
description metadata (such as Classifications). All WSRR elements have a
WSRR-assigned URI, a name and a description.
Service description entities are artefacts and documents created and managed
in WSRR, both physical and logical, and describe the service. For example
WSDL, PortType.
Service description metadata is used to decorate service description entities with
attributes like Properties and Relationships with other elements.
Figure 3-1 is an overview of the different types of metadata stored in WSRR.
Service Description Entities
Service Description Metadata
Physical Documents
Properties
WSDL
XSD
SCDL
WS-Policy
XML User-defined Documents
..
name
namespace
version
description
modifiedDate
imports
includes
predecessor
User-defined
name
namespace
User-defined
metrics
derivedFrom
operations
messages
User-defined
Relationships
Logical derivations
Interface
Operation
Message
Type
Service
Binding
Endpoint
..
Metadata
applies to
all
entities
GenericObjects
User-defined by classification
Business Application
Business Process
Governed Collection
External reference
User-defined
owner
externalURL
User-defined
dependantServices
serviceInterface
governedEntities
policies
..
Classifications
User-defined
States
Created
Approved
Published
Operational
User-defined
Environments
Development
Test
Approval
Production
User-defined
GenericObjects
Application
Process
Capability
Standard Ontologies
NAICS
UNSPSC
ISO3166
Figure 3-1 WebSphere Service Registry and Repository information model
3.2 Service description entities

There are three kinds of service description entities that are stored and managed
in WSRR.
1. Physical documents
80
Physical documents are XML documents that are known as service metadata
artefacts.
2. Logical derivations
Logical derivations are the finer-grained pieces of content that result when
some types of physical documents are parsed as they are loaded into WSRR.
3. GenericObject
GenericObjects are generic entities that are usually typed, and represent
anything that is not represented by a document in WSRR.
You can interact with all three types of service description entities, using them in
queries, applying service annotations, and establishing relationships from and to
them.
3.2.1 Physical documents

The most elemental building blocks for the WSRR information model are service
metadata artefact documents (physical documents), such as XSD or WSDL files.
These service metadata documents are stored and managed in WSRR. The
coarse-grained model made up from registry objects that represent those
documents is referred to as the physical model.
Documents are versionable objects in WSRR information model, meaning that in
addition to a URI, name and description they also have a version property.
Any service metadata artefact type can be stored in WSRR and receive the
benefits of broader visibility and reuse, management, and governance.
WSRR offers advanced functions for a number of well-known SOA metadata
types. The key WSRR metadata document types are:

WS-Policy
Service Component Description Language (SCDL)
For details on these document types, see 3.5, Document types on page 89.
For these document types WSRR provides special services, including parsing of
the documents upon receipt into Logical Derivations. See 3.2.2, Logical
derivations on page 82.
Other types of service metadata can be stored using a generic content type:
XML Document; documents of type XMLDocument are not decomposed into the
logical derivations.
Chapter 3. Information model
81
3.2.2 Logical derivations

WSRR offers advanced functions for a number of well-known SOA metadata
types. These key metadata document types are: WSDL, XSD, WS-Policy, and
SCDL. For these document types, WSRR provides special services, including
parsing of the documents upon receipt into logical derivations or a set of logical
objects. Logical objects are not versionable.
Logical derivations or logical objects enable users to explore WSRR content
beyond the boundaries of the files stored. Logical objects cannot be individually
versioned since they are derived from a physical document (which can be
versioned) and cannot therefore be individually manipulated. Logical objects may
however have additional service description metadata allocated to them such as
properties, relationships and classifications.
For the key document types WSRR also defines a few predefined properties and
makes an effort to detect relationships to other key documents, and where
available, records those relationships in the information model. An
XSDDocument, for example, has a targetNamespace property and the
relationships importedXSDs, redefinedXSDs and includedXSDs. When an entry
for a key-type document is created in WSRR, it is introspected for relationships to
other key-type artefacts; if not already in represented in WSRR, these related
artefacts are also added, and in either case the relationship between the
artefacts is recorded.
The set of logical derivations comprises the logical model of WSRR. The logical
model has entities such as portType, port, and message related to WSDL files,
and complexType or simpleType related to XSD documents. Elements of the
logical model have properties and relationships reflecting a subset of their
characteristics as defined in the underlying document. For example, a
WSDLService element has a namespace property and a relationship to the ports
it contains. It is important to note that all the individual results of document
parsing are aggregated into one logical model that represents not only the
content of individual documents, but also the relationships between the content
in the different documents.
WSRR stores other types of service metadata using the XMLDocument, a
generic document type. Documents of type XMLDocument are not decomposed
into the logical model.
For more details, refer to section 3.5, Document types on page 89.
82
3.2.3 GenericObject
There is one other kind of entity in WSRR, referred to as a GenericObject. This is
a generic object that can be used to represent anything that does not have a
physical document in WSRR.
GenericObjects can be used to represent a reference to content in some other
metadata repository such as a portlet in a portlet catalogue, an asset in an asset
repository, service implementation artefacts kept in a source code library or
information about SOA infrastructure topologies in a configuration management
database.
Note: GenericObject is the API name for the objects that appear in the Web UI
as Concepts. Refer to 9.9, Concepts on page 370 for more information.
A GenericObject can be used to group physical artefacts together for ease of
retrieval. GenericObjects can be used to represent collections of documents or
other GenericObjects. GenericObjects can also be used to represent a
business-level view on the SOA metadata managed in WSRR; this could include
GenericObjects such as Business Process, Business Service, Business Object
and Business Policy.
A GenericObject is simply a container for metadata, there are no constraints as
to what it can be used to represent. This means that you must provide additional
metadata such as classifications or templates to distinguish between different
types of GenericObject and thus the properties and relationships that are
appropriate. It is up to client applications to enforce the interpretation of these
types. WSRR provides support through templates and validator plug-ins to
allow you to extend WSRR to perform this.
GenericObjects provide the following predefined properties:
Name
A mandatory name identifying the GenericObject. This must be

unique across all objects in the repository when combined with
the namespace and version properties.
Namespace
An optional namespace used to distinguish similarly named

objects.
Version
An optional textual string that identifies different versions of the

same name/namespace identified object.
Description
An optional textual description of the GenericObject.
GenericObjects can be created, modified, used and deleted using the Web UI
(see 9.9, Concepts on page 370) or the API (see Chapter 4, Interfaces and
APIs on page 119).
83
3.3 Service description metadata

In addition to content directly related to service description entities, WSRR
supports a number of user-defined metadata types that are used to decorate the
service description entities to explain their semantics; we refer to those metadata
as Service description metadata. See Figure 3-1 on page 80.
WSRR supports three types of service description metadata types:
1. Properties
2. Relationships
3. Classifications
All three types can be used to decorate entities in the physical or logical model,
and GenericObjects as well. For example, you would use service semantic
metadata to:
Associate a property businessValue with a physical model entity representing
a WSDL file.
Define a new relationship makesUseOf between an entity in the logical model
representing a portType and an entity in the physical model representing an
XML document.
Create a classifier importantThings and associate it with a port entity in the
logical model and with an entity in the physical model representing a Policy
document. This enables semantic queries to target individual elements of the
service metadata, and meaningful dependency analyzes to take place prior to
making changes.
3.3.1 Properties
Properties are simple name/value pairs that are associated with any of the
Service description entities.
Some properties are assigned by the system, such as the unique id, the owner,
and the last time the service entity was changed. These system-assigned
properties cannot be changed.
Others are derived through the parsing of a key-type service description
document into its logical model. Properties of this type include name and
namespace.
Sometimes you are allowed to change these system-assigned values. You can
also create your own properties. These are referred to as user-defined
84
properties. You can use user-defined properties as a simple, unstructured and

untyped extension mechanism.
Note: User-defined properties are referred to as Custom Properties in the
Web user interface.
WSRR treats general properties and custom properties in the same way and all
property values are treated as strings. Properties can be used in queries, and
can be used to establish fine-grained access control.
Properties can be created, modified, used and deleted using the Web UI (see
9.4, Properties on page 335) or the API (see Chapter 4, Interfaces and APIs
on page 119).
3.3.2 Relationships
In a SOA environment, organizations expect to see reuse and loose flexible
coupling between services. This means that it is essential to able to determine
what services depend on what other services (or other service artefacts) at any
time in the lifecycle of the business applications.
Even at the IT level, services are described using standards-based documents
such as WSDLs and XSDs which have dependencies between them. As
business services progress through their lifecycles and evolve to meet market
needs, the targets of these dependencies will change and it will be crucial to
keep this information up to date.
Any changes to services in the deployed environment may have an impact on
other business applications. Changes in interface versions and compatibility will
need to be tracked and the impact of any change evaluated.
WebSphere Service Registry and Repository (WSRR) provides a means of
defining these relationships and dependencies between objects as relationship
metadata. WSRR defines and associates a number of built-in relationships that
are defined against the classes of objects exposed in the WSRR information
model. These are primarily associated with documents and imports and includes
between them. These built-in relationships are often created automatically when
a document is published and will therefore never be modifiable by a user.
Relationships tie together one source service description entity to one or more
target service description entities. Every relationship is given a name. A source is
only allowed to have a single relationship with a given name.
Some relationships are assigned by WSRR during the parsing of key types of
documents. One example of a system-assigned relationship is the relationship
85
established between XSD documents based on the importing of one into the
other.
WSRR also allows custom relationships. For example, you can:
Relate a GenericObject that represents an external object to a service using a
user defined relationship.
Relate all of the service description documents that will be governed as a unit
to a governable entity.
Relate a monitoring policy to a service endpoint.
These can be added or deleted from any object on an instance by instance basis.
For custom relationships both the name and target objects can be defined by the
user.
WSRR treats built-in relationships and custom relationships in similar ways for
the purposes of manipulation and query.
Relationships can be created, modified, used and deleted using the Web UI (see
9.5, Relationships on page 347) or the API (see Chapter 4, Interfaces and
APIs on page 119).
3.3.3 Classifications
WebSphere Service Registry and Repository (WSRR) provides a means of
classifying service artefact descriptions represented in WSRR. This allows you to
organize your services by allocating classifications from a set of predefined
classification systems.
Each classification system represents a different way of organizing services and
is represented as a hierarchy of classifications similar to a library indexing
system. WSRR supports any number of classification systems that can be
predefined to organize your service artefacts in the best way.
You can load classification systems into WSRR where they can then be used to
apply semantic meaning to Service description entities. Classification systems
are documents encoded using the Web Ontology Language (OWL).
While any valid OWL document can be used as a Classifier system, at present
WSRR exploits only a small subset of the expressiveness of OWL. WSRR
represents OWL Classes as classifiers and interprets the subTypeOf relationship
between those Classes as establishing a classifier hierarchy. Other OWL
concepts such as data or relationships representing properties or other built-in
OWL relationships are ignored.
86
A classifier system is imported into WSRR as a whole and cannot be modified

via WSRR functions; updates are done by importing a modified version of the
ontology. Any Class in the underlying ontology can be used as a classifier; the
same classifier can be used to classify multiple entities and an entity can be
associated with multiple classifiers.
Ontologies
An ontology is a vocabulary used to describe some domain. This includes
describing the entities in the domain, and their relationships. See the definition of
an ontology following Classifications on page 69.
Web Ontology Language

The Web Ontology Language (OWL) is a W3C endorsed format that can be used
to define an ontology. See the definition of an ontology following Classifications
on page 69. It can define relatively rich semantics including relations between
classes of entities (for example disjointedness), cardinality (for example exactly
one), equality, properties, characteristics of properties (for example symmetry),
and enumerated classes.
WSRR does not provide any facilities for editing or composing a new OWL file. It
is expected that external tools will be used to produce an OWL file, and the
resulting file is then loaded into WSRR by an Administrator.
For more details about OWL, visit:
http://www.w3.org/2004/OWL/
Taxonomies
At a more simplistic level, OWL can also describe taxonomies. A taxonomy is a
system of hierarchical types which can be used to describe entities. The types
are expressed in a class and subclass system.
So for example, a simple taxonomy could consist of a class called Transport
which could have subclasses Air Transport and Land Transport. Then, Land
Transport could in turn have subclasses Bus and Car. This hierarchy means
that a Car is a type of Land Transport, and is also a type of Transport.
3.3.4 Classifications in WSRR

WSRR is able to load and understand OWL files, but currently does not exploit all
the features of the OWL language. Instead, the taxonomy part of the OWL file is
made available to classify artefacts in WSRR. Within the WSRR Web UI each
taxonomy is referred to as a classification system, and the classes within the
taxonomy are referred to as classifications or classification classes.
87
Classification classes are used to organize and find artefacts in WSRR. Any
artefact may be tagged or classified with multiple classification classes.
For example an organizational classification system may be produced, with a
class Europe, which has a subclass UK, which in turn has a subclass London
office (and there could be many other classes for other regions, countries and
groups).
In addition simple lifecycle classification system could be produced with classes
such as Development, Production, Obsolete and so on.
An artefact in WSRR could then be classified with any number or combination of
these classes. Although the English language meaning of some of these classes
suggests that some of them are mutually exclusive, there is no enforcement of
such semantics; all classes are equal and any can be applied to any artefact.
One possibility is that a WSDL portType, say, is classified with the London office
and Production classes. This artefact would then be returned in a search for all
artefacts that had both these classifications applied, that is a search for all
artefacts produced by the London office that were in the production state. It
would also be returned for a search for all artefacts produced in the UK that were
in production.
Classifications can be used from the Web UI (see 9.6, Classifying objects on
page 358) or the API (see Chapter 4, Interfaces and APIs on page 119).
3.4 Templates
As discussed previously, user-defined properties and relationships can be used
to customize the set of predefined properties and relationships provided in the
WSRR meta-model. Users can add properties to a WSDLDocument or they can
configure a GenericObject with properties and relationships to represent its
structure.
To simplify the process of customizing WSRR entities, a simple template
mechanism is provided. It allows you to create an XML schema that captures the
definition of properties and relationships associated with a GenericObject entity
of a particular type. You can then associate the template with the entity type. All
interactions with entities of that type will then be patterned to match the
template, designating the properties and relationships that are relevant when
interacting with that kind of entity.
Template allows user-defined properties and relationship names to be applied
consistently to GenericObjects created within WSRR. These templates are
88
defined as simple XSD complex types with attributes being used to represent the
property and relationship names expected for entities created from the
templates.
Templates may therefore be used to represent metadata that describes objects in
the business domain, such as business services. Templates can be used to
model sets of metadata, which may then be applied to any GenericObjects that
are created in WSRR, thus allowing many different metadata models to be
represented.
Note: WSRR provides no other metadata modelling tools, so the use of
templates is the only way to achieve this. The template model does not include
type-checking or any other modelling-based validation, so you should ensure
that the templates are correct when you create them.
For more details on configuration of Templates, see 9.9.1, Defining a concept
template on page 371.
3.5 Document types

WSRR manages services by representing them in the registry and associating
metadata with them that describes the role of the service in the SOA
environment together with its relationship to other artefacts on which it depends.
By managing this service metadata, WSRR can provide the single copy of record
for service descriptions and thus allow organizations to manage their services.
As described previously, WSRR offers advanced functions for a number of
well-known SOA metadata types. These key WSRR metadata document types
are:

WS-Policy
Service Component Description Language (SCDL)
The menu hierarchy for service documents can be seen in Figure 3-2 on
page 90.
89
Figure 3-2 Service Documents
See Figure 3-3 for document objects.
Figure 3-3 Document objects
For these document types, WSRR provides special services, including parsing of
the documents upon receipt into logical derivations or a set of logical objects.
90
Figure 3-4 Service metadata
3.5.1 XML Schema Definition (XSD)

WebSphere Service Registry and Repository provides a single copy of record for
all service metadata. In a SOA environment the services exchange information in
Extensible Markup Language (XML) formats. To achieve interoperability, different
services have to agree on the schemas for this information exchange. The
industry standard for defining the XML schema is XSD (XML Schema Definition).
In an SOA environment there are many important artefacts that use XML
schemas to define the service implementation. Some of these are described
here.
Business objects - Businesses often adopt standardized representations of
information that is key to their business. Some of these are standardized across
individual companies to support particular market sectors.
Business messages - Message driven architectures rely primarily on XML
schema definitions to define the formats that are used to exchange information.
Business Events - As with messages, event structures are often defined in XML
schemas to assist in reporting and systems management.
Service operation signatures - Even when services are described using
WSDL, the parameters of the service operations are often expressed using XML
91
schemas expressed in XSD documents. This allows different services to share a

common information model.
WSRR provides the capability to register XSD documents and to identify the
important XML Schema constructs within those documents that will affect the
interoperability or common dependencies between services being managed.
For each XSD document WSRR identifies:
Global complex types - These identify the actual types used in interface and
message definitions. WSRR only identifies the name and namespace of the
complex type from the XSD, it does not maintain finer grain structure.
Global simple types - These identify the actual types used in interface and
message definitions. WSRR only identifies the name and namespace of the type
from the XSD.
Global elements - These identify elements that have global visibility and may
thus be used in interface and message definitions. WSRR only identifies the
name and namespace of the element from the XSD.
Global attributes - These identify attributes that have global visibility and may
thus be used in interface and message definitions. WSRR only identifies the
name and namespace of the attribute from the XSD.
Each of these constructs results in an object that is stored in the registry and
related to the schema document that declared it. These derived or logical
objects cannot be created or deleted by the user, they are managed entirely by
the registering or de-registering of the XSD document that defines them.
There is a special extension of global complex types that is used to support
templates. WSRR interprets certain local attributes and these can be used when
creating GenericObjects from templates as follows.
Local attributes that are declared of type xsd:string are treated as WSRR
properties in GenericObjects created from the template.
Local attributes that are declared of type xsd:IDREF are treated as WSRR
relationships in GenericObjects created from the template.
The only information available for these local attributes is the name.
The objective for all these derived objects is to allow the named construct to be
annotated with metadata to indicate how it should be used across the SOA
enterprise. This allows a particular construct declared within a document to be
managed differently from other constructs declared within the same document.
This has the implication that if any document is deleted or even updated (in terms
92
of content), any derived objects will be deleted and the attached metadata will be
lost.
In addition to this parsing of XSD documents, WSRR automatically detects and
maintains dependencies between documents. At the time of loading or creation,
of the dependent document, the documents that it depends on must be:
Already available within WSRR. Special handling of this is required since
xsd:include, xsd:import, xsd:redefine statements do not include enough
information to resolve between different versions of the same schema (same
name, location and namespace).
Provided with the dependent document as part of the load. In this case the
document that is depended on will also be loaded and parsed.
Available from the uri given in the import or include location hint. In this case
the document that is depended on will also be loaded and parsed.
For each of these dependencies encountered and resolved, WSRR will ensure
that a built-in relationship is established between the dependent document and
the depended on document.
See Figure 3-5 for XSD logical objects.
Figure 3-5 XSD logical objects
XSD Documents can be managed in WSRR using Web UI (see Chapter 9,

Getting started with WSRR on page 327), Eclipse plug-in (see Chapter 11,
Using the WSRR Eclipse plug-in on page 415) and APIs (see Chapter 4,
Interfaces and APIs on page 119).
93
3.5.2 Web Services Description Language service definitions

WebSphere Service Registry and Repository aims to provide a single copy of
record for all service definitions in a SOA environment.
In SOA the loose coupling between services means that organizations have the
flexibility to change which services depend on which other services. Before any
change can occur there needs to be confidence that the consumer service is
compatible with the provider. Thus all deployed or about to be deployed services
need to have a clear service definition that can be published for consumers to
discover. The industry standard for Web service definitions is Web Services
Description Language (WSDL).
Web service definitions are often provided at three levels, all of which use WSDL
to describe them.
Service interface definitions - Describe the interfaces in terms of operations
and signatures provided by a service. These will often reference XML schemas
to define common message formats or operation parameters.
Service binding definitions - Describe how the interfaces are represented in
the infrastructure and over the wire. This defines the transport protocols that are
supported such as SOAP, JMS, and so on. This references the service Interface
definition to indicate exactly which operations are actually supported over this
transport protocol.
Service endpoint definitions - Describe each individual deployed service and
describe how a consumer would actually find and connect to a service. They
define the endpoints and indicate which bindings and thus interfaces are
supported on each endpoint.
It is good practice to make sure that each of these three levels of service
definition are defined in different WSDL documents. This is not enforced by
WSRR but the split of definitions across multiple documents is supported.
WSRR provides the capability to register WSDL documents and to identify the
important WSDL constructs within those documents that will affect the
interoperability or common dependencies between services being managed.
For each WSDL document WSRR identifies:
Port Types - These identify the service interfaces defined in the document
including the operations and their signatures. These will often reference XML
schema constructs to define operation parameters.
94
Bindings - These identify the bindings defined in the document including the
soap binding and the portType supported.
Services - These identify the service, ports, soap address and the bindings to
which they relate.
Each of these constructs results in a related collection of objects that are stored
in the registry and related to the WSDL document that defined them. These
derived or logical objects cannot be created or deleted by the user, they are
managed entirely by the loading or deleting of the WSDL document that defines
them. This has the implication that if any document is deleted or updated (in
terms of content), any derived objects will be deleted and the attached metadata
will be lost.
The objective for all these derived objects is to allow the named construct to be
annotated with metadata to indicate how it should be used across the SOA
enterprise. This allows a particular construct declared within a document to be
managed differently from other constructs declared within the same document.
For example, different policies might be attached to different operations of a
service interface even though all the operations are defined in the same WSDL
document.
See Figure 3-6 for WSDL logical objects.
Figure 3-6 WSDL logical objects
95
In addition to this parsing of WSDL documents, WSRR automatically detects and

maintains dependencies between documents. At the time of loading or creation,
of the dependent document, the documents that it depends on must be:
Already available within WSRR. Special handling of this is required since an
xsd:include, xsd:import, wsdl:import statements do not include enough
information to resolve between different versions of the same document
(same name, location and namespace).
Provided with the dependent document as part of the create. In this case the
document that is depended on will also be loaded and parsed.
Available from the URI given in the import or include location hint. In this case
the document that is depended on will also be loaded and parsed.
For each of these dependencies encountered and resolved, WSRR will ensure
that a built-in relationship is established between the dependent document and
the depended on document.
WSDL Documents can be managed in WSRR using Web UI (see Chapter 9,
3.5.3 Service Component Architecture (SCA) modules

WebSphere Service Registry and Repository provides support for conventional
service and schema definitions through the use of WSDL and XSD documents.
However, these document standards are not enough to describe the
dependencies between services that are necessary to support service-oriented
architectures (SOA). SOA offers the ability to assemble components from
existing services either at development time or at runtime.
The emerging standard that will allow these assemblies to be described is the
Service Component Architecture (SCA).
SCA modules are components that can be deployed into an SCA environment
and represent processes or other compound services. Modules are assembled
from development time components into a single deployable artefact but these
modules can still be related to (depend on) other external deployed services.
SCA provides a number of important constructs that are defined as part of an
SCA module deployment description.
SCA libraries - each library provides a number of XSD and WSDL documents
that describe the services artefacts that are being reused or referenced within
the module.
96
SCA module file - this provides the definition of the module in terms of the
internal components used within the module. WSRR does not interpret the
internal content information but does identify any externalized dependencies
as imports and exports.
SCA imports - these provide the definitions of the external services that the
module depends on. These import files define the interfaces, bindings and
endpoints that the module will need to resolve when it is deployed.
SCA exports - these provide the endpoint descriptions that the module
exposes in terms of interfaces, bindings and endpoints.
For more details on SCA import export bindings, see 14.3.2, Mediation
modules on page 516.
One of the advantages of SCA over WSDL is that it allows a wider range of
bindings to be expressed. Thus, SCA modules can work with JMS and other
message based paradigms as well as the Web services that WSDL supports.
See Figure 3-7 for SCA logical objects.
Figure 3-7 SCA logical objects
SCA Documents can be managed in WSRR using Web UI (see Chapter 9,

Getting started with WSRR on page 327) and APIs (see Chapter 4, Interfaces
and APIs on page 119).
97
3.5.4 XML metadata files

WebSphere Service Registry and Repository aims to provide a single copy of
record for all service metadata.
Many SOA artefacts can be described by well known standards such as XSD
and WSDL. Many customers will however have their own service descriptions
that are stored in some other XML format. Examples of this can be business
rules, business policies, Business Process Execution Language (BPEL) files,
and so on.
WSRR provides a means of storing these XML documents and thus relating
them to the other service artefacts in the registry.
WSRR will not interpret the content of the XML document so there will be no
derived objects created.
XML metadata files can be managed in WSRR using Web UI (see Chapter 9,
3.5.5 Service Policy (WS-Policy)

One of the key goals of SOA is to provide policy driven interactions between
services. This results in business agility and faster time to value since behavior
can be changed simply by modifying the applicable policies. However the policies
themselves then need to be managed as closely as the service implementations
in order to maintain a compliant solution.
WebSphere Service Registry and Repository (WSRR) aims to provide a copy of
record for all policy documents. Using the metadata facilities within WSRR, these
policies can be related to the service artefacts to which they apply.
WSRR provides a very basic interpretation of the content of the WS-Policy
documents so there will be no derived objects created to which metadata can be
applied. It is therefore up to the client applications to interpret and enforce any
policies that are deemed applicable by the metadata contained within WSRR.
Policy documents can be managed in WSRR using Web UI (see Chapter 9,
Getting started with WSRR on page 327) and APIs (see Chapter 4, Interfaces
and APIs on page 119).
98
3.6 XPath
The XML Path Language (XPath) is a set of syntax and semantics for referring to
portions of XML documents.
XPath models an XML document as a tree of nodes, and provides the ability to
navigate around the tree, selecting nodes by a variety of criteria.There are
different types of nodes, including element nodes, attribute nodes and text
nodes. Some types of nodes also have names.
XPath uses expressions to identify a set of nodes in an XML document. This set
of nodes can contain zero or more nodes.
XPath expressions can refer to attributes as well as elements in an XML
document. When referring to an attribute, the @ character is used. For example,
the following XPath expression identifies currentPrice elements whose currency
attributes contain the value EUR:
/list/item/currentPrice[@currency="EUR"]
XPath includes built-in functions for string values, numeric values, date and time
comparison, node and QName manipulation, sequence manipulation, Boolean
values, and more.
XPath is intended to be used by other specifications such as Extensible
Stylesheet Language Transformations (XSLT) and the XML Pointer Language
(XPointer).
For more details on XPath, visit the following Web sites:
http://www.w3.org/TR/xpath
http://www.ibm.com/developerworks/edu/x-dw-xxpath-i.html
3.7 Service Data Objects (SDO)

In WSRR programming model, all elements (documents, logical models,
user-defined metadata, generic objects queries) are represented as SDO.
Service Data Objects (SDO) are designed to simplify and unify the way in which
applications handle data. Using SDO, application programmers can uniformly
access and manipulate data from heterogeneous data sources, including
relational databases, XML data sources, Web services, and enterprise
information systems.
99
SDO is based on the concept of disconnected data graphs. A data graph is a

collection of tree-structured or graph-structured data objects. Under the
disconnected data graphs architecture, a client retrieves a data graph from a
data source, mutates the data graph, and can then apply the data graph changes
back to the data source.
The task of connecting applications to data sources is performed by data
mediator services. Client applications query a data mediator service and get a
data graph in response. Client applications send an updated data graph to a data
mediator service to have the updates applied to the original data source. This
architecture allows applications to deal principally with data graphs and data
objects.
SDO enables both a static (or strongly typed) programming model and a dynamic
(or loosely typed) programming model. This enables a simple programming
model without sacrificing the dynamic model needed by tools and frameworks.
SDO also provides a metadata API, which allows applications, tools, and
frameworks to introspect the data model for a data graph. The SDO metadata
API unifies data-source-specific metadata APIs to enable applications to handle
data from heterogeneous data sources in a uniform way.
SDO is intended to be language-neutral and to be available in a range of
programming languages.
3.7.1 Data objects

Data objects are the fundamental components of SDO. In fact, they are the
service data objects found in the name of the specification itself. Data objects are
the SDO representation of structured data. Data objects are generic and provide
a common view of structured data. Data objects are linked together and
contained in data graphs.
3.7.2 Data graphs

Data graphs provide a container for a tree of data objects. SDO clients can
traverse a data graph and read and modify its data objects. SDO is a
disconnected architecture because SDO clients are disconnected from the data
source; they only see the data graph. Furthermore, a data graph can include
objects representing data from different data sources. A data graph contains a
root data object, all of the root's associated data objects, and a change summary
(See Figure 3-8 on page 101). When being transmitted between application
components (for example, between a Web service requester and provider during
service invocation), or saved to disk, data graphs are serialized to XML. The
SDO specification provides the XML Schema of this serialization.
100
Figure 3-8 Data graph
For an introduction to SDO, see:

http://www.ibm.com/developerworks/java/library/j-sdo/
For more information about the goals and architecture of SDO, see the following
Web site:
http://www.ibm.com/developerworks/library/specification/ws-sdo/
3.8 BaseObject
BaseObject is the root WSRR type. All elements in WSRR are inherited from
BaseObject. It defines common attributes and relationships.
Example 3-1 BaseObject
<xs:complexType name="BaseObject" abstract="true">

<xs:sequence>
<xs:element name="classificationURIs" type="xs:string"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="userDefinedRelationships"
type="tns:UserDefinedRelationship" minOccurs="0"
maxOccurs="unbounded"/>
<xs:element name="userDefinedProperties"
type="tns:UserDefinedProperty" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="bsrURI" type="xs:ID" sdo:dataType="xsd:string"
sdoxml:readOnly="true"/>
<xs:attribute name="name" type="xs:string"/>
101
<xs:attribute name="namespace" type="xs:string"/>

<xs:attribute name="version" type="xs:string"/>
<xs:attribute name="description" type="xs:string"/>
<xs:attribute name="owner" type="xs:string" sdoxml:readOnly="true"/>
<xs:attribute name="lastModified" type="xs:string"
sdoxml:readOnly="true"/>
</xs:complexType>
See Figure 3-9 on page 103 for the BaseObject model.
102
Figure 3-9 BaseObject model
3.9 Query
Once registered, services must be available for reuse and management for them
to be any use. WSRR implements a subset of XPath 2.0 with some extensions to
provide a simple yet powerful search and query mechanism.
103
WSRR allows querying against a virtual XML document rooted at /WSRR. This
document contains every SDO object held in WSRR.
The child elements of the /WSRR root are named after top-level SDO types, each
element instance representing an object.
A simple example of a query expression is:
/<PathExpression>[<FilterExpression>]
Where, <PathExpression> is the path to the required SDO along the containment
hierarchy of the information model. For example to search for WSDLDocument
SDOs the <PathExpression> is /WSRR/WSDLDocument, for WSDLPort SDOs the
<PathExpression> is /WSRR/WSDLService/ports.
Elements of types which are not top-level are named after the containing relation.
For example, /WSRR/WSDLService/ports. SDO attributes are modelled as XML
attributes on those elements.
For clarity, the word 'association' is used to mean 'non-containment relationship'.
A 'relationship' can be through association or containment.
An element is said to be contained by another if it is accessed at a lower point in
the XML hierarchy. An element is said to be associated to another if the former is
related to the latter but the latter is not contained by the former. That is,
association is used in a more specific sense than in UML, to mean
non-containment relationships in particular.
bsrURI attribute
A bsrURI attribute of XSD type xs:ID is assigned to every SDO object which is
unique to it within WSRR. These bsrURIs are used to implement associations
internally and so can be safely used to reconstruct relationships between objects
obtained by one or more queries. This is safer than using the original ids
because bsrURIs are WSRR-unique, rather than document-unique.
Do not use bsrURIs directly to navigate associations. For each association a
function has been provided which takes the current context as its only argument.
This function replaces the current context node with that of the associated
element.
3.9.1 Types of query

There are two types of queries: PropertyQuery and GraphQuery.
104
PropertyQuery
A PropertyQuery is used when only some attributes of objects that match the
query expression are to be returned. In this case, the result of the query is a
collection of QueryResult objects, each of which has the appropriate
user-defined properties set to the values of the chosen attributes of a matching
object.
GraphQuery
A GraphQuery is used when a complete datagraph is to be returned for each
object that matches the query expression. The default is to return all the objects
related to the matched object, but an attribute on the GraphQuery can control the
depth of the returned graph. A depth parameter can be specified on the
GraphQuery object that allows you to specify the depth of relationships that are
resolved in the object graph that is returned.
Specifying a depth parameter of -1 means that a complete object graph is
returned. For example, if a query with depth parameter of -1 returns a single
WSDLService element, you can then programmatically follow all the relationships
(both predefined and user-defined) from the root WSDLService object that is
returned from the query.
Specifying a depth parameter of 0 implies that only the objects that have been
queried for are returned and so you can access all the properties for a given
object, but cannot access any related object programmatically without executing
an additional query.
For example, if a WSDLService is returned, the default behavior will be to return
the WSDLService instance itself, all of the WSDLPort objects contained by the
WSDLService, the WSDLBindings associated with each WSDLPort and so on. If the
depth attribute were set to 2, then only the WSDLService, the WSDLPort objects
and the WSDLBinding objects would be returned.
The leaf objects have empty values for modelled relationships and do not have
any user-defined relationships.
3.9.2 Searching and querying

The following sections provide examples of queries.
Simple queries
This section explains how to write basic XPath queries.
105
Queries are built up from expressions separated by forward slashes '/'. Here is a
graph query which returns all WSDLServices:
/WSRR/WSDLService
Note that the singular form is used. The Relationship map (See Relationship
map on page 111) in the has the correct forms of all relations. Adding further
expressions delves deeper, finding objects which are either contained by or
associated with the preceding elements. For example, this graph query will return
all WSDLPorts contained by any WSDLService.
/WSRR/WSDLService/ports
To traverse an association rather than a containment relationship, append '(.)'. All
user-defined relationships are considered associations.
/WSRR/WSDLBinding/portType(.)
To retrieve an attribute (built-in or user-defined) from an element, use '@' in a
property query:
/WSRR/WSDLService/@name
It will return the names of all the WSDLServices which exist, not the
WSDLService objects themselves. If instead the intention was to find all
WSDLServices called 'TickerService', the following graph query could be used:
/WSRR/WSDLService[@name='TickerService']
Note: Graph queries end (ignoring predicates) in a relationship name, like
WSDLService or binding(.). Property queries end in an attribute name, like
@name. Use the appropriate API code for each.
Predicates
This section explains how to filter your results.
The previous example showed the use of a simple predicate to filter the objects
returned. Predicates can be used at any stage, and more than once in the query.
/WSRR/WSDLService[@name='Catalogue']/ports[@name='search']
Predicates can be logically combined using 'and' and 'or'. The 'or' operator has a
higher precedence in XPath than it does in SQL, so using parentheses to group
complex expressions is recommended to avoid unexpected results.
/WSRR/WSDLService[@name='TickerService' and @version!='1.2']/ports
/WSRR/WSDLService[@name='Catalogue' or @name='Library']
106
Predicates can be more complex than just an attribute accessor. They can be
any valid XPath expression which evaluates to a Boolean. Query 1 below returns
WSDLService objects, whereas query 2 returns WSDLPorts:
1. /WSRR/WSDLService[ports/@name='incoming']
2. /WSRR/WSDLService/ports[@name='incoming']
By putting the two together, complex filters can be created like this:
/WSRR/WSDLService[ports/@name='incoming' and ports/@name='outgoing']
The above query demonstrates that different objects may be used to fulfil each
sub-expression of the predicate. It could be translated as give me all the
WSDLServices which have a port named 'incoming' and also have a port named
'outgoing'.
To express give me all the WSDLServices which have a port named 'incoming'
that is also described as 'open', use nested predicates. This forces a single port
to match both conditions:
/WSRR/WSDLService[ports[@name='incoming' and @description='open']]
The matches() function allows you to use '.*' within your queries to mean 'any
sequence of characters'. For example, these queries find WSDLServices whose
names contain IBM at the beginning, end and in the middle respectively. No other
elements of regular expressions syntax are allowed.
/WSRR/WSDLService[matches(@name, 'IBM.*')]
/WSRR/WSDLService[matches(@name, '.*IBM')]
/WSRR/WSDLService[matches(@name, '.*IBM.*')]
The existence of a user-defined property or relationship can be queried like so:
/WSRR/WSDLService[@MyProperty]
/WSRR/WSDLService[MyRelationship(.)]
Note: Comparisons can be made, but all values are treated as strings. This
means that '2' is considered to be greater than '10'. Avoid queries like this:
# DO NOT DO THIS!
/WSRR/WSDLService[@version > '10']
Shortcuts and wildcards

This section explains how to use the double-slash and star operators.
The following graph query will return all WSRR objects named 'Ticker'.
//*[@name='Ticker']
107
A star can also be used to mean any attribute. This will include both built-in and
user-defined attributes.
/WSRR/WSDLService[@*='StockQuote']
These are the only supported uses of the double-slash and star operators.
The WSRR-provided function, anyUserDefinedRelationship(.), acts like a star for
user-defined relationships. This function can be used within a predicate as well,
to find objects which have user-defined relationships:
/WSRR/WSDLService/anyUserDefinedRelationship(.)
/WSRR/WSDLService[anyUserDefinedRelationship(.)]
Classification functions
WSRR provides a number of additional XPath functions to assist querying using
classifications. Some of the important functions are
classifiedByAnyOf, which returns true if an object is classified with any of the
URIs specified as arguments to the function.
classifiedByAllOf, which returns true if an object is classified by all of the
URIs specified as arguments to the function.
Note that these functions all take a single dot '.' as their first argument. The
examples use the following ontology (words are used instead of proper URIs for
clarity):
class color
class red
class green
class shape
class round
class tall
This ontology is used to classify the following WSDLServices:
1. name="Apple" classifications=["red", "round"]
2. name="Lime" classifications=["green", "round"]
3. name="Tree" classifications=["green", "tall"]
The following function:
classifiedByAnyOf(., 'owlURI1', 'owlURI2', ...)
108
It returns all objects classified by at least one of the given owlURIs or their
subtypes. So in our example, query:
/WSRR/WSDLService/classifiedByAnyOf(., 'shape')
It will return all three WSDLServices. The following query:
/WSRR/WSDLService/classifiedByAnyOf(., 'red', 'round')
It will return the Apple and Lime WSDLServices. The following query:
/WSRR/WSDLService/classifiedByAnyOf(., 'green', 'tall')
It will return the Lime and Tree WSDLServices.
classifiedByAllOf(., 'owlURI1', 'owlURI2', ...)
It returns all objects classified by all of the given owlURIs or their subtypes. So in
our example, the following query:
/WSRR/WSDLService/classifiedByAllOf(., 'shape')
It will return all three WSDLServices. The following query:
/WSRR/WSDLService/classifiedByAllOf(., 'red', 'round')
It will return the Apple WSDLService. The following query:
/WSRR/WSDLService/classifiedByAllOf(., 'green', 'tall')
It will return the Tree WSDLService.
Following function:
exactlyClassifiedByAnyOf(., 'owlURI1', 'owlURI2', ...)
It returns all objects classified by at least one of the given owlURIs. Subtypes are
not considered. So in our example, the following query:
/WSRR/WSDLService/exactlyClassifiedByAnyOf(., 'shape')
It will return none of the WSDLServices. The following query:
/WSRR/WSDLService/exactlyClassifiedByAnyOf(., 'red', 'round')
It will return the Apple and Lime WSDLService. The following query:
/WSRR/WSDLService/exactlyClassifiedByAnyOf(., 'green', 'shape')
It will return the Lime and Tree WSDLServices.
109

exactlyClassifiedByAllOf(., 'owlURI1', 'owlURI2', ...)
It returns all objects classified by all of the given owlURIs. Subtypes are not
considered. So in our example, the following query:
/WSRR/WSDLService/exactlyClassifiedByAllOf(., 'shape')
It will return none of the WSDLServices. The following query:
/WSRR/WSDLService/exactlyClassifiedByAllOf(., 'red', 'round')
It will return the Apple WSDLService. The following query:
/WSRR/WSDLService/exactlyClassifiedByAllOf(., 'green', 'shape')
It will return none of the WSDLServices.
Treat as
There are two points in the model where the query system needs some help to
know what the type of the elements are. Consider this query:
/WSRR/Module/exports
You know that for the Module you are interested in, the exports are
SCAWSDLPortTypes. As far as the query engine is concerned though, they are of
the supertype LogicalObject. To access properties or relationships defined on
the subtype, you must introduce a downcast, expressed in XPath with 'treat as':
/WSRR/Module/exports/(interfaces treat as
element(interfaces,SCAWSDLPortType))/WSDLPortType(.)
/WSRR/Module/exports/(interfaces treat as
element(interfaces,SCAWSDLPortType))[WSDLPortType(.)[@name='pt']]
/WSRR/Module/exports/(exportBinding treat as
element(exportBinding,SCAExportBinding))[@name='eb' and
@namespace='ens']
Note: The parentheses around the treat as expression are required.
The following types all descend from concrete supertypes and must be cast
using 'treat as' to access the relations and properties they define:
JMSImportBinding
JMSExportBinding
SCAImportBinding
110
SCAExportBinding
SLSBImportBinding
WebServiceImportBinding
WebServiceExportBinding
SimpleTypeDefinition
ComplexTypeDefinition
SCAWSDLPortType
Relationship map
This relationship map describes the WSRR object hierarchy and can be used to
assist in building XPath queries.
The map employs the following conventions:
Relations are given as their simple names.
Attributes are prefixed with @.
Containment is represented with indentation.
X < Y means type X inherits from Y.
X
Y means relation X leads to objects of type Y.
X is a Y means object X is of type Y, which has subclasses.

The map is in three parts:
Concrete types - Concrete types are those WSRR types which are directly
accessible from an XPath query. Use this map to begin building an XPath query.
Supertypes - Supertypes cannot be accessed directly in an XPath query.
However, concrete types either inherit from supertypes or have an object type of
one of the supertypes. Therefore, supertype attributes and subtypes may appear
in an XPath query.
XSD files - XSD files containing the XML schema definitions for all the WSRR
types.
Concrete types
Concrete types are those WSRR types which are directly accessible from an
XPath query. Use this map to begin building an XPath query.
To build an XPath query, begin at /WSRR and traverse through the object
hierarchy, appending subtypes, separated by /, at each stage and incorporating
attributes as required. Where a type A inherits from a type B (indicated by < or
111
is itself an object of type B (indicated by is a or is an), refer to the Supertypes

on page 114 in order to continue traversing the hierarchy.
Example: find all Subscriptions owned by Admin User. See Table 3-1 on
page 112.
Table 3-1 Example
Step
Action
XPath query
Begin at /WSRR, the root of the

hierarchy
/WSRR
Traverse the Subscription concrete

type (note that the attributes of the
Subscription type do not include the
owner)
/WSRR/Subscription
Subscription inherits from

BaseObject - therefore, refer to
BaseObject in the supertypes map.
BaseObject has an owner attribute append this as a predicate to complete
the XPath query
/WSRR/Subscription[@owner="Admin
User"]
The concrete types map is as follows:

Example 3-2 Concrete map
/WSRR
/AttributeDeclaration < LogicalObject
/ComplexTypeDefinition < XSDType
/localAttributes is a LocalAttribute
@attributeType
/Document < OriginalObject
@content
@encoding
@location
/ElementDeclaration < LogicalObject
/ExportDocument < Document
/GenericObject < OriginalObject
/GraphQuery < QueryObject
@depth
/ImportDocument < Document
/Module < LogicalObject
@moduleType
/exports is an Export
/exportBinding is an ExportBinding
112
/interfaces is an Interface
@preferredInteraction
/imports is an Import
/importBinding is an ImportBinding
/ModuleDocument < Document
@moduleType
/PolicyDocument < Document
/PolicyExpression < LogicalObject
@URI
/PropertyQuery < QueryObject
/SCAModule < OriginalObject
/WSDLDocuments(.) -> WSDLDocument
/XSDDocuments(.) -> XSDDocument
/exportDocuments(.) -> ExportDocument
/importDocuments(.) -> ImportDocument
/moduleDocument(.) -> ModuleDocument
/SimpleTypeDefinition < XSDType
/Subscription < BaseObject
@emailAddress
@locale
@subscribedOperations
@subscribedTransitions
@targetBsrUri
@targetClassifications
@targetName
@targetNamespace
@targetVersion
/WSDLBinding < LogicalObject
/SOAPBinding < LogicalObject
@style
@transport
/portType(.) -> WSDLPortType
/WSDLDocument < Document
/importedWSDLs(.) -> WSDLDocument
/importedXSDs(.) -> XSDDocument
/includedXSDs(.) -> XSDDocument
/redefinedXSDs(.) -> XSDDocument
/WSDLMessage < LogicalObject
/messageParts is a WSDLPart
/xsdElement(.) -> ElementDeclaration
/xsdType(.) -> XSDType
/WSDLPortType < LogicalObject
/operations is a WSDLOperation
113
/faults(.) -> WSDLMessage

/inputMessage(.) -> WSDLMessage
/outputMessage(.) -> WSDLMessage
/WSDLService < LogicalObject
/ports is a WSDLPort
/SOAPAddress < LogicalObject
@location
/binding(.) -> WSDLBinding
/XMLDocument < Document
/XSDDocument < Document
/importedXSDs(.) -> XSDDocument
/includedXSDs(.) -> XSDDocument
/redefinedXSDs(.) -> XSDDocument
Supertypes
Supertypes cannot be accessed directly in an XPath query. However, concrete
types either inherit from supertypes or have an object type of one of the
supertypes. Therefore, supertype attributes and subtypes may appear in an
XPath query.
Note: The UserDefinedRelationship and UserDefinedProperty associations
on BaseObject are unavailable. Use the name of the relationship and the dot
function (.) to traverse these.
The supertypes map is as follows:
Example 3-3 Supertype map
/BaseObject
@bsrURI
@description
@lastModified
@name
@namespace
@owner
@version
/Export < LogicalObject
/exportBinding is an ExportBinding
/ExportBinding < LogicalObject
/Import < LogicalObject
/importBinding is an ImportBinding
114
/ImportBinding < LogicalObject
/Interface < LogicalObject
/JMSExportBinding < ExportBinding
@dataBindingType
/JMSImportBinding < ImportBinding
@dataBindingType
/JMSExportBinding(.) -> JMSExportBinding
/LocalAttribute < LogicalObject
@attributeType
/LogicalObject < BaseObject
/document(.) -> Document
/OriginalObject < BaseObject
/predecessors(.) -> OriginalObject
/template(.) -> ComplexTypeDefinition
/QueryObject < OriginalObject
@queryExpression
/SCAExportBinding < ExportBinding
/SCAImportBinding < ImportBinding
/scaExportBinding(.) -> SCAExportBinding
/SCAWSDLPortType < Interface
/WSDLPortType(.) -> WSDLPortType
/SLSBImportBinding < ImportBinding
@jndiName
@location
/SOAPBinding < LogicalObject
@style
@transport
/WSDLOperation < LogicalObject
/faults(.) -> WSDLMessage
/inputMessage(.) -> WSDLMessage
/outputMessage(.) -> WSDLMessage
/WSDLPart < LogicalObject
/xsdElement(.) -> ElementDeclaration
/xsdType(.) -> XSDType
/WSDLPort < LogicalObject
@location
/binding(.) -> WSDLBinding
/WebServiceExportBinding < ExportBinding
/WSDLPort(.) -> WSDLPort
/WebServiceImportBinding < ImportBinding
/WSDLPort(.) -> WSDLPort
115
/XSDType < LogicalObject
XSD files
The XSD files containing the XML schema definitions for all the WSRR types are
provided with the product. Go to <WSRR-Install-Root>\admin\schemas folder and
see WSRRGovernanceSDO.xsd WSRRSDO.xsd. They provide additional
information not available from the map, attribute types for example. However,
many of the types defined in the XSD files are not accessible in an XPath query;
the concrete types map should, therefore, always be used as the starting point
for constructing a query.
3.9.3 More query examples

Following examples will help you understand the use of XPath to query elements
from WSRR.
Query all instances of a type

To query all instances of a type, first establish the path to the required type in the
information model. For example, WSDL documents are top level SDOs so the
XPATH is:
/WSRR/WSDLDocument
WSDL PortTypes are contained in WSDL services through the relationship
named ports so the XPATH is:
/WSRR/WSDLService/ports
To find all interface SDOs that are used within SCA modules, you need to do two
queries. An SCA module contains SCA imports and SCA exports through the
relationships named imports and exports and each of those can contain
interface SDOs, so there are two XPATH expressions that return interface SDOs.
One of them is:
/WSRR/Module/imports/interfaces
And the other is:
/WSRR/Module/exports/interfaces
Query Instances of a Type with a particular property value

To add a condition to the query based on type, use the standard XPath predicate
syntax.
116
For example, to search for all WSDLService instances named

StockQuoteService use a query string of:
/WSRR/WSDLService[@name='StockQuoteService']
Query based on a condition on a referrer

It is possible to have a relationship after the predicate(s) when the type of objects
returned are related to another object against which a predicate is expressed.
For example, to query for all portTypes referred to from bindings referred to from
ports of all services named "StockQuoteService" use
/WSRR/WSDLService[@name='StockQuoteService']/ports/binding(.)/portTy
pe(.)
Note that WSDL ports do not contain WSDL bindings but rather have a
relationship with them. As a result the function binding(.) needs to be invoked.
Because WSDL port types are contained in WSDL bindings, the next step is
simply the name of this containment relationship, that is portType.
Query based on a condition on a referent

It is possible to have a condition on a property of an object reached through a
relationship. For example, to return all WSDLServices that have a port that refers
to a binding that refers to a portType named StockQuotePortType use
/WSRR/WSDLService[ports/binding(.)/portType(.)/@name='StockQuotePort
Type']
Testing property existence

To query for all objects that have a property named foo defined, regardless of
value, use the following query expression:
//*[@foo]
The //* looks for all objects, regardless of where they are in the hierarchy of the
information model.
Testing relationship existence

To query for all objects that have a relationship named MyRelationship defined,
use the following query expression:
//*[MyRelationship(.)]
117
3.9.4 Limitations
Note that not every possible XPATH expression is supported. Listed here are
some of the limitations of WSRR queries:
Predicates filtering //* may only access attributes defined on BaseDocument.
The effective type of the target of a user-defined relationship is BaseObject.
This limits the attributes and relationships available to further terms in the
query.
You cannot query based on the inheritance hierarchy of the SDOs.
Multi-valued attributes are not supported. In general, multi-valued attributes
have been replaced by elements with children.
It is not possible to return the targets of relationships defined on extension
types in the SCA model. For example, query i below will not work. Instead, run
query 2 and access the WSDLPortType programmatically:
a. /WSRR/Module/(imports treat as
element(imports,SCAWSDLPortType))/WSDLPortType(.)
b. /WSRR/Module/(imports treat as element(imports,SCAWSDLPortType))
The flexibility of user-defined relationships and inheritance can easily cause
the underlying complexity of a query to expand exponentially. Therefore in
WSRR V6.0, no more than two of the following can be included in any query,
to guarantee it finishes before the timeout expires:
Traversals of relations defined by supertypes
Traversals of user-defined relationships
Access to user-defined properties
118
Chapter 4.
Interfaces and APIs

WSRR has several different interfaces that provide different ways of accessing
the products functionality.
This chapter describes the following:
4.1, Java API (EJB) on page 120
4.2, Web services API on page 136
4.3, Web user interface (Web UI) on page 144
4.4, Command Line Interface on page 154
4.5, Admin (JMX) on page 155
119
4.1 Java API (EJB)

WebSphere Service Registry and Repository has a Java application
programming interface (API) so that you can develop Java applications that
access WSRR at run time to find the most appropriate Web service to use.
During development, you can perform tasks such as creating documents in
WSRR using the Web-based user interface (UI). If you are developing
applications in an Eclipse environment, you can also use an Eclipse plug-in UI to
perform tasks such as searching for and uploading services to WSRR. For more
information about the Eclipse plug-in UI, see Chapter 11, Using the WSRR
Eclipse plug-in on page 415.
The WSRR API enables you to develop applications that can access WSRR at
run time to find the most appropriate Web service to use.
There are three aspects of the Java programming model:
The representation of the content of WSRR.
The support for creating, retrieving, updating, and deleting content in WSRR.
The support for querying WSRR.
The API is based on Service Data Objects (SDO) Version 2. All artefacts that are
stored in WSRR are represented by SDO. The WSRR types have both data
value properties and data object properties, which are referred to as
relationships in WSRR. All WSRR SDO types support open content properties,
properties that are defined on an individual instance of a type.
The WSRR API is made available as several Stateless Session Beans, with both
local and remote interfaces.
4.1.1 Creating a Java client

There are two clients supplied with the product which are used to interact with
WSRR. These is an EJB client and a Web services client. Both use the same
interfaces apart from the EJB client has a few more methods for supplying lists of
information for tasks such as update and delete.
In order to use either of the clients you must add the required jar files to your
runtime:
sdo-int.jar (This must be as high up the class path as possible to override
SDO 1 interfaces)
ServiceRegistryClient.jar
120
A suitable EJB/Web services runtime

Both sdo-int.jar and ServiceRegistryClient.jar can be found in your WSRR
installation directory (e.g. c:\Program Files\IBM\WebSphereServiceRegistry).
ServiceRegistryClient
ServiceRegistryClient.jar can be found in your WSRR installation directory. It
contains the following functionality:
WSRR SDO Objects
Helper classes (for creating objects and manipulating them)
Core EJB Client
Governance EJB Client
Ontology EJB Client
Web Services generated code
WSRR Core Web services client (calls the generated code)
SDO2 classes
Renamed EMF (required by the SDO2 runtime)
Figure 4-1 on page 122 illustrates how ServiceRegistryClient.jar can be used to
communicate with the WSRR server. The Ontology Web service is shown
separate to ServiceRegistryClient.jar as no special client code is needed to
access that Web service. See 4.2.1, Creating a Web services client on
page 136 for more information.
Chapter 4. Interfaces and APIs
121
ServiceRegistry.ear
Core
Web service
http/https
Core WS
EJB
Plugins
WSRR Obj.
Helpers
Core
Core
EJB
Governance
Governance
EJB
Ontology
Ontology
EJB
Ontology
Web service
Ontology WS
EJB
Impl
Figure 4-1 ServiceRegistryClient.jar architecture
Creating the EJB client

In this example, an EJB reference has been set up in the client J2EE
environment which points to the real JNDI name of
ejb/com/ibm/serviceregistry/ServiceRegistrySessionHome. Example 4-1
shows example code for connecting to a WSRR server where security is turned
off on the application server.
Example 4-1 Creating an EJB client
try {
// look up the home
ServiceRegistrySessionHome ejbHome = (ServiceRegistrySessionHome)
PortableRemoteObject.narrow(context.lookup("ejb/ServiceRegistrySession"),
ServiceRegistrySessionHome.class);
// create the client
122
ServiceRegistrySession serviceRegistry = ejbHome.create();

} catch (ClassCastException e) {
// do something
} catch (NamingException e) {
// do something
} catch (CreateException e) {
// do something
}
The Web services client is covered in 4.2, Web services API on page 136.
There are three helper classes:
com.ibm.serviceregistry.SRXMLHelper
Used to create Documents
com.ibm.serviceregistry.sdo.helper.DataFactory
Used to create GenericObjects and QueryObjects
com.ibm.serviceregistry.sdo.helper.BSRSDOHelper
Used to add relationships and properties to WSRR Objects
Registering the SDO objects

In order for any client to use the SDO objects, they must first be registered using
the org.apache.tuscany.sdo.util.SDOUtil.registerStaticTypes() method;
this needs only to be done once.
There are three separate packages that can be registered:
com.ibm.serviceregistry.sdo.SdoFactory
com.ibm.serviceregistry.governance.sdo.SdoFactory
com.ibm.serviceregistry.ontology.sdo.SdoFactory
However, if you register com.ibm.serviceregistry.governance.sdo.SdoFactory
then com.ibm.serviceregistry.sdo.SdoFactory will also be registered
automatically, as it is an extension, so there is no need to register it separately.
It is recommended that the following two lines of code are added to the client
application:
SDOUtil.registerStaticTypes(com.ibm.serviceregistry.governance.sdo.SdoF
actory.class);
SDOUtil.registerStaticTypes(com.ibm.serviceregistry.ontology.sdo.SdoFac
tory.class);
123
4.1.2 Creating content in WSRR

Several attributes can only be specified on a create operation. Once created,
they are treated as read-only. These attributes are:
namespace
name
version
Creating a GenericObject
The SDO DataFactory is used to create a GenericObject.
The namespace used to create WSRR dataobjects is:
http://www.ibm.com/xmlns/prod/serviceregistry/6/0/sdo
This is defined in a TypeConstants helper class.
Example 4-2 Creating a GenericObject
try {
GenericObject go =
(GenericObject)DataFactory.INSTANCE.create(TypeConstants.SR_URI,TypeCon
stants.TYPE_GENERICOBJECT);
go.setName(GenericObject1);
go.setLocation(location1);
go.setVersion(1);
String bsrURI = serviceRegistry.create(go);
} catch (ServiceRegistryException e) {
// handle exception;
}
Creating a document instance

The SRXMLHelper interface is used to create a Document instance. The content
of the document can be supplied locally by various means, or it can be retrieved
from a URL. It is possible to add additional metadata to the Document instance,
including properties, relationships and classifications before saving the
Document.
The interface is shown in Figure 4-2 on page 125.
124
Figure 4-2 SRXMLHelper interface
In order to create a document, the appropriate load method is invoked to read in

the content of the document and construct an instance of the appropriate
subtype of Document.
This instance can then be passed to the create method.
For example, creating a WSDL using the Java API is shown in Example 4-3,
however, the same technique can be used for any of the Document objects.
Example 4-3 Creating a WSDL using the Java API
try {
WSDLDocument wsdlDoc = (WSDLDocument)SRXMLHelper.INSTANCE.load(new
FileInputStream(C:/my.wsdl),TypeConstants.TYPE_WSDLDOCUMENT);
wsdlDoc.setName(myWsdl);
wsdlDoc.setLocation(my.wsdl);
wsdlDoc.setVersion(1);
String bsrURI = serviceRegistry.create(wsdlDoc);
} catch (FileNotFoundException e) {
} catch (IOException e) {
}
125
Resolving dependencies
In the case of WSDL and XML Schema files, WSRR will attempt to resolve
references to other documents that have a full URL specified for the location of
the dependency. WSDL has one mechanism for referring to another file: the
wsdl:import element. XML Schema has three mechanisms:
xsd:include
xsd:import
xsd:redefine
Any imported documents are related to the original document by a modelled
relationship. For example, WSDLDocument has a modelled relationship called
importedWSDLs that contains the other WSDL documents that are imported by
the root WSDL document.
Dependencies can also be satisfied by documents already in WSRR. Matching is
based on the appropriate combination of namespace and location (name). For
example, if w1.wsdl is a WSDL document that contains
<wsdl:import namespace="someNamespace" location="w2.wsdl">
and a document already exists in WSRR with a name/location of w2.wsdl and a
targetNamespace of someNamespace then when w1.wsdl is saved the import
will be resolved to w2.wsdl in WSRR, and the importedWSDLs relationship on
w1.wsdl will be updated appropriately.
Generating the logical model

If the subtype of Document is one which has an associated logical model, then
the content of the Document will be parsed and the appropriate logical model
objects created. For example, if a WSDL document contains two portTypes, then
two instances of WSDLPortType will be created and associated with the new
instance of WSDLDocument.
Creating multiple items at once

A GenericObject can be used as a collection to create multiple items with a
single create invocation. For example, to create a WSDL file GGG.wsdl and an
XML Schema file FFF.xsd that it depends on, a GenericObject would be created
and the two documents would be added to the GenericObject with a user-defined
relationship.
When the GenericObject is saved, each document in each of the relationships of
the GenericObject is tested to see if it is already in WSRR. If it is not it is added.
When dependencies such as WSDL imports are encountered, the documents in
the collection are examined to see if they satisfy the dependencies. If they do,
then those documents are used to satisfy the dependencies. If they do not, then
126
the normal processing of dependencies will take place, with a dependency being
satisfied from a document in WSRR if the appropriate document already exists in
WSRR, or an attempt to download the dependency from the URL used to refer to
the dependency.
A GenericObject can contain a relationship to another GenericObject, either a
new GenericObject or an existing one. If a GenericObject contains a relationship
to another GenericObject, then both GenericObjects will be saved.
All of the documents referenced from all of the GenericObjects referenced from
the root GenericObject are considered when looking to satisfy a dependency,
and it is an error if there is more than one document in the set of documents that
can satisfy a single dependency.
A GenericObject can have multiple relationships and all documents in all
relationships are treated equally.
It is possible to save a set of GenericObjects with circular dependencies but there
is no advantage to having circular dependencies and they should generally be
avoided.
Creating a document that depends on a specific version

Another use of GenericObject is to allow a document to be saved with a
dependency on a specific version of a document that is already in WSRR.
In this case, a GenericObject is created to contain the new document and the
mixture of new and existing documents that are required by the new document.
The existing documents are represented by an instance of the appropriate SDO
type which has previously been retrieved from WSRR. The retrieval can be
based on a specific version.
For example, to create a new file GGG.wsdl with a dependency on Version 1.2 of
HHH.xsd, do this:
1. Create a new GenericObject using the SDO DataFactory
2. Create a new WSDLDocument instance using the SRXMLHelper
3. Create a user-defined relationship and add it to the GenericObject with an
initial value that is the WSDLDocument instance for foo.wsdl
4. Retrieve an XSDDocument instance from WSRR for Version 1.2 of HHH.xsd
5. Save the GenericObject in WSRR
When the GenericObject is processed, a new WSDLDocument will be persisted
for GGG.wsdl and when processing the import of HHH.xsd, the location and
targetNamespace of the import in GGG.wsdl will be checked against the locations
and namespaces of other documents in the collection. In this case, the version of
127
HHH.xsd in the collection will match against the import in GGG.wsdl so the import
will be satisfied by Version 1.2 of HHH.xsd and this will be reflected in the
importedSchemas relationship of GGG.wsdl.
A GenericObject can have a dependency on another GenericObject, and if the
GenericObject has relationships to other documents, then the dependencies can
be satisfied by any of the documents related to the second GenericObject.
When a document is included in more than one collection, with different versions
of its dependencies, then all of the dependencies are added to the appropriate
relationships. For example, if W1.wsdl is a WSDL document at Version 1.0 and it
imports X1.xsd at Version 1.0 then the importedSchemas relationship on the
WSDLDocument representing W1.wsdl will include Version 1.0 of X1.xsd. If a
collection is created that includes the same version of W1.wsdl but in this case
Version 1.1 of X1.xsd is required, when the collection is saved, the
importedSchemas relationship on the WSDLDocument representing W1.wsdl will
have two XSDDocuments: one for the original Version 1.0 of X1.xsd and the
second for Version 1.1 of X1.xsd.
Creating a QueryObject
The SDO DataFactory is used to create the different types of QueryObject.
This is illustrated in Example 4-4.
Example 4-4 Creating a QueryObject using the Java API
GraphQuery query =
(GraphQuery)DataFactory.INSTANCE.create(http://www.ibm.com/xmlns/prod/s
erviceregistry/6/0/sdo,GraphQuery);
PropertyQuery query =
(PropertyQuery)DataFactory.INSTANCE.create(http://www.ibm.com/xmlns/pro
d/serviceregistry/6/0/sdo,PropertyQuery);
4.1.3 Retrieving content from WSRR

Any object can be retrieved by its bsrURI as shown in Example 4-5.
Example 4-5 Retrieving a document using the Java API
/*
* Retrieve a document with a known bsrURI. If we know the bsrURI for a
* document it can be retrieved using the retrieve() method. If we
* didn't know the bsrURI we would need to find it using a query
*
128
* The "namespace" property will have been set from the original XML
* content and the "location" property will have been set from the
* original document location.
*/
System.out.println(" retrieving document");
WSDLDocument storedDoc =
(WSDLDocument)serviceRegistry.retrieve(wsdlBsrURI);
System.out.println("
document found:");
name = " + storedDoc.getName());
namespace = " + storedDoc.getNamespace());
version = " + storedDoc.getVersion());
location = " + storedDoc.getLocation());
If the bsrURI is not known then a query would need to be run to find it, as
described in 4.1.6, Querying content in WSRR on page 130.
4.1.4 Updating content in WSRR

These properties are ignored when performing an update:
namespace
name
version
Example 4-6 shows example code retrieving a WSDLDocument, adding two user
defined properties and then updating the registry with the new changes.
Example 4-6 Retrieve a WSDLDocument, add user defined properties and update
try {
// set the bsrURI to the value of a stored WSDLDocument
String wsdlBsrURI = bsrURI;
WSDLDocument documentStored = (WSDLDocument) serviceRegistry
.retrieve(wsdlBsrURI);
// add user defined properties
BSRSDOHelper.INSTANCE.addProperty(documentStored, "prop1",
"value1");
BSRSDOHelper.INSTANCE.addProperty(documentStored, "prop2",
"value2");
// update the document
serviceRegistry.update(documentStored);
// handle exception
129
Updating a GenericObject collection

Calling update with a GenericObject will:
Update the properties on the root GenericObject.
Add any new Documents contained in any of the user-defined relationships of
the root GenericObject.
Remove the association with any documents no longer mentioned in any of
the user-defined relationships of the GenericObject.
For example, if a GenericObject is created with a relationship to documents A, B
and C and is then updated with the relationship containing A, C and D, after the
update the relationship will only contain A, C and D; B is removed. Note that
existing dependencies are not affected by the removal of B from the
GenericObject collection.
4.1.5 Deleting content from WSRR

Logical objects cannot be deleted explicitly, the document that defined them must
be deleted, in which case all the logical objects that were contributed by the
document are also deleted.
Example 4-7 shows how to delete a document using the Java API.
Example 4-7 Deleting a document using the Java API
/*
* Delete a document we no longer need. Documents must be deleted by
* passing the bsrURI to the delete() method.
*/
serviceRegistry.delete(wsdlBsrURI);
4.1.6 Querying content in WSRR

The support for query is based on XPath. There are two types of query:
GraphQuery
PropertyQuery
These types of query are described in the following pages.
130
An example using the GraphQuery and PropertyQuery can be found in

Example 4-8 and Example 4-9 respectively.
Example 4-8 Using GraphQueries with the Java API
try {
GraphQuery query = (GraphQuery) DataFactory.INSTANCE.create(
TypeConstants.SR_URI, TypeConstants.TYPE_GRAPHQUERY);
// retrieve all the XMLDocuments in the registry
query.setQueryExpression("/WSRR/XMLDocument");
List graphQueryResults = serviceRegistry.executeQuery(query);
for (int i = 0; i < graphQueryResults.size(); i++) {
XMLDocument doc = (XMLDocument) graphQueryResults.get(i);
System.out.println(doc.getBsrURI());
System.out.println(doc.getName());
}
// handle exception
}
Example 4-9 Using PropertyQueries with the Java API
try {
PropertyQuery query = (PropertyQuery)DataFactory.INSTANCE.create(
TypeConstants.SR_URI, TypeConstants.TYPE_PROPERTYQUERY);
// retrieve all the XMLDocuments in the registry
query.setQueryExpression("/WSRR/XMLDocument");
BSRSDOHelper.INSTANCE.addProperty(query, "p1", "description");
BSRSDOHelper.INSTANCE.addProperty(query, "p2", "name");
List propertyQueryResults = serviceRegistry.executeQuery(query);
// process each PropertyQueryResultObject found in the list
for (int i = 0; i < propertyQueryResults.size(); i++) {
PropertyQueryResult pqr = (PropertyQueryResult)
propertyQueryResults.get(i);
// get the name
String name =
BSRSDOHelper.INSTANCE.getPropertyQueryResultValue(propertyQueryResult,"
name"));
131
// get the description

String description =
BSRSDOHelper.INSTANCE.getPropertyQueryResultValue(propertyQueryResult,"
description"));
}
// handle exception
}
PropertyQuery
A PropertyQuery returns only a subset of the properties of the objects that match
the query expression. The properties to be returned are specified as the values
of user-defined properties on the PropertyQuery object.
For example, to return the name and description properties, add two
user-defined properties to the instance of PropertyQuery, one with the value
name and the other with the value description. The properties to be returned
must be specified in property values because query objects extend BaseObject
and therefore have their own name, description, and so on.
GraphQuery
GraphQueries retrieve SDO object graphs that represent data held in WSRR. A
depth parameter can be specified on the GraphQuery object that allows you to
specify the depth of relationships that are resolved in the object graph that is
returned.
Specifying a depth parameter of -1 means that a complete object graph is
returned. For example, if a query with depth parameter of -1 returns a single
WSDLService element, you can then programmatically follow all the
relationships (both predefined and user-defined) from the root WSDLService
object that is returned from the query.
Specifying a depth parameter of 0 implies that only the objects that have been
queried for are returned and so you can access all the properties for a given
object, but cannot access any related object programmatically without executing
an additional query.
Predefined queries
WSRR has a number of predefined queries, all of which are GraphQueries with a
depth of 0. Table 4-1 on page 133 lists the queries, giving the name of the query,
a description of the query and a description of the parameters of the query, if any.
132
When supplying the modelled attribute name and attribute value, pass in a String
array:
String[] params = new String[] { "attribute name", "attribute value"};
Table 4-1 WSRR predefined queries
Name of Query
Description
Parameters
getAllWSDLDocuments
Returns all instances of WSDLDocument
None
getAllXSDDocuments
Returns all instances of XSDDocument
None
getAllPolicyDocuments
Returns all instances of PolicyDocument
None
getAllXMLDocuments
Returns all instances of XMLDocument
None
getAllServices
Returns all instances of WSDLService
None
getAllPorts
Returns all instances of WSDLPort
None
getAllBindings
Returns all instances of WSDLBinding
None
getAllPortTypes
Returns all instances of WSDLPortType
None
getAllOperations
Returns all instances of WSDLOperation
None
getAllMessages
Returns all instances of WSDLMessage
None
getAllParts
Returns all instances of WSDLPart
None
getAllElementDeclarations
Returns all instances of ElementDeclaration
None
getAllComplexTypeDefinitions
Returns all instances of ComplexTypeDefinition
None
getAllAttributeDeclarations
Returns all instances of AttributeDeclaration
None
getWSDLDocument
Returns all instances of WSDLDocument that

have a specific value for the named attribute.
1.
getXSDDocument
Returns all instances of XSDDocument that

1. Modelled attribute
name
2. Attribute value
getPolicyDocument
Returns all instances of PolicyDocument that

name
2. Attribute value
getXMLDocument
Returns all instances of XMLDocument that

name
2. Attribute value
Modelled attribute
name
2. Attribute value
133
Name of Query
Description
Parameters
getWSDLDocServices
Return instances of WSDLService

corresponding to the WSDL services defined in
a specific WSDL document
bsrURI of the WSDL

document
getWSDLDocSOAPPorts
Return instances of SOAPPort associated with

the WSDL ports defined in a specific WSDL
document
bsrURI of the WSDL

document
getWSDLDocBindings
Return instances of WSDLBinding

corresponding to the WSDL bindings defined in
a specific WSDL document
bsrURI of the WSDL

document
getWSDLDocSOAPBindings
Return instances of SOAPBinding associated

with the WSDL bindings defined in a specific
WSDL document
bsrURI of the WSDL

document
getWSDLDocPorts
Return instances of WSDLPort corresponding

to the WSDL ports defined in a specific WSDL
document
bsrURI of the WSDL

document
getWSDLDocPortTypes
Return instances of WSDLPortType

corresponding to the WSDL portTypes defined
in a specific WSDL document
bsrURI of the WSDL

document
getWSDLDocOperations
Return instances of WSDLOperation

corresponding to the WSDL operations defined
bsrURI of the WSDL

document
getWSDLDocMessages
Return instances of WSDLMessage

corresponding to the WSDL messages defined
bsrURI of the WSDL

document
getWSDLDocParts
Return instances of WSDLMessage

corresponding to the WSDL messages defined
bsrURI of the WSDL

document
getXSDElements
Return instances of ElementDeclaration

corresponding to the global XML Schema
elements declared in a specific schema
document
bsrURI of the XML

Schema document
getXSDSimpleTypeDefs
Return instances of SimpleTypeDefinition

simple types defined in a specific schema
document
bsrURI of the XML

Schema document
134
Name of Query
Description
Parameters
getXSDComplexTypeDefs
Return instances of ComplexTypeDefinition

complex types defined in a specific schema
document
bsrURI of the XML

Schema document
getXSDAttributeDeclarations
Return instances of AttributeDeclaration

attributes declared in a specific schema
document
bsrURI of the XML

Schema document
getWSDLServices
Return instances of WSDLService that have a

specific value for a specific modelled attribute
name
2. Attribute value
getWSDLPorts
Return instances of WSDLPort that have a

1.
getWSDLPortTypes
Return instances of WSDLPortType that have a

name
2. Attribute value
getAllGenericObjects
Return all instances of GenericObject
None
getUserDefinedRelationshipN
ames
Returns a List of PropertyQueryResult objects

that have the relationship names as a user
defined property of the PropertyQueryResult
(see Example 4-10)
None
getGovernanceRecord
Returns the GovernanceRecord of a governed

object
bsrURI of the object

which has been
governed
Modelled
attribute name
2. Attribute value
Example 4-10 illustrates how to use the WSRR predefined queries to retrieve the
relationship names from the query results list.
Example 4-10 Using WSRR predefined queries to retrieve the relationship names
// "serviceRegistry" is an EJB or Web service client previously created

List propertyQueryResults =
serviceRegistry.executeNamedQuery("getUserDefinedRelationshipNames");
// In this case we want to know the value of the property "name"
// and add it to a list
ArrayList relationshipNames = new ArrayList();
for(int index = 0; index < propertyQueryResults.size(); index++) {
PropertyQueryResult propertyQueryResult =
135
(PropertyQueryResult)propertyQueryResults.get(index);
relationshipNames.add(BSRSDOHelper.INSTANCE.getPropertyQueryResultValue(pr
opertyQueryResult,"name"));
}
4.2 Web services API

Many of the functions in WSRR can also be invoked via a Web services API.
There is both a Java Web service API (4.2.1, Creating a Web services client on
page 136) and a raw SOAP API (4.2.3, SOAP API on page 139).
Not all functionality can be invoked via the Web services API. At the time of
writing all core and ontology functions had a Web services interface but the
governance functionality could only be invoked via the EJB API or the Web user
interface.
4.2.1 Creating a Web services client

As mentioned previously in 4.1.1, Creating a Java client on page 120 there are
two clients which are used to interact with WSRR, supplied with the product.
These is an EJB client and a Web services client. Both use the same interfaces
apart from the EJB has a few more methods for supplying list of information for
tasks such as update and delete.
In order to use either of the clients you must add the required jar files to your
runtime:
sdo-int.jar (This must be as high up the class path as possible to override
SDO 1 interfaces)
A suitable EJB/Web services runtime
Both sdo-int.jar and ServiceRegistryClient.jar can be found in your WSRR
installation directory (e.g. c:\Program Files\IBM\WebSphereServiceRegistry).
The Core Web service makes use of custom bindings to do conversion to/from
Datagraphs. This is illustrated in Figure 4-3 on page 137.
136
Web Service
ServiceRegistry.ear
Generated Client
WSRRCoreSDOClient
Custom Binding
Custom Binding
Figure 4-3 Core Web service client architecture
The WSRRCodeSDOClient allows the user to work with SDO objects directly
and call methods that take the same parameters as the EJB methods.
It has two constructors, one of which takes a userid and password:
com.ibm.serviceregistry.ws.WSRRCoreSDOClient(java.lang.String endpoint)
com.ibm.serviceregistry.ws.WSRRCoreSDOClient(java.lang.String endpoint,
java.lang.String username, java.lang.String password)
The URL to access the Core Web service is:
http(s)://localhost:port/WSRRCoreSDO/services/WSRRCoreSDOPort
The URL to access the Ontology Web service is:
http(s)://localhost:port/WSRROntologyWS/services/WSRR_Ontology_Port
137
The WSDLs can be exported from the WebSphere Application Server

administration console:
Go to Applications ServiceRegisty Publish WSDLs
There is also a Web services client to allow access to ontologies. There is no
special client code needed for the ontology Web service API since it does not use
SDOs. Export the WSDLs from WebSphere as documented previously and then
run the exported file through wsdl2java. The generated code can then be used to
access the Ontology API through Web services. This is described in more detail
in 4.2.2, Ontology Web service on page 138.
Create a Web services client

Example 4-11 shows the example code for connecting to WSRR where security
is turned off on the application server.
Example 4-11 Creating a Web service client
try {
String url = http://localhost/WSRRCoreSDO/services/WSRRCoreSDOPort;
WSRRCoreSDOClient serviceRegistry = new WSRRCoreSDOClient(url);
} catch (ServiceException e) {
// do something
} catch (MalformedURLException e) {
// do something
}
4.2.2 Ontology Web service

The ontology Web service allows you to perform a limited number of tasks for
querying of Ontologies. Unlike the main Web service, no client is supplied, so it is
necessary to create a client using external tooling.
There are a number of ways of generating the client code. For example, you
could use IBM Rational Software Architect or WSDL2Java which comes with
the WebSphere Application Client or WebSphere Application Server.
The typical command for generating the basic client code using WSDL2Java is:
WSDL2Java -a -r client WSRR_Ontology_API_service.WSDL
It is advisable to generate the client using namespace to classname mapping if
possible:
http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/ontology/service =
com.yourcompany.ontology.service
138
http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/ontology/binding =
http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/ontology/portType
= com.yourcompany.ontology.service
http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/ontology/schema =
http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ontology/sdo =
com.yourcompany.ontology.types
Example 4-12 shows an example of how to use the generated ontology Web
service client.
Example 4-12 Using the generated Ontology Web service client
URL url = new

URL("http://hostname:port/WSRROntologyWS/services/WSRR_Ontology_Port");
WSRR_Ontology_ServiceLocator locator = new
WSRR_Ontology_ServiceLocator();
WSRR_Ontology_API_portType port = locator.getWSRR_Ontology_Port(url);
If WebSphere security is turned on, the following two properties need to be
added:
((javax.xml.rpc.Stub)port)._setProperty(Stub.USERNAME_PROPERTY,"usernam
e");
((javax.xml.rpc.Stub)port)._setProperty(Stub.PASSWORD_PROPERTY,"passwor
d");
Trust Stores and Key Stores will also need to be set up.
4.2.3 SOAP API

This is the same SOAP API that is used by the SDO-based Web service client.
This section focuses on the low-level details that are hidden from the user by the
SDO runtime and the WSRR client.
SOAP:
A lightweight, XML-based protocol for exchanging information in a
decentralized, distributed environment. SOAP can be used to query and
return information and invoke services across the Internet.
Note: IBM is working to define a standard API for a service registry such as
WSRR. The current SOAP API will be deprecated when such a standard API
is defined.
139
DataGraphType
Many of the operations have one or more instances of DataGraphType as part of
either an input message or an output message.
This is a specialization of the standard SDO DataGraphType. The
DataGraphType as used by WSRR contains either an instance of the WSRR type
or an instance of the PropertyQueryResult type as the root object.
The data graphs used by WSRR are defined by the XML Schema element shown
in Example 4-13.
Example 4-13 SOAP API DataGraph XML schema
<xsd:element name="datagraph" type="sdo:DataGraphType"/>

<xsd:complexType name="DataGraphType">
<xsd:complexContent>
<xsd:extension base="sdo:BaseDataGraphType">
<xsd:sequence>
<xsd:element ref="wsrrsdo:WSRR" minOccurs="0"/>
<xsd:element ref="wsrrsdo:PropertyQueryResult"
minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
The data graph returned from a property query has an instance of
PropertyQueryResult as the root object of the data graph. All other uses of
DataGraphType have an instance of WSRR as the root object.
With the single exception of updating document content, when a change
summary element is used, none of the BaseDataGraphType elements are used.
WSRR
The artefacts element contains all the objects in the graph of objects that are not
contained in any other object in the graph of objects.
For example, if the graph consists of two WSDLDocument objects, both objects
will be in the artefacts, whereas if the graph consists of a WSDLService and its
WSDLPorts then only the WSDLService will be an artefact as the WSDLPorts
are contained by the WSDLService.
The WSRR type is defined by the XML Schema type shown in Example 4-14 on
page 141.
140
Example 4-14 SOAP API WSRR type XML schema
<xs:complexType name="WSRR">
<xs:sequence>
<xs:element name="root"
type="xs:IDREF"
nillable="false"
sdoxml:propertyType="tns:BaseObject"/>
<xs:element name="artefacts"
type="tns:BaseObject"
nillable="false"
</xs:sequence>
</xs:complexType>
The root element contains the bsrURI value of the object that is the root of the
graph of objects contained by the WSRR instance.
PropertyQueryResult
The PropertyQueryResult contains the set of properties specified in the query,
for one object that matched the query. Each object matching the query is sent
back as a separate instance of DataGraphType.
The PropertyQueryResult is defined by the XML Schema type shown in
Example 4-15.
Example 4-15 SOAP API PropertyQueryResult XML schema
<xs:complexType name="PropertyQueryResult">
<xs:sequence>
<xs:element name="userDefinedProperties"
type="tns:UserDefinedProperty"
minOccurs="0"
</xs:sequence>
</xs:complexType>
Temporary bsrURI values

When creating new objects, a temporary bsrURI value can be assigned to an
object, and one must be assigned to an object if it is necessary to refer to that
object.
If the root object of the data graph is a new object then it must have a temporary
bsrURI value assigned and that value must be specified as the value of the root
element of the WSRR instance.
141
As the type of the bsrURI attribute is the XML Schema ID type, the values must
be compatible with the NCName type, which means that a bsrURI must begin
with a Letter or with the underscore '_' character. As normal bsrURI values begin
with a Letter, a temporary bsrURI value must begin with a '_' character.
Document content
When working with documents, the content of the document is represented as
the value of an attribute named content, and it is encoded using base64
encoding.
Error handling
All of the operations return a ServiceRegistryWebServiceException fault.
The fault contains the message from the exception thrown by the WSRR server.
WSRR portType
The WSRR SOAP API is a document-literal SOAP/HTTP binding of a portType
that provides the following operations:
create
delete
executeNamedQuery
executeNamedQueryWithParameters
executeQuery
retrieve
retrieveWithDepth
update
All the operations are documented in more detail in the WebSphere Service
Registry and Repository Information Center, we will cover create only here, as
an example:
http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do
c/rwsr_soap_api_guide11.html
Create
The createRequest message is an instance of the create element, which
consists of a single datagraph element.
The definition of the create operation is as follows.
142
Example 4-16 SOAP API create operation
<wsdl:operation name="create">
<wsdl:input name="createRequest" message="impl:createRequest"/>
<wsdl:output name="createResponse" message="impl:createResponse"/>
<wsdl:fault name="ServiceRegistryWebServiceException"
message="impl:ServiceRegistryWebServiceException"/>
</wsdl:operation>
The createResponse message is an instance of the createResponse element,
which contains a single string which is the bsrURI value assigned by WSRR to
the root object of the request datagraph.
The following message (Example 4-17) is an example of a create request that
represents creating a single document, in this case an XMLDocument. A single
user-defined property is defined at the time of creation.
Note the use of the temporary bsrURI value of "_1" to refer to the root object.
Example 4-17 Example create a document using the SOAP API
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header/>
<soapenv:Body>
<p244:create
xmlns:p244="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/sdo">
<p905:datagraph xmlns:p905="commonj.sdo">
<p533:WSRR
xmlns:p533="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/sdo">
<p533:root>_1</p533:root>
<p533:artefacts xsi:type="p533:XMLDocument"
bsrURI="_1"
name="CreateSingleObjectTestDocument"
namespace="http://www.ibm.com/colgrave/WSRR/test"
description="Single document created via JAX-RPC"
content="PD94bWwgdmVyc2lvbj0iMS4wIj8+DQo8cm9vdC8+DQo="
location="hexbinarytest.xml">
<p533:userDefinedProperties
name="UserDefinedPropertyOne" value="ValueOne"/>
</p533:artefacts>
</p533:WSRR>
</p905:datagraph>
143
</p244:create>
</soapenv:Body>
</soapenv:Envelope>
The following message (Example 4-18) is an example of a successful response
message.
Example 4-18 Example of a successful response to a create document using SOAP API
<soapenv:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header/>
<soapenv:Body>
<p244:createResponse
xmlns:p244="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/sdo">
<createReturn>
WSRR--c8e644f7.fa84a879.29e0adb9.10db8541a90.6ae36dd4.46
</createReturn>
</p244:createResponse>
</soapenv:Body>
</soapenv:Envelope>
Other examples of using the SOAP API can be found in the WebSphere Service
Registry and Repository Information Center:
c/rwsr_soap_api_guide11.html
4.3 Web user interface (Web UI)

WSRR provides extensive customization capabilities for its user interface,
allowing you to modify the way in which information about your services is
presented to the user. These customization capabilities range from simply
modifying the properties that are displayed on an existing view of a service to
deploying a whole new perspective that defines new views for the information
stored in WebSphere Service Registry and Repository. This new perspective
may be specific to a certain kind of user within your organization, using
terminology that the user can understand and restricting the information
displayed to the minimum that allows the user to perform their day-to-day job.
144
This section describes the concepts and architecture of the Service Registry and
Repository Web user interface. Chapter 10, Customizing the Web UI on
page 381 goes into more detail on how to configure the WSRR user interface.
4.3.1 Web user interface layout

The WSRR Web user interface is structured in a fairly standard way familiar to
most users. A frameset is used to divide the page into three areas, as shown in
Figure 4-4.
Banner
Workarea
Navigation
Figure 4-4 Web user interface frameset
The only portion of the Web user interface that cannot be customized is the
banner. However, if you deploy a custom perspective to WSRR that the current
user is permitted to view, the display name of the custom perspective will appear
in the User perspective list within the banner frame. The user can then switch to
the custom perspective by selecting its name from the list and clicking Go.
145
The content that is displayed within the Navigation and Workarea frames is
controlled by a number of XML definition files. A set of system definition files is
loaded into WSRR as part of the installation process. These files define the
Administrator and User perspectives that are available by default within WSRR.
The XML definition files for these system perspectives can be modified to tailor
them to your business needs.
There are five different types of definition files used by the WSRR user interface,
as follows:
Perspective
Navigation Tree
Collection View
Detail View
View Query
Certain definition files may reference objects that are defined in other definition
files. For instance, a perspective definition must specify the navigation tree that
will be displayed when a user is viewing that perspective as well as the collection
views and detail views that should be used when viewing different types of object
within the perspective. The dependencies that exist between the different types
of definition file form a hierarchical structure for any given perspective, as shown
in Figure 4-5 on page 147.
146
Perspective
Navigation
Tree
Detail
View
Collection
View
View
Query
Figure 4-5 Definition file hierarchy
The sections that follow describe the key concepts of each of the definition file
types used by the WSRR user interface.
4.3.2 Perspectives
A perspective defines the views that users will see when they are browsing the
content of WSRR in the context of that perspective. More specifically, a
perspective defines:
The user roles whose members are permitted to view the perspective.
The navigation tree that will be displayed in the Navigation frame.
The collection views that will be used when displaying collections of objects in
the Workarea frame.
147
The detail views that will be used when displaying a specific object in the
Workarea frame.
A perspective is intended to provide the user with a consistent view of the data
within WSRR. For instance, a Business Analyst perspective would display a
navigation tree and a number of detail views and collection views that all use
consistent terminology that is meaningful to a business analyst. A Service
Developer perspective, on the other hand, would display a different navigation
tree, detail views, and collection views that would be likely to use more technical
terminology that is meaningful to a service developer.
Note: Role-based views
It is recommended that, when you are defining custom perspectives, you
attempt to use consistent terminology and display similar sets of metadata
across all of the views that are used by that perspective. Designing a
perspective in this way should ensure that it provides a role based view onto
the data stored within WSRR.
Roles
WSRR defines the Administrator and the User roles. You can use these roles
when creating a perspective to define the users that are permitted to view that
perspective. By default, any user that is able to log into the Web user interface is
able to see all perspectives that are visible to the User role. However, it is
possible to define additional roles to WSRR that match the roles performed by
the users in your organization. Users or groups can then be mapped to these
custom roles and the visibility of a perspective can then be restricted to just those
users or groups that are mapped to the custom role.
Relationships to other view definitions

It is important to note that a perspective does not contain or own any of the
objects that it refers to. It simply specifies the views that should be used to
display data in the context of the perspective. This allows navigation trees,
collection views and detail views to be shared across several perspectives at the
same time. In fact, many of the system collection views and detail views are
actually shared by the Administrator and User perspectives. This is shown in
Figure 4-6 on page 149.
148
Perspective
Navigation
Tree
Perspective
Detail
View
Collection
View
View
Query
Navigation
Tree
View
Query
Figure 4-6 Reusing view definitions
Due to the loose coupling that exists between the various definition files that
make up a perspective, WSRR does not mandate the order in which the files
must be loaded. As a result, the Web user interface delays attempting to resolve
any of the references between the files until they are required at runtime. This
late binding allows a perspective within the Web user interface to continue to
operate even if some of the view definitions that are referenced by the
perspective have not been loaded into WSRR. It is only when the user attempts
to navigate to an area of the perspective with the missing view definitions that
any problems will occur. At this point, a suitable error message will be displayed
and a WSRR administrator will need to take suitable action to resolve the
problem.
View definition selection precedence

We have explained that users browse the information within WSRR in the context
of a perspective. The view definition mappings for the users current perspective
149
are searched when attempting to resolve the collection or detail view definition
that should be used to display a certain type of object. By default, the WSRR
Web user interface will simply use the name of the underlying SDO object type in
order to select a suitable view definition to use to display the data. For instance, if
you are attempting to view the details of a WSDL document object, the Web user
interface will attempt to find a view definition within your current perspective that
is mapped to WSDLDocument.
However, it is possible to control how a perspective selects the view definition to
use when displaying an object. This is achieved using display types in the other
types of definition files within the user interface. If a display type is specified, this
display type is passed to the perspective and used when attempting to resolve
the view definition mapping instead of the name of the underlying SDO type. In
effect, when you use display types within view query, collection view or detail
view definitions you are stating that you want the information displayed using a
specific view definition.
For additional details on perspectives, see 10.4, Perspectives on page 394.
4.3.3 View queries and navigation trees

The navigation tree is key to the definition of any perspective. It is the starting
point for browsing the information stored within the WSRR. A well designed
navigation tree can help to ensure that a user can find the information that they
are looking for quickly and without the need to browse through several other
panels of information.
Within WSRR, the definition of the navigation tree is actually split into two
different configuration file types:
The visible portion of the navigation tree is defined within a navigation tree
definition file. This defines the physical structure of the navigation tree and the
text that is displayed for each node of the tree. It also defines whether a node
will be rendered as a link and what action should be performed when the link
is selected.
The query that will be executed when a node in the navigation tree is selected
is defined within a view query definition file. A view query definition file can
define multiple view queries, each with an ID. It is possible to override the
behavior of an existing system view query by defining a new view query with
the same ID. However, since view queries are shared across all of the
perspectives defined within WSRR, overriding a system view query may
modify the behavior of another perspective. For this reason, overriding an
existing view query should only be done with caution. View queries can vary
in complexity, from simply returning all objects of a specific type to returning
all of the objects that satisfy certain search criteria. A view query can also
150
specify the collection view that should be used to display the results of the
query.
Figure 4-7 shows how the navigation tree definition file links the nodes within the
navigation tree to the corresponding view queries that will be executed when the
node is selected.
<node id="wsdl"
node-resource-key="wsdLinstances"
view-query-id="showWSDLDocuments"/>
Navigation
Tree
Definition
<Query id="showWSDLDocuments">
<ObjectType>WSDLDocument</ObjectType>
</Query>
View
Query
Definition
Figure 4-7 Defining a navigation tree
Welcome page link and search box

Every navigation tree within WSRR will display a link to the welcome page and a
search box above the actual navigation tree. These items are always displayed
and cannot be configured using the navigation tree definition or view query
definition files.
For additional detail on queries, see 10.2, View query definitions on page 382.
For additional detail on navigation, see 10.3, Navigation trees on page 390.
4.3.4 Collection views

As its name suggests, a collection view is used to display information about a
collection of objects in WSRR. A collection view definition describes the
properties of the underlying object that are to be displayed in columns within the
view and also which action buttons should be displayed. A collection view
definition file can only contain a single collection view definition.
A collection view must also specify which columns within the view will be
displayed as HTML links. Selecting one of these links will navigate the user to the
151
detail view for the object on the corresponding row in the collection view. A
collection view can control the detail view definition that is used to display the
details of the selected object by specifying a display type. Recall that, if a display
type is specified the Web user interface will attempt to resolve it to a detail view
definition using the mappings defined within the current perspective. If a display
type is not specified, the Web user interface uses the SDO type name of the
object in the selected row to find the detail view definition to use.
Figure 4-8 shows the areas of a collection view that are controlled by a collection
view definition.
Title
Description
Button Definitions
Column
Definition
Column
Definition
Column
Definition
Column
Definition
Figure 4-8 Collection views
For additional detail on collection views, see 10.5, Collection views on

page 401.
4.3.5 Detail views

As its name suggests, a detail view is used to display the details of a specific
object in WSRR. A detail view definition describes the properties of the
underlying object that are to be displayed in the detail view and where within the
detail view they will be displayed. A detail view definition file can only contain a
single detail view definition. However, detail views do support the concept of
tabs. Tabs allow different views to be defined onto the same underlying data.
152
However, currently the only type of tab that supports customization is the Details
tab. The area of a detail view defined with a tab definition is shown in Figure 4-9.
Tab Definition
Figure 4-9 Detail view tabs
The way in which a property is displayed on the details tab within a detail view
depends on the type of the property itself and where in the detail view it is
displayed. The details tab is divided into a General Properties section and
multiple Additional Properties sections, as shown in Figure 4-10 on page 154.
153
Additional
Properties
General
Properties
Additional
Properties
Additional
Properties
Figure 4-10 General and additional properties
Properties that are displayed within the General Properties section of the details
view must be of type string. The value of the property is displayed within a text
entry field. Properties that are displayed in an Additional Properties section of the
details view must represent a reference to another object or objects in WSRR.
Properties displayed in the Additional Properties section of a details view are
displayed as HTML links. Selecting one of these links navigates the user to a
detail or collection view for the corresponding property on the object in question.
A detail view can control the view definition that is used to display the resulting
page by specifying a display type. Recall that, if a display type is specified the
Web user interface will attempt to resolve it to a view definition using the
mappings defined within the current perspective.
4.4 Command Line Interface

The Command Line Interface provides full support for all of the WSRR
programmatic APIs, including all administrative operations. It may be used from a
154
standalone Jython or Jacl interpreter, or it may be run inside wsadmin and used
in conjunction with the facilities available there. Several example scripts show
you how to perform governance tasks such as promoting entities from one
WSRR to another, or transitioning entities through different lifecycle states.
See 8.6, Administering WSRR using the CLI on page 299 for information about
how to configure the CLI and how to use it for administrative functions. Several
sample scripts are provided with the CLI that illustrate how to use it for both user
and administrative tasks, more details on these scripts can be found in 8.6.3,
Sample scripts on page 306.
4.5 Admin (JMX)

The WSRR administrative (JMX) interface provides a Java API that allows you to
manage configuration settings to control registry runtime behavior. For example,
loading and removing classification systems (ontologies), setting up access
control policies, or customizing the user interface. In addition, you can register
listeners for specific administration events. Sample client code is provided for you
to build on in the <WSRR_HOME>\admin\javasrc directory.
More information about the WSRR administrative JMX interface can be found in
8.5, Administering WSRR using JMX on page 292.
155
156
Chapter 5.
SOA governance enablers

This chapter describes the features of WebSphere Service Registry and
Repository that enable you to implement the governance processes that exist
within your SOA environment.
This chapter contains the following:
5.2, Lifecycles on page 158
5.3, WSRR security on page 187
5.4, WSRR plugins on page 197
5.5, Impact analysis on page 213
157
5.1 Overview
As discussed in Chapter 1, Introduction to SOA on page 3, SOA dramatically
increases the dynamism of your information system. More accurately, it provides
a means for you to address the requirements for dynamism that most businesses
are already facing. The basic tenet of SOA is to provide an information system
that is responsive to the rate of change faced by your business in its markets.
But that dynamism also brings additional risks, for example:
The risk that someone will change a business process in a way that is
detrimental to the business.
That someone will change a business process or service that places
unexpected and excessive demand on the capacity of the information system,
either crashing the system or having an adverse affect on the other processes
also being served by the information system.
That someone will introduce rogue software that siphons critical business
information.
That someone will change the configuration of the system in way that disrupts
the business.
For these reasons, the SOA lifecycle is layered on a backdrop of a set of
governance processes that ensure that compliance and operational policies are
enforced, and that change occurs in a controlled fashion and with appropriate
authority as envisioned by the business design.
It must be stressed that the scope of governance within an SOA environment
extends beyond any single product. However, WebSphere Service Registry and
Repository is a powerful enabler for SOA governance and provides a number of
mechanisms that allow you to implement the governance processes that have
been specified within your business design. These mechanisms are discussed in
the sections that follow.
5.2 Lifecycles
WebSphere Service Registry and Repository provides support for the definition
and enforcement of lifecycles which can be applied to the objects that it stores.
The process of applying a lifecycle to an object within WSRR is referred to as
making the object governable. An object that currently has a lifecycle applied to it
is referred to as a governed object or governed entity. If, at some point, you
158
decide that you no longer want to apply a lifecycle to an object, you can remove
governance from the object.
Note: Referring to objects in WSRR that have a lifecycle applied to them as
governed objects is a little misleading. It is possible to apply other aspects of
SOA governance to objects within WSRR, such as security and validation,
without applying a lifecycle to the objects. Indeed, applying a lifecycle to an
object in WSRR is optional. However, within this book, when we refer to
governed objects, we are referring to objects that have a lifecycle applied to
them.
During the installation process a simple default lifecycle is loaded into WSRR.
This default lifecycle provides the minimum capability to govern an object, or
collection of objects, in WSRR. This lifecycle is adequate for use in a proof of
concept or for prototyping. However, you should consider defining and deploying
a lifecycle that is more representative of the governance processes defined
within your organization. For more information about replacing the lifecycle
definition in WSRR, see the WebSphere Service Registry and Repository
Information Center:
c/twsr_configrn_governance02.html
5.2.1 State machine terminology

The lifecycle state of an object in WSRR is maintained using a simple state
machine. A state machine basically consists of states with transitions between
them. Within WSRR, an object can transition between states due to a call to the
transition method on the Governance API or due to a user clicking the relevant
button in the Web user interface. The basic terms that define the building blocks
of state machines are defined here:
States
Within WSRR, the state of a governed object simply defines the position of
that object within the governance lifecycle that is being applied to the object.
Composite states
A composite state is an aggregate of one or more states. They can be used to
decompose a complex state machine into a hierarchy of state machines.
Events
In the context of a generic state machine, an event is what triggers a transition
from one state to another. Within WSRR, however, there is only one event that
can trigger a transition for a governed entity. This event is a call to the
Chapter 5. SOA governance enablers
159
transition method on the governance API (the Web user interface uses this
method when transitioning objects as the result of a user action).
Transitions
A transition is the movement that occurs when a governed object moves from
a source state to a target state, as the result of a triggering event. The
transitions that are available for a governed object can be determined by
looking at the transitions whose source state match the current lifecycle state
the object.
5.2.2 Lifecycle definitions

Governance lifecycles in WSRR are defined using a matched pair of files. Both of
these files must be present in WSRR in order to be able to perform any lifecycle
related operations, such as making an object governable or transitioning the
state of an object within the lifecycle from one state to another.
State Adaptive Choreography Language (SACL) file

The actual governance lifecycle itself is defined using the State Adaptive
Choreography Language (SACL). SACL is simply an XML representation of state
machines that is used within WebSphere Process Server. SACL allows you to
define the states that exist within your state machine and the transitions that can
occur to move entities from one state to another.
WSRR only allows one SACL file to be loaded at any given time. However, this
SACL file is capable of defining multiple lifecycles. It is also possible to replace
the default lifecycle within WSRR with a custom lifecycle that is more
representative of the governance processes defined within your organization.
If you decide that you want to define your own lifecycle, a graphical editor is
available for creating and modifying SACL files within WebSphere Integration
Developer. It is also possible manually generate a SACL file using other
development tools. If you decide that you want to manually generate a SACL file,
we recommend that you use an XML editor that performs validation. The SACL
XML schema definition is provided as part of the WSRR fixpack 1 install and can
be found in the <WSRR_ROOT>\admin\schemas directory.
Lifecycle ontology file

Although all of the information required to apply a lifecycle to the objects in
WSRR is contained in the SACL file, WSRR requires additional information in
order to:
Simplify the process of searching for governed objects.
160
Simplify the process of defining access control permissions on governed

objects.
Display states and transitions in a user friendly manner.
WSRR achieves this by using the SACL file to generate a corresponding OWL
file. This OWL file defines a number of classes that represent the states and
transitions that are defined in the SACL file. For each state or transition contained
in the SACL file, there will exactly one OWL class defined in the corresponding
OWL file. At runtime, WSRR uses these OWL classes to classify governed
objects with a classification that corresponds to their state within the lifecycle.
This enables you to construct simple XPath queries that will return all of the
objects in WSRR that are in a given lifecycle state.
Note: The relationship between the states and transitions defined in the SACL
file, and the classes defined in the OWL file, is central to the operation of the
lifecycle state machine. If any modification is made to the SACL file, a
corresponding modification must be made to the OWL file. In other words, the
information that is contained in this matching pair of files must be kept
synchronized to ensure the correct operation of the lifecycle state machine.
Generating the lifecycle ontology file

The lifecycle ontology file does not need to be manually generated. WSRR
provides an Extensible Stylesheet Language Transformations (XSLT) file that is
able to generate the OWL file from the corresponding SACL file. This process is
shown in Figure 5-1 on page 162.
The OWL classes that are generated by the XSLT transform are of the form:
<SACL targetNamespace>#<SACL state or transition>
For example, the OWL class that is generated to represent the initial state of the
default lifecycle (InitialState1) is as follows:
http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/Default
Lifecycle#InitialState1
For more information about generating the lifecycle ontology file from the SACL
file, see the WebSphere Service Registry and Repository Information Center:
c/twsr_configrn_governance20.html
161
SACL
XSLT
XSLT Processor
OWL
Figure 5-1 Generating the lifecycle ontology file
Modifying the lifecycle ontology file

By default, the labels that are generated for the OWL classes only contain the
basic information that is available in the SACL file. For states, the label that is
generated contains the value of the displayName attribute of the SACL state. For
transitions, the label that is generated contains the value of the name attribute, of
the operation element, of the SACL transition.
However, the generated lifecycle ontology file can be edited before it is loaded
into WSRR in order to provide additional information, for example:
More descriptive state and transition labels can be specified.
Translations of the state and transition labels can be specified in order to
provide support for displaying states and transitions in browsers that specify
the relevant locales.
162
Descriptions of the state and transitions can be specified. It is also possible to

provide translations of these descriptions.
Example 5-1 shows an example of an OWL class that has been modified to
include translations of both the label and description.
Example 5-1 Modified OWL class
<owl:Class
rdf:about="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance
/DefaultLifecycle#InitialState1">
<rdfs:label>Created</rdfs:label>
<rdfs:label xml:lang="de">Erstellt</rdfs:label>
<rdfs:label xml:lang="it">Creato</rdfs:label>
...
<rdfs:comment>This initial state represents the default state of a
newly created governed collection.
</rdfs:comment>
<rdfs:comment xml:lang="de">Dieser Anfangszustand gilt als
Standardzustand einer neu erstellten regulierten Sammlung.
</rdfs:comment>
<rdfs:comment xml:lang="it">Questo stato iniziale rappresenta lo
stato predefinito di una collezione governata appena creata.
</rdfs:comment>
...
</owl:Class>
5.2.3 WSRR default lifecycle

As discussed previously, a simple default lifecycle is loaded in to WSRR at
installation time. This lifecycle is based upon the IBM SOA Foundation lifecycle
that was discussed in 1.1.3, SOA lifecycle on page 7. The states and transitions
defined within the WSRR default lifecycle represent the states and transitions
that apply to services as they move through the SOA lifecycle. The WSRR default
lifecycle is shown in Figure 5-2 on page 164.
163
Initial State
Created
Plan
Assemble
Certify
Model
AuthorizeDevelopment
Repair
Deploy
Approve
Revoke
Manage
Retired
Final State
Deprecate
Figure 5-2 WSRR default lifecycle
Created
The Created state represents the initial state of any object, or collection of
objects, within WSRR that is made governable. The transitions that are available
from this state are:
Plan
Performing the Plan transition moves the object, or collection of objects, from
the Created state to the Model state.
Model
In the IBM SOA Foundation lifecycle, modelling is described as the process of
capturing your business design from an understanding of business requirements
and objectives and translating that into a specification of business processes,
goals and assumptions creating an encoded model of your business.
In the context of WSRR, several tasks may be performed when a service is in the
model state including, but not limited to, the following:
Defining the business concepts that are required in order to fully describe
your services within WSRR.
Defining the metadata that must be added to the different types of artefacts
that you will store within WSRR.
Defining who should be allowed to access WSRR and what types of objects
they should be allowed to access.
Identifying existing service artefacts that your new services may depend on.
164
The transitions that are available from this state are:

AuthorizeDevelopment
Performing the AuthorizeDevelopment transition moves the object, or
collection of objects, from the Model state to the Assemble state. This
transition should be performed once the modelling of the service is complete.
Assemble
Services that are in the Assemble state in WSRR are in the process of being
developed and tested. This occurs when the service interface has been defined
and published to WSRR in order to socialize the interface, but the implementation
of the service is not yet complete. This approach allows clients of the new service
to be developed before the service is actually deployed, or for the new service to
be included in composite business process definitions.
Several of the WSRR artefacts that were identified during the Model phase of the
SOA lifecycle may also be created at this point. For instance, GenericObjects
may be created within WSRR or the service artefacts within WSRR may be
decorated with metadata.
Certify
Performing the Certify transition moves the object, or collection of objects,
from the Assemble state to the Deploy state. This transition should be
performed once the implementation of the service is complete.
Deploy
Services that are in the Deploy state in WSRR are in the process of being
deployed to the target runtime environment and tested in that environment. The
length of time that a service may spend in the Deploy state depends on the
complexity of the service. For instance, a simple, self contained service that is to
be hosted in an existing environment might be deployed in a matter of minutes. A
business process, on the other hand, that requires several component services
to be deployed across multiple new hosting environments may take days, or even
weeks, to deploy.
The deployment process might also involve creating or updating service artefacts
within WSRR. For instance, additional artefacts that represent the endpoints of
the deployed services may be created, or metadata regarding the environment
on which the services are being hosted may be added to the service definition.
165

Approve
Performing the Approve transition moves the object, or collection of objects,
from the Deploy state to the Manage state. This transition should be
performed once the deployment and testing of the process is complete and
the testing indicates that the service is functioning correctly.
Repair
Performing the Repair transition moves the object, or collection of objects,
from the Deploy state back to the Assemble state. This transition could be
performed because the testing of the new service indicated that it was not
functioning as required or providing the required levels of performance.
Manage
Services that are in the Manage state in WSRR are services that have been
deployed to a target runtime environment. At this point in the service lifecycle,
WSRR can be used to dynamically locate service endpoints at runtime.
Monitoring software, such as IBM Tivoli Composite Application Manager for
SOA, can also be used to monitor the performance of the services in the runtime
environment and update the service artefacts in WSRR with performance related
metadata. This metadata can, in turn, be used to affect the runtime routing
decisions of runtimes that use WSRR to dynamically locate service endpoints at
runtime.
Deprecate
Performing the Deprecate transition moves the object, or collection of objects,
from the Manage state to the Retired state. This transition should be
performed once the service is no longer required or used by other services
within the SOA environment, maybe as a result of a newer version of the
service being deployed. Impact analysis can be performed to determine the
other services within the SOA that have a dependency on the service in
question.
Revoke
Performing the Revoke transition moves the object, or collection of objects,
from the Manage state back to the Deploy state. This transition could be
performed in order to take the service offline and prevent it from being
invoked by other services, maybe because certain quality of service issues
need to be addressed in the runtime environment. Once again, impact
analysis can be performed to determine the other services within the SOA
that have a dependency on the service in question.
166
Retired
Services that are in the Retired state in WSRR are services that have been
withdrawn from service and should no longer be used.
5.2.4 GovernanceRecords
The lifecycle state of a governed object in WSRR is not stored on the object itself.
Instead, GovernanceRecords are used to encapsulate all of the information
regarding the state of an object in the governance lifecycle. When an object in
WSRR is made governable, a corresponding instance of a GovernanceRecord is
created in order to maintain the state of that object within the governance
lifecycle. It is this GovernanceRecord that is used by the lifecycle state machine
in order to determine the transitions that are available for the governed object.
The lifecycle state machine also uses the GovernanceRecord when the
governed object is transitioned from one state to another within the lifecycle.
Table 5-1 describes the attributes of the GovernanceRecord.
Table 5-1 GovrnanceRecord attributes
Attribute name
Description
entityBsrURI
The entityBsrUri attribute contains the bsrUri of the object that was
made governable. The object that this bsrUri refers to is known as
the root object.
governedObjects
A single GovernanceRecord is able to maintain the state in the

governance lifecycle of a collection of OriginalObjects in WSRR.
The governedObjects attribute is a list that contains references to
all of the OriginalObjects for which this GovernanceRecord is
maintaining lifecycle state. The collection of OriginalObjects that is
referenced by the governedObjects attribute is referred to as a
governed collection. The governed collection will always contain,
at least, a reference to the root object.
state
The state attribute defines the current lifecycle state of all of the
OriginalObjects in the governed collection.
An OriginalObject is any object a user specifically creates such as a Document, a

QueryObject, or a GenericObject. Refer to Figure 3-9 on page 103 to see where
the OriginalObject type fits into the BaseObject model.
Refer to Figure 3-1 on page 80 and 3.2.3, GenericObject on page 83 for
additional information about WebSphere Service Registry and Repository
objects.
167
Note: It is only possible to make the following types of objects governable in

WSRR:
GenericObject
PolicyDocument
SCAModule
WSDLDocument
XMLDocument
XSDDocument
It is not possible to govern derived objects directly. However, derived objects

are governed indirectly by governing the physical document from which they
were parsed. All derived objects are classified with the same governance
lifecycle state as the physical document from which they were parsed and are
consequently returned when querying WSRR for objects classified in this
manner.
Obtaining the GovernanceRecord

The GovernanceRecord for a particular object in WSRR can be obtained using
the getGovernanceRecord method on the Governance API. The bsrURI of the
object in question must be passed as an argument to this method. If the value
returned from this method is null, this indicates that the object in question is not
governed.
The root object

When an OriginalObject in WSRR is made governable, and a corresponding
instance of a GovernanceRecord is created, a reference to the governed object
is stored as the root object of the governed collection in the GovernanceRecord.
The root object of a governance collection has special significance. When you
want to transition the lifecycle state of a governed collection from one state to
another, you must do so using the root object. Attempting to transition the
lifecycle state of a governed collection using any object other than the root object
will cause an error.
Similarly, if you want to remove governance from a governed collection, you must
do so using the root object. Attempting to remove governance from a governed
collection using any object other than the root object will cause an error.
It is possible to determine whether an object is the root object of a governed
collection by comparing its bsrUri with the value of the entityBsrUri attribute on
the GovernanceRecord. If the two bsrUris are the same, then the object in
question is the root object of the governed collection. If the two bsrUris are
168
different, then the value of the entityBsrUri of the GovernanceRecord can be

used to retrieve the root object of the governed collection.
Governed collections
Consider a simple scenario where an OriginalObject exists in WSRR that has no
predefined or user defined relationships to any other OriginalObjects. If this
object is made governable, then the only reference that is added to the list of
governed objects in the GovernanceRecord is the root object. This is shown in
Figure 5-3.
Governed
Governance
Record
Ungoverned
Make
Governable
WSDL
Root Object
WSDL
GovernedObjects
State
Figure 5-3 Governing an object with no relationships to other objects
169
However, a root object may have a number of predefined or user defined

relationships to other OriginalObjects in WSRR, forming an object graph. In this
scenario, when the GovernanceRecord is created, references to all of the
OriginalObjects in this object graph, including the root object, are added to the
list of governed objects in the GovernanceRecord. This is shown in Figure 5-4.
Ungoverned
Governed
XSD
XSD
Governance
Record
Make
Governable
WSDL
Root Object
WSDL
GovernedObjects
Generic
Object
Figure 5-4 Governing an object with relationships to other objects
170
State
XSD
XSD
Generic
Object
For clarity in the discussions that follow, we will group all of the references from
the list of governed objects in the GovernanceRecord and depict them as shown
Figure 5-5.
Governance
Record
Root Object
GovernedObjects
State
XSD
WSDL
XSD
Generic
Object
Governed Collection
Figure 5-5 The governed collection
Adding an object to the governed collection

As previously discussed, the governed collection represents all of the
OriginalObjects that are related in some way to the root object. It is not possible
to explicitly add an OriginalObject in WSRR to a governed collection. Instead, an
171
OriginalObject is added to the governed collection implicitly. This occurs when a

relationship is added from an OriginalObject that is in the governed collection, to
an ungoverned OriginalObject object. This is shown in Figure 5-6.
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
GovernedObjects
State
State
XSD
XSD
Add
Relationship
WSDL
WSDL
XSD
XSD
Generic
Object
XSD
Generic
Object
Governed Collection
XSD
Governed Collection
Figure 5-6 Adding an ungoverned object to a governed collection
In this situation, there is an XSD that is ungoverned. When a relationship is

added from the GenericObject in the governed collection to the XSD, the XSD
becomes part of the governed collection.
172
The direction of the relationship that is added is extremely important. Adding a

relationship from an OriginalObject that is ungoverned, to one of the
OriginalObjects in the governed collection, has no effect on the contents of the
governed collection. This is shown in Figure 5-7.
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
GovernedObjects
State
State
XSD
XSD
Add
Relationship
WSDL
WSDL
XSD
XSD
Generic
Object
Governed Collection
Generic
Object
XSD
XSD
Governed Collection
Figure 5-7 The effect of the direction of a relationship on a governed collection
In this situation, there is an XSD that is ungoverned. When a relationship is

added from the XSD to the GenericObject in the governed collection, the XSD
does not become part of the governed collection.
173
It is also not possible for an OriginalObject in WSRR to be in more than one

governed collection at any given time. If a relationship is added from an
OriginalObject that is in one governed collection, to an OriginalObject that is in
another governed collection, then the contents of both governed collections
remain unchanged. This is shown in Figure 5-8.
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
GovernedObjects
State
State
XSD
XSD
WSDL
WSDL
XSD
XSD
Generic
Object
Governed Collection
XSD
Governed Collection
Figure 5-8 Creating a relationship between two governed objects
In this situation, a relationship has been defined from the GenericObject in one
governed collection to the XSD the other governed collection. Because the target
XSD was already in a governed collection, it has not been added to the governed
collection containing the GenericObject.
Removing an object from the governed collection

In the same way that it is not possible to explicitly add an OriginalObject to a
governed collection, it is also not possible to explicitly remove an OriginalObject
from a governed collection. An OriginalObject is removed from the governed
174
collection implicitly. This occurs when the relationship from an OriginalObject in

the governed collection to the object in question is removed. This is shown in
Figure 5-9.
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
GovernedObjects
State
State
Remove
Relationship
XSD
XSD
WSDL
WSDL
XSD
XSD
Generic
Object
Generic
Object
XSD
Governed Collection
XSD
Governed Collection
Figure 5-9 Removing a governed object from a governed collection
In this situation, the relationship from the GenericObject to the XSD is removed.
As a result, the XSD is also removed from the governed collection containing the
GenericObject.
175
However, this relationship must be the last such relationship from an

OriginalObject in the governed collection to the object in question. If any other
relationships exist from an OriginalObject to the object in question, then the
object will remain within the governed collection. This is shown in Figure 5-10.
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
GovernedObjects
State
State
Remove
Relationship
XSD
Generic
Object
WSDL
XSD
Generic
Object
WSDL
XSD
XSD
Governed Collection
Governed Collection
Figure 5-10 Multiple relationships to an object in a governed collection
In this situation, the GenericObject in the governed collection is the target of a

relationship from both of the XSDs. Removing the relationship from one of the
XSDs to the GenericObject does not remove the GenericObject from the
governed collection due to the fact that it is still the target of a relationship from
the other XSD.
Care must also be taken when removing a relationship to ensure that an entire
branch of the object graph is not inadvertently removed. This can occur when a
relationship to a non-leaf node in the object graph is removed. If this relationship
176
is the only relationship tieing the target object to the governed collection, then the
entire branch of the object graph extending from the target object is removed
from the governed collection. This is shown in Figure 5-11.
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
GovernedObjects
State
State
Remove
Relationship
XSD
XSD
WSDL
WSDL
XSD
XSD
Governed Collection
Generic
Object
Generic
Object
XSD
XSD
Governed Collection
Figure 5-11 Removing multiple governed objects from a governed collection
In this situation, the relationship from the XSD to the GenericObject is removed.
As a result, the branch of the object graph extending from the GenericObject is
removed from the governed collection. In this case, the object graph only
consists of the GenericObject and an XSD to which it is related. However, it is a
conceivable that, in a real world scenario, the number of objects removed from
the governed collection could be far more extensive.
It is also important to note that, during the process of removing an OriginalObject
from a governed collection, it will not be added to another governed collection.
This is the case, even if the object in question is the target of a relationship from
an OriginalObject in another governed collection. This is shown in Figure 5-12 on
page 178.
177
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
GovernedObjects
State
State
Generic
Object
WSDL
Generic
Object
Governed Collection 1
WSDL
Remove Relationship
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
GovernedObjects
State
State
Generic
Object
WSDL
Generic
Object
WSDL
Figure 5-12 Removing a governed object from a governed collection
Notice that a relationship exists between the GenericObject in Governed

Collection 1 and the GenericObject in Governed Collection 2. When the
relationship from the WSDL document to the GenericObject in Governed
Collection 1 is removed, the GenericObject becomes ungoverned, even though
it is still the target of a relationship from the GenericObject in Governed
Collection 2.
The reason for this behavior is that an object in WSRR can be the target of
multiple relationships from multiple different objects. If, when removing an
178
OriginalObject from a governed collection, that object is the target of

relationships originating from objects in several different governed collections,
there would be no way to determine which governed collection to which the
object should be added.
Governed collection best practices

Ensuring that the appropriate lifecycles are being applied to the appropriate set
of objects is essential when enforcing governance in an SOA environment.
WSRR provides you with the means to define the lifecycles that are relevant to
the governance processes within your SOA and to apply these lifecycles to
configurable governed collections. However, because the contents of a governed
collection are determined by examining the relationships that exist within an
object graph, care must be taken when making an object governable and adding
relationships to, or removing relationships from, objects within a governed
collection. The sections that follow describe a number of best practices that
should be followed when dealing with governed collections in WSRR.
Determine the order in which you need to make objects governable

The act of making an OriginalObject governable could implicitly add a number of
objects to the same governed collection. However, the lifecycle that will be
applied to the governed collection might not be appropriate for all of the objects.
Before making an object governable, you should use impact analysis in WSRR to
examine the object graph that extends from that object to ensure that the lifecycle
that will be applied is appropriate for all of the objects that will be added to the
governed collection. If there are objects in the object graph for which the lifecycle
is not appropriate, you will need to make these objects governable first. This will
prevent them from being added to the governed collection of the object in
question. Impact analysis is discussed in 5.5, Impact analysis on page 213.
To illustrate this scenario, consider the default lifecycle that is provided with
WSRR. This lifecycle defines operational states that might only be relevant to
service artefacts that have some form of implementation. For instance, the
deploy and manage states of the default lifecycle might only be relevant to
WSDLs that have a corresponding implementation, such as WSDLs that define a
Service element. A WSDL that only defines a PortType element, on the other
hand, only specifies the service interface and consequently does not have a
corresponding implementation. Similarly, the operational states of the default
lifecycle might not be applicable to XSDs.
179
A more suitable lifecycle for these types of objects is shown in Figure 5-13. This
lifecycle does not define any operational states and, therefore, could be applied
to artefacts in WSRR for which there is no corresponding implementation.
Initial State
Specified
Approve
Approved
Deprecate
Deprecated
Final State
Figure 5-13 Sample lifecycle
180
Now consider the simple object graph shown in Figure 5-14. If the objects in this
object graph were loaded into WSRR, it would be logical to apply different
lifecycles to certain objects. For instance, it would make sense to apply the
lifecycle shown in Figure 5-13 on page 180 to the XSD and the PortType WSDL
documents. It might also make sense to apply the default lifecycle to the two
Service WSDL documents.
XSD
PortType
WSDL
Service
WSDL
Service
WSDL
Figure 5-14 Sample object graph
However, to ensure that the appropriate lifecycle is applied to each of the objects
in the object graph, it is essential to make the objects governable in the correct
order.
181
If you were to make one of the Service WSDL documents governable, applying
the default lifecycle, both the PortType WSDL document and the XSD document
would also be added to the governed collection. This is shown in Figure 5-15.
Governed Collection
XSD
PortType
WSDL
Governance
Record
Root Object
GovernedObjects
Service
WSDL
Service
WSDL
State
Figure 5-15 Applying the same lifecycle
But, as we have already discussed, the default lifecycle that is applied to the
Service WSDL document might not be appropriate for the PortType WSDL
document and the XSD document.
182
In order to ensure that the sample lifecycle can be applied to the PortType
WSDL document and the XSD document, these documents need to be made
governable before the Service WSDL document. Since the PortType WSDL
document imports the XSD document, this can be achieved by making the
PortType WSDL document governable and applying the sample lifecycle. This is
shown in Figure 5-16.
Governed Collection
XSD
PortType
WSDL
Governance
Record
Root Object
GovernedObjects
Service
WSDL
Service
WSDL
State
Figure 5-16 Applying the sample lifecycle first
183
The first Service WSDL document can be then be made governable, applying
the default lifecycle, without affecting the governed collection of the PortType
WSDL document and the XSD document. This is shown in Figure 5-17.
Governed Collection
Governance
Record
XSD
Root Object
GovernedObjects
State
PortType
WSDL
Governance
Record
Root Object
GovernedObjects
Service
WSDL
Service
WSDL
State
Governed Collection
Figure 5-17 Applying the default lifecycle to the Service WSDL document
Of course, in a real world situation, it is unlikely that all of these artefacts would
have been loaded into WSRR at the same point in time. It is more realistic to
suggest that the underlying data model defined by the XSD document would be
designed first and then approved for use in the SOA environment. The service
interface defined by the PortType WSDL document would then be designed and
also approved for use in the SOA environment. Finally, the service
implementations would be developed and deployed, but not necessarily at the
same time.
184
In this scenario, it is quite conceivable that each of the artefacts in our sample
object graph would be loaded into WSRR at different points in time and,
consequently, would be contained within different governed collections. This is
Governance
Record
Governed Collection
Root Object
Governance
Record
Root Object
XSD
GovernedObjects
GovernedObjects
State
State
Governed Collection
PortType
WSDL
Governance
Record
Governance
Record
Root Object
Root Object
GovernedObjects
State
Service
WSDL
Service
WSDL
Governed Collection
Governed Collection
GovernedObjects
State
Figure 5-18 More realistic governed collection membership
Examine the source and target of a relationship before creation

The act of creating a relationship between two objects may implicitly add the
target of the relationship to the governed collection of the source object. Before
you create a relationship between two objects in WSRR, you should examine the
source and target objects of the relationship to determine what, if any, side
effects will occur. The questions that you should ask are as follows:
Is the source object governed?
An object will only be added to a governed collection if it is the target of a
relationship from an OriginalObject that is already governed. If the source
object is not governed, then adding the relationship will not add the target
object to the governed collection.
185
What is the type of the source object in the relationship?

An object will only be added to a governed collection if it is the target of a
relationship from an OriginalObject that is already governed. If the source
object is not an OriginalObject, then adding the relationship will not add the
target object to the governed collection.
Is the target object governed?
The target object of a relationship will only be added to the governed
collection of the source object if it is not already in a governed collection. If the
target object is already governed, then adding the relationship will not add the
target object to the governed collection of the source object.
What is the type of the target object in the relationship?
The target object of a relationship will only be added to the governed
collection of the source object if it is an OriginalObject. If the target object is
not an OriginalObject, then adding the relationship will not add the target
object to the governed collection.
Note: Derived objects can only ever be in the same governed collection as the
physical document object from which they were parsed.
Does the target object define relationships to other OriginalObjects?
The target object of a relationship may itself define a number of relationships
to other OriginalObjects in WSRR. Assuming that the target object is added to
the governed collection of the source object as a result of creating the
relationship, any of the OriginalObjects to which it is related may also be
added to the governed collection of the source object. You must examine the
object graph for the target object to ensure that any OriginalObjects that are
added to the governed collection of the source object are of the appropriate
type for the lifecycle that is being applied.
Examine the target of a relationship before deletion

The act of deleting a relationship between two objects may implicitly remove the
target of the relationship from the governed collection of the source object.
Before you delete a relationship between two objects in WSRR, you should
examine the target object of the relationship to determine what, if any, side
effects will occur. The questions that you should ask are as follows:
Does the target object define relationships to other OriginalObjects?
The target object of a relationship may itself define a number of relationships
to other OriginalObjects in WSRR. Assuming that the target object is removed
from the governed collection of the source object as a result of deleting the
relationship, any of the OriginalObjects to which it is related may also be
186
removed from the governed collection of the source object. You must examine
the object graph for the target object to ensure that any OriginalObjects that
are removed from the governed collection of the source object do not require
the relevant lifecycle to be applied.
5.3 WSRR security

WebSphere Service Registry and Repository makes use of the security
mechanisms provided by WebSphere Application Server to ensure that only
authenticated users are able to access the various interfaces that it exposes.
However, it also extends these capabilities to allow more fine grained access
control to the information that it stores. These capabilities are discussed in the
sections that follow.
5.3.1 J2EE security roles

As a J2EE application, WebSphere Service Registry and Repository defines a
number of security roles within its deployment descriptors. When global security
is enabled within WebSphere Application Server these J2EE security roles are
used to restrict who can access WSRR at runtime. In other words, WebSphere
Application Server uses these roles to enforce standard J2EE security within the
relevant J2EE containers at runtime.
The J2EE security roles defined by WSRR are:
User
Administrator
In order to be able to access the WSRR Web user interface, or to invoke methods
on the WSRR API, a user must at least be mapped to the J2EE User role. By
default the special subject AllAuthenticatedUsers is mapped to both the User and
Administrator roles during WSRR installation. Mapping the
AllAuthenticatedUsers special subject to a role maps any user that has
authenticated to WebSphere Application Server to that role. Therefore, in a
default WSRR installation, all users who are able to authenticate to WSRR are
able to perform any action against WSRR.
187
Note: It is recommended that you modify the relevant environment script prior
to installation to ensure that only those users or groups who are permitted to
access WSRR are mapped to the relevant roles.
However, note that the Server user ID that is configured in your WebSphere
Application Server environment must be mapped to the Administrator J2EE
security role in WSRR. If this mapping is not defined, WSRR will fail to start
when running in a WebSphere environment where security has been enabled.
5.3.2 User defined roles

The access control provided by the use of J2EE security roles within WSRR is
very coarse grained. It is only able to control who can access the WSRR Web
user interface or the WSRR API methods themselves. It is not able to control
access to the objects on which the WSRR API methods operate.
In order to provide more fine grained access control functionality, WSRR
provides an authorization component that allows additional roles to be defined
and for permissions to be added to these roles. User or Group principals must be
explicitly mapped to these roles in order for the principal to have the entitlement
(permissions) associated with the role.
When a method is invoked on the API, WSRR uses the authorization component
to determine whether the user is authorized to perform the requested action on
the target object or objects. Therefore, in a secure environment each method
invocation on the WSRR API results in the user being authorized twice, once for
standard J2EE role based access control and once for the more fine grained
access control provided by WSRR. This is shown in Figure 5-19.
Figure 5-19 Role based authorization within WSRR
188
Note: Any roles that are defined to the authorization component in WSRR are
completely separate from the J2EE security roles defined within the
deployment descriptors for the WSRR application. At runtime WebSphere
Application Server is only aware of the Administrator and User J2EE security
roles.
To simplify the installation and configuration of WSRR, the installation process
creates roles within the WSRR authorization component that match the J2EE
security roles. That is, the installation process creates an Administrator and a
User role within the WSRR authorization component. It also maps the same
users and groups to these roles that are mapped to the J2EE security roles.
5.3.3 Permissions
A permission within WSRR encapsulates an action and the target objects on
which it can be performed. Adding a permission to a role grants the users who
are mapped to that role the permission to perform the specified action on the
specified target objects. This is shown in Figure 5-20.
Role
Name: Administrator
Permission
Permission
Permission
Name: CreateWSDLPermission
Name: CreateWSDLPermission
Action:
srrCreate
Name:
CreateWSDLPermission
Action: srrCreate
Target:
/WSRR/WSDLDocument
Action: srrCreate
Target:: /WSRR/WSDLDocument
Figure 5-20 Roles and permissions in WSRR
The sections that follow describe the properties that can be defined on a
permission within WSRR.
189
Name
The name of the permission is used to identify the permission within WSRR. The
name of a permission must be unique within the context of a specific role. It is
possible, therefore, to create permissions with the same name on different roles.
Note: It is recommended that you use unique permission names for all of the
permissions that you define to the WSRR authorization component.
Action
The action property for a permission specifies the operation that the permission
authorizes. Table 5-2 describes the actions that can be specified for permissions
in WSRR.
Table 5-2 Valid actions for WSRR permissions
190
Name
Description
srrCreate
Permissions that specify the srrCreate action authorize the

target objects to be created in WSRR.
srrRetrieve
Permissions that specify the srrRetrieve action authorize the

target objects to be retrieved from WSRR. Permissions that
specify this action can be used to control access to objects
that are retrieved from WSRR using both the retrieve and
query methods on the WSRR API. When a user is
performing a query against WSRR, any objects that they are
not authorized to see will not be included in the query results.
srrUpdate
Permissions that specify the srrUpdate action authorize the

target objects to be updated within WSRR. This includes
updates to both the metadata and the content of the target
objects.
srrDelete
Permissions that specify the srrDelete action authorize the

target objects to be deleted from WSRR.
srrTransition
Permissions that specify the srrTransition action authorize

the target objects to be transitioned within WSRR.
srrManageGov
Permissions that specify the srrManageGov action authorize

the target objects to be governed, or to have governance
removed, in WSRR.
Note: The permissions that are defined using these actions are completely
independent of each other. For example, defining a permission to allow a
specific type of artefact to be deleted does not imply that permission to update
that type of artefact is automatically granted.
Target
The target property for a permission specifies the objects in WSRR to which the
permission applies. The target is specified using the WSRR query language. As
discussed in 3.6, XPath on page 99, the WSRR query language is based on a
subset of XPath 2.0 with support for Service Data Objects (SDO) properties,
relationships, and some additional functions to support querying by classification.
A simple example of a query expression is shown here:
/<PathExpression>[<FilterExpression>]
The <PathExpression> element defines the type of object to which the
permission applies and must match one of the types described in Chapter 3,
Information model on page 79. The type specified can appear at any point in
the WSRR information model type hierarchy. For instance, if you specified a
<PathExpression> of /WSRR/BaseObject for a permission then that permission
would apply to all objects in WSRR, since all of the object types in the WSRR
information model extend BaseObject. If, however, you specified a
<PathExpression> of /WSRR/WSDLDocument then that permission would only apply
to objects of type WSDLDocument in WSRR, since this type has no sub-types.
Note: The <PathExpression> element must always be prefixed with /WSRR.
Note: When defining permissions that specify the srrCreate or srrDelete

actions, the type specified must be one of the following:
GenericObject
OriginalObject
PolicyDocument
SCAModule
WSDLDocument
XMLDocument
XSDDocument
QueryObject
GraphQuery
PropertyQuery
191
The <FilterExpression> element defines additional constraints that can be used

to further restrict the objects in WSRR to which the permission applies. Table 5-3
shows some example filter expressions that can be used when specifying the
target of a permission. More complex filter expressions can be specified by
combining multiple expressions using the AND or OR operators. Up to five
expressions can be combined into a single, more complex, filter expression using
this mechanism.
Table 5-3 Example filter expressions
Expression
Example
Description
@property
@foo
This filter expression filters the target objects to those

that contain the specified property. The example
shown filters the target objects to those that have a
property named foo.
@property=value
@foo=bar

that contain the specified property with the specified
value. The example shown filters the target objects to
those that have a property named foo with a value of
bar.
The following restrictions apply when specifying a filter
expression of this form:
Only single valued properties are supported

Only the equality operator = is supported
classifiedByAnyOf
classifiedByAnyOf(
'classificationURI_1',
'classificationURI_2'
)

that are classified by any of the specified classification
URIs. The example shown filters the target objects to
those that are classified by classificationURI_1 or
classificationURI_2.
classifiedByAllOf
classifiedByAllOf(
'classificationURI_1',
'classificationURI_2'
)

that are classified by all of the specified classification
URIs. The example shown filters the target objects to
those that are classified by classificationURI_1 and
classificationURI_2.
Default permissions
WSRR adopts a permissive approach to access control in the authorization
component. This means that access to all of the artefacts in WSRR is
unrestricted by default. This approach allows users to continue to access objects
in WSRR when security is enabled, without the need to define permissions that
explicitly grants them access to these objects.
192
However, once a role is explicitly granted access to a set of target objects in

WSRR, all other roles are implicitly denied access to that set of objects. In this
situation, in order for other roles to access the same set of target objects, each
role must also be explicitly granted access to the set of objects.
For example, if you added a permission to the Administrator role that granted its
members permission to create WSDLDocument objects in WSRR, all other roles
that were defined to the authorization component would no longer be able to
create WSDLDocument objects. In order to grant users in a Developer role the
permission to create WSDLDocuments, you would need to add the same
permission to this role.
Administrator permissions
WSRR defines a set of default permissions that are used to control access to
governed objects. Table 5-4 describes the default permissions that are granted to
the Administrator role.
Table 5-4 Administrator default permissions
Permission
Description
Name:
GovernedCreatePermission
Action:
srrCreate
Target:
/WSRR/BaseObject[
classifiedByAnyOf(
'<URI>a#State'
)]
This permission authorizes WSRR Administrators to

create objects that are classified by one of the states
defined by the WSRR default lifecycle. This is most likely
to occur when using the createGovernable method on the
WSRR Governance API.
Name:
GovernedRetrievePermission
Action:
srrRetrieve
Target:
/WSRR/BaseObject[
classifiedByAnyOf(
'<URI>a#State'
)]
Granting this permission to the Administrator role

implicitly denies other roles the permission to perform this
action on the target objects.
retrieve objects from WSRR that are classified by one of
the states defined by the WSRR default lifecycle.
action on the target objects. However, limited capability to
retrieve the target objects is granted to the User role by
the GovernedUserRetrievePermissionA and
GovernedUserRetrievePermissionB permissions. These
permissions are described in Table 5-5 on page 195.
193
Permission
Description
Name:
GovernedUpdatePermission
Action:
srrUpdate

update objects in WSRR that are classified by one of the
states defined by the WSRR default lifecycle.
Target:
/WSRR/BaseObject[
classifiedByAnyOf(
'<URI>a#State'
)]
Name:
GovernedDeletePermission
Action:
srrDelete
Target:
/WSRR/BaseObject[
classifiedByAnyOf(
'<URI>a#State'
)]
Name:
GovernanceTransitionPermission
Action:
srrTransition
Target:
/WSRR/BaseObject
Name:
GovernanceManagePermission
Action:
srrManageGov
Target:
/WSRR/BaseObject

action on the target objects. However, limited capability to
update the target objects is granted to the User role by the
GovernedUserUpdatePermission permission. This
permission is described in Table 5-5 on page 195.
delete objects from WSRR that are classified by one of
the states defined by the WSRR default lifecycle.
action on the target objects. Therefore, by default, once
an object in WSRR is governed it can only be deleted by
an Administrator.
transition the lifecycle state of any type of object in WSRR
from one state to another.
action on any type of object in WSRR. Therefore, by
default, only an Administrator is able to transition the
lifecycle state of an object in WSRR from one state to
another.
make any type of object, or collection of objects,
governable and to remove governance from any type of
object, or collection of objects, in WSRR.
implicitly denies other roles the permission to perform
these actions on any type of object in WSRR. Therefore,
by default, only an Administrator is able to make an object,
or collection of objects, governable or remove governance
from an object, or collection of objects, in WSRR.
a. Where <URI> is http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/DefaultLifecycle
194
User Permissions
In isolation, the default permissions that are granted to the Administrator role
would prevent normal WSRR users from accessing governed objects. In order to
grant the User role a restricted level of access to governed objects, WSRR
defines a set of default permissions for this role. Table 5-5 describes the default
permissions that are granted to the User role.
Table 5-5 User default permissions
Permission
Description
Name:
GovernedUserUpdatePermission
Action:
srrUpdate
This permission authorizes WSRR Users to update

objects in WSRR that are classified by the lifecycle state
Model (State1) or Assemble (State2).
Target:
/WSRR/BaseObject[
classifiedByAnyOf(
'<URI>a#State1',
'<URI>a#State2',
)]
Name:
GovernedRetrievePermissionA
Action:
srrRetrieve
Target:
/WSRR/BaseObject[
classifiedByAnyOf(
'<URI>a#State1',
'<URI>a#State2',
)]
Name:
GovernedRetrievePermissionB
Action:
srrRetrieve
Target:
/WSRR/BaseObject[
classifiedByAnyOf(
'<URI>a#State3',
'<URI>a#State4',
)]
This permission authorizes WSRR Users to retrieve

objects from WSRR that are classified by the lifecycle
state Model (State1) or Assemble (State2).
This permission authorizes WSRR Users to retrieve

objects from WSRR that are classified by the lifecycle
state Deploy (State3) or Manage (State4).
a. Where <URI> is http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/DefaultLifecycle
Note: The GovernedRetrievePermissionA and GovernedRetrievePermissionB

permissions do not grant members of the User role the authority to retrieve objects
from WSRR that are in the Created (InitialState1) or Retired (FinalState1) lifecycle
states.
195
5.3.4 Extensible Access Control Markup Language (XACML)

The Extensible Access Control Markup Language is an XML based language
that is designed to express security rules, policies and policy sets that define the
access rights of users (subjects) to resources. The goal of XACML is to provide a
common policy language that allows organizations to enforce all of the elements
of their security policy across all of the components of their IT infrastructure. The
XACML specifications were developed through a collaborative effort involving
various companies including IBM, Sun Microsystems, and Entrust. XACML
was ratified by the Organization for the Advancement of Structured Information
Standards (OASIS) in February 2003. The XACML specification can be found
here:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xacml
The WSRR authorization component uses XACML to represent the security
policies that have been defined to it. It generates XACML policy files that are then
stored in WSRR and are used during application startup to initialize the WSRR
authorization component with the current security policies. The WSRR
authorization component makes use of two policy files and these are discussed
in more detail in the sections that follow.
Role mapping file

The WSRR authorization roles, and the User and Group principals that have
been mapped to these roles, are defined in the role mapping XACML file. This file
is read from WSRR during application startup and is used to initialize the role
mappings within the WSRR authorization component. The role mapping file is
stored in WSRR as configuration document called SrrAuthzRoleMappingXacml of
type XACML.
Authorization policy file

The WSRR authorization policy is defined in the authorization policy XACML file.
This file defines the mapping between permissions and the roles to which they
have been added. This file is read from WSRR during application startup and is
used to initialize the authorization policy within the WSRR authorization
component. The authorization policy file is stored in WSRR as a configuration
document called SrrAuthCheckedPolicyXacml of type XACML.
196
Note: While it is possible to modify these XACML files directly and load them
into WSRR, it is not recommended. The WSRR administration MBean
provides all of the operations that are required in order manipulate the
contents of these files, as follows:
addRole
removeRole
addPrincipalToRole
removePrincipalFromRole
getRolesWithPermissions
removePermissionFromRole
removeAllRolePermissions
removeAllRoles
addPermissionToRole
addPermissionToRole2
getPermissionsForRole
persistPolicy
persistRoleMappings
See Chapter 8, Administering WSRR on page 281 for more information

about using the administration MBean.
5.4 WSRR plugins

WebSphere Service Registry and Repository provides system programming
interfaces that allow you to implement code that can invoked during the standard
processing performed by WSRR. Classes written to these interfaces are referred
to as WSRR plugins. Plugins enable you to implement code that enforces the
governance processes that are defined by the business design within your SOA
environment.
There are currently two types of plugin defined within WebSphere Service
Registry and Repository, as follows:
Validators
Notifiers
Validators are invoked prior to persisting the changes for the relevant API method
within WSRR. Notifiers are invoked at the end of the relevant API method call.
The invocation sequence for a single validator and a single notifier is shown in
Figure 5-21 on page 198. If multiple validators or notifiers have been configured
within WSRR, separate calls to each validator or notifier in the chain may be
made as a result of a single call to the WSRR API.
197
Figure 5-21 Validator and notifier invocation
Note: The implementation classes for both validation and notification plugins
are able to make use of the WSRR API at runtime. However, they MUST avoid
creating instances of the ServiceRegistrySession or
ServiceRegistryGovernance EJBs within their constructors.
When an instance of one of these EJBs is created, it instantiates the set of
plugin instances that it will use to perform validation and notification for each
method invoked. If the constructors for any of the plugins create an instance of
one these EJBs, an infinite loop will occur. For this reason, plugins should
delay creating instances of these EJBs until the instance is actually required
(lazy initialization).
Note: Both validation and notification plugins are invoked synchronously, on

the same thread of execution as the WSRR EJB, as shown in Figure 5-21. You
should avoid performing long running operations in your plugin implementation
to ensure that the WSRR EJB method call completes in a reasonable amount
of time and the EJB thread is returned to the ORB thread pool.
5.4.1 Validators
Validation plugins are invoked at the beginning of calls to certain WSRR API
methods. They provide you with an opportunity to validate that the operation
being performed on the objects within WSRR complies with the policies that are
defined within your SOA environment. For instance, there may be a policy within
198
your SOA environment that states that all Web services deployed to the SOA
must be compliant with Version 1.0 of the WS-I Basic Profile.
A validator is also able to modify the objects that are passed to WSRR. This
provides you with an opportunity to define additional metadata on the objects
before they are persisted to the database.
This is the approach taken in the template validator that is provided with WSRR.
This validator is used when creating instances of an OriginalObject from a
template. The template validator modifies the OriginalObject during creation to
add the properties and relationships that are defined on the relevant template.
Validator interfaces
The validator interfaces defined by the WSRR API are shown in Figure 5-22.
Figure 5-22 Validator interfaces
Notice that there are actually two validator interfaces defined by the API. The
ServiceRegistryValidator interface defines the methods that you should
implement if you require validation to occur as a result of invoking operations on
the WSRR Core API. The ServiceRegistryGovernanceValidator interface
extends the ServiceRegistryValidator interface and defines additional
methods that you should implement if you require validation to occur as a result
of invoking operations on the WSRR Governance API.
199
Note: The methods that are defined by the

ServiceRegistryGovernanceValidator interface are only invoked for objects
that are currently part of a governed lifecycle. That is, they will only be invoked
on a governance validator as a result of invoking a WSRR Governance API
method on a governed object.
Create method
The create method is invoked before an instance of an OriginalObject is created
in WSRR. The create method is passed a reference to the OriginalObject that is
about to be created in order to perform the required validation tasks. The
validator is able to modify this object to ensure that it conforms with the relevant
governance policies that are in place before it returns from the create method.
The create method must return a ServiceRegistryStatus object to indicate
whether the validation process succeeded or failed. If the create method returns
a SUCCESS or WARNING return code in the ServiceRegistryStatus object,
WSRR will persist the new object.
If the create method returns an ERROR return code in the
ServiceRegistryStatus object, WSRR will throw a
ServiceRegistryValidationException from the invoked WSRR API method and
the new object will not be created in WSRR.
Update method
The update method is invoked before an existing OriginalObject within WSRR is
updated. The update method is passed references to the object in its current
state (oldObject) and its new state (newObject) in order to perform the required
validation tasks. The validator is able to modify the new state (newObject) of the
object to ensure that it conforms with the relevant governance policies that are in
place before it returns from the update method.
The update method must return a ServiceRegistryStatus object to indicate
whether the validation process succeeded or failed. If the update method returns
WSRR will persist the changes to the OriginalObject.
If the update method returns an ERROR return code in the
the changes to the OriginalObject will not be persisted to WSRR.
200
Delete method
The delete method is invoked before an existing OriginalObject within WSRR is
deleted. The delete method is passed a reference to the object that is about to be
deleted in order to perform the required validation tasks. For example, it may be
necessary to ensure that the object to be deleted is not the target of any
relationships that have been defined on other objects within WSRR.
The delete method must return a ServiceRegistryStatus object to indicate
whether the validation process succeeded or failed. If the delete method returns
WSRR will delete the OriginalObject.
If the delete method returns an ERROR return code in the
the OriginalObject will not be deleted from WSRR.
Transition method
The transition method is invoked before a governed object, or governed object
collection, is transitioned to a new governance lifecycle state. The transition
method is passed a reference to the object whose governance lifecycle state is
being changed and the transition that is being performed. The validator is able to
modify the governed object, or governed object collection, to ensure that it
conforms with the relevant governance policies that are in place before it returns
from the transition method.
Note: If the target of the transition is a governed object collection then the
OriginalObject passed to the transition method is the root object of the
governed object collection.
The transition method must return a ServiceRegistryStatus object to indicate
whether the validation process succeeded or failed. If the transition method
returns a SUCCESS or WARNING return code in the ServiceRegistryStatus
object, WSRR will modify the governance lifecycle state of the specified
OriginalObject.
If the transition method returns an ERROR return code in the
ServiceRegistryValidationException from the transition method that was
invoked on the WSRR Governance API and the governance lifecycle state of the
OriginalObject will not be modified within WSRR.
201
Note: If a transition completes successfully the governance lifecycle state of

the governed object, or governed object collection, is updated. As a
consequence of these updates, the update method of any other registered
validators may be invoked.
Validate method
The validate method is invoked as the result of an explicit call to the validate
method on the WSRR Governance API. The validate method is passed a
reference to the governed object, or governed object collection, that is to be
validated.
The validate method must return a ServiceRegistryStatus object to indicate
whether the validation process succeeded or failed. If the validate method
returns a SUCCESS or WARNING return code in the ServiceRegistryStatus
object, WSRR considers the validation to be a success and processing within the
WSRR client application continues as normal.
If the transition method returns an ERROR return code in the
ServiceRegistryStatus object, WSRR considers the validation to have failed
and will throw a ServiceRegistryValidationException from the validate method
that was invoked on the WSRR Governance API.
Note: Invoking the validate method on the WSRR Governance API will cause
the validate method on all of the registered governance validators to be
invoked for the governed object or governed object collection. However, the
validate method on the WSRR Governance API is simply a convenience
method that forces the validators to be invoked. Any modifications made by a
validator to the governed object, or governed object collect, will not be
persisted to WSRR.
The ServiceRegistryStatus object

As discussed previously, the ServiceRegistryStatus object is primarily used by
a validator method to indicate the success or failure of that method. This is
achieved by setting the return code on the ServiceRegistryStatus object to one
of the constant values defined by the ServiceRegistryStatus class, as follows:
SUCCESS
WARNING
ERROR
The default value of the return code for new instances of ServiceRegistryStatus
objects is SUCCESS. The return code for a ServiceRegistryStatus object will
202
remain set to the highest value it is given. For example, if the return code for an
instance of a ServiceRegistryStatus object is set to ERROR and then
subsequently set to SUCCESS or WARNING, the return code for that object will
remain at the ERROR level. If you need to reduce the level of the return code, you
must create a new instance of a ServiceRegistryStatus object and set the
required return code value.
ServiceRegistryStatus diagnostics
Validator methods should not throw exceptions to indicate that validation has
failed. However, a validator method may need to provide more information about
the failure of the validation process, particularly in situations where this process
is complex. If a validator method needs to provide more information about the
results of the validation process, it can add diagnostic objects or messages to the
ServiceRegistryStatus object that is returned using the methods shown in
Example 5-2.
Example 5-2 ServiceRegistryStatus diagnostic methods
public void addDiagnostic(int returnCode, Object message)

public void addException(Exception ex)
Both of these methods add the diagnostic information to an ordered list of
diagnostics that is maintained within the ServiceRegistryStatus object instance.
Note: Invoking the addException(Exception ex) method on a
ServiceRegistryStatus instance will automatically set the return code for that
instance to ERROR.
5.4.2 Notifiers
Notification plugins are invoked at the end of calls to certain WSRR API methods.
They provide you with an opportunity to perform various post processing tasks
based on the result of the operation that was requested. For instance, there may
be a policy within your SOA environment that states that an audit trail must be
maintained for all interactions with WSRR.
Notifier interfaces
The notifier interfaces defined by the WSRR API are shown in Figure 5-23 on
page 204.
203
Figure 5-23 Notifier interfaces
Notice that there are actually two notifier interfaces defined by the API. The
ServiceRegistryNotifier interface defines the methods that you should
implement if you require notification to occur as a result of invoking operations on
the WSRR Core API. The ServiceRegistryGovernanceNotifier interface
extends the ServiceRegistryNotifier interface and defines additional methods
that you should implement if you require notification to occur as a result of
invoking operations on the WSRR Governance API.
Note: The methods that are defined by the
ServiceRegistryGovernanceNotifier interface are only invoked for objects
that are currently part of a governed lifecycle. That is, they will only be invoked
on a governance validator as a result of invoking a WSRR Governance API
method on a governed object.
Note: There is no validate method defined on the

ServiceRegistryGovernanceNotifier interface. This is due to the fact that the
validate method on the WSRR Governance API is simply a convenience
method that forces the validators to be invoked.
Create method
The create method is invoked after an instance of an OriginalObject has been
created in WSRR, or after an attempt to create an instance of an OriginalObject
has failed. The create method is passed the following parameters:
A reference to the object that was created, or whose creation failed.
A boolean success flag that indicates whether the create method succeeded
or failed. True indicates that the object was created successfully. False
indicates that the creation of the object failed.
204
An exception parameter that indicates the cause of the failure if the creation of
the object failed. The value of this parameter will be null if the creation of the
object succeeded.
Update method
The update method is invoked after an object stored in WSRR has been
updated, or after an attempt to update an object in WSRR has failed. The update
method is passed the following parameters:
A reference to the original state of the object that was updated, or whose
update failed.
A reference to the new state of the object that was updated, or whose update
failed.
A boolean success flag that indicates whether the update method succeeded
or failed. True indicates that the object was updated successfully. False
indicates that the update of the object failed.
An exception parameter that indicates the cause of the failure if the update of
the object failed. The value of this parameter will be null if the update of the
object succeeded.
Note: The type of the oldObject and newObject parameters that are passed to
this method is BaseObject. This means that the update method on a notifier
can be invoked when any type of object within WSRR is updated, not just
OriginalObjects.
Delete method
The delete method is invoked after an instance of an OriginalObject has been
deleted from WSRR, or after an attempt to delete an instance of an
OriginalObject has failed. The delete method is passed the following
parameters:
A reference to the object that was deleted, or whose deletion failed.
A boolean success flag that indicates whether the delete method succeeded
or failed. True indicates that the object was deleted successfully. False
indicates that the deletion of the object failed.
An exception parameter that indicates the cause of the failure if the deletion of
the object failed. The value of this parameter will be null if the deletion of the
object succeeded.
Transition method
The transition method is invoked after a governed object, or governed object
collection, has been transitioned to a new governance lifecycle state, or after an
205
attempt to transition to a new governance lifecycle state has failed. The transition
method is passed the following parameters:
The URI of the transition that was performed or failed.
A reference to the original state of the governed object, or governed object
collection, whose governance lifecycle state was being transitioned, or whose
transition failed.
A reference to the new state of the governed object, or governed object
collection, whose governance lifecycle state was being transitioned, or whose
transition failed.
A boolean success flag that indicates whether the transition method
succeeded or failed. True indicates that the governance lifecycle state of the
governed object, or governed object collection, was modified successfully.
False indicates that the transition failed.
An exception parameter that indicates the cause of the failure if the transition
of the governed object, or governed object collection, failed. The value of this
parameter will be null if the transition of the governed object, or governed
object collection, succeeded.
Note: If the target of the transition is a governed object collection then the
OriginalObject passed to the transition method is the root object of the
governed object collection.
5.4.3 Packaging plugins

As discussed previously, a plugin is simply a Java class that implements one of
the plugin interfaces defined within the WSRR API. Plugin implementations must
be made available to WSRR on the classpath at runtime. The recommended way
to achieve this is to package all of the classes required by a plugin into a JAR file
and to add this JAR file to the classpath of a suitably configured shared library
within the WebSphere Application Server instance on which WSRR is running.
The deployment of WSRR plugins is discussed in more detail in 13.3.3,
Deploying custom plugins on page 491.
To simplify the plugin installation and configuration process, multiple plugins can
be packaged into the same JAR file. However, it may also be desirable to
package each plugin and its dependent classes into separate JAR files to allow
more granularity at deployment time.
206
5.4.4 Configuring plugins

Validation and notification plugins are configured in WSRR using configuration
properties files. These configuration properties files are stored within WSRR
itself. Initial versions of these configuration properties files are loaded into WSRR
during the installation process in order to configure the default validation and
notification plugins that are required by WSRR.
In order for your custom validation and notification plugins to be invoked at
runtime, you must modify the relevant configuration properties file within WSRR.
Since these configuration properties files form part of the administration
configuration of WSRR, the administration MBean must be used in order to
retrieve and update the relevant files.
Typically you will use the retrieveConfiguration operation on the administration
MBean to retrieve a configuration properties file. You then need to modify the
retrieved file to include the entries for the relevant plugins. You then use
updateConfiguration operation on the administration MBean to load the
modified configuration properties file back into WSRR. In order for the
configuration changes to take effect, you will need to restart the application
server on which WSRR is running. The administration MBean is described in
more detail in 8.5, Administering WSRR using JMX on page 292.
Table 5-6 shows the parameters that should be passed to the administration
MBean when invoking the retrieveConfiguration or updateConfiguration
operations to work with the configuration properties files for validation or
notification plugins.
Table 5-6 MBean operation parameters
Plugin type
Configuration Name
Configuration type
System
configuration
Validator
ValidationProperties
PLUGIN_PROPERTIES
true
Notifier
NotificationProperties
PLUGIN_PROPERTIES
true
Validator plugin properties

The configuration properties file for validation plugins uses the standard Java
format for properties files. The properties within the file are specified as key/value
pairs. The set of keys that can be used within the configuration properties file for
validation plugins is shown in Table 5-7 on page 208.
207
Table 5-7 Valid property keys for defining validation plugins

Configuration properties key
Description
validators
Validation plugins listed against this

key will be invoked as a result of the
relevant WSRR API methods being
invoked on any type of object.
validators.<OBJECT_TYPE>

invoked on objects of the specified
type. Currently, only OriginalObject
sub-classes can be specified, as
follows:
WSDLDocument
XSDDocument
PolicyDocument
XMLDocument
GenericObject
validators.classification.<CLASSIFICATION>

invoked on objects that are classified
by the specified classification URI.
governanceValidators

relevant WSRR API being invoked on
an object that is part of a governed
lifecycle. Any validation plugins listed
against this key must implement the
ServiceRegistryGovernanceValidator
interface.
Note: Due to the limitations of the Java properties file, any classification URI
specified as part of a key within the file must not contain any : (colon)
characters. These should simply be omitted from any classification URI
specified.
The values specified within the configuration properties file must be a comma
separated list of fully qualified class names for the required validation plugins. As
discussed in 5.4.3, Packaging plugins on page 206, the implementation classes
208
for any validation plugins that are specified in the configuration properties file
must be made available to WSRR on the classpath at runtime.
The default configuration properties file for validation plugins that is loaded into
WSRR during the installation process is shown in Example 5-3.
Example 5-3 Default configuration properties file for validation plugins
# These validators are called for all document types

validators=com.ibm.sr.api.SRTemplateValidator
# These validators are called for governed objects only
governanceValidators=com.ibm.sr.governance.api.SRGovernanceValidator
As you can see, this configuration properties file defines two default validation
plugins, as follows:
com.ibm.sr.api.SRTemplateValidator
This validation plugin provides support for applying templates to instances of
OriginalObjects during their creation.
com.ibm.sr.governance.api.SRGovernanceValidator
This validation plugin ensures that any updates to governed objects within
WSRR do not modify governance related metadata.
Note: The SRTemplateValidator and SRGovernanceValidator plugins are
system plugins that are required by WSRR at runtime. These validators should
not be removed when you are modifying the configuration properties file for
validation plugins.
Example 5-4 provides an example of how the configuration properties file for
validation plugins can be updated to include two additional validators. Notice that
the com.ibm.itso.plugins.ITSODefaultValidator plugin has been added to the
list of the plugins for the validators key. Also, the
com.ibm.itso.plugins.WSIComplianceValidator has been added against the
validators.WSDLDocument key. This validator will only be invoked when WSRR
API methods are invoked on objects of type WSDLDocument.
Example 5-4 Modified configuration properties file for validation plugins

validators=com.ibm.sr.api.SRTemplateValidator,com.ibm.itso.plugins.ITSO
DefaultValidator
# These validators are called for WSDLDocuments only
validators.WSDLDocument=com.ibm.itso.plugins.WSIComplianceValidator
209
# These validators are called for governed objects only

governanceValidators=com.ibm.sr.governance.api.SRGovernanceValidator
Validator chains
For any given call to the WSRR API, several validators may need to be invoked to
enforce various aspects of the governance policies defined within your SOA
environment. WSRR allows multiple validators to be configured for any given
type of object. This enables you to implement each validator such that it enforces
just a single aspect of your overall governance policy. Combinations of validators
can then be deployed and configured to WSRR to build up the overall
governance policy that is required in your SOA environment.
When a call is made to one of the relevant WSRR API methods at runtime,
WSRR determines which validators need to be invoked. Using the information
contained within the configuration properties file for validation plugins, WSRR
builds a list of the applicable validators and then invokes the relevant method on
each validator in turn. The list of validators that need to be invoked for a specific
API method call is known as a validator chain.
The order in which the validators are added to the validator chain is as follows:
1. If the target of the WSRR API method call is a governed object, any
governance validators are added to the validator chain.
2. General validators.
3. Classification specific validators.
4. Object type specific validators
If multiple validators are listed against one of the relevant keys in the
configuration properties file, these validators are added to the validator chain in
the order in which they are listed.
It is valid for the same validator to appear several times in the configuration
properties file for validation plugins. In this situation, the same plugin may appear
more than once in the validator chain. If this occurs, WSRR will only invoke the
validator in question once, at the earliest opportunity.
If any of the validators in the chain return a ServiceRegistryStatus object that
indicates that the validation failed, WSRR will not invoke the remaining validators
in the chain. More importantly, the WSRR API implementation module will not be
invoked for the relevant method. In this situation, WSRR will invoke any
registered notifiers that are relevant for the method, indicating to each notifier
that the operation failed using the success flag. Once all of the relevant notifiers
have been invoked a ServiceRegistryValidationException is returned to the
210
client. The invocation sequence for a single validator that fails validation, and a
single notifier is shown in Figure 5-24.
Figure 5-24 Failed validation invocation sequence
Note: Unlike validators, notifiers are not able to affect the execution of a
WSRR API method. They are simply notified of the result of a WSRR API
method call, giving them opportunity to perform any required post-processing
tasks.
Notifier plugin properties

The configuration properties file for notification plugins uses the standard Java
format for properties files. The properties within the file are specified as key/value
pairs. The set of keys that can be used within the configuration properties file for
validation plugins is shown in Table 5-8.
Table 5-8 Valid property keys for defining notification plugins
Description
notifiers
Notification plugins listed against this key will be invoked as

a result of the relevant WSRR API methods being invoked
on any type of object.
211
Description
notifiers.<OBJECT_TYPE>

on objects of the specified type. Currently, only
OriginalObject sub-classes can be specified, as follows:
WSDLDocument
XSDDocument
PolicyDocument
XMLDocument
GenericObject
notifiers.classification.<CLASSIFICATION>

on objects that are classified by the specified classification
URI.
governanceNotifiers

a result of the relevant WSRR API being invoked on an
object that is part of a governed lifecycle. Any notification
plugins listed against this key must implement the
ServiceRegistryGovernanceNotifier interface.
Note: Due to the limitations of the Java properties file, any classification URI
specified as part of a key within the file must not contain any : (colon)
characters. These should simply be omitted from any classification URI
specified.
The values specified within the configuration properties file must be a comma
separated list of fully qualified class names for the required notification plugins.
As discussed in 5.4.3, Packaging plugins on page 206, the implementation
classes for any notification plugins that are specified in the configuration
properties file must be made available to WSRR on the classpath at runtime.
The default configuration properties file for notification plugins that is loaded into
WSRR during the installation process is shown in Example 5-5.
Example 5-5 Default configuration properties file for notification plugins
# These notifiers are called for all document types

notifiers=com.ibm.sr.api.ServiceRegistryNotifierJMS
# These notifiers are called for governed objects only
governanceNotifiers=com.ibm.sr.api.ServiceRegistryNotifierJMS
212
As you can see, this configuration properties file defines a single default
notification plugin, as follows:
com.ibm.sr.api.ServiceRegistryNotifierJMS
This notification plugin provides support for publishing notification events to the
relevant JMS topics used by WSRR.
Note: The ServiceRegistryNotifierJMS plugin is a system plugin that is
required by WSRR at runtime. This notifier should not be removed when you
are modifying the configuration properties file for notification plugins.
Example 5-6 provides an example of how the configuration properties file for
notification plugins can be updated to include two additional notifiers. Notice that
the com.ibm.itso.plugins.ITSOAuditNotifier plugin has been added to the list
of the plugins for the notifiers key. Also, the
com.ibm.itso.plugins.WSIComplianceNotifier has been added against the
notifiers.WSDLDocument key. This notifier will only be invoked when WSRR API
methods are invoked on objects of type WSDLDocument.
Example 5-6 Modified configuration properties file for notification plugins
# These notifiers are called for all document types

notifiers=com.ibm.sr.api.ServiceRegistryNotifierJMS,com.ibm.itso.plugin
s.ITSOAuditNotifier
# These notifiers are called for WSDLDocuments only
notifiers.WSDLDocument=com.ibm.itso.plugins.WSIComplianceNotifier
# These notifiers are called for governed objects only
governanceNotifiers=com.ibm.sr.api.ServiceRegistryNotifierJMS
5.5 Impact analysis

The huge majority of objects that are stored in WSRR do not exist in isolation.
Each object may define a number of predefined relationships (also known as
modelled relationships) or user defined relationships that connect them to other
objects in WSRR, forming an object graph. These relationships indicate
dependencies that exist between the objects in the object graph. They can be
traversed in order to determine which objects may be affected by changes to
other objects in the graph. However, for any non-trivial object graph, attempting
to perform this task manually would be a time consuming process. The impact
213
analysis functionality within WSRR can automatically traverse the relationships in

an object graph to determine the list of dependent objects.
More specifically, the impact analysis component recursively navigates the
relationships that originate from a specified object, building a list of all of the
reachable objects in the object graph. It is this list that is returned as a result of
running impact analysis. It represents the collection of objects in WSRR that may
be affected by a change to the specified object.
5.5.1 Dependencies
When the impact analysis component in WSRR is traversing the relationships of
an object graph, the direction of the relationships between the objects in the
graph is extremely important. The impact analysis component categorizes these
relationships by the type of dependency that they define between objects in
WSRR. These are:
Outbound dependencies
Inbound dependencies
When you initiate impact analysis using either the Web user interface or the
governance API, you must specify which type of dependency you want to be
analyzed. The sections that follow described the different types of dependency
that can exist between objects in WSRR.
Outbound dependencies
An object, Object A, has an outbound dependency on another object, Object B, if
a modelled or user defined relationship exists from Object A to Object B. To put it
more simply, Object A has an outbound dependency on Object B if Object A
depends on Object B.
Using our simple object graph, shown in Figure 5-25 on page 215, the two
Service WSDL documents each have an outbound dependency on the
PortType WSDL document. The PortType WSDL document itself has an
outbound dependency on the XSD document.
214
XSD
PortType
WSDL
Service
WSDL
Service
WSDL
Figure 5-25 Sample object graph
In order to determine the list of objects on which a specific object depends, you
must invoke the getOutboundDependencies() method on the governance API,
specifying the bsrUri of the object in question.
If you are using the Web user interface, you must navigate to the Impact
Analysis tab for the object in question and ensure that the Include entities this
entity depends on check box is checked, as shown in Figure 5-26 on page 216.
215
Figure 5-26 Retrieving outbound dependencies using the Web user interface
Inbound dependencies
An object, Object A, has an inbound dependency from another object, Object B,
if a modelled or user defined relationship exists from Object B to Object A. To put
it more simply, Object A has an inbound dependency from Object B if Object B
depends on Object A.
Once again, using the simple object graph, shown in Figure 5-25 on page 215,
the XSD document has an inbound dependency from the PortType WSDL
document and the PortType WSDL document has two inbound dependencies,
one from each of the Service WSDL documents.
In order to determine the list of objects that depend on a specific object, you must
invoke the getInboundDependencies() method on the governance API,
specifying the bsrUri of the object in question.
If you are using the Web user interface, you must navigate to the Impact
Analysis tab for the object in question and ensure that the Include entities that
depend on this entity check box is checked, as shown in Figure 5-27 on
page 217.
216
Figure 5-27 Retrieving inbound dependencies using the Web user interface
Dependency depth
It is possible to restrict the extent to which the impact analysis component
traverses the object graph by specifying the depth of the analysis. In the context
of the impact analysis, the depth refers to the number of relationships that need
to be been traversed in order to navigate from the object on which impact
analysis is being performed, to any other object in the object graph. When
traversing the object graph, the impact analysis component stops analyzing a
given branch once the specified depth has been reached for that branch.
Specifying a suitable value for the depth is important when performing impact
analysis, since each object that is found when traversing a relationship is itself
analyzed for dependencies. Specifying a depth that is too small could lead to
important objects further down the object graph not being returned in the
dependency list. Specifying a depth that is too large could lead to a huge list of
dependent objects being returned, making it difficult to identify the most
important dependencies.
A value for the depth can be specified on both the getOutboundDependencies()
and getInboundDependencies() method on the governance API and also on the
217
Web user interface, using the Dependency depth field on the Impact Analysis
tab, as shown in Figure 5-28.
Figure 5-28 Specifying impact analysis depth using the Web user interface
5.5.2 Specifying modelled dependency relationships

As discussed in 2.2, Architecture of WebSphere Service Registry and
Repository on page 66, when loading documents into WSRR, the document
content is stored as a physical document object. However, during the process of
loading WSDL and XSD documents, WSRR parses the content of the document
and creates derived objects that represent the important structural elements of
the document. Relationships are added to these derived objects to associate
them with the physical document object from which they were parsed.
For example, consider a simple WSDL document that defines a single PortType
element. This PortType element itself defines a single Operation element with
both Input and Output message elements. When this WSDL document is loaded
into WSRR, a WSDLDocument object is created to represent the document itself
218
and several derived objects are created to represent the elements contained
within the document. Each of the derived objects has a relationship named
document that references the WSDLDocument object from which it was parsed. This
is shown in Figure 5-29.
Derived Objects
WSDLPortType
WSDLOperation
Physical Document
document
WSDL
WSDLMessage
WSDLPart
WSDLMessage
WSDLPart
WSDLPart
Figure 5-29 Physical and derived objects
Understanding the distinction between physical document objects, derived

objects, GenericObjects and how all of these objects are related to each other is
essential when performing impact analysis, because you must specify the list of
modelled and user defined relationships that you want the impact analysis
component to traverse in the object graph when attempting to determine the
dependencies.
219
Note: When performing impact analysis, the relationships that you specify do
not need to exist on the root object. Each object that is discovered during
impact analysis will itself be assessed to determine if it possesses any of the
modelled or user defined relationships that have been specified. If it does,
then these relationships are traversed and the objects that are discovered are
assessed, and so on until the specified depth is reached.
If the object does not contain any of the specified modelled or user defined
relationships the impact analysis component is unable to traverse the relevant
branch of the object graph any further and the object in question is considered
to be a leaf node.
The list of modelled relationships that should be traversed when performing
impact analysis is specified using the modelledRelationships parameter of the
the getOutboundDependencies() or getInboundDependencies() method on the
governance API. This parameter must contain the list of modelled relationship
names. If you are using the Web user interface, you can specify the modelled
relationships to be traversed by selecting them in the Built-in relationships list
box on the Impact Analysis tab, as shown Figure 5-30 on page 221.
220
Figure 5-30 Specifying modelled relationships
The modelled relationships that can be specified when performing impact

analysis on a number of the object types in the WSRR information model are
described in the sections that follow. Each of these sections contain a table that
describes whether each modelled relationship represents an inbound or
outbound dependency. They also specify both the name of the relationship that
must be used when performing impact analysis using the governance API
(shown as SDO) and the name of the relationship that must be used when
performing impact analysis using the Web user interface (shown as UI).
Common relationships
All of the types defined by the information model in WSRR are an extension of
the BaseObject type. As a consequence, all of the object types in WSRR share
some common relationships that can be specified when performing impact
analysis. These are described in Table 5-9 on page 222.
221
Table 5-9 Common modelled relationships that can be traversed during impact analysis
Relationship name
Dependency type
Description
SDO:
classificationURIs
Outbound
UI:
Entity Reference
to classification
When an object in WSRR is classified, the URI of the

classification is added to the classificationURIs list
on the object. This creates a dependency from the
object to the OntologySystem that defines the
classification URI.
If this relationship is specified when performing
impact analysis, all of the OntologySystem objects on
which the object depends will be included in the
returned list.
SDO:
governedObjects
UI:
Relationship to
object in the same
governance group
Inbound
When an object in WSRR is added to a governed

collection, the bsrUri of the object is added to the
governedObjects list of the relevant
GovernanceRecord object. This creates a
dependency from the GovernanceRecord to the
object.
impact analysis, the GovernanceRecord for the object
will be included in the returned list.
These relationships are shown in Figure 5-31.
Governance
Record
governedObjects
classificationURIs
BaseObject
Ontology
System
Figure 5-31 Common modelled relationships that can be traversed during impact
analysis
Note: At the time of writing, specifying the classificationURIs relationship

when using the governance API, or the Entity Reference to classification
relationship when using the Web user interface, does not result in any
OntologySystem objects being included in the returned dependency list,
regardless of how the object in question is classified.
222
Note: At the time of writing, specifying the Relationship to object in the

same governance group relationship when using the Web user interface to
perform impact analysis on a governed object, results in the GovernanceRecord
being included in the returned dependency list. However, the display name of
the GovernanceRecord object is (no value). Also, attempting to select this entry
in the displayed dependency list will cause an error similar to the following to
be displayed:
The item was of a type GovernanceRecord for which no detail view definition
exists in perspective Administrator.
Note: The relationship name Relationship to object in the same

governance group is somewhat misleading. This name suggests that all of
the objects in the same governed collection will be included in the dependency
list if this relationship is specified when performing impact analysis. However,
as we have described, specifying this relationship simply returns the
associated GovernanceRecord.
OriginalObject relationships
All of the physical document type objects defined by the information model in
WSRR ultimately extend the OriginalObject type. The GenericObject type also
extends OriginalObject. As a consequence, all of the physical document types
and the GenericObject type share some common relationships that can be
specified when performing impact analysis. These are described in Table 5-10.
Table 5-10 Modelled relationships that can be traversed for OriginalObjects during impact analysis
Relationship name
Dependency type
Description
SDO:
predecessors
Outbound/Inbound
UI:
Entity
Relationship to
predecessor
An OriginalObject in WSRR can refer to previous

versions of itself using the predecessor relationship.
This creates a dependency from the object to the
previous versions of the OriginalObject.
impact analysis of outbound dependencies, all of the
OriginalObject instances referred to by the
predecessors relationship will be included in the
returned list.
impact analysis of inbound dependencies, the
OriginalObject instance that is a later version of the
object in question will be included in the returned list.
223
Relationship name
Dependency type
Description
SDO:
template
Outbound
UI:
Non-derived entity
reference to its
template
An OriginalObject in WSRR can be based on a

template. The template is defines a number of
properties and relationships that should be added to
an instance of an OriginalObject when the template
is applied to them. Applying a template to an
OriginalObject creates a dependency from the
object to the ComplexTypeDefinition that defines
the template.
impact analysis, the ComplexTypeDefinition object
that defines the template will be included in the
returned list.
Original
Original
Object
Original
Object
Object
predecessors
Original
Object
template
Complex
Type
Definition
Figure 5-32 Modelled relationships that can be traversed for OriginalObjects during
impact analysis
Document relationships
All of the physical document types objects defined by the information model in
WSRR extend the Document type. As a consequence, all of the physical
document types share a common relationships that can be specified when
performing impact analysis. These are described in Table 5-11.
Table 5-11 Modelled relationships that can be traversed for Document objects during impact analysis
Relationship name
Dependency type
Description
SDO:
document
Inbound
UI:
Derived entity
reference to its
source document
See Table 5-14 on page 229 for a description of the

relationship from LogicalObject objects to Document
objects.
224
Logical
Object
document
Document
Figure 5-33 Modelled relationships that can be traversed for Document objects during
impact analysis
WSDLDocument relationships
analysis on WSDLDocument objects are described in Table 5-12.
Table 5-12 Modelled relationships that can be traversed for WSDLDocuments during impact analysis
Relationship name
Dependency type
Description
SDO:
importedWSDLs
Outbound/Inbound
UI:
WSDL document
to imported
WSDL document
A WSDL document, WSDL A, may import another

WSDL document, WSDL B. When these documents
are loaded into WSRR, a reference to WSDL B is
added to the importedWSDLs list of WSDL A. This
creates a dependency from the WSDLDocument object
representing WSDL A to the WDSLDocument object
representing WDSL B.
impact analysis of outbound dependencies, all of the
WSDLDocument objects that are referenced by the
importedWSDLs relationship will be included in the
returned list.
impact analysis of inbound dependencies, all of the
WSDLDocument objects that import the WSDLDocument
in question will be included in the returned list.
225
Relationship name
Dependency type
Description
SDO:
importedXSDs
Outbound
UI:
WSDL or XSD
document to
imported XSD
document
A WSDL document, WSDL A, may import an XSD

document, XSD A. When these documents are
loaded into WSRR, a reference to XSD A is added to
the importedXSDs list of WSDL A. This creates a
dependency from the WSDLDocument object
representing WSDL A to the XSDDocument object
representing XSD A.
impact analysis, all of the XSDDocument objects that
are referenced by the importedXSDs relationship will
be included in the returned list.
SDO:
includedXSDs
UI:
WSDL or XSD
document to
included XSD
document
Outbound
A WSDL document, WSDL A, may include an XSD

document, XSD A. When these documents are
loaded into WSRR, a reference to XSD A is added to
the includedXSDs list of WSDL A. This creates a
dependency from the WSDLDocument object
representing WSDL A to the XSDDocument object
representing XSD A.
are referenced by the includedXSDs relationship will
be included in the returned list.
SDO:
redefinedXSDs
UI:
WSDL or XSD
document to
redefined XSD
document
Outbound
A WSDL document, WSDL A, may redefine

elements defined in an XSD document, XSD A.
When these documents are loaded into WSRR, a
reference to XSD A is added to the redefinedXSDs
list of WSDL A. This creates a dependency from the
WSDLDocument object representing WSDL A to the
XSDDocument object representing XSD A.
are referenced by the redefinedXSDs relationship
will be included in the returned list.
These relationships are shown in Figure 5-34 on page 227.
226
WSDL
WSDL
WSDL
importedWSDLs
importedXSDs
includedXSDs
redefinedXSDs
WSDL
XSD
XSD
XSD
Figure 5-34 Modelled relationships that can be traversed for WSDLDocuments during impact analysis
XSDDocument relationships
analysis on XSDDocument objects are described in Table 5-13.
Table 5-13 Modelled relationships that can be traversed for XSDDocuments during impact analysis
Relationship name
Dependency type
Description
SDO:
importedXSDs
Outbound/Inbound
UI:
WSDL or XSD
document to
imported XSD
document
An XSD document, XSD A, may import another XSD

document, XSD B. When these documents are loaded
into WSRR, a reference to XSD B is added to the
importedXSDs list of XSD A. This creates a
dependency from the XSDDocument object representing
XSD A to the XSDDocument object representing XSD B.
If this relationship is specified when performing impact
analysis of outbound dependencies, all of the
XSDDocument objects that are referenced by the
importedXSDs relationship will be included in the
returned list.
analysis of inbound dependencies, all of the
XSDDocument and WSDLDocument objects that import the
XSDDocument in question will be included in the returned
list.
227
Relationship name
Dependency type
Description
SDO:
includedXSDs
Outbound/Inbound
UI:
WSDL or XSD
document to
included XSD
document
An XSD document, XSD A, may include an XSD

document, XSD B. When these documents are loaded
into WSRR, a reference to XSD B is added to the
includedXSDs list of XSD A. This creates a
dependency from the XSDDocument object representing
XSD A to the XSDDocument object representing XSD B.
includedXSDs relationship will be included in the
returned list.
XSDDocument and WSDLDocument objects that include the
XSDDocument in question will be included in the returned
list.
SDO:
redefinedXSDs
UI:
WSDL or XSD
document to
redefined XSD
document
Outbound/Inbound
An XSD document, XSD A, may redefine elements

defined in an XSD document, XSD B. When these
documents are loaded into WSRR, a reference to XSD
B is added to the redefinedXSDs list of XSD A. This
creates a dependency from the XSDDocument object
representing XSD A to the XSDDocument object
representing XSD B.
redefinedXSDs relationship will be included in the
returned list.
XSDDocument and WSDLDocument objects that redefine
elements in the XSDDocument in question will be
included in the returned list.
228
importedXSDs
includedXSDs
redefinedXSDs
WSDL
WSDL
WSDL
XSD
importedXSDs
includedXSDs
redefinedXSDs
XSD
XSD
XSD
Figure 5-35 Modelled relationships that can be traversed for XSDDocuments during impact analysis
LogicalObject relationships
All of the derived object types defined by the information model in WSRR
ultimately extend the LogicalObject type. As a consequence, all of the derived
object types share a common relationship that can be specified when performing
impact analysis. This is described in Table 5-14.
Table 5-14 Modelled relationships that can be traversed for LogicalObjects during impact analysis
Relationship name
Dependency type
Description
SDO:
document
Outbound
UI:
Derived entity
reference to its
source document
Recall that the document relationship on a derived

object (LogicalObject) references the physical
document instance from which it was parsed. This
creates a dependency from the derived object to the
physical document object.
impact analysis, the Document object that is
referenced by the document relationship will be
Logical
Object
document
Document
Figure 5-36 Modelled relationships that can be traversed for LogicalObjects during
impact analysis
229
Note: It is important to remember that LogicalObjects are created as a result

of parsing the contents of a physical document object. While the document
relationship on each derived object refers to the physical document object
from which they were parsed, the physical document object has no knowledge
of any of the derived objects that were produced from it. As a result, it is not
possible to perform impact analysis on a physical document and use modelled
relationships alone to discover the derived objects that are associated with it.
WSDLPortType relationships
analysis on WSDLPortType objects are described in Table 5-15.
Table 5-15 Modelled relationships that can be traversed for WSDLPortTypes during impact analysis
Relationship name
Dependency type
Description
SDO:
operations
Outbound
UI:
WSDL Port Type

to WSDL
Operation
A portType element in a WSDL document can

define a number of operations. If this is the case,
when loaded into WSRR the operations relationship
on the WSDLPortType object will contain references to
the WSDLOperation objects that were created when
the document was parsed. This creates a
dependency from the WSDLPortType object to the
relevant WSDLOperation objects.
impact analysis, all of the WSDLOperation objects that
are referenced by the operations relationship will be
SDO:
portType
UI:
WSDL Binding to
WSDL Port Type
230
Inbound

relationship from WSDLBinding objects to
WSDLPortType objects
portType
WSDL
Binding
WSDL
Port
Type
operations
WSDL
WSDL
Operation
WSDL
Operation
Operation
Figure 5-37 Modelled relationships that can be traversed for WSDLPortTypes during impact analysis
WSDLOperation relationships
analysis on WSDLOperation objects are described in Table 5-16.
Table 5-16 Modelled relationships that can be traversed for WSDLOperations during impact analysis
Relationship name
Dependency type
Description
SDO:
inputMessage
Outbound
UI:
WSDL Operation
to WSDL Input
Message
An operation element in a WSDL document can

define an input message. If this the case, when
loaded into WSRR the inputMessage relationship on
the WSDLOperation object will contain a reference to
the WSDLMessage object that was created when the
document was parsed. This creates a dependency
from the WSDLOperation object to the relevant
WSDLMessage object.
impact analysis, the WSDLMessage object that is
referenced by the inputMessage relationship will be
231
Relationship name
Dependency type
Description
SDO:
outputMessage
Outbound
UI:
WSDL Operation
to WSDL Output
Message

define an output message. If this the case, when
loaded into WSRR the outputMessage relationship
on the WSDLOperation object will contain a reference
to the WSDLMessage object that was created when the
WSDLMessage object.
impact analysis, the WSDLMessage object that is
referenced by the outputMessage relationship will be
SDO:
faults
Outbound
UI:
WSDL Operation
to WSDL Fault
Message

define a number of fault messages. If this the case,
when loaded into WSRR the faults relationship on
the WSDLOperation object will contain references to
the WSDLMessage objects that were created when the
WSDLMessage objects.
impact analysis, all of the WSDLMessage objects that
are referenced by the faults relationship will be
SDO:
operations
Inbound
UI:
WSDL Port Type

to WSDL
Operation

relationships from WSDLPortTpye objects to
WSDLOperation objects.
WSDL
Port
Type
operations
WSDL
Operation
inputMessage
outputMessage
faults
WSDL
WSDL
Message
WSDL
Message
Message
Figure 5-38 Modelled relationships that can be traversed for WSDLOperations during impact analysis
232
WSDLMessage relationships
analysis on WSDLMessage objects are described in Table 5-17.
Table 5-17 Modelled relationships that can be traversed for WSDLMessages during impact analysis
Relationship name
Dependency type
Description
SDO:
messageParts
Outbound
UI:
WSDL Message
to WSDL Part
A message element in a WSDL document can

define a number of parts. If this the case, when
loaded into WSRR the messageParts relationship
on the WSDLMessage object will contain references to
the WSDLPart objects that were created when the
from the WSDLMessage object to the relevant WSDLPart
objects.
impact analysis, all of the WSDLPart objects that are
referenced by the messageParts relationship will be
SDO:
inputMessage
UI:
WSDL Operation
to WSDL Input
Message
SDO:
outputMessage
UI:
WSDL Operation
to WSDL Output
Message
SDO:
faults
UI:
WSDL Operation
to WSDL Fault
Message
Inbound

relationships from WSDLOperation objects to
Inbound

Inbound

233
inputMessage
outputMessage
faults
WSDL
Operation
WSDL
Message
messageParts
WSDL
WSDL
Part
WSDL
Part
Part
Figure 5-39 Modelled relationships that can be traversed for WSDLMessages during impact analysis
WSDLPart relationships
analysis on WSDLPart objects are described in Table 5-18.
Table 5-18 Modelled relationships that can be traversed for WSDLParts during impact analysis
Relationship name
Dependency type
Description
SDO:
xsdType
Outbound
UI:
WSDL Part to
XSD Type
A part element in a WSDL document can specify its

XSD type. If this the case, when loaded into WSRR
the xsdType relationship on the WSDLPart object will
contain a reference to the XSDType object that was
created when the document was parsed. This
creates a dependency from the WSDLPart object to
the relevant XSDType object.
impact analysis, the XSDType object that is
referenced by the xsdType relationship will be
SDO:
xsdElement
UI:
WSDL Part to
XSD Element
Declaration
Outbound
A part element in a WSDL document can specify the

XSD element that defines its structure. If this the
case, when loaded into WSRR the xsdElement
relationship on the WSDLPart object will contain a
reference to the ElementDeclaration object that
was created when the document was parsed. This
creates a dependency from the WSDLPart object to
the relevant ElementDeclaration object.
impact analysis, the ElementDeclaration object that
is referenced by the xsdElement relationship will be
234
Relationship name
Dependency type
Description
SDO:
messageParts
Inbound
UI:
WSDL Message
to WSDL Part

relationship from WSDLMessage objects to WSDLPart
objects.
xsdType
WSDL
Message
messageParts
XSD
Type
WSDL
Part
xsdElement
Element
Declaration
Figure 5-40 Modelled relationships that can be traversed for WSDLParts during impact
analysis
WSDLBinding relationships
analysis on WSDLBinding objects are described in Table 5-19 on page 236.
235
Table 5-19 Modelled relationships that can be traversed for WSDLBindings during impact analysis
Relationship name
Dependency type
Description
SDO:
portType
Outbound
UI:
WSDL Binding to
WSDL Port Type
A binding element in a WSDL document must

specify the portType that it binds using the type
attribute. When the WSDL document is loaded into
WSRR the portType relationship on the WSDLBinding
object will contain a reference to the WSDLPortType
object that was created when the document was
parsed. This creates a dependency from the
WSDLBinding object to the relevant WSDLPortType
object.
impact analysis, the WSDLPortType object that is
referenced by the portType relationship will be
SDO:
SOAPBinding
UI:
WSDL Binding to
SOAP Binding
Outbound
A binding element in a WSDL document can

specify that it uses the SOAP binding by specifying
a soap:binding element. If this is the case, when
the WSDL document is loaded into WSRR the
SOAPBinding relationship on the WSDLBinding
object will contain a reference to the SOAPBinding
object that was created when the document was
parsed. This creates a dependency from the
WSDLBinding object to the relevant SOAPBinding
object.
impact analysis, the SOAPBinding object that is
referenced by the SOAPBinding relationship will be
SDO:
binding
UI:
WSDL Port to
WSDL Binding
236
Inbound

relationship from WSDLPort objects to WSDLBinding
objects.
SOAPBinding
portType
WSDL
Port
Type
SOAP
Binding
WSDL
Binding
binding
WSDL
Port
Figure 5-41 Modelled relationships that can be traversed for WSDLBindings during
impact analysis
SOAPBinding relationships
analysis on SOAPBinding objects are described in Table 5-20.
Table 5-20 Modelled relationships that can be traversed for SOAPBindings during impact analysis
Relationship name
Dependency type
Description
SDO:
SOAPBinding
Inbound
UI:
WSDL Binding to
SOAP Binding

relationship from WSDLBinding objects to
SOAPBinding objects.
237
WSDL
Binding
SOAPBinding
SOAP
Binding
Figure 5-42 Modelled relationships that can be traversed for SOAPBindings during
impact analysis
WSDLService relationships
analysis on WSDLService objects are described in Table 5-21.
Table 5-21 Modelled relationships that can be traversed for WSDLServices during impact analysis
Relationship name
Dependency type
Description
SDO:
ports
Outbound
UI:
WSDL Service to
WSDL Port
A service element in a WSDL document can group

a set of related ports together. If this is the case,
when the WSDL document is loaded into WSRR the
ports relationship on the WSDLService object will
contain references to the WSDLPort object that was
creates a dependency from the WSDLService object
to the relevant WSDLPort objects.
impact analysis, the WSDLPort object that is
referenced by the ports relationship will be included
in the returned list.
238
WSDL
Service
WSDL
WSDL
Port
WSDL
Port
Port
ports
Figure 5-43 Modelled relationships that can be traversed for WSDLServices during
impact analysis
WSDLPort relationships
analysis on WSDLPort objects are described in Table 5-22.
Table 5-22 Modelled relationships that can be traversed for WSDLPorts during impact analysis
Relationship name
Dependency type
Description
SDO:
SOAPAddress
Outbound
UI:
WSDL Port to
SOAP Address
A port element in a WSDL document that is using

the SOAP binding must specify exactly one address.
When the WSDL document is loaded into WSRR the
SOAPAddress relationship on the WSDLPort object
will contain a reference to the SOAPAddress object
that was created when the document was parsed.
This creates a dependency from the WSDLPort object
to the relevant SOAPAddress object.
impact analysis, the SOAPAddress object that is
referenced by the SOAPAddress relationship will be
239
Relationship name
Dependency type
Description
SDO:
binding
Outbound
UI:
WSDL Port to
WSDL Binding
A port element in a WSDL document must specify

the binding that it defines an endpoint for by using
the binding attribute. When the WSDL document is
loaded into WSRR the binding relationship on the
WSDLPort object will contain a reference to the
WSDLBinding object that was created when the
from the WSDLPort object to the relevant WSDLBinding
object.
impact analysis, the WSDLBinding object that is
referenced by the binding relationship will be
SDO:
ports
Inbound
UI:
WSDL Service to
WSDL Port

relationship from WSDLService objects to WSDLPort
objects.
SOAPAddress
WSDL
Service
ports
SOAP
Address
WSDL
Port
binding
WSDL
Binding
Figure 5-44 Modelled relationships that can be traversed for WSDLPorts during impact
analysis
240
SOAPAddress relationships
analysis on SOAPAddress objects are described in Table 5-23.
Table 5-23 Modelled relationships that can be traversed for SOAPAddresses during impact analysis
Relationship name
Dependency type
Description
SDO:
SOAPAddress
Inbound
UI:
WSDL Port to
SOAP Address

relationship from WSDLPort objects to SOAPAddress
objects.
WSDL
Port
SOAPAddress
SOAP
Address
Figure 5-45 Modelled relationships that can be traversed for SOAPAddresses during
impact analysis
ElementDeclaration relationships
analysis on ElementDeclaration objects are described in Table 5-24.
Table 5-24 Modelled relationships that can be traversed for ElementDeclarations during impact analysis
Relationship name
Dependency type
Description
SDO:
xsdElement
Inbound
UI:
WSDL Part to
XSD Element
Declaration

relationship from WSDLPart objects to
ElementDeclaration objects.
241
WSDL
Part
xsdElement
Element
Declaration
Figure 5-46 Modelled relationships that can be traversed for ElementDeclarations during
impact analysis
ComplexTypeDefinition relationships
analysis on ComplexTypeDefinition objects are described in Table 5-24 on
page 241.
Table 5-25 Modelled relationships that can be traversed for ComplexTypeDefinitions during impact analysis
Relationship name
Dependency type
Description
SDO:
localAttributes
Outbound
UI:
XSD complex
type reference to
a local attribute
An XSD complex type definition within an XSD

document or a WSDL document can define a
number of attribute elements. If this the case, when
the relevant document is loaded into WSRR the
localAttributes relationship on the
ComplexTypeDefinition object will contain a
reference to the LocalAttribute objects that were
creates a dependency from the
ComplexTypeDefinition object to the relevant
LocalAttribute object.
impact analysis, the LocalAttribute objects that are
referenced by the localAttributes relationship will be
SDO:
template
UI:
Non-derived entity
reference to its
template
Inbound

relationship from OriginalObject objects to
ComplexTypeDefinition objects.
These relationships are shown in Figure 5-47 on page 243.
242
Original
Object
template
Complex
Type
Definition
localAttributes
Local
Attribute
Figure 5-47 Modelled relationships that can be traversed for ComplexTypeDefinitions

during impact analysis
5.5.3 Specifying user defined dependency relationships

User defined relationships allow you to associate a source object to zero or more
target objects. The source and target objects can be of any physical document
object, derived object or GenericObject type. Any given source object is able to
contain many user defined relationships and the name of each user defined
relationship is defined when you create the relationship (with the restriction that
they must be unique within the scope of a source object).
This brief explanation of user defined relationships describes a simple, but
extremely flexible, feature of WSRR. However, the flexibility that user defined
relationships provide makes it difficult to use them when performing impact
analysis. Since user defined relationships are able to transcend all physical
document object, derived object and GenericObject types, the results that are
produced when they are used to perform impact analysis are not as predictable
as when using modelled relationships alone. This is exacerbated by the fact that,
without extensive knowledge of the objects in your object graph, it is not possible
to anticipate whether a user defined relationship constitutes an inbound or
outbound dependency on an object.
The list of user defined relationships that should be traversed when performing
impact analysis is specified using the userDefinedRelationships parameter on
the getOutboundDependencies() or getInboundDependencies() method on the
governance API. This parameter must contain the list of user defined relationship
names. If you are using the Web user interface, you can specify the user defined
relationships to be traversed by selecting them in the Custom relationships list
box on the Impact Analysis tab, as shown Figure 5-48 on page 244.
243
Figure 5-48 Specifying user defined relationships
Note: When the impact analysis component encounters a specified user

defined relationship on an object in the object graph, it adds all of the target
objects of the relationship to the list of dependencies.
244
Part 3
Part
Planning and
installing WSRR
245
246
Chapter 6.
Possible topologies
This chapter describes some possible installation topologies, such as which
version of IBM WebSphere Application Server to use and where to locate the
databases.
6.1, WSRR requirements on page 248
6.2, Database topologies on page 250
6.3, WebSphere Application Server topologies on page 251
247
6.1 WSRR requirements

WebSphere Service Registry and Repository (WSRR) comes with an installer
that provides an out of the box solution for numerous platforms. WSRR can also
be installed in several different configurations.
Before installing WSRR, administrators should consider a number of factors that
will affect how they install WSRR and what configuration tasks they need to
undertake in order to make WSRR provide the desired capability in their Service
Oriented Architecture (SOA).
6.1.1 Supported platforms

WSRR V6.0.0 is supported on the following platforms:
AIX V5.3
Solaris 2.9 or 2.10 on SPARC processors
Linux on x86 processors (RHAS 4.0 and SLES 9)
HPUX 11.23 on PA-RISC
Windows Server 2003
z/OS V1.7
WSRR requires at least 2Gb of physical memory and at least 2Gb of spare disk
space to install.
More detailed requirements on the supported operating systems and hardware
requirements can be found on the WSRR support Web site:
http://www.ibm.com/software/integration/wsrr/sysreqs/index.html
6.1.2 Supported databases

DB2 Universal Database Enterprise Server Edition V8.2 and Fix Pack 5 (or later
Fix Pack) is supported on all of the platforms listed in 6.1.1, Supported
platforms on page 248. DB2 Universal Database Enterprise Server Edition V8.2
Fix Pack 5 is supplied with WSRR.
In addition WSRR V6.0.0 supports Oracle 10g Enterprise Edition Release
10.2.0.1.0 on Solaris on SPARC.
248
6.1.3 Prerequisite software

WSRR requires both a database (supported ones are listed in 6.1.2, Supported
databases on page 248) and a WebSphere Application Server. Therefore
WSRR also requires WebSphere Application Server V6.0.2 and Fix Pack 11 (or
later fix pack) to be installed.
As of WSRR V6.0.0 Fix Pack 1 WSRR supports both WebSphere Application
Server Base edition and WebSphere Application Server Network Deployment
edition. Regardless of which edition is used the version must be V6.0.2 Fix Pack
11 (or later fix pack).
WebSphere base edition V6.0.2 Fix Pack 11 is supplied with WSRR.
6.1.4 Topology selection criteria

While a variety of factors come into play when considering the appropriate
topology for a WebSphere deployment, the primary factors to plan for typically
include:
Security
Performance
Throughput
Scalability
Availability
Maintainability
Session state
For detailed information about topologies, their advantages and disadvantages,

required software, as well as topology selection criteria, refer to the redbook
WebSphere Application Server V6 Planning and Design WebSphere Handbook
Series, SG24-6446.
Note: For each of the Network Deployment topologies, a decision needs to be
made regarding the placement of the Deployment Manager and master cell
repository. The Deployment Manager can be located either on a dedicated
machine, or on the same machine as one of its nodes. It is, however,
considered a best practice to place the Deployment Manager on a separate
machine. For more information about possible configurations, refer to 9.3,
Cell topologies in the redbook WebSphere Application Server V6 Planning
and Design WebSphere Handbook Series, SG24-6446.
Chapter 6. Possible topologies
249
6.2 Database topologies

Regardless of which database server you are using, DB2 or Oracle (Oracle is
only supported on Solaris in WSRR V6.0.0) you can choose to have the
database physically located on the same machine as the WebSphere Application
Server or on a different machine.
These two topologies are now explained.
6.2.1 Local database

This is when the database server and the WebSphere server are both located on
the same physical machine. This is illustrated in Figure 6-1.
Obviously the machine must be able to handle both the database server and
WebSphere server running at the same time. This would normally require a more
powerful machine than would be necessary were the database remote.
Physical Server
Database
Server
WSRR
xmeta1
WebSphere
Application
Server
SOR
Figure 6-1 Local database topology
6.2.2 Remote database

It is also possible to install WSRR in a configuration with the database server and
WebSphere server are on different physical machines.
This configuration is illustrated in Figure 6-2 on page 251 and the installation
process is described in 7.7, Installing WSRR with a remote database on
page 275.
250
This configuration requires multiple machines but each machine does not need
to be as powerful as would be necessary were the database local. The network
connection between the two machines should be as fast as possible and involve
as few network switches, hubs, and so on as possible. An ideal setup would have
both machines located in the same rack and on the same network subnet.
Physical Server 1
Physical Server 2
Database
Server
WSRR
xmeta1
WebSphere
Application
Server
SOR
Figure 6-2 Remote database topology
6.3 WebSphere Application Server topologies

This section introduces the different WebSphere configurations that are possible
to use with WSRR. Refer to the Redpaper WebSphere Application Server V6
Technical Overview, REDP-3918, which is about the WebSphere Application
Server architecture and components. For more information about WebSphere
performance, refer to the redbook WebSphere Application Server V6 Scalability
and Performance Handbook, SG24-6392.
6.3.1 Standalone server

Base, and Network Deployment both support a single stand-alone server
environment. With a stand-alone configuration, each application server acts as a
unique entity. An application server runs one or more J2EE applications and
provides the services required to run those applications.
Multiple stand-alone application servers can exist on a machine, either through
independent installations of the WebSphere Application Server code or through
multiple configuration profiles within one installation. However, WebSphere
Chapter 6. Possible topologies
251
Application Server does not provide for common management or administration

for multiple application servers.
6.3.2 Distributed server

With Network Deployment, you can build a distributed server configuration, which
enables central administration and workload management. In this environment,
you integrate one or more application servers into a cell that is managed by a
deployment manager. The application servers can reside on the same machine
as the deployment manager or on multiple separate machines.
Administration and management is handled centrally from the administration
interfaces via the deployment manager. With this configuration, you can create
multiple application servers to run unique sets of applications and then manage
those applications from a central location.
As of V6.0.0 Fix Pack 1 WSRR supports being installed into a federated server
using WebSphere Application Server Network Deployment. However, WSRR
V6.0.0 does not yet support any form of clustering, workload management or
failover using Network Deployment.
The main reason for using Network Deployment with WSRR instead of the
supplied Base edition would be to harmonize versions of WebSphere with
existing WebSphere servers or to provide the ability to use a separate
deployment manager.
252
Chapter 7.
Installing and deploying

This chapter describes how to install and deploy WebSphere Service Registry
and Repository and its associated prerequisite software.
In this chapter, the following topics are described:
7.1, Install WebSphere Application Server V6.0 on page 254
7.2, Install WebSphere Application Server V6.0 refresh pack 2 (V6.0.2) on
page 254
7.3, Install WebSphere Application Server V6.0.2 fix pack 11 (V6.0.2.11) on
page 255
7.4, Install DB2 Universal Database Enterprise Server Edition on page 256
7.5, Install WebSphere Service Registry and Repository on page 258
7.6, Deploy WebSphere Service Registry and Repository on page 265
7.7, Installing WSRR with a remote database on page 275
7.8, Installing WSRR using the WebSphere Application Server Network
Deployment on page 277
7.9, Upgrading WSRR to a new fixpack on page 279
7.10, Installation troubleshooting on page 280
253
7.1 Install WebSphere Application Server V6.0

As discussed in Chapter 6, Possible topologies on page 247 WSRR supports
both WebSphere Application Server and WebSphere Application Server Network
Deployment. Whichever edition is used it must be Version 6.0.2.x (where, x is 11
or greater).
For the purposes of this book we will assume we are using WebSphere
Application Server base edition.
1. Insert the WebSphere Application Server CD.
2. If the launchpad did not autorun then double-click launchpad.bat.
3. Select WebSphere Application Server Installation from the launchpad
4. Select Launch the installation wizard for the WebSphere Application Server
5. Click Next on the welcome window
6. Select the I accept option and then click Next on the license panel
7. Click Next on the system prerequisite check panel
8. Enter the directory to install the software to (for example, C:\Program
Files\IBM\WebSphere\AppServer) and then click Next
9. Click Next on the feature selection panel
10.Click Next on the Installation summary panel
11.Deselect the Launch the First steps console check box and click Finish on
the Installation Complete panel.
7.2 Install WebSphere Application Server V6.0 refresh

pack 2 (V6.0.2)
We now need to upgrade the installed version of WebSphere to be V6.0.2. To do
this, perform the following steps:
1. Insert the WebSphere Application Server fixpack CD 1
2. Open the 6.0-WS-WAS-WinX32-RP0000002 directory
3. Copy the updateinstaller directory to your WebSphere Application Server
directory (for example, C:\Program Files\IBM\WebSphere\AppServer)
4. Double-click the update.exe program in your freshly copied directory (e.g.
C:\Program Files\IBM\WebSphere\AppServer\updateinstaller\update.exe)
5. Click Next on the welcome panel
254
6. Check the path to your WebSphere installation is correct and then click Next.
7. Ensure Install maintenance package. is selected and click Next.
8. Ensure the path to the package to install ends in
6.0-WS-WAS-WinX32-RP0000002.pak and then click Next.
9. The refresh pack update needs to install a new Java runtime, however the
update installer is running using the current one, so it needs to copy the new
JDK to a temporary directory and then relaunch. After reading the
explanation of these steps in the panel click Next.
10.Once the copy has completed, click Relaunch.
11.When the wizard restarts ensure Install maintenance package is selected
and click Next.
12.The path to the package should not have changed and so click Next.
13.The wizard will now detail what it is about to do, namely to install RP6020 WebSphere Application Server 6.0.2.0. Check these details are correct and
then click Next.
14.Once it is complete, click Finish.
7.3 Install WebSphere Application Server V6.0.2 fix pack

11 (V6.0.2.11)
We now need to upgrade the installed version of WebSphere to V6.0.2.11. To do
this, perform the following steps:
1. Delete the <WAS_HOME>\updateinstaller directory (e.g. C:\Program
Files\IBM\WebSphere\AppServer\updateinstaller)
2. Insert the WebSphere Application Server fixpack CD 2
3. Open the 6.0.2-WS-WAS-WinX32-FP00000011 directory
4. Copy the updateinstaller directory to your WebSphere Application Server
directory (e.g. C:\Program Files\IBM\WebSphere\AppServer)
5. Double-click the update.exe program in your freshly copied directory (e.g.
6. Click Next on the welcome panel
7. Check the path to your WebSphere installation is correct and then click Next.
8. Ensure Install maintenance package. is selected and click Next.
9. Ensure the path to the package to install ends in
6.0.2-WS-WAS-WinX32-FP00000011.pak and then click Next.
Chapter 7. Installing and deploying
255
10.The wizard will now detail what it is about to do, namely to install FP60211 WebSphere Application Server 6.0.2.11. Check these details are correct and
then click Next.
11.Once it is complete click Finish.
12.Delete the <WAS_HOME>\updateinstaller directory (e.g. C:\Program
Files\IBM\WebSphere\AppServer\updateinstaller)
13.Open the 6.0.2-WS-WASJavaSDK-WinX32-FP00000011 directory on the CD
14.Copy the updateinstaller directory to your WebSphere Application Server
directory (e.g. C:\Program Files\IBM\WebSphere\AppServer)
15.Double-click the update.exe program in your freshly copied directory (e.g.
16.Click Next on the welcome panel
17.Check the path to your WebSphere installation is correct and then click Next.
18.Ensure Install maintenance package. is selected and click Next.
19.Ensure the path to the package to install ends in
6.0.2-WS-WASJavaSDK-WinX32-FP00000011.pak and then click Next.
20.The fix pack update needs to install a new Java runtime, however the update
installer is running using the current one, so it needs to copy the new JDK to a
temporary directory and then relaunch. After reading the explanation of these
steps in the panel click Next.
21.Once the copy has completed click Relaunch.
22.When the wizard restarts ensure Install maintenance package is selected
and click Next.
23.The path to the package should not have changed and so click Next.
24.The wizard will now detail what it is about to do, namely to install
WASJAVASDKFP60211 - Software Developer Kit V6.0.2.11. Check these
details are correct and then click Next.
25.Once it is complete click Finish.
7.4 Install DB2 Universal Database Enterprise Server

Edition
It is possible to install direct from a Windows DB2 fixpack without needing to
install the original GA product first. This is not possible on other platforms,
however for the purposes of this IBM Redbook we are only using Windows.
256
Follow these steps to install DB2 Universal Database Enterprise Server Edition
8.2.5:
1. Insert the DB2 Universal Database Enterprise Server Edition 8.2 fixpack 5
CD.
2. Run setup.exe
3. Select Install Product from the launchpad
4. Click Next after confirming that you want to install DB2 Universal Database
Enterprise Server Edition.
5. The DB2 install wizard will now start. Click Next on the welcome window.
6. Select the I accept option and then click Next on the license panel
7. Select Typical installation type and leave the additional function check boxes
unselected, then click Next.
8. Ensure the Install DB2 Enterprise Server Edition on this computer box is
checked and the Save your settings in a response file box is unchecked.
Click Next.
9. Select the option Single-partition database environment and click Next
10.Select the directory to install DB2 in to, e.g. C:\Program Files\IBM\SQLLIB
and then click Next.
11.Enter the following values for the DB2 Admin user details:
Domain: leave this blank if you do not have a domain
User name: Change this value if you want to use something other than
db2admin
Password: Enter a password for the userid
Confirm password: Enter the password again
Ensure the Use the same user name and password for the remaining DB2
services box is checked and then click Next.
12.Leave the Administration contact list as Local and leave Enable notification
deselected and then click Next.
13.Click OK in the notification warning window that appears.
14.Click Next in the Configuring DB2 instances panel
15.Check the Do not prepare the DB2 tools catalog option and click Next.
16.When asked to specify a contact for health monitoring select Defer the task
until after installation is complete and click Next.
17.Check the settings for this install are correct and then click Install.
18.Once the install has completed click Finish.
257
19.Click Exit First Steps when the First Steps Launchpad appears.
7.5 Install WebSphere Service Registry and Repository

It is possible to install direct from WSRR fixpacks without needing to install the
original GA image. Therefore these instructions are going to assume you are
installing directly from the WSRR fixpack1 image. The instructions for later
fixpacks should be similar.
Note: There was a manufacturing refresh performed after fixpack 1 was
completed, so if you obtained your WSRR install images after January 2007,
they should already be at the fixpack1 level. Consult the readme.html file
supplied with your WSRR installer to check which version you have.
1. From the directory Fixpack1 was downloaded to, run setup.exe
2. Select an installation language and click OK as in Figure 7-1.
Figure 7-1 WSRR Installation Language selection
258
3. Click Next on the welcome panel as in Figure 7-2.
Figure 7-2 WSRR Installation Welcome panel
259
4. Select the I accept option and then click Next on the license panel as in
Figure 7-3
Figure 7-3 WSRR Installation License panel
260
5. Select the directory to install to, e.g. C:\Program

Files\IBM\WebSphereServiceRegistry and then click Next as in Figure 7-4.
Figure 7-4 WSRR Installation Destination panel
261
6. Confirm the install settings are correct and then click Install as in Figure 7-5.
Figure 7-5 WSRR Installation Pre-install summary panel
262
7. The installer will now install the files as in Figure 7-6. Once complete it will tell
you that you need to run the deployment scripts to install the enterprise
application into WebSphere and to create the databases (See Figure 7-7 on
page 264. We will do that in the next section, 7.6, Deploy WebSphere
Service Registry and Repository on page 265.). Click Next.
Figure 7-6 WSRR Installation progress panel
263
Figure 7-7 WSRR Installation deployment warning panel
8. Click Finish as in Figure 7-8.
Figure 7-8 WSRR Installation completion panel
264
7.6 Deploy WebSphere Service Registry and Repository

In order to use WSRR it must be deployed to WebSphere. This will also create
the necessary databases.
The deployment process will carry out the following operations:
Create and populate the xmeta1 database

Create and populate the SOR database
Create JDBC Providers (XA and non-XA) in WebSphere
Create an authentication alias for the database userID and password
Create a JDBC datasource for the xmeta1 database
Set up a WAS variable pointing at a WSRR subdirectory
Create a shared library
Add a namespace binding
Create the xmeta SI Bus and JMS resources
Create a JDBC datasource for the SOR database
Create the WSRR SI bus and JMS resources
Install the ServiceRegistry.ear application
Change the default authorization provider
Configure the startup bean to start on startup
Preload the repository with configuration files
Setup default roles for fine grained access control
Note: The information in this section is appropriate for WebSphere Service
Registry and Repository V6.0.0.1 (fixpack 1). Other fixpack versions may differ
slightly.
As noted previously there was a manufacturing refresh performed after fixpack
1 was completed, so if you obtained your WSRR install images after January
2007, they should already be at the fixpack1 level. Consult the readme.html
file supplied with your WSRR installer to check which version you have.
To do so, perform the following steps:

1. Navigate to the WSRR installation directory (e.g. C:\Program
Files\IBM\WebSphereServiceRegistry)
2. Navigate to the install subdirectory
3. Open setenv.bat in notepad and edit the values in the file to match your
current environment. Typically the following variables might need to be edited:
WebSphere Application Server install location
DB2 install location
WebSphere SOAP and Bootstrap port numbers
265
WebSphere server name

WebSphere profile name
Database user name
But there are other variables in the file that you may need to edit too.
All possible parameters are described in Table 7-1. Note that the values for
these can be set by editing setenv.bat or by specifying them on the
command line. As can be seen in the usage statement for installall.bat
shown in Example 7-1.
Example 7-1 Installall.bat usage statement
Usage: installall.bat
-was-password was-password
-db-password db-password
[-was-user was-user]
[-administrator-user administrator-user-name]
[-administrator-group administrator-group]
[-user-user user-role-user-name]
[-user-group user-role-group]
[-was-home C:\IBM\WebSphere\AppServer]
[-was-profile default]
[-was-server server1]
[-soap-port 8880]
[-bootstrap-port 2809]
[-db-home C:\IBM\SQLLIB]
[-db-type db2_8]
[-db-user db-user]
[-db-port 50000]
[-db-hostname localhost]
[-db-tsdir C:\DB2TS]
[-skip-dbcreate true or false]
Table 7-1 WSRR Deployment parameters
266
Parameter
Description
DB_TYPE
The database type in use, one of the following two

values: db2_8 or oracle10g (Note: oracle10g is only
supported on Solaris)
DB_USER
For DB2 this should be set to the user ID to use to

access the databases. On Windows if this user does not
exist it will be created automatically, however on UNIX
the user ID must already exist, for example, xmeta.
On Oracle the db-user should be set to "system"
Parameter
Description
DB_HOME
The path to the Database software install directory, for

example, C:\IBM\SQLLIB or /opt/IBM/db2/8.1
DB_HOSTNAME
The name of the server the database is running on, for

example, localhost
DB_PORT
The database instance port number, for example, 50000.

On UNIX, if in doubt check /etc/services and look for
the db2c_<instance-name> entry.
DB2TSDIR
The directory path for the DB2 tablespaces, for example,

C:\DB2TS
SKIPDBCREATE
Set this option to true if you have already manually run

the createdb_db2 or createdb_ora script to create the
database table structures. The installer will then assume
the databases exist and will perform the remainder of
the install steps. This allows a database administrator to
create the database manually, should they want to, as
explained in 7.7, Installing WSRR with a remote
database on page 275.
WAS_HOME
The path to the WebSphere install directory, for

example, C:\IBM\WebSphere\AppServer
WAS_PROFILE
The name of the WebSphere profile, for example,

default
WASSRVR
The name of the WebSphere server, for example,

server1
WASPORT
The port number for the SOAP Connector, for example,

8880
BOOTSTRAPPORT
The port number for the bootstrap port, for example,

2809
WAS_ADMIN_USER
The WebSphere Administrator ID, or if WebSphere

security is turned off then a local system Administrator
ADMINISTRATOR_USER
The user you want added to the administrator role. This

can also be set to NONE or ALL_AUTHENTICATED.
ADMINISTRATOR_GROUP
The group you want added to the administrator role.
USER_USER
The user you want added to the user role. This can also
be set to NONE or ALL_AUTHENTICATED.
USER_GROUP
The group you want added to the user role.
267
Parameter
Description
LOGDIR
The directory to put the install log files in. Normally set
to be %SR_INSTALL% which will equate to be the
<WSRR_HOME>\install directory.
Table 7-2 shows the extra parameters that can be found in setenv.sh when
installing on UNIX but that are not used on Windows.
Table 7-2 UNIX only extra WSRR deployment parameters
Parameter
Description
DB_INSTID
The user ID the database instance runs as, for example,

db2admin (DB2 only)
DB2INST
The DB2 instance name, for example, db2inst1 (DB2

only)
ORACLEPATH
The path to the Oracle software install directory. For

example /home/oracle/product/10.2.0/Db_1 (Only
used on Oracle on Solaris)
ORAPORT
The port in use by Oracle. (Only used on Oracle on

Solaris)
ORAUSER
The oracle administration ID, for example oracle. (Only

used on Oracle on Solaris)
If any values in your environment file are incorrect then it is likely the deployment
will fail.
For more information about using the deployment scripts, consult the WSRR
Information Center:
c/twsr_installn15.html
Note: A common source of problems with the deployment stage is errors in
the parameters specified in setenv. Ensure all parameters used are
appropriate for your environment. Take extra care over the WASPORT and
BOOTSTRAPPORT values as there is no validation for these values.
Example 7-2 on page 269 shows the environment file used in our deployment.
268
Note: Even if you are not using security in WebSphere Application Server you
must still provide values for the WAS_ADMIN_USER variable in setenv.bat
and the was-password parameter on the installall.bat command line. It is
easiest to just provide the username and password for a local system
administrator.
If WebSphere security is off the install does seem to proceed correctly even if
the username and password specified are not actually valid, values just have
to be provided for them.
Example 7-2 WSRR deployment environment file
@rem begin_generated_IBM_copyright_prolog
@rem
@rem
@rem
@rem
@rem
@rem
Licensed Materials - Property of IBM

5724-N72
(c) Copyright IBM Corp. 2006 All Rights Reserved
US Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
@rem end_generated_IBM_copyright_prolog
@echo off
set SR_INSTALL=%~dps0
set XMETA_HOME=%~dps0..\xmeta
REM -------- DB Installation Information -------REM Database type
REM possible values: db2_8
if "%DB_TYPE%" == "" set DB_TYPE=db2_8
REM Database username
REM Please do not put quotes around the user ID
if "" == "%DB_USER%" set DB_USER=xmeta
REM The database password is not stored in this file for security reasons
REM Database install directory
REM Please do not put quotes around the directory path
if "%DB_HOME%" == "" set DB_HOME=c:\Program Files\IBM\SQLLIB
REM DB hostname
REM if you set this to anything other than localhost you must create the database
REM manually first and then specify "-skip-dbcreate true"
269
if "%DB_HOSTNAME%" == "" set DB_HOSTNAME=localhost

REM DB PORT
if "%DB_PORT%" == "" set DB_PORT=50000
REM DB2 Tablespace Directory
if "%DB2TSDIR%" == "" set DB2TSDIR=c:\DB2
REM Skip Database creation
REM Set this to true if you have created the database manually already.
REM This will then assume the databases exist and have all tables and
REM tablespaces correctly configured.
if "%SKIPDBCREATE%" == "" set SKIPDBCREATE=false
REM -------- WAS Installation Information -------REM WAS Base Installation Directory
REM Please do not put quotes around the directory path
if "%WAS_HOME%" == "" set WAS_HOME=c:\Program Files\IBM\WebSphere\AppServer
REM WAS Profile Name
if "%WAS_PROFILE%" == "" set WAS_PROFILE=default
REM WAS Server name
if "%WASSRVR%" == "" set WASSRVR=server1
REM WAS SOAP CONNECTOR ADDRESS PORT
if "%WASPORT%" == "" set WASPORT=8880
REM WAS BOOTSTRAP CONNECTOR ADDRESS PORT
if "%BOOTSTRAPPORT%" == "" set BOOTSTRAPPORT=2809
REM WAS Administration User ID
REM Please do not put quotes around the user ID
if "" == "%WAS_ADMIN_USER%" set WAS_ADMIN_USER=Administrator
REM The WAS admin password is not stored in this file for security reasons
REM
REM
REM
REM
REM
REM
REM
REM
REM
270
------------------------------------------------------------------------ Users and groups that should be granted each of the roles
-- defined by the service registry.
-- Each xxx_USER variable can be set to one of:
-- {NONE, EVERYONE, ALL_AUTHENTICATED, <any-valid-user-name>}
-- if using LDAP, the user name must be the short version of the user name
-- Each xxx_GROUP variable can be set to the name of a group or nothing.
-- if using LDAP, the group name must be the fully qualified group name
--
REM -- (where xxx is either ADMINISTRATOR or USER)

REM ----------------------------------------------------------------------REM Please do not put quotes around the values
if "" == "%ADMINISTRATOR_USER%" set ADMINISTRATOR_USER=ALL_AUTHENTICATED
if "" == "%USER_USER%" set USER_USER=ALL_AUTHENTICATED
if "" == "%ADMINISTRATOR_GROUP%" set ADMINISTRATOR_GROUP=NONE
if "" == "%USER_GROUP%" set USER_GROUP=NONE
REM
REM
set
set
REM
------------------------------------------------------------------------ Setup the ANT PATHS so we can use ant from WAS for installation -SR_ANTHOME=%XMETA_HOME%\lib
SR_ANTCP=%SR_ANTHOME%\ant.jar;%SR_ANTHOME%\ant-launcher.jar
-----------------------------------------------------------------------
REM The directory the install logs will be saved to.

set LOGDIR=%SR_INSTALL%
REM
REM
REM
REM
REM
------------------------------------------------ Shouldn't need to edit below this

----- Section of the file, but check just in ----- case you do...
------------------------------------------------
if not exist "%WAS_HOME%\bin\wasprofile.bat" goto :nowas

for /F "usebackq delims=" %%f in (`cmd /c "%WAS_HOME%\bin\wasprofile" -getPath
-profileName %WAS_PROFILE%`) do set WASPROFILEDIR=%%f
:nowas
REM JAVA_HOME. You shouldn't need to edit this one.
set JAVA_HOME=%WAS_HOME%\java
REM Update the PATH. You shouldn't need to edit this one either.
set
PATH=%JAVA_HOME%\jre\bin;%JAVA_HOME%\bin;%PATH%;%WAS_HOME%\bin;%DB_HOME%\java\jdk\jre\bin
goto ENDSCRIPT
:ENDERROR
exit /B 1
:ENDSCRIPT
exit /B 0
Once you have finished editing setenv.bat save and close the file.
271
4. Open a command prompt and cd to the install sub directory as shown in

Figure 7-9.
Figure 7-9 WSRR Deployment - change directory
5. Run installall.bat as in Example 7-3.

Example 7-3 WSRR Deployment command
installall.bat -was-password passw0rd -db-password passw0rd

This is illustrated in Figure 7-10. Replace passw0rd with the appropriate
passwords for your environment.
Figure 7-10 WSRR Deployment - install command
272
6. You should then get output similar to that shown in Figure 7-11.
Figure 7-11 WSRR Deployment - command output
If for any reason the deployment failed then you can look in the two log files
mentioned in the output, for possible information about why it failed.
Otherwise please contact your IBM Support representative.
7. WSRR should now be deployed and you should be able to verify the
installation was successful by pointing a Web browser at the WSRR user
interface:
http://<system-host-name>:9080/ServiceRegistry
Or, if you have WebSphere security turned on, point to:
https://<system-host-name>:9443/ServiceRegistry
You should see something similar to that shown in Figure 7-12 on page 274.
Note: The port number in the above URLs might be different for your
environment.
273
Figure 7-12 WSRR User Interface
Installation of WebSphere Service Registry and Repository is now complete.
7.6.1 Security
In most installations it is desirable to limit access to WSRR. This is done by
turning on WebSphere security. It is not within the scope of this book to cover
how to do that, but it is documented in the WebSphere Information Center:
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/topic/com.ibm.
websphere.base.doc/info/aes/ae/tsec_csec.html
For the purposes of this book we have turned on WebSphere Global Security
and we are using local operating system authentication. Therefore we have
created a local user on the WSRR installation machine called wasadmin. We did
not turn on Java2 Security because it is not necessary for this book. See the
274
following Web page in the WSRR Information Center for more information about
using WSRR with Java2 Security:
c/cwsr_planning_install16.html
7.7 Installing WSRR with a remote database

Our example install above is now complete, but there are several possible install
topologies as explained in Chapter 6, Possible topologies on page 247, and
one of those makes use of a separate remote database server instead of using
the same machine for both WebSphere and DB2 (or Oracle). This section will
detail how to do that should you want to do so.
1. Install WebSphere and its associated fixpacks on the WebSphere server as
explained in 7.1, Install WebSphere Application Server V6.0 on page 254 to
7.3, Install WebSphere Application Server V6.0.2 fix pack 11 (V6.0.2.11) on
page 255.
2. Install WSRR on the WebSphere server as outlined in 7.5, Install
WebSphere Service Registry and Repository on page 258.
3. Install DB2 on the database server as outlined in 7.4, Install DB2 Universal
Database Enterprise Server Edition on page 256.
4. Install WSRR on the database server as outlined in 7.5, Install WebSphere
Service Registry and Repository on page 258.
5. On the database server navigate to the install subdirectory of your WSRR
install root. Open setenv.bat in notepad.
6. Make sure the DB_USER, DB_HOME, DB_PORT and DB2TSDIR variables
are all set correctly. DB_HOSTNAME can be set to localhost here, although
it will need setting correctly when we come to run the WebSphere scripts on
the WebSphere server. The other settings in the file for WebSphere are not
important and will not be used by the create database script.
Note: It is normally easier if you create a user on both the database and
WebSphere servers with the same name and then use this user as the
DB_USER.
7. Open a command prompt and cd to the install/xmeta sub-directory as
shown in Example 7-4 on page 276.
275
Example 7-4 WSRR change directory command
cd C:\IBM\Program Files\WebSphereServiceRegistry\install\xmeta
8. Run createdb_db2.bat as in Example 7-5.
Example 7-5 WSRR Create database command
createdb_db2.bat -db-password passw0rd

Replace passw0rd with the appropriate password for your environment.
This should then create the xmeta1 and SOR databases and populate them
with the required tables, tablespaces and contents.
Note: This command will output several thousand lines of output so you
may want to redirect the output to a log file to be able to review it later and
check for possible errors:
createdb_db2.bat -db-password passw0rd > createdb.log 2>&1
9. On the WebSphere server navigate to the install sub-directory of your
WSRR install root. Open setenv.bat in notepad.
10.Make sure the DB_USER, DB_PORT, DB_HOSTNAME, WAS_HOME,
WAS_PROFILE, WASSRVR, WASPORT, BOOTSTRAPPORT,
WAS_ADMIN_USER variables are set correctly. The
ADMINISTRATOR_USER, ADMINISTRATOR_GROUP, USER_USER and
USER_GROUP variables should also be set here if needed. It is not
important to set the DB_HOME or DB2TSDIR variables since they are not
needed on the WebSphere server.
11.Set the SKIPDBCREATE variable to be true. This tells the deployment scripts
that we have already created the database separately and to not attempt
those steps.
12.Open a command prompt and cd to the install sub-directory as shown in
Example 7-6.
Example 7-6 WSRR change directory command
cd C:\IBM\Program Files\WebSphereServiceRegistry\install
13.Run installall.bat as in Example 7-7.
Example 7-7 WSRR installall command
installall.bat -was-password passw0rd -db-password passw0rd
276
It is still necessary to specify the database users password. Replace

passw0rd with the appropriate passwords for your environment.
This should then create the WebSphere resources and configure WebSphere
to connect to the remote database server and the databases we just created.
14.WSRR should now be deployed and you should be able to verify the
installation was successful by pointing a Web browser at the WSRR user
interface:
Or if you have WebSphere security turned on:
Note: The port number in the above URLs might be different for your
environment.
7.8 Installing WSRR using the WebSphere Application

Server Network Deployment
It is possible to install WSRR using WebSphere Application Server Network
Deployment instead of WebSphere Application Server base edition. WebSphere
should be installed in a similar way to that explained at the beginning of this
chapter with the exception of using the Network Deployment version of the
software and fixpacks.
Note: Even if using WebSphere Application Server Network Deployment,
WSRR V6.0.0.1 only supports Version 6.0.2.x where x is 11 or greater.
The DB2 installation will be identical to that outlined in 7.4, Install DB2 Universal
Database Enterprise Server Edition on page 256. The WSRR installation will
also be identical to that for WebSphere base edition, see 7.5, Install WebSphere
Service Registry and Repository on page 258.
If you are installing to a standalone server profile in WebSphere Application
Server Network Deployment then follow the instructions in 7.6, Deploy
WebSphere Service Registry and Repository on page 265. However since there
might be multiple profiles on the same machine take care that the WASPORT
and BOOTSTRAPPORT variables are correctly set in setenv.bat. Refer to the
277
WebSphere documentation for instructions on how to find what port numbers

your server is using if you are not sure.
If you want to install to a federated server then you will need to follow the steps
here:
1. Create a Deployment Manager profile inside WebSphere Application Server
Network Deployment if you do not already have one.
2. Start the deployment manager.
3. Create a custom profile.
4. Create an application server in the custom profile node you just created.
5. Deploy the WSRR application as outlined in 7.6, Deploy WebSphere Service
Registry and Repository on page 265 with the following important changes
when editing setenv.bat:
Set WAS_PROFILE to the name of the custom profile
e.g. WSRRNode
Set WASSRVR to the name of the server created in that profile
e.g. WSRRServer1
Set WASPORT to the SOAP_CONNECTOR_ADDRESS value of the
Deployment Manager
e.g. 8879
Set BOOTSTRAPPORT to the BOOTSTRAP_PORT value for the
application server specified in WASSRVR running in the WAS_PROFILE
specified.
e.g. 2811
Note: It is important to take care here as the two port values are
pointing at different servers, the SOAP port must point at the
deployment manager in order to run the wsadmin commands to create
the WebSphere resources. The BOOTSTRAPPORT value is that of the
application server profile itself as some of the utilities need to connect
to it directly rather than via the deployment manager.
6. WebSphere Service Registry and Repository should now be successfully
installed to your federated server. You should be able to verify the installation
was successful by pointing a Web browser at the WSRR user interface:
or if you have WebSphere security turned on:
278
The port numbers in these URLs will need to be substituted for those
appropriate to your environment.
7.9 Upgrading WSRR to a new fixpack

It is possible to install direct from the fixpack install image without needing to
have a previous version installed. However previous installations can also be
upgraded to the new level.
7.9.1 Upgrade from previous version

To upgrade to the latest fix pack, download the fix pack from the WebSphere
Service Registry and Repository support Web site:
http://www.ibm.com/software/integration/wsrr/support/index.html
1. Make a backup of your existing files, especially your setenv.bat/sh file as the
fixpack will overwrite it.
2. Run the InstallShield installer. Install the files over the top of the previous
version.
3. Edit the new setenv file and make sure the variables are set to the values they
were in the previous version. It is not possible to simply replace the new
setenv file with the old one as the new version could contain new variables
that will need setting.
4. Run the install/updatewsrr script as follows.
For Windows:
install/updatewsrr.bat was-password password db-password password
For UNIX:
install/updatewsrr.sh was-password password db-password password
That script will update the ServiceRegistry application in WebSphere with the
fixpack version.
7.9.2 Direct Installation

It is also possible to install direct from the fix pack without having a previous
version installed. To do this just download the fix pack, and then run the
InstallShield installer and deployment scripts as explained in 7.6, Deploy
WebSphere Service Registry and Repository on page 265.
279
7.10 Installation troubleshooting

Due to the deployment of WSRR involving several different products and
performing multiple operations it is possible that it may fail to run through to
completion.
This is normally due to a variable being incorrectly set in setenv.bat/sh so all the
values in that file should be thoroughly checked first.
The next thing to check is the levels of the software being used, If you are using
Windows then only Windows 2003 and Windows XP SP2 are supported. The
deployment scripts will fail to run correctly on Windows 2000 or XP SP1. See 6.1,
WSRR requirements on page 248 for more information about the supported
levels of software.
The deployment scripts produce two log files (installxmeta.log and
installsr.log) normally found in the install subdirectory of your WSRR
installation, for example:
C:\Program Files\IBM\WebSphereServiceRegistry\install
Check these files for any errors as they may give an indication of which part of
the deployment failed.
Some possible problems and their solutions have been documented in
TechNotes on the WSRR support site:
http://www.ibm.com/support/search.wss?tc=SSWLGF&rs=3163&dc=DB520&ran
k=8
If you cannot find the cause of the problem then contact IBM Support, details of
how to do so can be found on the WSRR Support Web site:
http://www.ibm.com/software/integration/wsrr/support/index.html
280
Chapter 8.
Administering WSRR
This chapter describes how to administer WebSphere Service Registry and
Repository and the various interfaces that can be used.
8.1, Administration overview on page 282
8.2, WSRR configurations on page 283
8.3, Security considerations on page 285
8.4, Administering WSRR using wsadmin on page 285
8.5, Administering WSRR using JMX on page 292
8.6, Administering WSRR using the CLI on page 299
8.7, Ontology administration on page 307
8.8, Access control administration on page 309
8.9, Import/Export on page 311
8.10, Environment promotion on page 319
8.11, Administration scripts (wsadmin) on page 321
281
8.1 Administration overview

Most of the administration of WebSphere Service Registry and Repository is
performed through its JMX interface. Each WSRR application registers an
MBean with an MBean identifier of ServiceRegistryRepository.
This MBean may be used by client applications to inspect and manage the
runtime configuration of a WSRR application. In order to manage the
configuration of WSRR, the ServiceRegistry application must be in the started
state.
The WSRR MBean operations can be invoked using standard JMX clients, such
as Java applications and wsadmin scripts. In addition, WSRR has a command
line interface which allows invocation of administration operations.
Some administration functions can also be performed through the WSRR Web
user interface, by users in the Administrator role. These functions are import and
export of entities and their metadata, and loading and removing ontology
systems.
8.1.1 Administrative scripting (wsadmin)

The WebSphere administrative (wsadmin) scripting program is a powerful,
non-graphical command interpreter environment enabling you to run
administrative operations in a scripting language. The wsadmin tool is intended
for production environments and unattended operations.
In addition to application server related tasks, the wsadmin scripting program can
be used to manage WSRR applications, by invoking the Service Registry and
Repository MBean. All of the operations available on the JMX interface are
available to the wsadmin scripting program. wsadmin scripts can be written in
Jacl or Jython.
8.1.2 Administrative (JMX) interface

The WSRR administrative (JMX) interface provides a Java API that allows you to
manage configuration settings to control registry runtime behavior. For example,
loading and removing classification systems (ontologies), setting up access
control policies, or customizing the user interface. In addition you can register
listeners for specific administration events. Sample client code is provided for you
to build on in the <WSRR_HOME>\admin\javasrc directory.
282
8.1.3 Command line administration

Jython-based command line interface. The command line interface provides full
operations.
Several example scripts show you how to perform governance tasks such as
promoting entities from one WSRR instance to another, or transitioning entities
through different lifecycle states. These scripts can be found in the
<WSRR_HOME>\CLI\scripts directory.
8.1.4 Configuration data

The behavior of many aspects of WSRR is determined by configuration data
residing in configuration files, typically using XML. For example, user interface
perspectives, lifecycle states, access control policies are all stored this way.
These configuration files are managed using the administrative tools described in
this chapter. Configuration items are stored with a configuration name, the
content of the configuration file, the type of configuration and whether the specific
configuration is a system configuration or a user-defined one.
8.2 WSRR configurations

WSRR components use configuration documents stored within the registry to
determine their runtime behavior. The management interfaces allow
administrators to retrieve, create, update, and remove configurations to meet
their business requirements.
A configuration in WSRR consists of:
Name
A logical name to uniquely identify the configuration for a particular
configuration type. The name must be 1 to 255 characters in length.
Configuration type
An identifier for the type of configuration, used by components to read the
content of the configuration in the appropriate context. See 8.2.1, Supported
configurations on page 284 for allowed configuration type values.
Content
The raw configuration content, stored as bytes. The configuration
administration operations provide different constructors to take the content
parameter as a byte array, a server-local file, or a remote URL.
Chapter 8. Administering WSRR
283
System indicator
A boolean flag which indicates if the configuration is a system configuration
(true) or a user-defined one (false). WSRR components may use this flag to
determine whether a configuration is required.
When a configuration is created, it is given a unique URI (within WSRR). Some
operations have signatures that take this URI as the configuration identifier, for
example updateConfiguration, retrieveConfiguration and deleteConfiguration. In
situations where you do not have this identifier available, operations often have a
signature that takes a name and configuration type, for example
updateConfiguration, retrieveConfiguration. To find out the identifier for a
configuration there is an operation that accepts a name and a configuration type.
8.2.1 Supported configurations

The configuration type parameter value for each configuration must be one of the
following:
Table 8-1 Supported configurations
Configuration type
Description
UI_PERSPECTIVE
UI perspective definition
UI_NAVIGATION_TREE
UI navigation tree definition
UI_VIEW_QUERY_SYSTEM
UI view query definition (system)
UI_VIEW_QUERY_USER_DEF
UI view query definition (user-defined)
UI_DETAIL_VIEW
UI detail view definition
UI_COLLECTION_VIEW
UI collection view definition
SACL
Lifecycle state definition
XACML
Access control definition
EMAIL_TEMPLATE
E-mail template for subscription notifications
PLUGIN_PROPERTIES
plugin properties
Note: If you are customizing the WSRR Web user interface, do not use the
UI_VIEW_QUERY_SYSTEM configuration type - use the
UI_VIEW_QUERY_USER_DEF configuration type with its
systemConfiguration flag set to false.
284
These values can be determined programmatically using the

com.ibm.serviceregistry.admin.ConfigurationType java class found in the
ServiceRegistryClient.jar. All of the allowed configuration types are declared as
public static final fields (it's a type-safe enumeration). This class also has a
utility method isConfigurationType(String type) which returns true if the type
is valid.
8.3 Security considerations

When WebSphere global security is enabled, you can only invoke the operations
of the ServiceRegistryRepository MBean if you are a user in an administrative
role.
The operations which make updates require the WebSphere Administrator or
Operator role, while read operations can be performed by the WebSphere
Administrator, Operator, Configurator and Monitor roles.
With security enabled you will also need to provide additional security
parameters when configuring the connection to the MBean.
8.4 Administering WSRR using wsadmin

WSRR administrative operations are performed by invoking the WSRR MBean
using standard wsadmin commands. You need to know the type of the WSRR
MBean, and the cell, node and server for the WSRR you want to configure.
8.4.1 Setting up wsadmin for managing WSRR

If the WSRR MBean encounters an error, either a validation problem with input
parameters or a system problem, it will throw a WSRR specific exception of type
com.ibm.serviceregistry.exception.admin.AdminException. This AdminException
may also contain one or more cause exceptions which will be subtypes of
ServiceRegistryException. These exception classes are available in the
ServiceRegistryClient.jar file. For this reason, the wsadmin environment must be
configured with the exception classes available on the class path. To configure
wsadmin, in addition to any other parameters specific to your environment, you
must specify the class path as follows:
<WASPATH>\bin\wsadmin
-wsadmin_classpath <WSRRPATH>\ServiceRegistryClient.jar
285
Where <WASPATH> is the path to the directory where WebSphere Application

Server is installed and <WSRRPATH> is the path to the directory where the
ServiceRegistryClient.jar resides.
Refer to the WebSphere Application Server scripting documentation for further
information:
websphere.base.doc/info/aes/ae/txml_scriptingep.html
8.4.2 Locating the WSRR MBean with wsadmin

As for all MBeans present in a WebSphere application server environment,
including cells, the only information required to start invoking MBean operations
is to know the MBean type. In the case of WSRR, the MBean type is
ServiceRegistryRepository.
1. To locate the WSRR MBean, first create a string representation of an
ObjectName query:
wsadmin>set objectNameString [$AdminControl queryNames
type=ServiceRegistryRepository,*]
This finds the ObjectNames for all WSRR MBeans running in the WebSphere
server process. If the client is connected to a Deployment Manager, there
may be multiple WSRR MBeans present in the cell. In this case you could
reduce the scope of the query and specify the cell name, node name and
server name.
The typical response will be the string representation of the matching
ObjectName:
WebSphere:platform=dynamicproxy,cell=WSRRCell,version=6.0.2.11,name=
ServiceRegistryRepository,mbeanIdentifier=ServiceRegistryRepository,
type=ServiceRegistryRepository,node=WSRRNode,process=server1
2. The next step is to create a JMX ObjectName object version from the string:
wsadmin>set objectName [$AdminControl makeObjectName
$objectNameString]
WebSphere:platform=dynamicproxy,cell=WSRRCell,version=6.0.2.11,name=
ServiceRegistryRepository,mbeanIdentifier=ServiceRegistryRepository,
type=ServiceRegistryRepository,node=WSRRNode,process=server1
8.4.3 Discovering WSRR MBean operations using wsadmin

You can interactively discover the interface of all WSRR MBean operations by
using the standard help mechanism of wsadmin. You must pass the string
286
version of the ObjectName (See 8.4.2, Locating the WSRR MBean with
wsadmin on page 286):
wsadmin>$Help operations $objectNameString
This will then respond with a list of possible operations. All available operations
have been described in Table 8-2.
More information about the Admin MBean operations can be found in the MBean
reference documentation:
http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.ja
vadoc.doc/WSRR_MBean.html
Table 8-2 Admin MBean operations
Method
Description
Parameters
loadConfiguration
Loads configuration file contents from a byte

array, returning ID of created object
name, type, content,

systemConfiguration
loadConfiguration
Loads configuration file contents from given

location, returning ID of created object
name, type, location,

systemConfiguration
loadConfiguration
Loads configuration file contents from a File,

returning ID of created object
name, type, file,

systemConfiguration
updateConfiguration
Updates configuration file contents of given

name
name, type, content,

systemConfiguration
updateConfiguration
Updates configuration file contents of given

ID
id, content,
systemConfiguration
retrieveConfiguration
Returns configuration file contents for given

ID
id
Returns configuration file contents for given

name
name, type,
systemConfiguration
retrieveAllConfigurationNames
Returns names (as String) of all

configurations for given type
type
deleteConfiguration
Deletes configuration file of given ID
id
getConfigurationId
Returns ID of configuration document for

given name and configuration type
name, type
getConfigurationIds
Returns IDs for all configuration documents

of the given configuration type
type
createOntologySystem
Creates ontology system
content
287
Method
Description
Parameters
Loads ontology system contents from given

location, returning ID of created ontology
system
location
deleteOntologySystem
Removes ontology system
uri
importMetaData
Imports Service Registry and Repository

metadata content returning the list of URIs for
objects created
xmlBytes
exportMetaData
Exports metadata XML (as byte array) for

specified Service Registry and Repository
objects
uris
addRole
Adds a new role to the Service Registry and

Repository authorization component role
mapping configuration
roleName
removeRole
Removes a role from the Service Registry

and Repository authorization component role
roleName
addPrincipalToRole
Adds a principal to a role in the Service

Registry and Repository authorization
component role mapping configuration
principalSecurityName,
roleName
removePrincipalFromRole
Removes a principal from a role in the

authorization component role mapping
configuration
principalSecurityName,
roleName
getRolesWithPermissions
Gets all roles with permissions in the Service

component policy configuration
None
removePermissionFromRole
Removes a permission from a role in the

configuration
permissionName,
roleName
removeAllRolePermissions
Removes all permissions from roles in the

authorization component policy configuration
None
removeAllRoles
Removes all roles from the Service Registry

and Repository authorization component role
None
288
Method
Description
Parameters
addPermissionToRole
Adds a permission to a role in the Service

component policy configuration
roleName, action,
permissionName,
permissionTarget
addPermissionToRole2
Adds an existing permission to a role in the

roleName,
permissionName
getPermissionsForRole
Returns all permissions (as String) for the

given role in the Service Registry and
Repository authorization component policy
configuration
roleName
persistPolicy
Persist the Service Registry and Repository

None
persistRoleMappings
Persist the Service Registry and Repository

configuration
None
8.4.4 Discovering WSRR MBean notifications using wsadmin

Using wsadmin help, again with the string version of the ObjectName of the
WSRR MBean, you can list the notification events fired by WSRR when certain
operations are invoked:
Example 8-1 Discover WSRR MBean notifications using wsadmin
wsadmin>$Help notifications $objectNameString

Notifications
ibm.serviceregistry.event
ibm.serviceregistry.classificationsystem.loaded
ibm.serviceregistry.classificationsystem.deleted
ibm.serviceregistry.configuration.loaded
ibm.serviceregistry.configuration.deleted
ibm.serviceregistry.configuration.updated
jmx.attribute.changed
These events can be monitored programmatically using standard JMX
techniques.
8.4.5 Invoking operations on WSRR MBean using wsadmin

To invoke MBean operations, the operation signature and parameters must be
passed to the invoke operation of the MBean client. The operation signature
289
specifies each of the parameter types as string values, and the parameters are
the corresponding values, as Java objects.
As an example, the loadConfiguration operation with the signature that takes a
byte[] as the configuration content is used to illustrate how to invoke one of the
WSRR MBean operations to load a custom navigation tree for the WSRR Web
user interface, from an XML file called CustomNavTree.xml. The full signature of
the operation is as follows:
java.lang.String loadConfiguration(java.lang.String name,
java.lang.String type, byte[] content, boolean systemConfiguration)
The return type is the id of the configuration item in the registry. First, read the
configuration file into a byte[] as in Example 8-2:
Example 8-2 wsadmin - read configuration file into a byte array
set filename "CustomNavTree.xml"

set filepath "C:/configurations"
set fis [java::new {java.io.FileInputStream} "$filepath/$filename"]
set channel [$fis {getChannel}]
set chansize [$channel {size}]
Create the byte array object with the same size as the file as in Example 8-3:
Example 8-3 wsadmin - create the byte array object
set content [java::new {byte[]} $chansize]

Populate the byte array with the file content as in Example 8-4:
Example 8-4 wsadmin - populate the byte array
$fis read $content

Set up the required signature as in Example 8-5:
Example 8-5 wsadmin - set up the signature
set sigs
$sigs
$sigs
$sigs
$sigs
290
[java::new {java.lang.String[]} 4]
set 0 java.lang.String
set 1 java.lang.String
set 2 \[B
set 3 boolean
Note: The byte array in the signature must be specified in the Java shorthand
notation and the square bracket must be escaped with a backslash character.
Also note that the operation requires a boolean primitive, set in the signature
as 'boolean' but because the parameters must be specified as an Object[], a
java.lang.Boolean is passed.
Set the parameter values in the parameters array as in Example 8-6:
Example 8-6 wsadmin - set the parameter values
set name "CustomNavTree"

set type "UI_NAVIGATION_TREE"
set systemConfig [java::new {java.lang.Boolean} false]
set params [java::new {java.lang.Object[]} 4]
$params set 0 $name
$params set 1 $type
$params set 2 $content
$params set 3 $systemConfig
set id [$AdminControl invoke_jmx $objectName loadConfiguration $params
$sigs]
The system returns the unique ID of the new configuration.
8.4.6 Troubleshooting WSRR administration with wsadmin

WSRR MBean operation parameters are validated before invoking the operation.
Should invalid data be passed to the operation, or the operation results in a
system error, the operation will throw an AdminException and cause exception.
The messages associated with the AdminException aim to help diagnose the
problem.
For example, if you tried to load a configuration file using the same configuration
name and the same configuration type as a configuration already present in
WSRR, the message in Example 8-7 would be returned in the wsadmin scripting
client.
Example 8-7 wsadmin - example exception message
javax.management.MBeanException
com.ibm.serviceregistry.exception.admin.AdminException:
com.ibm.serviceregistry.exception.admin.AdminException: GSR0098E: A
291
ConfigItem with the same name and configuration type already exists in
the repository.
A limitation of wsadmin is that when an MBeanException is thrown, the wsadmin
environment throws a ScriptingException to the client with only the message of
the underlying exception, but has no way of retrieving the cause exception. There
are circumstances where you may get a
com.ibm.serviceregistry.exception.admin.AdminException indicating an
operation failed. For example, if you tried to load a configuration with an invalid
configuration type of UI_PERSECTIVE you would get:
Example 8-8 wsadmin - example invalid configuration type exception
javax.management.MBeanException: null nested exception is

com.ibm.serviceregistry.exception.admin.AdminException: GSR0125E:
Unable to load configuration.
There is a cause exception of type
com.ibm.serviceregistry.exception.admin.ConstraintException with a message of
GSR0138E: The configuration type value UI_PERSECTIVE is unknown but
this is not reported by wsadmin. However, java JMX clients and WSRR command
line interface clients are able to catch and handle AdminExceptions and their
cause exceptions directly.
If you cannot diagnose problems similar in nature to this when invoking
administration operations using wsadmin, you can establish the cause by turning
on wsadmin trace. To turn on wsadmin tracing:
In the directory WAS_HOME/properties, in the file wsadmin.properties,
uncomment this line:
com.ibm.ws.scripting.traceString=com.ibm.*=all=enabled
When you invoke the wsadmin command again, the results are recorded in a file
wsadmin.traceout, in the directory WAS_HOME\profiles\<profile name>\logs.
This provides a stack trace, including the cause exception and its message.
8.5 Administering WSRR using JMX

WSRR can be managed programmatically by any remote Java client. A client
proxy class in ServiceRegistryClient.jar allows you to easily connect to the
WSRR MBean and invoke operations by invoking corresponding methods on the
proxy, without your classes needing to know about JMX classes or the WSRR
MBean.
292
The ServiceRegistryRepositoryProxy class can be configured and invoked as-is,

or, with the provided source code, you can customize it to suit your needs. The
source code for this class can be found in the WSRR installation directory, at:
<WSRRHOME>/admin/javasrc
8.5.1 Using ServiceRegistryRepositoryProxy.java JMX client

The ServiceRegistryRepositoryProxy class is built around standard code to set
up the properties required to connect to the MBean on the target WSRR,
establish the connection, locate the WSRR MBean, and then allow further
requests to invoke specific operations. The proxy class takes care of casting
parameters and return types to the types you expect to use according to the
WSRR MBean interface.
Exception handling is left as an exercise for the developer but you should look at
8.5.3, Exception handling with the Java JMX client on page 296 for information
about how to extract the available diagnostic information when an exception is
thrown by the WSRR administration component.
To invoke operations on the WSRR MBean follow this simple approach:
1. From your own client code, use one of the constructors to get an instance of
the ServiceRegistryRepositoryProxy class. This locates the WSRR MBean
and stores a reference to it.
2. Prepare parameters according to the WSRR MBean API.
3. Invoke methods on the proxy class, passing the necessary parameters.
4. Handle exceptions.
Each of these steps is described in the following sections.
ServiceRegistryRepositoryProxy.java constructors
There are three constructors available, depending on the way that the target
server is configured, whether global security is enabled, and which connector
type you want to use.
Use this constructor when global security is off and you want to use SOAP:
public ServiceRegistryRepositoryProxy(String server, String port,
String wasHome)
Use this constructor when WAS global security is enabled and you want to
use SOAP:
ServiceRegistryRepositoryProxy(String server, String port, String
wasHome, String userName, String userPassword, String
293
trustStorePath, String keyStorePath, String trustStorePassword,

String keyStorePassword)
Use this constructor if you want to configure the connection separately and
choose from the available connector types (SOAP, RMI or JMS):
public ServiceRegistryRepositoryProxy(Properties adminProperties)
When the connection is established, the proxy (private) method setupMBean
attempts to locate the WSRR MBean using this ObjectName query:
ObjectName queryName = new
ObjectName("WebSphere:type=ServiceRegistryRepository,*");
The queryNames method of AdminClient is invoked which uses the query to
search the entire cell for all occurrences of the WSRR MBean. If more than one
WSRR MBean ObjectName is found, only the first is used in this implementation,
and set as a private object variable for use by other public methods.
Note: If you want to run in an environment where there is more than one
WSRR application installed in the same cell (for example in WebSphere
Application Server Network Deployment), you will need to modify the
setupMBean method to use a more specific query that restricts and specifies
the server and node such that one MBean reference is obtained.
If running the client code from a static main method, the arguments passed could
correspond with the parameters required for one of the constructors. For
example:
String server = args[0];
String soapPort = args[1];
String wasHome = args[2];
ServiceRegistryRepositoryProxy wsrr =
new ServiceRegistryRepositoryProxy(server, soapPort, wasHome);
Determining the WSRR MBean API programmatically

The ServiceRegistryRepositoryProxy class provides a utility method
(outputMBeanInterface) to programmatically interrogate the
ServiceRegistryRepository MBean and output all the available attributes,
operations and notifications to System.out. For each operation, the return type,
operation name and parameter types are output as well as the impact property
which indicates how the operation changes the state of the
ServiceRegistryRepository MBean (and the WSRR application). As for all
MBeans, the value for the impact property can be one of the following:
294
ACTION
the state of the MBean will be changed
INFO
the state of the MBean remains unchanged and will return information
ACTION_INFO
the state of the MBean will change and return some information
UNKNOWN
the impact of invoking the operation is not known
Invoke outputMBeanInterface method (verbose parameter is set to false). The
available methods can be found described in Table 8-2 on page 287. The
expected output of invoking outputMBeanInterface can be found in the WSRR
Information Center:
c/twsr_adminstn_adiministration21.html
8.5.2 Invoking WSRR MBean operations with the Java JMX client
As an example, the following code illustrates how to gather a list of the names of
all configurations in WSRR for a particular configuration type. The method to
invoke is retrieveAllConfigurationNames, with this signature:
public List retrieveAllConfigurationNames(String type)
The type parameter can be any String but as far as the administration component
is concerned, it must be one of the allowed configuration types. To ensure this,
use the ConfigurationType class and choose one of the types, in this case
UI_DETAIL_VIEW as shown in Example 8-9.
Example 8-9 JMX ConfigurationType example
List uiDetailViewNames =
wsrr.retrieveAllConfigurationNames(
ConfigurationType.UI_DETAIL_VIEW.toString());
System.out.println("UI detail view configurations:");
Iterator iterator = uiDetailViewNames.iterator();
while (iterator.hasNext()) {
String configurationName = (String) iterator.next();
System.out.println(configurationName);
}
295
The configuration names are returned as a List to the invoking class. Inspecting
the retrieveAllConfigurationNames method in the proxy class shows how the
parameters are prepared for invoking the MBean operation:
1. Specify the type of each parameters:
String[] signature = new String[] { String.class.getName() };
2. Place the parameters in an object array:
Object[] params = new Object[] { type };
3. Invoke the method by name and cast the returned object to the required type:
List names = (List) invoke("retrieveAllConfigurationNames",
signature, params);
4. Return the result:
return names;
The invoke method in the proxy is used by all other public methods to invoke the
actual MBean operation, using the AdminClient object, previously set up in the
constructor:
return adminClient.invoke(mBean, operation, params, signature);
This pattern for invoking MBean operations is the same regardless of whether
the client is using Java code, or scripts using wsadmin or the WSRR command
line interface.
8.5.3 Exception handling with the Java JMX client

The public methods that correspond to WSRR MBean operations declare they
throw the following exceptions:
InstanceNotFoundException
MBeanException
ReflectionException
ConnectorException
For diagnosing problems caused by invalid parameters, or a problem occurring in

WSRR, the important exception to examine is MBeanException. The
MBeanServer will add any exceptions thrown by the MBean as the cause
exception of an MBeanException. The WSRR MBean will only ever throw
com.ibm.serviceregistry.exception.admin.AdminException exceptions, and
the following example shows how MBeanException can be examined to get
useful diagnostic information.
296
Note: Do not confuse

com.ibm.serviceregistry.exception.admin.AdminException (thrown by
WSRR MBean) with the
com.ibm.websphere.management.exception.AdminException.
Using the previous example, retrieving configuration names for a particular
configuration type, the first step is to place a try-catch block around the method
call as illustrated in Example 8-10.
Example 8-10 JMX - retrieve configuration names example with try-catch block
try {
List uiDetailViewNames =
wsrr.retrieveAllConfigurationNames(
System.out.println("UI detail view configurations:");
Iterator iterator = uiDetailViewNames.iterator();
while (iterator.hasNext()) {
String configurationName = (String) iterator.next();
System.out.println(configurationName);
}
} catch (MBeanException e) {
} catch (Exception e) {
e.printStackTrace();
}
To simplify the example, the InstanceNotFoundException, ReflectionException
and ConnectorException are caught in the last catch block and ignored.
To determine if the MBeanException contains an AdminException, extract the
cause exception as shown in Example 8-11:
Example 8-11 JMX - retrieve configuration names example extract cause exception
if (e.getCause() != null &&
e.getCause() instanceof AdminException) {
AdminException ae = (AdminException) e.getCause();
}
}
297
In addition to the standard getMessage and getLocalizedMessage from the

Exception class, the AdminException (which inherits from
ServiceRegistryException) provides several helper methods to pull out more
specific information as shown in Example 8-12:
Example 8-12 JMX - retrieve configuration names example with added information
if (e.getCause() != null &&
e.getCause() instanceof AdminException) {
AdminException ae = (AdminException) e.getCause();
System.out.println("Caught AdminException: ");
System.out.println("message: " + ae.getMessage());
System.out.println("explanation: " + ae.getExplanationText());
System.out.println("response: " + ae.getResponseText());
if (ae.getCause() != null &&
ae.getCause() instanceof AdminException) {
AdminException ce = (AdminException) ae.getCause();
System.out.println("AdminException cause: ");
System.out.println("message: " + ce.getMessage());
System.out.println("explanation: " + ce.getExplanationText());
System.out.println("response: " + ce.getResponseText());
}
}
}
The example code outputs the messages using default locale of the system. The
methods getExplanationText, getResponseText are overloaded to take a Locale
object if you want the message in a particular language. There are other
methods available on the ServiceRegistryException class to retrieve the
message number, message severity, and the message without the prefix.
You can force an AdminException to be thrown by changing this line:
List uiDetailViewNames = wsrr.retrieveAllConfigurationNames(
to this, where the configuration type is invalid:
List uiDetailViewNames = wsrr.retrieveAllConfigurationNames(
"INVALID_DETAIL_VIEW");
This results in this output are shown in Example 8-13 on page 299.
298
Example 8-13 Results of invalid configuration type
Caught AdminException:
message: GSR0131E: Unable to retrieve all configuration names for
configuration type "INVALID_DETAIL_VIEW".
explanation: The configuration type may not be valid. The operation may
have failed because of a validation error or a system error. If there
is a cause exception, its message may offer more explanation.
response: Check the type is valid. Correct any validation errors caused
by invalid parameters, and check system configuration.
AdminException cause:
message: GSR0138E: The configuration type value "INVALID_DETAIL_VIEW"
is unknown.
explanation: The configuration type must be one of the values in the
ConfigurationType class.
response: Replace the value of the configuration type string with a
valid value.
8.6 Administering WSRR using the CLI

Jython-based command line interface. The command line interface provides full
operations. It may be used from a standalone Jython or Jacl interpreter, or it may
be run inside wsadmin and used in conjunction with the facilities available there.
Several example scripts show you how to perform governance tasks such as
promoting entities from one WSRR to another, or transitioning entities through
different lifecycle states.
8.6.1 Configuring scripting environment

The command line client is invoked through the high level operating system
specific script called wsrrcli which sets up the command line environment for
accessing Jython and WebSphere Application Server libraries. This script should
be configured appropriately as a part of the installation. The following explains
the installation and configuration steps.
Install WebSphere, Jython

The WSRR command line client requires that either WebSphere Application
Server or WebSphere Application Client be installed. If you are using the
application client you will need to install Jython as well.
299
The default method is to copy jython.jar from an application server installation

into the AppClient/optionalLibraries/jython directory.
Edit environment variables

The command line client is invoked from scripts installed in <WSRR_HOME>/CLI. On
Unix-like platforms the script is wsrrcli.sh; on Windows platforms it is
WSRRCLI.bat. There are several environment variables referenced in the script.
Customize the environment variables to suit your installation:
WSRR_HOME the root of the WSRR installation, something like
C:\IBM\WebSphereServiceRegistry or /opt/IBM/WebSphereServiceRegistry.
It is used to locate the WSRR client java libraries, scripts, and configuration
files.
WAS_HOME the root of the WebSphere installation, something like
C:\IBM\WebSphere\AppServer or /opt/IBM/WebSphere/AppClient. It is used to
locate WebSphere client java libraries, and so on.
JYTHON_HOME the root of the Jython install, which contains the jython.jar
library. By default the command line client uses the Jython from the
WebSphere installation.
JAVA the Java executable to be used to execute Jython. By default the
command line client uses the JVM from the WebSphere installation. It must
refer to an IBM JVM.
Edit network and security configuration

The command line client generally refers to a configuration file containing the
network connection and security configuration of the service registry repository.
A sample is contained in config\wsrrcli.conf, as well as samples of two
associated files. Configuring a secure WebSphere environment can be complex,
and users interested in the topic should consult the WebSphere Application
Server documentation.
There are two ways to access the service registry repository, EJB and MBean,
and they require different parameters.
Find the parameters.
EJB connection configuration parameters include:
java.naming.provider.url
com.ibm.CORBA.ConfigURL
com.ibm.CORBA.loginUserid (optional, may be supplied at runtime)
com.ibm.CORBA.loginPassword (optional, may be supplied at runtime)
300
java.security.auth.login.config
MBean connection configuration parameters include:
host
port
type (SOAP or RMI)
username (optional, may be supplied at runtime)
password (optional, may be supplied at runtime)
securityEnabled
javax.net.ssl.trustStore
javax.net.ssl.keyStore
javax.net.ssl.trustStorePassword
javax.net.ssl.keyStorePassword
You may designate an alias by prefixing the parameter names with the alias,
thus: AN_ALIAS.host = test21.location.ibm-itso.com
This makes it possible to store configuration information for several machines in
the same file. The following example (Example 8-14) shows a configuration for
two machines, an unsecured machine open and a secure machine secure.
(Note that line breaks have been inserted for readability refer to file for actual
format.)
Example 8-14 Example CLI configuration file
## sample unsecured site -- alias "open"

# EJB connection configuration
open.java.naming.provider.url = iiop://192.168.1.100:2809
# MBean connection configuration parameters
open.host = 192.168.1.100
open.port = 8880
open.type = SOAP
open.securityEnabled = false
## sample secure site -- alias "secure"
secure.java.naming.provider.url = iiop://192.168.1.101:2809
secure.com.ibm.CORBA.ConfigURL =
file:///IBM/WebSphereServiceRegistry/CLI/config/sas.client.props
secure.java.security.auth.login.config =
file:///IBM/WebSphereServiceRegistry/CLI/config/wsjaas_client.conf
301
secure.host = 192.168.1.101
secure.port = 8880
secure.type = SOAP
secure.securityEnabled = true
secure.javax.net.ssl.trustStore =
C:/IBM/WebSphere/AppClient/etc/DummyClientTrustFile.jks
secure.javax.net.ssl.keyStore =
C:/IBM/WebSphere/AppClient/etc/DummyClientKeyFile.jks
secure.javax.net.ssl.trustStorePassword = WebAS
secure.javax.net.ssl.keyStorePassword = WebAS
Test connectivity
Once you have installed and configured the command line client it is a good idea
to test that it can connect properly to the WSRR server. The connectTest.py
script establishes and tests connections to each of the EJB beans and to the
MBean server.
To use it, run:
wsrrcli connectTest.py -a <configFile> \ -u <> -p <password>
For example:
WSRRCLI.bat scripts\connectTest.py a open c config\wsrrcli.conf
Or:
wsrrcli.sh scripts/connectTest.py a secure \ c config/wsrrcli.conf
-u username p passw0rd
8.6.2 Scripting elements and objects

The command line interface provides a thin utility class called the
WSRRConnectionFactory that helps in setting up the connections and sessions to
the WSRR EJB and MBean objects. These objects can then be manipulated in
the Jython scripts to invoke the desired operations on the WSRR API. See below
for the API specification for WSRRConnectionFactory class.
Constructor detail
Example 8-15 and Example 8-16 on page 303 detail the two constructors.
Example 8-15 WSRRConnectionFactory constructor
public WSRRConnectionFactory(java.util.Properties newProperties,

java.lang.String alias)
throws CLIException
302
Create a new WSRRConnectionFactory directly from a Properties object

containing configuration information. An alias may be specified; if
null is passed then no alias will be used and the keys in the
properties object will be used unmodified.
Parameters:
newProperties - Properties object containing configuration information
alias - alias value, null if no alias is to be used
Example 8-16 WSRRConnectionFactory constructor
public WSRRConnectionFactory(java.lang.String configFileName,

java.lang.String alias)
throws CLIException
Create a new WSRRConnectionFactory from a properties file containing
configuration information. If the file name is null an attempt will be
made to find the file specified by
com.ibm.serviceregistry.cli.ConfigURL. If
com.ibm.serviceregistry.cli.ConfigURL is not defined, the file
config/wsrrcli.conf will be used. An alias may be specified; if a null
is passed then no alias will be used and the keys in the configuration
file will be used unmodified.
Parameters:
configFileName - configuration file name
alias - alias value, null if no alias is to be used
Method detail
Example 8-17, Example 8-18 on page 304, Example 8-19 on page 304,
Example 8-20 on page 305 and Example 8-21 on page 305 show examples of
the available methods.
Example 8-17 getSessionConnection method
public com.ibm.serviceregistry.ServiceRegistrySession
getSessionConnection(java.lang.String user,
java.lang.String password)
throws java.rmi.RemoteException,
javax.naming.NamingException,
javax.ejb.CreateException,
CLIException
303
Returns a connection to the WSRR core session bean, using the session
bean connection parameters in the configuration.
Parameters:
user - user name to use for authentication, or null
password - password to use for authentication, or null
Returns:
ServiceRegistrySession instance
Example 8-18 getOntologyConnection method
public com.ibm.serviceregistry.ServiceRegistryOntology
getOntologyConnection(java.lang.String user,
CLIException
Returns connection to the WSRR Ontology manager, using the session bean
connection parameters in the configuration.
Parameters:
Returns:
ServiceRegistryOntology instance
Example 8-19 getGovernanceConnection method
public com.ibm.serviceregistry.governance.ServiceRegistryGovernance
getGovernanceConnection(java.lang.String user,
CLIException
Returns connection to the WSRR Governance bean, using the session bean
connection parameters in the configuration.
Parameters:
304

Returns:
ServiceRegistryGovernance instance
Example 8-20 getServiceRegistryRepositoryProxy method
public com.ibm.serviceregistry.admin.ServiceRegistryRepositoryProxy
getServiceRegistryRepositoryProxy(String user, String password)
throws ServiceRegistryException {
Gets ServiceRegistryRepositoryProxy instance using mbean connection
parameters from configuration. The proxy represents a
ServiceRegistryRepository MBean and provices methods that correspond to
the operations defined in the ServiceRegistryRepository MBean
descriptor.
Parameters:
password - password to use for authentication, null
Returns:
ServiceRegistryRepositoryProxy instance
Example 8-21 getProperties method
public java.util.Properties getProperties()

Returns a copy of the properties used to configure this instance of the
connection factory.
Returns:
copy of Properties object for this connection factory
Refer to the following API specifications for more details on the API operations
that are available to be invoked from the command line scripts:
WSRR External programmatic API:
c/rwsr_api.html
WSRR MBean API:
305
8.6.3 Sample scripts

A number of scripts are provided with the WSRR command line client for
illustrative purposes. Some of these scripts are utility scripts while others use the
utility scripts and perform programmatic and administrative tasks such as
creating content in WSRR, state transitions, export, import, find, and so on.
Though all the provided scripts are written in Jython, users are free to create and
use Jacl scripts instead of Jython using the API objects available. All the sample
scripts can be found in the <WSRR_HOME>\CLI\scripts directory.
The sample script cmdline.py provides methods that provides utility methods to
parse and validate command line arguments supplied to the command line
scripts.
The fileUtils.py and utils.py scripts provide utility methods to read and write
byte arrays from files, and to find objects by name, namespace, and version in
the Service Registry.
The createGenericObject.py is a sample script used to create generic
objects with the specified name, namespace and version information.
Usage: createGenericObject.py -a <alias> -c <configFile> -u <user>
-p <password> -n <name> -ns <namespace> -v <version>
The createXMLDocument.py script is used to create an XML document in the
Service Registry from the supplied input file
Usage: createXMLDocument.py -a <alias> -c <configFile> -u <user>
-p <password> -in <inputFile> -n <name> -ns <namespace> -v
<version> -loc <location>
The findBaseObject.py script queries the Service Registry for the requested
object based on the name, namespace and version.
Usage: findBaseObject.py -a <alias> -c <configFile> -u <user> -p
<password> -n <name> -ns <namespace> -v <version>
The deleteBaseObject.py script removes the object(s) from the Service
Registry that findBasObject.py would return.
Usage: deleteBaseObject.py -a <alias> -c <configFile> -u <user> -p
<password> -n <name> -ns <namespace> -v <version>
The export.py script exports the specified object into a file on the local file
system.
Usage: export.py -a <alias> -c <configFile> -u <user> -p
<password> -n <objectName> -ns <objectNamespace> -v
<objectVersion> -out <outputFile>
306
The import.py script imports an object into a WSRR instance from the
supplied file
Usage: import.py -a <alias> -c <configFile> -u <user> -p
<password> -in <inputFile>
The promote.py script promotes an object from one WSRR instance to
another
Usage: promote.py -c
<sourceUserName> -sp
<targerUserName> -tp
<objectNamespace> -v
<configFile> -s <sourceAlias> -su

<sourcePassword> -t <targetAlias> -tu
<targetPassword> -n <objectName> -ns
<objectVersion>
The transition.py script executes a transition on an object in the WSRR

instance.
Usage: transition.py -a <alias> -c <configFile> -u <user> -p
<password> -n <name> -ns <namespace> -v <version> -t <transition>
The loadConfig.py script loads configuration data to WSRR instance from
the specified file.
Usage: loadConfig.py -a <alias> -c <configFile> -u <user> -p
<password> -n <configName> -t <configType> -in <inputFile>
The retrieveConfig.py script retrieves configuration object from WSRR
instance and optionally stores it to specified file.
Usage: retrieveConfig.py -a <alias> -c <configFile> -u <user> -p
<password> -n <configName> -t <configType> -out <outputFile>
The deleteConfig.py script deletes a configuration object from WSRR.
Usage: deleteConfig.py -a <alias> -c <configFile> -u <user> -p
<password> -n <configName> -t <configType>
The updateConfig.py script updates the specified configuration object in the
WSRR instance from the specified file.
Usage: updateConfig.py -a <alias> -c <configFile> -u <user> -p
<password> -n <configName> -t <configType> -in <inputFile>
8.7 Ontology administration

Classification systems or taxonomies are represented in WSRR as ontologies, in
the form of OWL (Web Ontology Language) files. The WSRR MBean operations
available to manage ontologies are createOntologySystem and
deleteOntologySystem as shown in Example 8-22.
307
Example 8-22 Ontology Administration MBean operations
java.lang.String createOntologySystem(byte[] content) [ACTION]

(Creates ontology system)
java.lang.String createOntologySystem(java.lang.String location)
[ACTION]
(Loads ontology system contents from given location, returning ID of
created ontology system)
void deleteOntologySystem(java.lang.String uri) [ACTION]
(Removes ontology system)
Ontologies can also be loaded and removed from WSRR using the Web user
interface by users in the Administrator role.
Note: There is no updateOntologySystem method in the WSRR MBean. To
update an ontology it must be deleted and then recreated.
8.7.1 Creating an ontology system

To create an ontology system in WSRR, your ontology must exist as an OWL
document. OWL documents are best created using dedicated tooling although
you could create an OWL document using a text or XML editor, according to the
OWL schema definition.
The WSRR MBean provides two operations to create ontology systems:
Create an ontology system from byte array:
java.lang.String createOntologySystem(byte[] content)
Create an ontology system from an OWL document hosted at a URL:
java.lang.String createOntologySystem(java.lang.String location)
Both operations return the OWL URI of the ontology system. As soon as the
ontology is system is created it is immediately available for use in the Web user
interface.
Use the Jacl script <WSRR_HOME>\admin\scripts\loadOntologySystem.jacl to
create an ontology system from an OWL document on the file system.
8.7.2 Removing an ontology system

To remove an ontology system from WSRR, use the MBean operation:
void deleteOntologySystem(java.lang.String uri)
308
The uri parameter is the OWL URI of the ontology system. When an ontology
system is deleted, it is no longer available for use in the Web user interface.
A Jacl script is provided to perform this operation using wsadmin:
<WSRR_HOME>\admin\scripts\deleteOntologySystem.jacl
Note: Before removing an ontology system you should consider the impact to
users who may have classified WSRR entities with the ontology. Deleting the
ontology system will not remove classification URIs from entities, so queries
relying on these classifications will still work. However, if users try to view an
entity with a classification that no longer exists in an ontology system, the UI
will not be able to retrieve the corresponding labels and will report an error. In
addition, users will not be able to add further classifications from that ontology
system.
8.8 Access control administration

Fine-grained access control to WSRR artefacts is applied if WebSphere global
security is enabled. The WSRR authorization component will initially try to find a
policy in the WSRR configuration files. If successful it will load and use that
policy. If no policy is found a default policy is generated at runtime and stored
within WSRR for use when the application next starts.
8.8.1 Overview of access control within WSRR

Fine-level control of access to artefacts in WSRR is role-based and is similar in
concept to the standard, declarative scheme used to control access to the
individual methods of an EJB. Within WSRR, the following types of access are
defined:
Create
Permission to create an artefact in WSRR.
Update
Permission to update a particular artefact in WSRR
Delete
Permission to delete a given artefact from WSRR
Retrieve
Permission to retrieve information from a particular artefact in WSRR.
309
Transition
Permission to apply a transition as defined by an existing governance lifecycle
to an artefact in WSRR.
Each of these types of permission is independent of all the others, and there are
no implicit relationships between them. For instance, permission to delete an
artefact does not imply that permission to update the same artefact is
automatically granted, although permission to update could be defined explicitly.
Permissions are granted to roles. The number and names of the roles used to
control access within WSRR is configurable by the user. Typically each role
defined would map to a group of users defined within the user authentication
scheme being used. Permissions are then granted to each of the defined roles as
appropriate and all users belonging to a given role have the access permissions
granted to that role.
The artefacts to which a particular permission applies are defined using a subset
of XPath. Using this subset it is possible to specify sets of artefacts by their type
(WSDLDocument for example), by their modelled and user-defined properties,
and by their classification. In this way sets of artefacts can be defined in a
generic way.
Once permission for a given type of access has been defined for a particular set
of artefacts, for a given role, then every role which requires that access to that set
of artefacts must be granted that permission explicitly. Expressing it a different
way: access to all artefacts within the registry is unrestricted until a permission is
granted protecting a particular set of artefacts. Once this happens explicit
permission is then required for the defined access type to the defined set of
artefacts.
Note: The statements made in the preceding paragraph apply independently
to each of the permission types defined previously. For example, granting
update permission to a role for a set of artefacts will not protect those artefacts
from deletion by any role. That protection must come from an explicit
declaration of delete permission granted to the appropriate role, after which
users in other roles will not be able to delete them without explicit permission.
8.8.2 Administering the WSRR access control policy

Although the access control policy used within WSRR is defined as two XACML
configuration files, it is strongly recommended that these are not modified
directly. JMX operations for administering the access control policy used by
WSRR are accessible via the WSRR MBean. These operations provide the
means to add and remove roles within the configuration, and also allow the
310
addition and removal of permissions for those roles. Operations are also
available to ensure changes made to the policy are made permanent such that
the saved policy is available when WSRR is restarted. Jacl scripts to apply these
operations are supplied in the <WSRR_HOME>\admin\scripts directory.
Refer to the following documentation sources for further information.
WebSphere Application Server scripting:
websphere.base.doc/info/aes/ae/txml_scriptingep.html
WSRR MBean API specification:
8.9 Import/Export
WSRR provides a facility for exporting collections of entities, with their associated
metadata, to a file, and importing that file back into another WSRR instance.
The WSRR export function extracts entities from the source registry and writes a
document describing selected entities and their properties, relationships and
classifications. The WSRR import function reads the export document and
publishes the entities with their metadata into a target registry. This enables a
number of possible administrative tasks, for example:
Selective backup and restore
Promotion to another WSRR instance (see 8.10, Environment promotion on
page 319)
Bulk loading of registry metadata
WSRR defines a schema for the format of this import/export file. This schema is
proprietary and published but is expected to change in forthcoming releases as
standards in this area emerge. It is recognized that users may want to manipulate
the exported data for administrative tasks so the schema has been provided and
is explained in a subsequent section.
8.9.1 Export
Only original documents should be exported, as all logical objects and metadata
associated with the original document will be exported to support it; this is
because the logical objects and metadata cannot exist without the original
311
document, so any metadata exported must also have its original document
exported.
The export function is based on the document bsrURI, so some pre-selection of
documents for export must be carried out. Document pre-selection and export
can be performed within the Web user interface.
An exported document will be accompanied by everything to which it is related; if
it is related to some metadata from another document then that document will be
contained within the export. The exported content is then a full WSRR
representation of anything to which the requested document is related, taken to
the full hierarchical depth.
If a large portion of the documents in the registry are connected via relationships
then simply exporting one could result in this large portion of the WSRR also
being exported. Care should be taken to avoid large portions of the registry being
connected in this manner and some examination of the document for export
should be carried out. Export should not be used with a large list of documents.
It should be noted that the bsrURI is exported as a normal property; however on
import, the value of this will be overwritten by a bsrURI specific to the import
registry. In addition, the exported file will contain only the classification URI, not
the ontology to which this refers.
To export artefacts from WSRR through the UI, use the Export button provided in
the document collection views. Figure 8-1 shows the Policy documents
collection, the export button is circled.
Figure 8-1 Exporting documents using the Web UI
312
8.9.2 Import
Since files for import can be created outside WSRR, and those exported from
WSRR can be manipulated, the import process follows the same process and
validation as normal creation of the document. This ensures that badly formed
import/export files will not cause problems for the registry.
The difference with import is that the file for import will contain not only the
original document but its full WSRR representation, with all supporting
documents, relationships, user-defined properties and classifications. These will
also get created in the same transaction.
The document explicitly exported must not exist in the registry on import as this
would have the same effect as trying to create an already existing document.
Supporting documents can, however, already exist within the registry and the
import will attempt to find these supporting documents and use any existing ones
in place of those in the import file. As a result, the document imported will match
that in the import/export file at the top level; however, as relationships are
followed down the graph, documents may be encountered which already exist
within the repository. Import will not alter these pre-existing supporting
documents so importing a document can only result in the creation of new
documents or relationships to existing ones; it will not result in the altering of an
already existing document.
If it is required that the import/export file exactly matches the registry after import,
then either none of the supporting documents should exist within the repository,
or each supporting document should have been previously imported.
Any logical objects (also referred to as logical derivations) included within the
import file are used to update logical objects created through the normal creation
process. Therefore, for the purposes of import, if these logical objects are not
present in the import file then the import will go through the normal creation
process and they will be created anyway. If the logical objects are present in the
import file then any user defined properties, relationships, and classifications can
be added to the created logical objects during import. Modelled properties will
not be overridden.
The following examples illustrate the process:
1. A is related to B:
If A is exported then B will be exported as a supporting document
If the export file is then imported into a registry which already contains B,
A is created and the relationship is set up to the existing B which remains
unmodified. The supporting B in the import file is not used so any user
313
defined metadata on B in the import file is not set on the existing B in the
registry.
2. A is related to B, and B is related to C:
If A is exported then B and C will be exported as supporting documents.
If the export file is then imported into a registry which already contains B,
A is created and the relationship is setup to the existing B which remains
unmodified. The supporting B in the import file is not used so any user
defined metadata on B in the import file is not set on the existing B in the
registry. C is also created since it was originally related to A via B but the
existing B is not updated since the relationship B to C may not be valid in
this new registry. However, since C is created it is possible to manually
create this relationship from B to C after the import has completed.
3. A logical object of A (logA) is related to a logical object of B (logB):
If A is exported then logA will also be exported. Since logA is related to
logB, B will be exported together with logB as a supporting document.
If the export file is then imported into a registry which already contains B
and, consequently, logB, then A is created, and the logA that is created as
a result of creating A has a relationship set up to the already existing logB.
B and logB remain unchanged. The supporting B and logB in the import
file are not used so any user defined metadata on B in the import file is not
set on the existing B in the registry.
Documents can be imported using the Web UI, click Administration Import.
Figure 8-2 shows the import screen.
Figure 8-2 Importing a document using the Web UI
314
8.9.3 Import and export with the CLI

The command line interface can also be used to manage import and export of
WSRR entities. The export.py script (see Example 8-23) and the import.py
script (see Example 8-24 on page 316) demonstrate this function. Both scripts
can be found in the <WSRR_HOME>\CLI\scripts directory. Refer to 8.6,
Administering WSRR using the CLI on page 299 for further details on the use of
the CLI.
Example 8-23 WSRR CLI export.py script
## export object from WSRR instance to file

# usage: jython export.py -a <alias> -c <configFile> -u <user> -p
<password> -n <objectName> -ns <objectNamespace> -v <objectVersion>
-out <outputFile>
import sys
options = [
[ "-a", "alias" ],
[ "-c", "configFile" ],
[ "-u", "user" ],
[ "-p", "password" ],
[ "-n", "objectName" ],
[ "-ns", "objectNamespace" ],
[ "-v", "objectVersion" ],
[ "-out", "outputFile" ]
]
## process command line arguments
import cmdline
cmdline.processArgs(sys.argv, options, globals())
## export object from WSRR to file
import utils
metadata = utils.export(alias, configFile, user, password, objectName,
objectNamespace, objectVersion)
# store export in file
if metadata != None :
from java.io import FileOutputStream
outStream = FileOutputStream(outputFile)
outStream.write(metadata)
outStream.close()
315
Example 8-24 WSRR CLI import.py script
## import object to WSRR instance from file

# usage: jython import.py -a <alias> -c <configFile> -u <user> -p
<password> -in <inputFile>
import sys
options = [
[ "-a", "alias" ],
[ "-u", "user" ],
[ "-p", "password" ],
[ "-in", "inputFile" ]
]
import cmdline
# read metadata from file
import fileUtils
metadata = fileUtils.readByteArray(inputFile)
## import metadata into WSRR instance
from com.ibm.serviceregistry.cli import WSRRConnectionFactory
connectionFactory = WSRRConnectionFactory(configFile, alias)
mbeanProxy = connectionFactory.getServiceRegistryRepositoryProxy(user,
password)
uris = mbeanProxy.importMetaData(metadata)
if uris == None :
print "No uris imported"
else :
print "imported", uris
8.9.4 Processing import / export files

The schema for import/export files, WSRRImportExport.xsd, can be found in the
<WSRR_HOME>\admin\schemas directory, where <WSRR_HOME> is the directory
location in which the WSRR files were installed.
A simple example of an export file for an XML document is shown in
Example 8-25 on page 317.
316
Example 8-25 Example export file for an XML document
<?xml version="1.0" encoding="UTF-8"?>

<ie:SRMetaData
xmlns:ie="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/importexpor
t">
<RequestedObject>
<List>
<Object id="1"/>
</List>
</RequestedObject>
<Metadata id="1">
<MetadataSection Dialect="XMLDocument" LocalName="1"><?xml
version="1.0"?>
<people>
<person name="John" favcolor="yellow" favsport="football"/>
<person name="Jane" favcolor="red" favsport="tennis"/>
</people>
</MetadataSection>
<Property PropertyName="bsrURI" appliesTo="1"
multiValue="false"/>
<Property PropertyName="description" appliesTo="1"
multiValue="false">
<PropertyValue>testXMLtoSOAPElement: This is the description
</PropertyValue>
</Property>
<Property PropertyName="lastModified" appliesTo="1"
<Property PropertyName="name" appliesTo="1" multiValue="false">
<PropertyValue>testXMLtoSOAPElement</PropertyValue>
</Property>
<Property PropertyName="namespace" appliesTo="1"
<Property PropertyName="owner" appliesTo="1" multiValue="false"/>
<Property PropertyName="version" appliesTo="1"
multiValue="false">
<PropertyValue>1</PropertyValue>
</Property>
<Property PropertyName="encoding" appliesTo="1"
<Property PropertyName="location" appliesTo="1"
multiValue="false">
<PropertyValue>testXMLtoSOAPElement</PropertyValue>
</Property>
317
<Relationship RelationshipName="predecessors" appliesTo="1"

multiValue="true"/>
<Relationship RelationshipName="template" appliesTo="1"
<Classification appliesTo="1">
<Value>File://thisIsMyClassification/fred</Value>
<Value>File://thisIsMyOtherClassification/wilma</Value>
</Classification>
<Property PropertyName="nullProperty" appliesTo="1"
<Property PropertyName="I_am_a_property" appliesTo="1"
multiValue="false">
<PropertyValue>I am property value</PropertyValue>
</Property>
<Property PropertyName="more_properties" appliesTo="1"
multiValue="false">
<PropertyValue>more property values</PropertyValue>
</Property>
</Metadata>
</ie:SRMetaData>
The file contains a list of RequestedObject elements, each with an id. This id is
used within the import/export file to apply properties, relationships, and so on, to
the correct document. The RequestedObject is used to indicate which of the
following MetadataSections must be created on import and cannot already exist.
For each RequestedObject there is a MetaData element with a matching id which
will contain the MetadataSection for this object along with MetadataSection
elements for supporting documents, logical objects and further elements for
properties, relationships and classifications.
Loading documents into WSRR through an import file

Since import follows the normal logic for creating a document, the contents of the
import file can be incomplete with respect to what is actually stored within the
repository. The minimum information required within the import file is the same
minimum information required when adding something to the repository. With this
information to hand, an import file could be written to load documents into the
repository with the ability to specify user defined relationships between them.
318
8.10 Environment promotion

Environment promotion is the process of moving a service from one WSRR
environment to another. For instance, there may be multiple Service Registries
corresponding to a development WSRR environment, a test WSRR environment,
and a production WSRR environment; so, environment promotion is the
movement of a service from development to test to production.
8.10.1 Promotion mechanism

Environment promotion is achieved through the command line interface. The
promote mechanism is implemented as a script and can be configured for
custom requirements. An example of this kind of configuration could be the state
of an entity. WSRR entities can contain a variety of metadata. Some of this
metadata, such as IT service endpoints, may need to change when an entity is
promoted. The environment promotion script allows the user to configure the
promotion for their environment.
A typical environment promotion script would perform tasks in the order specified
here:
1. A check is performed on the state of the specified entity.
2. An export of the entity is performed on the source WSRR instance, storing the
exported contents into a file.
3. An import of the entity is performed on the target WSRR instance, obtaining
the imported contents from the same file (see above).
4. The state of the imported entity is changed.
A callout to a user script could be added between items #2 and #3, to perform the
transformation. Or the transformation can be added inline by changing the default
promotion script. Since promotion is a scripted form of export/import the
promotion scheme - what will be promoted - is based on export/import. For
instance, if an entity is promoted that has a specified classification, and if that
classification does not exist in the target WSRR instance, the promotion will fail.
Or, if an entity A is promoted and it has references to other entities, when it is
imported into the target WSRR it and its dependencies will also be created.
8.10.2 Sample script for promotion

A sample promotion script (promote.py) is provided with the WSRR command
line interface to illustrate how an import/export mechanism could be utilized to
perform environment promotion.
319
Example 8-26 WSRR Sample promotion script
## Promote an object from one WSRR instance to another

# usage: jython promote.py -c <configFile> -s <sourceAlias> -su
<sourceUserName> -sp <sourcePassword> -t <targetAlias> -tu
<targerUserName> -tp <targetPassword> -n <objectName> -ns
<objectNamespace> -v <objectVersion>
import sys
options = [
[ "-s", "sourceAlias" ],
[ "-su", "sourceUserName" ],
[ "-sp", "sourcePassword" ],
[ "-t", "targetAlias" ],
[ "-tu", "targerUserName" ],
[ "-tp", "targetPassword" ],
[ "-n", "objectName" ],
[ "-ns", "objectNamespace" ],
[ "-v", "objectVersion" ]
]
import cmdline
## export metadata from source WSRR instance
import utils
metadata = utils.export(sourceAlias, configFile, sourceUserName,
sourcePassword, objectName, objectNamespace, objectVersion)
## metadata is a byte array at this point
## it can be transformed in any way desired, providing the result is
legal WSRR import/export format
## for example, it may be turned into a string, subjected to pattern
substitution, and then turned back into a byte array
## or it may be parsed into an XML document model and transformed with
XSLT
## --> your transformation here <-## import metadata into target WSRR instance
utils.import(targetAlias, configFile, targerUserName, targetPassword,
metadata)
320
Note: A sample promotion script is supplied with WebSphere Service Registry

and Repository:
<WSRR_HOME>\CLI\scripts\promote.py
This sample script above accepts command line input for connection parameters
for the source and target WSRR instances and the name/namespace/version of
the object to be exported. It then uses a utility script (utils.py) to perform the
export and import. Note that this sample script does not perform any checking on
the metatdata of the object being exported. Also, no transformations (for
example: state change) are performed on the object before it is imported to the
target WSRR instance. Refer to 8.6, Administering WSRR using the CLI on
page 299 for more information about the utility sample script.
8.11 Administration scripts (wsadmin)

Several wsadmin scripts are provided for common administration functions.
These can be used as is, or modified to suit specific environments.
The wsadmin scripts are written in Jacl, although they could just as easily be
written in Jython. The scripts are located in the WSRR installation path, at:
<WSRR_HOME>/admin/scripts
All WSRR wsadmin scripts are invoked from the wsadmin environment (both
command line or batch file) and must include the ServiceRegistryClient.jar on the
wsadmin classpath, and any parameters required by the script:
wsadmin -wsadmin_classpath <WSRR_HOME>\ServiceRegistryClient.jar> -f
<script filename> <script parameters>
The command is entered as one line. The script filename parameter is the path
to the Jacl script file. The script parameters are specific to each script, as
described below.
Additional parameters are required if you are managing WSRR in a WebSphere
Application Server that has global security enabled, or you want to use RMI
instead of SOAP. These parameters are described by the wsadmin usage
message and in the WebSphere Application Server documentation.
The WebSphere Application Server must be in started state, as must the
ServiceRegistry application.
321
8.11.1 Scripts for managing configuration

These scripts help manage configuration items in WSRR, allowing you to load,
update, delete, and view details about loaded configurations.
loadConfiguration.jacl
updateConfiguration.jacl
deleteConfiguration.jacl
reportAllConfigurations.jacl
8.11.2 Scripts for managing ontologies

Classification systems or taxonomies must be defined as Web Ontology
Language (OWL) files. The following scripts allow you to load and delete
ontologies.
loadOntologySystem.jacl
deleteOntologySystem.jacl
Note: There is no MBean operation for updateOntologySystem.
8.11.3 Scripts for import and export of WSRR entities

The following scripts allow you to export entities from WSRR and import them
into another WSRR.
exportMetaData.jacl
importMetaData.jacl
8.11.4 Scripts for managing access control policy

Fine grained control of access to entities in WSRR is achieved using the
following administration scripts.
Scripts (or directly invoked MBean operations) that change access control
policies will immediately change the runtime behavior of WSRR with the new
access control policies. However, these changes would be lost if the WSRR
application is restarted. To persist the active access control policy configurations,
invoke the two operations persistPolicy and persistRoleMappings. This can be
achieved with the scripts persistPolicy.jacl and persistRoleMappings respectively.
addPermissionToRole.jacl
addPermissionToRole2.jacl
322
addPrincipalToRole.jacl
addRole.jacl
getPermissionsForRole.jacl
getPolicyConfiguration.jacl
getRoleMappingConfiguration.jacl
getRoles.jacl
loadPolicyConfiguration.jacl
loadRoleMappingConfiguration.jacl
persistPolicy.jacl
persistRoleMappings.jacl
removeAllRolePermissions.jacl
removeAllRoles.jacl
removePermissionFromRole.jacl
removePrincipalFromRole.jacl
removeRole.jacl
8.11.5 Scripts for managing lifecycles

These scripts illustrate how to go about setting the lifecycles used by the
governance component of WSRR, and the associated access control policies.
setupDefaultLifecyclePermissions.jacl
updateLifecycleDefinition.jacl
323
324
Part 4
Part
Using WSRR
325
326
Chapter 9.
Getting started with WSRR

This chapter describes how to use the core functionality of WSRR from the Web
user interface (Web UI). It will cover how to work with documents, properties,
relationships, classifications and concepts.
It contains the following:
9.1, Introduction on page 328
9.2, Navigating the Web UI on page 329
9.3, Publishing documents on page 331
9.4, Properties on page 335
9.5, Relationships on page 347
9.6, Classifying objects on page 358
9.7, Searching the registry on page 363
9.8, Deleting artefacts on page 369
9.9, Concepts on page 370
327
9.1 Introduction
Chapter 7, Installing and deploying on page 253 explains how to install
WebSphere Service Registry and Repository. We now cover how to use the main
interface to it, the Web UI.
The Web UI enables you to use and manage all aspects of WSRR from a
compatible Web browser.
Figure 9-1 shows the WSRR Web UI welcome window.
Figure 9-1 WSRR Web UI
This chapter covers the basics of how to use the Web UI. It will then guide you
through using it to perform some basic operations such as loading a document,
adding relationships, classifications, and so on.
328
9.2 Navigating the Web UI

We cover the structure of the Web UI in 4.3.1, Web user interface layout on
page 145.
When looking at the Web UI (as in Figure 9-1 on page 328), at the top of the
screen there are some basic links that will always be present as the banner
area of the frameset is not customizable. There is a drop down list to select a
different perspective. (Creating new perspectives is covered in Chapter 10,
Customizing the Web UI on page 381.) There are also links to Logout, there is
a link to the WSRR Support site and a link to some basic Web UI Help on the
current screen.
To the left-hand side is the navigation pane. This is where you choose what
operations to perform. Selecting a link here will normally load some content or
the operation output in the workarea pane to the right.
At the top of the navigation pane is a link to the welcome window (Figure 9-1 on
page 328). Under this is the quick search box and then links to different areas of
functionality in WSRR. Each of these is briefly described in the sections that
follow.
9.2.1 Quick search

Use the quick search field at the top left of the navigation tree to find any type of
object stored in the registry. The search is performed on the entire registry using
an exact-case match on the text entered. It is matched against the name and
description properties of any object. The text is used as a partial match; for
example, a search for Echo would return both Echo.wsdl and MyEcho. You
can specify an asterisk (*) in any part of the search text to denote that any
number of other characters are permitted to occur at that position in the search
results.
9.2.2 Unified Service Metadata

Use the Unified Service Metadata section of the navigation tree to work with
views of business-oriented or abstract concepts. By default, the Unified Service
Metadata section contains just two views, Concepts and Templates. Concepts
are entities in the registry that cannot be represented using the standard WSRR
document types such as WSDL and XSD. The Concepts link shows all concept
entities that are stored in the registry. The Templates link shows all the available
templates that can be used to create concepts.
Chapter 9. Getting started with WSRR
329
9.2.3 Service Documents

Use the Service Documents section of the navigation tree to work with all of the
documents stored in the registry, and to load new documents into the registry.
9.2.4 Service Metadata

Use the Service Metadata section of the navigation tree to work with all of the
derived logical objects stored in the registry. Every time a document is loaded
into the registry, it is parsed and a rich logical view of the contained XML
elements is generated and stored along with the original document. WSDL
documents, XML schema documents, and SCA modules all have associated
logical elements derived from them and stored on upload.
Each document type that has logical elements has an expandable section in the
navigation tree that contains links to collections of the more important types of
derived logical objects for the document.
9.2.5 Queries
Use the query wizard to perform selected queries against objects stored in the
registry. See 9.7, Searching the registry on page 363 for more information.
9.2.6 Classification systems

Use classifications in the registry to make objects easier to find, and also to add
meaning to custom objects that are unique to a particular system. WSRR
supports classification systems loaded from OWL files (Web Ontology
Language).
While the underlying OWL sub-system supports most forms of OWL files, the
most useful types are ones that have simple hierarchical relationships; those for
example, found in industry standard taxonomies such as NAICS (North American
Industry Classification System). See 9.6, Classifying objects on page 358 for
more information.
9.2.7 My Service Registry

Use the My Service Registry section of the navigation tree to work with
information that is specific to you, as the current user:
My subscriptions shows the list of all subscriptions in the registry that are owned
by the currently logged-in user. This enables you to determine what objects are
330
currently being monitored. Administrators have an additional link that shows the
list of all subscriptions currently active in the registry for all users.
My favorites shows the list of objects in the registry that the current user has
selected as favorites.
My preferences shows configuration settings that allow you to alter the
appearance of elements in the Web UI. The only setting that can be changed
currently is the time zone that you want to use when dates and times are
displayed on screen.
9.2.8 Administration
The Administration section of the navigation tree allows an administrator to
import objects into the registry. Only files generated by the export facility can be
imported back into the registry. No other file formats are supported.
9.3 Publishing documents

In order to populate WSRR, documents such as WSDLs and XSDs must be
loaded. The process of loading the document creates all the logical objects that
are derived from the original source document.
Once the document is loaded, both the original source document and the derived
logical objects can then be annotated with metadata.
Assuming you have a WSDL file locally that you want to load into WSRR, use the
following steps.
331
1. From the navigation pane expand the Service Documents section and then
select Load Document as shown in Figure 9-2.
Figure 9-2 Load document menu option
Alternatively there is a Load Document button on the collection view for each
of the supported Service Document types as shown in Figure 9-3.
Figure 9-3 Load document link on XSD collection view
2. The load document wizard should then open in the workarea tab.
332
3. Select the document you want to load and optionally specify a description and
version for it. If you loaded the wizard using the Load Document link from the
navigation tree then you must also specify the document type. See Figure 9-4
for an example of the load document wizard.
Figure 9-4 Load document wizard
333
4. The document should now be loaded and a screen similar to Figure 9-5
should display.
Figure 9-5 Load document results
Once the document has been loaded a detail page summarizes the properties of
the object. There are also links to the logical objects that were derived from the
source document.
334
Any properties that are not read-only may be set from this page. The changes
will be committed when either the OK or the Apply buttons are pressed.
Clicking on the Content tab shows the contents of the source document (as in
Figure 9-6).
Figure 9-6 Document content view
9.4 Properties
WSRR is not intended to be an editor for any of the artefacts it stores. For
instance, when the WSDL for a service is published to WSRR, read-only logical
elements are created to represent its contents.
These elements are read-only because changing their properties would mean
the logical model would no longer be in sync with the content of the original
WSDL document.
335
Properties, relationships and classifications allow a user to annotate the objects

within WSRR with service metadata.
This service metadata can then be used both internally, by WSRR, and externally
by clients extracting information from WSRR.
Properties within WSRR are modelled as String properties on the underlying
SDOs and so consequently the properties are shown as simple name/value
pairs.
Within the SDO property names must be unique. Therefore, it is not possible to
define a property or relationship on an object if a property or relationship of the
same name already exists on that object.
9.4.1 Adding a new custom property

To add a new custom property to the StockQuote.wsdl we just loaded follow
these steps.
1. Navigate to the document and then click Custom Properties as shown in
Figure 9-7.
Figure 9-7 Document custom properties link
336
2. The list of current properties on the document will then appear. Clicking on
the name of any of the existing properties will allow you to edit the value of
that property. Some of the properties are compulsory, and so the delete check
box next to those properties is greyed out.
At the top of this list is a New button as shown in Figure 9-8. Click New.
Figure 9-8 Document custom properties
337
3. You will then be prompted for a Key and Value for the new custom property.
Enter your desired values for these fields as demonstrated in Figure 9-9.
Then click OK.
Figure 9-9 Entering values for the new custom property
338
4. The new property has now been added and you should see it in the list of
properties, as shown in Figure 9-10.
Figure 9-10 The newly added custom property
339
It is also possible to add the same custom property to multiple documents at

once from the collective view. Select the check box for all the desired documents
in the collective view and then click the Add Property button as shown in
Figure 9-11.
Figure 9-11 Adding custom properties to multiple documents
9.4.2 Editing a property

To edit a property, whether it is a predefined property or a custom property, follow
these steps.
340
1. From the documents details page select Custom properties from the
Additional properties links on the right, as highlighted in Figure 9-12.
Figure 9-12 Custom properties link
341
2. Click the name of the property you want to edit. In Figure 9-13 we are going to
edit the value of the ServiceLevel custom property.
Figure 9-13 Selecting a property to edit
342
3. Change the value of the property to whatever you want it to be and then click
OK (see Figure 9-14).
Figure 9-14 Edit property value
343
4. You should then be able to see the new value for the property in the
properties list as shown in Figure 9-15.
Figure 9-15 Edit property result
9.4.3 Deleting a custom property

Predefined properties cannot be deleted. However, to delete a custom property
follow these steps.
344
1. From the documents details page select Custom properties from the
Additional properties links on the right, as highlighted in Figure 9-16.
Figure 9-16 Custom properties link
345
2. Select the check box for the custom property you want to delete and then click
the Delete button as highlighted in Figure 9-17.
Figure 9-17 Delete custom property
3. You should now get a confirmation message that the property was deleted as
346
Figure 9-18 Delete custom property result
9.5 Relationships
Relationships, similar to properties, allow users to annotate objects in WSRR
with service metadata.
They are modelled within WSRR as List properties on the underlying SDOs.
They are 1:many (1 source object, many target objects) and are uni-directional.
The object on which the relationship is defined is the source object of the
relationship.
The relationship property contains the list of WSRR objects that are the target of
the relationship.
9.5.1 Creating a new relationship

To create a relationship follow these steps.
1. Select the document to create the relationship from.
2. From that documents details view select the Custom relationships link from
the Relationships links on the right. This is highlighted in Figure 9-19 on
page 348.
347
Figure 9-19 Custom relationships link
3. Click New in the custom relationships window as shown in Figure 9-20 on

page 349.
348
Figure 9-20 Create new custom relationship
It is also possible to add a new relationship to multiple documents at once

using the Add relationship button on the document collective view as shown
349
Figure 9-21 Add a relationship to multiple documents
4. The custom relationship wizard should now open. Enter a name for the
relationship and click Next as shown in Figure 9-22 on page 351.
350
Figure 9-22 New relationship - relationship name
5. You will now need to find the document(s) to create a relationship to. Select
the type of document to query for and then click Next (see Figure 9-23).
Figure 9-23 New relationship - query document type
6. You now need to enter the search criteria to find the specific documents to
create a relationship to. You can query by different criteria, in our case we
knew the name of the document Address.wsdl and so typed that in the
Name field, as shown in Figure 9-24 on page 352. Click Next once you have
entered the desired search criteria.
351
Figure 9-24 New relationship - query document details
7. It will now display the results of your search query. You can now select the
precise documents you want to create a relationship to. Check the check box
next to the desired target document and click Next. (See Figure 9-25 on
page 353.)
352
Figure 9-25 New relationship - select document
8. You will now see a summary of the proposed new relationship as shown in
Figure 9-26. If all the details seem correct then click Finish.
Figure 9-26 New relationship - summary
353
9. The relationship has now been created and you should see output similar to
that in Figure 9-27.
Figure 9-27 New relationship - result
9.5.2 Editing an existing relationship

Once a relationship has been created, it is only possible to add or remove target
objects from it.
To do this, follow these steps:
1. From the source documents detail view click Custom relationships as
highlighted in Figure 9-28 on page 355.
354
Figure 9-28 Custom relationships link
2. When the custom relationships list appears, click the name of the relationship
you want to edit, as shown in Figure 9-29 on page 356.
355
Figure 9-29 Edit relationship - select relationship
3. You will then be displayed with the list of current targets for that relationship
similar to Figure 9-30. To add a new target click the Add button and you will
then have to follow a similar process to that used to find the target of the
relationship when creating a new relationship in 9.5.1, Creating a new
relationship on page 347. The main differences are that you cannot specify
the relationship name and you must specify a target object.
To remove a target, check the check box next to that target and click the
Remove button.
Figure 9-30 Edit relationship - targets
356
9.5.3 Deleting a relationship

1. To delete an existing relationship navigate to the relationships collection view
on the relevant object and then check the check box next to the relationship
you want to delete and click Delete. This is shown in Figure 9-31.
Figure 9-31 Delete relationship
2. You should now see a confirmation message similar to that in Figure 9-32.
Figure 9-32 Delete relationship result
357
9.6 Classifying objects

Classifications can be used to make finding objects easier and to add meaning to
entities unique to a customers environment. They are defined as OWL files (Web
Ontology Language).
It is possible to import user-defined OWL files, however this operation can only
be performed by a WSRR Administrator.
Classifications currently support simple hierarchies or parents and children and
are modelled as list properties on the classified entity.
9.6.1 Loading an OWL file

This task can only be performed by WSRR Administrators.
1. Select Load classification system from the navigator under Classification
Systems (highlighted in Figure 9-33).
Figure 9-33 Load classification link
2. You will then be prompted for the path to the OWL file. Either type in the path
to your OWL file or browse until you find it. Then click OK. (See Figure 9-34
on page 359.)
358
Figure 9-34 Load classification
3. Once the classification has been loaded you should see a confirmation
message similar to that displayed in Figure 9-35.
Figure 9-35 Load classification result
9.6.2 Browsing classifications

In order to see the available ontologies use the following steps.
359
1. Select Browse classification systems from the Classification systems

section of the navigation pane as highlighted in Figure 9-36.
Figure 9-36 Browse classifications link
2. You should then see a tree structure representing all of the loaded ontologies
as shown in Figure 9-37.
Figure 9-37 Classifications tree structure
360
9.6.3 Removing a classification

To remove a classification follow these steps:
1. Select Browse classification systems from the Classification systems section
of the navigation pane as highlighted in Figure 9-36 on page 360.
2. Check the check box for the classification tree you want to delete and then
click the Delete button, as shown in Figure 9-38.
Figure 9-38 Delete classifications
3. You should then get confirmation the classification was deleted.
9.6.4 Classifying an entity

To classify an object in WSRR follow these steps:
1. Browse to the detail view of the entity you want to classify
2. Select Classifications from the Relationships links on the right-hand side as
highlighted in Figure 9-39 on page 362.
361
Figure 9-39 Classifications link
3. Select the classification you want to classify this entity as, from the tree
structure on the left and then click the Add button. This is shown in
362
Figure 9-40 Add classifications to an entity
4. You should now see your added classification in the Classification List box
on the right. Click the OK button.
Note: Multiple classifications can be added at the same time, just keep
selecting classifications from the tree on the right and click the Add button.
5. Your classification has now been added and you should have been returned
to the detail view for the entity.
9.7 Searching the registry

The query wizard allows queries based on the following criteria:
Different specific types of entity
All entity types
Entity name
363
Custom property name or value

Classifications
Some entity property (for example, namespace)
AND or OR queries
To use the query wizard follow the example.

In this example we will search for the document that we added the classification
to in 9.6.4, Classifying an entity on page 361.
1. Select Query wizard from the navigation pane under Queries as highlighted
in Figure 9-41.
Figure 9-41 Query wizard link
2. Select the type of query from the drop down list shown in Figure 9-42 on
page 365. For the purposes of this example we will query by classification,
and so we selected Entities by Classification. Then click OK.
364
Figure 9-42 Select the type of query
3. The query wizard window should appear as shown in Figure 9-43 on

page 366. We will leave the query set to use AND and leave the Name field
blank. Check the Match children check box and then click the Choose
button.
365
Figure 9-43 Query by classification
4. The classification wizard will then appear as shown in Figure 9-44 on

page 367. In order to demonstrate the match children field working we will
select the parent of the classification we used in 9.6.4, Classifying an entity
on page 361. Then click the Add button and then the OK button.
366
Figure 9-44 Select the classification to query for
5. You should now see the classification you selected in the list box on the query
wizard screen, as shown in Figure 9-45 on page 368. Click Next.
367
Figure 9-45 Query wizard after selecting classification
6. The query wizard will now display a summary of the query to be run (see
Figure 9-46 on page 369). Click Finish.
368
Figure 9-46 Query wizard summary
7. The query results should now be displayed. Figure 9-47 shows an example of
the results screen.
Figure 9-47 Query wizard results
9.8 Deleting artefacts

To delete a document from WSRR use the following steps.
369
1. First you must navigate to the collection view for the type of document you
want to delete.
2. Then select the check boxes next to the document that you want to delete and
click the Delete button as shown in Figure 9-48.
Figure 9-48 Delete a document
3. You should then receive a confirmation message to state the document was
deleted from WSRR.
9.9 Concepts
WSRR models the content of the artefacts that it stores. However, it is possible
you will want to work with business objects that do not exactly match those
370
defined within WSRR. These could include MQ endpoints, capabilities, verbs,

and so on.
It is not possible for WSRR to model all possible business objects that might be
required. Concepts provide a way of modelling the business objects that you
might need to represent within an SOA environment.
Note: Concept is the Web UI term for GenericObject.
9.9.1 Defining a concept template

WSRR used XML schema complex types to define the structure of the concepts.
The complex type acts as a template when creating an instance of the concept.
In the XML an attribute of type string defined on the complex type results in a
custom property being added to the new concept.
If an attribute of type IDREFS is defined on the complex type then a custom
relationship will be added to the new concept.
As an example, the Application complex type shown in Example 9-1 defines a
businessOwner attribute of type string and referencedServices and
referencedProcesses attributes of type IDREFS.
Example 9-1 Example concept complex type definition
<xsd:complexType name=Application>
<xsd:attribute name=businessOwner type=xsd:string />
<xsd:attribute name=referncedServices type=xsd:IDREFS />
<xsd:attribute name=referencedProcesses type=xsd:IDREFS />
</xsd:complexType>
Creating a new concept instance using the Application template would result in a
new concept with the following metadata associated with it:
A custom property called businessOwner
A custom relationship called referencedServices
A custom relationship called referencedProcesses
9.9.2 Classifying a complex type as a template

A complex type that can be used to create instances of concepts must first be
classified as a template within WSRR.
371
The Template classification is provided within WSRR as part of the WSRR Core
Ontology as shown in Figure 9-49.
Figure 9-49 Template classification
To classify a complex type as a Template follow the instructions in 9.6.4,

Classifying an entity on page 361 but use the Template classification.
9.9.3 Viewing templates

The templates that have been defined in WSRR can be viewed by selecting the
Templates link from the navigation pane as highlighted in Figure 9-50.
Figure 9-50 List templates link
372
This will then display a screen similar to that shown in Figure 9-51, displaying a
list of the templates currently available in WSRR.
Figure 9-51 List of available templates
Clicking on an individual template will display the details for that specific template
as shown in Figure 9-52 on page 374.
373
Figure 9-52 Template details view
9.9.4 Creating a concept from a template

To create a new instance of a concept follow these steps:
1. Select Templates from the navigation pane as shown in Figure 9-53 on
page 375.
374
Figure 9-53 Templates link
2. Select the Template you want to use for the new concept instance. Click the
Create new instance button as shown in Figure 9-54.
Figure 9-54 Create new instance from a template
375
3. Fill in the fields as necessary for your template and then click OK. The
example shown in Figure 9-55 is based on the JMSEndpoint template created
by the WMB V6 Client for WebSphere Service Registry and Repository.
Figure 9-55 New instance of a template - details
4. Your new instance should now have been created. The next section will
explain how to view the details on it.
Custom properties that will be added by the template are shown in a separate
section below the General Properties. Custom relationships defined by the
template are not shown until after the new concept instance has been created.
376
As a result, targets for the custom relationships cannot be defined during

creation.
9.9.5 Viewing the details of a concept

1. To view details of a concept click the Concepts link on the navigation pane as
Figure 9-56 Concepts link
2. The concepts collection view will then display

3. Then click the concept you want to see the details of. You should then see the
details of that concept. For instance, Figure 9-57 on page 378 shows the
details for the concept we created in 9.9.4, Creating a concept from a
template on page 374.
377
Figure 9-57 Details of a concept
9.9.6 Deleting a concept

1. To delete a concept click the Concepts link on the navigation pane, as shown
2. From the concepts collection view, select the concepts you want to delete and
then click the Delete button, as highlighted in Figure 9-58 on page 379.
378
Figure 9-58 Delete a concept
3. You should then receive confirmation the concept was deleted.
379
380
10
Chapter 10.
Customizing the Web UI

This chapter discusses how to customize the WSRR Web user interface (Web
UI). It will use the sample scenario provided with the WMB V6 Client for
WebSphere Service Registry and Repository SupportPac as a demonstration
of some of the capabilities.
This chapter describes the following:
10.2, View query definitions on page 382
10.3, Navigation trees on page 390
10.4, Perspectives on page 394
10.5, Collection views on page 401
10.6, Managing UI customization configurations on page 411
381
10.1 Introduction
As covered in 4.3, Web user interface (Web UI) on page 144, WSRR provides
extensive customization capabilities for its user interface. These customization
capabilities range from simply modifying the properties that are displayed on an
existing view of a service to deploying a whole new perspective that defines new
views for the information stored in Service Registry and Repository. This new
perspective may be specific to a certain kind of user within your organization,
using terminology that the user can understand and restricting the information
displayed to the minimum that allows the user to perform their day-to-day job.
Section 4.3, Web user interface (Web UI) on page 144 describes the concepts
and architecture of the WebSphere Service Registry and Repository Web user
interface.
This chapter goes into more detail on the underlying technology powering that
flexibility and how you can customize it for your own needs. For demonstration
purposes we will use the example scenario that comes with the WebSphere
Message Broker V6 Client for WebSphere Service Registry and Repository
SupportPac. The scenario is described in more detail in 16.7, WMB Client
support for SOA patterns on page 803. We will describe how to perform the
customizations necessary for that scenario, however the UI customization files
necessary for it are actually provided with the SupportPac in the following
directory:
<WMBClient_Install>\Tests\WSRRTestEntities\GUIConfiguration
Where <WMBClient_Install> is the directory the WMB V6 Client for WebSphere
Service Registry and Repository is installed to.
10.2 View query definitions

The WSRR view query system is a highly customizable method of creating
predefined queries against the contents of the registry. It uses a simple XML file
that defines the parameters of each query, associating that query with a unique
identifier. These queries then form the main method of providing links from the
navigation tree to show relevant views in the user interface. Users can customize
existing or new navigation trees in the UI by defining additional view queries in a
new view query definition file and then referencing the new queries in the
navigation tree.
This chapter will describe how to understand and create view query definition
files and will go on to describe how to apply those view queries to a custom
navigation tree as part of a custom perspective view.
382
View query definitions allow you to perform a rich set of queries against just
about any type of object that WSRR can store. The possible parameters include
object type, classifications, properties and relationships, all of which can be used
in any combination. This covers all three categories of metadata that WSRR
supports so should allow the maximum flexibility to find the required objects in
the registry.
Let us begin with a simple view query which we can build on to explain other
features. In Example 10-1 the XML namespace attributes are listed for
informational purposes, however they will be omitted from the later examples in
this chapter for the sake of clarity.
Example 10-1 Basic view query
<ViewQueryDefinitionSet
xmlns="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ViewQueryDefin
itionSet"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ViewQueryDefinitionS
et ../../schemas/ViewQueryDefinitionSet.xsd">
<QueryDefinitions>
<Query id="showWSDLs">
<ObjectType>WSDLService</ObjectType>
</QueryDefinitions>
</ViewQueryDefinitionSet>
Each view consists of a separate Query element that is contained within the
QueryDefinitions element. There is no limit to the number of queries that can be
defined except for physical storage since each one will be represented in
memory at startup. Each query must have a unique ID represented as the id
attribute within the Query element. It is recommended that the query ID start with
a short prefix so as to minimize the chances of a name conflict with other view
query definitions already defined in the system. Note that there is one exception
to the unique ID rule; it is possible to override an existing system-defined view
query with a user-defined one by creating the user view query with the same ID.
This should only be used with caution since changing a system view query could
affect the expected operation of the default perspective views.
The query in Example 10-1 returns all WSDLService objects currently stored in the
registry and introduces the ObjectType element. The object type is an optional
element that filters the query to return only objects of the given type. The type
can only be chosen from a fixed list of types that correspond to the Service Data
Objects (SDO) types currently supported for querying in the registry. Table 10-1
on page 384 shows the list of valid object types that can be used.
Chapter 10. Customizing the Web UI
383
Table 10-1 Valid object types
384
Object type
Description
WSDLDocument
WSDL document
XMLDocument
XML document
XSDDocument
XML schema definition document
PolicyDocument
Policy document
GenericObject
Generic object (displayed as Concept in the UI)
WSDLBinding
WSDL binding logical object
WSDLMessage
WSDL message logical object
WSDLOperation
WSDL operation logical object
WSDLPart
WSDL message part logical object
WSDLPort
WSDL port logical object
WSDLPortType
WSDL port type logical object
WSDLService
WSDL service logical object
SOAPAddress
SOAP address logical object
SOAPBinding
SOAP binding logical object
XSDAttribute
XSD attribute logical object
XSDComplexType
XSD complex type logical object
XSDSimpleType
XSD simple type logical object
XMLElement
XML element logical object
SCAModule
SCA module container
ModuleDocument
(SCA) module document
ImportDocument
(SCA) import document
ExportDocument
(SCA) export document
Module
(SCA) module logical object
Import
(SCA) import logical object
Export
(SCA) export logical object
SCAImportBinding
SCA import binding logical object
Object type
Description
SLSBImportBinding
(SCA) Stateless session bean import binding logical

object
WebServiceImportBinding
(SCA) Web service import binding logical object
SCAWSDLPortType
SCA WSDL port type logical object
SCAExportBinding
SCA export binding logical object
WebServiceExportBinding
(SCA) Web service export binding logical object
Subscription
Subscription object
Note: GenericObject is the API name for the objects that appear in the Web
UI as Concepts.
The ObjectType element is not a required setting - omitting the value will
cause the query to consider all searchable registry objects as part of the query
(that is, all objects that derive from the BaseObject SDO parent class).
10.2.1 Using alternative views

The query in Example 10-1 on page 383 will use the default collection view
definition for a WSDLService object, however we can choose to use a different
view to display the results of the query. In our example WMB Patterns scenario,
we have some extra properties being stored in our endpoints and it would be
helpful to display those new values in the query results views. This is achieved
using the DisplayType element as shown in Example 10-2 (an XML snippet
taken from MBPatternViewQueryDefinition.xml as supplied in the WMB V6 Client
for WebSphere Service Registry and Repository). Example 10-2 is querying by
classification not ObjectType, this is explained in 10.2.4, Querying by
classification on page 387, but does not affect how using alternative views
works.
Example 10-2 Using alternative views
<ViewQueryDefinitionSet>
<QueryDefinitions>
<Query id="showEndpoints">
<DisplayType>MBPatternEndpoint</DisplayType>
<QueryClassificationsAnyOf>
<ClassificationURI>
http://eis.ibm.com/ServiceRegistry/GenericObjectTypes#Endpoint</Classif
icationURI>
385
</QueryClassificationsAnyOf>
</Query>
</QueryDefinitions>
The DisplayType element instructs the Web UI to use a different view definition
to display the results of the query. This view definition is referenced by its unique
ID which is mapped to a collection view definition in the perspective definition file.
More detailed information about how to create perspectives and view definitions
can be found in 10.4, Perspectives on page 394.
10.2.2 Querying by property

The view query system has support for querying by property using the Property
element. The Property element has two attributes that specify the name and
value of the property being queried. Each one is an exact match test, that is,
there are no wild cards permitted in the name and value. Example 10-3 shows an
example which we could use in the WMB Pattern scenario.
Example 10-3 Querying by property
<QueryDefinitions>
<Query id="showJMSEndpoints">
<DisplayType>MBPatternEndpoint</DisplayType>
<Property name="endpointtype" value="JMS"/>
</Query>
</QueryDefinitions>
In this example the query is looking for all objects that contain a property called
endpointtype that has an exact value of JMS. It's also possible to omit either
one of name or value to widen the search. Omitting the value attribute will
change the query such that it will now search for all objects of the given type that
contain a property of the given name regardless of the value. Similarly, omitting
the value attribute will change the meaning of the query such that it will now
search for all objects of the given type that contain any property that has the
given value as an exact match.
10.2.3 Querying by relationship

Querying by relationship allows you to find objects in the registry specifically by
their relationship to another object. This uses the Relationship element and its
associated Target child element. A typical usage of this is when using templated
386
objects to ensure that the objects found in the search are of the correct templated
type. Example 10-4 shows the syntax of just such a query:
Example 10-4 Querying by relationship
<QueryDefinitions>
<Query id="MBViewJMSTemplated">
<ObjectType>GenericObject</ObjectType>
<Relationship name="template">
<Target>
<Property name="name" value="JMSEndpoint"/>
</Target>
</Relationship>
</Query>
</QueryDefinitions>
This query reads as find all the generic objects that have a relationship called
'template' where the target object of that relationship has a name of
'JMSEndpoint'. This introduces several new elements to the query. Firstly, the
Relationship element which declares that the query is looking for a relationship
on the objects of the given type. This has one optional attribute that gives the
specific name of the relationship to look for which can be either a modelled
relationship or a user-defined relationship. This is an exact match test and wild
cards are not expanded in the value. Omitting the name of the relationship
means the query will look for target objects for any relationship on the initial list of
objects filtered by the given type.
The Relationship element can contain a Target child element that directs the
query to consider the objects that are at the target of the relationship. The Target
element must contain exactly one Property element declaring which name/value
pair to look for on the target object. It is not possible to specify more than one
property to look for when considering the target objects of a relationship. The
rules for the Property element when used within a target object search are
exactly the same as when they are used in the main body of the query. The
Target element is optional - omitting it means that the query will be widened to
search purely for objects that have the named relationship.
10.2.4 Querying by classification

The view query system has four different elements to cover all the ways that
classifications can be used as part of a query. Each of these elements then
contains any number of ClassificationURI elements that build up a list of
classifications to search for. Classifications are specified as the fully qualified
387
OWL URI from the classification system that was used to classify the object.
Searches involving classifications that have child OWL URIs in the classification
system (that is, there are additional classifications that are a subClassOf the
given URI in OWL terms) can additionally be used such that the URI given and all
of its inferred child URIs are also considered as part of the search. For example a
classification search on Fruit with inference would also consider Apple and
Orange as additional classifications as part of the search. Table 10-2 shows the
four elements and their behavior.
Table 10-2 Classification elements
Element
Meaning
QueryClassificationsAnyOf
Find objects that are classified by any of the given

URIs and additionally consider any inferred child
URIs from each URI in the initial list.
QueryClassificationsAllOf
Find objects that are classified by all of the given

URIs and additionally consider any inferred child
URIs from each URI in the initial list.
QueryExactClassificationsAnyOf
Find objects that are classified exactly by any of

the given URIs without using inference.
QueryExactClassificationsAllOf
Find objects that are classified exactly by all of the

given URIs without using inference.
For our example WMB Patterns scenario we use a simple OWL file to classify
services. It is used to mark services as a particular type and impose a hierarchy
where JMSEndpoint, MQEndpoint and URLEndpoint are all children of Endpoint.
Example 10-5 shows a snippet from the OWL file used. The complete file can be
found here:
<WMBClient_Install>\Tests\WSRRTestEntities\Classifications\GenericObjec
tTypes.owl
Example 10-5 Sample OWL file
<?xml version="1.0"?>
<rdf:RDF
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns="http://eis.ibm.com/ServiceRegistry/GenericObjectTypes#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xml:base="http://eis.ibm.com/ServiceRegistry/GenericObjectTypes">
<owl:Ontology rdf:about="">
388
<rdfs:label
rdf:datatype="http://www.w3.org/2001/XMLSchema#string">MB Nodes Concept
Types</rdfs:label>
</owl:Ontology>
<owl:Class rdf:ID="Endpoint">
<rdfs:label
rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Endpoint</rdfs:l
abel>
</owl:Class>
<owl:Class rdf:ID="JMSEndpoint">
<rdfs:label
rdf:datatype="http://www.w3.org/2001/XMLSchema#string">JMSEndpoint</rdf
s:label>
<rdfs:subClassOf rdf:resource="#Endpoint"/>
</owl:Class>
<owl:Class rdf:ID="URLEndpoint">
<rdfs:label
rdf:datatype="http://www.w3.org/2001/XMLSchema#string">URLEndpoint</rdf
s:label>
</owl:Class>
<owl:Class rdf:ID="MQEndpoint">
<rdfs:label
rdf:datatype="http://www.w3.org/2001/XMLSchema#string">MQEndpoint</rdfs
:label>
</owl:Class>
</rdf:RDF>
In our WMB Patterns scenario we use a view query using classifications to show
the MQEndpoints as shown in Example 10-6.
Example 10-6 Querying by classification
<QueryDefinitions>
<Query id="showMQEndpoints">
<DisplayType>MBPatternMQEndpoint</DisplayType>
<ClassificationURI>
http://eis.ibm.com/ServiceRegistry/GenericObjectTypes#MQEndpoint</Class
ificationURI>
</Query>
</QueryDefinitions>
389
View queries are restricted to allowing just one classification-type element per
query, chosen from the list of four available. Finding the fully qualified OWL URI
for a classification value can sometimes be tricky even if you have access to the
source of the OWL document. There is a simple procedure that can be used in
the Web UI that will allow you to find the full URI of any classification value. In the
Web UI, navigate to any object either in a collection view or detail view. From a
collection view, select the object from the list and click Add classifications, or
from a detail view, click the Classifications link in the relationships section. Note
that you do not need to update the object with new classifications, this is purely to
get a specific view in the Web UI. Once in the classifications view, the full OWL
URI of any classification value can be obtained by selecting the classification in
the classification list which then shows the full details of that value in the table at
the bottom of the page. The URI can then be copied and pasted from the Web UI.
If the classification value is not in the list, then it can be added to the list by
browsing the tree, selecting the value and clicking the Add button. If you are not
intending to update the classifications on the object, remember to click the
Cancel button when complete.
10.3 Navigation trees

In the WSRR Web UI, the navigation tree is always available on the left side of
the page and acts as the table of contents for the current perspective view. As
part of customizing the UI, this is where you decide which views will be useful for
the target audience of the perspective. A well designed navigation tree will allow
you to find the information you need quickly and with only a few mouse clicks.
This section will explain how to create a custom navigation tree and how the
navigation tree definition file and the view query definition file combine to form
the completed navigation tree. Figure 10-1 on page 391 shows the example
navigation tree that forms part of the scenario for this chapter.
390
Figure 10-1 Example navigation tree
The navigation tree for our WMB Patterns scenario introduces a completely new
top-level grouping called Message Broker Pattern Metadata which collects
together all the custom views that we need for monitoring the services in the
registry. It also re-uses the query wizard, classification, and other sections from
the default navigation trees supplied with WSRR.
Built-in standard features

The navigation tree has a link to the welcome page and a quick search box that
are shown at the top of the navigation tree pane. These are always present and
cannot be configured or customized through the navigation view definition or the
view query definition files.
Figure 10-2 on page 392 shows how the navigation tree definition combines with
the view query definitions to form the final view.
391
Navigation tree
Navigation tree definition

<node id="routers"
node-resource-key="mbpattern.navigationtree.routers"
node-resource-bundle="MBPatternResources"
view-query-id="showRouters"/>
View query
definition
<Query id="showRouters">
<DisplayType>MBPatternRouter</DisplayType>
<ClassificationURI>http://eis.ibm.com/ServiceRegistry/GenericObject
Types#Router<ClassificationURI>
</Query>
Figure 10-2 Linking navigation tree and view query
The diagram shows that there are two parts to each node definition in the
navigation tree. The display part is a resource key (and optional resource bundle)
that defines the text to be displayed for the node in the tree, and the link part that
defines what action will be performed when you click the link in the tree. In our
example, the link runs the view query specified by the view query ID in the
navigation tree node.
Example 10-7 shows part of the navigation tree definition file used to display the
tree for the sample scenario.
Example 10-7 Example navigation tree

<NavigationTree
xmlns="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/Navigation
TreeDefinition"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/serviceregistry/6/
0/NavigationTreeDefinition ../../schemas/NavigationTree.xsd"
392
name="MBPatternUserNavigationTree">
<node id="navtree_root"
node-resource-key="navigationtree.service.registry">
<node id="mbnodes"
node-resource-key="mbpattern.navigationtree.title"
node-resource-bundle="MBPatternResources">
<node id="routers"
node-resource-key="mbpattern.navigationtree.routers"
node-resource-bundle="MBPatternResources" view-query-id="showRouters"/>
...
</node>
...
<node id="queries"
node-resource-key="navigationtree.service.queries">
<node id="qwizard"
node-resource-key="navigationtree.service.queries.wizard"
forward="QueryWizardPrepare"/>
</node>
...
</node>
</NavigationTree>
The enclosing NavigationTree element has just one attribute name that must be
unique within the context of all navigation trees within WSRR. This name is used
directly by the perspective definition file to declare which navigation tree to use.
There is only one other element node used to construct the navigation tree. Node
elements can be nested to any depth and will form the tree hierarchy in the
navigation pane of the Web UI. The outer-most node with the ID of navtree_root
must be present in the definition file - it doesn't get displayed but acts as the
container for all the displayable nodes. The first level nodes under the root node
form the main content sections of the tree and are highlighted as main headings
in the navigation pane. Content sections cannot be set as links to views, they
only serve to contain other nodes and are always displayed in the navigation
pane.
The node element has just two required attributes: id which must be unique
within the navigation definition file and node-resource-key which defines the key
to use in the resource file for the display text for the node. To go with the resource
key there is the optional node-resource-bundle attribute that lets you specify a
different resource file to load display text from. If this is omitted, then the resource
bundle defaults to the built-in resources used by the Web UI. Any user-supplied
resource properties file must be available on the WAS classpath - in the default
profile the easiest directory to use would be
<WAS_HOME>/profiles/default/classes.
393
There are two ways to specify the way the active link works when using the node
element. The main way is to use the view-query-id attribute and specify its value
as the ID of a view query stored in a view query definition file. View query links
are typically used to display collections of objects stored in the registry, however
not every possible view or action in WSRR can be represented by a view query
so there is a second attribute forward that can be used to forward to the special
view, wizard or action. Table 10-3 details exactly what forwards can be used and
what action they perform.
Table 10-3 Special navigation forwards
Forward
Action performed
LoadDocument
Displays the load document page
QueryWizardPrepare
Displays the first page of the query wizard
LoadClassificationSystem
Displays the load classification system page administrator task only
BrowseClassificationSystem
Displays the available classification systems in a

browsable tree view
ListMySubscriptions
Displays the subscriptions specifically for the current

user
ListMyFavourites
Displays the list of favorites for the current user
ShowPreferences
Displays the UI preferences for the current user
ImportDocuments
Displays the first page of the import documents wizard

for importing a WSRR export file - administrator task
only
10.4 Perspectives
Perspectives are used in the WSRR Web User Interface to provide a user role
the appropriate view of the data and the ability to perform their tasks. The
Administrator perspective allows you to load classification systems and import
data among other tasks. The User perspective lets you browse the classification
system, load documents and browse the artefacts in the Service Registry and
Repository. The perspective developed for the WMB Patterns scenario shows
metadata relevant to their business.
In order to show the WMB Patterns scenario metadata, we have created a
custom MB Pattern User perspective which shows the navigation tree from
Figure 10-1 on page 391 and their services' operational and static metadata in
collection and detail views.
394
A perspective definition describes the title of the perspective, the navigation tree,
which user roles are permitted to use the perspective, and which collection and
detail views are to be shown. Figure 10-3 shows the MB Pattern User
perspective starting page.
Figure 10-3 The MB Pattern User perspective
10.4.1 A skeleton perspective definition

A skeleton perspective file is shown in Example 10-8. The perspective definition
name is blank, there are placeholders for the title, roles and navigation tree, and
no mappings.
Example 10-8 Skeleton perspective definition

<perspective-definition
perspective-definition-name="" weight="0"
xmlns=
"http://www.ibm.com/xmlns/prod/serviceregistry/6/0/PerspectiveDefinitio
n"
xsi:schemaLocation=
n
../../schemas/PerspectiveDefinition.xsd ">
395
<title-message message-key=""/>
<roles>
<role>role</role>
</roles>
<navigation-tree-name>navigation-tree-name</navigation-tree-name>
<detail-view-mappings/>
<collection-view-mappings/>
</perspective-definition>
10.4.2 Adding name, title and roles

Every perspective has a name, which is independent of the definition file name.
This name is only used by the WSRR internally. For our MB Pattern User
perspective we use the name MBPatternUser. Because definitions are stored by
their file name, we recommend always using the definition name as the file name.
In our case, the perspective is stored in a file called
MBPatternUserPerspectiveDefinition.xml.
The title message which appears in the perspective drop-down is defined using a
resource bundle key name. By default this key is resolved using the WSRR Web
UI resource bundle which is not customizable. The attribute
resource-bundle-name is used to specify a different resource bundle which you
provide. In this example, we use the resource bundle MBPatternResources for all
messages.
Definition name uniqueness

The perspective definition name is a unique key which identifies the definition
among other definitions of the same type. Every perspective definition must have
a unique name among perspectives. We therefore advise using a prefix for all of
your definitions.
Resource key uniqueness

A resource key must be unique within its resource bundle. By specifying a
different resource bundle, your resource keys only need to be unique within that
bundle.
As discussed in 4.3.2, Perspectives on page 147, each perspective specifies a
set of permissible user roles which can access the perspective. A user needs to
be in one of these roles to use the perspective. Because we want all users to be
able to view the MB Pattern User perspective, we specify only one entry of User.
In the MB Pattern User perspective file MBPatternUserPerspectiveDefinition.xml
the perspective definition has a definition name, title and role added, as shown in
396
Example 10-9. The file MBPatternUserPerspectiveDefinition.xml can be found in

the following folder:
Example 10-9 Perspective name, title and a role

perspective-definition-name="MBPatternUser" weight="40"
xmlns=
n"
xsi:schemaLocation=
n
<title-message message-key="mbpattern.perspective.display.name.user"
resource-bundle-name=MBPatternResources/>
<roles>
<role>User</role>
</roles>
...
10.4.3 The navigation tree and weight

A perspective has a single navigation tree which is shown in the navigation pane
when the perspective is active. The navigation-tree-name element specifies the
name of the navigation tree to use, as defined in the navigation tree definition
XML file. In 10.3, Navigation trees on page 390 we showed the navigation tree
developed for the WMB Patterns scenario which groups services according to
endpoint type, called MBPatternUserNavigationTree. We want this to be the
navigation tree for our perspective.
Each perspective has a weight which defines the weight of the perspective
relative to others within the WSRR user interface. When a user logs into the
WSRR Web UI, the perspective with the highest weight is used as the current
perspective. The weight of the MB Pattern User perspective will be 40.
Two perspectives are provided with the WSRR user interface. The Administrator
perspective has a weight of 100 and the User perspective has a weight of 70.
Therefore the Administrator perspective is the default. If you want your
perspective to be the default one, give it a weight greater than 100.
397
Example 10-10 shows the MB Pattern User perspective definition which specifies
a weight of 40 and a navigation tree called MBPatternUserNavigationTree.
Example 10-10 Perspective weight and navigation tree

perspective-definition-name="MBPatternUser" weight="40"
xmlns=
n"
xsi:schemaLocation=
n
<title-message message-key="mbpattern.perspective.display.name.user"
resource-bundle-name=MBPatternResources/>
<roles>
<role>User</role>
</roles>
<navigation-tree-name>MBPatternUserNavigationTree</navigation-tree-name
>
...
10.4.4 Collection and detail view mappings

Required mappings
A perspective contains a set of mappings for collection and detail views. They
map between a display type name and the definition name of a view. Whenever a
view is needed, it is looked up in the current perspective using the mappings.
This is significant in several ways.
Firstly, whenever the WSRR user interface displays an entity, it is actually
showing a Service Data Object (SDO) instance from the WSRR API. Each
different type of entity within WSRR is represented by a different type of SDO,
each SDO type has a distinct type name. By default, when the WSRR user
interface displays an entity, it uses the SDO type name as the display type and
looks up a detail view definition in the current perspective.
Therefore, to show an entity such as a WSDL Document or WSDL Service, a
mapping for the display type WSDLDocument or WSDLService must be in the
current perspective. This applies to all SDO types in WSRR; they must all have a
398
detail view mapping to be displayed. Consequently there is a list of detail view

mappings which should be present in all perspective definitions, if you want to be
able to display all entities.
Secondly the WSRR detail views link to collection views of related entities, such
as the WSDL ports of a WSDL document. The query wizard also uses a set of
collection views to display results, the quick search box uses a specific collection
view to display results, and the classification browser uses a specific collection
view. Consequently there is a list of collection view mappings which should be
present in all perspective definitions, for non-customizable parts of the user
interface to use.
Thirdly any of the views used by the WSRR user interface can potentially be
overridden to specify your own detail and collection views. You can also use
entirely unique names to identify your new views, then refer to these names
within collection and detail view definitions.
The complete MB Pattern User perspective definition in the
<WMBClient_Install>\Tests\WSRRTestEntities\GUIConfiguration directory
contains all the necessary mappings. These are the mappings present in the
WSRR User perspective. To copy the mappings directly, you can extract the User
perspective definition from WSRR using the administration interface. See
Chapter 8, Administering WSRR on page 281 for more details.
Customized mappings
We have developed several collection views detail views for the WMB Pattern
scenario. These views show the static and operational metadata of interest to the
scenario. In order to use them from view queries and collection views, these
views must be added to the mapping sections.
To add mappings for our new collection views, the collection-view-mappings
element has several view-mapping elements added. These map between the
display type names used in the view queries in 10.2, View query definitions on
page 382 and our collection views. The mappings are shown in Example 10-11.
Example 10-11 New collection view mappings
<collection-view-mappings>
<view-mapping display-type="MBPatternRouter"
view-definition-name="MBPatternRouter" />
<view-mapping display-type="MBPatternTranscoder"
view-definition-name="MBPatternTranscoder" />
<view-mapping display-type="MBPatternEndpoint"
view-definition-name="MBPatternEndpoint" />
<view-mapping display-type="MBPatternJMSEndpoint"
view-definition-name="MBPatternJMSEndpoint" />
399
<view-mapping display-type="MBPatternMQEndpoint"
view-definition-name="MBPatternMQEndpoint" />
<view-mapping display-type="MBPatternURLEndpoint"
view-definition-name="MBPatternURLEndpoint" />
<view-mapping display-type="MBPatternRouting"
view-definition-name="MBPatternRouting" />
...
</collection-view-mappings>
To add mappings for our new detail views the detail-view-mappings element
has a new view-mapping element added, as shown in Example 10-12.
Example 10-12 New detail view mappings
<detail-view-mappings>
<view-mapping display-type="MBPatternRouter"
view-definition-name="MBPatternRouter" />
<view-mapping display-type="MBPatternTranscoder"
view-definition-name="MBPatternTranscoder" />
<view-mapping display-type="MBPatternEndpoint"
view-definition-name="MBPatternEndpoint" />
<view-mapping display-type="MBPatternJMSEndpoint"
view-definition-name="MBPatternJMSEndpoint" />
<view-mapping display-type="MBPatternMQEndpoint"
view-definition-name="MBPatternMQEndpoint" />
<view-mapping display-type="MBPatternURLEndpoint"
view-definition-name="MBPatternURLEndpoint" />
<view-mapping display-type="MBPatternRouting"
view-definition-name="MBPatternRouting" />
...
</detail-view-mappings>
10.4.5 Perspective resources

The title key used in the perspective definition has to be added to the resource
file we specified in the definition. This was MBPatternResources. Example 10-13
shows the key used.
Example 10-13 Perspective messages
# resources for the MB Pattern User perspective

mbpattern.perspective.display.name.user=MB Pattern User
400
10.5 Collection views

Collection views are used extensively in the WSRR Web UI. Query results, lists
of WSDL Documents, the operations in a port type; all of these are collection
views and all are defined in the same way. Collection views show a set of entities
from the WSRR. The collection views developed for the WMB Patterns scenario
show their business metadata as columns for each entity in the collection.
In order to show all deployed endpoints in the WMB Patterns scenario, we have
created a set of collection views. Each collection view shows metadata of interest
to the WMB Patterns scenario; the name, description and namespace for each
endpoint or routing. In this section we show how to create such a collection view.
A collection view definition describes the properties of the WSRR entities that
are to be displayed in columns within the view and also which action buttons
should be displayed. Figure 10-4 shows the collection view used to display all
MQ Endpoints.
Figure 10-4 A WMB Patterns scenario collection view
10.5.1 Collection view areas

A collection view has several aspects which are specified in a collection view
definition. These are the title, description, column headings, the properties
which provide the values for rows in the view, and the buttons. The buttons are
401
each specified in a button definition. A column heading and which property is

used is specified in the column definition. Figure 10-5 shows these areas.
Title
Description
Button Definitions
Column
Definition
Column
Definition
Column
Definition
Column
Definition
Figure 10-5 Areas of the collection view
10.5.2 A skeleton collection view

A skeleton collection view file is shown in Example 10-14. The definition name is
blank, there are placeholders for the title and description, and a single empty
column definition. Collection view definitions are stored in the folder named
collection underneath the folder named views in your project. We will extend this
skeleton to make a collection view intended to display all MQ Endpoints.
Example 10-14 Skeleton collection view definition

<collection-view-definition view-definition-name=""
xmlns="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/CollectionView
Definition"
xsi:schemaLocation=
"http://www.ibm.com/xmlns/prod/serviceregistry/6/0/CollectionViewDefini
tion
../../../schemas/CollectionViewDefinition.xsd ">
<messages>
<title-message message-key=""/>
402
<description-message message-key=""/>
</messages>
<column-definitions>
<column-definition>
<heading-message message-key=""/>
<property-name>property-name</property-name>
</column-definition>
</column-definitions>
</collection-view-definition>
10.5.3 Adding name, title and description

Every view definition has a name, which is independent of the definition file
name. This name is used in the view mappings in the perspective. For this view
we will use the name MBPatternMQEndpointCollection.
The title and description messages which appear on the collection view are
defined using two resource bundle key names. By default these keys are
resolved using the WSRR Web UI resource bundle which is not customizable.
The attribute resource-bundle-name is used to specify a different resource
bundle which you provide. In this article, we use the resource bundle
MBPatternResources for all messages. The title and description we use state that
the view is showing all monitored services.
Definition name uniqueness

Every collection view definition must have a unique definition name among
collection views. We therefore advise using a prefix for all of your definitions. In
this scenario, we use MBPattern as our prefix.
Resource key uniqueness

A resource key must be unique within its resource bundle. By specifying a
different resource bundle, your resource keys only need to be unique within that
bundle.
Update the skeleton as shown in Example 10-15 to add a definition name, title
and description keys.
Example 10-15 Adding the messages

<collection-view-definition view-definition-name="MBPatternMQEndpoint"
xmlns="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/CollectionView
Definition"
403
xsi:schemaLocation=
"http://www.ibm.com/xmlns/prod/serviceregistry/6/0/CollectionViewDefini
tion
../../../schemas/CollectionViewDefinition.xsd ">
<messages>
<title-message
message-key="mbpattern.collection.view.mqendpoints.title"
resource-bundle-name="MBPatternResources" />
<description-message
message-key="mbpattern.collection.view.mqendpoints.description"
resource-bundle-name="MBPatternResources" />
</messages>
<column-definition>
<heading-message message-key=""/>
<property-name>property-name</property-name>
</collection-view-definition>
The title appears in several places; at the top of the collection view and in the
portlet title. It also appears as the entry in the bread crumb trail. Figure 10-6
shows where these new additions appear.
Figure 10-6 The title and description on the view
Reusing view definition content

In order to create a new collection view definition which differs from another by
only the title and description, it is necessary to create an entirely new view
definition, copying the column and button definitions into the new definition.
10.5.4 Collection view columns

A collection view definition can contain one or more column definitions. A column
definition describes the heading message for the column, again using a message
key and resource bundle. Recall that a collection view shows a set of entities
404
from WSRR, each in a row. Each entity has a number of properties with a name
and value. A column definition identifies the name of a property on the entity, the
value of which is shown in the cell. This is done by the value of the property
element.
A cell value can be rendered as plain text, or as a HTML link which links to a
detail view of the entity in the row. Typically the first column of a collection view is
a set of HTML links allowing the user to see details of the entities shown. Adding
an action element with the value of DetailView makes the cell a link to a detail
view.
You can specify which detail view is used to show the entity, using a customized
view instead of the Web UI default. This is done by adding a display-type
element, the value of which is mapped to a detail view name in the perspective.
We will use the customized detail view developed for the WMB Pattern scenario
to show the MQ endpoints, called MBPatternMQEndpoint.
The first column in our view will show the name of the entity. All entities in WSRR
have a property called name which contains their name. Modify the
column-definition element to specify a message key for the column heading,
our resource bundle, the property name of name, add an action element with a
value of ViewDetail and a display-type element with a value of
MBPatternMQEndpoint. The new column definition is shown in Example 10-16.
Example 10-16 Adding a name column
<column-definition>
<heading-message message-key="collection.view.name"/>
<property-name>name</property-name>
<action>ViewDetail</action>
<display-type>MBPatternMQEndpoint</display-type>
<column-definition>
Figure 10-7 on page 406 shows the column you added to the collection view.
405
Figure 10-7 The name column in the view
The value of display-type means the detail view looks up the view mapped to
the display type MBPatternMQEndpoint in the MB Pattern User perspective. This is
the detail view we shall develop later in this chapter. For other columns, we want
the cell values shown as plain text, so we will omit the action element.
The entities shown in a collection view are Service Data Objects (SDOs), each of
which has predefined properties, for example name or version. They can also
have user defined properties, which can be added from the Web UI or the API.
Both predefined and user defined property names can be specified in a collection
view definition. If a user defined property has not been added to a particular
entity, the cell will be empty.
We need to add the metadata of interest to our scenario to the collection view, so
we can see at a glance the available endpoints.
Showing the type of an entity

You can specify a special property name which results in the SDO type of the
entity being shown in the cell. This special name is sdoType.
The completed column definitions should appear as in Example 10-17.
Example 10-17 The completed column definitions
<column-definition filterable="true">
<heading-message message-key="collection.view.column.name" />
<property-name>name</property-name>
406
<action>ViewDetail</action>
<display-type>MBPatternMQEndpoint</display-type>
<heading-message message-key="collection.view.column.description"
/>
<property-name>description</property-name>
<heading-message message-key="collection.view.column.nameSpace"
/>
<property-name>namespace</property-name>
10.5.5 Collection view buttons

A collection view definition can specify a number of buttons which appear above
the columns. There is a set of actions to choose from for each button. A button's
action determines what happens when the button is clicked.
If a collection view definition specifies any buttons, an extra column of select
boxes will be rendered in the view. The select boxes allow the user to select
entities for those actions which act upon entities. Some actions do not act upon
entities, such as the New Concept action.
For our scenario we will add buttons to allow us to create new endpoints, delete
existing endpoints, add properties, relationships and classifications to the
endpoints, export, subscribe to changes and add the endpoints to our favorites.
All button definitions are enclosed in a single button-definitions element which
must be after the column-definitions element. An individual button is defined in
a button-definition element, with required elements to define the button
message and the button action.
The first button we will add to our view will allow us to add a user defined
property to the selected entities in the view. Add a button-definitions element
below the column-definitions element, as shown in Example 10-18 on
page 408.
407
Example 10-18 A button definition for Add property
...
<button-definitions>
<button-definition>
<button-message message-key="collectionButton.addProperties"/>
<button-action>addProperty</button-action>
</button-definition>
</button-definitions>
The button-message element specifies the message which appears on the
button, here we use a message from the WSRR resource bundle. The
button-action element specifies what happens when the button is clicked; its
value is from a predefined list of button actions, discussed in 10.5.6, Collection
view button action values on page 410. Figure 10-8 shows where the button you
added appears in the view.
Figure 10-8 The Add Properties button in the view
To complete the button definitions, add button-definition elements with the

values shown in Table 10-4.
Table 10-4 Button definitions
408
Button message key
Button action
collectionButton.new
createGenericObject
collectionButton.deleteItems
deleteItems
Button message key
Button action
collectionButton.addProperty
addProperty
collectionButton.addRelationship
addRelationship
collectionButton.addClassifications
addClassifications
collectionButton.export
exportDocuments
collectionButton.subscribe
subscribe
collectionButton.addFavourites
addFavorites
The completed button-definitions element is shown in Example 10-19.

Example 10-19 The complete button definitions
<button-definitions>
<button-definition>
<button-message message-key="collectionButton.new" />
<button-action>createGenericObject</button-action>
<template-name>MQEndpoint</template-name>
<button-definition>
<button-message message-key="collectionButton.deleteItems" />
<button-action>deleteItems</button-action>
<button-definition>
<button-message message-key="collectionButton.addProperties" />
<button-action>addProperty</button-action>
<button-definition>
<button-message message-key="collectionButton.addRelationship" />
<button-action>addRelationship</button-action>
<button-definition>
<button-message message-key="collectionButton.addClassifications" />
<button-action>addClassifications</button-action>
<button-definition>
<button-message message-key="collectionButton.export" />
<button-action>exportDocuments</button-action>
<button-definition>
<button-message message-key="collectionButton.subscribe" />
<button-action>subscribe</button-action>
409
<button-definition>
<button-message message-key="collectionButton.addFavourites" />
<button-action>addFavorites</button-action>
</button-definitions>
10.5.6 Collection view button action values

As mentioned, a button can perform one of a number of actions when clicked.
The button-action element specifies this action. You can use one of the
following button actions:
Create a new GenericObject (Concept) by presenting you with the initial
values to use.
Load a new document into WSRR.
Add a new user defined property to all selected entities, with values provided
by you in the Web UI.
Delete the selected entities, providing they can be deleted.
Add a new custom relationship to all selected entities, with the name and
targets provided by you in the Web UI.
Export the selected entities, providing they can be exported.
Add the selected entities to the your favorites list.
Subscribe to changes of the selected entities, further filtering can be provided
by you in the Web UI.
Add classifications to all selected entities, as chosen by you in the Web UI.
For further information and detail, see the WSRR Information Center, UI
customization section:
c/twsr_configrn_webUI.html
10.5.7 Adding collection view resources

The keys used in the collection view definition need to be added to the resource
file we specified in the view definition. This was MBPatternResources.
Example 10-20 on page 411 shows the messages used by this collection view.
410
Example 10-20 Collection view messages
mbpattern.collection.view.mqendpoints.title=MQ Endpoints
mbpattern.collection.view.mqendpoints.description=This is the
collection of the MQ Endpoints in the registry.
10.6 Managing UI customization configurations

The runtime behavior of WSRR components is determined by the content of
configuration objects associated with those components. For example the
access control component uses two configuration objects that set policy and role
mapping behavior. The UI has five such configuration types which correspond to
each of the types of UI definition files. A WSRR configuration comprises a logical
name, a configuration type, content (as bytes), and an indication of whether it is a
system configuration or a user-defined configuration, as shown in Table 10-5.
Table 10-5 Attributes of a configuration object
Name
Description
Name
The logical name for this configuration.
Type
The configuration type, which, for the purposes of customizing the

UI must be one of:
UI_PERSPECTIVE
UI_NAVIGATION_TREE
UI_COLLECTION_VIEW
UI_DETAIL_VIEW
Content
The contents of the configuration, stored as a byte array. This is

typically populated by reading from an XML file.
System indicator
A value of true indicates the configuration is used internally by

WSRR. A value of false indicates the configuration is user-defined.
For each of the UI view definition files you create, you need to load a
corresponding configuration object of the appropriate type, as shown in
Table 10-6. As these are typically new view definitions, the configuration object
must be loaded with the system indicator value set to false.
Table 10-6 Configuration types and corresponding UI view definitions
Configuration type
Use this for the UI view definition of type:
UI_PERSPECTIVE
perspectives
411
Configuration type
Use this for the UI view definition of type:
view queries
UI_NAVIGATION_TREE
navigation trees
UI_COLLECTION_VIEW
collection views
UI_DETAIL_VIEW
detail views
The combination of a configuration name and configuration type uniquely identify

a configuration. For example, you could have two configurations called new
user, one for the perspective configuration and one for the navigation tree.
10.6.1 Manage configurations with MBean operations

You load, update, remove and retrieve configurations using the JMX interface.
The WSRR application provides an MBean of type ServiceRegistryRepository
which allows administrators to perform a range of housekeeping operations. In
addition to managing configurations this includes refining access control,
managing ontology systems and performing import/export of WSRR entities. The
specific operations you are interested in for managing configurations are:
loadConfiguration
updateConfiguration
deleteConfiguration
getConfigurationId
Previously, we defined view queries that return all endpoints that are classified
with type of MQ, JMS or URL (see 10.2.4, Querying by classification on
page 387). To support this classification of services, we would need to define an
ontology system as an OWL file and load into WSRR. The MBean operations for
loading and removing ontology systems are:
deleteOntologySystem
The pattern for invoking any MBean operation is the same: locate an MBean,
specify operation signature and parameters, invoke the named operation on the
MBean and cast any result object to an appropriate type.
For more information about how to use the WSRR Admin MBean, refer to 8.5,
Administering WSRR using JMX on page 292.
A sample script to load all the UI customizations that make up our scenario is
provided with the WMB V6 Client for WebSphere Service Registry and
412
Repository. It can be found in the

<WMBClient_Install>\Tests\WSRRTestEntities\GUIConfiguration directory and
is documented in 16.8.2, Configuring WSRR for the patterns on page 810 step
8 on page 812.
413
414
11
Chapter 11.
Using the WSRR Eclipse

plug-in
This chapter describes the installation, configuration and usage of the
WebSphere Service Registry and Repository (WSRR) Eclipse plug-in.
During development, if you are working in an Eclipse-based development
environment, you can use the Eclipse user interface (UI) that is supplied in the
WSRR Eclipse plug-in to access and search for documents that are stored in
WSRR. You can also use the Eclipse UI to publish documents that you are
developing to WSRR.
415
11.1 WSRR Eclipse user interface

The WebSphere Service Registry and Repository Eclipse user interface (UI) is
supplied as a WSRR Eclipse plug-in and provides a new view, the Service
Registry view, in your Eclipse workbench (for example, Rational Software
Architect). You can use the Service Registry view to access and search for
objects in WSRR. You can also publish to WSRR new objects that you develop in
the Eclipse workbench using the Service Registry view.
The Service Registry view is supplied by the WSRR plug-in. The plug-in can be
downloaded from the WSRR SupportPac page:
http://www.ibm.com/support/docview.wss?rs=171&uid=swg27008751#1
Install it using Update Manager in your Eclipse workbench. When you have
installed the WSRR plug-in, you can open the Service Registry view, which is
initially displayed by default in the Resource perspective, as shown in
Figure 11-1.
Figure 11-1 Resource perspective
416
You can rearrange the views in the workbench if you prefer. For more information,
see Moving and docking views in the Eclipse Workbench User Guide:
http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.user/t
asks/tasks-3e.htm
The Eclipse UI connects the workbench to a local or remote instance of WSRR.
You can then work in the Service Registry view to perform the following tasks:
Search WSRR for objects.

Import objects from WSRR to a project in your local workspace.
Publish to WSRR objects that you create in your local workspace.
Add property and relationship information to objects in WSRR.
Every object in WSRR can be uniquely identified by using a combination of the

document's name, version, and namespace. Every object can also have any
number of custom name-value properties, any number of custom relationships,
and belong to a hierarchy of classifications.
From the Service Registry view, you can search WSRR using one or more of the
following criteria:
The object's uniqueness identifiers or any part of it. If you search on only one
or two parts of the identifier, more than one object could be returned in the
search results.
The type, or types, of object that you want to retrieve; for example, you can
search for XML and WSDL documents.
One or more properties and property values of the object.
The classification of the object in WSRR. If you specify a high level
classification, all of the objects in all of the classifications below it are returned
in the search results.
The search results return zero or more objects depending on how specific the
search criteria are.
11.2 Installing the Eclipse user interface

The Eclipse UI comes in the form of an Eclipse plug-in and is supplied separately
as a WebSphere Service Registry and Repository SupportPac. The following
instructions describe how to download, install, and configure the Eclipse UI in an
Eclipse workbench; for example, in WebSphere Integration Developer or Rational
Software Architect.
Chapter 11. Using the WSRR Eclipse plug-in
417
Before you can install and use the Eclipse UI, you must complete the following
tasks:
Install on your local computer an Eclipse workbench; for example,
WebSphere Integration Developer or Rational Software Architect. The
minimum level is Eclipse 3.0.2.
Install on your local computer the WebSphere Application Server Application
Client or WebSphere Application Server Application Server. For more
information about installing the Application Client, see Installing Application
Client for WebSphere Application Server in the WebSphere Application
Server information center. Alternatively, have access to a WebSphere
Application Server version 6.0.2 JRE.
Connect to the Internet.
To download and install the WSRR plug-in:
1. On the WSRR SupportPacs page
http://www.ibm.com/support/docview.wss?rs=3163&uid=swg27008751 click
SA02.
2. Download the WSRR Eclipse plug-in zip file to a local folder in your machine,
for example, C:\ITSO\WSRR\EclipsePlugin.
3. Start the Eclipse workbench.
4. In the workbench, from the Help menu, click Software Updates Find and
Install, as shown in Figure 11-2. The Install/Update wizard should now open.
Figure 11-2 Help Menu
418
5. In the wizard, click Search for new features to install (see Figure 11-3 on
page 419), then click Next.
Figure 11-3 New features to install
6. The wizard lists the locations that are searched when searching for new
features.
7. Add a new location to search.
a. Click New Archived Site (as shown in Figure 11-4). The Select Local
Site Archive dialog opens.
419
Figure 11-4 New Archived Site
b. Choose the WSRR Eclipse plug-in zip file you have downloaded.
c. Click OK.
The new location is added to the list in the wizard as shown in Figure 11-5.
420
Figure 11-5 New location added
8. Select the check box for the new location or archived site and then click Next
as shown in Figure 11-6 on page 422. If the location is secured, enter your
user name and password.
421
Figure 11-6 New location selected
9. Eclipse searches the selected location or locations for new features. When
the search is complete, the available features that are relevant to your
installation are displayed in the wizard.
10.Select the check box for com.ibm.serviceregistry.core.feature, which
contains the WSRR plug-in, as shown in Figure 11-7 on page 423, and then
click Next.
422
Figure 11-7 Select Feature to install
11.Read the license agreements and click I accept the terms in the license
agreements to accept the terms, then click Next (see Figure 11-8 on
page 424).
423
Figure 11-8 License agreement
12.Select the location on your local computer where you want to install the
WSRR plug-in (see Figure 11-9 on page 425). To add a new location, click
Add Site, and then browse to the location where you want to install the
WSRR plug-in.
424
Figure 11-9 Select Install location
13.Click Finish.
14.In the Jar Verification dialog (Figure 11-10 on page 426), click Install.
425
Figure 11-10 Jar Verification
15.When prompted, click Yes to restart the Eclipse workbench, which completes
the installation. The WSRR plug-in is now installed in your Eclipse
workbench.
16.Open the Service Registry view:
a. From the window menu, click Show View Other. The Show View dialog
opens as in Figure 11-11 on page 427.
b. Expand the Service Registry folder.
c. Click Service Registry, then click OK.
426
Figure 11-11 The show view dialog
d. The Service Registry view opens in the bottom-right of the workbench as

in Figure 11-12.
Figure 11-12 Service Registry view
You have now installed the WSRR Eclipse UI in your Eclipse workbench.
The next section covers configuration of the Eclipse UI to connect to WSRR.
427
11.3 Configuring the Eclipse user interface

Before you can use the Eclipse UI to access the objects in WSRR, you must
configure the UI with the connection details that it needs, including any security
details for making a secure connection.
To configure the Eclipse UI to connect to WSRR:
1. Start the Eclipse workbench and ensure that the Service Registry view is
open.
2. From the window menu, click Preferences. The Preferences dialog opens.
3. In the Preferences dialog, expand Service Registry, then click WSRR
Locations. The WSRR Locations page is displayed.
4. On the WSRR Locations page, shown in Figure 11-13, click Add.
Figure 11-13 WSRR Preferences
5. The Add/Edit Service Registry Preferences dialog opens (shown in

Figure 11-14 on page 429).
6. In the dialog, enter your connection details:
a. In the Alias field, type a meaningful name for the connection. For example,
type the name of the remote computer to which you are connecting.
b. In the Host field, type the fully-qualified name or IP address (IPv4 or IPv6)
of the remote computer to which you are connecting. For example,
eclipse.itso.ibm.com or 192.168.0.3
428
c. In the Port field, type the port number of the WSRR WebSphere
Application Servers JNDI port. The default port number is 2809.
d. In the Security field, select the type of security to use for the connection:
If the WebSphere Application Server instance to which you are

connecting has security turned off, select None.
Figure 11-14 Add Service Registry preferences
If the WebSphere Application Server (WSRR) instance to which you

are connecting has security turned on, select sas.client.props. The
WebSphere client provides a sample sas.client.props file. For
example:
<AppServer-client-install-root>\profiles\default\properties\sa
s.client.props.
Open the sas.client.props file in a text editor. In the sas.client.props
file, type the WebSphere Application Server user name and password
on the lines shown here:
com.ibm.CORBA.loginSource=properties
com.ibm.CORBA.loginUserid=<username>
com.ibm.CORBA.loginPassword=<password>
429
Edit the following lines of the file to ensure that the

com.ibm.ssl.keyStore and com.ibm.ssl.trustStore have the correct
values:
com.ibm.ssl.keyStore=C:/IBM/AppServer/profiles/default/etc/Dum
myClientKeyFile.jks
com.ibm.ssl.trustStore=C:/IBM/AppServer/profiles/default/etc/D
ummyClientTrustFile.jks
If security is enabled on the WSRR instance, then the panel should
look similar to Figure 11-15.
Figure 11-15 Edit Service Registry preferences
e. Click OK. The new connection is listed on the WSRR Locations page of
the Preferences dialog.
430
Note: If you are connecting to a secure WSRR and the Eclipse plug-in
is installed in RSA (Rational Software Architect) V6 or WID
(WebSphere Integration Developer) V6, you need to start RSA or WID
with -vm argument to use JRE of WebSphere Client. For example
For RSA: rationalsdp.exe -vm
C:\RSA6.0\runtimes\base_v6\java\jre\bin\javaw.exe
For WID: wid.exe -vm
C:\RSA6.0\runtimes\base_v6\java\jre\bin\javaw.exe
7. Select the new location, checking the appropriate location, then click OK.
8. If you have previously connected to WSRR in this workbench session you will
have to restart the workbench to apply the changes. The Eclipse JVM caches
the security credentials of any previous WSRR connection, you must restart
the workbench to clear the cache.
You have now configured the WSRR Eclipse UI to connect to WSRR.
The following sections cover using the Eclipse UI to access WSRR.
11.4 Searching for objects in WSRR

You can search for documents and other objects in WSRR using a combination
of different types of criteria.
To search for objects in WSRR:
1. In the Service Registry view, right-click somewhere in the view, then click
Retrieve (this is shown in Figure 11-16 on page 432). The Search dialog
opens.
431
Figure 11-16 Retrieving objects from WSRR
2. In the Search dialog, select the criteria on which you want to search. You
must select, as a minimum, the type of object for which you are searching. For
example, select the WSDL check box to search for WSDL files as shown in
Figure 11-17 on page 433. The number of results that are returned depends
on how specific the criteria are.
432
Figure 11-17 Search window
3. Click Search. All objects in WSRR that match the search criteria that you
specified are displayed in the Retrieved Items dialog (see Figure 11-18 on
page 434) which opens when the search has completed.
433
Figure 11-18 Search result window
4. Click OK to close the Retrieved Items dialog.

The retrieved items are added to the appropriate categories of the Service
Registry view; for example, if you searched for some WSDL documents, the
WSDL documents that were retrieved are listed under the WSDL Documents
category in the Service Registry view.
If a document imports another document, for example, if a.wsdl imported b.wsdl
then this is displayed as an expandable tree node with a + symbol next to the
a.wsdl document. See Figure 11-19 on page 435 for an example of this.
434
Figure 11-19 WSDL Documents retrieved
If you want to retrieve all of the objects of a certain type from WSRR, you can
quickly do this if you right-click in the Service Registry view, then click the object
type that you want to retrieve; for example, to retrieve all the WSDL documents in
WSRR, click Retrieve WSDLs.
Now, you can import one or more of the retrieved documents into a project in
your local workspace.
11.5 Importing documents into your local workspace

When you have retrieved documents from WSRR, they are displayed in the
Service Registry view. You cannot work with the documents, though, until you
have imported them into a project in your local workspace.
To import documents from WSRR to your local workspace:
1. Switch to the Resource perspective.
2. In the Navigator view, create a new project.
3. In the Service Registry view, right-click the document that you want to
import, then click Import document as shown in Figure 11-20 on page 436.
The Import wizard opens.
435
Figure 11-20 Import Document
4. In the wizard (see Figure 11-21 on page 437), click the name of the project
into which you want to import the document and ensure that the correct file
name is shown in the File Name field.
436
Figure 11-21 Import document wizard
5. Optional: To import any objects that depend on the selected document, select
the Include all dependent artefacts check box.
6. Click Finish.
437
Figure 11-22 Document Imported
A copy of the document from WSRR is imported into the project in your local
workspace as shown in Figure 11-22.
You can now change or use the document as required.
11.6 Publishing documents to WSRR

When you have developed new documents, or new versions of documents that
already exist in WSRR, you can publish them to WSRR using the Eclipse UI.
To publish a document, or a new version of a document, to WSRR:
1. Switch to the Resource perspective.
2. In the Navigator view, right-click the document that you want to publish, then
click Service Registry Publish Document (as shown in Figure 11-23).
Figure 11-23 Publish Document menu option
3. The Publish A Document To WSRR wizard opens as shown in Figure 11-24

on page 439.
4. In the wizard, check that the correct name is shown in the Name field and the
correct document type is shown in the File type field.
5. Optional: Type a description in the Description field.
438
6. Optional: If a previous version of the document already exists in WSRR, type

a new version number in the Version field so that you can distinguish this new
version of the document.
Figure 11-24 Publish a Document to WSRR dialog
7. Click Finish. When the document has been published to WSRR, a

confirmation message is shown. Click Ok.
The document is now stored in WSRR. You can check this by retrieving it using
the Service Registry view.
You can now perform the following tasks on the document in WSRR:
Adding properties to objects in WSRR
Defining relationships between objects in WSRR
Creating concepts for objects in WSRR
These tasks are explained in the next sections.
439
11.7 Adding properties to objects in WSRR

You can use the Eclipse UI to add properties to the objects in WSRR to formally
describe them and make it easier for other developers to find and reuse them.
To add properties to an object in WSRR:
1. In the Service Registry view, retrieve the document or documents to which
you want to add properties. The documents must be displayed in the Service
Registry view.
2. In the Service Registry view, right-click one or more documents, then click
Add Properties (as shown in Figure 11-25).
Figure 11-25 Add Properties menu option
3. The Add Properties wizard opens as in Figure 11-26 on page 441. In the
wizard, click Add.
440
Figure 11-26 Add Properties dialog
4. The Add Property dialog opens as in Figure 11-27. In the dialog, type a
name for a new property and type the value for the property, then click OK.
Figure 11-27 Add property dialog
5. Optional: Add more or edit properties in the same way.

6. Click Next. This will display a summary of the documents that will have new
properties added to and the list of properties that will be added to each.
7. Click Finish. The new properties will now be added to the documents. The
properties of a particular document can be seen in the Properties view; if you
open the Properties view and reselect the document in the Service Registry
441
view then you will see them in the User-defined category of the Properties
view, as highlighted in Figure 11-28.
Figure 11-28 Properties view
The properties have now been added to the documents in WSRR.
11.8 Defining relationships between objects in WSRR

In WSRR, you can define relationships between documents so that, for example,
one document has a named relationship to another document. You can define
these relationships using the Eclipse UI.
To define relationships between objects in WSRR:
1. In the Service Registry view, retrieve the document or documents to which
you want to add relationships. The documents must be displayed in the
Service Registry view.
2. In the Service Registry view, right-click one document, and then click Add
Relationships (as shown in Figure 11-29 on page 443).
442
Figure 11-29 Add Relationships menu option
3. The Add Relationships wizard opens as in Figure 11-30. In the wizard, type
the name of the relationship that you want to define, then click Next.
Figure 11-30 Add Relationship dialog
4. The wizard displays the Search dialog (see Figure 11-31 on page 444) so
that you can search for the document or documents you want to define the
relationship to.
443
Figure 11-31 Search criteria
5. Click Next. This will display the results of the search (see Figure 11-32). If no
results are found, either:
Click Back and re-specify your search criteria,
Or click Cancel. Check at least one document that you want to create a
relationship to, from your originally selected document.
Figure 11-32 Search results
6. Click Finish.
444
The new relationship is now defined between the documents in WSRR. This new
relationship can be seen in the User relationships category of the Properties
view as shown in Figure 11-33.
Figure 11-33 Properties view
11.9 Creating concepts for objects in WSRR

Concepts are collections of objects stored in WSRR. You can create concepts
using the Eclipse UI.
Note: Concepts are called GenericObjects in the WSRR API.
To create a concept in WSRR:
1. In the Service Registry view, select the documents that you want to group
together into a Concept.
2. Right-click the selection, then click Create Concept as in Figure 11-34 on
page 446.
445
Figure 11-34 Create Concept menu option
3. The Publish as Concept wizard opens as in Figure 11-35. Enter a name,

description, and version for the concept, then click Next.
Figure 11-35 New Concept details
446
4. For each document click in the cell for the Relationship name (highlighted in
Figure 11-36). A cursor is displayed in the cell so that you can type in it. Press
Enter to apply each change.
Figure 11-36 Add Relationships to documents in new Concepts
5. Optional: Click Next, then add one or more properties to the concept.
6. Click Finish. A message confirms that the concept was successfully created.
The concept has now been created in WSRR as seen in Figure 11-37 on
page 448. You can check this by retrieving it using the Service Registry view.
447
Figure 11-37 New Concept created
11.10 Creating concepts using local documents

Concepts are collections of objects. New objects that are created within the
Eclipse workspace can be grouped together into a collection and published as a
new concept into WSRR.
This has the same effect as individually publishing a document into WSRR then
creating concepts for objects in WSRR.
Before you can create concepts using local documents, you must have created a
document in a project in your local workspace; the project must be displayed in
the Navigator view of the Resource perspective.
To publish a concept using local documents:
1. In the Navigator view, select and right-click one or more documents, then click
Publish as Concept (as in Figure 11-38 on page 449). The Publish As
Concept wizard opens.
448
Figure 11-38 Publish as Concept menu option
2. In the wizard, type a name, description, and version for the concept (as shown
in Figure 11-39), then click Next.
Figure 11-39 New Concept details
3. For each document click in the Relationship name cell as highlighted in

Figure 11-40 on page 450. A cursor is displayed in the cell so that you can
type in it. Press Enter to apply each change.
449
Figure 11-40 Add Relationships to documents in new Concepts
4. Optional: Click Next, then add one or more properties to the concept.
5. Click Finish. A message confirms that the concept was successfully created.
The concept has now been created in WSRR as shown in Figure 11-41 on
page 451. You can check this by retrieving it using the Service Registry view.
450
Figure 11-41 New Concept created
451
452
12
Chapter 12.
Scenarios description
This chapter describes the example scenarios used later in this book in
Chapters 13, 14 and 15.
The topics covered are:
12.1, Services description on page 454
12.2, Requirements on page 458
12.3, Solution overview on page 458
453
12.1 Services description

IBM-ITSO Ltd. decided to use Web services in their organization to query the
price of items they deal in. They want to use Service Oriented Architecture to add
dynamic and flexibility to their solution. They use WebSphere Service Registry
and Repository as their service registry solution.
They have a WSDL Port Type ItemPrice describing the Interface.
Figure 12-1 shows the interface ItemPrice, which is the interface of the Web
services. It accepts itemName of type xsd:string as input and returns xsd:int
price as output.
Figure 12-1 ItemPrice Interface
IBM-ITSO has developed two Web services, ItemPriceService and

ItemPriceDiscountedService to provide the price for a given item name.
ItemPriceService returns the normal price (without any discounts) and it is
comparatively slow. Valid item names are Item1, Item2 and Item3. Any other item
name generates a RuntimeException. See Example 12-1.
Note: A delay of 5 seconds has been added in ItemPriceService so that the
response of the service is delayed. This is intentionally done to illustrate and
observe different quality of interactions between the two services.
Example 12-1 ItemPriceSerivce implementation
/**
* ItemPriceSoapBindingImpl.java
*/
package com.ibm.itso;
454
public class ItemPriceSoapBindingImpl implements com.ibm.itso.ItemPrice

{
public int getPrice(java.lang.String itemName)
throws java.rmi.RemoteException {
int itemPrice = -100;
// Sleep to add delay
try {
Thread.sleep(5000);
} catch (InterruptedException e) {
}
if (itemName.equals("Item1"))
itemPrice = 100;
else if (itemName.equals("Item2"))
itemPrice = 200;
itemPrice = 300;
else
throw new RuntimeException("ItemPriceService: Internal
Error!!");
System.out.println("ItemPrice:: itemName: " + itemName
+ ", itemPrice: " + itemPrice);
return itemPrice;
}
}
ItemPriceDiscountedService returns the discounted price which is typically
provided for privileged customers. There is no delay in this service
implementation and the response is comparatively fast. Valid item names are
Item1, Item2 and Item3. Any other item name generates a RuntimeException.
See Example 12-2.
Example 12-2 ItemPriceDiscountedSerivce implementation
/**
* ItemPriceDiscountedSoapBindingImpl.java
*/
public class ItemPriceDiscountedSoapBindingImpl implements
Chapter 12. Scenarios description
455
com.ibm.itso.ItemPrice {
public int getPrice(java.lang.String itemName)
throws java.rmi.RemoteException {
int itemPrice = -90;
if (itemName.equals("Item1"))
itemPrice = 90;
itemPrice = 180;
itemPrice = 270;
else
throw new RuntimeException("ItemPriceDiscountedService:
Internal Error!!");
System.out.println("ItemPriceDelayed:: itemName: " + itemName
+ ", itemPrice: " + itemPrice);
return itemPrice;
}
}
They have two categories of customers, Gold and General. Gold customers are
privileged customers and get discounts on items. All price requests from Gold
customers should be handled by the discounted service. See Figure 12-2.
General
IBM-ITSO Ltd.
ItemPriceService
ItemPriceDiscountedService
Gold
Figure 12-2 System context
Both services use the ItemPrice PortType but have different endpoints. See
456
getPrice
(Operation)
ItemPrice
(PortType)
ItemPriceService
SOAP Endpoint
ItemPrice
(Port)
ItemPriceService
(Service)
ItemPriceDiscounted
(Port)
SOAP Endpoint
(Service)
Figure 12-3 ItemPrice and ItemPriceDiscounted services use the same PortType
Users provide name of item and type of customer (Gold or General) to query the
price of item. We use another interface ItemPriceEnquiry to receive request
from users. See Figure 12-4.
Figure 12-4 ItemPriceEnquiry Interface
457
12.2 Requirements
The solution requirements are divided into Governance and ESB Runtime
categories.
Governance requirements
1. Access to the resources in the WSRR runtime environment must be restricted
such that each user is only granted the minimum level of access that they
require in order to perform their role.
2. The physical document objects that are stored in WSRR must have a suitable
lifecycle applied to them.
3. When a physical document object is loaded into WSRR, a checksum must be
calculated and added as property to the object.
ESB Runtime Requirements

1. To externalize the endpoint address and not hard code it in WebSphere
Enterprise Service Bus (WESB)
2. Dynamically decide which service to invoke (ItemPrice or
ItemPriceDiscounted) based on the customer type
12.3 Solution overview

ESB Runtime
Both ItemPriceService and ItemPriceDiscountedService will be deployed in
WebSphere Application Server.
Service metadata (like the endpoints) will be published to WebSphere Service
Registry and Repository (WSRR).
The solution uses WebSphere Enterprise Service Bus (WESB) to mediate the
service consumer request and redirect to the appropriate service based on the
customer type.
458
WAS
WESB
Service
Consumer
Mediation
Module
ItemPriceService
WSRR
Figure 12-5 Interaction between WESB and WSRR
459
460
13
Chapter 13.
Configuring governance
This chapter describes how to enforce the various aspects of SOA governance
that were discussed in Chapter 5, SOA governance enablers on page 157.
13.1, Configuring security on page 462
13.2, Using lifecycles on page 476
13.3, Developing custom plugins on page 482
13.4, Performing impact analysis on page 499
461
13.1 Configuring security

The sections that follow describe how to configure security in WebSphere
Service Registry and Repository in the context of the scenario described in
Chapter 12, Scenarios description on page 453. IBM-ITSO Ltd. wants to
harden the security configuration of WSRR in their SOA environment to ensure
that the permissions that are granted to users only provide them with the
minimum level of access that they need in order to perform their role.
In this scenario, we assume that WSRR has been installed to a WebSphere
Application Server environment that has global security enabled and is using the
Local OS as the user registry. Also, as discussed in 7.6.1, Security on
page 274, we assume that the wasadmin user has been defined on the
machine on which WSRR is running. Finally, we assume that the default role
mappings were used during the installation process.
It is not within the scope of this book to describe how to enable global security in
WebSphere Application Server. This is described in the WebSphere Information
Center:
websphere.base.doc/info/aes/ae/tsec_csec.html
It is also not within the scope of this book to describe how to create users and
groups in the user registry that you have configured in your WebSphere
Application Server environment. However, the sections that follow require that a
number of users are created in the relevant user registry. You must perform the
steps that are required by the configured user registry in order to create the users
shown in Table 13-1.
Table 13-1 Users defined in the IBM-ITSO Ltd. user registry
462
User name
Description
itcam4soa
This user is used by the IBM Tivoli Composite Application Manager for
SOA product in order to connect to WSRR.
wesb
This user is used by the WebSphere Enterprise Service Bus product

in order to connect to WSRR.
assetmgr
This user performs lifecycle related tasks on the artefacts in WSRR,

such as making objects governable and transitioning their state.
wsrruser
This user represents a normal user of WSRR in IBM-ITSO Ltd.
Note: All of the example commands shown in this section specify -user and
-password parameters when invoking wsadmin. These parameters are
required because IBM-ITSO Ltd. has enabled security in their WebSphere
environment.
Also, in all of the example commands shown, <WAS_INSTALL> is the root
installation directory of WebSphere Application Server and <WSRR_INSTALL> is
the root installation directory of WebSphere Service Registry and Repository.
Finally, it is assumed that all of the example commands are executed from the
<WSRR_INSTALL>\admin\scripts directory.
13.1.1 Modifying the J2EE security role mappings

As discussed previously, WSRR was installed into the IBM-ITSO Ltd.
environment using the default role mappings that are specified in the WSRR
installation scripts. This means that the special subject, AllAuthenticatedUsers, is
currently mapped to both the Administrator and User J2EE security roles in
WSRR.
IBM-ITSO Ltd. wants to modify the security role mappings so that only the
wasadmin user is mapped to the Administrator J2EE security role. As noted in
5.3.1, J2EE security roles on page 187, since the wasadmin user is defined as
the Server user ID in the IBM-ITSO Ltd. WebSphere environment, it must be
mapped to the Administrator J2EE security role in order to ensure the correct
operation of WSRR in a secure environment. The steps that are required to do
this are as follows:
1. Logon to the WebSphere Administrative Console as the wasadmin user.
2. In the navigation tree, expand Applications.
3. Click Enterprise Applications.
4. In the list of Enterprise Applications, click ServiceRegistry.
5. In the Additional Properties section, click Map security roles to
users/groups. This is shown in Figure 13-1 on page 464.
Chapter 13. Configuring governance
463
Figure 13-1 Map security roles to users/groups
6. Check the check box in the Select column for the Administrator role and
uncheck the check box in the All authenticated? column.
7. Click Look up users, as shown in Figure 13-2 on page 465.
464
Figure 13-2 Removing the all authenticated mapping
8. Make sure that an asterisk (*) is entered in the Search String entryfield.
9. Click Search.
10.The Available list box displays the list of user names that match the specified
search string. From this list of user names, select the wasadmin user.
11.Click >>, as shown in Figure 13-3 on page 466.
465
Figure 13-3 Adding the wasadmin mapping
12.The wasadmin user is now displayed in the Selected list box. Click OK.
13.The wasadmin user is now listed in the Mapped users column for the
Administrator role, as shown in Figure 13-4 on page 467.
466
Figure 13-4 The completed mapping
14.Click OK.
15.Save the changes and synchronize them with the nodes.
16.For the changes to become effective, you must restart the application server
on which WSRR is running.
13.1.2 Removing the AllAuthenticatedUsers principal from the WSRR

Administrator role
As discussed in 5.3.2, User defined roles on page 188, WebSphere Service
Registry and Repository provides an authorization component that allows
additional roles to be defined. Since the default role mappings were used when
installing WSRR to the IBM-ITSO Ltd. environment, the AllAuthenticatedUsers
special subject has also been mapped to the Administrator role in the WSRR
authorization component.
In order to restrict the users who have administrative access to WSRR,
IBM-ITSO Ltd. wants to modify the role mappings defined in the WSRR
authorization component to remove this role mapping. They would then like to
map the wasadmin user to the Administrator role in the WSRR authorization
component.
In order to remove the AllAuthenticatedUsers special subject from the
Administrator role in the WSRR Authorization component, execute the command
shown in Example 13-1 on page 468.
467
Example 13-1 Command to remove the AllAuthenticatedUsers mapping from the

Administators role
<WAS_INSTALL>\wsadmin.bat
-user wasadmin
-password passw0rd
-wsadmin_classpath <WSRR_INSTALL>\ServiceRegistryClient.jar
-f removePrincipalFromRole.jacl
VirtualPrincipal.AllAuthenticatedUsers
Administrator
Note: VirtualPrincipal.AllAuthenticatedUsers must be specified as the
principal in order to remove the AllAuthenticatedUsers special subject. Simply
specifying AllAuthenticatedUsers will have no effect on the role mapping.
In order to add the wasadmin user to the Administrator role in the WSRR
Authorization component, execute the command shown in Example 13-2.
Example 13-2 Command to map the wasadmin user to the Administrators role
-user wasadmin
-password passw0rd
-f addPrincipalToRole.jacl
wasadmin
Administrator
The modifications to the role mappings in the WSRR Authorization component
must be persisted in order for them to become effective. In order to do this,
execute the command shown in Example 13-3.
Example 13-3 Command to persist the WSRR role mappings
-user wasadmin
-password passw0rd
-f persistRoleMappings.jacl
13.1.3 Adding roles

IBM-ITSO Ltd. wants to harden the security configuration of WSRR to prevent
users from performing any actions that are outside of their defined roles. In order
to do this, they need to define additional roles to the authorization component in
468
WSRR and map the relevant user to these roles. The roles that IBM-ITSO Ltd.
need to define are shown in Table 13-2.
Table 13-2 New roles required by IBM-ITSO Ltd.
Role name
Description
SOAInfrastructure
This role will be used to control access to objects in WSRR by

other runtime components in IBM-ITSO Ltds SOA environment,
such as IBM Tivoli Composite Application Manager for SOA and
WebSphere Enterprise Service Bus.
LifecycleManager
This role will be used to control access to the lifecycle

management actions provided by WSRR.
In order to add these roles to the WSRR Authorization component, execute the
commands shown in Example 13-4.
Example 13-4 Commands to add the required roles
-user wasadmin
-password passw0rd
-f addRole.jacl
SOAInfrastructure
-user wasadmin
-password passw0rd
-f addRole.jacl
LifecycleManager
execute the command shown in Example 13-3 on page 468.
13.1.4 Adding permissions to roles

As discussed in 5.3, WSRR security on page 187, WSRR adopts a permissive
approach to access control in the WSRR authorization component, with access
to all of the objects in WSRR unrestricted by default. However, once a role is
explicitly granted access to a set of target objects in WSRR, all other roles are
implicitly denied access to that set of objects. In this situation, in order for other
469
roles to access the same set of target objects, each role must also be explicitly
granted access to the set of objects.
IBM-ITSO Ltd. require that the permissions for all WSRR users provide them with
the minimum level of access that they need in order to perform their role. Given
the behavior described previously, in order to achieve this they will first need to
grant the Administrator role the permission to perform any action on any object in
WSRR. This will implicitly deny all other roles the permission to perform these
actions. They can then selectively grant permissions to each role to allow the
required level of access for that role.
The permissions required by each of the roles in the IBM-ITSO Ltd. SOA
environment are shown in Table 13-4 on page 475.
Table 13-3 IBM-ITSO Ltd. permissions
WSRR action
Administrator
LifecycleManager
SOAInfrastructure
srrCreate
srrRetrieve
srrUpdate
srrDelete
srrTransition
srrManageGov
User
The sections that follow describe the commands that need to be executed in
order to add the required permissions to each of the roles.
Adding permissions to the Administrator role

In order to add the required permissions to the Administrator role, execute the
commands shown in Example 13-5.
Example 13-5 Commands to add the required permissions to the Administrator role
-user wasadmin
-password passw0rd
-f addPermissionToRole.jacl
Administrator
srrCreate
IBMITSOAdministratorCreatePermission
/WSRR/BaseObject
470
-user wasadmin
-password passw0rd
Administrator
srrRetrieve
IBMITSOAdministratorRetrievePermission
/WSRR/BaseObject
-user wasadmin
-password passw0rd
Administrator
srrUpdate
IBMITSOAdministratorUpdatePermission
/WSRR/BaseObject
-user wasadmin
-password passw0rd
Administrator
srrDelete
IBMITSOAdministratorDeletePermission
/WSRR/BaseObject
-user wasadmin
-password passw0rd
Administrator
srrTransition
IBMITSOAdministratorTransitionPermission
/WSRR/BaseObject
-user wasadmin
-password passw0rd
471
Administrator
srrManageGov
IBMITSOAdministratorManageGovPermission
/WSRR/BaseObject
The modifications to the permissions in the WSRR Authorization component

execute the command shown in Example 13-6.
Example 13-6 Command to persist the WSRR permissions policy
-user wasadmin
-password passw0rd
-f persistPolicy.jacl
Adding permissions to the LifecycleManager role

In order to add the required permissions to the LifecycleManager role, execute
the commands shown in Example 13-7.
Example 13-7 Commands to add the required permissions to the LifecycleManager role
-user wasadmin
-password passw0rd
LifecycleManager
srrRetrieve
IBMITSOLifecycleManagerRetrievePermission
/WSRR/BaseObject
-user wasadmin
-password passw0rd
LifecycleManager
srrUpdate
IBMITSOLifecycleManagerUpdatePermission
/WSRR/BaseObject
472
-user wasadmin
-password passw0rd
LifecycleManager
srrTransition
IBMITSOLifecycleManagerTransitionPermission
/WSRR/BaseObject
-user wasadmin
-password passw0rd
LifecycleManager
srrManageGov
IBMITSOLifecycleManagerManageGovPermission
/WSRR/BaseObject

Adding permissions to the SOAInfrastructure role

In order to add the required permissions to the SOAInfrastructure role, execute
the commands shown in Example 13-8.
Example 13-8 Commands to add the required permissions to the SOAInfrastructure role
-user wasadmin
-password passw0rd
SOAInfrastructure
srrRetrieve
IBMITSOSOAInfrastructureRetrievePermission
/WSRR/BaseObject
-user wasadmin
-password passw0rd
473
SOAInfrastructure
srrUpdate
IBMITSOSOAInfrastructureUpdatePermission
/WSRR/BaseObject

Adding permissions to the User role

In order to add the required permissions to the User role, execute the commands
Example 13-9 Command to add the required permission to the User role
-user wasadmin
-password passw0rd
User
srrRetrieve
IBMITSOUserRetrievePermission
/WSRR/BaseObject

Removing permissions from the User role

As discussed in User Permissions on page 195, the User role is granted some
default permissions in the WSRR authorization component by the installation
process. Two of these permissions grant the User role the permission to retrieve
objects from WSRR that are in specific states in the default lifecycle. Since this
action is also authorized for the User role by the permission defined in
Example 13-9, these permissions do not concern us, although it would normally
be best practice to remove them.
However, the GovernedUserUpdatePermission authorizes the User role to
update objects in WSRR that are in the Model or Assemble states defined by the
default lifecycle. The requirements specified by IBM-ITSO Ltd. do not allow users
474
in the User role to perform any updates of objects in WSRR and so this
permission must be removed. In order to remove this permission from the User
role, execute the command shown in Example 13-10.
Example 13-10 Command to remove the GovernedUserUpdatePermission permission
from the User role
-user wasadmin
-password passw0rd
-f removePermissionFromRole.jacl
GovernedUserUpdatePermission
User

13.1.5 Mapping users to roles

Now that the roles required by IBM-ITSO Ltd. have been created and the
required permissions have been added to them, the only thing that remains to be
done is to add the relevant users to them. The required role mappings for
IBM-ITSO Ltd. are shown in Table 13-4.
Table 13-4 IBM-ITSO Ltd. role mappings
Role name
Mapped users
Administrator
wasadmin
User
AllAuthenticatedUsers
SOAInfrastructure
itcam4soa
wesb
LifecycleManager
assetmgr
Note that the Administrator and User roles are just shown for completeness. The
wasadmin user was mapped to the Administrator in 13.1.2, Removing the
AllAuthenticatedUsers principal from the WSRR Administrator role on page 467.
The AllAuthenticatedUsers special subject was mapped to the User role during
WSRR installation.
In order to map the relevant users to the new roles in the WSRR Authorization
component, execute the commands shown in Example 13-11 on page 476.
475
Example 13-11 Commands to map users to roles
-user wasadmin
-password passw0rd
itcam4soa
SOAInfrastructure
-user wasadmin
-password passw0rd
wesb
SOAInfrastructure
-user wasadmin
-password passw0rd
asssetmgr
LifecycleManager

Note: If WebSphere Application Server has been configured to use an LDAP
user registry and you are attempting to map an LDAP group principal to a role
in WSRR, you must specify the fully qualified name of the LDAP group
principal, for example:
cn=wsrruser,ou=itdepartment,o=IBMITSO
13.2 Using lifecycles

As discussed in 5.2, Lifecycles on page 158, WebSphere Service Registry and
Repository provides support for the definition and enforcement of a lifecycle. The
sections that follow describe how a lifecycle can be applied to an object in
476
WSRR, how the lifecycle state of an object can by transitioned from one state to
another and how you can stop applying a lifecycle to an object.
All of these tasks can be performed using both the WSRR Web UI or the
Governance API. However, the sections that follow only describe how to perform
these tasks using the Web UI. For more information about performing these
tasks using the Governance API, refer to the Governance application
programming section of the WebSphere Service Registry and Repository
Information Center:
http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.doc/t
wsr_mansrvce_programmingguide_1_502.html
These tasks are not described within the context of a scenario. We simply
describe the steps that need to be performed in order to achieve the tasks. The
following chapters may refer to these instructions when asking you to perform the
relevant actions in the context of the scenario for that chapter.
13.2.1 Making an object governable

Recall that the process of applying a lifecycle to an object in WSRR is referred to
as making the object governable. The steps here describe how to make an object
governable using the Web user interface.
1. Logon to the WebSphere Service Registry and Repository Console as a
user in the Administrator role.
2. In the navigation tree, expand Service Documents.
3. Click WSDL Documents.
4. Click a WSDL document in the list.
5. On the details view of the WSDL document, click the Governance tab.
6. The Governance tab displays the current governance status for the object.
when the object is not governed, the panel will as shown in Figure 13-5 on
page 478.
477
Figure 13-5 Governance tab for an object that is not governed
7. Select a suitable transition from the Initial state transitions list. When using
the WSRR default lifecycle, only the Default transition is available.
8. Click Make Governable.
9. The WSDL document is made governable. During this process a
GovernanceRecord is created and the object is added to its list of governed
objects. The object is also classified using the relevant initial state for the
lifecycle in question. Figure 13-6 on page 479 shows the governance panel
for the ItemPrice.wsdl WSDL document after making it governable. Notice
that the Governance State for the object is Created. This is initial state for
the WSRR default lifecycle.
478
Figure 13-6 Governance tab for a governed object
13.2.2 Transitioning the lifecycle state of a governed object

Once an object in WSRR is governed, it is possible to transition the governed
object from one lifecycle state to another. The steps here describe how to
transition the governed object.
5. Select the required transition from the Available state transitions list.
6. Click Transition, as shown in Figure 13-7 on page 480.
479
Figure 13-7 Transitioning an object
7. The lifecycle state of the WSDL document is transitioned to the relevant state.
In the example shown, the WSDL object is originally in the Created state. In
the default lifecycle, the only transition from that is available from this state is
the Plan transition. Performing this transition moves the WSDL document
from the Created state to the Model state, as shown in Figure 13-8 on
page 481.
480
Figure 13-8 New lifecycle state
Note: When using the default lifecycle, it is not always possible to transition an
object back to a previous state in the lifecycle. This is due to the fact that some
states only have transitions defined that move objects forwards in the lifecycle.
Refer to 5.2.3, WSRR default lifecycle on page 163 for more information
about the transitions that are possible in the WSRR default lifecycle.
13.2.3 Removing governance from an object

If, at some point, you decide that you no longer want to apply a lifecycle to an
object, you can remove governance from the object. The steps here describe
how to remove governance from a governed object.
5. Click Remove Governance, as shown in Figure 13-9 on page 482.
481
Figure 13-9 Removing governance from an object.
6. Governance is removed from the WSDL document. That is, the WSDL
document no longer has a lifecycle applied to it. During this process the
GovernanceRecord associated with the WSDL document is deleted. The
governance panel is updated to reflect the fact that the WSDL document is no
longer governed, as shown in Figure 13-5 on page 478.
Note: Governance can only be removed from the root object of a governance
collection. Attempting to remove governance from any non-root object in the
governance collection will result in an error. It is possible to navigate from an
object in the governance collection to the root object of the governance
collection. This can be done by selecting the Root governance record link on
the Governance tab of the non-root object.
13.3 Developing custom plugins

As discussed in 5.4, WSRR plugins on page 197, WebSphere Service Registry
and Repository provides the following system programming interfaces that allow
you to implement WSRR plugins that can be invoked during the standard
processing performed by WSRR:
482
ServiceRegistryValidator
ServiceRegistryGovernanceValidator
ServiceRegistryNotifier
ServiceRegistryGovernanceNotifier
The sections that follow describe an example of developing, packaging,

deploying and configuring a validation and a notification plugin.
Note: This section assumes that you have already downloaded and unpacked
the additional materials itso.zip file to the root of the your C drive. For more
detailed information, refer to Appendix B, Additional material on page 877.
13.3.1 Developing a custom validator

In the context of our scenario, IBM-ITSO Ltd. wants to store in memory copies of
the documents in WSRR on client machines in order to improve performance. To
do this, they must be able to determine if the content of the document that is
stored in WSRR is the same as the content of the document that is stored on the
client.
IBM-ITSO Ltd. has decided to make use of the java.security.MessageDigest
class to calculate a fixed-length hash value for each document that is stored in
WSRR. The java.security.MessageDigest class provides applications with the
functionality of a message digest algorithm, such as MD5 or SHA. Message
digests are secure one-way hash functions that take arbitrary-sized data and
output a fixed-length hash value.
In order to ensure that each document that is stored in WSRR has the correct
hash value associated with it, IBM-ITSO Ltd. has implemented a validation plugin
that will calculate the hash value when a document is created or updated in
WSRR. The sections that follow describe the implementation of this validator.
The full source code for this validator can be found in the
<ADD_MATS>\ITSO\WSRR\src directory, where <ADD_MATS> is the directory where
you extracted the additional materials for this redbook.
ITSOValidationPlugin class definition

IBM-ITSO Ltd. require that the hash value for a document be calculated
regardless of whether or not the document in question is a governed object.
Since their validator does make use of any of the methods defined on the
ServiceRegistryGovernanceValidator interface, it simply implements the
ServiceRegistryValidator interface, as shown in Example 13-12 on page 484.
483
Example 13-12 ITSOValidationPlugin class
public class ITSOValidationPlugin implements ServiceRegistryValidator {

// Checksum property name constant
private static final String CHECKSUM_PROPERTY = "checksum";
public ServiceRegistryStatus create(OriginalObject newObject) {
// Make sure that the object has a CustomerType property
ServiceRegistryStatus srStatus = addChecksum(newObject);
return srStatus;
}
public ServiceRegistryStatus update(OriginalObject oldObject,
OriginalObject newObject) {
// Make sure that the object has a CustomerType property
ServiceRegistryStatus srStatus = addChecksum(newObject);
return srStatus;
}
public ServiceRegistryStatus delete(OriginalObject oldObject) {
return new ServiceRegistryStatus();
}
}
The addChecksum method

Both the create and the update methods of the validation plugin invoke the
addChecksum method. The addChecksum method is shown in Example 13-13
on page 485.
This method needs to ensure that the object in question is a Document object.
Once it has determined that the object in question represents a document, it
checks to see if the object has a checksum property. If no checksum property is
present, the hash value for the document content is calculated. A checksum
property is then added to the object using the calculated hash as the value.
If the object already has checksum value, a check is made to ensure that the
checksum is correct since it is possible that the content of the document has
been updated. If the hash value that is calculated for the document content is
different to the hash value stored in the checksum property, the value of the
checksum property is updated with the new hash value.
484
Example 13-13 addChecksum method
private ServiceRegistryStatus addChecksum(OriginalObject object) {

// Create the variable to return
ServiceRegistryStatus srStatus = new ServiceRegistryStatus();
// Make sure that the object represents a document
if (object instanceof Document) {
// Cast the object to a document
Document document = (Document)object;
// All document objects must have a checksum property. If it's
// not already there add it, unless there is a relationship with
// the same name, in which case we have an error.
BSRSDOHelper sdoHelper = BSRSDOHelper.INSTANCE;
if (!sdoHelper.isRelationshipSet(object, CHECKSUM_PROPERTY)) {
try {
if (!sdoHelper.isPropertySet(object, CHECKSUM_PROPERTY)) {
// No CustomerType property or relationship...
// ...add the property.
String checksum =
calculateMD5Checksum(document.getContent());
sdoHelper.addProperty(object, CHECKSUM_PROPERTY,
checksum);
} else {
// Check to see if the content of the object has
// changed by comparing checksums
String currentChecksum = sdoHelper.getPropertyValue(
object, CHECKSUM_PROPERTY);
String newChecksum = calculateMD5Checksum(
document.getContent());
if (!currentChecksum.equals(newChecksum)) {
sdoHelper.addProperty(object, CHECKSUM_PROPERTY,
newChecksum);
}
}
// Add exception to the status object.
// This automatically sets the return code to ERROR
srStatus.addException(e);
}
} else {
// A relationship called CustomerType already exists on the
485
// object... this is an error.

srStatus.addDiagnostic(ServiceRegistryStatus.ERROR,
"Relationship with name: " + CHECKSUM_PROPERTY
+ " already exists on the object");
}
}
return srStatus;
}
The calculateMD5Checksum method

The calculateMD5Checksum method is the method that actually calculates the
hash value of the document content. As its name suggests, it uses the MD5
message digest algorithm in order to calculate the hash value. It then converts
this hash value to a hexadecimal string. The calculateMD5Checksum method is
Example 13-14 calculateMD5Checksum method
private String calculateMD5Checksum(byte[] content)

throws NoSuchAlgorithmException {
// Create the variable to return
String md5hash = null;
// Create the MD5 MessageDigest object
MessageDigest msgDigest = MessageDigest.getInstance("MD5");
byte[] md5sum = msgDigest.digest(content);
// Convert the byte array to hex
BigInteger bigInt = new BigInteger(1, md5sum);
md5hash = bigInt.toString(16);
return md5hash;
}
13.3.2 Developing a customer notifier

In the context of our scenario, IBM-ITSO Ltd. wants to use the WSRR mediation
primitive in provided with WebSphere Enterprise Service Bus to dynamically
route service requests to the target service based on the customer type. The
WSRR mediation primitive queries WSDLPort objects from WSRR at runtime
using the metadata defined on these objects. IBM-ITSO Ltd. wants to add a
486
CustomerType property to all WSDLPort objects in WSRR to be used for this

purpose.
WSDLPort objects, however, do not represent physical documents in WSRR. A
WSDLPort is a derived object that is created to represent the contents of a port
element contained in a WSDL document. Therefore, a WSRR validation or
notification plugin will not be invoked directly as the result of creating a
WSDLPort object. In order to update WSDLPort objects in WSRR, IBM-ITSO Ltd.
has implemented a notification plugin that adds a CustomerType property to all of
the WSDLPorts that are created when a WSDLDocument object is created or
updated.
Note: The CustomerType property is added to WSDLPort objects using a
notification plugin because the plugin must make use of the bsrURI of the
WSDLDocument in order to query the relevant WSDLPort objects from
WSRR. It is not possible to use a validator for this, since the bsrURI of objects
that are being created does not get set until the object is persisted to WSRR.
This happens after the create method on the validator is invoked.
Note: The value of the CustomerType property that is added to the WSDLPort
objects is an empty string. IBM-ITSO Ltd. administrators still need to manually
specify the correct value of this property in order to ensure that service
requests are routed correctly.
The sections that follow describe the implementation of this notifier. The full
source code for this notifier can be found in the <ADD_MATS>\ITSO\WSRR\src
directory, where <ADD_MATS> is the directory where you extracted the additional
materials for this redbook.
ITSONotificationPlugin class definition

IBM-ITSO Ltd. require that the CustomerType property be added to WSDLPort
objects regardless of whether or not the WSDLDocument being created or
updated is a governed object. Since their notifier does make use of any of the
methods defined on the ServiceRegistryGovernanceNotifier interface, it simply
implements the ServiceRegistryNotifier interface, as shown in Example 13-15
on page 488.
Notice that the notifier has a constructor that it uses to create an InitialContext
instance. However, the constructor does not attempt to create an instance of the
WSRR API session EJB. As discussed in 5.4, WSRR plugins on page 197,
validators and notifiers should not attempt to create instances of the
ServiceRegistrySession or ServiceRegistryGovernance EJBs within their
constructors.
487
Example 13-15 ITSONotificationPlugin class
public class ITSONotificationPlugin

implements ServiceRegistryNotifier {
// Business owner property name constant
private static final String CUSTOMER_TYPE_PROPERTY = "CustomerType";
// Attribute required to acces WSRR API session EJB
private InitialContext context = null;
private ServiceRegistrySession wsrrClient = null;
public ITSONotificationPlugin() {
try {
// Create the InitialContext object
context = new InitialContext();
} catch (NamingException e) {
}
}
public void create(OriginalObject newObject, boolean success,
ServiceRegistryException ex) {
// Check to see if the create succeeded
if (success) {
// Check to see if a WSDLDocument was created
if (newObject instanceof WSDLDocument) {
// Check the WSDLPorts for the CustomerType property
checkWSDLPorts((WSDLDocument) newObject);
}
}
}
public void update(BaseObject oldObject, BaseObject newObject,
boolean success, ServiceRegistryException ex) {
// Check to see if the update succeeded
if (success) {
// Check to see if a WSDLDocument was updated
if (newObject instanceof WSDLDocument) {
488
// Check the WSDLPorts for the CustomerType property

checkWSDLPorts((WSDLDocument) newObject);
}
}
}
public void delete(OriginalObject oldObject, boolean success,
ServiceRegistryException ex) {
}
}
The init method

The ITSONotificationPlugin implements an init method in order to perform lazy
initialization of the ServiceRegistrySession EJB reference. This is shown in
Example 13-16.
Example 13-16 init method
private void init() {

// Get the local home
try {
Object obj =
context.lookup(
"ejb/com/ibm/serviceregistry/ServiceRegistrySessionHome");
ServiceRegistrySessionHome home =
(ServiceRegistrySessionHome)PortableRemoteObject.narrow(obj,
ServiceRegistrySessionHome.class);
wsrrClient = home.create();
}
}
The checkWSDLPorts method

Both the create and the update methods of the notification plugin check to see if
the object being created or updated is a WSDLDocument object. If it is, they
invoke the checkWSDLPorts method. The checkWSDLPorts method is shown in
Example 13-17 on page 490.
489
The first thing that the checkWSDLPorts method does is to ensure that the
reference to the WSRR API session EJB is initialized. This lazy initialization of
the EJB reference avoids the infinity loop issue discussed in 5.4, WSRR plugins
on page 197.
The checkWSDLPorts method then needs to execute a query to obtain all of the
WSDLPorts that were created as a result of creating or updating the
WSDLDocument. WSRR provides a set of predefined queries that can be used
to run common queries. The getWSDLDocPorts query returns the list of
WSDLPort objects for a given WSDLDocument. For the full list of predefined
queries that are available in WSRR, see the WebSphere Service Registry and
Repository Information Center:
c/programguide63.html
The checkWSDLPorts method iterates over the list of WSDLPort objects that was
returned by the query and checks each one for the existence of the
CustomerType property.
Example 13-17 checkWSDLPorts method
private void checkWSDLPorts(WSDLDocument wsdlDocument) {

// Make sure that remote EJB reference is initialized
if (wsrrClient == null) {
init();
}
try {
// Run the getWSDLDocPorts predefined query
String[] params = new String[] { wsdlDocument.getBsrURI() };
List results = wsrrClient.executeNamedQuery("getWSDLDocPorts",
params);
// For each WSDLPort found, make sure that
// it has CustomerType property
for (Iterator i = results.iterator(); i.hasNext();) {
WSDLPort wsdlPort = (WSDLPort) i.next();
checkForCustomerType(wsdlPort);
}
}
}
490
The checkForCustomerType method

The checkForCustomerType method simply checks the WDSLPort object to see
if it has a CustomerType property. If no CustomerType property is present, it adds
the property with an empty string as the value. The checkForCustomerType
method is shown in Example 13-18.
Example 13-18 checkForCustomerType method
private void checkForCustomerType(WSDLPort wsdlPort) {

// All objects need to have the CustomerType property.
// If it's not already there add it, unless there is a relationship
// with the same name, in which case we have an error.
BSRSDOHelper sdoHelper = BSRSDOHelper.INSTANCE;
if(!sdoHelper.isRelationshipSet(wsdlPort, CUSTOMER_TYPE_PROPERTY)) {
if (!sdoHelper.isPropertySet(wsdlPort, CUSTOMER_TYPE_PROPERTY)) {
try {
// No CustomerType property or relationship...
// ... add the property.
sdoHelper.addProperty(wsdlPort, CUSTOMER_TYPE_PROPERTY,
"");
wsrrClient.update(wsdlPort);
}
}
} else {
System.out.println( "Relationship with name: "
+ CUSTOMER_TYPE_PROPERTY + " already exists on the object");
}
}
13.3.3 Deploying custom plugins

As discussed in 5.4.3, Packaging plugins on page 206, the recommended way
of deploying custom plugins is to package them in a JAR file and add this JAR file
to the classpath of the WSRR application. Two actions need to be performed in
order to achieve this, as follows:
1. The JAR file containing the plugin implementation classes must be added to
the classpath of a shared library within WebSphere Application Server
instance on which WSRR is running.
491
2. A reference to this shared library must be added to the WSRR application.

These actions are described in the sections that follow.
Creating the shared library

IBM-ITSO Ltd. have packaged the ITSOValidationPlugin and
ITSONotificationPlugin into a JAR file called ITSO_WSRR_Plugins.jar. This JAR
file is provided with the additional materials in the
<ADD_MATS>\ITSO\WSRR\plugins directory, where <ADD_MATS> is the directory
where you extracted the additional materials for this redbook. In order to create a
shared library and add this JAR file to its classpath, follow the steps described
here:
1. Copy the ITSO_WSRR_Plugins.jar to a directory on the target machine, for
example, C:\ITSO\WSRR\plugins.
2. Logon to the WebSphere Application Server Administrative Console.
3. In the navigation tree, expand Environment Shared Libraries.
4. Click New.
5. Enter ITSO_WSRR_Plugins in the Name field.
6. Enter the path to the ITSO_WSRR_Plugins.jar file in the Classpath field, as
492
Figure 13-10 Creating the shared library
7. Click OK.
8. Save the changes and synchronize them with the nodes.
Adding a reference to the shared library to WSRR

The new shared library has now been created at the specified scope within the
WebSphere Application Server cell. However, the plugin implementation classes
contained in the shared library are still not available to WSRR. In order to make
them available to WSRR, the shared library needs to be added to the classloader
for the WSRR application. To do this, follow the steps described here:
1. In the navigation tree, expand Applications Enterprise Applications.
2. In the list of enterprise applications, click ServiceRegistry.
3. In the Additional Properties section, click Libraries.
493
4. Click Add.
5. Select ITSO_WSRR_Plugins in the Library name drop down list, as shown
in Figure 13-11.
Figure 13-11 Adding the shared library reference to WSRR
6. Click OK.
7. Save the changes and synchronize them with the nodes.
8. For the changes to become effective, you must restart the application server
13.3.4 Configuring custom plugins

WSRR is now able to access the plugin implementation classes contained in the
ITSO_WSRR_Plugins.jar file. However, WSRR needs to be configured so that it
knows what actions and what object types the plugins need to be invoked for. As
discussed in 5.4.4, Configuring plugins on page 207, this is achieved by
modifying the relevant configuration properties file. The sections that follow
describe how to configure the validation and notification plugins in WSRR.
Configuring the validation plugin

The sections that follow describe how to configure the validation plugin in WSRR.
494
Retrieving the validation configuration properties file from WSRR

In order to make the necessary modifications to the validation configuration
properties file, it must first be retrieved from WSRR. We have provided a script
that will retrieve this configuration properties file from WSRR. In order to retrieve
the file using this script, follow the steps described here:
1. Open a command prompt and change to the <ADD_MATS>\ITSO\WSRR\scripts
directory, where <ADD_MATS> is the directory where you extracted the
additional materials for this redbook.
2. Execute the command shown in Example 13-19, where <WASPATH> is the path
to the directory where WebSphere Application Server is installed and
<WSRRPATH> is the file path to the directory where the ServiceRegistryClient.jar
resides.
Example 13-19 Running the retrieveConfiguration.jacl script
-f retrieveConfiguration.jacl
PLUGIN_PROPERTIES
true
validation.properties
Note: The command shown in Example 13-19 must be entered on a single
line of the command window.
3. The validation configuration properties file will be retrieved from WSRR and
written to the validation.properties file.
Modifying the validation configuration properties file

Once the configuration properties file has been retrieved, it must be modified to
include an entry for the ITSOValidationPlugin. Recall that the
ITSOValidationPlugin adds a checksum property to documents when they are
created or updated in WSRR. The plugin itself checks that the type of document
being created represents a physical document, so it is possible to add the
ITSOValidationPlugin implementation class to the end of the list of validators
specified on the validators key. To do this, follow the steps described here:
1. Open the validation.properties file in a text editor.
2. Modify the validators key to include the fully qualified ITSOValidationPlugin
implementation class, as shown in Example 13-20 on page 496.
495
Example 13-20 Modifying the validation configuration properties file

validators=com.ibm.sr.api.SRTemplateValidator,com.ibm.itso.plugins.ITSO
ValidationPlugin
3. Save and close the validation.properties file.
Updating the validation configuration properties file in WSRR

The modified validation configuration properties file must now be stored back in
WSRR. WSRR provides a sample administration script that can be used to
update configuration objects. In order to update the configuration properties file
using this script, follow the steps described here:
1. Copy the modified validation.properties file to <WSRRPATH>\admin\scripts,
where <WSRRPATH> is the directory where WSRR is installed.
2. Open a command prompt and change to the <WSRRPATH>\admin\scripts
directory.
3. Execute the command shown in Example 13-21, where <WASPATH> is the path
to the directory where WebSphere Application Server is installed.
Example 13-21 Running the updateConfiguration.jacl script
-f updateConfiguration.jacl
.
validation.properties
PLUGIN_PROPERTIES
true
496
Note: The parameters required by the updateConfiguration.jacl script are:
Filepath
Filename
Configuration name
Configuration type
System configuration
The current directory . is specified as the filepath specified in Example 13-21.

If you need to specify a fully qualified filepath for when running this script on
the Windows platform, all path separators need to be specified using forward
slashes /.
4. The validation configuration properties file has now been updated in WSRR.
For the changes to become effective, you must restart the application server
Configuring the notification plugin

The sections that follow describe how to configure the notification plugin in
WSRR.
Retrieving the notification configuration properties file from WSRR

In order to make the necessary modifications to the notification configuration
properties file, it must first be retrieved from WSRR. We have provided a script
that will retrieve this configuration properties file from WSRR. In order to retrieve
the file using this script, follow the steps described here:
1. Open a command prompt and change to the <ADD_MATS>\ITSO\WSRR\scripts
directory, where <ADD_MATS> is the directory where you extracted the
additional materials for this redbook.
2. Execute the command shown in Example 13-19 on page 495, where
<WASPATH> is the path to the directory where WebSphere Application Server is
installed and <WSRRPATH> is the file path to the directory where the
ServiceRegistryClient.jar resides.
Example 13-22 Running the retrieveConfiguration.jacl script
-f retrieveConfiguration.jacl
PLUGIN_PROPERTIES
true
notification.properties
497

3. The notification configuration properties file will be retrieved from WSRR and
written to the notification.properties file.
Modifying the notification configuration properties file

Once the configuration properties file has been retrieved, it must be modified to
include an entry for the ITSONotificationPlugin. Recall that the
ITSONotificationPlugin adds a CustomerType property to WSDLPort objects
when the WSDLDocument object that contains them has been created or
updated in WSRR. Since the plugin only needs to be invoked after a
WSDLDocument object is created or updated, the ITSONotificationPlugin
implementation class can be added to the end of the list of notifiers specified on
a new key of notifiers.WSDLDocument. To do this, follow the steps described
here:
1. Open the notification.properties file in a text editor.
2. Add a new notifiers.WSDLDocument key to the properties file, specifying the
fully qualified ITSONotificationPlugin implementation class as the value, as
Example 13-23 Modifying the validation configuration properties file
# These validators are called for all WSDLDocuments

notifiers.WSDLDocument=com.ibm.itso.plugins.ITSONotificationPlugin
3. Save and close the notification.properties file.
Updating the notification configuration properties file in WSRR

The modified notification configuration properties file must now be stored back in
WSRR. WSRR provides a sample administration script that can be used to
update configuration objects. In order to update the configuration properties file
using this script, follow the steps described here:
1. Copy the modified notification.properties file to <WSRRPATH>\admin\scripts,
where <WSRRPATH> is the directory where WSRR is installed.
2. Open a command prompt and change to the <WSRRPATH>\admin\scripts
directory.
3. Execute the command shown in Example 13-21 on page 496, where
<WASPATH> is the path to the directory where WebSphere Application Server is
installed.
498
Example 13-24 Running the updateConfiguration.jacl script
-f updateConfiguration.jacl
.
notification.properties
PLUGIN_PROPERTIES
true
Note: The parameters required by the updateConfiguration.jacl script are:
Filepath
Filename
Configuration name
Configuration type
System configuration
The current directory . is specified as the filepath specified in Example 13-21.

If you need to specify a fully qualified filepath for when running this script on
the Windows platform, all path separators need to be specified using forward
slashes /.
4. The notification configuration properties file has now been updated in WSRR.
For the changes to become effective, you must restart the application server
13.4 Performing impact analysis

The sections that follow provide a number of examples of performing impact
analysis in WSRR using the Web user interface in order to determine the
dependencies that exist between various artefacts. The artefacts that are used
within the example are those from the IBM-ITSO Ltd. scenario described in
Chapter 12, Scenarios description on page 453. It is assumed at this point that
all of the relevant artefacts for the scenario have been loaded into WSRR.
499
13.4.1 Analyzing dependencies between physical document objects

The documents for the services that IBM-ITSO Ltd. have developed have been
loaded into WSRR in their SOA environment. The object graph for the physical
document objects for these services is very simple, consisting of three WSDL
documents, as follows:
ItemPricePortType.wsdl
ItemPrice.wsdl
ItemPriceDiscounted.wsdl
The ItemPricePortType.wsdl document simply defines the port type for the
service. The ItemPrice.wsdl and ItemPriceDiscounted.wsdl documents both
import the ItemPricePortType.wsdl document and define bindings and
endpoints for the service. This is shown in Figure 13-12.
ItemPricePortType
WSDL
import
import
ItemPrice
ItemPriceDiscounted
WSDL
WSDL
Figure 13-12 IBM-ITSO Ltd. physical document objects
WSDL documents that import other WSDL documents

The importedWSDLs relationship on a WSDLDocument object can be navigated in
order to determine whether it imports other WSDL documents. To use impact
analysis to determine the list of WSDL documents that are imported by the
ItemPrice.wsdl document object, follow the steps described here:
1. Logon to the WebSphere Service Registry and Repository Console.
500

4. Click ItemPrice.wsdl in the WSDL documents.
5. On the details view of the WSDL document, click the Impact Analysis tab.
6. To determine which WSDL documents are imported, we must determine the
outbound dependencies for the ItemPrice.wsdl document. Therefore, check
the Include entities this entity depends on check box.
7. The modelled relationships that can be specified when performing impact
analysis on WSDLDocument objects are described in Table 5-12 on page 225.
To determine which WSDL documents are imported, select the WSDL
document to imported WSDL document from the Built-in relationships
list box, as shown in Figure 13-13.
Figure 13-13 Analyzing outbound dependencies to other WSDL documents
8. Click OK.
9. The results are shown in Figure 13-14 on page 502.
501
Figure 13-14 WSDL documents imported by ItemPrice.wsdl
The results can be interpreted by reading the columns in the order:

1. Originating Object
2. Impact Relationship
3. Name
4. Relationship name
For the results shown in Figure 13-14, this would interpreted as:
ItemPrice.wsdl depends on ItemPricePortType.wsdl via the
importedWsdls relationship.
WSDL documents that are imported by other WSDL

documents
It is also possible to use impact analysis to traverse the importedWSDLs
relationship on a WSDLDocument object in the other direction. That is, it is possible
to use impact analysis to determine whether other WSDL documents import the
WSDL document in question. To use impact analysis to determine the list of
WSDL documents that import the ItemPricePortType.wsdl document object,
follow the steps described here:
4. Click ItemPricePortType.wsdl in the WSDL documents.
6. To determine which WSDL documents import this document, we must
determine the inbound dependencies for the ItemPricePortType.wsdl
document. Therefore, check the Include entities that depend on this entity
check box.
analysis on WSDLDocument objects are described in Table 5-12 on page 225.
502
To determine which WSDL documents that import this WSDL document,

select the WSDL document to imported WSDL document from the Built-in
relationships list box, as shown in Figure 13-15.
Figure 13-15 Analyzing inbound dependencies from other WSDL documents
8. Click OK.
9. The results are shown in Figure 13-16.
Figure 13-16 WSDL documents that import the ItemPricePortType.wsdl

3. Name
503
For the results shown in Figure 13-16 on page 503, this would interpreted as:
ItemPricePortType.wsdl is depended on by ItemPriceDiscounted.wsdl
via the importedWsdls relationship.
ItemPricePortType.wsdl is depended on by ItemPrice.wsdl via the
importedWsdls relationship.
13.4.2 Analyzing dependencies between physical document objects

and derived objects
The derived objects that were created when the ItemPricePortType.wsdl
document was loaded into WSRR are shown in Figure 13-17.
ItemPrice
WSDLPortType
getPrice
WSDLOperation
getPriceRequest
getPriceResponse
WSDLMessage
WSDLMessage
parameters
WSDLPart
getPrice
getPriceResponse
ElementDeclaration
ElementDeclaration
Figure 13-17 Derived objects parsed from the ItemPricePortType.wsdl document
504
As noted in LogicalObject relationships on page 229, the

ItemPricePortType.wsdl WSDLDocument object has no knowledge of any of
the derived objects that were produced from it. However, it is possible to use
impact analysis to determine all of the derived objects that were parsed from a
physical document object. This can be done by specifying the document
relationship when performing impact analysis to determine inbound
dependencies on a physical document object. To use impact analysis to
determine the list of derived objects that were parsed from the
ItemPricePortType.wsdl document object, follow the steps described here:
4. Click ItemPricePortType.wsdl in the WSDL documents.
6. To determine which derived objects were parsed from this WSDL document,
we must determine the inbound dependencies for the
ItemPricePortType.wsdl document. Therefore, check the Include entities
that depend on this entity check box.
analysis on Document objects are described in Table 5-11 on page 224. To
determine which derived objects were parsed from this WSDL document
select the Derived entity reference to its source document from the
Built-in relationships list box, as shown in Figure 13-18 on page 506.
505
Figure 13-18 Analyzing inbound dependencies from derived objects
8. Click OK.
9. The results are shown in Figure 13-19.
Figure 13-19 Derived objects parsed from the ItemPricePortType.wsdl
506

3. Name
4. Object type
For the first result in the list shown in Figure 13-19 on page 506, this would
interpreted as:
ItemPricePortType.wsdl is depended on by getPriceResponse XML
element via the document relationship.
Note: The impact analysis results shown in Figure 13-19 on page 506 actually
contains eight results, but only seven derived objects were created when the
ItemPricePortType.wsdl was loaded into WSRR. The parameters object
appears twice in the impact analysis results due to the fact that this object can
be reached via two different branches of the object graph.
13.4.3 Analyzing dependencies between derived objects

Due to the large number relationships that can be traversed when performing
impact analysis on derived objects, it is not possible to provide examples for all of
them. We simply provide a single example that demonstrates how impact
analysis can be used to determine both inbound and outbound dependencies at
the same time using the Web user interface. In this example, we demonstrate
how to perform impact analysis on the getPrice WSDLOperation object to
determine which port type it is defined in and also which input and output
messages it defines. In order to do this, follow the steps described here:
2. In the navigation tree, expand Service Documents WSDL.
3. Click Operations.
4. In the list of operations, click the getPrice operation that has a Namespace
value of http://itso.ibm.com.
5. On the details view of the operation, click the Impact Analysis tab.
6. To determine which input and output messages this operation defines, we
must determine the outbound dependencies for the getPrice
WSDLOperation. Therefore, check the Include entities this entity depends
on check box.
507
7. To determine which port type this operation was defined in, we must
determine the inbound dependencies for the getPrice WSDLOperation.
Therefore, check the Include entities that depend on this entity check box.
analysis on WSDLOperation objects are described in Table 5-16 on page 231.
To determine which input messages the getPrice WSDLOperation defines,
select WSDL operation to input WSDL message from the Built-in
relationships list box.
9. To determine which output message the getPrice WSDLOperation defines,
select WSDL operation to output WSDL message from the Built-in
relationships list box.
10.To determine which port type the getPrice WSDLOperation was defined in,
select WSDL port type to WSDL operation from the Built-in relationships
list box, as shown in Figure 13-20.
Figure 13-20 Analyzing inbound and outbound dependencies for derived objects
11.Click OK.
12.The results are shown in Figure 13-21 on page 509.
508
Figure 13-21 Dependent objects for the getPrice WSDLOperation
509
510
14
Chapter 14.
Integrating WSRR with

WebSphere ESB
This chapter describes how to integrate WSRR with WebSphere Enterprise
Service Bus (WESB).
The following topics are covered:
14.2, WebSphere ESB overview on page 512
14.3, Structure of WebSphere Enterprise Service Bus on page 515
14.4, Related technologies on page 521
14.5, Endpoint Lookup mediation primitive on page 525
14.6, Managing access from WESB to WSRR on page 536
14.7, Integration scenario on page 543
511
14.1 Introduction
This chapter describes the use of WebSphere Service Registry and Repository
in an Enterprise Service Bus (ESB) environment, using WebSphere Enterprise
Service Bus (WESB) as the ESB implementation. Use of WSRR allows ESB
mediations that interact with some set of endpoint services to be more tolerant of
changes within the environment. This is enabled by the ESB using WSRR as a
dynamic lookup mechanism, providing information about service endpoints (the
service metadata). So, when changes occur in the service endpoint environment,
the associated ESB mediations do not have to change.
The interaction between WESB and WSRR is provided by a new primitive
introduced in WESB V6.0.2 called the Endpoint Lookup primitive.
This primitive can be used when building Mediation flows in WESB. It can call
WSRR to fetch service metadata and has caching mechanism to improve the
efficiency of the interaction.
Section 14.5, Endpoint Lookup mediation primitive on page 525 includes more
information about this new primitive and how it works.
14.2 WebSphere ESB overview

WebSphere Enterprise Service Bus delivers an Enterprise Service Bus (ESB)
infrastructure to enable inter-application connections with standards based
interfaces (typically a Web service interface described in a WSDL file). It provides
mechanisms to process request and response messages from service
consumers and service providers that connect to the ESB.
WebSphere Enterprise Service Bus is the mediation layer that runs on top of the
transport layer within WebSphere Application Server. As such, WebSphere
Enterprise Service Bus provides prebuilt mediation functions and easy-to-use
tools to enable rapid construction and implementation of an ESB as a value-add
on top of WebSphere Application Server.
Figure 14-1 on page 513 gives an overview of WebSphere Enterprise Service
Bus, the components in the product, and the features and functions that are
associated with the product.
512
Messaging:
MQ
Interoperability
Clients:
C++
Client
JMS 1.1
.Net
Client
Java and C/C++

Web Services
Client
WebSphere Enterprise Service Bus

Custom
Mediation
WebSphere
Integration
Developer
XSLT
Web
Services:
Message
Logger
Mediation
Function
Message
Router
DB
Lookup
WebSphere Application Server

Tivoli Access Manager
DB2 Universal Database
Edge Components
UDDI
Web Services Gateway
SOAP/
HTTP
WebSphere
Adapter
Support
SCA
Programming
Model:
SCA
SOAP/
JMS
WS-*
UDDI
Registry 3.0
SMO
SDO
Figure 14-1 WebSphere Enterprise Service Bus at a glance
WebSphere Enterprise Service Bus leverages WebSphere Application Server

Network Deployment qualities of service, with its clustering, failover, scalability,
security, and a built-in messaging provider. Along with these qualities,
WebSphere Enterprise Service Bus includes a number of key WebSphere
Application Server related features, including UDDI as a service registry, the
Web services gateway, Tivoli Access Manager, DB2 Universal Database, and
Edge components.
WebSphere Enterprise Service Bus adds the following value to the application
server:
Provides built-in mediation functions, which can be used to create integration
logic for connectivity.
The Service Component Architecture (SCA) programming model supports
rapid development of mediation flow components.
WebSphere Integration Developer is an easy-to-use tool that supports
Leveraging WebSphere Application Server, WebSphere Enterprise Service
Bus offers JMS messaging and WebSphere MQ interoperability for
messaging, as well as a comprehensive clients package for connectivity.
Offers support for J2EE Connector Architecture based WebSphere Adapters.
Chapter 14. Integrating WSRR with WebSphere ESB
513
To implement an SOA properly, it is necessary to have a single invocation model

and a single data model. Service Component Architecture (SCA) is this
invocation model every integration component is described through an
interface. These services can then be assembled in a component assembly
editor thus enabling a very flexible and encapsulated solution.
WebSphere Enterprise Service Bus introduces a new component type to the
SCA model the mediation flow component. From the perspective of the SCA,
a mediation flow component is not different to any other service component.
Business Objects are the universal data description. They are used as data
objects are passed between services and are based on the Service Data Objects
(SDO) standard. In WebSphere Enterprise Service Bus a special type of SDO is
introduced, the service message object (SMO).
14.2.1 Key terms in WebSphere Enterprise Service Bus

Table 14-1 summarizes the key terms that are introduced in this chapter in the
context of WebSphere Enterprise Service Bus.
Table 14-1 Key terms relating to WebSphere Enterprise Service Bus
514
Term
Explanation
Mediation
A service request interception by an ESB that

typically centralizes logic such as routing,
transformation, and data handling.
Mediation module
The basic building block in WebSphere Enterprise

Service Bus for creating mediations.
Export
Exposes the interfaces of a mediation module and

contains the bindings.
Stand-alone reference
The external publishing of an interface for SCA

clients only (without a WSDL description).
Import
Represents the service providers that are invoked

by a mediation module.
Binding
The protocols and transports that are assigned to

exports and imports.
Mediation flow component
The container for mediation logic inside a mediation

module that provides interfaces and that uses
references.
Interface
Defines access points and is defined using WSDL.
Term
Explanation
Operation
Represent interactions that can be 1-way (only input

parameters) and 2-way (input and output
parameters)
Partner reference
The declaration of the referenced interfaces of an

mediation flow component.
Wire
An association between components inside a

mediation module and exports/imports/stand-alone
references.
Mediation flow
The processing steps that are defined for each

interface in the form of a request flow and usually a
response flow.
Mediation primitive
Units of message processing inside a mediation

flow that provide different terminals.
Service message object (SMO)
A data object that represents the context, the

content, and the header information of an
application message that is created during a
mediation flow.
Business object
Data type definitions (specified in an XML schema)

that can be used for input/output parameters.
14.3 Structure of WebSphere Enterprise Service Bus

This section explores the structure of WebSphere Enterprise Service Bus by
working through the different layers of the product architecture in a top-down
manner.
14.3.1 Mediations, service consumers, and service providers

A service interaction in SOA defines both service consumers and service
providers. The role of WebSphere Enterprise Service Bus is to intercept the
requests of service consumers and fulfill additional tasks in mediations in order
to support loose coupling. When the mediation completes, the relevant service
provider(s) should be invoked. The mediation tasks include:
Centralizing the routing logic so that service providers can be exchanged
transparently
Performing tasks like protocol translation and transport mapping
515
Acting as a facade in order to provide different interfaces between service

consumers and providers
Adding logic to provide tasks such as logging
As shown in Figure 14-2, mediations customize the protocol and the details of a
request and also modify the results of the reply.
Figure 14-2 Enterprise Service Bus and mediations
WebSphere Enterprise Service Bus can interconnect a variety of different

service consumers and providers using standard protocols including:
JMS
SOAP over HTTP (for Web services)
SOAP over JMS (for Web services)
For back-end applications (such as SAP) several IBM WebSphere Adapters
(based on JCA) are available.
14.3.2 Mediation modules

The mediation module is a type of SCA component that can process or mediate
service interactions. As illustrated in Figure 14-3 on page 517, the mediation
module is externalized or made available through an export, which specifies the
interfaces that are exposed. These interfaces are defined in a WSDL document.
The mediation module typically invokes other service providers. These providers
are declared with the creation of an import, which represents an external service
to be invoked.
516
Figure 14-3 Mediation modules
For each export and import, an interface needs to be specified. Each interface
has multiple operations, which in turn can have multiple input and output
parameters that are associated with either simple data types or business objects.
Every export and import has to be associated with a binding. A binding identifies
a specific type of invocation for a service consumer or provider. WebSphere
Enterprise Service Bus supports several bindings:
Web Service bindings
Web Service bindings allow you to access Web services.
The supported protocols are SOAP/HTTP and SOAP/JMS.
SCA bindings
SCA bindings connect SCA modules to other SCA modules.
SCA bindings are also referred to as default bindings.
Java Message Service (JMS) 1.1 bindings
JMS bindings allow interoperability with the WebSphere Application
Server default messaging provider.
JMS can exploit various transport types, including TCP/IP and HTTP(S).
The JMS Message class and its five subtypes (Text, Bytes, Object,
Stream, and Map) are automatically supported.
WebSphere MQ JMS bindings
WebSphere MQ JMS bindings allow interoperability with WebSphere MQ
based JMS providers.
517
You might have WebSphere MQ JMS bindings if you want to use

WebSphere MQ as a JMS provider.
The JMS Message class and its five subtypes (Text, Bytes, Object,
Stream, and Map) are automatically supported.
WebSphere MQ bindings
WebSphere MQ bindings allow interoperability with WebSphere MQ.
You might have WebSphere MQ bindings if you want to communicate with
native WebSphere MQ applications.
You can use WebSphere MQ bindings only with remote queue managers
via a WebSphere MQ client connection; you cannot use them with local
queue managers.
WebSphere Adapter bindings
WebSphere Adapter bindings enable interaction with Enterprise
Information Systems (EIS).
Finally, data types (business objects) and interfaces can be defined at the
module level, but they can also be defined and referenced in libraries in order to
centralize them and to be able to reuse those artefacts.
14.3.3 Mediation flow components

Inside a mediation module there can be one mediation flow component.
Mediation flow components offer one or more interfaces and use one or more
partner references. Both get resolved, assigning them to exports or imports via
wires, as shown in Figure 14-4 on page 519.
In addition to the mediation flow component inside a mediation module, one or
more Java components can be created using custom mediation implementations.
14.3.4 Mediation flows

Mediation flows (Figure 14-4 on page 519) contain the high-level mediation logic.
In WebSphere Enterprise Service Bus, the processing of requests is separated
from processing of responses. Therefore, we distinguish between a request flow
and a response flow. In both directions, logic can be added or modifications can
be applied.
518
Figure 14-4 Mediation flows
Mediation flows consist of a sequence of processing steps that are executed

when an input message is received. A request flow begins with a single input for
the source operation and can have multiple callouts. If a message is to be
returned to the source directly after processing, it can be wired to an input
response in the request flow. If fault messages are defined in the source
operation, an input fault is also created. A response flow begins with one or more
callout responses and ends with a single input response (and optionally a callout
fault).
In terms of the actual data, WESB introduces the service message object (SMO).
SMO is a special kind of a service data object that represents the content of an
application message as it passes through a mediation flow component. As well
as the payload in the body, it contains context and header information, which can
be accessed and acted upon inside the mediation flows.
519
14.3.5 Mediation primitives

Mediation primitives (Figure 14-5) are the smallest building blocks in
WebSphere Enterprise Service Bus. They are wired and configured inside
mediation flows. They let you change the format, content, or target of service
requests; log messages; do database lookups; and so forth.
Figure 14-5 Mediation primitives (in the complete overview)
WebSphere Integration Developer and WebSphere Enterprise Service Bus

V6.0.2 provide the following standard mediation primitives:
The Message Logger primitive logs a copy of a message to a database for
future retrieval or audit. The integration developer can customize the primitive
by, for example, naming the database.
The Database Lookup primitive retrieves values from a database to add them
to a message.
The Message Filter primitive compares the content of a message to
expressions configured by the developer, and routes the message to the next
mediation primitive based on the result.
The XSL Transformations (XSLT) primitive transforms messages according to
transformations defined by an XSL style sheet.
520
The Fail primitive throws an exception and terminates the path through the
mediation flow.
The Stop primitive silently terminates the path through the mediation flow.
The Custom Mediation primitive allows the user to implement their own
mediate method using Java. The Custom mediation, like the other primitives,
receives a Service Message Object and returns a Service Message Object. It
can be used to perform tasks that cannot be performed by using the other
mediation primitives.
The Endpoint Lookup primitive dynamically routes the messages to
appropriate service endpoints. The primitive searches for service information
in WebSphere Service Registry and Repository. See section 14.5, Endpoint
Lookup mediation primitive on page 525 for more details.
The Event Emitter Mediation primitive emits business events from within a
mediation flow, if an event occurs.
The Message Element Setter primitive can be used to set the contents of
messages.
Mediation primitives have three types of terminal:
In terminal: All mediation primitives have an in terminal that can be wired to
accept a message.
Out terminal: Most mediation primitives have one or more out terminals that
can be wired to propagate a message (exceptions are the stop and the fail
primitive).
Fail terminal: If an exception occurs during the processing of an input
message, then the fail terminal propagates the original message, together
with any exception information.
14.4 Related technologies

This section explores some of the accompanying features of WebSphere
Enterprise Service Bus in more detail.
14.4.1 Service message objects

Messages can come from a variety of sources, so the payload has to be able to
carry a number of different types of messages. Mediation primitives need to be
able to operate on these messages, and service message objects (SMOs)
represents the common representation that is needed.
521
The types of messages that are handled by WebSphere Enterprise Service Bus
include:
SDO data object

SDO data graph
SCA component invocation message (request, reply or exception)
SOAP message
JMS message
The SMO model is extensible so it can support other message types in the
future, such as COBOL structures. SMO extends SDO with additional information
to support the needs of a messaging subsystem.
SMO structure
All SMOs have the same basic structure, defined by an XML schema. An SMO
has three major sections:
The body contains the application data (payload) of the message, particularly
the input or output values of an operation.
The headers contain the information relevant to the protocol used to send the
message.
The context covers the data specific to the logic of a flow or failure
information.
Figure 14-6 on page 523 shows a sample SMO when calling the ItemPrice
service which is used later in this chapter.
522
Figure 14-6 Sample SMO
Data section
The data that is carried in the SMO body is the operation that is defined by the
interface specification and the inputs/outputs/faults that are specified in the
message parts set in the business object definition (Figure 14-7 on page 524).
523
Figure 14-7 Content of the SMO body
Context section
The context includes the correlation and transient context information.
Correlation is used to maintain data across a request/response flow, while
transient maintains data only in one direction. Both of these contexts are used to
pass application data between mediation primitives. They are described as
business objects, which contain XML schema that are described data objects
and that are specified on the mediation flows input node properties.
The context includes the failInfo, which is added to the SMO when a fault
terminal flow is used. The information that is provided includes the
failureString (nature of the failure), origin (mediation primitive in which the
failure occurred), invocationPath (the flow taken through the mediation) and
predecessor (previous failure).
It also includes primitiveContext, which are used by primitives. EndpointLookup
primitive uses primitiveContext to adds zero or more EndpointLookupContext
to store service endpoints. See Figure 14-6 on page 523. In the future more
primitives will use primitiveContext to store context information.
Header section
The header section of a SMO contains the following supplemental information:
524
SMOHeader: information about the message (message identifier, SMO version)

JMSHeader: used when there is a JMS import or export binding
SOAPHeader: used when there is a Web services import or export binding
SOAPFaultInfo: contains information about SOAP faults
Properties[]: arbitrary list of name value pairs (for example JMS user
properties)
SMO manipulation
During the execution of mediation flows the active mediation primitives can
access and manipulate the SMO. There are three different ways to access
SMOs:
XPath V1.0 expressions
Many mediation primitives have a property called Root that contains an XPath
1.0 expression. The XPath expression represents the root of the current
mediation. Typically, you can specify: /, /body, /headers, or your own XPath
expression. / refers to the complete SMO, /body refers to the body section of
the SMO, /headers refers to the headers of the SMO. If you specify your own
XPath expression then the part of the SMO you specify is processed.
XSL stylesheets
Used by the XSLT mediation primitive and are the common way to modify the
SMO type within a flow. It can also be used to modify the SMO without
changing the type (using XSLT function and logical processing with XSL
choose statements).
Java code
Using the Custom Mediation primitive, you can access the SMO either using
the generic DataObject APIs (commonj.sdo.DataObject, which is loosely
typed) or the SMO APIs (com.ibm.websphere.sibx.smobo, strongly typed).
14.5 Endpoint Lookup mediation primitive

The Endpoint Lookup mediation primitive is used to dynamically route messages
to appropriate service endpoints. The Endpoint Lookup searches for service
information in WebSphere Service Registry and Repository (WSRR).
The Endpoint Lookup mediation primitive lets you retrieve service endpoint
information from a WSRR registry that can be local or remote. The service
endpoint information can relate directly to Web services or to Service
Component Architecture (SCA) module exports.
In order to use the Endpoint Lookup mediation primitive you might need to add
service endpoint information to your WSRR registry. If you want to extract service
endpoint information about Web services, then your WSRR registry must contain
the appropriate WSDL documents or SCA modules that contain exports using
Web service bindings. If you want to extract service endpoint information about
exports that use the default SCA binding, then your WSRR registry must contain
the appropriate SCA modules.
525
The Endpoint Lookup mediation primitive lets you retrieve service endpoint
information that relates to the following:
Web services using SOAP/HTTP.
Web services using SOAP/JMS.
Mediation module exports with Web service bindings, using SOAP/HTTP.
Mediation module exports with Web service bindings, using SOAP/JMS.
Mediation module exports with the default SCA binding.
When the Endpoint Lookup mediation primitive receives a message it sends a
search query to the registry. The search query is constructed using the Endpoint
Lookup properties that you specify and the query might return nothing, or might
return one or more service endpoints. You can choose whether to be informed of
all endpoints that match your query, or just one endpoint that matches your
query.
The Endpoint Lookup mediation primitive has one input terminal and three output
terminals. The input terminal is wired to accept a message and the output
terminals are wired to propagate a message. One of the output terminals is for
failure output. If an exception occurs during the processing of the input message,
then the fail terminal propagates the original message, together with any
exception information. If service endpoints are retrieved from the registry then
the out terminal propagates the original Service Message Object (SMO) modified
by the service endpoint information. If no services are retrieved from the registry
then the noMatch terminal propagates an unmodified message.
The Endpoint Lookup primitive as represented in the Mediation Flow Editor in
WebSphere Integration Developer is shown in Figure 14-8.
Figure 14-8 Endpoint Lookup primitive
Note: In order for the runtime to implement dynamic routing on a request, you
must set the Use dynamic endpoint property in the callout node. Optionally,
you can specify a default endpoint that the runtime uses if it cannot find a
dynamic endpoint. You specify a default endpoint by wiring an import that has
the default service selected.
526
14.5.1 Match policy

Figure 14-9 shows how to change the Match Policy for the primitive.
Figure 14-9 Endpoint Lookup primitive properties
If you specify an endpoint Match Policy of Return one matching endpoint, and
your registry query returns matches, then the dynamic callout address in the
SMO header is updated with one service address and the SMO context is
updated with registry information relating to that service.
If you specify an endpoint Match Policy of Return all matching endpoints, and
your registry query returns matches, then the SMO context is updated with
registry information relating to all services returned by the registry. The dynamic
callout address in the SMO header is not updated. Therefore, you need to
post-process the SMO to select a service endpoint.
The SMO context contains a primitiveContext element that is used for storing
state information. The Endpoint Lookup mediation primitive uses an element
within the primitiveContext, called EndpointLookupContext, to store the results
of WSRR queries. A number of service endpoints can be stored within the SMO
context. If you specify a Match Policy of Return one matching endpoint then the
Endpoint Lookup mediation primitive updates the SMO header at
/headers/SMOHeader/Target/address.
If you specify a Match Policy of Return all matching endpoints then you must
wire the Endpoint Lookup mediation primitive to another mediation primitive that
decides which endpoint to use, and moves endpoint information from the SMO
context to /headers/SMOHeader/Target/address.
527
14.5.2 Usage
You can use the Endpoint Lookup mediation primitive to dynamically route
messages based upon customer classification. For example, you might want
messages for customers of type A routed to URL X, and messages for customers
of type B routed to URL Y. If you set up your registry to key URLs against
customer types, then you can dynamically route customer requests according to
customer type.
You can use the Endpoint Lookup mediation primitive, together with other
mediation primitives, to add security to dynamic routing. For example, you could
use the Endpoint Lookup, Message Filter and XSLT mediation primitives to check
whether an endpoint was external or internal, and remove any internal
information from public messages. To do this you might wire the matching output
terminal of the Endpoint Lookup mediation primitive to the input terminal of the
Message Filter mediation primitive. You could then use the Message Filter
mediation primitive to check whether the URL was internal or external, and route
external messages to the XSLT mediation primitive: wire one of the Message
Filter output terminals to the XSLT mediation primitive. Lastly, you could use the
XSLT mediation primitive to remove private information from messages.
14.5.3 Properties
The Endpoint Lookup primitive fetches service metadata from WSRR based on
the properties specified in the primitive.
There are advanced properties which let you specify Classification and User
Properties. This enables you to search for objects that match a particular
classification. Also, you can search the registry for services that are annotated
with user defined properties. See Figure 14-10 on page 529.
528
Figure 14-10 Endpoint Lookup primitive advanced properties
The properties of the Endpoint Lookup primitive are described in Table 14-2 and
Table 14-3 on page 531. Refer to Figure 14-9 on page 527 and Figure 14-10 for
screen captures of the Endpoint Lookup primitive property pages in WebSphere
Integration Developer.
Table 14-2 Endpoint Lookup mediation primitive properties
Property
Description
Registry Name
This identifies the WSRR definition to be used by Endpoint

Lookup mediation primitive. A WSRR definition is created
using the server administrative console and provides
connection information for a WSRR instance. At least one
WSRR definition needs to exist on the server that your
mediation module is installed to. If the Registry Name is
absent then the default WSRR definition is used.
For details on how to configure WSRR Definitions in WESB,
see 14.6, Managing access from WESB to WSRR on
page 536.
529
Property
Description
Match Policy
If the registry has more than one service matching your query,
then the Match Policy determines how many service
endpoints should be added to the message. Specify Return
one matching endpoint to add only one match, and specify
Return all matching endpoints to add all matches. If you
choose a Match Policy of Return one matching endpoint
then the Endpoint Lookup mediation primitive selects the first
service returned from the registry. If you choose a Match
Policy of Return all matching endpoints then, typically, you
would wire the match output terminal of the Endpoint Lookup
to another mediation primitive. This is because if multiple
endpoints are returned, the SMO context is updated but the
dynamic callout address in the SMO header is not updated.
Therefore, you need to post-process the SMO to select a
service endpoint.
PortType Name
Search the registry for services that implement a particular

portType, the name of which is specified by PortType Name.
PortType Namespace

portType, the namespace of which is specified by PortType
Namespace. The PortType Namespace can be specified in
any valid namespace format. For example, URI or URN.
PortType Version

portType, the version of which is specified by PortType
Version.
User Properties
Search the registry for services that are annotated with user
defined properties.
Name
The name of the user defined property.
Type
The type of the user defined property. If the type is String then
what you specify as the Value is used as a literal, in the search
query. If the type is XPath then what you specify as the Value
must be an XPath expression. The XPath expression must
resolve to a unique leaf node in the inbound SMO. The value
of the leaf node is used in the search query.
Value
The value of the user defined property. This can be either a
literal value or an XPath expression, depending upon the Type
property.
530
Property
Description
Classification
Search for objects that match a particular classification. The

WSRR classifies objects using the ontology classification
system (OWL), in which each classifier is a class and has a
URI. OWL implements a simple hierarchical system. For
example, a bank account could start with the following details:
Account
o Identifier
o Name
- First name
- Second name
o Address
- First line of Address
- Second line of Address
Specifying a classification of Address matches any object
classified as Address, First line of address or Second
line of address.
Table 14-3 describes valid and default values for the properties of the Endpoint
Lookup primitive.
Table 14-3 Endpoint Lookup mediation primitive properties valid values and defaults
Property
Valid Values
Default
Registry Name
String
The default registry
Match Policy
String: Return one matching

endpoint or Return all matching
endpoint
One
PortType Name
String
PortType Namespace
String
PortType Version
String
User Properties - Name
String
User Properties - Type
String or XPath
User Properties - Value
Dependent on Type
Classification
List of URIs
531
14.5.4 Considerations
Consider the following when using the Endpoint Lookup mediation primitive:
If the Use dynamic endpoint property is not set in the callout node, then the
runtime will not use the dynamic endpoint in
/headers/SMOHeader/Target/address. In this case, the runtime uses the
default endpoint if there is one, or throws an error.
It is valid to specify no properties for an Endpoint Lookup mediation primitive,
other than the Match Policy. In this case, the default registry will be queried
for all applicable services.
You can use WSDL Web services loaded into the WSRR registry as a WSDL
file, or as a mediation module with an export using the Web service binding.
In either case, the Endpoint Lookup mediation primitive will search the
registry for WSDL Port objects that implement a PortType described by the
PortType properties. Any Classification or User properties specified on the
Endpoint Lookup need to be defined on the WSDL Port object within the
registry.
In the case of mediation modules that include an export using the default SCA
binding, the Endpoint Lookup mediation primitive searches the registry for
SCA Export objects that implement a PortType described by the PortType
properties. Any Classification or User properties specified on the Endpoint
Lookup need to be defined on the SCA Export object within the registry.
All PortType, Classification or User properties specified for an Endpoint
Lookup mediation primitive result in a query that combines all of these
properties using a logical AND.
If you want to use Classification URIs that include white space characters,
the correct URL encoding should be used. For example, a single character
space should be represented as %20.
White space characters provided in any of the Endpoint Lookup mediation
primitive properties will be treated as literal characters. They are not removed
by the Endpoint Lookup mediation primitive when querying the registry. For
example, if you specify a Classification property and the expected results
are not returned from a query, ensure there is no white space before or after
the Classification URI.
14.5.5 SOAP/HTTP example

The URI format in the case of an export with a Web service binding, is as follows:
http://<host>:<port>/<moduleName>/sca/<exportName>
532
The URI format in the general Web service case, (when a Web service is not
implemented by an export with a Web service binding), is as follows:
http://<host>:<port>/<service>
Consider the example WSDL in Example 14-1.
Example 14-1 SOAP/HTTP example WSDL

<wsdl:definitions name="SOAP_HTTPExport_BigEchoHttp_Service"
targetNamespace="http://big.com/Binding3"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:Port_0="http://big.com"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:this="http://big.com/Binding3"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<wsdl:import namespace="http://big.com" location="BigEcho.wsdl"/>
<wsdl:binding name="SOAP_HTTPExport_BigEchoHttpBinding"
type="Port_0:BigEcho">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="echo">
<soap:operation/>
<wsdl:input name="echoRequest">
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output name="echoResponse">
</wsdl:output>
<wsdl:fault name="BadBoyException">
<soap:fault name="BadBoyException" use="literal"/>
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="SOAP_HTTPExport_BigEchoHttpService">
<wsdl:port name="SOAP_HTTPExport_BigEchoHttpPort"
binding="this:SOAP_HTTPExport_BigEchoHttpBinding">
<soap:address
location="http://testhost:9080/RegistryWeb/sca/SOAP_HTTPExport"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
533
The port declaration contains a soap:address location of

http://testhost:9080/RegistryWeb/sca/SOAP_HTTPExport. This indicates that it
is an export with a Web service binding. To enable dynamic routing, update the
/headers/SMOHeader/Target/address field in the message with the location value
in the soap:address element.
14.5.6 SOAP/JMS example

The URI format in the case of an export with a Web service binding, is as follows:
jms:/queue?destination=jms/WSjmsExport&connectionFactory=jms/WSjmsExpor
tQCF&targetService=WSjmsExport_ServiceBJmsPort
The URI format in the general Web service case, (when a Web service is not
implemented by an export with a Web service binding), is as follows:
jms:/queue?destination=<destName>&connectionFactory=<factory>&targetser
vice=<service>
Consider the example WSDL in Example 14-2.
Example 14-2 SOAP/JMS example WSDL

<wsdl:definitions name="SOAP_JMSExport_BigEchoJms_Service"
targetNamespace="http://big.com/Binding4"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:Port_0="http://big.com"
xmlns:this="http://big.com/Binding4"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<wsdl:import namespace="http://big.com" location="BigEcho.wsdl"/>
<wsdl:binding name="SOAP_JMSExport_BigEchoJmsBinding"
type="Port_0:BigEcho">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/jms"/>
<wsdl:operation name="echo">
<soap:operation/>
<wsdl:input name="echoRequest">
</wsdl:input>
<wsdl:output name="echoResponse">
</wsdl:output>
<wsdl:fault name="BadBoyException">
<soap:fault name="BadBoyException" use="literal"/>
534
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="SOAP_JMSExport_BigEchoJmsService">
<wsdl:port name="SOAP_JMSExport_BigEchoJmsPort"
binding="this:SOAP_JMSExport_BigEchoJmsBinding">
<soap:address
location="jms:/queue?destination=jms/SOAP_JMSExport&;connectionFactory=
jms/SOAP_JMSExportQCF&;targetService=SOAP_JMSExport_BigEchoJmsPort"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
14.5.7 SCA default binding example

The URI format in the case of an export with the default SCA binding, is as
follows:
sca://<moduleName>/<exportName>
For services that use the SCA binding, the URI is never physically present in the
resources that define the service.
If using an Endpoint Lookup mediation primitive to retrieve endpoint information
about services using the SCA binding from a service registry, the Endpoint
Lookup will derive this URI from the information returned by the registry.
Consider the example SCDL in Example 14-3.
Example 14-3 Example SCDL

<scdl:export xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns1="http://big.com"
xmlns:scdl="http://www.ibm.com/xmlns/prod/websphere/scdl/6.0.0"
xmlns:wsdl="http://www.ibm.com/xmlns/prod/websphere/scdl/wsdl/6.0.0"
displayName="SCAExport" name="SCAExport">
<interfaces>
<interface xsi:type="wsdl:WSDLPortType" portType="ns1:BigEcho">
<method name="echo"/>
</interface>
</interfaces>
</scdl:export
535
14.5.8 Dynamic endpoint selection

You can route messages to an endpoint that is decided at runtime. The endpoint
that the runtime uses is located in the SMO header at
/headers/SMOHeader/Target/address. You can set this part of the SMO
manually, using various mediation primitives, but the Endpoint Lookup mediation
primitive can also set this location automatically.
In order for the runtime to implement dynamic routing on a request, you must set
the Use dynamic endpoint property in the callout node. See Figure 14-11.
You can specify a default endpoint for the runtime to use if it cannot find a
dynamic endpoint. You specify a default endpoint by wiring an import to a
reference.
Figure 14-11 Properties of callout node
14.6 Managing access from WESB to WSRR

It is required to create a WSRR definition in WebSphere ESB to establish a
connection between WESB and WSRR. You can create, configure, and view all
your WSRR access definitions using the WESB administrative console.
WebSphere ESB supports the use of the WSRR product, which allows the
storage and retrieval of services. WSRR is installed as an enterprise application
and provides a Web service interface that allows you to connect Endpoint
Lookup mediation primitives to a registry instance (as part of a mediation flow), to
look up services to invoke.
A WSRR definition and its connection properties is the mechanism used to
connect to a registry instance and look up a Web service to invoke.
536
14.6.1 Registry definitions

In the administrative console page, to view the list of Registry definitions click
Service integration WSRR definitions. You should see something similar to
Figure 14-12.
Figure 14-12 WSRR Definitions
537
This panel provides a list of WSRR definitions that have been created. To browse
or change the properties of a listed item, select its name in the list. You should
then see the detail view for the WSRR definition, as shown in Figure 14-13.
Figure 14-13 General Properties
14.6.2 General properties

WSRR definition name
This field is the unique name for this WSRR definition
Description
This is the description of this WSRR definition
Default WSRR definition
This indicates whether this WSRR definition is the default
538
Timeout of cache
This value sets the time (in seconds) after which the WSRR cache expires
and will be refreshed
The WSRR cache is used to maximize the performance of registry lookups.
There is one WSRR cache for each server, used to store services requested
by mediation modules on the server.
If a mediation module requests a new registry lookup, the service returned is
added to the cache and the timeout period started for that lookup. During the
timeout period, any more requests for the same lookup retrieve the service
from the cache. After the timeout period has expired, the next time the same
lookup is requested, the service is retrieved from the registry and refreshed in
the cache, and the timeout is reset.
The timeout for a lookup request is defined in the WSRR definition that the
mediation module uses for that request. Modules can use different WSRR
definitions that each define a different cache timeout for lookup requests.
If you want to clear the WSRR cache for a server, restart the server.
Connection type
This selects the type of connection for this WSRR definition
The connection type is set when the registry definition is created, and cannot
be altered. Currently, the only implemented choice is Web Service.
14.6.3 Connection properties

Connection properties can be seen by clicking on Connection Properties link
under Additional Properties. Figure 14-14 on page 540 shows the Connection
Properties panel.
539
Figure 14-14 Connection Properties
Registry URL
This is the URL to be used to connect to the WSRR Web service
Default: http://localhost:9080/WSRRCoreSDO/services/WSRRCoreSDOPort
If you want modules to use a WSRR Web service application on another
server or port number, change the server:port_number values in this URL.
If you are connecting to a secure WSRR, use https instead of http.
For example
https://ITSO-WSRR:9443/WSRRCoreSDO/services/WSRRCoreSDOPort
Authentication alias
This is the alias to be used to authenticate with the WSRR Web service if
security is enabled in WSRR.
The authentication alias corresponds to a user name and password that are
used for authentication.
You can use the list to select one of the existing WebSphere authentication
aliases. Otherwise, you can use the Other, please specify option in the list to
type another alias that you later define as a WebSphere authentication alias.
You can list and define WebSphere authentication aliases on the J2EE
Connector (J2C) authentication data entries panel - Security Global
security [Authentication] JAAS Configuration J2C Authentication
data.
540
For an example of a WSRR Definition, see 14.7.6, Configure WSRR definition in

WESB on page 568.
14.6.4 Connecting to a secure WSRR

Connecting to an instance of WSRR where security is on is not very different
from connecting to an unsecure WSRR. However, you will require some
additional steps to get it working.
1. Download APAR IC51354 from the ESB support site:
http://www.ibm.com/software/integration/wsesb/support/
2. Install it as described on the APAR download page.
3. Open the WESB administrative console. Select Security SSL to see the
list of SSL configuration repertoires as shown in Figure 14-15.
Figure 14-15 List of SSL configuration repertoire
4. Either use the default repertoire or create a new one to use the appropriate
keystore and truststore. Note down the name of repertoire.
5. Create a namespace binding in the admin console.
Select Environment Naming Name Space Bindings.
Ensure that your scope is Server level. Click New (as highlighted in
Figure 14-16 on page 542).
541
Figure 14-16 Name Space Bindings
6. See Figure 14-17 on page 543 for an example of the basic properties screen.
Select String from the list of Binding Types. Click Next.
7. In the field BInding Identifier, enter: myRepertoire
8. In the field Name in Name Space, enter: esb/endpointLookup/repertoire
9. In the field String Value, enter the name of repertoire you noted in step 4 on
page 541.
542
Figure 14-17 New binding
10.Click Next. Click Finish. Save the configuration changes.

11.Now you can create a WSRR definition. For more information about creating
a WSRR definition, see 14.7.6, Configure WSRR definition in WESB on
page 568.
14.7 Integration scenario

The integration scenario we are going to create is described in detail in
Chapter 12, Scenarios description on page 453.
543
IBM-ITSO Ltd uses a WSDL Port Type ItemPrice to describe the Interface
(Figure 14-18).
Figure 14-18 ItemPrice Interface
The ItemPriceService returns the normal price and is meant for General
customers. The ItemPriceDiscountedService returns the discounted price and
will serve Gold customers. Both services use the ItemPrice PortType but have
different endpoints.
14.7.1 Interaction between WESB and WSRR

WESB mediates the call from the service consumer to the service. It can fetch
endpoint information from WSRR and dynamically choose the service to call.
See Figure 14-19.
WebSphere Application
Server
WESB
Service
Consumer
Mediation
Module
ItemPriceService
WSRR
Figure 14-19 Interaction between WESB and WSRR
544
14.7.2 Scenarios
There are three integration scenarios between WESB and WSRR
1. Only one service. The service endpoint is in WSRR and WESB retrieves it.
This is most basic scenario. In this scenario, we use just one service. We
publish service metadata for only the ItemPriceService in WSRR.
We design a WESB Mediation Module to fetch metadata from WSRR for all
services that are using the ItemPrice port type. Since there is only one such
service available in WSRR, it will be retrieved. WESB then uses this retrieved
information to call the service.
2. There are 2 services. The service endpoints are in WSRR and WESB fetches
only one based on a User property.
In this case, we publish the metadata in WSRR for both services
(ItemPriceService and ItemPriceDiscountedService). We create a custom
property CustomerType in WSRR.
We design a WESB Mediation Module to fetch metadata from WSRR for all
services that are using the ItemPrice port type and have a user defined
property CustomerType with a given value. Since there is only one such
3. There are 2 services. The service endpoints are in WSRR. WESB fetches
both and the custom mediation decides which one to use.
(ItemPriceService and ItemPriceDiscountedService). We create a custom
We design a WESB Mediation Module to fetch, from WSRR, metadata for all
services that are using the ItemPrice port type. Since there are two such
services available in WSRR, both will be retrieved. WESB then uses an
additional primitive to choose between them and calls the service.
14.7.3 Setup
We used three physical machines for our WESB and WSRR integration
scenarios. All the boxes are running on Windows 2003 Server Service Pack 1.
Here are the details of the three boxes:
1. WID Server (ITSO-WESB) - It has WID V6.0.2 with the WESB 6.0.2
EmbeddedRuntime installed. It is used for development and deployment of
the Mediation module.
2. WSRR server (ITSO-WSRR) - It has WSRR V6.0.0.1 installed.
545
3. WebSphere Server (ITSO-WMB) - It has WebSphere Application Server

6.0.2.11 installed. It is used for deployment of the Web services.
3
1
Service
Consumer
ITSO-WESB
WID v6.0.2
W-ESB v6.0.2
ITSO-WMB

v6.0.2.11
ItemPriceService
ITSO-WSRR
WSRR v6.0 with FP1
Figure 14-20 Scenario setup
You do not need to have three machines to try these scenarios. You can install
these products on one or two machines depending on availability.
Note: Download the additional material for this redbook and extract it to some
suitable location, for example, C:. This path is referred as <lab-files> in the
remaining sections. See Appendix B, Additional material on page 877 for
details.
14.7.4 Installation of sample Web services

We start with installation of the scenario Web services (ItemPriceService and
ItemPriceDiscountedService) into WebSphere Application Server.
546
Open the WebSphere Application Server Admin Console, for example:

http://ITSO-WMB:9060/ibm/console
Login to the admin console by providing the user name as shown in
Figure 14-21.
Figure 14-21 WebSphere Admin Console login
547
Click Applications Install New Application from the navigation tree as

highlighted in Figure 14-22.
Figure 14-22 WebSphere Admin Console - Install New Application
548
In the Local File System - Specify path field click the Browse button (see
Figure 14-23). Select the
<lab-files>\ITSO\WSRR\WESB\WebServices\ItemPriceApp.ear file and click
Next.
Figure 14-23 WebSphere Admin Console - Install New Application wizard
Leave all the options as defaults and click the Next button on the next four
screens. Click the Finish button on the final screen.
Ensure that you get a message saying Application ItemPriceApp
installed successfully on the results page. Click the Save to Master
Configuration link and then click the Save button to save the changes to the
repository.
549
Click Enterprise Applications in the navigation tree. You should see a list of
installed applications similar to Figure 14-24. Ensure that ItemPriceApp is
there in the list of Application names. Select the ItemPriceApp application by
checking the check box next to it. Click the Start button in the top menu to
start the application.
Figure 14-24 WebSphere Admin Console - Application start
Note: Now, since the services (ItemPriceService and

ItemPriceDiscountedService) are deployed and running, you can change the
SOA lifecycle state of these service to Deploy. For more information about the
process to take these services through the service lifecycle in WSRR, refer to
13.2, Using lifecycles on page 476.
550
Click the ItemPriceApp application link to see the details. You should then see
a screen similar to Figure 14-25. Under Additional Properties on the right,
click the Publish WSDL files link.
Figure 14-25 WebSphere Admin Console - Application properties
Select ItemPriceApp_WSDLFiles.zip link as shown in Figure 14-26 and

download the zip file to the <lab-files>\ITSO\WSRR\WESB\WSDLs folder.
Figure 14-26 WebSphere Admin Console - Publish WSDL
551
Extract the zip file to the same folder and you should have a structure similar
to that shown in Figure 14-27.
Figure 14-27 Downloaded WSDL
Now you should have WSDL files for both services as shown in Figure 14-28.
Open each WSDL and examine the contents.
Figure 14-28 WSDL files
552
Note: We are using split WSDL for our scenario. There are two Web
services and there are two WSDLs for each service. One WSDL contains
the Port Type (ItemPricePortType.wsdl) and other one is for the service
and binding details.
Example 14-4 shows the Port Type defined in the ItemPricePortType.wsdl
WSDL file which can be found in the folder:
<lab-files>\ITSO\WSRR\WESB\WSDLs\ItemPriceApp.ear\ItemPriceWeb.war\W
EB-INF\wsdl
Notice that the name of the Port Type is ItemPrice.
Example 14-4 ItemPricePortType.wsdl

<wsdl:definitions xmlns:impl="http://itso.ibm.com"
xmlns:intf="http://itso.ibm.com"
xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"
targetNamespace="http://itso.ibm.com">
<wsdl:types>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://itso.ibm.com">
<element name="getPriceResponse">
<complexType>
<sequence>
<element name="getPriceReturn" type="xsd:int"/>
</sequence>
</complexType>
</element>
<element name="getPrice">
<complexType>
<sequence>
<element name="itemName" nillable="true"
type="xsd:string"/>
</sequence>
</complexType>
</element>
</schema>
</wsdl:types>
<wsdl:message name="getPriceResponse">
<wsdl:part element="impl:getPriceResponse" name="parameters"/>
</wsdl:message>
553
<wsdl:message name="getPriceRequest">
<wsdl:part element="impl:getPrice" name="parameters"/>
</wsdl:message>
<wsdl:portType name="ItemPrice">
<wsdl:operation name="getPrice">
<wsdl:input message="impl:getPriceRequest"
name="getPriceRequest"/>
<wsdl:output message="impl:getPriceResponse"
name="getPriceResponse"/>
</wsdl:operation>
</wsdl:portType>
</wsdl:definitions>
Example 14-5 shows the binding and the service defined in the
ItemPrice.wsdl WSDL file. Notice that the endpoint address is
http://ITSO-WMB:9080/ItemPriceWeb/services/ItemPrice.
Example 14-5 ItemPrice.wsdl

<wsdl:definitions targetNamespace="http://itso.ibm.com"
xmlns:impl="http://itso.ibm.com" xmlns:intf="http://itso.ibm.com"
xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
<wsdl:import namespace="http://itso.ibm.com"
location="ItemPricePortType.wsdl"/>
<wsdl:binding name="ItemPriceSoapBinding" type="impl:ItemPrice">
<wsdlsoap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="getPrice">
<wsdlsoap:operation soapAction=""/>
<wsdl:input name="getPriceRequest">
<wsdlsoap:body use="literal"/>
</wsdl:input>
<wsdl:output name="getPriceResponse">
<wsdlsoap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="ItemPriceService">
<wsdl:port name="ItemPrice" binding="impl:ItemPriceSoapBinding">
<wsdlsoap:address
location="http://ITSO-WMB:9080/ItemPriceWeb/services/ItemPrice"/>
554
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Examine the contents of folder
<lab-files>\ITSO\WSRR\WSDLs\ItemPriceApp.ear\ItemPriceDiscountedWeb.
war\WEB-INF\wsdl also. Notice that the endpoint address is
http://ITSO-WMB:9080/ItemPriceDiscountedWeb/services/ItemPriceDiscou
nted.
14.7.5 Publish the ItemPrice service to WSRR

The next step is to publish the WSDLs for one service (ItemPrice) in WSRR
using the WSRR Console.
Open the WSRR Console, for example:
http://ITSO-WSRR:9080/ServiceRegistry/
You should see something similar to Figure 14-29.
Figure 14-29 WSRR Console
555
Select Service Documents WSDL Documents from the navigation tree

as highlighted in Figure 14-30.
Figure 14-30 WSDL Documents option in WSRR console navigation tree
Click the Load document button on top menu as highlighted in Figure 14-31.
Figure 14-31 WSRR Console - Load Document
556
In the Local file system field (see Figure 14-32), click the Browse button and
select
<lab-files>\ITSO\WSRR\WSDLs\ItemPriceApp.ear\ItemPriceWeb.war\WEB-IN
F\wsdl\ItemPricePortType.wsdl.
In the Enter document description field, enter:
WSDL Port Type for ItemPrice service
Figure 14-32 Load Port Type WSDL
557
Click OK to complete the loading of the Port Type. You should then see a
confirmation message as shown in Figure 14-33.
Figure 14-33 WSRR Console - WSDL Document successfully loaded
558
Click the Content tab and review the contents. Notice that you can see WSDL
Port Type for your service (see Figure 14-34).
Figure 14-34 WSRR Console - WSDL Document contents
Come back to the Details tab and review other the sections given under the
headings Additional Properties and Relationships.
Load another WSDL document with service and binding details. Click Service
Documents WSDL Documents. Click the Load document button from
top menu.
559
In the Local file system field (see Figure 14-35), click the Browse button and
select
F\wsdl\ItemPrice.wsdl.
In the Enter document description field, enter: WSDL Service for
ItemPrice service
Figure 14-35 Load service WSDL
Click the OK button to complete the loading of the WSDL service.
560
Update/Add a Custom Property CustomerType to the Port

Come back to the Details tab and click the Service link under Additional
Properties as highlighted in Figure 14-36.
Figure 14-36 WSDL Document - Services
Click ItemPriceService in the list of Services to see the service details as

Figure 14-37 WSDL Document - Ports
561
Click Ports under Additional Properties as highlighted in Figure 14-38.
Figure 14-38 WSDL Document - Service Details
562
Alternatively, you can select ports from left side navigation tree. Select
Service Metadata WSDL Ports after loading the WSDL document (as
highlighted in Figure 14-39).
Figure 14-39 WSDL Ports
563
Click the ItemPrice port to see the details, as shown in Figure 14-40.
564
Click Custom Properties under Additional Properties (as highlighted in

Figure 14-41).
Figure 14-41 WSDL Port details
565
If you have created a custom notifier as described in 13.3.2, Developing a

customer notifier on page 486, you will see a property CustomerType in this
list and you just need to change its value to General. If you have not defined a
custom notifier, click the New button to create a new property (highlighted in
Figure 14-42).
Figure 14-42 Create new property
566
Enter CustomerType as the Key and General as the Value as shown in

Figure 14-43. Click the OK button.
Figure 14-43 Create new property values
567
The new property should now be listed as shown in Figure 14-44.
Figure 14-44 List of properties
14.7.6 Configure WSRR definition in WESB

Open WebSphere Integration Developer. Ensure that you are in the Business
Integration perspective by looking at the title bar as highlighted in
Figure 14-45. If you are not in the Business Integration perspective, select
Windows Open Perspective Other Business Integration OK.
Figure 14-45 WID - Business Integration perspective
568
The next step is to create a WSRR definition in WESB so that WESB knows
which instance of WSRR to access to get the service metadata. Select the
Servers view from the stack of views at the bottom right. Select WebSphere
ESB Server v6.0 by clicking on it.
Click the Debug icon on view menu bar (circled in Figure 14-46) or right-click
WESB server and select Debug from context menu to start the WESB server
in Debug mode.
Figure 14-46 Start WESB server in Debug mode
Wait for the WESB server to be started. You should get the message Server
server1 open for e-business in the console. Once it is started, right-click
WebSphere ESB Server v6.0 in the servers view again and select Run
administrative console as shown in Figure 14-47.
Figure 14-47 WESB - Open Admin Console
569
Provide the user id and click Log in. From the navigation tree on the left,
select Service integration WSRR Definitions as highlighted in
Figure 14-48.
Figure 14-48 WSRR Definitions
Click the New button to create a new WSRR definition (circled in

Figure 14-49).
Figure 14-49 New WSRR Definition
570
Provide the configuration details for your WSRR installation as shown in

Figure 14-50. In the WSRR definition name field, enter: ITSO-WSRR
In the Description field, enter: Service Metadata Registry for ITSO
In the Timeout of cache field, enter: 600.
Click Apply.
Figure 14-50 New WSRR Definition details
Click Connection properties under the heading Additional Properties.

Since we are using a secured WSRR, we need to specify an Authentication
alias also. As discussed in 13.1.5, Mapping users to roles on page 475, the
user wesb has been defined for all interactions between WESB and WSRR.
Click J2EE Connector Architecture (J2C) authentication data entries
under Related Items to see a list of Authentication aliases. Click New to
create a new Authentication alias.
571
As shown in Figure 14-51, in the Alias field, enter: WSRR

In the User Id field, enter: wesb
In the Password field, enter: <password for user wesb>
In the Description field, enter: User for WESB to WSRR interactions
Figure 14-51 New Authentication Alias
572
Specify the hostname or IP Address and port number of your WSRR server in
the Registry URL property (see Figure 14-52). Change http to https if you
are using a secure WSRR (see 14.6.4, Connecting to a secure WSRR on
page 541). Click OK.
Figure 14-52 WSRR server details
If you are connecting to a WSRR instance with security enabled, you need to
perform some additional steps. Refer to 14.6, Managing access from WESB
to WSRR on page 536 and Connecting to a secure WSRR on page 541 for
more information.
573
Click the Save link to save the changes as circled in Figure 14-53.
Figure 14-53 Save changes
Click the Save button to confirm.

You should see a newly created WSRR definition and it is the Default Registry
because we only have one definition. (See Figure 14-54)
Figure 14-54 New WSRR Definition
We could add more WSRR definitions and choose which one should be the
default. There can to be only one default WSRR definition. The default WSRR
definition is used when no definition is specified in the Endpoint Lookup
primitive in the WESB Mediation Module. You can now close the WESB
Admin Console.
14.7.7 Scenario 1: Dynamically fetch the service endpoint

Only one service. The service endpoint is in WSRR and WESB retrieves it.
574
This is most basic scenario. In this scenario, we just use one service. We publish
service metadata for only the ItemPriceService to WSRR.
We design the WESB Mediation Module to fetch, from WSRR, metadata for all
services that are using the ItemPrice port type. Since there is only one such
Select File New Project. Select Mediation Module and click Next, as
Figure 14-55 New Mediation module
575
Enter the Mediation Module name: Item as shown in Figure 14-56. Leave the
other options as they are. Click Finish.
Figure 14-56 Mediation module details
576
In the Business Integration view, select the Item module by clicking on it.
Select File Import. Select WSDL/Interface from the list of import sources
and click the Next button. In the Import from field, click the Browse button
and select the
F\wsdl folder. Click wsdl in the left panel. You should see the
ItemPricePortType.wsdl file in the right side panel. Select it by checking the
check box. Ensure that the Into module field has the Item module selected.
Click the Finish button. This is shown in Figure 14-57.
Figure 14-57 WSDL Import
577
In the Business Integration view, right-click the Assembly Diagram node.

Select Open or Open Open with Assembly Editor from the context
menu. You should now see the Assembly Editor as in Figure 14-58.
Figure 14-58 Open Assembly Diagram
578
Click the Mediation component Mediation1. Select the Properties view (lower
right pane). Select the Description tab and change the name to
ItemPriceMediation. (See Figure 14-59)
Figure 14-59 Mediation component
579
In the Assembly Diagram, Right-click ItemPriceMediation, select Add

Interface. In the Add Interface window, select the ItemPrice interface from
Matching interfaces and click the OK button (see Figure 14-60).
Figure 14-60 Add Interface to mediation component
Right-click again on the ItemPriceMediation mediation component and select

Add Reference. In the Add Reference window, select the ItemPrice
interface from Matching interfaces and click the OK button.
580
In the Assembly Diagram, right-click ItemPriceMediation and select

Generate Implementation. This is highlighted in Figure 14-61.
Figure 14-61 Generate Implementation
In the Generate Implementation window, click the OK button. You should

see the Mediation Flow Editor as shown in Figure 14-62. It shows the
Interface (ItemPrice) and the Reference (ItemPricePartner) with one
operation each.
Figure 14-62 Mediation Flow Editor
581
Hover the mouse over getPrice operation in ItemPrice interface. When the
tip of the yellow wire can be seen, drag the wire onto getPrice operation in
ItemPricePartner reference (see Figure 14-63).
Figure 14-63 Wire the operations
582
Click the newly created arrow. The bottom half of this editor is where the
Mediation flow will be designed. Notice that at the bottom left of the editor,
there are two tabs Request: getPrice and Response: getPrice. Ensure that
you are in the Request: getPrice tab. Right-click the getPrice: ItemPrice
callout and select Show in Properties. Select the Details tab and ensure
that the Use dynamic endpoint if set in the message header property is
checked (See Figure 14-64).
Figure 14-64 Dynamic callout property
In the Mediation Flow Editor, expand the palette on the bottom-left side of
the Editor and select the Endpoint Lookup icon (see Figure 14-65).
583
Click in the middle of the Editor to drop the new Endpoint Lookup primitive.
Click the new primitive and rename it to ItemPriceLookup as in Figure 14-66.
Figure 14-66 Rename primitive
Wire the out terminal of Input getPrice: ItemPrice to the in terminal of the
ItemPriceLookup primitive, Wire the out terminal of the ItemPriceLookup
primitive to the in terminal of Callout getPrice: ItemPricePartner as shown
in Figure 14-67.
Figure 14-67 Wiring
Right-click the ItemPriceLookup primitive and select Show in Properties.

(See Figure 14-68) Select the Details tab in the Properties view. In the
Name field (Port Type name), click the Browse button and select the
ItemPrice interface.
In the Registry Name field, enter: ITSO-WSRR (the name of the Registry
definition you created earlier in WESB)
Ensure that Match Policy is: Return one matching endpoint
Figure 14-68 Endpoint Lookup primitive configuration
584
Note: We have not specified the endpoint of the ItemPrice service

anywhere in the properties. The service endpoint is only stored in WSRR
and will be retrieved from there at runtime. If there is any change to the
endpoint in the future, it can be in done in WSRR without making any code
change or configuration in the Mediation module.
Select the Response: getPrice tab at the bottom left of the Mediation Flow
Editor. Wire the out terminal of Callout Response getPrice:
ItemPricePartner to the in terminal of Input Response getPrice: ItemPrice
as shown in Figure 14-69.
Figure 14-69 Wire response flow
Select File Save All.
585
Go to the Servers view. Right-click WebSphere ESB Server v6.0 and select
Add and remove projects. Select ItemApp from the list of Available projects
and click the Add button to add the project to the list of Configured projects
as highlighted in Figure 14-70. Click Finish.
Figure 14-70 Deploy project to WESB server
Wait for the console to confirm deployment with a message similar to

ApplicationMg A
586
WSVR0221I: Application started: ItemApp
14.7.8 Scenario 1 testing

Open the Assembly Diagram. Right-click ItemPriceMediation. Select Test
Component from the context menu. The ItemPriceMediation_Test tab will
be opened as in Figure 14-71. In the Initial request parameters, enter the
value for itemName: Item1.
Figure 14-71 Test input
587
Click the Continue button. In the Deployment Location window, select

WebSphere ESB Server v6.0 WebSphere ESB Server v6.0. Click
Finish. (see Figure 14-72)
Figure 14-72 Select deployment location
588
You should see 100 as the output in Return parameters as shown in

Figure 14-73.
Figure 14-73 Output
589
14.7.9 Publish ItemPriceDiscounted service metadata in WSRR

The next step is to publish WSDLs of the second service (ItemPriceDiscounted
service) in WSRR using the WSRR Console.
Open the WSRR Console, for example:
http://ITSO-WSRR:9080/ServiceRegistry/
You should see something similar to Figure 14-74.
Figure 14-74 WSRR Console
Select Service Documents WSDL Documents from the navigation tree

as highlighted in Figure 14-75.
Figure 14-75 WSDL Documents option in WSRR console navigation tree
590
Click the Load document button as circled in Figure 14-76.
Figure 14-76 WSRR Console - Load Document
591
In the Local file system field (as shown in Figure 14-77), click the Browse
button and select:
<lab-files>\ITSO\WSRR\WESB\WSDLs\ItemPriceApp.ear\ItemPriceDiscounte
dWeb.war\WEB-INF\wsdl\ItemPriceDiscounted.wsdl
In the Enter document description field, enter: WSDL Service for
ItemPriceDiscounted service
Figure 14-77 Load service WSDL
Click the OK button to complete the loading of the WSDL service.
592
Update/Add Custom Property CustomerType to the Port

Come back to the Details tab and click the Service link under Additional
Properties as circled in Figure 14-78.
Figure 14-78 WSDL Services
Click ItemPriceDiscountedService in the list of Services to see the service

details as shown in Figure 14-79.
Figure 14-79 WSDL Document - Services
593
Click Ports under Additional Properties (Figure 14-80).
Figure 14-80 WSDL Document - Service Details
Click the ItemPriceDiscounted port to see its details (circled in Figure 14-81).
594
Click Custom Properties under Additional Properties (circled in

Figure 14-82).
Figure 14-82 WSDL Port details
If you have created a custom notifier as described in 13.3.2, Developing a

customer notifier on page 486, you will see a property CustomerType in this
list and you just need to change its value to Gold. If you have not defined a
custom notifier, click the New button (circled in Figure 14-83) to create a new
property.
595
Enter CustomerType as the Key and Gold as the Value as shown in

Figure 14-84. Click the OK button.
596
The new property should now be listed in the list of properties as shown in
Figure 14-85.
Figure 14-85 List of properties
Now we have metadata for two services ItemPrice and ItemPriceDiscounted

published in WSRR.
14.7.10 Scenario 2: Fetch endpoint based on custom property

There are 2 services. The service endpoints are in WSRR and WESB fetches only
one based on a User property.
(ItemPriceService and ItemPriceDiscountedService). We also create a custom
services that are using the ItemPrice port type and have a user defined property
CustomerType with a given value. Since there is only one such service available in
597
WSRR, it will be retrieved. WESB then uses this retrieved information to call the
service.
This scenario is a continuation of the previous scenario.
In the Business Integration view, select the Item module by clicking on it.
Select File Import. Select WSDL/Interface from the import source list
and click the Next button. In the Import from field, click the Browse button as
circled in Figure 14-86.
Select the <lab-files>\ITSO\WSRR\WESB\EnquiryInterfaceWSDL folder. Click
EnquiryInterfaceWSDL in the left pane. Select ItemPriceEnquiry.wsdl by
checking the check box. Ensure that the Into Folder field contains Item. Click
Finish.
Figure 14-86 WSDL Import wizard
598
In the Business Integration View, click the + icon to expand the Item
Module. Expand Interfaces and double-click the ItemPriceEnquiry interface
to review it. Notice that it has customerType as one of the input parameters.
(see Figure 14-87).
Figure 14-87 ItemPriceEnquiry Interface
In the Assembly Editor, right-click the ItemPriceMediation component, and

select Show in Properties. In the Properties view, click the Details tab. Click
the + icon of the Interfaces to expand that section. Right-click the ItemPrice
interface and select Delete (shown in Figure 14-88).
Figure 14-88 Remove existing interface
In the Assembly Diagram, right-click ItemPriceMediation, select Add

Interface. In the Add Interface window, select the ItemPriceEnquiry
interface from Matching interfaces and click the OK button.
599
Right-click ItemPriceMediation and select Regenerate Implementation.

Press OK button to accept the replace warning.
You should see the Mediation Flow Editor as shown in Figure 14-89. It
shows the Interface (ItemPriceEnquiry) and the Reference
(ItemPricePartner) with one operation each. Hover the mouse over the
getPrice operation in the ItemPriceEnquiry interface. When the tip of the
yellow wire can be seen, drag the wire onto the getPrice operation in the
ItemPricePartner reference. Click the newly created arrow. (Figure 14-90 on
page 601).
Figure 14-89 Mediation Flow Editor
The bottom half of this editor is where the Mediation flow will be designed.
Notice that at the bottom left of the editor (Figure 14-90 on page 601), there
are two tabs Request: getPrice and Response: getPrice. Ensure that you
are in Request: getPrice tab. Right-click getPrice: ItemPrice callout and
select Show in Properties.
600
Select the Details tab and ensure that Use dynamic endpoint if set in the
message header property is checked as in Figure 14-90.
Figure 14-90 Dynamic callout
In the Mediation Flow Editor expand the palette on the bottom-left side of
the Editor and select the Endpoint Lookup icon (highlighted in
Figure 14-91). Click in the middle of the Editor to drop a new Endpoint Lookup
primitive.
601
Click the new primitive and rename it to ItemPriceLookup.
Figure 14-92 Rename primitive
From the palette, select the XSL Transformation icon (see Figure 14-93).
Click in the Editor to drop the new XSL Transformation primitive to the right of
the ItemPriceLookup primitive. Click the new primitive and rename it to
XSLTransformationRequest.
Figure 14-93 XSL Transformation primitive
Wire the out terminal of Input getPrice: ItemPriceEnquiry to the in

terminal of the ItemPriceLookup primitive. Wire the out terminal of the
ItemPriceLookup primitive to the in terminal of the XSLTransformationRequest
primitive. Wire the out terminal of the XSLTransformationRequest primitive to
the in terminal of Callout getPrice: ItemPricePartner (see Figure 14-94).
Figure 14-94 Wiring
602
Right-click the ItemPriceLookup primitive and select Show in Properties.

Select the Details tab in the Properties view (Figure 14-95). In the Name
field (Port Type name), click the Browse button and select the ItemPrice
interface.
In the Registry Name field, enter: ITSO-WSRR (the name of the Registry
definition you created earlier in WESB)
Ensure that Match Policy is set to: Return one matching endpoint
Figure 14-95 Endpoint Lookup primitive properties
Go to the Advanced tab. This tab can be used to specify the Classifications
and User Properties to filter the service that will be returned from WSRR.
603
Click the Add button in the User Properties section to open the Add/Edit
window (highlighted in Figure 14-96).
Figure 14-96 Advance properties
In the name field, enter: CustomerType (Figure 14-97).

Ensure that the Type field has XPath selected. Click the Custom XPath
button.
Figure 14-97 Add/Edit User Properties dialog
604
In the XPath Expression Builder window, you can see the schema of the
SMO which is passed to the mediation primitive. Click the + icon of body:
getPriceRequestMsg to expand it. Click the + icon of getPrice:
_getPriceParameters_. Click customerType: string to select it (circled in
Figure 14-98).
Figure 14-98 XPath Expression Builder
Click the OK button. In the Add/Edit window, click Finish. Select File Save
All.
605
Right-click the XSLTransformationRequest primitive and select Show in

Properties. Go to the Details tab. Click the New button to create a new XSLT
mapping (Figure 14-99).
Figure 14-99 New XSL Transformation
In the New XSLT Mapping window (Figure 14-100), leave the values as their
default values and click the Finish button.
Figure 14-100 New XSLT Mapping dialog
606
A new tab for the XSLTrasformation1_req_1.xmx mapping should be

displayed. Click the + icons to expand the Source and Target SMO trees in
the top left and top right panels. Expand both SMOs until you can see the
itemName nodes. Click the source SMO itemName node (left) and drag it onto
itemName in the target SMO (right) (Figure 14-101).
Figure 14-101 Mapping elements in XSLT Editor

Come back to the Mediation Flow Editor. Select the Response: getPrice tab
at the bottom left of the Mediation Flow Editor.
From the palette, select the XSL Transformation icon. Click in the middle of
the Editor to drop a new XSL Transformation primitive. Click the new
primitive and rename it to XSLTransformationResponse.
Wire the out terminal of Callout Response getPrice: ItemPricePartner to
in terminal of the XSLTransformationResponse primitive. Wire the out terminal
of the XSLTransformationResponse primitive to the in terminal of Input
Response getPrice: ItemPriceEnquiry (Figure 14-102).
Figure 14-102 Wiring
Right-click the XSLTransformationResponse primitive and select Show in

Properties. Go to the Details tab. Click the New button to create a new XSLT
mapping.
In the New XSLT Mapping window, leave the values as their default values
and click the Finish button.
A new tab for the XSLTrasformation1_res_1.xmx mapping should be
displayed. Click the + icons to expand the Source and Target SMO trees in
the top left and top right panels. Expand both SMOs until you see the
607
getPriceReturn nodes. Click the source SMO getPriceReturn node (left) and
drag it onto getPriceReturn in the target SMO (right) (Figure 14-103).
Figure 14-103 Mapping elements in XSLT Editor

and click the Add button to add the project to the list of Configured projects.
Click Finish. (Figure 14-104)
608
Wait for the console to confirm with the message similar to:
ApplicationMg A

be opened. In the Initial request parameters, enter the Value for itemName:
Item1. Enter the value for customerType: General (shown in Figure 14-105).
609

WebSphere ESB Server v6.0 WebSphere ESB Server v6.0
(Figure 14-106). Click Finish.
You should see 100 as the output in Return parameters (circled in

Figure 14-107).
Figure 14-107 Output
610
In the ItemPriceMediation_Test tab, scroll up and click the Invoke Icon to

retest the component (Figure 14-108).
Figure 14-108 Invoke button
In the Initial request parameters, enter the Value for itemName: Item1. Enter
the value for customerType: Gold (Figure 14-109).Click the Continue button.
You should see 90 as the output in Return parameters (Figure 14-110).
Add and remove projects. Select ItemApp from the list of Configured
611
projects and click the Remove button to remove the project from the list of
Configured projects. Click Finish.
14.7.12 Scenario 3: Use the Lookup primitive to get both endpoints

There are 2 services. The service endpoints are in WSRR. WESB fetches both and
the custom mediation decides which one to use.
(ItemPriceService and ItemPriceDiscountedService). We also create a custom
services that are using the ItemPrice port type. Since there are two such
services available in WSRR, both will be retrieved. WESB then uses an
additional primitive to choose between them and calls the service.
This scenario is a continuation of the previous scenario.
Open the Assembly Diagram. Right-click ItemPriceMediation and click
Open to open the Mediation Flow Editor. Click the arrow between the
ItemPriceEnquiry Interface and the ItemPricePartner reference.
The bottom half of this editor is where the Mediation flow will be designed.
Notice that at the bottom left of the editor, there are two tabs Request:
getPrice and Response: getPrice. Ensure that you are in the Request:
getPrice tab.
In the Mediation Flow Editor expand the palette on the bottom-left side of
the Editor and select the Custom Mediation icon (Figure 14-111).
Figure 14-111 Custom Mediation Lookup
612
Click in the Editor to drop a new Custom Mediation primitive to the right of the
ItemPriceLookup primitive. Click the CustomMediation1 primitive and rename
it to EndPointSelector (Figure 14-112).
Figure 14-112 Rename Custom Mediation primitive
Click the arrow between ItemPriceLookup and XSLTransformationRequest,

right-click and select Delete from the context menu (Figure 14-113).
Figure 14-113 Delete existing wiring
Wire the out terminal of the ItemPriceLookup primitive to the in terminal of

the EndPointSelector primitive. Wire the out terminal of EndPointSelector to
the in terminal of XSLTransformationRequest (as shown in Figure 14-114).
Figure 14-114 New wiring
613
Right-click ItemPriceLookup and select Show in Properties. Click the

Details tab. In the Match Policy field, select the Return all matching
endpoints option (Figure 14-115).
Figure 14-115 ItemPriceLookup properties
Select the Advanced tab. In the list of User Properties, select the
CustomerType property by clicking on it. Click the Remove button to remove
the property (Figure 14-116).
Figure 14-116 ItemPriceLookup advance properties
614
Select File Import. Select File system from the list of Import sources
and click the Next button. In the From directory field, click the Browse
button and select the folder <lab-files>\ITSO\WSRR\WESB\Code
(Figure 14-117).
Click the Code folder in the left panel. You should see
MyEndPointSelector.java on the right-hand side. Select it by clicking the
check box next to it.
In Into folder, enter: Item/com/ibm/itso. Click Finish.
Figure 14-117 Import Code
615
The Java class has been imported but it is not visible in the Business
Integration view. If you want to see the class, you can go to another view like
the Physical Resources view (shown in Figure 14-118).
Figure 14-118 Physical Resources view
The class contents are shown in Example 14-6.

Example 14-6 MyEndPointSelector.java
import java.util.Iterator;
import java.util.List;
import
import
import
import
import
com.ibm.websphere.sibx.smobo.EndpointLookupContextType;
com.ibm.websphere.sibx.smobo.RegistryPropertyType;
com.ibm.websphere.sibx.smobo.ServiceMessageObjectFactory;
com.ibm.websphere.sibx.smobo.TargetAddressType;
commonj.sdo.DataObject;
public class MyEndPointSelector {

public static DataObject setEndPoint(DataObject smo) {
String requiredPropName = "CustomerType";
String requiredPropValue =
smo.getString("/body/getPrice/customerType");
List services =
smo.getList("/context/primitiveContext/EndpointLookupContext");
System.out.println("EndPointSelector:: endpoint count: " +
services.size());
/* create an iterator to loop through the service data */
Iterator serviceIterator = services.iterator();
616
boolean finished = false;

while(!finished && serviceIterator.hasNext())
{
/* get the next service */
EndpointLookupContextType currentService =
(EndpointLookupContextType) serviceIterator.next();
String address =
currentService.getEndpointReference().getAddressElement().getValue();
System.out.println("EndPointSelector:: Endpoint is: " +
address);
/* retrieve all of the properties for the current service */
java.util.List properties =
currentService.getRegistryAnnotations().getProperty();
/* create an iterator to loop through the service properties*/
java.util.Iterator propsIterator = properties.iterator();
while(!finished && propsIterator.hasNext())
{
/* get the next property */
RegistryPropertyType currentProperty =
(RegistryPropertyType) propsIterator.next();
/* check if the current property is the one we want */
if(requiredPropName.equals(currentProperty.getName()))
{
/* check if this property has the correct value */
if(requiredPropValue.equals(currentProperty.getValue()))
{
/* create a new message target address element */
TargetAddressType targetAddress =
ServiceMessageObjectFactory.eINSTANCE.createTargetAddressType();
/* set this element to contain the current endpoint*/
System.out.println("EndPointSelector:: Selected
endpoint is: " + address);
targetAddress.setAddress(address);
/* update the dynamic callout header */
smo.set("/headers/SMOHeader/Target", targetAddress);
/* flag that we are done */
finished = true;
617
}
}
}
}
return smo;
}
}
Review the contents of class.
Go back to the Mediation Flow Editor. Right-click the EndPointSelector
primitive and select Show in Properties. Click the Details tab and ensure
that Java is selected as the Implementation option and / is selected in the
field Root (Figure 14-119).
In the text box given, enter:
return com.ibm.itso.MyEndPointSelector.setEndPoint(input);
Figure 14-119 Custom Mediation properties
618
and click the Add button to add the project to the list of Configured projects.
Click Finish (Figure 14-120).
Wait for the console to confirm deployment with a message similar to:
ApplicationMg A
619

be opened. In the Initial request parameters, enter the Value for itemName:
Item1. Enter the value for customerType: General (Figure 14-121).
620

WebSphere ESB Server v6.0 WebSphere ESB Server v6.0. Click
Finish. (Figure 14-122)
621
In the ItemPriceMediation_Test tab, scroll up and click the Invoke Icon to

retest the component (Figure 14-124).
Figure 14-124 Invoke button
In the Initial request parameters, enter the Value for itemName: Item1. Enter
the value for customerType: Gold. Click the Continue button (Figure 14-125).
Add and remove projects. Select ItemApp from the list of Configured
622
projects and click the Remove button to remove the project from the list of
Configured projects. Click Finish.
623
624
15
Chapter 15.
Integrating WSRR with

ITCAM for SOA
This chapter introduces the challenge of SOA management and the role
WebSphere Service Registry and Repository plays in that scope. It also
describes the integration capabilities between WebSphere Service Registry and
Repository and IBM Tivoli Composite Application Manager for SOA (ITCAM for
SOA) and provides a working example of this integration.
15.1, SOA management and WSRR on page 626
15.2, IBM Tivoli IT Service Management on page 631
15.3, IBM Tivoli solutions for SOA management on page 633
15.4, IBM Tivoli Composite Application Manager for SOA on page 640
15.5, WSRR and ITCAM for SOA integration scenarios on page 654
15.6, Discovery and display of service information on page 654
15.7, Service status information forwarding on page 677
15.8, Discovery and display of service information: working example on
page 692
15.9, Forwarding service status information - working example on page 727
625
15.1 SOA management and WSRR

This section provides an introduction to the challenges of SOA management and
relates them to WSRR and its role in this domain. It also outlines the approach,
architecture and products used by IBM Tivoli to address this problem space.
15.1.1 Introduction to SOA management

Within the SOA solution domain, business processes increasingly depend on
integrated services that form multi-tier, composite applications. Composite
applications often span architectural layers including service consumers,
business processes, services, service components, and operational systems.
SOA management includes solutions and software for managing and monitoring
SOA composite applications and the supporting infrastructure. In this section, we
highlight the challenges for SOA management:
Monitoring end-to-end view of composite applications

Understanding the relationship of services
Managing services as resources
Ensuring nonfunctional requirements are achieved by design
Monitoring end-to-end view of composite applications

In a silo-based application architecture, resources are often managed by
separate operators or specialists, by using separate management consoles.
Composite applications require a mind shift in the management approach. There
is a need for monitoring and management tooling that covers the end-to-end view
of the composite application, as well as for providing detailed information about
performance and availability metrics for the individual resources. Also, the
operator should have an end-to-end monitoring role.
Figure 15-1 on page 627 illustrates the multi-tiered and heterogeneous nature of
composite applications in an SOA. It clearly emphasizes the three dimensions of
composite application management and monitoring.
1. end to end resource monitoring: resources range from hardware appliances
located at the edge of the network to applications, middleware infrastructure
and existing back-end systems, which implies different technologies and
monitoring capabilities.
2. end to end services and transactions: service interactions span multiple layers
of an SOA (from the consumers to the providers perspective) and respective
transactions must be correlated to truly understand the runtime behavior of
composite applications.
626
3. applications, services and relationships: applications and the services they

exhibit and use are linked and rely on each other to deliver the functions of
composite applications. These relationships must be understood and
materialized in the management perspective and tooling to monitor, diagnose
and troubleshoot the overall SOA.
Services & Transactions

Applications
Resource Monitoring
Figure 15-1 Composite Application consisting of several different types of components
Understanding the relationship of services

It is important to understand the relationship of service consumers and providers
for composite applications. SOA brings the benefits of application reuse. The
importance of monitoring and managing the availability and performance of the
application functionality exposed as a service increases when reused by service
consumers that depend on this functionality.
For example, in a silos approach each application can have its own tax
calculation application functionality. In an SOA composite application, the tax
calculation can be exposed and consumed as a common service. This common
service has the benefits of flexibility, reuse, cost savings, and so on, but also has
increased dependency and must be monitored and managed accordingly.
Managing services as resources

To achieve the quality of service (QoS) defined by the business, each service
endpoint should be managed as a resource. This includes the invocation of
services (service consumer) as well as the application functionality exposed as a
service (service provider).
Managed services should have real time availability and performance metrics,
and a defined service-level agreement. Like other resources, services are
Chapter 15. Integrating WSRR with ITCAM for SOA
627
deployed, configured, versioned, monitored, managed, secured and audited.

When down, the management tooling should provide a means of
troubleshooting, and, better still, a method of monitoring and alerting of issues
before failure.
However, it is key to recognize services as a higher level of abstraction than
traditional system resources to stress SOA specific aspects of IT management.
The service definition should be driven from business context. This close
relationship implies that whatever situation the service goes through has a
direct consequence to the way the business is operating. It is therefore of
prime importance to consider services as enterprise assets with strong
management and monitoring requirements.
A service is meant to hide the technical implementation of a function from
requestors, and expose a higher-level context. However, from a management
perspective a service is really a collaboration of underlying resources such as
applications, servers, repositories... Managing services implies a thorough
understanding of these interactions and dependencies so that to track
outages and malfunctions down to the cause. In essence, managing services
forces us to reconsider the notions of application and infrastructure and the
boundary between these
Ensuring nonfunctional requirements are achieved by design

SOA management is used to ensure nonfunctional requirements of the IT
architecture are aligned with the business objectives. Monitoring and
management of the composite applications and associated services should
include specific metrics to ensure business objectives are met.
This directly translates into the following key elements:
Contracts are established between service consumers and providers, also
known as Service Level Agreements (SLA). These contracts formally specify
the expectations, capabilities and agreements from the consumers and
providers perspectives.
Services are measured against these contracts using key performance
indicators (KPIs) in order to directly align their IT behavior to business
measures. Management focus turns to monitoring for compliance to agreed
upon service levels.
Active management optimizes service providing systems to avoid service
violations and outage in business operations.
628
15.1.2 Managing the SOA Foundation architectural layers

The SOA Foundation reference architecture solution view includes architectural
layers as seen in Figure 15-2. We explain how the resources for these
architectural layers are managed in an SOA environment. In some cases, the
monitoring spans the architectural layers. In others, it is focused on monitoring
specific resources within the layers.
Channel
B2B
atomic and composite
Service Provider
Service Components
Operational Systems
Packaged
Application
Atomic Service
Custom
Application
Composite Service
Governance
Services
Data Architecture (meta-data) &

Business Intelligence
Business Process
Composition; choreography;
business state machines
QoS Layer (Security, Management &

Monitoring Infrastructure Services)
Integration (Enterprise Service Bus)
Service Consumer
Consumers
OO
Application
Registry
Figure 15-2 SOA Foundation reference architecture solution view
Refer to 1.1.4, SOA reference architecture model on page 11 for additional

information about the SOA reference architecture.
Managing services
The management of services includes service consumers and service providers.
Service consumers invoke services, while service providers expose application
functions to be consumed. For example, both a J2EE Web Services client
application (service consumer) and an session EJB Web service (service
provider) can be monitored and managed.
Some key elements of managing the services layer are listed here:
Understand how services relate to each other and to the IT infrastructure, as
well as how the service relates to the business process layer.
629
Control the message flow in the service environment through management

mediations such as log, filter, and route. The message flow often spans the
architectural layers.
Centralize services management policy.
Define business-related IT goals.
Note: Business processes are managed indirectly in that the services that
make up the business processes are managed resources. It is very important
to understand the relationship of service providers and consumers. This also
includes understanding the impact to the business process or business
service.
Managing transactional performance

Managing and monitoring the end-to-end transactional performance is a key
measurement for SLAs. Managing transaction performance is also a very useful
analysis and troubleshooting tool. For example, you can be proactive in detecting
a slow down in performance before it becomes a critical problem that stops the
transaction from being completed. Also, a view of the transactional performance
can be very helpful for troubleshooting to isolate the resources that are not
performing or failing.
Managing transactional performance includes the following:
Understand the performance of a service and the decomposition of
transactions with specific metrics for individual requests.
Provide the relationship between service requests and the implementation
artefacts such as J2EE beans and JDBC requests.
Managing the supporting middleware

Many of the resources used by services are found in the middleware. For
example, WebSphere Application Server application servers are used to host
J2EE and Web Services applications. DB2 UDB is used to host databases. IBM
WebSphere MQ is used for messaging. Each of these resources should be
managed and monitored.
Managing the supporting middleware includes the following concepts:
Understanding the health of the infrastructure that supports the services.
Correlating problems in the services to infrastructure issues such as a queue
filling up or an exhausted thread pool.
630
Managing the operational systems

SOA environments are built using real resources and those resources must also
be managed. Managing the operational systems includes the following concepts:
Understand the health of the infrastructure that support the services.
Correlate problems in the services to infrastructure issues such as a queue
filling up or an exhausted thread pool.
Note: Within the SOA Foundation scenarios, SOA security has been defined
as a separate solution area from SOA management. Some organizations may
view SOA security as part of the SOA management domain. For the purposes
of this chapter, we do not cover SOA security.
For more information about SOA security, refer to the following IBM Redbook:
Understanding SOA Security Design and Implementation, SG24-7310
15.1.3 The role of a service registry and repository in SOA

management
Refer to Service registry and repository in SOA management on page 36 for
more information.
15.2 IBM Tivoli IT Service Management

IBM IT Service Management helps organizations better manage their IT
infrastructure to more effectively and efficiently deliver IT services. IBM IT
Service Management is comprised of the following elements as seen in
IT Process Management products
IT Service Management platform
Note: SOA management tooling can be found within the scope of the IT
Service Management platform. We will highlight the products defined in the
IT Service Management platform for SOA management in 15.3, IBM Tivoli
solutions for SOA management on page 633.
IT Operational Management products
631
IT Process
Management
IT Process
Management Products
IT Service
Management Platform
IT Operational
Management Products
Best Practices
Figure 15-3 IBM IT Service Management
Some of the key capabilities provided by IBM IT Service Management are:
ITIL-aligned workflows, based on WebSphere Process Server

Open and standards-based Configuration Management Database (CMDB)
Automated, infrastructure-aligned tasks
Best Practices and Implementation Support
Note: To find more information, visit these Web sites:
IBM IT Service Management
http://www.ibm.com/software/tivoli/features/it-serv-mgmt/
Information Technology Infrastructure Library (ITIL)

ITIL began as a series of reference books and has evolved into an
important standard for IT service management best practices. The intent of
ITIL is to align your Information Technology with your business
requirements, improve service quality, and lower the long-term cost of IT
service provision. These concepts are consistent with the objectives of an
SOA. More information about ITIL can be found at this Web site:
http://www.ibm.com/software/tivoli/features/it-serv-mgmt/ITIL.html
632
15.3 IBM Tivoli solutions for SOA management

Note: The purpose of this section is not to provide a detailed description of
IBM Tivoli solutions for SOA management but rather to give an overview of its
main constituents. For more information about the IBM Tivoli Composite
Application Manager family of products, refer to the redbook IBM Tivoli
Composite Application Manager V6.0 Family: Installation, Configuration, and
Basic Usage, SG24-7151.
Typically composite applications consist of many components including Web
servers, application servers, database servers, and back-end systems such as
CICS and IMS running on mainframe systems. Traditional application
monitoring tools provide the ability to observe each individual system layer but do
not provide a way to perform end-to-end monitoring of the entire application.
Figure 15-4 shows the complete Tivoli solution portfolio for storage, security, and
systems management.
Business Service Management

Orchestration and Provisioning
Storage
Security
Event Correlation and Automation

Composite Application Management
Resource Monitoring
Figure 15-4 IBM Tivoli solution stack for security, storage and system management
The complete system management solution stack offers the following features:
Resource Monitoring
Measuring and managing IT resource performance including servers,
databases, and middleware.
633
Composite Application Management

Monitoring and managing an application and its components and providing a
view on application availability.
Event Correlation and Automation
Correlates and automates events or faults that are generated by resource
monitoring and application monitoring to provide information about root-cause
analysis of failure in the environment.
Orchestration and Provisioning
Provides the ability to deploy components as required to fulfill processing
needs, if the need arises as indicated by the correlation engine.
Business Services Management
Provides a high-level view of business status as reflected by its underlying
monitoring components. The view can either be in real time or based on a
service level agreement (SLA).
15.3.1 IBM Tivoli Composite Application Manager

IBM Tivoli Composite Application Manager is the name for a suite of Tivoli
monitoring products that are positioned for performance monitoring and
management of composite applications.
The IBM Tivoli Composite Application Manager suite consists of the following
products:
IBM Tivoli Composite Application Manager for Response Time Tracking
Proactively recognizes, isolates, and resolves transaction performance
problems
IBM Tivoli Composite Application Manager for SOA
Monitors and manages the Web services layer of an IT architecture
Note: For more information about ITCAM for SOA refer to the following:
15.4, IBM Tivoli Composite Application Manager for SOA on page 640
This section provides a more detailed look at the features provided by
ITCAM for SOA.
15.8, Discovery and display of service information: working example
on page 692
This section includes a working example scenario for using ITCAM for
SOA in collaboration with WSRR to manage, monitor services and
provide operational feedback.
634
IBM Tivoli Composite Application Manager for WebSphere

Can isolate the root cause of bottlenecks in a WebSphere application runtime
environment
IBM Tivoli Composite Application Manager for CICS Transactions
Provides data from CICS systems to be used in ITCAM for response time
tracking
IBM Tivoli Composite Application Manager for IMS Transactions
Provides data for IMS systems to be used in ITCAM for response time
tracking
OMEGAMON XE for WebSphere Business Integration
Monitors WebSphere MQ family runtimes and provides automatic corrective
actions to improve performance and availability
Table 15-1 lists the mapping between the new IBM terminologies and the
previous Candle terminology. It is worth noting that in the documentation
slightly differing Candle terminologies may mean the same in the IBM
terminologies.
Table 15-1 Mapping between new IBM terminology and previous Candle terminology
IBM Tivoli terminology
Candle/OMEGAMON terminology
IBM Tivoli Monitoring Services
OMEGAMON Platform
IBM Tivoli Monitoring
OMEGAMON for distributed products
Tivoli Enterprise Monitoring Server
Candle Management Server (CMS)
Tivoli Enterprise Monitoring Agent
Tivoli Enterprise Portal Server
CandleNET Portal Server
Tivoli Enterprise Portal
CandleNET Portal
Situation Event Console
Enterprise Event Console/Event Console
Candle Management Workstation
Database
Candle Data Warehouse
Note: Additional information about the ITCAM family of products can be found
in IBM Tivoli Composite Application Manager family products on page 872.
635
15.3.2 IBM Tivoli Enterprise Monitoring framework

The ITCAM products are designed to work together within one framework, called
the IBM Tivoli Enterprise Monitoring framework. The framework is depicted in
Figure 15-5.
Figure 15-5 Components of the IBM Tivoli Enterprise Monitoring framework
Tivoli Enterprise Monitoring Server (TEMS)

The Tivoli Enterprise Monitoring Server (or monitoring server) is the initial
component to install to begin building the IBM Tivoli Monitoring Services
foundation. It is the component on which all other architectural components
depend. The TEMS acts as a collection and control point for alerts received from
agents, and collects their performance and availability data. The TEMS is
responsible for tracking the heartbeat request interval for all Tivoli Enterprise
Management Agents connected to it.
The TEMS stores, initiates, and tracks all situations and policies, and is the
central repository for storing all active conditions and short-term data on every
636
Tivoli Enterprise Management Agent. Additionally, it is responsible for initiating

and tracking all generated actions that invoke a script or program on the agent.
The TEMS stores its data in a collection of log files, which can be persisted in a
relational database.
The primary TEMS is configured as a hub. All IBM Tivoli Monitoring installations
require at least one TEMS configured as a hub. Additional remote TEMS can be
installed later to introduce a scalable hierarchy into the architecture.
This hub/remote interconnection provides a hierarchical design that enables the
remote TEMS to control and collect its individual agent status and propagate the
agent status up to the hub TEMS. This mechanism enables the hub TEMS to
maintain infrastructure-wide visibility of the entire environment. This visibility is
passed to the Tivoli Enterprise Portal Server for formatting, ultimately displaying
in the Tivoli Enterprise Portal client.
Tivoli Enterprise Portal Server (TEPS)

The Tivoli Enterprise Portal Server, also known as portal server, is a repository
for all graphical presentation of monitoring data. The portal server database also
consists of all user IDs and user access controls for the monitoring workspaces.
The TEPS provides the core presentation layer, which allows for retrieval,
manipulation, analysis, and formatting of data. It manages this access through
user workspace consoles. The TEPS keeps a persistent connection to the hub
TEMS, and can be considered a logical gateway between the hub TEMS and the
Tivoli Enterprise Portal client. Any disconnection between the two components
immediately disables access to the monitoring data used by the Tivoli Enterprise
Portal client.
A database must be installed on the same host prior to the TEPS installation.
This prerequisite is necessary because the TEPS installation will create the
required TEPS database, along with the supporting tables. Also, an ODBC (data
source name) is configured to connect directly to the Tivoli Data Warehouse
database. This ODBC connection is used whenever a pull of historical data from
the Tivoli Data Warehouse is requested.
Tivoli Enterprise Portal clients

The TEP client (referred to as the portal client) is a Java-based user interface
that connects to the Tivoli Enterprise Portal Server to view all monitoring data
collections. It is the user interaction component of the presentation layer. The
TEP brings all of these views together in a single window so you can see when
any component is not working as expected. There are two TEP clients, namely,
the Java desktop client and an HTTP browser client.
637
To invoke the browser-based TEP client, use the URL:

http://<hostname>:1920/cnp/kdh/lib/cnp.html
Where <hostname> is the host name of the Tivoli Enterprise Portal Server.
The following products have integrated interfaces into the TEP:
OMEGAMON z/OS
OMEGAMON Distributed
IBM Tivoli Monitoring 5.1.2
IBM Tivoli Monitoring 6.1
NetView for z/OS (release 5.2)
IBM Tivoli Enterprise Console
IBM Tivoli Composite Application Manager for Response Time Tracking
This means that a consolidated view of a composite application has been made
available through a single client.
Tivoli Enterprise Monitoring Agent (TEMA)

The Tivoli agents are installed on the systems or subsystems requiring data
collection and monitoring. The agents are responsible for data gathering and
distribution of attributes to the monitoring servers, including initiating the
heartbeat status.
Note: Monitoring applications are identified by product code, a three-letter
identifier that starts with the letter K. Some identifiers are:
KUM: Universal Agent

KNT: Windows operating system monitoring
KD4: ITCAM for SOA
KYN: ITCAM for WebSphere
KT2: ITCAM for RTT
These agents test attribute values against a threshold and report these results to
the monitoring servers. The TEP displays an alert icon when a threshold is
exceeded or a value is matched. The tests are called situations.
When a portal workspace is opened or refreshed, the TEPS sends a sampling
request to the hub TEMS. The request is passed to the monitoring agent if there
is a direct connection or through the remote TEMS to which the monitoring agent
connects. The monitoring agent takes a data sampling and returns the results
through the monitoring server and portal server to the portal workspace.
638
The sampling interval for a situation (a test taken at your monitored systems) can
be as often as once per second or as seldom as once every three months. When
the interval expires, the monitoring server requests data samples from the agent
and compares the returned values with the condition described in the situation. If
the values meet the condition, the icons change on the navigation tree.
Optionally, the agents can be configured to transfer data collections directly to
the Warehouse Proxy agent instead of using the remote TEMS. If firewall
restrictions are disabled or minimal, you should configure all the agents to
transfer directly to the Warehouse Proxy agent. Otherwise, firewall security is a
key factor in the location of the Warehouse Proxy agent respective to the firewall
zone and agents. Warehousing data through the remote TEMS is limited and
should be used only as a last resort.
Tivoli Enterprise Management Agents are grouped into two categories:
Operating system (OS) agents
Operating system agents retrieve and collect all monitoring attribute groups
related to specific operating system management conditions and associated
data.
Application agents
Application agents are specialized agents coded to retrieve and collect unique
monitoring attribute groups related to one specific application. The monitoring
groups are designed around an individual software application, and they
provide in-depth visibility into the status and conditions of that particular
application.
Common management agents packaged with IBM Tivoli Monitoring include:
Window OS Agent
Linux OS Agent
UNIX OS Agent
UNIX Log Agent
i5 OS Agent
Universal Agent
The Universal Agent is a special agent that leverages an API to monitor and
collect data for any type of software. The Universal Agent can monitor and
retrieve data from any application that produces data values. Essentially, IBM
Tivoli Monitoring can now monitor any unique application regardless of whether
the base product supports it.
Common optional management agents that are packaged separately include:
Monitoring Agent for IBM Tivoli Monitoring 5.x Endpoint
DB2 Agent
639
Oracle Agent
MS SQL Agent
MS Exchange Agent
Active Directory Agent
Tivoli Data Warehouse (TDW)

The Tivoli Data Warehouse is the database storage that contains all of the
historical data collection. A Warehouse Proxy must be installed to leverage the
TDW function within the environment. In large-scale deployments, a Tivoli Data
Warehouse can be shared among monitoring installations.
Tivoli Data Warehouse Proxy agent

The Warehouse Proxy agent is a unique agent that performs only one task:
collecting and consolidating all historical data collections from the individual
agents to store in the Tivoli Data Warehouse. If using the Tivoli Data Warehouse,
one Warehouse Proxy agent is required for each IBM Tivoli Monitoring
installation. It uses ODBC to write the historical data to a supported relational
database.
Warehouse Summarization and Pruning Agent

The Summarization and Pruning agent is a unique agent that performs the
aggregation and pruning functions for the historical raw data on the Tivoli Data
Warehouse. It has advanced configuration options that enable exceptional
customization of the historical data storage.
One Summarization and Pruning agent is recommended to manage the
historical data in the Tivoli Data Warehouse. Due to the tremendous amounts of
data processing necessary, we recommend that the Summarization and Pruning
agent always be installed on the same physical system as the Tivoli Data
Warehouse repository.
15.4 IBM Tivoli Composite Application Manager for SOA

IBM Tivoli Composite Application Manager for SOA provides the management
function for managing the services and mediations in a service oriented
architecture (SOA) running on multiple application servers and SOA
infrastructures. For supported environments, IBM Tivoli Composite Application
Manager for SOA monitors and performs simple control of message traffic
between Web services in the SOA. IBM Tivoli Composite Application Manager
for SOA relies on a distributed network of data collectors to feed data into IBM
Tivoli Monitoring for analysis and management.
640
15.4.1 Overview
SOA uses the term services to describe both Web services and other services
with well defined interfaces. Because the definition of a service from an SOA
perspective is fairly broad, IBM Tivoli Composite Application Manager for SOA
defines its scope through support for the application server runtime environments
that host the services. It can monitor, manage, and control the service layer of IT
architectures while drilling down to the application or resource layer to identify the
source of bottlenecks or failures and to pinpoint services that take the most time
or use the most resources.
IBM Tivoli Composite Application Manager for SOA works in concert with other
products to support the logical services management layer in a complete SOA
management solution, and to manage the resources that support the services
and the WebSphere Enterprise Service Bus. IBM Tivoli Composite Application
Manager for SOA focusses on discovery and monitoring of services in a wide
range of application server runtime environments that are most common in early
SOA adoption projects, such as Microsoft .Net, BEA WebLogic Server, IBM
WebSphere Application Server, and others.
IBM Tivoli Composite Application Manager for SOA supports production IT
environments in key areas of operation, such as status and situation generation.
The basic control of message traffic provided by IBM Tivoli Composite
Application Manager for SOA includes the ability to log messages and the ability
to filter messages based on user-configurable criteria (computer name, service
name, operation name, and IP address of the requester).
IBM Tivoli Composite Application Manager for SOA can also process correlation
information from the message traffic to create pattern and sequence views in the
IBM Web Services Navigator, a separate tool provided with IBM Tivoli Composite
Application Manager for SOA.
IBM Tivoli Composite Application Manager for SOA provides basic control of
message traffic, including the logging of messages and filtering messages based
on criteria that you can configure (machine name, service name, operation
name, and IP address of the requester).
ITCAM is installed and operates within the management infrastructure of the
Tivoli Monitoring Services platform and the overall Enterprise Monitoring
Framework introduced in 15.3.2, IBM Tivoli Enterprise Monitoring framework on
page 636. As a result, ITCAM for SOA and the service centric management
capabilities it enables are simply considered as another perspective in the overall
multi-layered SOA management domain. The Tivoli Monitoring Services work in
conjunction with Tivoli Enterprise Portal to provide graphical views of metrics of
services calls.
641
Figure 15-6 on page 643 illustrates this integrated view of the different
management views within the IBM Tivoli Enterprise Portal.
642
Figure 15-6 Sample ITCAM for SOA workspace displayed via Tivoli Enterprise Portal
643
15.4.2 Product features

The previous release of IBM Tivoli Composite Application Manager for SOA,
v6.0, introduced support for management of Web services running in several
application server environments that are most common in early SOA adoption
projects, including IBM WebSphere Application Server, WebSphere Process
Server, Microsoft .Net, and BEA WebLogic Server environments.
In addition to the operating systems supported by v6.0 of IBM Tivoli Composite
Application Manager for SOA, additional support for Linux operating systems
was made available on the IBM Passport Advantage Web site through the
installation of the IBM Tivoli Composite Application Manager for SOA v6.0 Linux
Platforms Media Delivery Pack. The capabilities of IBM Tivoli Composite
Application Manager for SOA version 6.0 were further expanded with the
availability of two interim features (previously referred to as sparklers), providing
additional function.
IBM Tivoli Composite Application Manager for SOA version 6.1 augments and
enhances the features provided by the previous version. This is the version used
in this book.
ITCAM for SOA V6.0

ITCAM for SOA V6.0:
Provides service monitoring views in Tivoli Enterprise Portal. ITCAM for SOA
workspaces consist of:
Performance summary
Shows the response time information for Web services calls as viewed
from the client or the server.
Message Summary
Shows the message statistics, including the volume and size of message
information.
Fault Summary
Shows failure analysis for Web services calls.
Service Management Configuration Summary
Provides a summary of the Web services configuration.
Leverages Tivoli Enterprise Portal situations to check thresholds. ITCAM for
SOA provides some predefined situations that you need to tailor. The
predefined situations concern:
The number of messages received by a service within a time window
The size of the messages
644
Provides basic mediation support with the ability to filter or reject Web
services call messages from a particular client or service. It can log request
and response messages for analysis.
Offers heterogeneous platform coverage:
Support for IBM WebSphere Application Server, Microsoft .NET, BEA
WebLogic
Target IBM Enterprise Service Bus and integration platforms: WebSphere
Application Server 5.x and 6.x, WebSphere Business Integration Server
Foundation 5.1.1
Displays a list of services and operations monitored in environment.
Leverages Tivoli Enterprise Portal workflow and policy editor for
threshold-triggered action sequences.
Offers the ability to include Services-layer views in Tivoli Enterprise Portal.
The context-rich views and inter-workspace linkages in the Tivoli Enterprise
Portal enables users to drill down to IT resources to identify of Web service
bottlenecks and failures. By providing built-in and extensible alerts, situations,
and workflows, users can create powerful automated mediation scenarios via the
Tivoli Enterprise Portal.
The service metrics, alerts, and automation workflows provided by ITCAM for
SOA and other Tivoli products can be displayed in the Tivoli Enterprise Portal
with the cross-workspace linkages to provide a rich and multi-layered source of
information that can help to reduce the time and skills required for problem
root-cause analysis and resolution.
ITCAM for SOA includes the Web Services Navigator, a plug-in to IBM Rational
and other Eclipse-based tools. It provides deep understanding of the service
flow, patterns, and relationships to developers and architects. The Web Services
Navigator uses data from IBM Tivoli Monitoring V6.1s Tivoli Data Warehouse or
from the ITCAM for SOA metric log files using the Log Assembler tool.
ITCAM for SOA V6.1

Version 6.1.0 includes all of the function from version 6.0 and previously released
interim features, and broadens the scope of services supported by ITCAM for
SOA to be consistent with IBM SOA strategy. You can now implement services
using a wide range of technologies, including CICS transactions, J2EE
Enterprise Java Beans, Service Component Architecture (SCA) modules, Java
classes, JMS-based applications, or .NET applications. Web Services
Description Language (WSDL) is used to describe Web services interfaces and
bindings, and provides a standard definition of the service interface, independent
of the technologies used to implement the service.
645
IBM Tivoli Composite Application Manager for SOA v6.1 provides updated
support for newer versions of the previous application server runtime
environments from v6.0, and includes support for the following features:
Support for Web services running in the IBM WebSphere Application Server
v6.1 application server runtime environment.
Support for Web services running in the Microsoft .NET Framework V2
application server runtime environment.
Support for Web services running in the JBoss V4.0.3 application server
runtime environment.
Instrumentation and monitoring support for the Service Component
Architecture (SCA) infrastructure of IBM WebSphere Process Server and IBM
Monitoring support for Web service flows through a DataPower SOA
appliance acting as a proxy between the Web service client and server.
Support for Web services running in the SAP NetWeaver V6.40 application
server runtime environment.
Support for Web services running in the WebSphere Community Edition (CE)
application server runtime environment.
Support for Web services flowing to and from a IBM CICS Transaction Server
3.1 region running on the z/OS operating system.
The ability to launch the DataPower Web browser based user interface from a
row in the Services Inventory attributes table to configure the DataPower SOA
appliance.
The data collectors for IBM Tivoli Composite Application Manager for SOA v6.1
support these application server runtime environments with functions similar to
those environments supported in v6.0. Data from these environments are
displayed as additional environment types in Tivoli Enterprise Portal workspaces
and views.
IBM Tivoli Composite Application Manager for SOA v6.1 also introduces the
following additional capabilities for monitoring and managing services:
New Topology views in Tivoli Enterprise Portal
You can display static service relationships in a graphical topology display in
the Tivoli Enterprise Portal, and navigate through the relationships to view
and understand them. This display includes relationships between services,
service ports, operations, business processes, and the application servers
and computer systems on which they are deployed. The topology view
depends on information from several Discovery Library Adapters (DLAs),
including the WebSphere Service Registry and Repository DLA, the Business
646
Process Execution Language (BPEL) DLA, and the IBM Tivoli Composite
Application Manager for SOA DLA. This latter DLA discovers services that
have been observed by the ITCAM for SOA monitoring agents.
Integration with WebSphere Service Registry and Repository
WebSphere Service Registry and Repository Discovery Library Adapter
discovers services and static relationships between service artefacts that are
registered with WSRR. The data discovered by the DLA is displayed in the
new topology views. Integration with WSRR also includes the ability to
discover and display certain XML-based metadata files associated with a
service, and the ability to send status events to WebSphere Service Registry
and Repository when a situation is detected for a service port and operation.
Configurable mediations in WebSphere Enterprise Service Bus
Web services traffic can be monitored inside WebSphere Enterprise Service
Bus. You can track information about message interactions between Service
Component Architecture (SCA) components. Mediations are components of
WebSphere Enterprise Service Bus that can process messages and Take
Action commands, such as re-route, log, or transform a message, or create a
notification or event.
You can configure the behavior of a mediation by turning on and off managed
SCA mediation primitives in the mediation flow component. A developer can
insert one of several predefined configurable mediation primitives (shipped
with IBM Tivoli Composite Application Manager for SOA v6.1) into the wiring
of a mediation flow component using WebSphere Integration Developer. An
operator can then use IBM Tivoli Composite Application Manager for SOA
v6.1 at run time to set and change the behavior of the mediations by turning
on and off the individual primitives by name. A new workspace and
associated views display the configuration status of these primitives.
Monitor Web services in DataPower appliances
You can monitor Web services traffic through the DataPower intermediary,
which implements the proxy model for message mediation.
Note: For more information about IBM Tivoli Composite Application Manager
for SOA V6.1, see:
http://www.ibm.com/software/tivoli/products/composite-application
-mgr-soa/
15.4.3 Product components

The following list describes the primary components of IBM Tivoli Composite
Application Manager for SOA:
647
A monitoring agent that interacts with the managed application servers and
infrastructure middleware to collect data, and store the data in a log file. The
monitoring agent consists of the following sub-components:
An Intelligent Remote Agent (IRA)
One or more Data Collectors (DCs) that are installed locally on every
application server runtime environment where services are to be
managed. The data collector is the lowest-level component of the
monitoring agent. This component is responsible for actually observing
what is happening in the environment that it is designed to monitor. The
data collected by the data collector is provided to the Data Collector
Adapter through a log file on the monitored machine, for transmittal
through the IBM Tivoli Monitoring infrastructure. Data collectors typically
have access to the following types of information about the message traffic
it monitors:
Source and destination (machine name, application server name,

service name and operation name)
Whether the message is a request or a response
Interaction type (synchronous or asynchronous)
The association of a request to its response during an asynchronous

interaction
The response time for the message
Whether or not the message generated a fault
Whether the message is a one-way or a two-way message
Optionally, the actual header and body content of the message itself
A Data Collector Adapter (DCA), used to communicate between the Data

Collector and Intelligent Remote Agent. The Data Collector Adapter
accesses the data stored in the log file by the data collector, and stores
data collector configuration data in a configuration file that is accessed by
the data collectors on each managed system.
A set of managed SCA mediation primitives that you can add to your
WebSphere Integration Developer environment and incorporate into
mediation flow components and mediation modules in SOA applications that
you later deploy into WebSphere Enterprise Service Bus or WebSphere
Process Server runtime environments. With these managed SCA mediation
primitives, you can dynamically enable and disable the mediation of
messages flowing between services.
A set of Discovery Library Adapters (DLAs) that support service discovery by
extracting service information from source applications, artefacts and
repositories
648
A set of management data using logical table constructs.

A set of queries and commands
An Eclipse-based viewer that processes log files that are generated by the
Web services data collector. It generates visual representations of various
characteristics of monitored Web services.
Figure 15-7 provides an overview of ITCAM for SOA components and how they
collaborate within the Tivoli Enterprise Monitoring Framework to deliver SOA
management capabilities.
TEP Client
Web Services Navigator
SOA Topology UI
TEP Topology Adapter
UI Server
Tivoli Enterprise
Monitoring Server
(TEMS)
SOA Domain
Management
Server
Object
Access
Layer
TEPS Extension
Relationships
Mgmt Server
Tivoli Enterprise
Monitoring Server
(TEMS)
Tivoli
Data Warehouse
Message
Metrics
Mediation
Configuration
WebSphere
DC
DataPower
DC
Tivoli Common
Object
Repository
(TCORE)
Metrics History
ITCAM
for SOA
DLA
Agent
WESB
DC
WebLogic
DC
JBoss DC
BPEL
DLA
WSRR
DLA
ITCAM for SOA
Tivoli Monitoring
Figure 15-7 ITCAM for SOA high level architecture
Monitoring agent
Figure 15-8 on page 650 depicts the overall conceptual architecture of the
monitoring agent and its sub-components.
649
Microsoft .NET server

Log
KD4 service
extension
Data
collector
BEA WebLogic server

Log
JAX-RPC
handler
WebSphere Application
Server
JAX-RPC
handler
Data
collector
TCAM for SOA
Monitoring agent
Log
Data
collector
Configuration
IRA
(Intelligent
Resource Agent)
Data Collector
adapter
WESB/WPS
Log
SCA/Mediation
Primitives
Data
collector
DataPower
Log
Transaction Log
API
Tivoli Enterprise
Management Server
Tivoli Enterprise
Monitoring Server
Data
collector
Figure 15-8 ITCAM for SOA monitoring agent conceptual architecture
As described in 15.4.2, Product features on page 644 ITCAM for SOA works
with several runtime environments and technologies that may contribute to an
overall SOA:
WebSphere Application Server Community Edition
WebSphere Process Server
Microsoft .NET
BEA WebLogic server
JBOSS Application Server
SAP NetWeaver
650
CICS Transaction Server

DataPower SOA appliances
To accommodate these heterogeneous environments ITCAM for SOA provides
different installations for the monitoring agent data collector:
a JAX-RPC handler deployable in J2EE environments
a service extension deployable in Microsoft environments
SCA components and mediation primitives deployable in SCA enabled
environments such as WebSphere Process Server or WebSphere Enterprise
Service Bus
use of DataPower Transaction Log API to collect information from the
appliance
use of CICS Transaction Server to natively monitor services on z/OS
environments
Data Collectors are given control when either of the following events occurs:
A client application invokes a Web service, which is referred to as a
client-side interception.
The Web service request is received by the hosting application server, which
is referred to as a server-side interception.
The monitoring agent records and collects monitored information into one or
more local log files. The information is then transferred to Tivoli Enterprise
Monitoring Server and can be archived into a historical database for later
retrieval with IBM Web Services Navigator.
Web Services Navigator

Web Services Navigator is an Eclipsed-based tool used to visualize Web
services in an SOA environment. It provides a graphical display of:
Web services transaction flows
Service topology
Flow patterns
Web Services Navigator concepts can be illustrated as shown in Figure 15-9 on
page 652.
651
Metric
log
Data
collector
Metric
log
Tivoli Enterprise
Monitoring Agent
Data
collector
TDW
Warehouse
Web Services
Navigator
Metric
log
Log Assembler
Combined
metric log
Data
collector
Metric
log
Data
collector
Figure 15-9 Web Services Navigator conceptual architecture
The Web Services Navigator is a log-browsing tool intended for offline analysis of
SOA Web services. Four primary views that are provided:
Statistic tables
Message statistics
Per-message statistics including requestor, provider, send/receive time,
and message size.
Invocation statistics
Response time, network delay, message size, and more for each Web
service invocation.
Transaction statistics
Provides statistics for aggregated transactions, including elapsed time,
number of faults, number of machines this transaction involves, and
number of invocations comprising this transaction.
Pattern invocation statistics
Provides statistics for discovered patterns, including operation names,
number of occurrences, response times, and message sizes.
652
Service topology view

A graphical representation of the monitored Web services that displays
aggregated information and information about the relationships between Web
services.
Transaction flows view
Transaction flow view displays Universal Markup Language (UML) style
sequence diagrams. Transaction flow shows a chronological view of each
transaction, the flow between the various Web services over time, and the
topology and statistics for each transaction. The view can be zoomed to see
the details of individual transactions.
Flow pattern view
Flow pattern view is a visual representation of the aggregated pattern of
transactions represented in the log file. The view also represents each pattern
as a distinct sequence of Web service calls and displays the frequency of
each pattern.
Figure 15-10 shows the different views provided by the Web Services Navigator.
Sequence
Sequence Diagram:
Diagram:
Topology
Topology View:
View:
Shows
Shows exact
exact sequence
sequence of
of
messages
messages over
over time
time
Aggregate
Aggregate interactions
interactions
among
among services.
services.
Statistics
Statistics View:
View:
A
A table
table view
view of
of the
the raw
raw data
data
collected
collected by
by the
the monitoring
monitoring
agent
agent at
at each
each interception
interception point
point
Content
Content View:
View:
Shows
Shows content
content of
of aa
SOAP
SOAP message
message
Figure 15-10 Web Services Navigator
653
15.5 WSRR and ITCAM for SOA integration scenarios

Integration between WSRR and ITCAM for SOA conforms to the description of
the role of a service registry and repository in SOA management as described in
Service registry and repository in SOA management on page 36.
The integration between IBM Tivoli Composite Application Manager for SOA and
WebSphere Service Registry and Repository can be broken down into two main
scenarios:
WebSphere Service Registry and Repository Discovery Library Adapter
discovers services and static relationships between service artefacts that are
registered with WSRR. The data discovered by the DLA is displayed in the
new Services Management Workspace within the Tivoli Enterprise Portal.
This integration also includes the ability to discover and display certain
XML-based metadata files associated with a service and extracted from
WSRR. This scenario and its supporting capabilities are described in 15.6,
Discovery and display of service information on page 654.
IBM Tivoli Composite Application Manager for SOA sends status events back
to WebSphere Service Registry and Repository when a situation is detected
for a service port and operation. This mechanism can be used to enrich
service metadata in WSRR with additional operational information monitored
and feedback by ITCAM for SOA. Providing coarse-grained information about
service health allows registry users such as mediations to dynamically select
services, and humans to choose a specific service to access. This scenario
and its supporting capabilities are described in 15.7, Service status
information forwarding on page 677.
15.6 Discovery and display of service information

This integration scenario describes how IBM Tivoli Composite Application
Manager for SOA can use and leverage the information and metadata about the
services registered with WebSphere Service Registry and Repository. The
following aspects are discussed:
Discovery of services
Discovery of services observed by ITCAM for SOA
Discovery of services registered in WSRR
Display of service information
Reconciliation of observed and registered services
Display of service topologies and relationships
654
Display of service metadata documents

Figure 15-11 depicts the architectural overview of the key elements involved in
this scenario.

(Services Management Workspace)
Display of Observed and

Registered Services
DLA
ITCAM
for
SOA
TCORE /
CCMDB
DLA Book with

Observed Services and
their Relationships
Observed
Services
Agents
Common Object
Repository
DLA
WSRR
DLA Book with

Registered Services,
their relationships,
their metadata
and documents
Service
Metadata
Repository
DLA
Operational
System
(Observed)
Operational
System
(Observed)
DLA Book with

Business Processes
and the participating Services
Figure 15-11 Discovery, reconciliation and display of service information (architectural overview)
The discovery and display of service information are some key capabilities of the
Tivoli monitoring infrastructure and ITCAM for SOA.
The following sections introduces these capabilities and describe how they are
leveraged to contribute to the integration scenario between ITCAM for SOA and
WSRR.
15.6.1 Discovery of services

IBM Tivoli Composite Application Manager for SOA graphically displays service
relationships between services, service ports, operations, and port types in the
655
topology view in Tivoli Enterprise Portal. This relationship data is obtained from
the Tivoli Common Object Repository (TCORE) database, which is populated by
one or more Discovery Library Adapters (DLAs).
Discovery Library Adapters

A Discovery Library Adapter (DLA) is a special program that extracts data from a
source application and generates an XML file, called a book. DLA books contain
managed elements and relationships that describe the source application data.
Each Discovery Library Adapter book uniquely identifies the author of the
discovery data, when the data was generated, and the objects and relationships,
with sufficient identifying information to be displayed uniquely in the topological
view of the Tivoli Enterprise Portal. The format of the Discovery Library Adapter
book is specified in the IBM Discovery Library Identity Markup Language (IDML)
Schema Specification.
There are two types of Discovery Library Adapter books:
Refresh books contain a complete replacement of existing data imported from
previous runs of the Discovery Library Adapter. Resources present from prior
runs but not present in the refresh book are removed. Refresh books
represent a snapshot in time, replacing existing information with new data.
Delta books contain changes and updates to existing data imported during
previous runs of a Discovery Library Adapter.
After a DLA generates an XML book file, the file is copied to a shared directory,
called the Discovery Library File Store (DLFS).
As new books are copied into the Discovery Library File Store, you can
periodically run a special bulk load program to load these book files into either:
the Tivoli Common Object Repository (TCORE) database which is part of IBM
Tivoli Composite Application Manager for SOA v6.1.0
the Configuration Management Database that is part of IBM Tivoli Change
and Configuration Management Database (ITCCMDB) Version 1.1.1
You can also run the bulk load program manually as new files become available.
Figure 15-12 on page 657 illustrates the overall DLA mechanism where DLAs
extract information about managed entities out of different sources, aggregate it
into books and use them to build a Common Object Repository.
656
DLA
Source of Information
on Managed Entities
DLA
TCORE /
CCMDB
DLA Book
DLA Book
Source of Information
on Managed Entities
Common Object Repository:

description of managed entities, attributes,
relationships and metadata
Figure 15-12 DLAs and Common Object Repository
Three DLAs are provided with IBM Tivoli Composite Application Manager for
SOA:
IBM Tivoli Composite Application Manager for SOA Discovery Library
Adapter: discovers the relationships between service ports and operations
and the application servers and computer systems on which they are
deployed, using data collected by ITCAM for SOA monitoring agents and
retrieved from Tivoli Enterprise Monitoring Server.
WebSphere Service Registry and Repository Library Adapter: discovers the
relationships between service ports, operations, services, port types, and
metadata documents from WSRR. WebSphere Service Registry and
Repository can process Web Services Description Language (WSDL) and
other definition files to determine these static relationships.
Business Process Execution Language for Web Services Discovery Library
Adapter: discovers the relationships between port types, operations, and
business processes from BPEL files.
Note: WS-BPEL Discovery Library Adapter is beyond the scope of this
scenario and this book.
SOA Managed Elements (Common Data Model)

All managed elements constitute the management model reflecting the entities,
attributes and relationships which are part of the management domain. This
description follow a clearly defined structure referred to as the Common Data
Model, which is used by both TCORE and ITCCMDB and is built from the
information contained in the multiple books extracted by the DLAs from the
different information sources (see Figure 15-12).
The Common Data Model specify the representation of the management domain
as stored in the Common Object Repository. Figure 15-13 on page 658 provides
657
an overview of the main entities of the Common Data Model with focus on the
SOA managed elements.
federates
WebSphere
Cell
WebSphere
Cluster
WebService
memberOf
federates
definedUsing
memberOf
WebSphereServer
memberOf
provides
federates
definedUsing
federates
WSEndPoint
WebSphere
Node
imports
WSPort
provides
Document
invokedThrough
runsOn
definedUsing
WSOperation
runsOn
definedUsing
Computer
System
federates
Business
Process
federates
WSPortType
Figure 15-13 Overview of the Common Data Model (some omitted elements)
While this is really only an SOA-centric overview of the Common Data Model it
certainly exhibits some important characteristics:
The left part of the model is centered on operational systems and topologies.
The right part of the model describes the managed Web services by breaking
them down into elementary entities such as PortType, Operation and Port.
The link between the operational elements and the Web service centric ones
is materialized by the EndPoint which is deployed on an server and is also
part of the description of a given Web service.
The Document element represent a service artefact such as WSDL, XSD or
WS-Policy document and is as such part of the notion of managed service as
a set of related entities.
Discovery of observed services: ITCAM for SOA DLA

IBM Tivoli Composite Application Manager for SOA monitors services message
traffic and allows basic control of messages flowing between services in an SOA.
Discovered data related to Web services is stored in the Services Inventory
attributes table.
658
The IBM Tivoli Composite Application Manager for SOA Discovery Library
Adapter retrieves these Web services objects using the Tivoli Enterprise
Monitoring Server SOAP interface in your environment. The discovered
resources are then written to the Discovery Library File Store in a Discovery
Library Adapter book. The IBM Tivoli Composite Application Manager for SOA
Discovery Library Adapter populates the Tivoli Common Object Repository with
the Web services objects that are observed by the ITCAM for SOA v6.1
monitoring agents. These objects represent the dynamic discovery of the Web
services related information. The data for an observed Web service includes the
service port name and namespace, the operation name and namespace, the
application server where the service port is deployed, and the computer system
on which the application server is running.
Note: ITCAM for SOA Discovery Library Adapter uses the TEMS SOAP API to
retrieve the list of ITCAM for SOA V6.1 agents and the agent data from the
TEMS Hub. Agent data from the Services Inventory table of the Performance
Summary workspace is retrieved.
Figure 15-14 illustrates the discovery of observed services in ITCAM for SOA.
DLA
ITCAM
for
SOA
DLA Book with

their Relationships
Observed
Services
Common Object
Repository
Agents
Operational
System
(Observed)
TCORE /
CCMDB
Operational
System
(Observed)
Figure 15-14 Discovery of observed services using ITCAM for SOA DLA
During this discovery phase ITCAM for SOA DLA populates the Common Object
Repository (see SOA Managed Elements (Common Data Model) on page 657)
with the following managed elements and relationships between them:
WSPort: Identifies a service port name and namespace
659
WSOperation: Identifies an operation name and namespace

WSEndpoint: Maps a service port to an application server it is deployed on
WebSphereServer, WebSphereNode, WebSphereCell, and WebSphereCluster (if
applicable): Identifies a WebSphere application server and the environment in
which it is deployed
AppServer: Identifies other application servers (for example, BEA WebLogic)
ComputerSystem: Identifies the computer system on which an application
server is deployed
BindAddress: Identifies the application server port number
IPInterface, IPv4Address: Identifies the IP address of a computer system
Discovery of registered services: WSRR DLA

The WebSphere Service Registry and Repository Discovery Library Adapter
allows for a loosely coupled model to input data into the Tivoli Common Object
Repository. Because WebSphere Service Registry and Repository and Tivoli
Common Object Repository can be in different parts of the network (with firewalls
between them), the DLA allows more flexibility on the delivery of data.
The WebSphere Service Registry and Repository DLA uses WSRR application
programming interfaces (APIs) to access the list of registered Web Services
Description Language (WSDL) metadata documents and the set of objects (such
as services, service ports, operations, and port types) stored in the registry for
each document. These documents, along with other metadata documents are
also discovered by the DLA. The data is then exported to a Discovery Library
Adapter book. This DLA book supplies information that complements the
information supplied by the IBM Tivoli Composite Application Manager for SOA
Discovery Library Adapter.
Note: WSRR Discovery Library Adapter uses the WSRR Java API to retrieve
the list of Web services from WSRR. WSRR DLA is a Java Enterprise Java
Bean (EJB) client.
Figure 15-15 on page 661 illustrates the discovery of registered services in
WSRR.
660
TCORE /
CCMDB
Common Object
Repository
DLA
WSRR
DLA Book with

their metadata
and documents
Service
Metadata
Repository
Figure 15-15 Discovery of registered services using WSRR DLA
During this discovery phase WSRR DLA populates the Common Object
Repository (see SOA Managed Elements (Common Data Model) on page 657)
with the following managed elements and relationships between them:
WebService: Identifies a WSDL service name and namespace
WSPort: Identifies a WSDL port name and namespace
WSOperation: Identifies a WSDL operation name and namespace
WSPortType: Identifies a WSDL port type name and namespace
Document: Identifies a WSDL, XSD, or WS-Policy document. Only WS-Policy
documents that have a relationship to a WSDL service, WSDL port, WSDL
operation, or WSDL port type are discovered. The documents content is
included in the DLA book.
Repository: Identifies the WSRR server
Note: Service Component Architecture (SCA) Modules and their artefacts are
not discovered by the WSRR DLA.
Classifications
WSRR supports classification systems loaded from Web Ontology Language
(OWL) files. Classification classes are used to organize and find artefacts in
WSRR. Any artefact can be tagged or classified with multiple classification
classes.
Refer to 9.6, Classifying objects on page 358 for additional information about
classification of artefacts.
By default, WSRR Discovery Library Adapter is configured to discover Web
services and their artefacts that are tagged with the Deployed or Managed
661
classifications. These two classifications are defined in the default OWL file
shipped with WSRR.
WSRR Discovery Library Adapter can be configured to use other classifications
when it discovers Web services or it can be configured to ignore classifications.
See Configuration instructions on page 708 for more information about
configuring classification support in WSRR DLA.
Versioning
WSRR can be used to manage different versions of WSDL documents and the
artefacts that they define. The different versions are defined by one of the
following methods:
Using the same name for a WSDL document but specifying a different version
number. The artefacts of a WSDL document inherit the version number of the
document.
Using a different name for a WSDL document but specifying the same WSDL
service, WSDL port, WSDL port type, and WSDL operation as defined in
another WSDL document.
Since the Common Data Model does not support a Version attribute for Web
service related managed elements (see SOA Managed Elements (Common
Data Model) on page 657), the WSRR DLA cannot include multiple versions of
the same Web service (and its artefacts) in its books. WSRR DLA does not
distinguish between different versions of documents and their artefacts: it
uniquely identifies a Web service by its name and namespace properties.
When the DLA retrieves the list of Web services from WSRR, it uses the first
instance of a Web service in the returned list. If there are other instances of the
same Web service (for example, a Web service with the same name and
namespace), the other instances are ignored. The WSRR DLA logs a message
when it discovers multiple instances of the same Web service.
Recommendations:
If you are using WSRR to manage multiple versions of the WSDL documents,
and you are using the WSRR DLA, use one of the following options to ensure
the WSRR DLA discovers the correct versions of your services:
Depending on your versioning policies, you may want to use a different
namespace for each version of a Web service and its artefacts. This would
particularly apply to the notion of major versions where backward
compatibility might not be maintained.
Use WSRR classifications to control which version of a Web service and its
artefacts are retrieved by the WSRR Discovery Library Adapter.
662
15.6.2 Displaying of service information

Displaying of service information is performed in Tivoli Enterprise Portal using
the Services Management workspace as depicted in Figure 15-16.

(Services Management Workspace)
Display of Observed and

Registered Services
ITCAM
for
SOA
DLA
TCORE /
CCMDB
DLA Book with

their Relationships
Common Object
Repository
DLA
WSRR
DLA Book with

their metadata
and documents
Figure 15-16 Displaying of observed and registered service information in TEP
Services Management workspace

The Services Management workspace provides the integration of IBM Tivoli
Composite Application Manager for SOA with the WebSphere Service Registry
and Repository.
This workspace provides topology views to help you with the following tasks:
View the services and service relationships that are registered with
WebSphere Service Registry and Repository that have been discovered by
WSRR DLA and imported into the Tivoli Common Object Repository.
View service metadata documents from WSRR.
View the service ports and operations that are discovered by the IBM Tivoli
Composite Application Manager for SOA DLA and imported into the Tivoli
Common Object Repository.
Compare a set of service definitions with a set of discovered services, to
verify that services are implemented and operating as designed.
663
View the business processes that use activities that are implemented by Web
services that are discovered by the ITCAM for SOA DLA or the WSRR DLA.
The business process and service relationship data is discovered by the
BPEL DLA and imported in to the Tivoli Common Object Repository.
The topologies views relevant to WSRR integration are described in more details
in WSRR integration topology views on page 665.
The Services Management workspace is accessed from a customized Navigator
view called ITCAM for SOA.
Note: The table views in this workspace contain UTF-8 character set data that
so that strings of data can be represented in different languages. Unlike other
workspaces, however, the (Unicode) designation does not appear in the
column titles for the table.
Reconciliation of observed and registered services

The discovery of services as described in 15.6.1, Discovery of services on
page 655 is twofold:
Observed services were discovered using IBM Tivoli Composite Application
Manager for SOA DLA from the running agents monitoring operational
applications and services.
Registered services were discovered using WebSphere Service Registry and
Repository DLA by querying WSRR for published services and related
information.
The information captured in the Common Object Repository must be reconciled
to link observed and registered services together and ensure consistency
between designed and operational states of services.
Reconciliation of service information is displayed in the Services Overview table
view as described in The Services Overview table view on page 666.
The need to reconcile service information

Such a reconciliation is necessary as it helps point out the following situations:
Services observed but not registered: assuming that registering a service in
WSRR is a prerequisite to a broader reuse of that service, this situation might
reflect the fact that the operational services which are currently observed are
not the ones targeted for exposure and reuse. These observed services might
be only test services whose implementation is due to change.
Services registered but not observed: this situation might indicate that the
common services which are registered in WSRR and potentially highly
reused are missing monitoring capabilities, therefore leading to probable poor
664
decision making regarding exposure decision because of the lack of

operational information (for example, utilization, performance...).
Services registered and observed: this situation should prove a sound
foundation to enable and understand common service reuse.
Understanding discrepancies enables better service governance.
How ITCAM for SOA correlates service information

Certain attributes are used to uniquely identify service artefacts, business
processes, and application servers:
Services, service ports, operations, port types, and business processes are
uniquely identified by the combination of their name and namespace.
Application servers are uniquely identified by their product type, port number,
and the computer on which they are installed. WebSphere application servers
are also identified by their node, cell, and cluster names (if applicable).
The Services Management workspace is accessed from a customized Navigator
view called ITCAM for SOA.
The service ports and operations that are discovered by the ITCAM for SOA
DLA, the WSRR DLA, and the BPEL DLA can only be correlated in this
workspace if the DLAs discover the same name and namespace for the service
port and operation. In certain cases, the ITCAM for SOA data collectors might
not be able to obtain the correct namespace from the application server that is
being monitored.
WSRR integration topology views

Topologies views are defined in Tivoli Enterprise Portal Services Management
workspace (see Services Management workspace on page 663).
They aim at combining or leveraging information (data and metadata) from
multiple sources (ITCAM for SOA, WSRR, and BPEL) and providing these
elements to Subject Matter Experts (SMEs). There are multiple topology views:
Services Overview, Service Details, and Service Port Details views:
combine data from ITCAM for SOA and WSRR
Business Process views and Business Process Details view: combine data
from all three sources
All views potentially provide access to metadata and are dependent upon WSRR
data being available.
665
Unlike most Tivoli Enterprise Portal data displays all topology views are in a
single workspace with the topology view changing display based on the context
requested.
Topology views use the TEP Topology Adapter so they inherit many capabilities
from it such as pan/zoom, search, as well as sorting and filtering in table mode.
Note: The descriptions of the different topology views provided in the next
sections of this redbook are not intended to cover all details and functionalities
but rather focus on WSRR integration and the display of WSRR information
within TEP. For example, dynamic workspace linking is not described in this
book.
For more information, refer to the ITCAM for SOA Information Center.
http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?toc
=/com.ibm.itcamsoa.doc/toc.xml
The Services Overview table view

The Services Overview table view displays service definitions that have been
defined in WebSphere Service Registry and Repository and the discovered
service information that is monitored by IBM Tivoli Composite Application
Manager for SOA. This is the initial view that is displayed when you select the
ITCAM for SOA custom Navigator view and bring up the Services Management
workspace to navigate through your SOA topologies.
The Services Overview view is always displayed as a table as shown in
Figure 15-17.
Figure 15-17 Service Overview table in the Services Management workspace
The Services Overview table view displays all of the service ports, operations,
Web services, and application servers that were discovered by the DLAs and
retrieved from the Tivoli Common Object Repository. It includes information
666
about service ports and operations that are observed by IBM Tivoli Composite
Application Manager for SOA monitoring agents, and specific information defined
in WebSphere Service Registry and Repository.
The Services Overview table view contains various column headings as
described in Table 15-2.
Table 15-2 Names and descriptions of the column headings for the Services Overview
Name
Description
Service Port
The name of the Web Services Description Language (WSDL)

service port.
Operation
The name of the Web Services Description Language operation.
Service
The name of the Web Services Description Language service.
Application Server
The name of the application server on which the service port is

deployed
Computer System
The machine on which the application server is running.
Observed
Indicates that the service port and operation have been observed
by the IBM Tivoli Composite Application Manager for SOA
monitoring agents.
Registered
Indicates that the service has been defined in the WebSphere

Service Registry and Repository.
The Services Overview view is the main correlation point for data from ITCAM for
SOA and WSRR as it allows comparison between designed and operational
state of services. The Observed and Registered columns are marked with a
check mark when the information has been obtained through observations by the
monitoring agents of IBM Tivoli Composite Application Manager for SOA and
from definitions in WebSphere Service Registry and Repository, respectively.
This allows for quick visual reconciliation of ITCAM for SOA and WSRR service
information as explained in Reconciliation of observed and registered services
on page 664. Figure 15-18 on page 668 illustrates the reconciliation of these two
sources of information.
667
Services observed
in ITCAM for SOA
Data from WSRR
Services
registered in
WSRR
Data from ITCAM for SOA
Figure 15-18 Visual reconciliation of service information from WSRR and ITCAM for SOA
When you right-click a row in the table, the resulting context menu that is
displayed provides a list of resource actions and views, giving access to Details
views, Business Process views, Metadata, and linking to SOA Performance
Summary workspaces.
The following resource relationship views are available from the Services
Overview table view:
View Service Details
Displays the Service Details view for the service in the selected row. If no
service information is available, this menu item is not available
View Service Port Details
Displays the Service Port Details view for the service port in the selected row.
View Business Processes for Service
Displays the Business Process view for the service. If no service information
is available in the selected row, this menu item is not available. If there is no
668
business process information available for this service, an empty view is

displayed.
View Business Processes for Service Port
Displays the Business Process view for the service port in the selected row. If
there is no business process information available for this service port, an
empty view is displayed.
View Metadata
Displays the Metadata dialog, which might contain a list of metadata
documents for the service, service port, and operation for the selected row of
the Services Overview table view. If only one metadata document is available,
it is displayed. This menu item is only available if the service, service port, and
operation is registered in WebSphere Service Registry and Repository.
The Service Details view

The Service Details view is a topology and table view that displays the service
ports, operations, and application servers on which the service ports are
observed, and that have been defined in the Tivoli Common Object Repository
as being related to a specified service. The icons or nodes in the topology
represent the various resource types. Similar to the Services Overview table
view, information for this view is obtained from multiple data sources, so all
information for a given service might not be available. To receive additional
information for a resource, hover over a resource and use the flyover help.
Figure 15-19 on page 670 shows an example of the Service Details view.
669
Service
Service
contains
contains
Service
Service
Port
Port
defined
defined within
within
hosts
hosts
Operation
Operation
Application
Application
Server
Server
Figure 15-19 The Service Details view in the Services Management workspace
Use the Service Details table view to clarify your view if there are a large number
of resources contained in the topology. You can narrow your scope by using the
column sorting and filtering capabilities.
When you right-click a resource in the topology or a row in the table, the context
menu provides a list of resource actions and views. These are the resource
relationship views available from the Service Details view:
View Service Port Details
Displays the Service Port Details view for a selected port.
Displays the Business Process view for the selected service.
Displays the Business Process view for the selected service port.
View Metadata
Displays the Metadata dialog, which might contain a list of metadata
documents for the service, service port or operation. If only one metadata
document is available, it is displayed. This menu item is only available if the
service, service port or operation is registered in WebSphere Service
Registry and Repository.
670
Select Properties from the context menu to set a limit on the number of nodes
that you can view in the topology. If the node threshold is exceeded, the topology
view automatically switches to the table view. The default setting is 50 but you
can modify or turn off the threshold. Refer to the online help procedures to edit
the properties.
See the online help for Tivoli Enterprise Portal for information about the other
context menu actions and the capabilities for column sorting and filtering.
The Service Details table view contains the column headings as described in
Table 15-3.
Table 15-3 Names and descriptions of the column headings for the Service Details
Name
Description
Name
The name of the resource.
Resource Type
The type of resource and its accompanying icon.
Namespace
The namespace used to fully qualify the resource.
Port Type
The definition of a set of operations for the service port that can
be deployed as a group.
Computer System
The name of the machine on which the application server is

running.
Source
The origin of the relationship indicated by the solid line arrows in

the topology view, that indicates a directional relationship
between the source and the destination.
Destination
The endpoint of the relationship indicated by the solid line arrows

in the topology view, that indicates a directional relationship
Use the Show/Hide additional attributes button on the table toolbar to turn on
the columns to show more information about the services. In addition to the
previously mentioned column headings, the Service Details table view has the
following attributes.
Table 15-4 Additional attributes for the Service Details table view
Name
Description
Name
The name of the resource
Description
The description of the resource.
Node Name
The name of the WebSphere node to which the

application server belongs.
671
Name
Description
Cell Name
The name of the WebSphere cell to which the

Cluster Name
The name of the WebSphere cluster to which the

Vendor Name
The name of the vendor that makes the application

server.
Product
The application server program product name.
Port Type Namespace
The namespace that fully qualifies the port type.
Computer System IP Address
The IP Address for the computer system that the

application server runs on
To receive additional attribute information for a resource, hover over a resource

and use the flyover help.
The Service Port Details view

The Service Port Details view is a topology and table view that displays
operations, Web services, and the application servers on which the service port
is observed and that has been defined in the Tivoli Common Object Repository
related to the specific service port. The icons or nodes in the topology represent
the various resource types. Similar to the Service Details view, information for
this view is obtained from multiple data sources, so all information for a given
service port might not be available. To receive additional information for a
resource hover over a resource and use the flyover help.
Use the Service Port Details table view to clarify your view if there are a large
number of resources contained in the topology. You can narrow your scope by
using the column sorting and filtering capabilities.
The Service Port Details topology view uses the same icons as the Service
Details view.
When you right-click a resource in the topology or a row in the table, the context
menu provides a list of resource actions and views. These are the resource
relationship views available from the Service Port Details view:
View Service Details
Displays the Service Details view for a selected service.
Displays the Business Process view for the selected service.
672

Displays the Business Process view for the selected port.
View Metadata
Displays the Metadata dialog, which might contain the list of metadata
documents for the service, service port or operation. If only one metadata
document is available, it is displayed. This menu item is only available if the
service, service port or operation is registered in WebSphere Service
Registry and Repository.
Select Properties from the context menu to set a limit on the number of nodes
that you can view in the topology. If the node threshold is exceeded, the topology
automatically switches to the table view. The default setting is 50 but you can
modify or turn off the threshold. Refer to the online help procedures to edit the
properties.
See the online help for Tivoli Enterprise Portal for information about the other
context menu actions and the capabilities for column sorting and filtering.
The Service Port Details table view contains the column headings as described
in Table 15-5.
Table 15-5 Names and descriptions of the column headings for the Service Port Details
Name
Description
Name
The name of the resource.
Resource Type
The type of resource and its accompanying icon.
Namespace
The namespace used to fully qualify the resource.
Port Type
The definition of a set of operations for the service port that can
be deployed as a group.
Computer System
The name of the machine on which the application server is

running.
Source
The origin of the relationship indicated by the solid line arrows in

the topology view, that indicates a directional relationship
Destination
The endpoint of the relationship indicated by the solid line arrows

in the topology view, that indicates a directional relationship
Use the Show/Hide additional attributes button on the table toolbar to turn on
the columns to show more information about the services. In addition to the
673
previously mentioned column headings, the Service Port Details table view has
the following attributes.
Table 15-6 Additional attributes for the Service Port Details table view
Name
Description
Name
The name of the resource
Description
The description of the resource.
Node Name
The name of the WebSphere node to which the

Cell Name
The name of the WebSphere cell to which the

Cluster Name
The name of the WebSphere cluster to which the

Vendor Name
The name of the vendor that makes the application

server.
Product
The application server program product name.
Port Type Namespace
The namespace that fully qualifies the port type.
Computer System IP Address
The IP Address for the computer system that the

application server runs on
To receive additional attribute information for a resource, hover over a resource

and use the flyover help.
Business Process views

Business processes are discovered using the Business Process Execution
Language for Web Services Discovery Library Adapter as mentioned in
Discovery Library Adapters on page 656.
Different views are provided to display business processes information and relate
it to the other elements of the Common Object Model:
Business Processes for Service view
The Business Processes for Service view displays service relationships for a
business process. This topology or table view displays all of the service ports
and operations for a specific service that participate in business processes
along with those business processes that have been defined in the Tivoli
Common Object Repository. The icons or nodes in the topology represent the
various resource types. Similar to the Services Overview table, information for
674
this view is obtained from multiple data sources, so all information for a given
service might not be available
Business Processes for Service Port view
The Business Processes for Service Port view displays service port
relationships for business processes. This topology or table view displays the
service port, its associated service, and all the operations that participate in
business processes along with those business processes that have been
defined in the Tivoli Common Object Repository. The icons or nodes in the
topology represent the various resource types. Similar to the Services
Overview, information for this view is obtained from multiple data sources, so
all information for a given service port might not be available.
Business Process Details view
The Business Process Details view is a topology and table view that displays
the operations, service ports, and services that have been defined in the
Tivoli Common Object Repository related to a specific business process. The
icons or nodes in the topology represent the various resource types. Similar to
the Services Overview, information for this view is obtained from multiple data
sources, so all information for a given business process might not be
available.
Note: These three views are similar to the Service Details and Service Port
Details views presented previously. Refer to ITCAM for SOA documentation if
more details are needed.
The Metadata view

Metadata information about services and related elements has been discovered
from WSRR using WSRR DLA (see Discovery of registered services: WSRR
DLA on page 660). Metadata information includes WSDL, XSD and WS-Policy
documents.
Metadata display is conditionally available from all views in the SOA topology for
the following entities:
Rows in the Services Overview table that have Service information
Services from all other views
Service Ports, and Operations from the other views if they are associated with
a Service in that view
Metadata displays in a separate dialog as illustrated in Figure 15-20 on
page 676.
675
Figure 15-20 Metadata display view
A selection dialog is displayed if more than one metadata document is available

for a given resource (for example, WSDL and related XSD for a given service), as
676
Figure 15-21 Metadata selection dialog
You can use this Metadata selection dialog to multi-select the metadata
documents you want to view.
15.7 Service status information forwarding

This integration scenario describes how IBM Tivoli Composite Application
Manager for SOA can propagates service information back to WebSphere
Service Registry and Repository to enrich registered service descriptions with
additional operational metadata. The following aspects are discussed:
Detection and processing of service related situations
Detection of situations
Generation of situation events
Propagation, capture and processing of service events
Propagation and capture of service events
Processing of service events
Use of service status information
Figure 15-22 on page 678 depicts the architectural overview of the key elements
involved in this scenario.
677
Generation of
Situation Events
Detection of
Situations
Conditions
Situation
Definitions
Update of Service
Information
Event
Event
OTEA
Metadata
Repository
Capture & Processing

of Situation Events
ITCAM
for
SOA
EIF
Events
Event
Handler
WSRR
Services
Observed
Re-send
Rule
Agents
WAS
TEC
TEC-OMNIbus
Probe
OMNIbus-TEC
Gateway
OMNIbus Support
planned for the future
OMNIbus
Server
Figure 15-22 Forwarding of service status information (architectural overview)
Service status information is forwarded to WSRR using the situation and events
mechanisms provided by Tivoli management infrastructure and leveraged by
ITCAM for SOA.
The following sections introduce the notions of situation and event, and describe
how these concepts contribute to feedback service operational information from
ITCAM for SOA to WSRR.
15.7.1 Detection and processing of service related situations

IBM Tivoli Composite Application Manager for SOA uses situations to detect and
react to critical activity in the management domain.
678
Once they have been configured, the situation alerts provide ITCAM trigger
notification. Situations detected by ITCAM for SOA are all directly related to the
observed services.
When the situation conditions are detected or closed, an event is generated.
Situation events materialize the originating situations and provide information
about them and the context they occur in.
Figure 15-23 depicts the detection of situations and the generation of
corresponding situation events.
Generation of
Situation Events
Event
Event
Detection of
Situations
Conditions
OTEA
ITCAM
for
SOA
Situation
Definitions
Attribute Tables
Properties
Services
Observed
Agents
Operational
System
(Observed)
Operational
System
(Observed)
Figure 15-23 Detection of situations and generation of events in ITCAM for SOA
Situations
A situation is a type of an event that is generated in Tivoli Monitoring Services.
IBM Tivoli Composite Application Manager for SOA provides predefined
situations. These predefined situations are designed to help you monitor critical
activity, and serve as templates for creating customized situations for your own
use. These predefined situations are activated when they are distributed to the
679
node that you are monitoring. After they are configured, the alerting functions
included as part of these predefined situations trigger event notification.
A situation is a condition where a set of attributes are tested against a threshold.
The situation evaluates the conditions at predefined intervals and invokes the
appropriate automated responses and notification methods.
Predefined situations are activated when they are distributed to the node that you
want to monitor. Use the Tivoli Enterprise Portal Situation Editor to distribute a
situation to a specific agent or managed system agent list. You can also use the
Situation Editor to associate a situation with a desired report node.
You can modify an existing situation to create your own.
The predefined situations that are provided with IBM Tivoli Composite
Application Manager for SOA v6.1 are listed in Table 15-7. All predefined
situations for this version of IBM Tivoli Composite Application Manager for SOA
have the _610 suffix at the end of the situation name.
Note: If you have an environment that incorporates both v6.1 monitoring
agents and v6.0 monitoring agents, you can only use the situations that apply
to each version, respectively.
For more information about predefined situations provided with IBM Tivoli
Composite Application Manager for SOA v6.1 or v6.0, refer to the product
information center.
Table 15-7 Predefined situations for ITCAM for SOA v6.1 monitoring agents
Situation name
Description
Fault_610
Triggered if Web services faults have occurred based on defined

filtering criteria or application problems. The initial threshold is set to
0.
MessageSize_610
Triggered if the average message length of all messages during the

time interval is greater than expected. The initial threshold is set to
1600 bytes.
MaxMessageSize_610
Triggered if the message length of any single message during the

time interval is greater than expected. The initial threshold is set to
1600 bytes.
680
Situation name
Description
MessageArrivalCritical_610
Triggered if excessive Web services traffic is received from specified

remote clients during a specified time interval. The initial settings
detect traffic from all combinations of service port name and
namespace, operation name and namespace, and remote IP
address, over the 3 most recent 30-second sampling intervals (time
interval set to 90 seconds). The initial threshold is set to 50
messages. This situation is cleared when the
MessageArrivalClearing_610 situation is triggered.
MessageArrivalClearing_610
Clears a previous MessageArrivalCritical_610 situation. Triggered

when Web services traffic received from specified remote clients
during a specified time interval falls below the threshold level. The
initial settings detect traffic from all combinations of service port name
and namespace, operation name and namespace, and remote IP
address, over the 3 most recent 30-second sampling intervals (time
interval set to 90 seconds). The initial threshold is set to 40
messages. This situation clears itself after 5 minutes.
ResponseTimeCritical_610
Triggered if the average elapsed round trip response time to complete

Web service requests during the time interval exceeds the expected
threshold. The threshold is initially set to greater than 10000 ms (10
seconds).
ResponseTimeWarning_610
Triggered if the average elapsed round trip response time to complete

Web service requests during the time interval exceeds the expected
threshold. The threshold is initially set to greater than 8000 ms (8
seconds) but less than or equal to 10000 ms (10 seconds).
MaxResponseTimeCritical_610
Triggered if the elapsed round trip response time to complete any

single Web service request exceeds the expected threshold during
the time interval. The threshold is initially set to greater than 10000 ms
(10 seconds).
MaxResponseTimeWarning_610
Triggered if the elapsed round trip response time to complete any

single Web service request exceeds the expected threshold during
the time interval. The threshold is initially set to greater than 8000 ms
(8 seconds) but less than or equal to 10000 ms (10 seconds)
Attributes
The information triggering a situation and available in the corresponding event
depends on the type of the observed resource that is at the origin of the situation.
These characteristics are described as attributes in the attribute tables. ITCAM
for SOA situation events contain attributes as a list of property-value pairs.
Note: Event attributes are also called event class attributes or properties in the
ITCAM for SOA and ITM documentation.
681
IBM Tivoli Monitoring gathers data from the various monitoring agents installed
on the computers in your environment. Information about Web services is
collected for IBM Tivoli Composite Application Manager for SOA and stored for
display in tables of attributes. Each attribute is a characteristic of an object from
the Common Object Model. For example, Service Port Name is an attribute of a
message that identifies the name of the service port where the message was
intercepted and for which filtering is defined.
Data that is stored in attribute tables is displayed in various table views in the
Tivoli Enterprise Portal workspaces. Each table view corresponds to a group of
attributes. Columns in the table view correspond to the attributes in the group.
Some of these attributes are used as parameters for the creation of situations, or
for specifying Take Action commands.
Table 15-8 summarizes the attribute tables used by ITCAM for SOA v6.1. These
tables contain the attributes that apply to v6.1 monitoring agents for IBM Tivoli
Composite Application Manager for SOA. Table names corresponding to their
v6.0 counterparts have a _610 suffix attached to signify that they are for v6.1
attributes only. Many attributes in v6.1 tables have similar names and function to
their v6.0 counterparts. These tables also include new attributes that only apply
to v6.1 data collectors.
Note: Tables specific to v6.0 are not described in this book.
For more information about attribute tables, refer to the IBM Tivoli Composite
Application Manager for SOA information center and product documentation.
Table 15-8 ITCAM for SOA v6.1 attribute tables
Attribute Table
Description
KD42GT: Data Collector Global

Configuration_610
These attributes define the global configuration settings in

the properties file that apply to all v6.1 data collectors
running in the specified application server runtime
environment.
These attributes perform the following functions
Enable data collection
Disable data collection
Define the level of logging information that is stored
Turn tracing functions on and off
KD42CT: Data Collector Monitor

Control_610
These attributes define the type of data that is collected by

the v61 monitoring agent.
KD42FT: Data Collector Filter Control

Configuration_610
These attributes define the type of filtering that is applied to

message data collected by the v61 monitoring agent.
682
Attribute Table
Description
KD42ET: Fault Log_610
These attributes define the data that make up each simple

object access protocol (SOAP) fault that is received by the
data collector. Use these attributes to create situations that
monitor SOAP errors received by the data collector.
KD42IT: Services Inventory_610
The Services Inventory_610 attributes table provides data

on current service inventory. It also contains aggregate
metric data. Use this table to monitor your services inventory
and ensure that settings do not reach or exceed predefined
thresholds.
The Services Inventory_610 attributes table contains one
row per unique combination of service name, operation
name, and message type (provider or requester), for each 5
minute time interval. Only the incomplete and most recently
completed time intervals are available for real time queries.
When historical data collection is enabled each 5 minute
interval record is collected as historical data.
KD42AT: Message Arrival Threshold_610
These attributes represent the computed data table, used to

create situations based on the arrival rate of messages that
monitor message arrival data, such as the number of
messages that arrive during a specified time interval.
KD42MT: Services Message Metric_610
The Services Message Metric_610 attributes table can

contain a significant number of rows depending on the
number of times each service is called. Due to the large
amount of data that can be generated, when historical data
collection is not enabled, queries can retrieve data collected
only during the previous 10 minutes. When historical data
collection is enabled, or for any real time query, data
collected only during the previous 5 minutes is available. At
any time, a maximum of 30,000 rows of data is kept in
memory and available to be returned as a result of a query.
KD42WT: Mediation Configuration_610
This attribute table contains criteria for configuring

mediations. A mediation is the action of applying service
interaction logic to messages flowing between service
requesters and providers.
For example, a mediation can perform the following
functions:
Adapt message formats
Convert transport protocols
Route messages between services
Situations and situation events for WSRR

Situation and event mechanisms are used to propagate service information as
observed by ITCAM for SOA back to WSRR.
683
All the attribute tables introduced in Attributes on page 681 might contribute to
the generation of situation events related to observed services. However, only
the situation events generated from the KD42IT: Services Inventory_610
attribute table are propagated to WSRR.
As previously described, the events identify the situation name, situation status,
and the service port, operation, application server, and computer system where
the event occurred.
Predefined situations for Services Inventory_610 table

ITCAM for SOA provides a set of predefined situations.
The following situations are supported for WSRR integration as they are
generated from the information stored in the KD42IT: Services Inventory_610
attribute table:
Fault_610
MessageSize_610
MaxMessageSize_610
Refer back to Situations on page 679 for a brief description of these predefined
situations.
Note: MessageArrivalCritical_610 and MessageArrivalClearing_610
predefined situations are not supported by WSRR as these are not generated
from the KD42IT: Services Inventory_610 attribute table.
Using predefined situations, operational information about observed services in
ITCAM for SOA is fed back to WSRR whenever one of these operational
circumstances occurs. The corollary of this is that as long as none of these
predefined situations arise (which depends on the settings in use to
parameterize the situations with threshold and time intervals), no monitoring
information is sent back to WSRR.
Two options are available to modify the frequency of these operational feedbacks
from ITCAM for SOA to WSRR:
684
Adjust thresholds and time intervals of the predefined situations to augment

the sensitivity of the situations in response to operational information (see
product documentation)
Define custom situations (see Custom situations for Services Inventory_610
table on page 687)
685
Operational situations in ITCAM for SOA and WSRR:

As described here, the integration between ITCAM for SOA and WSRR
heavily relies on the use of situations, and the default behavior using
predefined situations is that operational information is propagated to WSRR
only when exceptional circumstances arise.
While it is definitively possible to adjust the frequency of these operational
feedback as explained above, this raises the interesting issue of the mapping
between operational situations as observed in ITCAM for SOA and the ones
captured in WSRR.
From an SOA monitoring and management perspective, tracking critical
circumstances such as those predefined in ITCAM for SOA (see Predefined
situations for Services Inventory_610 table on page 684) is particularly
relevant as they directly reflect an abnormal behavior of the overall SOA.
From a service registry and repository perspective, operational data is used to
enrich the description of the registered services, consequently offering more
information to the actors and components of the SOA and enabling them to
make advanced use of service information and metadata.
There is definitively an equivalence between these two perspectives, and part
of the operational situations occurring on services as observed by the
monitoring infrastructure are to be reflected in the registry. For example,
operational information about the quality of the services as observed at
runtime is particularly valuable to augment the description of registered
services and potentially assess the adequation with their expected behavior.
Such information includes observed metrics such as service average
response time or average fault rate.
On the other hand, some operational situations as captured by the monitoring
infrastructure might not directly relate to the definition of services as described
in the registry. Situations like abnormal service traffic or exceptionally big
message payloads, while of particular relevance from an SOA management
perspective, would probably not add any value to the definition of the
registered services.
Another aspect to consider when defining the rules governing the feedback of
operational information from ITCAM for SOA to WSRR is the extra amount of
interactions involved to ensure this feedback between the two components.
This has a direct impact on the performance of these solutions, and might lead
to degraded interactions with other components and actors, potentially
compromising the overall service interaction.
686
Custom situations for Services Inventory_610 table

Custom situations for the KD42IT: Services Inventory_610 table can be defined
using the ITM Situation Editor. This provides an easy yet powerful way to adjust
the frequency of the service operational feedback from ITCAM for SOA to WSRR
without having to wait for critical predefined situation to arise. For example, it is
possible to define a custom situation which would be triggered at a specified time
interval, allowing service status information to be sent back to WSRR on a
regular and configurable basis.
Note: See the ITM 6.1 User's Guide section that describes how to work with
the ITM Situation Editor:
http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp?to
pic=/com.ibm.itm.doc/itm610usersguide227.htm
When creating a situation you can either create a new situation or reuse
another existing situation as a template. The latter option allows you to copy
an existing situation and use it as a base and example for the new situation.
15.7.2 Propagation, capture and processing of situation events

Once situations arise and events are generated, these events are propagated to
an event server or listener.
WSRR provides an IBM Tivoli Composite Application Manager for SOA Event
Handler to listen to, capture and process situation events issued by ITCAM for
SOA in response to operational situations on services.
Propagation of situation events

IBM Tivoli Monitoring can be configured to send events to an event server such
as Tivoli Enterprise Console (TEC) or any event listener that supports the Event
Integration Facility (EIF).
Figure 15-24 on page 688 describes the propagation of situation events from
ITCAM for SOA to WSRR.
687
Event
Event
OTEA

of Situation Events
ITCAM
for
SOA
EIF
Events
Event
Handler
WSRR
Re-send
Rule
WAS
TEC
TEC-OMNIbus
Probe
OMNIbus-TEC
Gateway
OMNIbus
Server
OMNIbus support planned for the future
Figure 15-24 Propagation of situations events from ITCAM for SOA to WSRR
OMEGAMON TEC Event Adapter (OTEA) receive filter, adapts and forwards the
events generated by ITCAM for SOA to the different communication channels
between ITCAM for SOA and WSRR ITCAM for SOA Event Handler.
There are two different ways to propagate events to WSRR ITCAM for SOA
Event Handler:
Configure ITM to forward ITCAM for SOA situation events for the
Services_Inventory_610 table directly to the ITCAM for SOA Event Handler if
no event server is being used with ITM
688
If ITM is configured to forward situation events to TEC, use a re-send

forwarding rule on TEC to send all ITCAM for SOA events to the ITCAM for
SOA Event Handler.
Forwarding events through OMNIbus (OMNIbus is a component of Micromuse
which allows Micromuse events to be funneled into the TEC) will be supported in
the future.
Details on each of these alternatives are provided as part of the working
example. See 15.7, Service status information forwarding on page 677.
Capture and processing of situation events

The ITCAM for SOA Event Handler for WSRR (referred to here as Event
Handler) is designed to reside between WebSphere Service Registry and
Repository and IBM Tivoli Monitoring (ITM).
When an ITCAM for SOA situation event is detected by ITM for a service, ITM
sends out an event to the Event Handler (optionally via Tivoli Enterprise Console)
which updates metadata in the registry for that service.
The Event Handler creates, updates or removes properties on the WSDLPort
and/or SCA Export logical objects in the registry based on the properties
contained in the situation event (see Attributes on page 681).
if the event handler is configured to process the situations events, it uses the
event data to look up a WSDLPort object in WSRR and updates configurable
properties on that WSDLPort object
Figure 15-25 on page 690 illustrates the capture and the processing of situation
events by the ITCAM for SOA Event Handler.
689
Properties
Event
Event
Metadata
Repository

of Situation Events
Properties
Update of Service
Information
Event
Handler
WSRR
WAS
Figure 15-25 Capture and processing of situation events
Details on each of these alternatives are provided as part of the working

example. See 15.7, Service status information forwarding on page 677.
15.7.3 Use of service status information

Operational data is used to enrich the service information managed in WSRR
with additional elements such as:
average response time
fault rate
service availability
Having these operational elements stored in WSRR along with the definition of
services enable other actors and components in the SOA to access this
information and use it in advanced use cases as suggested by the following
examples:
An ESB infrastructure could implement routing policies based on the quality
of interaction as it has been observed from running service implementations.
These routing policies could handle requests issued by different classes of
service consumers and route them to the appropriate service implementation
based on their privileges.
Service consumers could directly access this information to have an idea of
the regular operational behavior of a given service and make consumption
decisions accordingly.
690
Service providers could use this information to define and plan service
migration/retirement strategies based on the utilization rate of a particular
service.
The effectiveness of the SOA can be captured in the service information
where service usage could directly reflect the success overall reuse policy of
services across consumers.
Figure 15-26 depicts a logical architecture where a logical ESB component
would use the enhanced service information and metadata to implement
mediation policies. This logical architecture is an extension of the one which was
introduced previously.
Service
Consumer
Service
consumers
uses service
information
and metadata
to access and
consume
services.
Service Consumer
consumes
virtualized/exposed
services
Service
Provider
ESB
Provided
services are
virtualized
Mediation policy are

based on service
information and
metadata (including
operational data)
Service
Registry
& Repository
Provided
services are
registered in
SRR
Information on
registered services is
made available
Services are
observed by
the Monitoring
and
Management
infrastructure
Monitoring &
Management
Operational data on
observed services
is fed back
Operational data enriches

the service information and
metadata
Information on registered
services is reconciled with that
collected from observed
services and is used to
augment the understanding of
the management domain
Figure 15-26 Use of service status information by ESB infrastructure
691
15.8 Discovery and display of service information:

working example
15.8.1 Scenario
This scenario builds on the scenario described in Chapter 12, Scenarios
description on page 453.
IBM-ITSO Ltd. has implemented and deployed two services, namely
ItemPriceService and ItemPriceDiscountedService. These services are
provided to different classes of customers and are considered key enterprise
assets. As such, they are part of the management domain as monitored
resources, and are observed and controlled by the Management and Monitoring
infrastructure IBM-ITSO Ltd. has deployed using IBM Tivoli Monitoring product
suite.
In this scenario, IBM-ITSO Ltd. is looking at the integration between this
monitoring infrastructure and their enterprise service registry and repository to
ensure the control and management of their services across the overall service
lifecycle.
This scenario describes the integration between IBM-ITSO Ltd. Management
and Monitoring infrastructure based on Tivoli Enterprise Monitoring framework,
most particularly IBM Tivoli Composite Application Manager for SOA, and their
enterprise service registry and repository based on WebSphere Service Registry
and Repository.
15.8.2 Assumptions and prerequisites

It is assumed that ITCAM for SOA v6.1 and the required elements of Tivoli
Enterprise Monitoring Framework are up and running (see 15.3.2, IBM Tivoli
Enterprise Monitoring framework on page 636). The installation procedure is not
documented in this redbook.
It is also assumed that WSRR v6.0.0.1 is up and running as this scenario builds
on the ones previously detailed in this redbook. The following Web services are
deployed on WebSphere Application Server v6.0.2.
Observed services
Figure 15-27 on page 693 summarizes the services as observed by ITCAM for
SOA.
692
Observed Services
(ITCAM for SOA)
ItemPriceService
Figure 15-27 Observed services in ITCAM for SOA (working example)
ItemPriceService and ItemPriceDiscountedService are running on WebSphere

Application Server v6.0.2 as part of the scenario. These are the two backend
services implemented by IBM-ITSO Ltd.
More details about the monitoring of these services are provided in 15.8.5,
Monitoring services using ITCAM for SOA on page 698.
Registered services
Figure 15-28 shows the services registered in WSRR and their associated
lifecycle state.
Registered Services
(WSRR)
ItemPriceService
Manage
ItemPriceEnquiryService
Assemble
Figure 15-28 Registered services in WSRR (working example)
693
ItemPriceService, ItemPriceDiscountedService and ItemPriceEnquiryService

are all registered services in WSRR.
As part of its overall SOA Governance process IBM-ITSO Ltd. has taken these
services through the service lifecycle:
ItemPriceService and ItemPriceDiscountedService have been deployed
and are now part of the SOA management domain. They have reached the
Manage state of the service lifecycle.
ItemPriceEnquiryService has only been assembled but is has not yet been
fully approved for deployment and is obviously not yet part of the SOA
management domain. It has reached the Assemble state.
For more information about the process to take these services through the
service lifecycle in WSRR, refer to 13.2, Using lifecycles on page 476
15.8.3 Logical architecture

The architecture used to illustrate the scenario is deliberately simple and does
not try to reflect a real deployment but rather focusses on demonstrating the key
aspects of the integration between ITCAM for SOA and WSRR.
Figure 15-29 on page 695 provides an overview of the logical architecture of the
scenario.
694
Service Provider
Application Server
Data
Collector
Service
Consumer
ItemPriceService
Monitoring Agent
Service Discovery Adapter

(Observed Services)
Monitoring & Management
Service
Registry
& Repository
Monitoring Server

Service Discovery Adapter
(Registered Services)
Monitoring Console
Monitoring SOA Support
Monitoring Model
Event Listener
Monitoring Warehouse
Figure 15-29 WSRR and ITCAM for SOA working scenario: logical architecture
Figure 15-29 depicts the logical nodes and focusses on the capabilities and
responsibilities of each of the components running on each node.
Note: The nodes depicted here are logical nodes and do not reflect the
operational topology which is described in 15.8.4, Operational architecture
on page 697.
Service Consumer
The Service Consumer logical node hosts the service consumer capabilities and
acts as a requestor for the services deployed on the Service Provider node. This
node is of no particular relevance in the context of our scenario.
Service Provider
The Service Provider logical node hosts the services (ItemPriceService and
ItemPriceDisountedService) that are provided to the consumers. These services
695
are deployed in an managed execution environment (Application Server) and are

exposed as Web services.
A Data Collector collects information from the execution environment about the
interactions between the services and the Service Consumer. The Data Collector
is dedicated to a particular execution environment and acts as a bridge between
this environment and the Monitoring Agent.
A Monitoring Agent uses the information extracted by the Data Collector from the
service execution environment, and propagates them to the Monitoring Server
running on the Monitoring and Management node.
A Service Discovery Adapter discovers the services deployed on this logical
node that are observed by the monitoring infrastructure, and extracts information
about them in order to populate the Monitoring Model.
Monitoring and Management

The Monitoring and Management logical node provides the core capabilities to
centrally monitor and manage the services of the SOA.
The Monitoring Server centrally deliver the core capabilities of the monitoring
infrastructure. It aggregates the information collected by the different Monitoring
Agents and process it, detecting situations, raising events and triggering actions.
The Monitoring Console provides visual interaction channels with the monitoring
infrastructure. Multiple interaction channels might include Web browser as well
as desktop application.
The Monitoring SOA Support component provides support for SOA specific
monitoring aspects such as service and business process centric views. These
views complement the other dimensions of the monitoring and management
domain as explained in 15.1.1, Introduction to SOA management on page 626.
The Monitoring Model captures all information on monitored resources, including
their properties and the relationships among them. It stands as the central
source of information for management activities, and drives the behavior of the
monitoring infrastructure.
Note: Some aspects of the Monitoring Model can be compared to the
Configuration Management DataBase (CMDB) as described in the Information
Technology Infrastructure Library (ITIL) as both deal with the description of
resources and their relationships, therefore helping define, plan and drive
delivery and changes in IT systems.
696
The Monitoring Warehouse archives monitoring information for later retrieval and
analysis. This capability is not illustrated in our scenario.
Service registry and repository

The service registry and repository logical node contains the capabilities needed
to define, store, manage and access service information and metadata. Those
capabilities are provided by the service registry and repository component.
The Service Discovery Adapter discovers the services registered in the service
registry and repository component, and extracts information about them to
populate the Monitoring Model.
The Event Listener captures the events sent by the Monitoring Server. These
events reflect operational information being fed back from the monitoring
infrastructure to the service registry and repository, allowing for additional
enrichment of service information and metadata.
15.8.4 Operational architecture

Figure 15-30 on page 698 provides an overview of the operational architecture.
697
Service Provider
(itso-wmb)
WebSphere Application Server v6.0.2 FP11
ITCAM for SOA Agent v6.1
Service
Consumer
Service Registry & Repository

(itso-wsrr)
Monitoring & Management

(itso-itcam)
TEMS v6.1 FP4
WSRR v6.0.0.1
ITCAM for SOA Application Support v6.1
ITCAM for SOA Event Handler
TEPS v6.1 FP4
WebSphere Application Server v6.0.2 FP11
TEP (Desktop)
WSRR DLA v6.1

DB2 UDB v8.2.5
ITCAM for SOA DLA v6.1

DB2 UDB v8.2.5
Figure 15-30 WSRR and ITCAM for SOA working scenario: operational architecture
All physical nodes are running Windows 2003 Server Service Pack 1.
WSRR and ITCAM for SOA Event Handler are deployed in the same instance of
WebSphere Application Server. Security is turned on, on this application server.
15.8.5 Monitoring services using ITCAM for SOA

In order to demonstrate the reconciliation of observed services with registered
services as described in Reconciliation of observed and registered services on
page 664 we need to monitor the ItemPriceService and
ItemPriceDiscountedSevice services.
698
Note: The detailed procedure to monitor services using ITCAM for SOA is not
described in this redbook.
For more information, refer to the following resources:
IBM Tivoli Composite Application Manager V6.0 Family: Installation,
Configuration, and Basic Usage, SG24-7151 (Part 4: IBM Tivoli Composite
Application Manager for SOA)
Patterns: SOA Foundation Service Creation Scenario, SG24-7240
(Chapter 12: Manage and monitor services with ITCAM for SOA)
Patterns: SOA Foundation Service Connectivity Scenario, SG24-7228
(Chapter 12: Service monitoring and management with IBM Tivoli
Composite Application Manager for SOA)
Best Practices for SOA Management, REDP-4233
You can also refer to the product documentation available at the following
address:
http://www-306.ibm.com/software/tivoli/products/composite-applicationmgr-soa/
These services are observed by ITCAM for SOA using a data collector
implemented as a JAX-RPC Handler (see Monitoring agent on page 649).
The TCORE database has been updated using the DLA book produced by the
ITCAM for SOA Discovery Library Adapter, reflecting the services currently
observed.
Figure 15-31 on page 700 is a screen capture of Tivoli Enterprise Portal
displaying the services in the Physical workspace as they are being observed
using ITCAM for SOA WebSphere Application Server Data Collector after some
traffic involving the two services has been generated.
699
Figure 15-31 ItemPriceService and ItemPriceDiscountedService as observed in TEP Physical workspace
As shown in Figure 15-31:

All the operations provided by each service are observed. In that case, each
service has one single operation called getPrice as displayed in the different
views.
700
Both operations have the same signature and manipulate the same service
data model as the services share the same PortType. Similar average
message sizes for the two services illustrate this as captured in the Average
Message Size view. The slight difference is due to the faults returned as part
of the simulated failures.
ItemPriceService is slower than ItemPriceDiscountedService as captured in
the average response time view. This is the expected behavior as described
in Chapter 12, Scenarios description on page 453.
By using the simulated error cases provided by the two services we can observe
the resulting faults as they are captured in ITCAM for SOA. Figure 15-32 on
page 702 shows the resulting display in the console.
701
Figure 15-32 Observed service faults (working examples)
15.8.6 Understanding WSRR Discovery Library Adapter

WSRR DLA was introduced in Discovery of registered services: WSRR DLA on
page 660. This section provides a more detailed understanding of the design and
the behavior of this component and elaborates on the aspects presented
previously.
702
Note: For more information about WSRR Discovery Library Adapter, refer to
the readme.txt file provided with the installation package.
WSRR DLA design overview

Figure 15-33 provides some details on the design of WSRR DLA.
Event
props
Event
Adapter
Discover
Published
and
Operational
Data in
WSRR
WSRR
WSRRDLA
DLAProcess
Process
- -Discovery
of registered services
Discovery of registered services
- Create Intermediate file
- Create Intermediate file
- Create IdML book using DL API
- Create IdML book using DL API
- Call script to transfer file
- Call script to transfer file
Determine
deltas from
last run
Cached
Discovery
Info
Transfer
book to
DLFS
Discover Library
File Store
Figure 15-33 WSRR Discovery Library Adapter
WSRR DLA extracts information about Web services registered in WSRR.

WSRR DLA is stateful adapter with support of create, modify, delete and refresh
operations. The DLA uses WSRR J2EE API (provided by the WSRR product as
EJBs) to query information about Web services that are considered published or
operational. Custom states can be also specified which override the default
states used in the query. The DLA runs in a J2EE thin client container on a
WSRR server.
The DLA is stateful in that it keeps track of previous discoveries. It will support
both refresh and delta discoveries. The first invocation of the DLA is a refresh.
After the initial run, the DLA takes cached information from the last successful
run and uses that to compare against current information taken from WSRR to
create a delta IdML book with creates, modifies and deletes specified. The ability
to specify a refresh via the command line interface is also be supported. The
DLA is initiated via a command line 'Requestor' which supports the ability to
703
request a refresh and to request DLA discoveries on an on-demand basis.

Scheduling can be done via the native operating system (for example: cron).
The DLA uses the WSRR API to extract information from WSRR and create an
IdML book. In order to create the IdML book, the data from WSRR is formatted
into an IdML book using the Discovery Library API. The IdML book is then be
transferred to the Discovery Library File Store via a user customizable script.
Sample scripts are provided for FTP but other transport methods can be used.
WSRR DLA books

The WSRR DLA generates these types of books:
Refresh: This type of book contains a complete replacement of existing data
from previous runs of the discovery library adapter for a WSRR server.
Resources present from prior runs but not present in a refresh book are
removed from the database when the book is loaded by the bulk load
program. Refresh books represent a snapshot in time, replacing existing
information with new data.
Delta: This type of book contains changes and updates to existing data
imported during previous runs of the discovery library adapter for a particular
WSRR server.
The WSRR DLA creates a refresh book the first time the DLA is run. It creates
delta books on all subsequent runs unless you specify the -r command line
option which forces the creation of a refresh book. The discovery library adapter
maintains a cache to track the changes from previous runs and uses the cache to
determine which new services are included in a delta book. If the discovery
library adapter is run, and no new services have been observed since the
previous run, no book is created unless you specify the -r command line option
to force the creation of a refresh book.
The WSRR discovery library adapter book names consist of the following
segments:
1. WSRRV600: This is the application code of the portion of the book name.
2. Host name: This is the hostname of the server whereWebSphere Service
Registry and Repository is installed.
3. An ISO 8601 UTC (Coordinated Universal Time) time stamp, with colons (:)
replaced by periods (.): This time stamp indicates when the book was
generated.
4. The text refresh if the book is a refresh book.
5. An .xml file name extension.
704
When a discovery library adapter book is loaded using the bulk load program, the
data in the book is associated with the Managed Software System (MSS) that is
identified by the DLA application code and the hostname of the server where
WebSphere Service Registry and Repository is installed. The data for one MSS
does not replace data for another MSS in the database.
The discovery library adapter writes books to the directory that is specified in the
discovery library adapter configuration properties file,
WSRR_DLA.config.properties (see Editing WSRR_DLA.config.properties file on
page 708). If this directory is not accessible to the bulk load program, the
discovery library adapter file transfers books to the computer where the bulk load
program is running. The discovery library adapter supports the File Transfer
Protocol (FTP) or Secure Shell (SSH) File Transfer Protocol (SFTP). SFTP is
only supported when the discovery library adapter is running on a Linux, AIX, or
Solaris operating system. When a book is file transferred, it is removed from the
discovery library adapter local directory once the file transfer completes. A
command line option or configuration property is used to confirm that the file
transfer was successful when FTP is performed. When a file transfer
confirmation is requested, the discovery library adapter reads the book from the
target computer and compares it to the original book. If an error occurs during
the file transfer, the book remains in the local directory. The next time the
discovery library adapter is run, the discovery library adapter attempts to transfer
the book again.
Use a command line interface to run the discovery library adapter. You can either
run the discovery library adapter manually or you can use operating system
utilities, such as cron on the Linux, Solaris, or AIX operating systems to
periodically run the discovery library adapter.
15.8.7 Installing WSRR Discovery Library Adapter

The installation can be considered as a standalone package that can be
dropped in to the owning product's environment.
Note: WSRR Discovery Library Adapter is packaged with ITCAM for SOA v6.1
as a zip file:
WSRRV600_DLA.zip
Prerequisites and deployment options

The WSRR DLA must be installed on the same server as WSRR and is supported
on the following operating systems:
Windows 2003 Server
705
Red Hat Enterprise Linux AS 4.0 on Intel

SuSE Linux Enterprise Server (SLES) 9 on Intel
AIX 5.3
Solaris 10
Note: If security is enabled on the application server where WebSphere
Service Registry and Repository is installed, you must define a user that is
assigned a role to access the WSRR Java API in order to discover Web
services, their artefacts, and WSDL, XSD, and WS-Policy documents. If you
are using the default roles provided by WSRR, this user must be assigned the
Administrator role.
Installation instructions
The WSRR Discovery Library Adapter is packaged in the WSRRV600_DLA.zip file
that also includes a readme.txt file. To install the discovery library adapter,
perform the following steps:
1. Copy the WSRRV600_DLA.zip file to the computer where you plan to install the
discovery library adapter.
2. Create the directory where you plan to install the discovery library adapter.
This directory is referred to as DLA_INSTALL_DIR in this readme.
3. Uncompress the WSRRV600_DLA.zip file into the directory that you created in
step 2:
For the Windows operating system, use an uncompress utility, such as
WinZip. If using WinZip, ensure that the Overwrite existing files and
Use folder names check boxes are selected.
For a Linux, Solaris, or AIX operating system, run the unzip command to
uncompress the .zip file. The following command example uncompresses
the .zip file into the current directory:
unzip ./WSRRV600_DLA.zip
Note: If you are installing the discovery library adapter on the AIX operating
system and your computer does not have the unzip command, download the
unzip command from the IBM AIX support site.
After the files are extracted from the .zip file, the file structure should match
Example 15-1.
Example 15-1 File structure after installing WSRR DLA
[DLA_INSTALL_DIR]
706

--- readme.txt - The readme file
+--- bin - Directorythat contains the discovery library adapter,
scripts and configuration properties files.
+-- cache - Default directory for the discovery library adapter
cache files
+-- jars - Directory for the discovery library adapter .jar files
+-- logs - Default directory for the discovery library adapter log
files
+-- message-doc - Directory that contains HTML files describing the
discovery library adapter log messages
+-- staging - Default directory where the discovery library adapter
books are written
+-- templates - Directory that contains the template files used by
the discovery library adapter file transfer
processing
+-- traces - Default directory for the discovery library adapter

trace files
Working example
In our working scenario, the WSRR DLA is installed on Windows 2003 Enterprise
Server as summarized in Example 15-2.
Example 15-2 Installation of WSRR DLA working example
Machine name = itso-wsrr

[DLA_INSTALL_DIR] = C:\ITSO\WSRR\ITCAMforSOA-WSRR_DLA
Note: At the time of writing we experienced some problems with the Windows
2003 Enterprise installation of WSRR DLA when there were white spaces in
the DLA_INSTALL_DIR path. For example:
C:\Program Files\IBM\ITCAMforSOA-WSRR_DLA
We therefore recommend that the DLA_INSTALL_DIR path you use when
installing WSRR DLA does not contain any white space.
707
15.8.8 Configuring WSRR Discovery Library Adapter

After you install the WSRR Discovery Library Adapter, you need to configure the
discovery library adapter by editing the following properties files and modifying
the variables in the DLA script files.
Editing WSRR_DLA.config.properties file

This file is located in the [DLA_INSTALL_DIR]/bin directory.
Configuration instructions
This file contains properties that specify how to connect to WSRR, the directories
to use when creating books, and how to perform logging and tracing.
At a minimum, configure or verify the values for the following properties:
com.ibm.management.soa.dla.wsrr.address
The value of this property specifies the hostname of the server where
WebSphere Service Registry and Repository is installed. The default value is
localhost.
com.ibm.management.soa.dla.wsrr.port
The value of this property specifies the bootstrap address and JNDI port
number of the WebSphere Application Server environment that WebSphere
Service Registry and Repository is running on. The default value is 2809.
com.ibm.management.soa.dla.wsrr.domainName
The value of this property specifies the domain of the server WebSphere
Service Registry and Repository is installed on. This property is used if the
discovery library adapter is unable to determine the domain name portion of
the hostname from the environment. The default value is ibm.com.
com.ibm.management.soa.dla.wsrr.websphereSecurityEnabled
The value of this property indicates whether security is enabled on the
WebSphere Application Server where WebSphere Service Registry and
Repository is installed. When this property is set to true, you must provide
values for the com.ibm.management.soa.dla.wsrr.userid and
com.ibm.management.soa.dla.wsrr.password properties. The supported
values are true and false. The default value is true.
com.ibm.management.soa.dla.wsrr.securityEnabled
The value of this property specifies if the password property is encoded in the
properties file. If set to true, the password value is replaced with (*) and an
encoded version of the password is added as the value of the
com.ibm.management.soa.dla.wsrr.password.encoded property by the
708
discovery library adapter. If set to false, the password value is not encoded.
The supported values are true and false. The default value is true.
com.ibm.management.soa.dla.wsrr.userid
The value of this property specifies the username that the DLA provides when
using the WSRR Java API. This user must be assigned a role, either the
Administrator or a custom defined role, that can query the desired WSRR
classifications. There is no default value.
com.ibm.management.soa.dla.wsrr.password
The value of this property specifies the password of the user in the
com.ibm.management.soa.dla.wsrr.userid property. There is no default
value.
com.ibm.management.soa.dla.wsrr.uriClassifications
The value of this property specifies the list of classifications the WSRR DLA
uses when retrieving Web service information from WSRR. Only services that
are tagged with the listed classifications are discovered. If no classifications
are listed, or the property is commented out, then all Web services in WSRR
are discovered.
The default classification list is the Deploy (State3) and Manage (State4)
classifications that are installed with WSRR as part of the default service
lifecycle. See 13.2, Using lifecycles on page 476 for a description of how to
use service lifecycles. Other classifications (not necessarily related to states
in the service lifecycle) can be used. Refer to 9.6, Classifying objects on
page 358 for more information about loading and using classifications.
Note: Classifications also apply to WS-Policy documents. For example, if a
policy document is not assigned one of the classifications in the list, the
document is not included in the discovery library adapter book even if it is
associated with a Web service that does match one of the classifications.
com.ibm.management.soa.dla.wsrr.includeDocuments
The value of this property specifies whether the contents of WSDL, XSD, and
WS-Policy documents are included in the WSRR DLA books. If this property
is set to true, the document contents are included in the DLA books. The
supported values are true and false. The default value is true.
709
Note: See the WSRR_DLA.config.properties file for the complete list of

properties and a description of each property.
When specifying directory paths for Windows, use forward slashes instead of
backslashes. Double backslashes can also be used.
For example:
com.ibm.management.soa.dla.wsrr.dlfs.local=C:/DLA/staging
com.ibm.management.soa.dla.wsrr.dlfs.local=C:\\DLA\\staging
Working example
In our example we edit the WSRR_DLA.config.properties file and define the
content of the required properties as summarized in Example 15-3.
Example 15-3 WSRR_DLA.config.properties
# WebSphere Service Registry and Repository host information

com.ibm.management.soa.dla.wsrr.address=localhost
com.ibm.management.soa.dla.wsrr.port=2809
com.ibm.management.soa.dla.wsrr.domainName=itso.ral.ibm.com
# WebSphere Service Registry and Repository Credentials
com.ibm.management.soa.dla.wsrr.websphereSecurityEnabled=true
com.ibm.management.soa.dla.wsrr.securityEnabled=true
com.ibm.management.soa.dla.wsrr.userid=itcam4soa
com.ibm.management.soa.dla.wsrr.password=passw0rd
com.ibm.management.soa.dla.wsrr.password.encoded=
# WebSphere Service Registry and Repository Classifications Filter
com.ibm.management.soa.dla.wsrr.uriClassifications='http://www.ibm.com/
xmlns/prod/serviceregistry/6/0/governance/DefaultLifecycle#State3','htt
p://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/DefaultLifecy
cle#State4'
A few comments on this configuration file:
WSRR DLA and WSRR are installed on the same machine, hence the use of
localhost in the configuration file.
WSRR security is turned on to demonstrate a possible deployment in a real
production environment. We provide credentials in the configuration file to
enable WSRR DLA to use WSRR APIs in a secured mode. We set the
com.ibm.management.soa.dla.wsrr.securityEnabled property to true to
710
have WSRR DLA process encrypt the password and valuate the
com.ibm.management.soa.dla.wsrr.password.encoded property with the
encoded value while removing the unencrypted one. As described in
Chapter 12, Scenarios description on page 453, we use specific credentials
(uid=itcam4soa, pwd=passw0rd) for ITCAM for SOA to access WSRR as an
identified actor in the overall SOA.
We use the default lifecycle and its associated classification so that WSRR
DLA only discovers services that are classified as Manage or Deploy as a
consequence of their state in the service lifecycle. This is the default value
for the com.ibm.management.soa.dla.wsrr.uriClassifications property.
Editing DLA_FileTransfer.properties file

This file is located in the [DLA_INSTALL_DIR]/bin directory.
This file contains the properties that specify how to connect to the file transfer
server, the directories to use when transferring books, and how to perform
logging and tracing.
At a minimum, the following properties must be configured for the discovery
library adapter to perform a file transfer:
com.ibm.management.soa.dla.filetransfer.host
The value of this property specifies the host name or IP address of the target
computer. Books are transferred to this computer by the discovery library
adapter.
com.ibm.management.soa.dla.filetransfer.userid
The value of this property specifies the username that is used to access the
target computer. This user must be granted the authority to write files to the
target directory. If using FTP with confirmation, the user also requires
authority to read and delete files in the target directory.
com.ibm.management.soa.dla.filetransfer.password
The value of this property specifies the password of the user that is used to
access the target computer.
Note: Changing the value of other file transfer properties might be required if
you do not want to use the default values in the properties file, such as the
default directory on the target computer.
See the DLA_FIleTransfer.properties file for the complete list of properties and
a description of each property.
711
Note: If patches are applied, the WSRR_DLA.config.properties and

DLA_FileTransfer.properties files might be overwritten. Back up the
discovery library adapter properties files so you can migrate existing settings
into new versions of the properties files.
Using SFTP
If you plan to use the SFTP protocol to file transfer discovery library adapter
books when the discovery library adapter is installed on a Linux, AIX, or Solaris
operating system, you must perform the following steps to configure SSH:
Ensure that SSH is installed on both the source and target computers.
Log on to the source computer as the user who runs the discovery library
adapter and generate public and private keys. On most systems, use the
ssh-keygen command. Press Enter when prompted for a passphrase for the
easiest configuration.
On the target computer, log on as the user that the discovery library adapter uses
when accessing the target computer. Add the contents of the public key from the
source computer into the ~/.ssh/authorized_keys file.
Note: If you created the keys using a passphrase, use the ssh-agent and
ssh-add commands to prevent a prompt for the pass phrase. See the following
URL for more information:
http://www.ibm.com/developerworks/library/l-keyc2/
Use the sftp command on the source computer to check connectivity to the
target computer and verify that no password or passphrase prompt is presented.
For example:
sftp user@targetserver.com
Note: When SFTP is used, a value for the password property is still required
in the DLA_FileTransfer.properties file. However, the value of the password
property is not used.
If you do not generate public and private keys, the discovery library adapter
cannot transfer books using the SFTP protocol.
712
Working example
We do not use FTP or SFTP transfer in our working scenario. WSRR DLA books
are manually copied to the ITM installation.
Editing the WSRR DLA script files

You must also edit the WSRR DLA script files to reference both the WAS and
WSRR client installation path.
If you installed the DLA on a Windows operating system, edit the
[DLA_INSTALL_DIR]\bin\WSRR_DLA.bat file, and, if you installed the DLA on a
Linux, AIX, or Solaris operating system, edit the
[DLA_INSTALL_DIR]/bin/WSRR_DLA.sh file.
Make sure the following variables are defined accordingly:
WAS_BIN
Set this variable to the location of WebSphere Application Server bin directory
as shown in Example 15-4.
Example 15-4 Setting the WAS_BIN variable in WSRR DLA script files
On a Linux, AIX, or Solaris operating system:

WAS_BIN=/opt/IBM/WebSphere/AppServer/bin
On a Windows operating system:
WAS_BIN=C:\Program Files\IBM\WebSphere\AppServer\bin
WSRR_CLIENT_DIR
As shown in Example 15-5, set this variable to the directory that contains the
WSRR client jar file, ServiceRegistryClient.jar. This jar file is installed with
WSRR.
Example 15-5 Setting the WSRR_CLIENT_DIR variable in WSRR DLA script files
On a Linux, AIX, or Solaris operating system:

WSRR_CLIENT_DIR=/opt/IBM/WebSphereServiceRegistry
On a Windows operating system:
WSRR_CLIENT_DIR=C:\Program Files\IBM\WebSphereServiceRegistry
Working example
In our example we edit the [DLA_INSTALL_DIR]\bin\WSRR_DLA.bat file and define
the content of the variables as shown in Example 15-6 on page 714.
713
Example 15-6 Setting WSRR DLA script files: working example
set WAS_BIN=C:\Program Files\IBM\WebSphere\AppServer\bin

set WSRR_CLIENT_DIR=C:\Program Files\IBM\WebSphereServiceRegistry
15.8.9 Using WSRR Discovery Library Adapter

Running WSRR DLA performs the following operations:
Connect to WSRR using security credentials if security is on
Extract registered services from WSRR
Create an intermediate file to convert extracted information
Create an IdML book using Discovery Library API
Transfer the books from the local DLA staging directory to the Discovery
Library File Store using transfer script
Using WSRR_DLA script

To use WSRR DLA you run the WSRR_DLA script dedicated to your
environment.
Execution instructions
Running the WSRR Discovery Library Adapter involves the following steps:
1. Using a command interpreter, change directories to the
[DLA_INSTALL_DIR]/bin directory.
2. Run the WSRR DLA using the following options:
For a Windows operating systems: WSRR_DLA.bat [OPTIONS]
For all other operating systems: ./WSRR_DLA.sh [OPTIONS]
The options to be passed to the script ([OPTIONS]) are the following:
[-o configfile]
This option specifies the name of the discovery library adapter configuration
properties file. The directory containing the properties file must be in the DLA
classpath.
The [DLA_INSTALL_DIR]/bin directory is in the classpath by default. If this
option is not specified, the
[DLA_INSTALL_DIR]/bin/WSRR_DLA.config.properties file is used.
[-p protocol]
Specifies the file transfer protocol. The default is FTP.
714
SFTP is also supported when the discovery library adapter is installed on a

Linux, AIX, or Solaris operating system.
[-r]
Create a refresh book.
[-c]
Confirm the file transfer. This option passes the confirm flag to the file transfer
script and overrides the value specified in the
com.ibm.management.soa.dla.filetransfer.confirmTransfer property.
[-d]
Do not perform post-discovery file transfer.
[-?]
Displays the script options
Working example
In our scenario we run the WSRR DLA to extract information about the services
that are classified as Managed or Deployed. This reflects the fact that these
services are governed entities and have gone through some stages in the
service lifecycle as described in Registered services on page 693.
The following table summarizes the different services registered in WSRR before
the execution of the WSRR DLA.
Table 15-9 Services registered in WSRR before running WSRR DLA
Service
Lifecycle State
ItemPriceService
Managed
Managed
Assembled
We run the WSRR DLA by issuing the following commands in a DOS command
windows.
Example 15-7 Running WSRR DLA
C:\>cd C:\ITSO\WSRR\ITCAMforSOA-WSRR_DLA\bin
C:\ITSO\WSRR\ITCAMforSOA-WSRR_DLA\bin>WSRR_DLA.bat -r -d
The last command line:
Forces the creation of a refresh book (-r option)
715
Does not perform post-discovery file transfer (-d option)

Example 15-8 describes the output which is displayed in the console and is also
captured in the WSRRDLALog.log log file located in [DLA_INSTALL_DIR]/logs.
Example 15-8 WSRR DLA execution log
C:\ITSO\WSRR\ITCAMforSOA-WSRR_DLA\bin>WSRR_DLA.bat -r -d
2006-12-12 20:22:02.391-05:00 [main] KD4SR0017I The discovery library adapter is starting its
discovery process.
2006-12-12 20:22:09.047-05:00 [P=922438:O=0:CT] KD4SR0010I The discovery library adapter book:
WSRRv600.ITSO-WSRR.itso.ral.ibm.com.2006-12-13T01.22.06.219Z.refresh.xml was generated and
stored into the following directory: ../staging\.
2006-12-12 20:22:09.078-05:00 [P=922438:O=0:CT] KD4SR0018I The discovery library adapter is
exiting its discovery process.
The resulting WSRR DLA book should appear in the

[DLA_INSTALL_DIR]/staging directory with a refresh.xml extension:
WSRRv600.ITSO-WSRR.itso.ral.ibm.com.2006-12-13T01.22.06.219Z.refresh.xml
Note: Depending on your configuration and your context the name of the
WSRR DLA book is likely to be different.
While the format of the resulting DLA book is rather verbose, it is still easy to
verify that only the services that were in the Manage state were discovered, that is
ItemPriceService and ItemPriceDiscountedService. You can perform a quick
search on these two names to make sure you find the following occurrences in
the xml file.
<cdm:soa.WebService
id="http://itso.ibm.com#WebService#ItemPriceService" >
<cdm:soa.WebService
id="http://itso.ibm.com#WebService#ItemPriceDiscountedService" >
There should be no mention of the ItemPriceEnquiryService which was in the
Assemble state.
This example stresses the importance of service classification to be able to
handle a large number of services.
Transferring WSRR DLA book to Discovery Library File Store

Once created the WSRR DLA book needs to be transferred to the Discovery
Library File Store.
716
Transfer instructions
Transfer of DLA books can be automatically performed by the DLA scripts when
configuration values have been specified in the configuration files. See Editing
DLA_FileTransfer.properties file on page 711.
Working Example
In our example, we do not use the automatic book transfer feature but rather
manually copy the WSRR DLA book to the appropriate directory.
We use the following directory as the DLFS on the itso-itcam machine:
C:\ITSO\WSRR\DLA\books
Loading WSRR DLA book into the TCORE database

The WSRR DLA book stored in the Discovery Library File Store needs to be
loaded into the TCORE database to enrich the Common Object Repository with
additional information describing the services registered in WSRR. This is done
using the Bulk Load Program.
Bulk Load Program

The bulk load program loads Identity Markup Language (IDML) XML files called
books from the Discovery Library File Store into the Tivoli Common Object
Repository. It is useful for loading large numbers of managed elements and
relationship data into the Tivoli Common Object Repository. You can use
operating system utilities such as cron on Linux or AIX to periodically run the bulk
load program to load new files as they appear in the shared directory, or you can
run the bulk load program manually as new files become available.
Running the Bulk Load Program

All information about how to run the Bulk Load Program is included in the
following document: Tivoli Composite Application Manager for SOA - Version
6.1.0 - Installation and Users Guide, GC32-9492-01. In particular, refer to The
Bulk Load Program section in Chapter 12. Using Discovery Library Adapters.
Working example
Run the Bulk Load Program as follows:
cd C:\IBM\ITM\CNPS\Products\KD4\tcore\bin
The location of the Bulk Load Program can vary depending on your installation.
loadidml -f C:\ITSO\WSRR\DLA\books\<book name>
717
In our case <book name> is:

WSRRv600.ITSO-WSRR.itso.ral.ibm.com.2006-12-13T01.22.06.219Z.refresh.xml
Example 15-9 describes the execution and the result of the Bulk Load Program
after loading the WSRR DLA book previously extracted.
Example 15-9 Bulk Load Program (working example)
C:\IBM\ITM\CNPS\Products\KD4\tcore\bin>loadidml -f
C:\ITSO\WSRR\DLA\books\WSRRv6
00.ITSO-WSRR.itso.ral.ibm.com.2006-12-13T01.22.06.219Z.refresh.xml
C:\IBM\ITM\CNPS\Products\KD4\tcore\bin>call setenv.bat
Bulk Load Program starting.
Bulk Load Program running.
Bulk Load Program running.
Bulk Load Program succeeded. Return code is: 0
0
Bulk Load Program ending.
At this point the TCORE model should have been updated to reflect both the
services as they are observed by ITCAM for SOA and the services registered in
WSRR. The situation should be the one depicted in Figure 15-34 on page 719.
718
Observed Services
(ITCAM for SOA)
Registered Services
(WSRR)
ItemPriceService
ItemPriceService
WSRR
DLA Book
(Registered Services in
Deploy or Manage state )
ITCAM for SOA

DLA Book
(Observed Services)
ItemPriceService
ItemPriceService
TCORE /
CCMDB
ItemPriceService
Figure 15-34 Observed and registered services in TCORE: working example
15.8.10 Reconciling service information using ITCAM for SOA

To explore the managed resources and the topology of the management domain,
and perform visual reconciliation between observed services and registered
services, we use the Tivoli Enterprise Portal.
Accessing the Services Management workspace

We use the Services Management workspace which was described in Services
Management workspace on page 663.
As for any other workspace, we access this workspace using the Navigator View
and selecting either the ITCAM for SOA option in the combo box or the ITCAM for
SOA tab if the Services Management workspace has been opened previously.
Figure 15-35 on page 720 illustrates this.
719
Figure 15-35 Accessing Services Management workspace using the Navigator View in
TEP
Note: The Services Management workspace is not enabled by default on the

ITCAM for SOA installation. To enable it, refer to the product documentation.
Exploring the Services Overview table view

The Services Overview table view is the main view of the Services Management
workspace, and is displayed by default when opening that workspace as shown
on Figure 15-36.
Figure 15-36 Services Overview table view in TEP
720
The Services Overview table view allows us to reconcile service information

extracted from the different sources (ITCAM for SOA and WSRR) by displaying
the following information for the two discovered services, namely
ItemPriceService and ItemPriceDiscountedService:
The name of the Service Ports
In that case the two services have different ports: ItemPrice (for
ItemPriceService) and ItemPriceDiscounted (for
ItemPriceDiscountedService)
The name of the Operations
Both services sharing the same PortType, they have the same single
getPrice operation.
The name of the Services
Both services appear here: ItemPriceService and
ItemPriceDiscountedService.
The name of the Application Servers where the Service Ports are deployed
Both services are deployed onto the same instance of WebSphere
Application Server which is called server1.
The IP address of the Computer System where these services are running
As mentioned above, both services are running on the same machine.
The observation status of the Service Ports
Both services are currently monitored by ITCAM for SOA, as represented by
the Observed checked box.
The registration status of the Service Ports
Both services are currently registered in WSRR, as represented by the
Registered checked box.
Note: As mentioned in Reconciliation of observed and registered services
on page 664, there might be cases where the observation and registration
status differ. Our working example does not illustrate one of these situations
but rather focusses on one simple case, obviously without claiming to closely
reflect a complete real-life SOA management scenario.
Exploring the Service Details view

We access the Service Details view by either double-clicking on of the row in the
Services Overview table view or by selecting one row, right-clicking to display the
contextual menu, and selecting View Service Details.
721
Figure 15-37 and Figure 15-38 on page 723 illustrate the Service Details views
associated respectively with ItemPriceService and
ItemPriceDiscountedService.
Figure 15-37 Service Details view: ItemPriceService
722
Figure 15-38 Service Details view: ItemPriceDiscountedService
These visual representations of the service topology are built from the
information stored in the Common Object Repository describing each of these
services and related resources:
Services: ItemPriceService and ItemPriceDiscountedService are
represented as bells.
Service Ports: ItemPrice and ItemPriceDiscounted are represented as bells
linked to gearings.
Operation: the single getPrice operation provided by both services is
represented as a gearing.
Server: both services are running on the same server called server1.
While our example is pretty straightforward, more complex topologies would take
advantage of this visual representation mode to provide an immediate
understanding of the relationships among the different resources of the SOA.
One can obtain more information either using the hover help or the table view.
Hover help is triggered by hovering the mouse for some time over the selected
element as illustrated in Figure 15-39 on page 724.
723
Figure 15-39 Hover help in Service Details view
Switching between topology view and table view in the Service Details view is
done using either the dedicated buttons in the toolbar or the Topology View as
Table/View as Topology items in the contextual menu. Figure 15-40 illustrates
the Service Details view of ItemPriceService displayed in a table view.
Figure 15-40 Table view of ItemPriceService Service Details
The table view provides more information about all resources linked to a given
service than the corresponding topology view, for example:
Name of the resource
Type of the resource
Namespace for Operation, Service and Service Port resources
Associated PortType for Operation and Service Port resources
IP address of the hosting Computer System for Server resources
Relationships between the different resources
Note: Additional attributes for each resource can be displayed or hidden using
the filtering mechanism provided by the table view.
724
Exploring the Metadata view

Provided the necessary information (that is, WSDL and XSD documents) has
been discovered in WSRR and imported into the Common Object Model during
the service discovery phase, a Metadata view is available on the following type or
resources:
Service
Service Port
Operation
Accessing the Metadata view is done using the contextual menu on the desired
resource as illustrated in Figure 15-41.
Figure 15-41 Accessing Metadata view in TEP
When accessing the Metadata view for the ItemPriceService, we are displayed a
selection dialog to choose the metadata documents we want to view. This
process is illustrated in Figure 15-42 on page 726.
725
Figure 15-42 Selecting metadata documents to display for ItemPriceService
This process provide support for multiple metadata documents related to a given
resource to be displayed in TEP.
In our example above, ItemPriceService has two related metadata documents:
ItemPricePortType.wsdl: this is the interface WSDL, where PortType,
Messages and Schemas are defined.
ItemPrice.wsdl: this is the implementation WSDL for the ItemPriceService,
which references the ItemPricePortType WSDL document.
Figure 15-43 on page 727 illustrates the display of ItemPricePortType.wsdl
metadata document for ItemPriceService.
726
Figure 15-43 ItemPricePortType.wsdl metadata document for ItemPriceService
15.9 Forwarding service status information - working

example
In the previous part of the scenario we have reconciled the services observed by
ITCAM for SOA with the ones registered in WSRR.
This part of the scenario describes a working example where we use the
situation and event mechanisms provided by ITCAM for SOA to forward
operational information to WSRR. Refer to 15.7, Service status information
727
forwarding on page 677 for more information of the key aspects of this
integration.
15.9.1 Understanding ITCAM for SOA Event Handler

ITCAM for SOA Event Handler was introduced in Capture and processing of
situation events on page 689. This section provides more information about this
component.
Figure 15-44 describes a high level break-down of ITCAM for SOA Event
Handler.
ITCAMListener.ear
Event
Event Adapter
Properties
Configuration
File
Integration
Logic
Editor for
Configuration File
WSRR
Metadata
Repository
Web Browser
Figure 15-44 ITCAM for SOA Event Handler
Events sent by ITCAM for SOA using the Event Integration Facility or EIF (see
Propagation of situation events on page 687) are captured by the Event
Adapter which adapts the content of the event to the internal data model,
including the properties of the event.
The adapted event is passed to the Integration Logic which processes the event
received and updates the content of the corresponding elements in WSRR using
the Web Services API.
728
The processing of the events, the update of corresponding properties in WSRR,

the configuration of the Event Adapter and the connectivity to WSRR are
governed by an internal XML configuration file.
The manipulation of the configuration file is performed using a dedicated Editor
provided by the Event Handler package. The Editor takes the form of a Web
console which is packaged with the Event Handler and is deployed at the same
time.
The Event Handler is packaged as an EAR file and must be deployed on a
WebSphere Application Server.
15.9.2 Installing ITCAM for SOA Event Handler

This section describes the installation procedure of ITCAM for SOA Event
Handler for WSRR, also referred to as ITCAM for SOA Event Handler.
Installation prerequisites
The following are prerequisites for the ITCAM for SOA Event Handler:
IBM WebSphere Application Server V6.0.2 and Fix Pack 11 or later. This can
be the same application server to which the registry is installed.
IBM WebSphere Service Registry and Repository 6.0.0.1 installed and
configured.
IBM Tivoli Monitoring V6.1 Fixpack 4
IBM Tivoli Composite Application Manager for SOA V6.1
Tivoli Enterprise Console V3.9 (optional)
ITCAM for SOA Event Handler is packaged as part of the WSRR 6.0.0.1 ITCAM
for SOA Event Handler SupportPac. This SupportPac is now available as a
archive file for customer download at the following URL:
http://www.ibm.com/support/docview.wss?rs=171&uid=swg24014240&loc=en
_US&cs=utf-8&lang=en
Installation instructions
1. For Windows download sa04.zip to a temporary location. For Linux or Unix
download sa04.tgz to a temporary location.
2. Extract ITCAMListener.ear from the downloaded file to a temporary location.
3. Using the WebSphere Application Server administration console or command
line wsadmin tool, deploy the ear to the chosen installation of WebSphere
Application Server.
729
For more information about the installation of an Enterprise Application, refer to

the WebSphere Application Server InfoCenter.
Important: If installing to an instance of WebSphere Application Server other
than that with WebSphere Service Registry and Repository installed, two
client jars are required:
ServiceRegistryClient.jar (from the registrys default installation
directory)
sdo-int.jar (from [WAS_HOME]/classes after having run the WSRR
installall script)
Both client libraries must be copied to the [WAS_HOME]/classes directory on
the server where the Event Handler is intended to reside.
Working example
In our example we install the Event Handler on the same instance of WebSphere
Application Server that already hosts WSRR. Hence we do not need to copy the
extra client jars to that instance.
Installing the ITCAMListener.ear file as a new Enterprise Application is
performed using the administration console. Start the application.
Figure 15-45 shows the result of the installation in WebSphere Application
Server administration console after application has been started.
Figure 15-45 ITCAM for SOA Event Handler installed as an Enterprise Application in
WebSphere Application Server administration console
730
15.9.3 Configuring ITCAM for SOA Event Handler

This section describes the configuration procedure of ITCAM for SOA Event
Handler for WSRR.
Configuration of the ITCAM for SOA Event Handler is performed via a Web
configuration console. The URL for this is:
http://<server name>:<port number>/ITCAMWeb/admin
Figure 15-46 illustrates the Web configuration console provided by ITCAM for
SOA Event Handler.
Figure 15-46 ITCAM for SOA Event Handler Web configuration console (Configuration page)
The default page is the Configuration page.
731
From this page the registry which is to be updated by the Event Handler is
specified, along with any required security information and logging information.
On the left-hand side is a navigation pane with links to the State page, where the
Event Handler is stopped and started, and the EventMapping page where the
incoming events that are to be mapped to custom properties in the registry are
specified. The Configuration link points to the Configuration page.
Pressing Submit saves the configuration and pressing Refresh reverts the
configuration page back to the currently saved configuration.
Figure 15-47 illustrates the State page of the ITCAM for SOA Event Handler
configuration console.
Figure 15-47 ITCAM for SOA Event Handler Web configuration console (State page)
Figure 15-48 on page 733 illustrates the EventMapping page of the ITCAM for
SOA Event Handler configuration console.
732
Figure 15-48 ITCAM for SOA Event Handler Web configuration console (EventMapping page)
The following sections describe the various aspects of the Event Handler that
require configuration. These configuration points are all accessed using the Web
configuration editor and the navigation pane located of the left part of the screen.
ITCAMListener (Configuration page)

Port is the TCP/IP port that the Event Handler listens on for events. It should be
left as 1111 unless there in a port clash with an existing service on the server on
which the Event Handler is installed.
IBM Tivoli Monitoring or the Tivoli Enterprise Console must also be configured to
use this same port number.
See the sections Configuring IBM Tivoli Monitoring for Event Handler on
page 746 and Configuring IBM Tivoli Enterprise Console for Event Handler on
page 752 for more details.
WSRRLocation (Configuration page)

Endpoint is the Web services endpoint of the WebSphere Service Registry and
Repository which the Event Handler updates.
733
Assuming security is off for the server where WSRR instance is running, then the
endpoint should be:
http://<server name>:<port number>/WSRRCoreSDO/services/WSRRCoreSDOPort
For example:
http://myserver:9080/WSRRCoreSDO/services/WSRRCoreSDOPort
If security is enabled for the server where WSRR instance is running, then the
endpoint should be:
https://<server name>:<secure port
number>/WSRRCoreSDO/services/WSRRCoreSDOPort
For example:
https://myserver:9443/WSRRCoreSDO/services/WSRRCoreSDOPort
UID and PWD refer to the username and password required to log in to WebSphere
Service Registry and Repository. These are only needed when security is
enabled, otherwise leave blank.
HTTPS (Configuration page)

If security is not enabled for the server where WSRR instance is running, leave
this check box unchecked and continue to the next section. If security is enabled,
check this box and specify the locations and passwords of the trust store and key
store.
Find more information in the WebSphere Application Server V6.0 Information
Center.
EIFLogger (Configuration page)

Logging and tracing parameters for the Event Integration Facility (EIF) used by
the Event Handler are specified in this section.
The file where the logging is saved is specified as LogFileName, and the tracing
file is specified as TraceFileName. They are in the usual format for the operating
system.
LogLevel and TraceLevel specify the level of logging (or tracing). Use the default
values unless otherwise instructed by IBM support personnel.
The Event Handlers traces are specified in the WebSphere Application Server
Admin Console. See the Information Center for more details. The Event
Handlers log messages are written to the application servers SystemOut.log file.
734
EventMap (EventMapping page)

The EventMap defines how the Event Handler processes the situation events
received from ITCAM for SOA, and how these events are turned into
modifications on the service properties managed by WSRR.
The EventMap configuration is accessed by following the EventMapping link on the
left-hand side of the page. Here events of interest are identified for mapping to
property updates in the WebSphere Service Registry and Repository.
Each row in the table represents one mapping for events with a given situation
name, which is also called an EventID. Each event has a status of either Y, N or P,
representing, respectively:
the situation is open meaning the situation event is received (Y)
the situation is closed meaning the situation has been cleared (N)
the situation is no longer being monitored (P)
When a status=Y event of interest is received by the Event Handler, it attempts to
create or update a property as specified by the Received type and value in the
EventMap table, explained below.
When a status=N event is received by the Event Handler, it attempts to update
the property using the Cleared type and value information.
A status=P event received by the Event Handler causes all properties associated
with that EventID to be removed from the repository.
When the Event Handler is first installed there are several event mappings
preconfigured. For each mapping there are the following settings.
Table 15-10 ITCAM for SOA Event Handler: default settings for event mapping
Setting
Explanation
EventID
The name of the ITCAM for SOA

situation. You can use any of following names (predefined situations) or use
custom names for custom situations:
Fault_610
MessageSize_610
MaxMessageSize_610
WSRRPropertyName
The name of the property to be created,

updated or removed in the WSRR
735
Setting
Explanation
Compound
Appends the name of the service operation that triggered the event to the front
of the property name, for example methodname.propertyname.
This differentiates properties associated with different operations that share a
service endpoint.
Received Type
(WSRRPropertyValue)
The Received Type section is used for

events received with a status of Y.
Possible values are Property Value or Static String:
A value of Property Value indicates that the WSRR property will contain
the value of the event property entered in the Received Value column. See
the ITCAM for SOA Event Properties section for the list of event property
names that can be specified.
A value of Static String indicates that the WSRR property will contain the
value specified in the Received Value column.
Received Value
(WSRRPropertyValue)
Used for ReceivedTypes of Property Value and Static String, this value is used
to specify which event property of the incoming event to put in the registry
property value, or the static string to put in the registry property value.
See ITCAM for SOA event properties on page 737 for the list of event property
names that can be specified for this setting when the Received Type is set to
Property Value.
Cleared Type
(WSRRPropertyValue)
The Cleared Type selection is used for events received with a status of N.
Possible values: Removal, Property Value or Static String:
A value of Removal indicates the WSRR property associated with the
received event will be removed.
A value of Property Value indicates the value of the WSRR property
associated with the received event will be updated with the value of the
event property entered in the Cleared Value column.
A value of Static String indicates the value of the WSRR property
associated with the received event will be updated with the value of the
string entered in the Cleared Value column.
Cleared Value
(WSRRPropertyValue)
Used for Cleared Types of Property Value and Static String, this value is used
to specify which event property of the incoming clearing event to place in the
registry property value, or the static string to place in the registry property value.
Disabled when Cleared Type is Removal.
See ITCAM for SOA event properties on page 737 for the list of event property
names that can be specified for this setting when the Cleared Type is set to
Property Value.
New event mappings can be introduced by pressing the create button which
creates an empty row in the table. When this page is revisited the EventIDs are
ordered alphabetically, so a new event map may no longer be seen at the bottom
of the table. Pressing Submit saves the configuration and pressing Refresh
reverts the configuration page back to the last saved configuration.
736
Any ITCAM for SOA situation can be configured to write corresponding

properties in WSRR. Each situation should be assigned to a unique property
name. Sharing properties among situations causes unpredictable results due to
the random ordering of events that clear situations.
ITCAM for SOA Message Arrival events are ignored by the Event Handler as they
are pure events and do not originate from the Services Inventory_610 table.
Note: In addition to the WSRR property defined in the event map, the Event
Handler also writes or removes correlation properties in the registry. The
name of the correlation property is a concatenation of values received in the
event:
<situation_name>---<situation_displayitem>---<situation_origin>
For example:
ResponseTimeCritical_610---343e64e14341cc26267585b1f84a2e8d---D4--46
7c60d6--cs-gr2qh5jaqiz-serve
Its value is the name of WSRR property that is written for the received event,
for example, ResponseTime.
The correlation property allows the Event Handler to identify the WSRR
property that needs to be changed or removed when the situation clears.
Event Handler Runtime (State page)

Once the configuration of the Event Handler has been saved it does not take
effect until the Event Handler application has been [re]started. Start the Event
Handler by clicking on the State link on the left-hand side of the page, then click
Submit so that the Event Handler state changes to active.
To restart the Event Handler application, click Submit twice: once to stop the
application and again to start it. When the application server is restarted, the
Event Handler and its listener will automatically be started.
ITCAM for SOA event properties

Event properties describe the information contained in the situation event that the
Event Handler can use and process to update the service metadata managed by
WSRR.
Table 15-11 on page 738 lists (in alphabetical order) the names of the event
properties in the ITCAM for SOA events generated from the Services
Inventory_610 table, also called an attribute group. See Situations and situation
events for WSRR on page 683.
737
Note: If you define a custom situation for the Services Inventory_610 table
that the Event Handler should process, you must select the Unique_Key_U
event property as the value of the Display Item selection when configuring
the advanced situation options.
Table 15-11 ITCAM for SOA event properties
Event property name
Description
appl_label
Application specific data related with the event, if any.
application_server_cellName_u
Name of the application server cell where the port and operation are
deployed.
application_servercluster_u
Name of the application server cluster where the port and operation
are deployed.
application_servername_u
Name of the application server where the port and operation are
deployed.
application_server_nodename_u
Node name of the application server where the port and operation
are deployed.
application_serverenv
Specifies the application server environment:

1=WebSphere Application Server
2=.NET
3=WebLogic Server
4=JBoss
5=CICS
6=SAP
7=WebSphere Community Edition
8=DataPower
9=Service Component Architecture
avg_elapsed_time
Average elapsed round trip time in milliseconds during this

monitoring interval.
This does not include values which were set to -1 to indicate entry
requests.
avg_msg_length
The average message length, in bytes, observed during this

monitoring interval (including headers when possible).
cms_hostname
TCP/IP host name of the Tivoli Enterprise Monitoring Server that

forwards the event.
cms_port
Tivoli Enterprise Monitoring Server port on which the service is

listening.
elapsed_time_msg_count
Number of messages observed during this monitoring interval that

contain an elapsed time value.
738
Event property name
Description
fault_count
Number of faults observed during this monitoring interval.
hostname
Base event class attribute that contains the TCP/IP hostname of the
managed system where the event originates, if available.
integration_type
Indicator to help Tivoli Enterprise Console performance:

N for a new event, the first time the event is raised
U for update event, subsequent event status changes
interval_begin_time
Inclusive beginning date and time of the monitoring interval.
interval_end_time
Exclusive ending date and time of the monitoring interval.
interval_length
Length of the monitoring interval in minutes.
interval_status
Specifies the status of this monitoring interval:

1=Incomplete
2=Complete
Incomplete means the end of this monitoring interval has not yet
been reached.
local_hostname_u
Hostname of the machine where the port and operation are deployed
local_ipaddress_u
IP address of the machine where the port and operation are deployed
master_reset_flag
Master reset indicator set for master reset events:

R for Tivoli Enterprise Monitoring Server recycle master_reset
S for hotstandby master_reset
NULL for all other events
max_elapsed_time
Largest elapsed time, in milliseconds, of any message observed

during this monitoring interval.
max_msg_length
Length of the largest message, in bytes, observed during this

min_elapsed_time
Smallest elapsed time, in milliseconds, of any message observed

during this monitoring interval.
min_msg_length
Length of the smallest message, in bytes, observed during this

msg
Base event class attribute that contains the situation name and
formula.
msg_count
The number of messages observed during this monitoring interval.
operation_name_u
Web Services Description Language (WSDL) operation name
operation_namespace_u
Namespace used to fully qualify the operation name.
739
Event property name
Description
port_namespace_u
Namespace used to fully qualify the service port name.
port_number
The number of the port, 0 - 65535, on which the application container

being monitored is listening. -1 if unknown.
severity
Base event class attribute that contains the resolved severity.
service_name_u
Service port name also known as the Web Services Description

Language (WSDL) port name
situation_displayitem
Display item of associated situation, if available.
situation_eventdata
Event data attributes in key-value pair format.

The event data can be truncated because the Event Integration
Facility (EIF) imposes a 2k size limit.
situation_name
Name of the associated situation.
situation_origin
Same value as sub_source attribute.
situation_status
Current status of the situation event:

Y indicates the event has been opened.
N indicates the event has been closed
P indicates the situation has been stopped
There are additional status values but the Event Handler does not
take an action on those values.
situation_time
Timestamp of the situation event.
source
Base event class attribute that contains "ITM"
std_dev_elapsed_time
The standard deviation of all elapsed round trip times, in

milliseconds, observed during this monitoring interval.
std_dev_msg_length
Standard deviation of all message lengths, in bytes, observed during

this monitoring interval.
sub_source
Base event class attribute that contains the origin managed system
name for the associated situation.
table_version_u
The version of this table definition.
unique_key_u
A unique hash of the service port namespace, service port name,

operation namespace, operation name, and service type in this
event.
740
Working example
In our example the Event Handler is installed on the same instance of
WebSphere Application Server than WSRR. Security is turned on in this
instance.
To configure the ITCAM for SOA Event Handler, we use the Web configuration
console using the following URL:
http://itso-wsrr:9080/ITCAMWeb/admin
We begin with the base configuration of the Event Handler, accessed using the
Configuration link in the navigation pane on the left side. Also, the
Configuration page should be displayed by default when first accessing the
Event Handler Web configuration URL.
Configuration
As summarized in Table 15-12, we start by setting the configuration attributes in
the Configuration page.
Table 15-12 Configuration attributes for Event Handler (working example)
Section
Attribute
Value
ITCAMListener
Port
1111
WSRRLocation
Endpoint
https://localhost:9443/WSRRCoreSDO/services/WS
RRCoreSDOPort
UID
itcam4soa
PWD
itso4you
Enabled
yes
TrustStore
C:\Program
Files\IBM\WebSphere\AppServer\profiles\default\ect
\DummyClientTrustFile.jks
TrustStore Password
WebAS
KeyStore
C:\Program
Files\IBM\WebSphere\AppServer\profiles\default\ect
\DummyClientKeyFile.jks
KeyStore Password
WebAS
Https
741
Section
Attribute
Value
EIFLogger
LogFileName
C:\itso\eif\eif01.log
LogLevel
ALL
TraceFileName
C:\itso\eif\eif01.trc
TraceLevel
ALL
Note: for our example we are using the default TrustStore and KeyStore
provided by WebSphere Application Server. In a real world deployment we
recommend that you generate your own cryptographic stores.
Also, we set both the Log and Trace levels to ALL in order to easily assess the
correct behavior of the Event Handler. For performance reasons this is
obviously not a recommended setting in any real case scenarios.
We click the Submit link to validate and save our changes. A confirmation screen
reading The configuration file has been saved successfully should be
displayed on the screen.
We can proceed with the definition of the event mappings.
Note: To obtain more information about the events received and processed by
the Event Handler, we also turned on the corresponding WSRR logs in
WebSphere Application Server:
com.ibm.wsrr.*=all
EventMapping
The definition of event mappings is performed using the EventMapping page. This
page is accessed via the EventMapping link on the navigation pane located on the
left side.
In our scenario we use the Fault_610 situation to trigger the propagation of
situation events from ITCAM for SOA to WSRR and ultimately update status
information. While this most probably would not be sufficient in a real life
deployment, our scenario provides us with an easy way to generate faults from
the deployed services by using incorrect item name (see Chapter 17, Integrating
WSRR with CICS on page 825 for a complete description of the scenario).
742
Fault_610 situation: Use the Fault_610 situation while monitoring messages

in the Web services flow to alert you when a Web services fault occurs during
the most recently completed monitoring interval. The situation is described by
the following formula:
*IF *VALUE Services_Inventory_610.Fault_Count *GT 0 *AND *VALUE
Services_Inventory_610.Interval_Status *EQ Complete
If a fault occurs for a service operation an increment count is set to >0, which
indicates at least one SOAP fault was received in response to the message.
This fault might occur for one of the following reasons:
There might be an application based fault. For example, the application
might not be running in the application server runtime environment.
Navigate to the Faults Summary workspace and examine the summary of
faults that have been reported. In the Fault Details table view, locate the
fault of interest and examine the contents of the Fault String column for
more information. Then take the necessary action to correct any problems
with your applications.
The message was rejected according to filtering criteria defined in the
monitoring agent.
If the applications do not appear to be the source of the problem, select the
Services Management Agent node in the Navigator Physical view and
examine the filter criteria defined in the Data Collector Filter Control
Configuration view. These filter criteria are defined to reject messages
based on a specified combination of service port name, service port
namespace, operation name, operation namespace, and remote IP
address. If these criteria are not defined correctly, undesired faults might
be received as a result.
Use the AddFltrCntrl_610 or the DelFltrCntrl_610 Take Action commands to
modify your filter criteria as needed.
743
Note: As discussed before, the fact that ITCAM for SOA uses situation events
to forward service status information to WSRR implies that you pay particular
attention when defining the event mappings in the Event Handler. Effectively,
events mappings and the associated situations that trigger their emission will
ultimately determine the frequency of that feedback loop from ITCAM for SOA
to WSRR.
Depending on your exact requirements, you may want to limit the number of
event mappings and situation events, change the settings of these situations,
use custom situations to control this feedback more precisely.
To define the adequate event mappings for our scenario, we start by deleting all
default event mappings using the Delete button.
Then we create a new event mapping using the Create button. Define the event
mapping as described in Table 15-13.
Table 15-13 Creating event mapping (working example)
Setting
Value
EventID
Fault_610
WSRRPropertyName
AvgResponseTime
Compound
No
Received Type
Property Value
Received Value
avg_elapsed_time
Cleared Type
Static String
Cleared Value
cleared
This event mapping supports the following scenario:

Whenever the situation Fault_610 evaluates to true, meaning that the number
of Web services faults exceeds a given threshold, an Open situation event is
sent to the Event Handler.
On the reception of this Open situation event, a property named
AvgResponseTime is created (if it does not exist) or updated (if it already exists)
in WSRR for the target WSDLPort object (the Service Port the operation at
the origin of the situation belongs to). The property is valued with the content
of the event property called avg_response_time, representing the average
response time of the target operation.
744
Whenever the situation Fault_610 is cleared, meaning that the number of

Web services faults observed during an observation interval does not exceed
a given threshold anymore, a Closed situation event is sent to the Event
Handler.
On the reception of this Closed situation event, the AvgResponseTime property
is valued with the content of the cleared static string.
Whenever the situation Fault_610 is no longer being monitored, a Removed
situation event is sent to the Event Handler.
On the reception of this Removed situation event, the AvgResponseTime
property is removed from WSRR.
Note: As the services used in our example provide only a single operation, we
do not use the Compound feature of the Event Handler which would append
the name of the operation to the name of the property in order to distinguish
between different operations of the same Service Port in WSRR.
Figure 15-49 illustrates the corresponding EventMapping configuration page.
Figure 15-49 Defining the event mapping (working example)
We click the Submit link to validate and save our changes. A confirmation screen
reading The configuration file has been saved successfully should be
displayed on the screen.
Once the configuration of the Event Handler has been saved we can proceed
with restarting the Event Handler.
State
Once updated, the configuration of the Event Handler does not take effect until
the Event Handler application has been restarted. The State page allows us to
restart the Event Handler and is accessible using the State link on the left-hand
side navigation pane.
The Event Handler should be running as illustrated by a green arrow beside the
Module State label.
We stop the Event Handler by clicking on the Submit button. The arrow
mentioned above should be replaced by a red cross.
745
We restart the Event Handler by clicking another time on the Submit button. The
red cross should be replaced by the green arrow.
Now that we are all set with ITCAM for SOA Event Handler, we can configure
Tivoli Monitoring infrastructure to send event to the Event Handler.
15.9.4 Configuring Tivoli Enterprise Monitoring Framework to send

events to the Event Handler
If IBM Tivoli Monitoring has not been configured to forward events to an event
server, you should configure IBM Tivoli Monitoring to forward ITCAM for SOA
events from the Hub Tivoli Enterprise Monitoring Server directly to the Event
Handler. See Configuring IBM Tivoli Monitoring for Event Handler on page 746.
On the other hand, If IBM Tivoli Monitoring has been configured to forward
events to Tivoli Enterprise Console, you should configure Tivoli Enterprise
Console to send ITCAM for SOA events to the Event Handler. See Configuring
IBM Tivoli Enterprise Console for Event Handler on page 752.
Configuring IBM Tivoli Monitoring for Event Handler

This section discusses how to configure IBM Tivoli Monitoring to send situation
events to the Event Handler and provides a working example.
Note: Currently you cannot forward events directly from a Tivoli Enterprise
Monitoring Server running in z/OS to the Event Handler. If you want to forward
events detected for z/OS monitoring to the Event Handler, there are a couple
of options to achieve that:
You can run the Tivoli Enterprise Monitoring Server in zLinux and from
there forward the situations to the Event Handler.
You can run the Tivoli Enterprise Monitoring Server in a distributed
system and then forward the events to the Event Handler.
To configure IBM Tivoli Monitoring to forward events, you need to start by
enabling event forwarding for the Tivoli Enterprise Monitoring Server.
For Windows monitoring servers only, do the following:
Open the Manage Tivoli Enterprise Monitoring Services application.
Right-click the Tivoli Enterprise Monitoring Server and click
Reconfigure.
746
On the configuration options window, select TEC Event Integration

Facility.
Click OK and OK.
Complete the following fields on the TEC Server: Location and Port
Number window and click OK:
TEC Server Location: Type the host name or IP address for the server
where the Event Handler is installed.
TEC Port Number: Type the port number that the Event Handler is
listening on. By default, the Event Handler uses port number 1111. The
port number must match the port number value specified when you
configured the Event Handler.
For UNIX and Linux monitoring servers, do the following on the server where
Tivoli Enterprise Monitoring Server is installed:
At the command line change to the /opt/IBM/ITM/bin directory (or the
directory where you installed IBM Tivoli Monitoring).
Run the following command:
./itmcmd config -S -t tems_name
where tems_name is the name of your monitoring server (for example,
HUB_itmdev17).
You will be prompted for the monitoring server configuration values. Enter
the same values that you provided when you installed the monitoring
server until you are asked about the TEC Event Integration Facility.
Answer YES for this question and press Enter. Complete the following
additional steps:
At the TEC Server prompt, type the hostname or IP address of the

server where the Event Handler is installed.
At the TEC Port prompt, type the port number that the Event Handler is
listening on. By default, the Event Handler uses port number 1111. The
port number must match the port number value specified when you
configured the Event Handler.
Once event forwarding has been enabled for Tivoli Enterprise Monitoring Server,
you need to specify where events are to be forwarded to. In this case, you need
to have Tivoli enterprise Monitoring Server forward events to the Event Handler
acting as an event server.
To do that, edit the Event Integration Facility (EIF) configuration file,
om_tec.config, which is located in the following directory on the server where
Tivoli Enterprise Monitoring Services is installed:
On a Windows system: C:\IBM\ITM\cms\TECLIB
747
On a UNIX or Linux system: /opt/IBM/ITM/tables/host name/TECLIB

where /opt/IBM/ITM and C:\IBM\ITM are the default locations where the Tivoli
Enterprise Monitoring Server is installed and host name is the value supplied
during the Tivoli Enterprise Monitoring Server configuration.
As summarized in Table 15-14the following parameters should be added or
modified in the om_tec.config file.
Table 15-14 Configuration parameters in om_tec.config file
Parameter name
Parameter Value
Parameter Description
FilterMode
IN
Enables event filtering
Filter:Class
ITM_Services_Inventory_610;
Event filter which forwards all

ITCAM for SOA events for the
Services_Inventory_610 table
to the Event Handler.
FilterCache:Class
ITM_Services_Inventory_610;
Filter that specifies which

events to cache when IBM
Tivoli Monitoring is unable to
forward an event to the Event
Handler.
Important:
If the EIF configuration file already contains values for any of the
parameters listed above, you should replace the current values with the
values described in the table.
The EIF configuration file also contains other parameters, including
ServerLocation and ServerPort parameters which are set to the values
you configured during the procedure described above. However, you must
use this procedure described to specify the hostname and port number for
the Event Handler rather than editing the EIF configuration file directly with
these values.
Note: For more information about configuring IBM Tivoli Monitoring to forward
events, see the IBM Tivoli Monitoring Version 6.1 Administrators Guide topics
on configuring Tivoli Event Console integration.
The next step is to ensure the kd4.map file is copied to the directory where the
EIF configuration file is located. The kd4.map file is available on the ITCAM for
SOA V6.1 installation media and also in the itcam4soa-tec-file.zip file that is
748
included in the sa04.zip and sa04.tgz files that are downloaded from the Event
Handler SupportPAC Web page.
You then need to restart the Tivoli Enterprise Monitoring Server for these
changes to take effect:
For Windows monitoring servers only, use the Manage Tivoli Enterprise
Monitoring Services application to start the monitoring server.
For UNIX and Linux monitoring servers, do the following:
At the command line change to the /opt/IBM/ITM/bin directory (or the
directory where you installed IBM Tivoli Monitoring).
Run the following commands:
./itmcmd server stop
./itmcmd server start
tems_name
tems_name
where tems_name is the name of your monitoring server (for example,

HUB_itmdev17).
Note: See the Commands Reference in the IBM Tivoli Monitoring Version 6.1
Installation and Setup Guide for more information about these commands.
Working example
In our working example, we start by reconfiguring TEMS using the Tivoli
Enterprise Monitoring Services application (Windows system). We right-click
the Tivoli Enterprise Monitoring Server and click Reconfigure as shown in
749
Figure 15-50 Reconfiguring TEMS
We select TEC Event Integration Facility and click OK twice as illustrated in

750
Figure 15-51 TEMS Configuration
We specify the TEC event server location using the IP address and the port of
the Event Handler as shown in Figure 15-52.
Figure 15-52 TEC event handler location and port
We click OK to validate our configuration changes.

We then modify the Event Integration Facility configuration file located at
C:\IBM\ITM\cms\TECLIB\om_tec.config as illustrated in Example 15-10.
Example 15-10 om_tec.config configuration file
ServerLocation=9.42.170.137
ServerPort=1111
751
RetryInterval=5
getport_total_timeout_usec=50500
NO_UTF8_CONVERSION=YES
ConnectionMode=co
BufferEvents=YES
BufEvtMaxSize=4096
BufEvtPath=./TECLIB/om_tec.cache
FilterMode=IN
Filter:Class=ITM_Services_Inventory_610;
FilterCache:Class=ITM_Services_Inventory_610;
Note: We just need to add/update the FilterMode, Filter:Class and
FilterCache:Class properties as the rest of the properties have been updated
in the previous steps using the graphical interface.
We copy the kfd4.map file in the C:\IBM\ITM\cms\TECLIB\ folder.
Using the Tivoli Enterprise Monitoring Services application we then restart
TEMS so that our changes take effect.
Configuring IBM Tivoli Enterprise Console for Event Handler

This section discusses how to configure IBM Tivoli Enterprise Console to re-send
situation events to the Event Handler and provides a working example.
This procedure configures Tivoli Enterprise Console to send ITCAM for SOA
events to the Event Handler.
1. Create a temporary directory, for example C:\temp\itcamsoarules on a
Windows system.
2. Download the .zip file provided with the Event Handler SupportPAC and
extract the following files from the .zip file to the temporary directory that you
created in step 1.
install_itcam_rb.sh
tec_itcam.rls
tec_itcam.conf
kd4.baroc
kd4.map
If Tivoli Enterprise Console is installed on a UNIX or Linux system, ensure
install_itcam_rb.sh is granted execute permission.
3. Edit the following parameters in the tec_itcam.conf file as shown in
Table 15-15 on page 753.
752
Table 15-15 Configuration parameters in tec_itcam.conf file

Parameter name
Parameter Value
Parameter Description
ServerLocation
Event Handler server

address
Hostname or IP address of the

server where the Event Handler is
installed
ServerPort
Event Handler port number
Port number that the Event Handler

is listening on. By default, the Event
Handler uses port number 1111.
The port number must match the
port number value specified when
you configured the Event Handler.
4. Edit the following variables in itcam_rb.sh.

Table 15-16 Configuration parameters in itcam_rb.sh file
Variable name
Value description
DIR
Set this variable to the temporary directory that contains the

install_rb.sh file.
For example:
DIR=C:\temp\itcamsoarules
RuleBase
Set this variable to the rule base that was specified when IBM
Tivoli Enterprise Console event synchronization was installed on
the event server.
RuleBasePath
Set this variable to the rule base path that was specified when IBM
Tivoli Enterprise Console event synchronization was installed on
the event server.
5. Open a command line window

6. Set up the Tivoli Management Framework environment by running the
following command:
On a Windows system, run the following command:
C:\WINDOWS\system32\drivers\etc\Tivoli\setup_env.cmd
On a Linux or UNIX system, run the following command from a shell
environment:
./etc/Tivoli/setup_env.sh
Change to the directory created in step 1
Enter the following commands:
bash
753
./install_itcam_rb.sh
7. Restart Tivoli Enterprise Console
Important: Also ensure the kd4.map file is copied to the following directory on
the system where Tivoli Enterprise Monitoring Server is installed:
On a Windows system: C:\IBM\ITM\cms\TECLIB
On a UNIX or Linux system: /opt/IBM/ITM/tables/host name/TECLIB
where /opt/IBM/ITM and C:\IBM\ITM are the default locations where the Tivoli
Enterprise Monitoring Server is installed and host name is the value supplied
during the Tivoli Enterprise Monitoring Server configuration.
The kd4.map file is available on the ITCAM for SOA V6.1 installation media and
also in the .zip file that you downloaded in step 2 above.
The steps above install a re-send rule that forwards all ITCAM for SOA events to
the Event Handler. All events, except events with the severity set to Harmless,
are sent to the Event Handler.
15.9.5 Triggering situations and forwarding service status

information
The next step of our integration scenario is the triggering of situations in ITCAM
for SOA and the observation of the updates in WSRR.
Observing the initial state of the registered services

Before triggering the situation, we can observe the initial definition of the two
services (ItemPriceService and ItemPriceDiscountedService) as they are
defined in WSRR.
The elements of interest in our scenario are the two Ports as these are the
Logical Objects that get updated with operational information flowing back from
ITCAM for SOA when situations arise.
Figure 15-53 on page 755 and Figure 15-54 on page 756 show the custom
properties initially defined respectively for the ItemPrice port and the
ItemPriceDiscounted port in WSRR.
754
Figure 15-53 Initial custom properties for ItemPrice service port
755
Figure 15-54 Initial custom properties for ItemPriceDiscounted service port
Configuring predefined situations

For the purpose of our scenario, we are using the predefined Fault_610 situation
which falls under the Services Management Agent Environment in the Situation
Editor provided by TEP.
This situation is preconfigured with a default threshold of 0 for the Fault Count, is
cleared whenever the sampling interval is complete, and has a default sampling
interval of 5 minutes. Figure 15-55 on page 757 shows the default configuration
of the Fault_610 situation in the Situation Editor.
756
Figure 15-55 Fault_610 predefined situation in TEP Situation Editor
You can modify the sampling interval to augment the frequency with which the
situation is evaluated, or change the threshold of the Fault Count to adjust its
sensitivity.
Triggering situations: Fault_610 open

To observe meaningful results in the average response time measurement, we
start by generating some traffic involving the two observed services as shown in
757
Service Provider
Service
Consumer
getPrice(ItemName)
Item price is returned
ItemPriceService
Observe operational data

(messages, response
time)
Service
Registry
& Repository
Monitoring &
Management
Display service information

(topology and operational
data)
Figure 15-56 Observing ItemPriceService and ItemPriceDisountedService
The Monitoring and Management infrastructure observes, collects and displays

the regular operational data for the observed services as illustrated in
Figure 15-56.
We then generate a Web services Fault by issuing a request for the price of an
unknown item.
The invoked service returns a simulated fault which is observed, collected and
displayed by the Monitoring and Management infrastructure as shown in
This Fault triggers the Fault_610 predefined situation at the end of the sampling
interval. The situation appears in the Navigator view as blue exclamation points
as shown in Figure 15-57 on page 759.
758
Figure 15-57 Situation Fault_610 displayed in TEP Navigator view
The situation is also displayed in the Situation Event Console view as shown in
Figure 15-58.
Figure 15-58 Situation Fault_610 displayed in TEP Situation Event Console view
Figure 15-59 on page 760 illustrates a customized Workspace displaying an

consolidated view of the Faults by Operation, along with the Fault Details and the
Situation Events Console.
759
Figure 15-59 Fault and Fault_610 situation in customized TEP workspace
Observing service status information in WSRR

The Fault_610 situation triggers the corresponding situation event which is sent
to the ITCAM for SOA Event Handler. As the result of the event being captured
and processed by the Event Handler, a custom property named AvgResponseTime
is created/updated on the Service Port Logical Object which has issued the Fault
(in that case ItemPrice service port), as shown in Figure 15-60 on page 761.
760
Figure 15-60 AvgResponseTime custom property added to ItemPrice service port in WSRR
Note: As explained in EventMap (EventMapping page) on page 735, ITCAM

for SOA Event Handler also creates a correlation custom property to keep
track of the WSRR property that needs to be changed or removed when the
situation clears.
The lastModified custom property is modified accordingly to reflect the
modification on the Service Port object.
Trace was turned on for both the Event Handler and the WebSphere Application
Server. The trace files produced by the ITCAM for SOA Event Handler
(Example 15-11) and WebSphere Application Server (Example 15-12 on
page 762) provide some details on the capture and the processing of the
situation event.
Example 15-11 eif01.trc (C:\ITSO\EIF)
2006.12.14 14:24:26.906
com.tivoli.tec.event_delivery.transport.socket.SocketTransport decodeEvent
Decoding event using the encoding: UTF8
761
Example 15-12 trace.log ([WAS_INSTALL\profiles\default\logs\server1)

[12/14/06 14:24:26:906 EST] 000000e7 adapter
1
**************************************************************************************
[12/14/06 14:24:26:906 EST] 000000e7
Fault_610
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
D4:18c837b2:9-server1
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
http://itso.ibm.com
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
b0c804fa56fa84ac827cd3adaddcb7b6
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
ITSO-WMBNode01
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:906 EST] 000000e7
ITSO-WMBNode01Cell
[12/14/06 14:24:26:906 EST] 000000e7
[12/14/06 14:24:26:922 EST] 000000e7
[12/14/06 14:24:26:922 EST] 000000e7
[12/14/06 14:24:26:922 EST] 000000e7
ITSO-ITCAM.itso.ral.ibm.com
[12/14/06 14:24:26:922 EST] 000000e7
762
adapter
ITCAMAdaptor receives a message with ID:
adapter
adapter
adapter
3
3
3
[severity] = HARMLESS
[interval_begin_time] = 1061214192500000
[situation_origin] =
adapter
adapter
3
3
[adapter_host] = ITCAM4SOA:ITSO-WMB:D4
[operation_namespace_u] =
adapter
adapter
adapter
adapter
adapter
adapter
adapter
adapter
adapter
adapter
adapter
adapter
3
3
3
3
3
3
3
3
3
3
3
3
[cms_port] = 3661
[sub_source] = D4:18c837b2:9-server1
[table_version_u] = 1
[interval_status] = 2
[std_dev_msg_length] = 103
[fault_count] = 1
[min_msg_length] = 240
[situation_name] = Fault_610
[application_servername_u] = server1
[master_reset_flag] =
[avg_elapsed_time] = 5000
[situation_displayitem] =
adapter
adapter
adapter
adapter
adapter
adapter
3
3
3
3
3
3
[application_serverenv] = 1
[max_elapsed_time] = 5000
[hostname] = ITSO-WMB
[elapsed_time_msg_count] = 4
[local_ipaddress_u] = 9.42.170.143
[unique_key_u] =
adapter
[application_server_nodename_u] =
adapter
adapter
adapter
3
3
3
[source] = ITM:Truncated
[interval_end_time] = 1061214193000000
[sub_origin] =
adapter
adapter
3
3
[std_dev_elapsed_time] = 0
[application_server_cellname_u] =
adapter
adapter
adapter
adapter
3
3
3
3
[msg_count] = 8
[origin_node] = D4:18c837b2:9-server1
[service_type] = 1
[cms_hostname] =
adapter
[operation_name_u] = getPrice
[12/14/06 14:24:26:922 EST] 000000e7 adapter

3 [integration_type] = U
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [situation_time] = 12/14/2006
14:30:56.000
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [appl_label] =
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [avg_msg_length] = 334
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [local_hostname_u] = 9.42.170.143
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [msg] = Fault_610[(Fault_Count>0 AND
Interval_Status=Complete ) ON D4:18c837b2:9-server1 ON b0c804fa56fa84ac827cd3adaddcb7b6
(Fault_Count=1 Interval_Status=Complete )]
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [situation_status] = Y
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [situation_eventdata] = ~
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [filler1] = 0
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [service_name_u] = ItemPrice
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [origin] = 9.42.170.143
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [port_number] = 2809
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [interval_length] = 5
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [min_elapsed_time] = 5000
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [date] = 12/14/2006
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [application_servercluster_u] =
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [port_namespace_u] = http://itso.ibm.com
[12/14/06 14:24:26:922 EST] 000000e7 adapter
3 [max_msg_length] = 484
[12/14/06 14:24:26:922 EST] 000000e7 integrationmo 1 Event is being processed ...
[12/14/06 14:24:26:922 EST] 000000e7 integrationmo 1 Event ID: Fault_610
[12/14/06 14:24:26:922 EST] 000000e7 integrationmo 1 Event Msg:
ITM_Services_Inventory_610;cms_hostname='ITSO-ITCAM.itso.ral.ibm.com';cms_port='3661';integrati
on_type='U';master_reset_flag='';appl_label='';situation_name='Fault_610';situation_origin='D4:
18c837b2:9-server1';situation_time='12/14/2006
14:30:56.000';situation_status='Y';hostname='ITSO-WMB';origin='9.42.170.143';adapter_host='ITCA
M4SOA:ITSO-WMB:D4';severity='HARMLESS';date='12/14/2006';source='ITM:Truncated';sub_source='D4:
18c837b2:9-server1';msg='Fault_610[(Fault_Count>0 AND Interval_Status=Complete ) ON
D4:18c837b2:9-server1 ON b0c804fa56fa84ac827cd3adaddcb7b6 (Fault_Count=1
Interval_Status=Complete
)]';situation_displayitem='b0c804fa56fa84ac827cd3adaddcb7b6';sub_origin='b0c804fa56fa84ac827cd3
adaddcb7b6';origin_node='D4:18c837b2:9-server1';application_servercluster_u='
';application_servername_u='server1';service_name_u='ItemPrice';operation_name_u='getPrice';int
erval_length='5';port_namespace_u='http://itso.ibm.com';operation_namespace_u='http://itso.ibm.
com';port_number='2809';unique_key_u='b0c804fa56fa84ac827cd3adaddcb7b6';service_type='1';applic
ation_serverenv='1';avg_msg_length='334';msg_count='8';elapsed_time_msg_count='4';avg_elapsed_t
ime='5000';fault_count='1';max_msg_length='484';max_elapsed_time='5000';min_msg_length='240';mi
n_elapsed_time='5000';std_dev_msg_length='103';std_dev_elapsed_time='0';interval_status='2';fil
ler1='0';interval_begin_time='1061214192500000';interval_end_time='1061214193000000';local_host
name_u='9.42.170.143';local_ipaddress_u='9.42.170.143';application_server_nodename_u='ITSO-WMBN
ode01';application_server_cellname_u='ITSO-WMBNode01Cell';table_version_u='1';situation_eventda
ta='~';END
[12/14/06
[12/14/06
[12/14/06
[12/14/06
14:24:26:922
14:24:26:922
14:24:26:922
14:24:26:922
EST]
EST]
EST]
EST]
000000e7
000000e7
000000e7
000000e7
integrationmo
integrationmo
integrationmo
integrationmo
1
1
1
1
Handle the Y-type event.

OperationName = getPrice
PortName = ItemPrice
PortNamespace = http://itso.ibm.com
763
[12/14/06 14:24:26:922 EST] 000000e7 integrationmo 1 Query statement:

/WSRR/WSDLService/ports[@name='ItemPrice' and @namespace='http://itso.ibm.com']
[12/14/06 14:24:27:547 EST] 000000e7 integrationmo 1 Handle the event as a WebService binding
event.
[12/14/06 14:24:27:547 EST] 000000e7 integrationmo 1 /WSRR/Module/exports[(exportBinding
treat as element(exportBinding,WebServiceExportBinding))[WSDLPort(.)[@name='ItemPrice' and
@namespace='http://itso.ibm.com']]]
[12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 try to update properties in
BaseObject[com.ibm.serviceregistry.sdo.impl.WSDLPortImpl@b052e3cd (classificationURIs:
[http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/DefaultLifecycle#State4], bsrURI:
WSRR--7797c588.ec8a0705.98a064c.7c8dbd7c-34a1-41fb.8a54.65078e655417, description: null,
lastModified: 1166114668375, name: ItemPrice, namespace: http://itso.ibm.com, owner:
administrator, version: )]
[12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 the value of property[AvgResponseTime]
will be updated
[12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 property has been updated
[12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 correlation
property[Fault_610---b0c804fa56fa84ac827cd3adaddcb7b6---D4--18c837b2--9-server1] has been added
[12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 There are 1 WSDLPort(s) need to be
updated
[12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 Persisting 1 WSRR instance(s) to WSRR
...
Figure 15-61 on page 765 summarizes the overall use case.
764
Service Provider
Service
Consumer
getPrice(UnknownItemName)
Fault is returned
ItemPriceService
Fault
Fault
The situation event is

Service
captured and
Registry
processed by the
& Repository
Event Handler. A
corresponding
AvgResponseTime=5000
AvgResponseTime
property is created
and valued for the
target Service Port
object in WSRR.

(Messages, Response time,
Faults)
Monitoring &
Management
Event
Situation Open
Properties
Fault_610
Situation Open
Fault_610 situation is
triggered after the end
of the sampling
interval and a
situation event is fired
Figure 15-61 Observing Faults on ItemPriceService and ItemPriceDiscountedService,

and forwarding events
Clearing situations: Fault_610 cleared

After some time (depending on the configuration of the sampling interval in the
Situation Editor), the Fault_610 situation is cleared as shown in Figure 15-62 on
page 766 displaying the customized workspace used previously.
765
Figure 15-62 Fault_610 situation cleared in TEP customized workspace
A corresponding situation event is fired and sent to the Event Handler which
captures and processes it. As a result, the AvgResponseTime custom property on
the ItemPrice service port object in WSRR is set to cleared as specified when
configuring the Event Handler EventMapping (see Working example on
page 749).
Figure 15-63 on page 767 displays the updated custom properties on the
ItemPrice service port object in WSRR.
766
Figure 15-63 AvgResponseTime custom property set to cleared in WSRR
Note: The correlation custom property created previously is removed when

the situation clears.
The lastModified custom property is modified accordingly to reflect the
modification on the Service Port object.
767
Service Provider
Service
Consumer
getPrice(ItemName)
ItemPriceService

Faults)

Service
captured and
Registry
processed by the
& Repository
Event Handler. The
corresponding
AvgResponseTime=cleared
AvgResponseTime
property is set to
cleared for the target
Service Port object in
WSRR.
Monitoring &
Management
Event
Situation Cleared
Properties
Fault_610
Situation Cleared
cleared after the end
of the sampling
interval and a
Figure 15-64 Cleared situation and forwarding of corresponding event
Removing situations: Fault_610 removed

Stopping the Fault_610 situation using the Situation Editor as shown in
Figure 15-65 triggers a situation event which is sent to the Event Handler.
Figure 15-65 Stopping Fault_610 situation in TEP Situation Editor
Figure 15-66 on page 769 shows the corresponding event in the Situation Event
Console view.
768
Figure 15-66 Stopped situation event in TEP Situation Event Console view
As a result, the corresponding custom property AvgResponseTime is deleted from

the ItemPrice service port object in WSRR. Figure 15-67 shows the resulting
custom property set of the ItemPrice service port object in WSRR.
Figure 15-67 AvgResponseTime custom property removed in WSRR
Once more, the lastModified custom property is modified accordingly to reflect

the modification on the Service Port object.
769
Service Provider
Service
Consumer
getPrice(ItemName)
St
o

captured and
processed by the
Event Handler. The
corresponding
AvgResponseTime
property is removed
from the target
Service Port object in
WSRR.
ItemPriceService
Fa
ul
t_
61
0
Si
tu
at

Faults)
io
n
Service
Registry
& Repository
Monitoring &
Management
Event
Situation Stopped
Properties
Fault_610
Situation Stopped
stopped and a
Figure 15-68 Stopped situation and forwarding of corresponding event
Note: The same behavior would have occurred if we had removed the
Fault_610 situation instead of just stopping it.
15.9.6 Using service status information in ESB infrastructure

Elaborating from the scenario described in 14.7.12, Scenario 3: Use the Lookup
primitive to get both endpoints on page 612 we could now use the operational
data observed from the running ItemPriceService and
ItemPriceDiscountedService services in the routing policy. This would be an
implementation of the logical architecture depicted in 15.7.3, Use of service
status information on page 690.
Instead of basing the routing policy only on the CustomerType static custom
property, we could enhance this policy with the use of the dynamic
AvgResponseTime custom property so that this policy would now take into account
the observed average response time of the services in the routing decision.
770
16
Chapter 16.
Integrating WSRR with WMB

This chapter describes how to integrate WSRR with WebSphere Message
Broker through the use of the additional SupportPac WMB V6 Client for
WebSphere Service Registry and Repository.
16.2, About WebSphere Message Broker on page 772
16.3, Installation on page 779
16.4, WebSphere Message Broker Client for WSRR on page 786
16.5, WSRR nodes on page 790
16.6, WMB Client Cache for WSRR on page 800
16.7, WMB Client support for SOA patterns on page 803
16.8, Setting up your environment for the patterns on page 809
771
16.1 Introduction
This chapter describes the use of WebSphere Service Registry and Repository
in an Enterprise Service Bus (ESB) environment, using WebSphere Message
Broker (WMB) as the ESB implementation. Use of WSRR allows ESB mediations
that interact with some set of endpoint services to be more tolerant of changes
within the environment. This is enabled by the ESB using WSRR as a dynamic
lookup mechanism, providing information about service endpoints (the service
metadata). So, when changes occur in the service endpoint environment, the
associated ESB mediations do not have to change.
The interaction between WMB and WSRR is provided by an IBM product
extension for WMB, the WebSphere Message Broker V6 Client for WebSphere
Service Registry and Repository. This is provided as a Category 1 SupportPac,
IA9L, available from the WMB SupportPac URL:
http://www.ibm.com/support/docview.wss?uid=swg24013639
The support encompasses a set of WMB nodes that can be used when building
WMB flows. These nodes encapsulate the API calls to WSRR and a caching
mechanism to improve the efficiency of the interaction.
Section 16.4, WebSphere Message Broker Client for WSRR on page 786
includes more information about the component parts of the client and how it
works.
16.2 About WebSphere Message Broker

Application integration is a big challenge for enterprises, and IBM provides a
number of software solutions and offerings to assist companies with integrating
their applications. WebSphere Message Broker is an important part of the IBM
offerings, and the way in which WebSphere Message Broker benefits application
integration is described in the following sections.
16.2.1 Application integration and WebSphere Message Broker

Application integration, at a high level, refers to solutions that are implemented to
integrate software applications within and between organizations. Historically,
application integration has been concerned with the integration of existing
software applications, such as between different departments and divisions
within companies, or new acquisitions. Within an organization, these applications
often vary considerably across departments, exist on different platforms, are
written in different programming languages, and use different data formats.
772
Integrating the applications is a more practical and cost effective solution than
the alternative of re-writing the existing applications.
WebSphere Message Broker is used in the implementation of an application
integration architecture because it provides a mechanism for connecting, routing,
and transforming business data from a variety of transports without any need to
change the underlying applications generating the data.
WebSphere Message Broker enhances the flow and distribution of information by
enabling the transformation and intelligent routing of messages without the need
to change either the applications that are generating the messages or the
applications that are consuming them. In WebSphere Message Broker,
connectivity is provided by applications that communicate by sending and
receiving messages.
WebSphere Message Broker also has the following key capabilities that make it a
valuable solution for business integration:
Distributes any type of information across and between multiple diverse
systems and applications, providing delivery of the correct information in the
correct format and at the correct time
Reduces the number of point-to-point interconnections and simplifies
application programming by removing integration logic from the applications
Routes information in real time based on topic and content to any endpoint
using a powerful publish/subscribe messaging engine
Validates and transforms messages in-flight between any combination of
different message formats, including Web Services, and other XML and
non-XML formats
Routes messages based on (evaluated) business rules to match information
content and business processes
Improves business agility by dynamically reconfiguring information distribution
patterns without reprogramming end-point applications
Access control to securely deliver personalized information to the right place
at the right time
16.2.2 WebSphere Message Broker 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.
Business rules can be applied to the data that is flowing through the message
broker in order to route, store, retrieve, and transform the information.
Chapter 16. Integrating WSRR with WMB
773
Editions of WebSphere Message Broker

There are three editions of the WebSphere Message Broker product as
described in the sections below.
WebSphere Event Broker

WebSphere Event Broker is used for the distribution and routing of messages
from disparate applications. It can distribute information and data, which is
generated by business events in real time, to people, applications, and devices
throughout an enterprise. WebSphere Event Broker has support for multiple
transport protocols and extends the flow of information in an organization beyond
point to point, utilizing flexible distribution mechanisms such as publish/subscribe
and multicast.
WebSphere Message Broker

WebSphere Message Broker contains all the functionality of WebSphere Event
Broker and extends it to include additional capabilities to enable storage,
transformation, and enrichment of data flowing through the broker. Detailed
capabilities of the product are described in the following sections and are based
upon the functional capabilities of the WebSphere Message Broker specifically.
Rules and Formatter Extension

WebSphere Message Broker with Rules and Formatter Extension includes the
Rules and Formatter Extension from New Era Of Networks which provides Rules
and Formatter nodes and associated runtime elements. These support the
functionality supplied with earlier releases of WebSphere MQ Integrator.
16.2.3 Capabilities of WebSphere Message Broker

The primary capabilities of WebSphere Message Broker are message routing,
message transformation, message enrichment, and publish/subscribe. Together
these capabilities make WebSphere Message Broker a powerful tool for business
integration.
Message routing
WebSphere Message Broker provides connectivity for both standards based and
non-standards based applications and services. The routing can be simple
point-to-point routing or it can be based on matching the content of the message
to business rules defined to the broker.
WebSphere Message Broker contains a choice of transports that enable secure
business to be conducted at any time and any place, providing powerful
integration using mobile, telemetry, and Internet technologies. WebSphere
774
Message Broker is built upon WebSphere MQ and therefore supports the same
transports. However, it also extends the capabilities of WebSphere MQ by adding
support for other protocols, including real-time Internet, intranet, and multicast
endpoints.
WebSphere Message Broker supports the following transports:
WebSphere MQ Enterprise Transport

WebSphere MQ Web Services Transport
WebSphere MQ Real-time Transport
WebSphere MQ Multicast Transport
WebSphere MQ Mobile Transport
WebSphere MQ Telemetry Transport
WebSphere Broker JMS Transport
In addition to the supplied transports, the facility exists for users to write their own
input nodes to accept messages from other transports and formats as defined by
the user.
Message transformation and enrichment

Transformation and enrichment of in-flight messages is an important capability of
WebSphere Message Broker, and allows for business integration without the
need for any additional logic in the applications themselves.
Messages can be transformed between applications to use different formats, for
example, transforming from a custom format in a existing system to XML
messages that can be used with a Web service. This provides a powerful
mechanism to unify organizations because business information can now be
distributed to applications that handle completely different message formats
without a need to reprogram or add to the applications themselves.
Messages can also be transformed and enriched by integration with multiple
sources of data such as databases, applications, and files. This allows for any
type of data manipulation including logging, updating, and merging. For the
messages that flow through the broker, business information can be stored in
databases or can be extracted from databases and files and added to the
message for processing in the target applications.
Complex manipulation of message data can be performed using the facilities
provided in the Message Brokers Toolkit, such as ESQL and Java.
In WebSphere Message Broker, message transformation and enrichment is
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,
775
a message definition of their structure must exist. The Message Brokers Toolkit
contains facilities for defining messages to the message broker. These facilities
are discussed in more detail below.
Publish/subscribe
The simplest way of routing messages is to use point-to-point messaging to send
messages directly from one application to another. Publish/subscribe provides an
alternative style of messaging in which messages are sent to all applications that
have subscribed to a particular topic.
The broker handles the distribution of messages between publishing applications
and subscribing applications. As well as applications publishing on or subscribing
to many topics, more sophisticated filtering mechanisms can be applied.
An improved flow of information around the business is achieved through the use
of publish/subscribe and the related technology of multicast. These flexible
distribution mechanisms move away from hard-coded point-to-point links.
16.2.4 Components of WebSphere Message Broker

WebSphere Message Broker is comprised of two principle parts, a development
environment for the creation of message flows, message sets, and other
message flow application resources; and a runtime environment, which contains
the components for running those message flow applications that are created in
the development environment.
Development environment
The development environment is where the message flow applications that
provide the logic to the broker are developed. The broker uses the logic in the
message flow applications to process messages from business applications at
run time. In the Message Brokers Toolkit, you can develop both message flows
and message sets for message flow applications.
Message flows
Message flows are programs that provide the logic that the broker uses to
process messages from business applications. Message flows are created by
connecting nodes together, with each node providing some basic logic. A
selection of built-in nodes is provided with WebSphere Message Broker for
performing particular tasks. These tasks can be combined to perform complex
manipulations and transformations of messages.
A choice of methods is available for defining the logic in the message flows to
transform data. Depending on the different types of data or the skills of the
message flow application developer, the following options are available:
776
Extended Structured Query Language (ESQL)

Java
eXtensible Style sheet Language for Transformations (XSLT)
Drag-and-drop mappings
The nodes in the message flows define the source and the target transports of
the message, any transformations and manipulations based on the business
data, and any interactions with other systems such as databases and files.
Message sets
A message set is a definition of the structure of the messages that are processed
by the message flows in the broker. As mentioned previously, in order for a
message flow to be able to manipulate or transform a message, the broker must
know the structure of the message. The definition of a message can be used to
verify message structure, and to assist with the construction of message flows
and mappings in the Message Brokers Toolkit.
Message sets are compiled for deployment to a broker as a message dictionary,
which provides a reference for the message flows to verify the structure of
messages as they flow through the broker.
Broker Application Development perspective

The Broker Application Development perspective is the part of the Message
Brokers Toolkit that is used to design and develop message flows and message
sets. It contains editors that create message flows, create transformation code
such as ESQL and define messages.
Runtime environment
The runtime environment is the set of components that are required to deploy
and run message flow applications in the broker.
Broker
The broker is a set of application processes that host and run message flows.
When a message arrives at the broker from a business application, the broker
processes the message before passing it on to one or more other business
applications. The broker routes, transforms, and manipulates messages
according to the logic that is defined in their message flow applications.
A broker uses WebSphere MQ as the transport mechanism both to communicate
with the Configuration Manager, from which it receives configuration information,
and to communicate with any other brokers to which it is associated.
Each broker has a database in which it stores the information that it needs to
process messages at run time.
777
Execution groups
Execution groups enable message flows within the broker to be grouped
together. Each broker contains a default execution group. Additional execution
groups can be created as long as they are given unique names within the broker.
Each execution group is a separate operating system process and, therefore, the
contents of an execution group remain separate from the contents of other
execution groups within the same broker. This can be useful for isolating pieces
of information for security because the message flows execute in separate
address spaces or as unique processes.
Message flow applications are deployed to a specific execution group. To
enhance performance, the same message flows and message sets can be
running in different execution groups.
Configuration Manager
The Configuration Manager is the interface between the Message Brokers Toolkit
and the brokers in the broker domain. The Configuration Manager stores
configuration details for the broker domain in an internal repository, providing a
central store for resources in the broker domain.
The Configuration Manager is responsible for deploying message flow
applications to the brokers. The Configuration Manager also reports back on the
progress of the deployment and on the status of the broker. When the Message
Brokers Toolkit connects to the Configuration Manager, the status of the brokers
in the domain is derived from the configuration information stored in the
Configuration Managers internal repository.
Broker domain
Brokers are grouped together in broker domains. The brokers in a single broker
domain share a common configuration that is defined in the Configuration
Manager. A broker domain contains one or more brokers and a single
Configuration Manager. It can also contain a User Name Server. The
components in a broker domain can exist on multiple machines and operating
systems, and are connected together with WebSphere MQ channels.
A broker belongs to only one broker domain.
User Name Server

A User Name Server is an optional component that is required only when
publish/subscribe message flow applications are running, and where extra
security is required for applications to be able to publish or subscribe to topics.
778
The User Name Server provides authentication for topic-level security for users
and groups that are performing publish/subscribe operations.
Broker Administration perspective

The Broker Administration perspective is the part of the Message Brokers Toolkit
that is used for the administration of any broker domains that are defined to the
Message Brokers Toolkit. This perspective is also used for the deployment of
message flows and message sets to brokers in the defined broker domains.
The Broker Administration perspective also contains tools for creating message
broker archive (bar) files. Bar files are used to deploy message flow application
resources such as message flows and message sets.
The Broker Administration perspective also contains tools to help test message
flows. These tools include Enqueue and Dequeue for putting and getting
messages from WebSphere MQ queues.
16.3 Installation
For the purposes of this book we will assume that you already have WebSphere
Message Broker V6 installed and working. If not, refer to the WMB Information
Center for documentation about how to install WebSphere Message Broker:
http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/index.jsp
16.3.1 Download the SupportPac

To acquire the SupportPac you must contact your IBM representative or e-mail
spacs@uk.ibm.com. You will then be sent a link from which you can download
the SupportPac zip file. This information is also available on the SupportPac Web
site:
16.3.2 Prerequisites
The SupportPac provides WSRR nodes and functionality to be used with
WebSphere Message Broker V6.0.0.2 (and later) product. WebSphere Service
Registry and Repository is also required. For normal use there are no other
prerequisites.
In order for the cache synchronization to function using a SIBus (the default for
both WebSphere and WSRR), the JMS Client will need to be available. It can be
obtained from:
779
If global security is enabled for the WebSphere Application Server then a WMB
fix to enable secure access to the SIBus is also needed. This fix is included in
WMB FixPack 3 (V6.0.0.3). WMB FixPack 3 can be downloaded from:
http://www.ibm.com/support/docview.wss?rs=849&uid=swg24013952
Note: The WMB V6 Client for WebSphere Service Registry and Repository
uses JAR files from both WSRR and from either WebSphere Application
Server or the WebSphere Application Client. These JAR files must be
available for the WMB Client to operate, they are not provided with the
SupportPac itself.
16.3.3 Install the SupportPac

The installation of the WMB V6 Client for WebSphere Service Registry and
Repository is quite complicated and involves several manual steps. Take care
when following the steps here.
Install WMB
For the purposes of this book we will assume that you have WMB installed. If you
do not, then consult the WMB documentation about how to do so:
Install WMB FP3

If you have global security turned on in WebSphere then you will require WMB
FixPack 3 (V6.0.0.3). Download it from this Web site and then follow the
instructions there about how to install it:
Install JMS Client

Install the JMS client on the WMB Broker runtime system. This is only needed if
you want to use the cache synchronization functionality provided in the WSRR
SupportPac.
1. Download from:
2. Copy the downloaded file to the directory you want to install the JMS Client to,
for example, C:\Program Files\IBM\MQSI\JMSClient
3. Install the client by executing the following command from the directory to
which you copied the JMSClient jar file.
780
java -jar sibc_install-<build>.jar -text jms_jndi_ibm

Where <build> is the specific version of your JMSClient jar file, at the time of
writing the latest version was build o0647.15
Substitute jms_jndi_sun for jms_jndi_ibm if installing on Solaris.
Install WMB Client for WSRR

Download the SupportPac from:
Unzip the zip file to where you want the WMB Client installed, for example,
C:\Program Files\IBM\MQSI\WMB-WSRRClient
Gather files on the runtime system

There are several files that you will need later on in the installation process. It is
simpler to gather them all together now. Copy the following files to a single folder
on the target WMB toolkit system, for example, C:\Program
Files\IBM\MQSI\WMB-WSRRClient\clientfiles
From the SupportPac:
<WMBClient_Install>\ServerRuntime\MBClientAccessToWSRR Folder
<WMBClient_Install>\ServerRuntime\MBRuntimeExtension\ServiceRegsitry
MessageBrokerNodes.par
<WMBClient_Install>\ServerRuntime\MBClientCacheSynchronization\WSRRU
pdateCache_1.0.1.bar
<WMBClient_Install>\SupportPac-Shared-classes\WMBc4WSRR_1.0.1.jar
From the WSRR WebSphere Application Server Install:
<WAS_INSTALL>\classes\sdo-int.jar
<WAS_INSTALL>\runtimes\ibm-jaxrpc-client.jar
From the WSRR Install:
<WSRR_INSTALL>\ServiceRegistryClient.jar
Setup and Configure Broker Classpath

Edit the brokers profile script (typically mqsiprofile.cmd or mqsiprofile.sh in the
<WMB_INSTALL>\bin directory adding the following lines to the CLASSPATH
section of the script:
rem Adding to support WSRR
set CLASSPATH=%CLASSPATH%;<WMBCLIENTFILES>\ibm-jaxrpc-client.jar
781
set CLASSPATH=%CLASSPATH%;<JMSCLIENT_INSTALL>\lib\sibc.jms.jar;<sibc
directory>\lib\sibc.jndi.jar
Where <WMBCLIENTFILES> is the directory you gathered all the files to in the
previous step.
Where <JMSCLIENT_INSTALL> is the directory you installed the JMS client to in a
previous step.
Ensure you restart the command environment to pick up these changes.
Configuring and running wsrrsetparams

You now need to configure and run wsrrsetparms.bat or wsrrsetparms.sh
depending on the type of system you are using.
1. Create a folder
<WMBCLIENTFILES>\MBClientAccessToWSRR\config\shared-classes
Where <WMBCLIENTFILES> is the directory you gathered all the files to in a
previous step.
2. Move the provided wsrr.properties file from the config directory into the newly
created shared-classes directory and ensure no other wsrr.properties files
exist on the file system (saving confusion), for example,
move <WMBCLIENTFILES>\MBClientAccessToWSRR\config\wsrr.properties
<WMBCLIENTFILES>\MBClientAccessToWSRR\config\shared-classes
previous step.
3. Copy the provided key file to an available location on the runtime
environment. A suggestion would be the same folder as the
ibm-jaxrpc-client.jar above, for example:
move
<WMBCLIENTFILES>\MBClientAccessToWSRR\config\WSRRProxyConfig.key
<WMBCLIENTFILES>
Where, <WMBCLIENTFILES> is the directory you gathered all the files to in a
previous step.
4. Edit wsrr.properties file in the shared-classes directory of
MBClientAccessToWSRR:
For a standard configuration remove the predefinedQueries value
Change the keyStore and trustStore locations if necessary, you may need
to copy these files from your WebSphere server to the local machine if
WSRR is not installed on the same machine as WMB.
782
Update the endpointaddress to reflect the correct hostname and port for
your WSRR installation. Note you need to specify whether to use HTTP or
HTTPS too.
Change all references to the default alias to a value you prefer
An example wsrr.properties file is shown in Example 16-1, note that the
password values will all be set in step 7 by running wsrrsetparams.
Example 16-1 Example wsrr.properties file
DEFAULT_ALIAS = ITSO
ITSO.endpointaddress =
https://itso-wsrr:9443/WSRRCoreSDO/services/WSRRCoreSDOPort
ITSO.keyStore =
C:/Progra~1/ibm/MQSI/WMB-WSRRClient/clientfiles/DummyClientKeyFile.jks
ITSO.keyStorePassword = (DES)+BjuKS5EWVY=
ITSO.keyfile =
file:/C:/progra~1/IBM/MQSI/WMB-WSRRClient/clientfiles/WSRRProxyConfig.key
ITSO.needCache = true
ITSO.password = (DES)KdB6OwaJfJXIWyDoLB9lCA==
ITSO.predefinedQueries =
ITSO.refreshQueriesAfterNotification = true
ITSO.timeout = 10000000
ITSO.trustStore =
C:/Progra~1/ibm/MQSI/WMB-WSRRClient/clientfiles/DummyClientTrustFile.jks
ITSO.trustStorePassword = (DES)+BjuKS5EWVY=
ITSO.userid = (DES)dqndmirQTCzIWyDoLB9lCA==
5. Confirm that the URL provided in the properties file correctly addresses
WSRR:
Navigate using a Web browser to the value used in ITSO.endpointaddress
this should produce a Web page indicating a test Web service has been
called.
6. Edit the <WMBCLIENTFILES>\MBClientAccessToWSRR\wsrrsetparms.bat (or.sh)
file:
Provide a path to a java runtime, it is likely the one provided in the script
doesn't exist.
set JAVA_HOME=C:\IBM\WebSphere\AppServer\java
Provide the full path to the key file mentioned above
set
WSRR_PROXY_KEY=file:/C:/Progra~1/IBM/MQSI/WMB-WSRRClient/clientf
iles/WSRRProxyConfig.key
783
Configure the correct alias to use as defined in your current

wsrr.properties file
set WSRR_PROXY_CONFIG_ALIAS=ITSO
7. Execute wsrrsetparms
Provide values for the user name and passwords of all entries
The keystore and truststore default password is WebAS
wsrrsetparams.bat -u wasadmin -p passw0rd -k WebAS -t WebAS
Replace the values above with the correct values for your environment.
Configure the WMB runtime shared-classes

Copy the following files to the <WMB workpath>\shared-classes directory. To
determine the directory query the MQSI_WORKPATH environment variable. By
default this is C:\Documents and Settings\All Users\Application
Data\IBM\MQSI\shared-classes.
Note: This may be a hidden directory and so you may need to alter some
Windows folder options to see the folder.
sdo-int.jar
WMBc4WSRR_1.0.1.jar
wsrr.properties (the file created in step 4 on page 782 above)
Configure the WMB toolkit

1. Unzip
<WMBCLIENTFILES>\ClientTooling\MBToolkitPlugin\ServiceRegistryMessag
eBrokerNodesPlugin_1.0.1.zip
previous step.
2. Copy the com.ibm.sr.mb.nodes_1.0.1 folder from the expanded zip file
plugins directory to the toolkit machine placing in the directory
<WMBToolkitInstall>\6.0\eclipse\plugins
Where, <MBToolkitInstall> is the WMB Toolkit install directory.
3. Copy the following files from the <WMBCLIENTFILES> directory to the WMB
toolkit machine into the
<MBToolkitInstall>\6.0\eclipse\plugins\com.ibm.sr.mb.nodes_1.0.1\sha
red-classes directory
784
sdo-int.jar
wsrr.properties (the file created in step 4 on page 782 above)
ibm-jaxrpc-client.jar
4. Start the WMB Toolkit with the -clean option to refresh the toolkit with the new
plugin
<MBToolkitInstall>\6.0\wmbt.exe -clean
Where <MBToolkitInstall> is the WMB Toolkit install directory.
Configure WSRR bus security

For WMB FP2 or earlier you must turn off security for the WSRR bus as defined
in the SupportPac documentation.
For WMB FP3 or later execute the following commands:
mqsistop <brokername>
mqsisetdbparms <brokername> -n jms::jms/SRConnectionFactory -u <uid>
-p <pwd>
mqsistart <brokername>
Where uid and pwd are the userid and password for your WSRR installation.
The broker must be stopped for the mqsisetdbparms command to run.
Configure the broker

On the WMB runtime machine configure the broker to load the plugin jar file.
Ensure that you have reloaded the profile after the changes were made in Setup
and Configure Broker Classpath on page 781 above.
1. Copy <WMBCLIENTFILES>\ServiceRegsitryMessageBrokerNodes_1.0.1.par to
a directory you prefer on the WMB runtime system if necessary.
2. Configure the broker to reference the above directory:
mqsichangebroker <brokerName> -l <directoryOfParFile>
Note: If you do not already have a broker, then create one before running
mqsichangebroker. The mqsicreatebroker can be used for this purpose;
consult the WMB documentation for more information.
3. Start the broker and check for any errors
Possible places to see errors would be in the console output or in the
Windows Event Viewer:
785
Control Panel Administrative Tools Event Viewer Application/System

For more information about troubleshooting WMB, check the WMB
Information Center:
http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/topic/com.ib
m.etools.mft.doc/au03830_.htm
Optional: Deploy the UpdateCache bar file

This step is only necessary if you want to use the cache synchronization
functionality by the SupportPac.
1. Copy the bar file to the Toolkit machine
2. Create a new Servers project in the WMB Toolkit.
3. Import the <WMBCLIENTFILES>\WSRRUpdateCache_1.0.1.bar file
4. Click the configure tab for the BAR file
5. Change the JNDI settings to point to your WSRR installation, for example:
iiop://itso-wsrr:2809/
6. Deploy the BAR file, again checking for errors
Installation of the WMB Client for WSRR is now complete. The following section
will explain what the client provides before we then go on to set up an example
scenario which will demonstrate the use of it.
16.4 WebSphere Message Broker Client for WSRR

The WMB V6 Client for WebSphere Service Registry and Repository provides
the runtime access to WSRR from within WebSphere Message Broker.
786
The contents of the client are shown in Figure 16-1.

Execution Group
Flow
WSRR Node
Execution Group
WSRR
Proxy
(cache)
Flow
Flow
WSRR Node
WSRR
Proxy
(cache)
WSRR
Nodes
Flow
WMB Client for WSRR
Figure 16-1 WMB Client for WSRR contents
The two primary parts of the client are the WMB nodes and a WMB cache for
WSRR entities.
16.4.1 WSRR nodes

The clients nodes provide access to a services metadata contained in WSRR.
These nodes operate similar to other WMB built-in nodes. At development time
the WSRR entity is specified (or values for a query are specified). The nodes
access WSRR, as requested by the developer of the flow, at runtime in order to
populate the contents of the domain (with the service metadata). For more
details, refer to 16.5, WSRR nodes on page 790.
16.4.2 WMB Client cache for WSRR

The clients proxy provides a WMB localized cache for service metadata. The
cache helps improve the performance of the flow (by accessing a local cached
copy of service metadata instead of retrieving it on each invocation). For more
details refer to 16.6, WMB Client Cache for WSRR on page 800.
787
16.4.3 Client runtime access to WSRR

At runtime a WMB flow uses the WMB client for WSRR to access an entitys
metadata as seen in Figure 16-2.

Execution Group
Flow
WSRR Node
Execution Group
WSRR
Proxy
(cache)
Flow
Flow
WSRR Node
WSRR
Proxy
(cache)
WSRR
Nodes
Flow
Application
Application
Application
WSRR
UI
WSRR
3
Database
Figure 16-2 WMB Client Runtime access sequence
The runtime sequence of execution starts with the execution of the mediation:
1. When the mediation flow is executed, and the client node is invoked, the node
uses the information specified at development time to access the entitys
metadata. It does this by accessing a WMB client for WSRR proxy, which
looks for the entity in the cache before accessing WSRR.
2. When an entity is requested by the WSRR proxy, the proxy checks to see if
that service is available from the cache. If the service (metadata) is available
from the cache the proxy returns that information to the requesting node. If
the service is not available from the cache the proxy retrieves the service
directly from the WSRR and stores it in its cache for future use. See 16.6,
WMB Client Cache for WSRR on page 800 for more information about
cache strategy options.
3. When a service is requested from the WSRR, it communicates with the
datastore to obtain the service metadata. It returns this metadata to the
requestor.
4. If changes are made to a service, via the WSRR UI (Web-based or command
line) the WSRR fires a notification event with details of the change.
5. When a service notification event is received by the WMB client for WSRR
proxy its cache is updated to contain the new metadata. For details about how
788
this notification event is obtained and processed by the proxy, refer to the
cache details, 16.6, WMB Client Cache for WSRR on page 800.
16.4.4 WMB Client and WSRR deployment

Figure 16-3 shows the deployment of the WMB Client for WSRR components.

Execution Group
Flow
WSRR Node
Flow
Execution Group
WSRR
Proxy
(cache)
Flow
WSRR Node
WSRR
Proxy
(cache)
WSRR
Nodes
Flow
Flows use WMB

client for WSRR
nodes
Cache shared
within an Execution
Group
Deployed for a
broker instance
Figure 16-3 WMB Client for WSRR deployment
The WMB flows are deployed in WebSphere Message Broker, within a specified
Execution Group. These flows represent the exposed service and control the
actual service that is invoked, any message transformation that needs to occur,
as well as other mediation specific details.
Cache Scope: The WMB client proxy handles the request for service metadata,
retrieving that metadata from either its cache or from WSRR. The default
deployment for the cache is within a WMB execution group. This means that
each execution group contains its own separate cache. Refer to 16.6, WMB
Client Cache for WSRR on page 800 for details on the deployment options for
the cache.
Node Scope: The WMB client nodes are deployed across an entire WMB
installation. This means that the nodes are available across all brokers and
execution groups.
789
16.5 WSRR nodes

The following sections discuss the WebSphere Message Broker (WMB) nodes
for accessing WSRR. They are used the same way as other WMB built-in nodes.
The nodes utilize metadata stored in WSRR and node properties to determine
the action to take, within a flow, at runtime. The node properties combined with
the Service (entity) metadata can be used at runtime to determine how the flow
operates.
There are two types of nodes; nodes supporting the router and transcoder
patterns and nodes for generic access to WSRR content.
Note: All nodes throw a MbRecoverableException when a syntactical or
semantic error occurs, unless otherwise stated.
16.5.1 Introducing the nodes

There are five nodes that may be used to access service metadata that resides
in WSRR. These nodes are designed to be included in message processing
flows that mediate between service consumers and service providers in an SOA
installation. The first three nodes, SR****VirtualService, are available for a
specific pattern of usage (see 16.7, WMB Client support for SOA patterns on
page 803); while the other two, SRRetrieve****, are for generic WSRR access.
The names of the five nodes provided are shown in Table 16-1.
Table 16-1 WSRR WMB nodes
790
Node Name
Node Purpose
SRGetVirtualService
Get Virtual service metadata from WSRR. This virtual

service represents the router pattern. (This requires
specific configuration of WSRR see 16.8, Setting up your
environment for the patterns on page 809 for details.)
SRProcessVirtualService
Process message content for services obtained with the

SRGetVirtualService node. (This requires specific
configuration of WSRR, see 16.8, Setting up your
environment for the patterns on page 809 for details.)
SRDispatchVirtualService
Dispatches an IT service that will execute the request, for

services obtained with the SRGetVirtualService node.
This requires specific configuration of WSRR see 16.8,
Setting up your environment for the patterns on
page 809 for details.)
Node Name
Node Purpose
SRRetrieveITService
Get a WSRR service (currently only a Web Service

defined via a WSDL is supported).
SRRetrieveEntity
Retrieve metadata about any entity defined in WSRR.
16.5.2 SRGetVirtualService node

This node is used within a message flow to obtain metadata associated with the
virtual service that corresponds to the WMB flow. This virtual service represents
the router pattern.
Node properties
The properties on the node are: namespace, name, version, relationship type
name, and relationship type value. These are shown in Table 16-2.
Table 16-2 SRGetVirtualService node properties
Property Name
Mandatory
Configurable
Name
Yes
Yes
Namespace
Yes
Yes
Version
Yes
Yes
Relationship type
Yes
Relationship type XPath
Yes
Default
Values
Property
Values
verb
The Namespace, Name, and Version are specified on the SRGetVirtualService

node properties to uniquely identify the virtual service that represents the WMB
flow implementing the router pattern.
The Relationship Type and XPath can also be specified on the properties page.
The Relationship Type defaults to verb. The XPath location of the relationship
type corresponds to the incoming message (for example, the location of the
relationship type within the incoming message). The Relationship Type XPath
value can also be specified on the relationship and would override the value set
here.
Node terminals
Table 16-3 on page 792 shows the terminals for this node.
791
Table 16-3 SRGetVirtualService node terminals

Terminal Name
Description
In
Node input terminal
Out
Node output terminal
Failure
Node failure terminal (where exceptions are thrown)
Runtime destination routing

Since the virtual service obtained with this node represents the router pattern,
this node automatically sets the destination routing based on the relationship
type, relationship value, and endpoint alias (also known as the network location).
This means that flows can be built to handle all known routes and the node will
set the context so that the correct route will be taken.
The SRGetVirtualService node will set a default destination label to the value
RouteToLabel specified on the relationship between Services, if blank or not set
the destination label will not be set.
792
Use of this destination is primarily related to use by the WMB built-in node
RouteToLabel, as seen in Figure 16-4, but can also be used in a non-WMB
environment.
The destination can be overridden using normal WMB toolkit functionality.
Figure 16-4 SRGetVirtualService node route mapping
16.5.3 SRProcessVirtualService node

This node is used to create the proper format for the target service invocation
and override the target services operation (if necessary). This node is normally
invoked after message translation (if needed).
Node properties
This node has no properties.
Node terminals
Table 16-4 shows the terminals for this node.
Table 16-4 SRProcessVirtualService node terminals
Terminal Name
Description
In
Node input terminal
793
Terminal Name
Description
Out
Failure
Runtime destination routing

This node will set the destination label to the value Label{-<Protocol>}. The
protocol must be one of the supported types of protocols; such as MQ, URL, or
JMS. If the protocol is not specified, the routing label will be Label.
At the completion of this node the endpoint will be established such that the
backend service can be invoked (usually through the use of a HTTPRequest or
MQOutput node).
Use of this destination is primarily related to use by the WMB built-in node
RouteToLabel. The destination can be overridden using normal Message Broker
toolkit functionality.
16.5.4 SRDispatchVirtualService node

This node is used to establish the endpoint of the target service. It will normally
send its output to a HTTPResponse or MQOutput built-in node.
Note: This node is dependent on the domain context set by the
SRGetVirtualService node.
Node properties
This node has no properties.
Node terminals
Table 16-5 SRDispatchVirtualService node terminals
794
Terminal Name
Description
In
Node input terminal
Out
Failure
16.5.5 SRRetrieveITService node

This node is a generic node in that it retrieves the service endpoint information
related to a WSRR defined service (for example, WSDL). It does not perform
additional filtering or selection; other than that specified by the property
matching. If a single service (Web Service only) is requested (MatchPolicy is
One), it will set the endpoints in the context so that this service information is
correctly placed in the domain context in order that existing WMB built-in nodes
will correctly invoke the service.
Note: This node is independent of any other domain context.
Support is currently limited to querying for Web Service endpoints.
Node properties
The properties on the node are: name tuple, user properties, classification and
MatchPolicy. These are shown in Table 16-6.
Table 16-6 SRGetVirtualService node properties
Property
Name
Mandatory
Configurable
Default
Values
Name tuple
(portType
name,
namespace
and version)
No
Yes
Name tuple that uniquely

defines a WSRR defined
WSDL service portType.
User
properties
No
No
Allows a query to specify

user-defined properties
for the port.
Classification
No
Yes
This uses the OWL

classification system.
Each classifier is a class
in OWL, and has a URI.
MatchPolicy
Yes
Yes
One
Property Values
Specify One to return

only 1 match; Specify All
to return all matches.
If all three values are specified for the Name tuple then all ports that implement
the single service portType will be returned (if they exist). At least one of the
three is required. If any of the three are left blank, then all ports that implement
multiple service portTypes will be returned (if a match is found).
795
Note: While the Name tuple, user properties and Classification fields are not
mandatory, a warning will be issued if none of the three properties are set.
Figure 16-5 shows a sample properties dialog for the SRRetrieveITService node.
Figure 16-5 SRRetrieveITService node properties
Node terminals
Table 16-7 SRRetrieveITService node terminals
796
Terminal Name
Description
In
Node input terminal
Out
Terminal Name
Description
Failure
Nomatch
If no entity is found, based on the specified values, the message

is propagated to this terminal.
Operational sequence
The following is the sequence that this node follows:
1. Receives a message
2. Retrieves the IT service endpoint information from WSRR using the specified
query string
3. If one or more matches can be found:
a. If MatchPolicy is One and a single endpoint is matched, the proper
endpoints will be set in the domain so that existing WMB built-in nodes can
be used to invoke the service.
b. If MatchPolicy is All, adds all matching endpoints information to the
message instance, leaving all other message content unchanged.
c. Propagates this to the out terminal
4. If a match cannot be found:
a. Propagates the input message to the nomatch terminal
5. On failure
a. Adds FailInfo to the unchanged message content leaving all other
message elements unchanged
16.5.6 SRRetrieveEntity node

This node is a generic node that retrieves the metadata related with a WSRR
entity. It does not perform additional filtering or selection, other than that
specified by the property matching. It also does not resolve endpoints, do content
based routing, or set domain context for execution of the target service. It is up to
the message flow developer to perform all those functions.
Note: This node is independent of any other domain context.
Node properties
The properties on the node are: name tuple, template, user properties,
classification and MatchPolicy. These are shown in Table 16-8.
797
Table 16-8 SRRetrieveEntity node properties

Property
Name
Mandatory
Configurable
Default
Values
Name tuple
(portType
name,
namespace
and version)
No
Yes
Name tuple that uniquely

defines a WSRR defined
WSDL service portType.
Template
No
Yes
The template or type of

the entity as defined in
WSRR.
User
properties
No
No
Allows a query to specify

user-defined properties
for the port.
Classification
No
Yes
This uses the OWL

classification system.
Each classifier is a class
in OWL, and has a URI.
MatchPolicy
Yes
Yes
One
Property Values
Specify One to return

only 1 match; Specify All
to return all matches.
If all three values are specified for the Name tuple then all ports that implement
the single service portType will be returned (if they exist). At least one of the
three is required. If any of the three are left blank, then all ports that implement
multiple service portTypes will be returned (if a match is found).
Note: While the Name tuple, template, user properties and Classification
fields are not mandatory, a warning will be issued if none of the four properties
are set.
Figure 16-6 on page 799 shows a sample properties dialog for the
SRRetrieveEntity node.
798
Figure 16-6 SRRetrieveEntity node properties
Node terminals
Table 16-9 SRRetrieveEntity node terminals
Terminal Name
Description
In
Node input terminal
Out
Failure
799
Terminal Name
Description
Nomatch
If no entity is found, based on the specified values, the message is

propagated to this terminal.
Operational sequence
The following is the sequence that this node follows:
1. Receives a message
2. Retrieves the entity metadata information from WSRR using the specified
query string
3. If one or more matches can be found:
a. If MatchPolicy is One adds a single piece of metadata information to
the message instance, leaving all other message content unchanged.
b. If MatchPolicy is All, adds all matching metadata information to the
message instance, leaving all other message content unchanged.
c. Entity metadata information will be available for additional processing
(either by ESQL or a JavaComputeNode)
d. Propagates this to the out terminal
4. If a match cannot be found:
a. Propagates the input message to the nomatch terminal
5. On failure
a. Adds FailInfo to the unchanged message content leaving all other
message elements unchanged
16.6 WMB Client Cache for WSRR

This section gives a brief overview of the cache provided in the WMB V6 Client
for WebSphere Service Registry and Repository and explains the caching
options available for it.
16.6.1 Cache logical topology

The WMB Clients cache for WSRR entities is composed of both a cache and
proxy component, which utilizes the WSRR Web Service API to retrieve and
cache data in memory. See also this article on the Requestor side caching
pattern for additional details:
http://www.ibm.com/developerworks/webservices/library/ws-rscp1/
800
The proxy provides a basic API and utilizes the cache content to provide efficient
access to WSRR content at runtime. The cache itself stores both the query
objects (containing a reference to all bsrURI objects that represent the result of
the query as returned by WSRR) and the individual WSRR objects along with
basic statistics on the objects such as updatedTimestamp,
lastAccessedTimestamp and the number of times the object has been accessed
from the cache.
The logical topology of the WSRR cache can be seen in Figure 16-7.
Message Broker
Specific
WSRR
Nodes
WSRR Cache
WSRR
Proxy
API
WSRR
Proxy (Cache)
Configuration
WSRR
WSRR
Proxy &
Cache
WSRR
EJB
Client
Cache
Synchronize
WSRR
Web Service
API
Notification
Publish
JMS
Pub/Sub
Notification
Subscribe
Figure 16-7 WSRR cache logical topology
16.6.2 Cache loading strategy

The cache loading strategy determines how and when content from WSRR is
retrieved and populated in the cache. The proxy/cache configuration file supplies
data on the loading method to be used by the proxy. This file is supplied to the
proxy by the client environment through an API call. There are three options of
loading available to be specified.
No Load
The first option is to specify no load wherein the cache instance is completely
bypassed. The proxy serves as nothing more than a pass-through in
accessing WSRR. None of the query results obtained from WSRR are
cached and all queries are sent to WSRR for processing.
Lazy Load
The second option is to specify lazy load wherein the cache instance is
populated with an object from WSRR when the object is queried for the first
801
time by a client. Thereafter the object is stored up in the cache and returned
from the cache for subsequent queries for the same object. The object is
retained in the cache until the object is invalidated due to synchronization or
other means.
Preload
The third option is to specify preload wherein the cache instance is populated
with objects from WSRR prior to the object being queried by a client. The
cache configuration file controls the objects to be preloaded by specifying a
classification or a set of classifications objects belonging to which are
queried and pre-loaded by the proxy into the cache. The object is retained in
the cache until the object is invalidated due to synchronization or other
means.
16.6.3 Setting cache load strategy

No Load
Set the needCache option to false (needCache=false) in the wsrr.properties
file.
Preload
Set the needCache option to true (needCache=true) in the wsrr.properties file.
To specify the WSRR entities that will be preloaded, specify the
predefinedQueries value required to load the entities needed. The preload
option requires the cache update synchronization flow be installed.
Lazy Load
Set the needCache option to true (needCache=true) in the wsrr.properties file
and set the predefinedQueries to blank. The lazy load option does not require
that the cache update synchronization flow is installed (but it is
recommended).
16.6.4 Cached items

Entities stored in the cache are indexed by query string and by name tuple
(name, namespace, and version). Before issuing a query against WSRR, the
proxy will check the cache to see if it contains entities for the exact same query
string (name, classification, user property, and so on) or for a specific entity by its
unique tuple (name, namespace, and version). If found by either index (query
string or tuple), it will return the item, or if not found by either index it will perform
a query against WSRR and store the results (indexed by query string and tuple).
Entities are stored in the cache only once; however, they may be indexed in
multiple ways. For instance, suppose a query returns a specific entity. If a new
802
and different query is specified, the proxy would not find an existing index for this
new query string, and will thus issue the query against WSRR. If the same entity
is returned, the existing cached entity will be updated, and a new index created
(for the new query string). If a different entity is returned, it is stored in the cache
and two indexes are created (query string and tuple).
16.6.5 Cache synchronization

The cache synchronization process is available to keep the data consistent
between the cache and WSRR. While the cache is read-only, objects in WSRR
could be modified after the object has been cached in the WMB Client cache on
the client side. WSRR generates notifications in the form of JMS topics whenever
an object in the registry is created, updated or deleted.
16.7 WMB Client support for SOA patterns

The WMB Client nodes support two different styles of uses; one is a set of
generic access nodes for WSRR metadata and the other set of nodes support
the Router and Transcoder patterns. These patterns are explained below.
16.7.1 Transcoder pattern

From Service Oriented Architecture (SOA) Compass by IBM Press, ISBN
0-13-187002-5:
The transcoder pattern changes the format of the message payload without
changing its logical content. For example, it may convert a SOAP message into a
JMS/Text message with an XML payload that matches the body of the SOAP
message (possibly by mapping SOAP header fields into JMSProperties).
Mediations which conform to this pattern can often be created automatically
when there is a clear definition of the two formats and of the relationship between
them.
This pattern requires update access to the payload of the message.
Context
As seen in the SOA Characteristics section in the SOA Compass book, the
characteristics of platform, location, protocols, and versioning all need to be
understood, to one degree or another, by the requesters of a specific service.
Enterprises may choose different ways to implement a service and the
implementation may change over the life of the service.
803
Services come online, to provide new functionality or replace existing services

(for example, that have become obsolete).
These changes, depending on the implementation, can adversely affect clients.
Use of the pattern allows the Enterprise to reduce the impact to clients and
increase the flexibility of their (the Enterprise) choices for implementing services.
Forces
If the requester and provider are both under full control of the Enterprise, then
establishment of a unified protocol (location, and so on) and the planning and
scheduling of changes (that affect both parties) can be largely controlled. This
can lead to a preferred communication between the requester and provider,
which may result in a performance increase. However, if both the requester
and provider are not under full control of the Enterprise, then isolating the
requester from the implementation details can provide benefits to the provider
(the Enterprise) and the requester.
Multiple implementations of the same semantic service provide distinct
benefit to the Enterprise. For instance, the same semantic service may be
provided by both a SOAP/HTTP implementation and a XML/MQ
implementation; without the requester knowing these details.
New versions of a service may require new (or different) transformations. For
instance, a services change in implementation from SOAP/HTTP to XML/MQ
for performance reasons or a new version of a service coming online requiring
a different signature can be performed with no impact to the client.
Solution
This is a WSRR virtual service in that it does not provide business functionality;
however, it does represent the exposed business functionality and implements
the pattern.
For instance, suppose an enterprise provides a service that represents
functionality for a customer or about a customer. The functional and
non-functional specification (the functionality delivered and quality of availability)
defines the service, at least at the business partnership level. Regardless of the
implementation of the service, the business can specify the functionality that a
service will provide and the quality of that service and/or the availability of that
service.
Suppose this service is implemented as a Web Service; however, in order to
provide a specific quality of service it is re-implemented as a MQ-based
service. In other words, the implementation of the service has at least changed
the protocol, message format (probably), and location (service executable
endpoint). This change will require changes to all requesters, internal and
804
external. Coordination of the change(s) will impact the both requesters and
providers in multiple ways.
Within an Enterprise Service Bus the Transcoder mediation pattern provides (or
represents) a common semantic for the business service. It is responsible for
determining which operational service to invoke to execute the request, based on
message context, message content, and/or other data. Depending on this
information the mediation can transform the message (as required), change the
destination (location), and choose which operational service to use to fulfill the
request. New IT services can be brought online, old ones retired, and the
complete service lifecycle followed without affecting the clients.
In effect the mediation encapsulates the underlying operational service
implementation(s) into a single semantic service that uses a single canonical
interface. The mediation can determine if there is a preferred implementer, use a
different operational service provider to provide a different QoS to meet specific
SLAs, or route to a specific service for other business or technical reasons.
Figure 16-8 shows an enterprises view of the virtual service (ESB mediation). In
the figure all the IT service providers are assumed to provide the same
semantics, but maybe using different syntax.
ESB mediations
control which IT
service provider is
invoked
MQ based
Service Provider
Client
All content in XML
Internal
Requester
Virtual Service (Mediation)
Both use single, wellknown location
Web Service
Based
Service Provider
Web Service
Based
Service Provider
Figure 16-8 ESB Mediation Pattern
805
Consequences
A direct consequence of the ESB Transcoder pattern is that there is a single
canonical semantic representation of the exposed service, regardless of the
actual implementation of the operational service. This semantic could be a Web
Service that is exposed to requesters or some other interface type. This virtual
service is responsible for all transformations required to invoke the operational
service.
Another consequence is that this virtual service needs to have each supported
operational service known to it. This means that relationships between this
service, that implements the transcoder pattern, and the operational service that
actually provides the functionality must be established. This can be hard-coded
into this service, or can be externalized in WSRR.
Implementation
The most flexibility is obtained by externalizing the relationships between the
virtual service (that implements the transcoder pattern) and the operational
services.
The virtual service that implements the transcoder pattern contains relationships
to the operational services. The relationships metadata is used by this service in
order to determine which relationship, and thus which targeted operational
service, to select. In the logical model, the metadata that is used in the selection
is called endpointAlias (see the Endpoint object). However, the actual metadata
could be much more complex.
The Routing Label relationship property is used by the transcoder service to
branch or execute a specific piece of functionality. For instance, a message may
need to be transformed before it can be passed to a specific operational service.
Refer to 16.8, Setting up your environment for the patterns on page 809 on how
to realize this pattern in WSRR and using the pattern-based nodes in WMB.
16.7.2 Router pattern

The router pattern changes the intended route of a message, selecting between
the service providers associated with the mediation. Simple selection would
include routing between two versions of a service, with the percentage routed to
the new version being increased by the system administrator as confidence in its
capabilities increases. Another example is routing to a local version of a service
until it becomes overloaded, then routing to a more expensive remote service.
This latter case could also take the importance of the message into
consideration, as indicated by a gold user status or the size of a purchase, for
806
example. This pattern requires update access to the context of the message and
read access to the payload if it is needed for the routing-selection criteria.
Another way for the Enterprise to achieve looser coupling is to use a router. The
router really is intended to do what classically has been called
distribution/aggregation, that is, parsing the incoming request, sending individual
requests to appropriate service, handling responses. Response aggregation can
occur with synchronous protocols or can be avoided with asynchronous
protocols. Internal requesters normally interface with the virtual service that
performs the mediation. However, they could interface with the router virtual
service. The router can handle multiple message formats (for example, XSD
schemas) and perhaps even aggregated messages.
Context
As seen in the SOA Characteristics section in the SOA Compass book (Service
Oriented Architecture (SOA) Compass by IBM Press, ISBN 0-13-187002-5), the
characteristics of platform, location, protocols, and versioning all need to be
understood, to one degree or another, by the requesters of a specific service.
Enterprises may choose different ways to implement a service and the
implementation may change over the life of the service.
Services come online, to provide new functionality or replace existing services
(for example, that have become obsolete).
These changes, depending on the implementation, can adversely affect clients.
Use of the pattern allows the Enterprise to reduce the impact to clients and
increase the flexibility of their (the Enterprise) choices for implementing services.
Forces
If the enterprise wants to provide a single (or small set) of access points. The
router provides dynamic context routing, commonly using the message
content to aid that routing process.
If the enterprise wants to perform specific routing decisions, for instance
combining message content with service metadata to determine preferred
machines, service locations, and so on.
If the enterprise needs to route certain requesters to different services,
perhaps to fulfil a SLA.
Solution
This is a virtual service in that it does not provide business functionality; however,
it does represent the exposed business functionality. In this case it is usually a
single gateway for all services or for a classification of services. For instance,
807
suppose an enterprise provides three levels of service; standard, gold, and

platinum. Each of these QoS levels could be a separate router location.
In affect the mediation, router service, encapsulates a set of services into a
single location.
Figure 16-9 shows an enterprises view of the virtual service (ESB router).
Virtual Service
Logically shown as two

different ESBs, but
could be physically the
same ESB
Virtual Service
Distribution / Aggregation
Virtual Service
(Router)
Client
Internal
Requester
Virtual Service
Figure 16-9 ESB Router Pattern
Consequences
A direct consequence of the ESB Router pattern is that there is a single (or small
set) location for requesters to access. The enterprise can then determine how to
process a specific request. For instance, when a new version of a service comes
online, the enterprise may choose to route a specific list of requesters (perhaps
the beta users) to the new version.
Another consequence is that this virtual service needs to have a relationship to
each service it is capable of routing to; whether the service is another virtual
service or an operational service. If this routing needs to be dynamic, then the
necessary metadata needs to be externalized.
Implementation
The most flexibility is obtained by externalizing the relationship metadata
between the router virtual service and the service to which it can route.
808
Refer to 16.8, Setting up your environment for the patterns on page 809 on how
to realize this pattern in WSRR and using the pattern-based nodes in WMB.
16.8 Setting up your environment for the patterns

The configuration files necessary to set up the patterns in WSRR are provided
with the WMB V6 Client for WebSphere Service Registry and Repository. They
can be found in the following directory:
<WMBClient_Install>\Tests
Where <WMBClient_Install> is the WMB Client installation directory.
In the following structure:
<WMBClient_Install>\Tests\ClientForTestExecution - Tools to run this
example scenario
<WMBClient_Install>\Tests\SampleMessages - Example messages to use in the
WMB Message Flow
<WMBClient_Install>\Tests\WASTestWebServices - Example Web services to
deploy to WebSphere
<WMBClient_Install>\Tests\WMBTestFlows - WMB Message Flows
corresponding to this scenario
<WMBClient_Install>\Tests\WSRRTestEntities - WSRR configuration scripts
<WMBClient_Install>\Tests\WSRRTestEntities\Classifications - an OWL file
corresponding for this scenario
<WMBClient_Install>\Tests\WSRRTestEntities\Deployment - deployment
scripts to setup this scenario in WSRR
<WMBClient_Install>\Tests\WSRRTestEntities\GUIConfiguration Configuration files to add the new perspective to the WSRR UI
<WMBClient_Install>\Tests\WSRRTestEntities\SampleVirtualServices example services to add to WSRR
For the benefit of documenting the configuration procedure we used two
machines:
itso-wsrr - WSRR and will also host the demo Web services
809
itso-wmb - WMB and WMQ

You could host everything on a single machine if desired, although obviously the
machine may need to be slightly more powerful in that scenario.
16.8.1 Configuring WMB for the patterns

The following steps will guide you through how to configure your WMB and
WSRR environments to support the Mediation and Router SOA Patterns.
1. Edit <WMBClient_Install>\Tests\WSRRTestEntities\Deployment\setenv.bat
and set all variables as necessary for your environment.
You will almost definitely need to edit the SUPPORTPAC_HOME and
PAR_FILE_DIR variables.
2. From a WMB Command Console prompt run the following:
<WMBClient_Install>\Tests\WSRRTestEntities\Deployment\deploy_local.b
at.
That script will then perform the following steps:
Create MQ queues for the sample test flows
Deploy the WMB ServiceRegistryMessageBrokerNodes.par file
Copy required jars to the WMB working path shared-classed directory.
(This step is not actually necessary, since we did this manually in
Configure the WMB runtime shared-classes on page 784, however it will
not do any harm for the copy to run again since the same file will be
copied.)
Deploy the sample test flows BAR file to the broker
Deploy the cache update BAR file to the broker
16.8.2 Configuring WSRR for the patterns

We now need to configure WSRR, this will entail loading a new ontology system
for the new classifications and some new UI customizations.
Note: The UI customizations necessary for the WMB Patterns are used as the
demonstration scenario in Chapter 10, Customizing the Web UI on
page 381.
These steps do not need to be performed on the WSRR machine, the WSRR CLI
can connect to a remote WSRR server, however for reasons of practicality we will
be running the CLI on the WSRR server itself.
810
1. We need to configure the WSRR CLI before we use it to load the new
ontology and UI configuration files into WSRR.
Edit <WSRR_Install>\CLI\config\wsrrcli.conf and ensure all settings are
set correctly for your environment.
If you have an unsecured WSRR installation then configure the open
settings, since our WSRR server has WebSphere security turned on we will
configure the secure settings. The relevant portion of wsrrcli.conf for our
environment can be seen in Example 16-2.
Example 16-2 Sample wsrrcli.conf configuration file
## sample secure site -- alias "secure"

secure.java.naming.provider.url = iiop://localhost:2809
secure.com.ibm.CORBA.ConfigURL =
file://c:/Progra~1/IBM/WebSphere/AppServer/profiles/default/properties/sas
.client.props
secure.java.security.auth.login.config =
file://C:/progra~1/IBM/WebSphere/AppServer/profiles/default/properties/wsj
aas_client.conf
secure.host = localhost
secure.port = 8880
secure.type = SOAP
secure.securityEnabled = true
secure.javax.net.ssl.trustStore =
C:/progra~1/IBM/WebSphere/AppServer/profiles/default/etc/DummyClientTrustF
ile.jks
secure.javax.net.ssl.keyStore =
C:/progra~1/IBM/WebSphere/AppServer/profiles/default/etc/DummyClientKeyFil
e.jks
secure.javax.net.ssl.trustStorePassword = WebAS
secure.javax.net.ssl.keyStorePassword = WebAS
2. If you are running the WSRR CLI on a different machine to the one where the
WSRR client is installed, then copy the <WMBClient_Install>\Tests directory
to the WSRR CLI machine.
In our case we copied the entire <WMBClient_Install> directory to the WSRR
CLI machine and placed it here: C:\Program Files\IBM\WMB-WSRRClient
3. The MQ connection details are defined in
<WMBClient_Install>\Tests\WSRRTestEntities\SampleVirtualServices\scr
ipts\Constants.py. Check that the settings in that file are correct, but do NOT
change the values for the classifications in Constants.py though.
811
4. Edit
<WMBClient_Install>\Tests\WSRRTestEntities\SampleVirtualServices\cre
ate_sample_services.bat (in our case on the WSRR CLI machine).
Make sure the ALIAS is set to the correct alias from your wsrrcli.conf, in our
case secure. If you have security turned on then make sure the USER_ID
and PASSWORD are also set correctly to a user ID that can access WSRR.
5. Edit
<WMBClient_Install>\Tests\WSRRTestEntities\SampleVirtualServices\Dem
oCustomer.wsdl and
<WMBClient_Install>\Tests\WSRRTestEntities\SampleVirtualServices\Dem
oVehicle.wsdl (in our case on the WSRR CLI machine).
Make sure the wsdlsoap:address location at the bottom of the files is set to
the correct hostname and port for the machine you are deploying the
DemoServiceEAR to. In our case that is the WSRR machine itself. You may
also need to change it to https if you are using WebSphere security.
6. Run the following script and if prompted enter the correct userID and
password for a user able to access WSRR:
<WMBClient_Install>\Tests\WSRRTestEntities\SampleVirtualServices\cre
ate_sample_services.bat
7. Edit
<WMBClient_Install>\Tests\WASTestWebServices\deploy_DemoServiceEAR.b
at (in our case on the WSRR CLI machine).
Change WAS_BIN_HOME to be the correct path to your WebSphere bin
directory. If you have security turned on then make sure the USER_ID and
PASSWORD are also set correctly to a user ID that can access WSRR.
8. Change directory to
Run the following command:
<WSRR_Install>\CLI\wsrrcli.bat -a secure -c
<WSRR_Install>\CLI\config\wsrrcli.conf -u wasadmin -p passw0rd -w
<WAS_Install>/profiles/default
Where <WSRR_Install> is your WSRR installation directory and
<WAS_Install> is your WebSphere Application Server installation directory.
Replace secure with the name of the alias you are using in wsrrcli.conf
(normally open or secure). Also replace wasadmin and passw0rd with the
correct credentials for your WSRR installation.
It may prompt you for a username and password - if so enter the user ID and
password for your WSRR WebSphere installation. Once complete it should
have reported the installation of numerous configuration files.
812
9. Restart WebSphere on the WSRR machine to pick up the new GUI

configuration files. Once done you should see two new perspectives in the
WSRR UI - MB Pattern Admin and MB Pattern User.
10.Run the following script:
<WMBClient_Install>\Tests\WASTestWebServices\deploy_DemoServiceEAR.b
at
11.Edit
<WMBClient_Install>\Tests\WSRRTestEntities\Deployment\createJmsEnpoi
ntResources.bat (in our case on the WSRR CLI machine).
Change WAS_HOME to be the correct path to your WebSphere AppServer
directory. If you have security turned on then make sure the
WAS_USERNAME and WAS_PASSWORD are also set correctly to a user ID
that can access WSRR. If you are not security then set both
WAS_USERNAME and WAS_PASSWORD to be .
Note: If your <WMBClient_Install> path contains a space character then
you will also need to replace both references to %~dp0 with %~dps0 in
createJmsEnpointResources.bat. Otherwise the script will not run correctly
and will report errors, such as Cannot find c:\Program.
12.Run the following script:
<WMBClient_Install>\Tests\WSRRTestEntities\Deployment\createJmsEnpoi
ntResources.bat
16.8.3 Configure the test client

On the WMB machine edit
<WMBClient_Install>\Tests\ClientForTestExecution\setEnv.bat and ensure
JAVA_HOME is set correctly.
Note: If your <WMBClient_Install> path contains a space character then you
will also need to replace references to %~dp0 with %~dps0 in all the scripts in
the ClientForTestExecution directory. Otherwise the scripts will not run
correctly.
16.8.4 Run the tests

On the WMB machine you should now be able to run the supplied test scripts to
verify that the flows do indeed work and that WMB can connect to WSRR and
retrieve data.
813
There are five test scripts provided all in the

<WMBClient_Install>\Tests\ClientForTestExecution directory. Run each of the
scripts from a Windows command prompt.
run_addVehicle.bat
This script will invoke the TestFlow with the vehicle message.
It outputs a trace file in C:\VirtualService.log if you need to debug any
problems.
Example 16-3 shows an example of the type of output you should get back from
running the script.
Example 16-3 run_addVehicle.bat example output
*** invoke test flow with message_vehicle.xml

Sending message to http://localhost:7080/DemoSR/services/TestFlow
Getting response >>>
<NS1:Envelope
xmlns:NS1="http://schemas.xmlsoap.org/soap/envelope/"><NS1:Body><N
S2:addVehicle xmlns:NS2="http://demo.sr.eis.ibm.com"><str>A vehicle
description</str></NS2:addVehicle></NS1:Body></NS1:Envelope>
Completed in 9094 ms.
C:\Program
Files\ibm\MQSI\WMB-WSRRClient\Tests\ClientForTestExecution>pause
Press any key to continue . . .
Figure 16-10 on page 819 shows the TestFlow message flow as used by
run_addVehicle.bat. It is also described in more detail in TestFlow on page 818.
run_testCustomer.bat
This script will invoke the TestFlow with the customer message.
problems.
running the script.
Example 16-4 run_testCustomer.bat example output
*** invoke test flow with message_customer.xml

814
<soapenv:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header/>
<soapenv:Body><p434:updateCustomerResponse
xmlns:p434="http://demo.sr.eis.ibm.com"><updateCustomerReturn>DemoCusto
mer.updateCustomer(A customer
description)</updateCustomerReturn></p434:updateCustomerResponse></soap
env:Body></soapenv:Envelope>
run_testCustomer.bat. It is also described in more detail in TestFlow on
page 818.
run_testEntityFlow.bat
This script will invoke the EntityTestFlow.
It outputs a trace file in C:\RetrieveEntity.log if you need to debug any
problems.
running the script.
Example 16-5 run_testEntityFlow.bat example output
Sending message to http://localhost:7080/DemoSR/services/EntityTestFlow

<Result><Status>Found 1 Entity(ies)!</Status><Entity
name="RMAssertionPolicy" namespace="http://mb.sr.eis.ibm.com"
version="1.0.0"><content><wsp:Policy wsu:Id="RMAssertion"
TargetNamespace="http://mb.sr.eis.ibm.com"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss
-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"&
gt;
<wsp:ExactlyOne>
<wsp:All>
<wsrm:RMAssertion><wsrm:InactivityTimeout
Milliseconds="600000"/><wsrm:BaseRetransmissionInterval
Milliseconds="3000"/><wsrm:ExponentialBackoff/><w
815
srm:AcknowledgementInterval
Milliseconds="200"/></wsrm:RMAssertion>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy></content></Entity></Result>
C:\Program
Figure 16-12 on page 822 shows the EntityTestFlow as used by
run_testEntityFlow.bat, the message flow is also described in more detail in
EntityTestFlow on page 822.
run_testITService.bat
This script will invoke the ITServiceTestFlow with the customer message.
It outputs a trace file in C:\SRRetrieveITService.log if you need to debug any
problems.
running the script.
Example 16-6 run_testITService.bat example output
*** invoke test flow with message_customer.xml

Sending message to
http://localhost:7080/DemoSR/services/ITServiceTestFlow
<soapenv:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header/>
<soapenv:Body><p434:updateCustomerResponse
xmlns:p434="http://demo.sr.eis.ibm.com"><updateCustomerReturn>DemoCusto
mer.updateCustomer(A customer
description)</updateCustomerReturn></p434:updateCustomerResponse></soap
env:Body></soapenv:Envelope>
Press any key to continue .
816
Figure 16-11 on page 821 shows the ITServiceTestFlow message flow as used
by run_testITService.bat, the message flow is also described in more detail in
ITServiceTestFlow on page 821.
run_testMQ.bat
This script will invoke the TestFlow with the MQ message.
problems.
running the script.
Example 16-7 run_testMQ.bat example output
*** invoke test flow with message_mq.xml

<Result><Status>Message submitted to MQ service for
processing</Status><MQ_DestinationData><queueManagerName>WBRK6_DEFAULT_
QUEUE_MANAGER</queueManagerName><queueName>SERVICE.INPUT</queueName><ms
gId>414d51205742524b365f44454641554ce4fd734520001403</msgId><correlId>4
14d51205742524b365f44454641554ce4fd734520001404</correlId></MQ_Destinat
ionData><RequestMessage>
<SRRequest>
<Auth>
<userid>user id</userid>
<password>password</password>
</Auth>
<Verb>UpdateAll</Verb>
<Data>
<mqdata>mq message data</mqdata>
</Data>
</SRRequest>
</RequestMessage></Result>
C:\Program
run_testMQ.bat. It is also described in more detail in TestFlow on page 818.
817
16.8.5 Test message flows

The following sections describe each of the three message flows used in this
scenario in more detail.
More information about the WMB built-in nodes mentioned below can be found at
this Web site:
http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/topic/com.ib
m.etools.mft.doc/ac04550_.htm
TestFlow
Figure 16-10 on page 819 shows the TestFlow message flow.
818
Figure 16-10 TestFlow message flow
The message flows through the TestFlow Message Flow as follows:

1. The starting point for the message is the HTTP Input node which is listening
for a message.
2. The message is then used to trigger the retrieval of a Web service from
WSRR in the SR Get Service node, this checks WSRR for a service which
has the same verb as the input message to this flow.
3. There is then a TraceService node which outputs some debug information to
a file.
819
4. The Route to mapping node then routes the message based on the
SR-Route-To-Label environment variable in the WMB LocalEnvironment.
This value was set by the SRGetVirtualService node. If it contains vehicle
then the message is routed to the Label-Vehicle node, if it contains
customer then it is routed to the Label-Customer node. Otherwise if it
contains ALL it is routed to the Label-ALL node.
5. If it was a customer message then it now proceeds through the map
customer node, this generates a new message in a different format based on
the input message.
If it was a vehicle message then it now proceeds through the map vehicle
node, this also generates a new message in a different format based on the
input message.
6. All three types of message now flow to the SR Process Service node where
the message is processed. This node is used to create the proper format for
the target service invocation.
7. The message then passes through the Route to Dispatcher node which will
route the message based on the content of the SR-Protocol-Label
environment variable in the WMB LocalEnvironment. If it contains
URLEndpoint the message is routed to the Label-URLEndpoint node,
messages containing MQEndpoint go to the Label-MQEndpoint node, and
those containing JMSEndpoint are routed to the Label-JMSEndpoint node.
8. The service in each message is then dispatched using the relevant
SRDispatchVirtualService node for each type of message. The
SRDispatchVirtualService nodes are used to establish the endpoint of the
target service.
a. URLEndpoint messages retrieve the HTTP service information from
WSRR and then invoke it using the HTTP Request node. This then gives
a HTTP Service Reply.
b. MQEndpoint messages retrieve the MQ service information from WSRR
and then put a MQ message on the appropriate MQ queue. The Display
MQ Submission compute node is then called which sets the relevant
parameters for the MQ Destination queue from variables in the
LocalEnvironment. The final node in the flow for MQ messages gets the
MQ Service Reply.
c. JMSEndpoint messages retrieve the JMS service information from WSRR
and then publish a JMS message using that information. The Display
JMS Submission compute node is then called which sets some Result
parameters based on variables in the LocalEnvironment. The final node in
the flow for JMS messages gets the JMS Service Reply.
820
ITServiceTestFlow
Figure 16-11 shows the ITServiceTestFlow message flow.
Figure 16-11 ITServiceTestFlow message flow
This message flow retrieves a PortType from WSRR in the following stages:
for a message.
2. The message is then used to trigger the retrieval of a service port type from
WSRR in the SRRetrieveITService node, this checks WSRR for a port type
called DemoCustomer with a given namespace and which has a user
property policy set to RM, and country set to China. It also must have
the specified classification (InitialState1).
3. If the node fails to retrieve the service then the Failure compute node is
called which will set the appropriate result status.
4. If the SRRetrieveITService node did not match a service with the
appropriate criteria then the Post No Match compute node is called which
again sets the appropriate result status.
5. If the document was found then a Customer Mapping node is called which
creates a new message based on the original one.
6. A Trace node is then called to output some appropriate debug information to
a file.
7. The HTTP Request node then opens a connection to the specified URL.
8. Regardless of the path through the flow, it comes to an end with the HTTP
Reply node which will output the reply message to the Web services client
(or the console in the case of the test scripts).
821
EntityTestFlow
Figure 16-12 shows the EntityTestFlow message flow.
Figure 16-12 EntityTestFlow message flow
This message flow retrieves a Policy document from WSRR in the following
stages:
for a message.
2. The message is then used to trigger the retrieval of a policy document from
WSRR in the SRRetrieveEntity node, this checks WSRR for a document
called RMAssertionPolicy with a given namespace and which has a user
property grade set to gold.
3. If the node fails to retrieve the policy document then the Display Failure
compute node is called which will set the appropriate result status.
4. If the SRRetrieveEntity node did not match a policy document with the
appropriate criteria then the Display No Match compute node is called which
again sets the appropriate result status.
5. If the document was found then a Trace node is called to output some
appropriate debug information to a file.
6. Then the Display Entity Content node is called to output the Policy
document content.
7. Regardless of the path through the flow, it comes to an end with the HTTP
Reply node which will output the reply message to the Web services client
(or the console in the case of the test scripts).
822
16.8.6 Optional: Importing the test scenario into WMB toolkit

If you want to see how the provided message flows work, or customize them in
any way then the provided files can be imported into your WMB Toolkit.
1. Create a Server project
2. Import into that project from the provided zip file:
<WMBClient_Install>\Tests\WMBTestFlows\WSRRNodes_TestFlow_PIC.zip
3. Create a new Message Broker Archive selecting the projects you just
imported
4. Deploy the new BAR file to your Broker execution group.
Refer to the WMB Information Center if you need more help with any of these
stages:
823
824
17
Chapter 17.
Integrating WSRR with CICS

This chapter describes how to integrate WSRR with CICS and the possible ways
this combination can be used.
This chapter discusses the following:
17.2, What is CICS? on page 827
17.3, Installation on page 831
17.4, Publishing WSDL files from z/OS batch to WSRR on page 834
17.5, Publishing WSDL files from CICS to WSRR on page 842
17.6, Retrieving WSDL files from WSRR using z/OS batch on page 847
17.7, Security considerations on page 854
825
17.1 Introduction
Customer Information Control System (CICS) can be integrated with WebSphere
Service Registry and Repository through an additional CICS SupportPac
(CA1N). This SupportPac provides the tools to streamline the job of registering,
discovering and governing Web services resources generated from CICS
applications. Together these tools provide additional support for organizations
intending to move to a Service-Oriented Architecture (SOA).
The new tools enable Web Services Description Language (WSDL) files derived
from CICS application interfaces to be automatically published from the CICS
z/OS environment to WSRR where they can be accessed by other Web
applications. The tools also enable retrieval of Web Service Description
Language files from WSRR, into the z/OS environment where they can be
modified and reverse engineered into new CICS High Level Language
applications (HLLs).
The SupportPac includes:
CWSP - a CICS transaction to publish a WSDL document to WSRR for each
of your CICS programs that are Web service providers
DFHWS2SR - a z/OS batch utility to publish a WSDL document to WSRR
DFHSR2WS - a z/OS batch utility to read a WSDL document from WSRR
When enabling your CICS application to be a Web service provider, you can use
the CICS Web services assistant (DFHLS2WS) provided with CICS TS V3.1 to
generate the WSDL interface from your programs high level language structures.
Use this SupportPac to automate the publication of this WSDL directly from z/OS
to WSRR.
When developing a CICS application that invokes a Web service, use this
SupportPac to automate the retrieval of the WSDL document from WSRR
directly to z/OS. You can then use the CICS Web services assistant
(DFHWS2LS) to generate the high level language structures needed to pass
data to CICS when invoking the Web service.
Note: CICS SupportPac CA1N can be downloaded from:
826
17.2 What is CICS?

This section provides a short overview of the products in the CICS portfolio. It
also looks at why the ability to interoperate CICS with WebSphere is important in
the context of using CICS transactional applications as Web services within an
SOA (service oriented architecture). Finally the section explains why WSRR is
central to both application development and the runtime in an SOA that
implements CICS and WebSphere.
17.2.1 CICS product portfolio

CICS is IBM Customer Information Control System and is a major family of IBM
application servers, connectors and tools for delivering high volume transaction
processing, management and connectivity. Since being introduced over 30 years
ago, CICS has been the power behind worldwide transaction processing systems
that handle billions of transactions per day. CICS is used in financial, insurance,
banking, e-commerce and other transactional environments where high
throughput, security, scalability and reliability are critically important.
CICS runs primarily on IBM mainframe systems under the z/OS or z/VSE
operating systems but is also available as a distributed product for use on
i5/OS, OS/2, and as TXSeries on AIX, Windows, and Linux. The majority of
users run CICS on z/OS.
CICS transaction processing systems handle online and batch processing,
supporting thousands of transactions per second on large mainframe systems
such as System z and z9. This capability makes CICS a central part of
enterprise computing. Programmers and developers write CICS applications in
COBOL, PL/I, C, C++, IBM Basic Assembly Language, REXX, and Java.
17.2.2 CICS Transaction Server

CICS Transaction Server is the application server that handles CICS
transactions. It provides a mainframe runtime environment for processing high
volumes of CICS transactions reliably and securely, in a way that can be scaled
to meet changing demands and workloads. CICS Transaction Server also
supports the use of CICS applications as service providers or requesters within
an SOA.
CICS Transaction Server has an associated set of tools used for managing the
CICS subsystem (for example CICS Configuration Manager), and for
transforming applications (for example CICS Business Event Publisher for
MQSeries).
Chapter 17. Integrating WSRR with CICS
827
17.2.3 CICS tools

The CICS tools play an important role in managing the CICS Transaction Server
runtime efficiently. They enable system managers and administrators to analyze
and optimize CICS system functionality, performance and efficiency. The CICS
tools are designed to increase productivity, reduce costs and ultimately, to
improve the customer satisfaction perceived by end-users. The CICS tools
enable best practice management, monitoring and control of the CICS
subsystem. They also enable transformation of CICS applications so they can be
accessed by other systems.
The following tools support CICS subsystem management, monitoring and
control:
CICS Configuration Manager: for managing CICS resource definitions used in
multiple CICS systems
CICS Interdependency Analyzer: for analyzing the relationships between
CICS resources to make management decisions.
CICS VSAM Recovery: for recovering corrupted CICS or VSAM data.
Session Manager: for managing multiple CICS sessions from a single
terminal.
CICS Batch Application Control: for managing batch processes that coexist
with CICS systems.
CICS Performance Analyzer: for offline reporting on CICS system
performance.
CICS VSAM Copy: for copying CICS data without interrupting users.
CICS Online Transmission Time Optimization: for 3270 terminal data stream
performance optimization.
The following tools support CICS application transformation:
CICS Business Event Publisher for MQSeries: for publishing CICS
applications and data as events.
CICS Interdependency Analyzer: for analyzing relationships between CICS
resources to make decisions about transforming them.
CICS VSAM Transparency: for migrating VSAM data to DB2 without rewriting
it.
17.2.4 CICS connectors

The CICS connectors provide a way of extending existing CICS and TXSeries
(the distributed version of CICS) into other operational areas in order to more
828
fully exploit the resources they use. The connectors enable better performance,
scalability, reliability, systems management and security.
The CICS connectors are:
CICS Transaction Gateway: for rapid deployment of CICS applications into an
SOA whilst keeping existing business logic intact.
CICS Universal Client: for delivering low-cost, single-user access to CICS
across an enterprise.
SOAP for CICS: for enabling CICS applications to interact securely and
reliably with Web services, independently of platform, environment or
application language.
MQSeries Integrator Agent for CICS: for application integration with a run time
component and a build time component.
17.2.5 CICS TXSeries

TXSeries is designed for running CICS transactions on distributed systems
rather than in a mainframe environment. TXSeries has been powering CICS
transaction processing on distributed platforms for 10 years. It runs on the AIX,
Windows, HP-UX and Solaris operating systems, and features an intuitive
Web-based administrative console which has the same look and feel as the
WebSphere administrative console. TXSeries also enables services written in
COBOL, C, C++, PL/1 and Java, to be integrated into an SOA.
17.2.6 Why interoperate CICS and WebSphere?

From a business viewpoint, interoperation greatly increases the range of
commercial possibilities for customers who are using CICS and WebSphere by
allowing the tools, applications and runtimes in each environment to make use of
resources held in the other.
From the CICS customer viewpoint, the transactional programs and applications
that have been developed and maintained over the last 20 to 30 years represent
a huge investment in time and money with many millions of lines of code usually
being involved. By allowing WebSphere to access these valuable resources, they
can be modernized, reused and better exploited in modern, flexible SOA
architectures.
There are two main scenarios where CICS and WebSphere can interoperate:
Application development: using tools like WebSphere Developer for System z
to develop new CICS applications and to modernize existing CICS
829
applications. In addition, using the CICS SupportPac tools to

reverse-engineer CICS applications from files held in WSRR.
Application runtime: enabling applications in CICS and WebSphere to invoke
each other as service providers and service requesters within an SOA
implementation.
Application Development
The WebSphere product portfolio contains an important tool for System z
application development called WebSphere Developer for System z.
WebSphere Developer for System z (formerly called WebSphere Developer for
zSeries) is an integrated application development workbench that runs in
Eclipse. The product is specifically designed for developing System z
applications (the applications that run on CICS mainframe systems).
When a developer uses WebSphere Developer for System z to work with a CICS
application, the tool must be able to locate the resources (programs) that make
up that application. This is possible because an Eclipse plug-in provides an
interface that allows WebSphere Developer for System z to access service
metadata held the WSRR in the form of WSDL files.
On the CICS side of the development fence, the WSRR SupportPac tools
included with CICS Transaction Server enable developers to retrieve application
service metadata files (WSDL files) from WSRR, bring them into the CICS z/OS
environment, and 'reverse engineer' them into new CICS High Level Language
(HLL) applications.
Application Runtime
In an SOA implementation that involves CICS and WebSphere, CICS
applications must be able invoke WebSphere applications as service providers
(for example applications running in WebSphere Application Server). WebSphere
applications must be able to invoke CICS applications as service providers.
WSRR plays a key role in an SOA runtime environment because it holds the
service metadata information (WSDL files) that enable CICS and WebSphere
applications to discover and invoke (call) each other.
This is possible because WSDL files derived from CICS application HLL
structures are published automatically from the CICS z/OS environment to
WSRR. These files can then be accessed by other Web applications that want to
invoke their associated applications.
830
17.2.7 CICS and WebSphere in an SOA

Firstly, a short recap of what an SOA is. SOA is not a product or a runtime
environment. It is a business-centric, architectural approach to IT that allows
loose coupling of disparate applications as reusable business tasks, processes
or services. SOA encourages the use of composite applications that call other
functions from multiple sources within and beyond the enterprise, thus
supporting horizontal business processes.
In an SOA that implements CICS and WebSphere applications (or any other
SOA for that matter), good governance is critically important. Good governance
enables best practice management, control and exploitation of assets and
resources.
Put in practical terms, this means allowing developers to easily discover existing
services or components so that they can be reused, extended and exploited
within new solutions. It also means enabling disparate applications running in
CICS and WebSphere (two very different environments) to discover and invoke
each other as service requesters or service providers.
An SOA that involves CICS and WebSphere therefore depends on having a
WSRR which is well structured. The registry must also be supported by a good
governance process, and by development staff who are encouraged to reuse
existing assets and resources wherever possible.
17.3 Installation
This section describes the tasks you need to perform to download and install the
CICS SupportPac, and the software required to run it.
This section is aimed at experienced CICS system programmers who are
responsible for installing and customizing CICS. Knowledge of downloading files
from the internet, uploading files to z/FS, and UNIX commands is assumed.
Options for the cp, pax, and chmod commands are detailed in the z/OS UNIX
System Services Command Reference manual.
17.3.1 Software requirements

To use the SupportPac, the following software products required at the version
stated, or later:
IBM CICS Transaction Server for z/OS V3.1
The service APAR PK23547 for CICS TS is required to be applied to provide
the mapping level 1.2 support.
831
IBM SDK for z/OS Java 2 Technology Edition V1.4

IBM WebSphere Service Registry and Repository V6
17.3.2 Downloading and installing the CICS SupportPac

The following steps guide you through downloading and installing the
SupportPac.
1. From a workstation, download the ca1n.zip file from the IBM CICS
SupportPacs Web site to your workstation:
Browse to the Web site or to the CICS TS V3.1 Information Center
Welcome page.
http://www.ibm.com/software/htp/cics/tserver/support/
Click the link SupportPacs
Click the link View all: By Category
Click the link CA1N
Click the link FTP
Providing you agree to the terms and conditions shown, click the link I
agree
Save the ca1n.zip file onto your workstation.
2. Extract the contents of ca1n.zip to a local directory. The directory should
contain the following:
\ca1n\ca1n.pdf the SupportPac documentation
\ca1n\ca1n.pax.Z the SupportPac code in the z/OS pax archive format
3. Upload the file \ca1n\ca1n.pax.Z in binary to your z/OS system. For example,
from a workstation command shell, enter the following. Substitute
install-directory with the directory to be used for the SupportPac files on
z/FS, such as /usr/lpp/cicsts/ca1n.
ftp mvs.mysite.com
(login with your hostname, userid and password)
ftp>
ftp>
ftp>
ftp>
ftp>
832
mkdir /install-directory
cd /install-directory
bin
put ca1n\ca1n.pax.Z
quit
4. Expand the ca1n.pax.Z file. For example, from a z/OS UNIX shell enter the
following:
cd /install-directory
pax -rvf ca1n.pax.Z
5. Ensure the appropriate permissions and attributes are set for the files in the
install-directory and its sub-directories. In particular the files in
install-directory/bin need to have their execution permission set. For
example, from a z/OS UNIX shell enter the following:
chmod 755 /install-directory/bin/*
6. Copy the CA1N.JCL.XMIT and CA1N.LOAD.XMIT files to datasets. For
example, from a z/OS UNIX shell enter the following. Substitute hlq for the
high-level qualifier to be used for the SupportPac datasets:
cp -F bin -P "RECFM=FB,LRECL=80"
/install-directory/datasets/CA1N.JCL.XMIT
"//'hlq.CA1N.JCL.XMIT'"
cp -F bin -P "RECFM=FB,LRECL=80"
/install-directory/datasets/CA1N.LOAD.XMIT
"//'hlq.CA1N.LOAD.XMIT'"
7. Expand the hlq.CA1N.JCL.XMIT and hlq.CA1N.LOAD.XMIT datasets to
libraries. For example, from a z/OS TSO shell enter the following:
RECEIVE INDATASET('hlq.CA1N.JCL.XMIT')
When prompted with the message Enter restore parameters... respond with:
DA('hlq.CA1N.JCL')
RECEIVE INDATASET('hlq.CA1N.LOAD.XMIT')
When prompted with the message Enter restore parameters... respond with:
DA('hlq.CA1N.LOAD')
8. The hlq.CA1N.JCL.XMIT and hlq.CA1N.LOAD.XMIT datasets can now be
safely removed.
The following directories and dataset libraries should now exist:
/install-directory/ - high level installation
/install-directory/bin - z/OS UNIX shell scripts
/install-directory/classes - Java class libraries
/install-directory/datasets - z/OS datasets
/install-directory/docs - documentation
/install-directory/licenses - license information
/install-directory/pipeline - CICS pipeline configuration
833
/install-directory/samples - sample configuration

/install-directory/wsbind - CICS WSBIND
hlq.CA1N.JCL() - JCL to launch the utilities and sample JCL library
hlq.CA1N.LOAD() - program load modules library
17.4 Publishing WSDL files from z/OS batch to WSRR

This section describes how to use the z/OS cataloged procedure DFHWS2SR
provided by the SupportPac to publish a Web Services Description Language
document stored on z/FS to WSRR together with optional metadata.
If you need to first create a WSDL document from your CICS application's high
level language structures (copybooks), use the DFHLS2WS procedure provided
with CICS TS V3.1.
It is possible to call DFHLS2WS followed by DFHWS2SR within the same z/OS
batch JCL to keep the WSBind, WSDL, and the WSDL stored in WSRR in step
with the copybooks. Figure 17-1 illustrates the components involved in this
scenario.
z/OS Batch JCL

Input Parameters:
Language, container, end of URI,
Provider Application Name, etc...
Output
Input
Language
Structures
Input Parameters:
WSDL document location, meta
data description, name, version,
encoding, user-defined
name+value, WSRR server
location + security credentials
.
.
DFHLS2WS
Build WSDL and WSBind
file from.Language
Structure(s)
.
.
.
.
DFHWS2SR
.
Publish to WSRR
.
.
WSBind
WSDL
Web service WSRR API
WSRR
log
Figure 17-1 Publishing WSDL files from z/OS batch to WSRR
834

responsible for installing and customizing CICS. Knowledge of basic UNIX
commands and the Java configuration on your system is required.
The userid under which the DFHWS2SR procedure is run will need authority to:
read files from the SupportPac bin directory (WORKDIR symbolic parameter)
read files from the Java product directories (JAVADIR symbolic parameter)
read the WSDL file to be published (LOCATION parameter)
optionally, read the trust store and key store files (TRUSTSTORE and
KEYSTORE parameters)
write access to the temporary directory (TMPDIR symbolic parameter)
write access the log file (LOGFILE parameter)
access to TCP/IP services to send Web services requests to the WSRR
server (HOSTPORT parameter)
If connectivity to WSRR is required to be via HTTPS, review 17.7, Security
considerations on page 854.
17.4.1 Running DFHWS2SR

To run the DFHWS2SR procedure you need to write JCL that includes symbolic
parameters and input parameters.
1. Customize the template JCL provided in hlq.CA1N.JCL(WSDLPUB) using
information in 17.4.2, Job control statements for DFHWS2SR on page 837.
2. Submit the JCL.
3. If there are errors reported in the JCL output, check the z/FS log file specified
by the LOGFILE parameter for detailed error messages.
The following (Example 17-1) is a customized version of hlq.CA1N.JCL(WSDLPUB).
Example 17-1 A customized version of hlq.CA1N.JCL(WSDLPUB)
//WSDLPUB JOB (MYSYS,AUSER),MSGCLASS=H,

//
CLASS=A,NOTIFY=&SYSUID,REGION=0M
//WSDLPUB JCLLIB ORDER=(CICS.CICSTS.CA1N.JCL)
// EXEC DFHWS2SR,
//
JAVADIR='java/IBM/J1.4',
//
WORKDIR='/usr/lpp/cicsts/ca1n',
//
TMPDIR='/u/username/tmp',
//
TMPFILE='WS2SR'
//INPUT.SYSUT1 DD *
835
LOGFILE=/u/username/tmp/WS2SR.log
LOCATION=/usr/lpp/cicsts/cicsts31/samples/webservices/wsdl/placeOrder.wsdl
NAME=placeOrder
DESC=CICS TS V3.1 Catalog sample place order service
VERSION=3
ENCODING=UTF-8
HOSTPORT=http://wsrr.my-example.server:443
USERNAME=wasadmin
PASSWORD=wasadm1n
KEYSTORE=/u/username/DummyClientKeyFile.jks
KEYPWD=wasadm1n
TRUSTSTORE=/u/username/DummyClientTrustFile.jks
TRUSTPWD=wasadm1n
PROP1NAME=Host
PROP1VALUE=IBM CICS Transaction Server
PROP2NAME=Publisher
PROP2VALUE=CICS SupportPac CA1N
*/
Example 17-2 is an extract from the log file created by DFHWS2S after
submitting the example JACL above in Example 17-1 on page 835.
Example 17-2 DFHWS2S log extract
Value of 'NAME' is 'placeOrder'.

Value of 'LOCATION' is
'/usr/lpp/cicsts/cicsts31/samples/webservices/wsdl/placeOrder.wsdl'.
Value of 'DESC' is 'CICS TS V3.1 Catalog sample place order service'.
Value of 'VERSION' is '3'.
Value of 'ENCODING' is 'UTF-8'.
Value of 'LOGFILE' is '/u/username/tmp/WS2SR.log'.
Value of 'HOSTPORT' is 'http://wsrr.my-example.server:443'.
Value of 'USERNAME' is 'wasadmin'.
Value of 'PASSWORD' is '********'.
Value of 'KEYSTORE' is '/u/username/DummyClientKeyFile.jks'.
Value of 'KEYPWD' is '********'.
Value of 'TRUSTSTORE' is '/u/username/DummyClientTrustFile.jks'.
Value of 'TRUSTPWD' is '********'.
Value of 'PROP1NAME' is 'Host'.
Value of 'PROP1VALUE' is 'IBM CICS Transaction Server'.
Value of 'PROP2NAME' is 'Publisher'.
Value of 'PROP2VALUE' is 'CICS SupportPac CA1N'.
Starting publish of WSDL document to WSRREndpoint
[http://wsrr.my-example.server:443/WSRRCoreSDO/services/WSRRCoreSDOPort
]
836
Create message [<soapenv:Envelope

xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"><
soapenv:Body><p828:create
xmlns:p828="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/sdo"><
sdo:datagraph xmlns:sdo="commonj.sdo"
xmlns:sdo_1="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/sdo"><sd
o_1:WSRR><sdo_1:root>//@eRootObject/@artefacts.0</sdo_1:root><sdo_1:art
efacts xsi:type="sdo_1:WSDLDocument" encoding="UTF-8" description="CICS
TS V3.1 Catalog sample place order service"
location="/usr/lpp/cicsts/cicsts31/samples/webservices/wsdl/placeOrder.
wsdl" name="placeOrder" version="3" content="
...
="><sdo_1:userDefinedProperties name="Host" value="IBM CICS Transaction
Server"/><sdo_1:userDefinedProperties name="Publisher" value="CICS
SupportPac
CA1N"/></sdo_1:artefacts></sdo_1:WSRR></sdo:datagraph></p828:create></s
oapenv: Body></soapenv:Envelope>]
CreateResponse [<soapenv:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Body><p2
44:createResponse
createReturn>WSRR--c8e644f7.f101e566.3a247853.10defa75aa9.26ec785d.63</
createReturn></p244:createResponse></soapenv:Body></soapenv:Envelope>]
Program 'DFHWS2SR' completed SUCCESSFULLY.
17.4.2 Job control statements for DFHWS2SR

JOB
Initiates the job.
EXEC
Specifies the procedure name (DFHWS2SR).
DFHWS2SR requires sufficient storage to run a Java virtual machine (JVM).
You are advised to specify REGION=0M on the EXEC statement.
INPUT.SYSUT1 DD
Specifies the input. The input parameters are usually specified in the input
stream.
837
However, they can be defined in a data set, or in a member of a partitioned

dataset.
Symbolic parameters
The following symbolic parameters are defined in cataloged procedure
DFHWS2SR:
JAVADIR=path
Specifies the name of the Java directory that is used by DFHWS2SR. The
value of this parameter is appended to /usr/lpp/ giving a complete path name
of /usr/lpp/path.
TMPDIR=tmpdir
Specifies the location of a directory in z/FS that DFHWS2SR uses as a
temporary work space. The user ID under which the job runs must have read
and write permission to this directory.
The default value is /tmp
TMPFILE=tmpprefix
Specifies a prefix that DFHWS2SR uses to construct the names of the
temporary workspace files.
The default value is WS2SR
WORKDIR=path
Specifies the location of the directory in z/FS in which the SupportPac was
installed. The user ID under which the job runs must have read permission to
this directory.
The temporary work space

DFHWS2SR creates the following three temporary files during execution:
tmpdir/tmpprefix.in
tmpdir/tmpprefix.out
tmpdir/tmpprefix.err
Where:
tmpdir is the value specified in the TMPDIR parameter
tmpprefix is the value specified in the TMPFILE parameter.
The default names for the files (when TMPDIR and TMPFILE are not specified),
are:
/tmp/WS2SR.in
/tmp/WS2SR.out
838
/tmp/WS2SR.err
Important: DFHWS2SR does not lock access to the generated HFS file
names. Therefore, if two or more instances of DFHWS2SR run concurrently,
and use the same temporary workspace files, there is nothing to prevent one
job overwriting the workspace files while another job is using them. This can
lead to unpredictable failures.
Therefore, you are advised to devise a naming convention, and operating
procedures, that will avoid this situation. For example, you can use the system
symbolic parameter SYSUID to generate workspace file names that are
unique to an individual user.
These temporary files are deleted before the end of the job.
Input Parameters for DFHWS2SR

These are shown in Example 17-3.
Example 17-3 Input parameters to DFHWS2SR
.-CCSID=Cp037-.
>>-+-------------+--+------------+--+----------------+--------------->
'-CCSID=value-' '-DESC=value-' '-ENCODING=value-'
>----HOSTPORT=scheme://-+-domain name-+-:port number---------------->
'-IP address--'
>--+-------------------------------+--LOCATION=value--LOGFILE=value->
'-KEYSTORE=value-+--------------+
'-KEYPWD=value-'
>--+------------+--+----------------------------------------+------->
'-NAME=value-' +-PROP1NAME=value----PROP1VALUE=value----+
+-PROP2NAME=value----PROP2VALUE=value----+
etc.
+-PROP254NAME=value--PROP254VALUE=value--+
'-PROP255NAME=value--PROP255VALUE=value--'
>--+-----------------------------------+---------------------------->
'-TRUSTSTORE=value-+----------------+
'-TRUSTPWD=value-'
.-VERSION=1-----.
>--+---------------------------------+--+---------------+----------><
'-USERNAME=value-+----------------+ '-VERSION=value-'
'-PASSWORD=value-'
Parameter use
You can specify the input parameters in any order.
839
Each parameter must start on a new line.

A parameter (and its continuation character, if you use one) must not extend
beyond column 72; columns 73 to 80 should contain blanks.
If a parameter is too long to fit on a single line, use an asterisk (*) character at
the end of the line to indicate that the parameter continues on the next line.
Everything (including spaces) before the asterisk is considered part of the
parameter. For example:
LOCATION=/dir/*
placeOrder.wsdl
is equivalent to
LOCATION=/dir/placeOrder.wsdl
A # character in the first character position of the line is a comment character.
The line is ignored.
All keywords and values are case sensitive unless otherwise specified.
Parameter description
CCSID=Cp037|value
The character encoding used to read the WSDL file from z/FS. A list of
character encodings that can be specified is available in the Supported
Encodings topic in the Java manuals. For Java 1.4, the character encodings
are available from:
http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html
DESC=value
The description of the WSDL used by WSRR to set the Description property.
ENCODING=value
The character set encoding of the WSDL document used by WSRR to set the
Encoding property. If ENCODING is not specified, WSRR obtains this value
from the <?xml encoding="encoding_value"> typically found at the beginning
of the WSDL document.
HOSTPORT=scheme://{domain name|IP address}:port number
The URI of the WSRR server. The scheme can be HTTP or HTTPS. The port
number defaults to 80 for the scheme HTTP, and 443 for HTTPS.
KEYSTORE=value
The fully qualified filename of the Keystore file.
KEYPWD=value
840
The password to decrypt the keystore file.

LOCATION=value
The fully qualified filename of the WSDL to publish.
LOGFILE=value
The fully qualified filename into which DFHWS2SR writes its activity log and
trace information. DFHWS2SR creates the file (but not the directory structure)
if it does not already exist. Normally you will not need to use this file, but it
may be helpful to diagnose problems.
NAME=value
The name of the WSDL used by WSRR to set the Name property. If NAME
is not specified, WSRR uses the unqualified filename of the WSDL.
PASSWORD=value
The password to access WSRR.
PROP1NAME=value
WSRR allows for custom properties to be publish along with WSDL
documents. Each custom property has a name and value pair. Up to 255
custom properties can be specified using the format PROPxNAME replacing
x with a numeric between 1 to 255 in ascending order. Duplicate and blank
custom property names should be avoided.
PROP1VALUE=value
The value of a custom property to set in WSRR. Required if PROP1NAME
specified. Similarly, if PROP2NAME is specified, PROP2VALUE is required,
and so on.
TRUSTPWD=value
The password to decrypt the truststore file.
TRUSTSTORE=value
The fully qualified filename of the truststore file.
USERNAME=value
The username to access WSRR, and is used by WSRR to set the Owner
property.
VERSION=1|value
The version number of the WSDL used by WSRR to set the Version
property.
Completion Codes
Table 17-1 on page 842 shows the possible completion codes for DFHWS2SR.
841
Table 17-1 Completion codes for DFHWS2SR

Completion Code
Meaning
OK. The job completed successfully and only Informational

messages have been issued.
Input Error. The job did not complete successfully. One or more
error messages were issued to SYSOUT whilst validating the
input parameters.
input parameters.
12
Error. The job did not complete successfully. One or more error
messages were issued to SYSOUT during execution.
17.5 Publishing WSDL files from CICS to WSRR

This section describes how to use the CWSP transaction provided by the CICS
SupportPac to publish a WSDL document installed as part of a CICS Web
service provider application to WSRR together with optional metadata.
The following diagram (Figure 17-2) illustrates the components involved in this
scenario.
CICS TS V3.1
Input Parameters:
WSRR server location + security
credentials + description + version
WSDL
WSDL
WSDL
CWSP
Transaction
Publish WSDL
to WSRR
WSRR
log
Figure 17-2 Publishing WSDL files from CICS to WSRR

commands is required.
842
Before performing the steps to run the CWSP transaction, the following needs to
be in place:
The CICS system initialization (SIT) parameter LOCALCCSID must be set to
an EBCDIC code page. The default for LOCALCCSID is EBCDIC codepage
037. If a non-EBCDIC code page is specified, CWSP will ABEND AEXZ.
The WSDL document for the CICS Web service provider application needs to
be available to the CICS region, and specified in the applications associated
WEBSERVICE resource in the WSDLFILE parameter. In addition the CICS
default user ID running CWSP requires read permission on for the WSDL
document.
The CICS region needs access to TCP/IP services to send Web services
requests to the WSRR server (HOSTPORT parameter)
17.5.1 Running the CWSP transaction

Perform the following steps to setup and run CWSP:
1. Add the SupportPac load library to the CICS startup
2. Create and install the resource group DFHWSPB
3. Modify the CWSP configuration file
4. Run CWSP and check output messages
Add the SupportPac load library to the CICS startup

Add the dataset hlq.CA1N.LOAD to the CICS module load library (DFHRPL)
concatenation for the CICS regions within which CWSP is going to run.
Create and install the resource group DFHWSPB

The following steps involve using the CICS TS V3.1 supplied DFHCSDUP utility
to update the CICS System Definition (CSD). Alternative methods could be used
for example using the facilities provided by the CEDA transaction or
CICSPlexSM.
1. Modify the JCL template file hlq.CA1N.JCL(DFHWSUP) to:
Update the JOB accounting information.
Update STEPLIB to point to the SDFHLOAD dataset for the CICS TS V3.1
installation.
Update DFHCSD to point to the CSD dataset used by the CICS region in
which CWSP is to be used.
843
Replace all instances of install-directory with the z/FS directory the

SupportPac was installed in to.
Optionally, modify the transient data queue named CWSP if messages
produced by CWSP are to be directed somewhere other than the default
CSSL.
2. Submit the modified JCL to create the CSD group DFHWSPB.
3. Install the CSD group DFHWSPB, for example by adding the group to your
CICS startup LIST.
Modify the CWSP configuration file

Modify the template configuration file,
/install-directory/samples/dfhwspb.config, to specify the location of the
WSRR server, access credentials, and other information to be published with
WSDL files.
See CWSP configuration file on page 845 for details of the valid parameters.
Run CWSP and check output messages

User ID under which the CWSP transaction runs requires the authority to use the
CICS SPI. The CWSP uses SPI commands to dynamically create a
DOCTEMPLATE as a means of retrieving the WSDL document from z/FS.
To publish all installed CICS Web service provider applications to WSRR, run
CWSP with no parameters.
To publish a single CICS Web service provider application to WSRR, run CWSP
specifying the WEBSERVICE resource name as a parameter. This parameter is
case sensitive. If you need to alter the upper casing options on your terminal, use
the CEOT transaction provided by CICS. For example see Example 17-4:
Example 17-4 CWSP output messages
CWSP TEST
Complete -
1 published
CWSP writes output messages to the CWSP transient data queue. By default is
redirected to the CSSL which can typically be viewed by viewing the CICS JOB
output in JES. Example 17-5 is an except from publishing CICS Web service
provider to WSRR.
Example 17-5 CICS JOB output
27/09/06 11:12:20 DFHWSPB has started
844
27/09/06 11:12:20 Server location is

https://wsrr.my-example.server:9443
DFHCA5510 W 27/09/2006 11:12:19 IYCQST20 IYCQTC50 CWSP DOCTEMPLATE
names beginning with DFH are reserved and may be redefined by CICS.
DFHDH0105 27/09/2006 11:12:19 IYCQST20 Document template definition
DFH00048 has been added as HFSFILE(/u/ca1n/wsdl/myservice1.wsdl) with
template name DFH00048.
TC50 CWSP CTSQ01D 27/09/06 11:12:19 CREATE DOCTEMPLATE(DFH00048)
TEMPLATENAME(DFH00048) HFSFILE(/u/ca1n/wsdl/myservice1.wsdl)
APPENDCRLF(YES) TYPE(BINARY)
DFHDH0106 27/09/2006 11:12:19 IYCQST20 Document template definition
DFH00048 has been deleted.
27/09/06 11:12:20 Starting to publish TEST
27/09/06 11:12:28 WSDL published for TEST
27/09/06 11:12:28 DFHWSPB has finished
CWSP configuration file

Parameter use:
A parameter cannot span more than one line.
Parameter can be delimited by a comma , or carriage return or line feed.
Configuration parameters for CWSP

Example 17-6 shows the possible configuration parameters for CWSP.
Example 17-6 CWSP configuration parameters
.-----------------.
v
|
>>--+-------------+-+--+------------+--+----------------+----------->
'-aName=value-'
'-DESC=value-'
'-ENCODING=
>----HOSTPORT=scheme://-+-domain name-+-:port number---------------->
'-IP address--'
.-VERSION=
>--+-----------------------------------+--+---------------+--------><
'-USERNAME=value--+-----------------+ '-VERSION=
845
'-PASSWORD=value-'
aName=value
WSRR allows for custom properties to be published along with WSDL
documents. Each custom property has a name and value pair. Up to 255
name and value pairs can be specified. Duplicate and blank custom property
names should be avoided.
An example aName=value is Publisher=CICS SupportPac CA1N
DESC=value
The description of the WSDL used by WSRR to set the Description property.
ENCODING=value
The character set encoding of the WSDL document used by WSRR to set the
Encoding property. If ENCODING is not specified, WSRR obtains this value
from the <?xml encoding="encoding_value"> typically found at the beginning
of the WSDL document.
The URI of the WSRR server. The scheme can be HTTP or HTTPS. The port
number defaults to 80 for the scheme HTTP, and 443 for HTTPS.
PASSWORD=value
USERNAME=value
The username to access WSRR, and is used by WSRR to set the Owner
property.
VERSION=1|value
The version number of the WSDL used by WSRR to set the Version
property.
An example CWSP configuration file is shown in Example 17-7.
Example 17-7 Example CWSP configuration file
DESC=A description for all the webservices being published

VERSION=1
HOSTPORT=https://wsrr.my-example.server:9443
USERNAME=wsrrusername
PASSWORD=wsrrpassword
ENCODING=UTF-8
Host=IBM CICS Transaction Server
846
Publisher=CICS SupportPac CA1N
17.6 Retrieving WSDL files from WSRR using z/OS

batch
This section describes how to use the z/OS cataloged procedure DFHSR2WS
provided by the CICS SupportPac to read a WSDL document stored in WSRR
and place a copy of it on z/FS.
If you need to create high level language structures (copybooks) from the WSDL
document, use the DFHWS2LS procedure provided with CICS TS V3.1.
It is possible to call DFHSR2WS followed by DFHWS2LS within the same z/OS
batch JCL to keep the copybooks, WSBind and WSDL on z/FS in step with the
WSDL stored in WSRR. To keep the CICS application which makes use of the
generated copybooks would take additional steps. Figure 17-3 illustrates the
components involved in this scenario.
z/OS Batch JCL

Input Parameters:
WSDL unique token, WSRR
server location + security
credentials
Input Parameters:
Language, container, end of URI,
Provider Application Name, etc...
DFHSR2WS
.
Read from WSRR
WSRR
.
.
.
.
.
DFHWS2LS
Build Language
.
Structure(s) & WSBIND
file from. WSDL
.
WSDL
WSBind
Output
Input
log
Language
Structures
Figure 17-3 Reading WSDL files stored in WSRR from z/OS batch

commands and the Java configuration on your system is required.
847
The userid under which the DFHWS2SR procedure is run will need authority to:
read files from the SupportPac bin directory (WORKDIR symbolic parameter)
read files from the Java product directories (JAVADIR symbolic parameter)
optionally, read the trust store and key store files (TRUSTSTORE and
KEYSTORE parameters)
write the WSDL file to z/FS (LOCATION parameter)
write access to the temporary directory (TMPDIR symbolic parameter)
write access the log file (LOGFILE parameter)
access to TCP/IP services to send Web services requests to the WSRR
server (HOSTPORT parameter)
17.6.1 Running DFHSR2WS

To run the DFHSR2WS procedure you need to write JCL that includes symbolic
parameters and input parameters.
1. Customize the template JCL provided in hlq.CA1N.JCL(WSDLREAD) using
information in the 17.6.2, Job control statements for DFHSR2WS on
page 850.
2. Submit the JCL.
3. If there are errors reported in the JCL output, check the z/FS log file specified
by the LOGFILE parameter for detailed error messages.
Example 17-8 shows a customized version of hlq.CA1N.JCL(WSDLREAD).
Example 17-8 Customized version of hlq.CA1N.JCL(WSDLREAD)
//WSDLREAD JOB (MYSYS,AUSER),MSGCLASS=H,

// CLASS=A,NOTIFY=&SYSUID,REGION=0M
//WSDLREAD JCLLIB ORDER=(CICS.CICSTS.CA1N.JCL)
// EXEC DFHSR2WS,
// JAVADIR='java/IBM/J1.4',
// WORKDIR='/usr/lpp/cicsts/ca1n',
// TMPDIR='/u/username/tmp',
// TMPFILE='SR2WS'
//INPUT.SYSUT1 DD *
LOGFILE=/u/username/tmp/SR2WS.log
LOCATION=/u/username/tmp/placeOrder.wsdl
HOSTPORT=https://wsrr.my-example.server:9443
848
USERNAME=wasadmin
PASSWORD=password
KEYSTORE=/u/username/DummyClientKeyFile.jks
KEYPWD=wasadm1n
TRUSTSTORE=/u/username/DummyClientTrustFile.jks
TRUSTPWD=wasadm1n
WSDLID=WSRR--c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a
*/
Example 17-9 is an extract from the log file created by the DFHSR2WS after
submitting the example JCL above.
Example 17-9 Log extract after running customized version of
hlq.CA1N.JCL(WSDLREAD)
Value of 'LOCATION' is '/u/username/tmp/placeOrder.wsdl'.

Value of 'LOGFILE' is '/u/username/logread'.
Value of 'HOSTPORT' is 'https://wsrr.my-example.server:9443'.
Value of 'USERNAME' is 'wasadmin'.
Value of 'PASSWORD' is '********'.
Value of 'WSDLID' is
'WSRR--c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a'.
Value of 'KEYSTORE' is '/u/username/DummyClientKeyFile.jks'.
Value of 'KEYPWD' is '********'.
Value of 'TRUSTSTORE' is '/u/username/DummyClientTrustFile.jks'.
Value of 'TRUSTPWD' is '********'.
Starting read of WSDL document from WSRREndpoint
[https://wsrr.my-example.server:9443/WSRRCoreSDO/services/WSRRCoreSDOPo
rt]
getRequest [<soapenv:Envelope
soapenv:Body><p828:retrieveWithDepth
p828:bsrURI>WSRR--c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a</p8
28:bsrURI><p828:depth>0</p828:depth></p828:retrieveWithDepth></soapenv:
Body></soapenv:Envelope>]
getResponse [<soapenv:Envelope
soapenv:Body><p244:retrieveWithDepthResponse
849
sdo:datagraph xmlns:sdo="commonj.sdo"
xmlns:sdo_1="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/sdo">
<changeSummary logging="true" xmlns=""/>
<sdo_1:WSRR>
<sdo_1:root>WSRR--c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a</sd
o_1:root>
<sdo_1:artefacts xsi:type="sdo_1:WSDLDocument" bsrURI="WSRR-c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a" description="Dan
Desc" lastModified="1159360105251" name="placeOrder"
namespace="http://www.WEBPROV.WEBPROVI.com" owner="wasadmin"
version="3"
content="
...
=" encoding="UTF-8" location="/u/username/wsdl/myservice1.wsdl">
<sdo_1:userDefinedProperties name="three" value="four"/>
<sdo_1:userDefinedProperties name="one" value="two"/>
<sdo_1:xsdTargetNamespaces>http://www.WEBPROV.WEBPROVI.Request.com</sdo
_1:xsdTargetNamespaces>
<sdo_1:xsdTargetNamespaces>http://www.WEBPROV.WEBPROVI.Response.com</sd
o_1:xsdTargetNamespaces>
</sdo_1:artefacts>
</sdo_1:WSRR>
</sdo:datagraph>
</p244:retrieveWithDepthResponse></soapenv:Body></soapenv:Envelope>]
Program 'DFHSR2WS' completed SUCCESSFULLY.
17.6.2 Job control statements for DFHSR2WS

JOB
Initiates the job.
EXEC
Specifies the procedure name (DFHSR2WS).
DFHSR2WS requires sufficient storage to run Java virtual machine (JVM).
You are advised to specify REGION=0M on the EXEC statement.
INPUT.SYSUT1 DD
Specifies the input. The input parameters are usually specified in the input
stream.
However, they can be defined in a data set, or in a member of a partitioned
data set.
850
Symbolic parameters
The following symbolic parameters are defined in cataloged procedure
DFHSR2WS:
JAVADIR=path
Specifies the name of the Java directory that is used by DFHSR2WS. The
value of this parameter is appended to /usr/lpp/ giving a complete path name
of /usr/lpp/path
TMPDIR=tmpdir
Specifies the location of a directory in z/FS that DFHSR2WS uses as a
temporary work space. The user ID under which the job runs must have read
and write permission to this directory.
The default value is /tmp
TMPFILE=tmpprefix
Specifies a prefix that DFHSR2WS uses to construct the names of the
temporary workspace files.
The default value is SR2WS
WORKDIR=path
Specifies the location of the directory in z/FS in which the SupportPac was
installed. The user ID under which the job runs must have read permission to
this directory.
The temporary work space

DFHWS2SR creates the following three temporary files during execution:
tmpdir/tmpprefix.in
tmpdir/tmpprefix.out
tmpdir/tmpprefix.err
Where:
tmpdir is the value specified in the TMPDIR parameter
tmpprefix is the value specified in the TMPFILE parameter.
The default names for the files (when TMPDIR and TMPFILE are not specified),
are:
/tmp/SR2WS.in
/tmp/SR2WS.out
/tmp/SR2WS.err
851
Important: DFHSR2WS does not lock access to the generated HFS file
names. Therefore, if two or more instances of DFHSR2WS run concurrently,
and use the same temporary workspace files, there is nothing to prevent one
job overwriting the workspace files while another job is using them. This can
lead to unpredictable failures.
Therefore, you are advised to devise a naming convention, and operating
procedures, to avoid this situation. For example, you can use the system
symbolic parameter SYSUID to generate workspace file names that are
unique to an individual user.
These temporary files are deleted before the end of the job.
Input parameters for DFHSR2WS

These are shown in Example 17-10.
Example 17-10 Input parameters for DFHSR2WS
.-CCSID=Cp037-.
>>-+-------------+--HOSTPORT=scheme://-+-domain name-+-:port number-->
'-CCSID=value-' '-IP address--'
>--+-------------------------------+--LOCATION=value--LOGFILE=value-->
'-KEYSTORE=value-+--------------+
'-KEYPWD=value-'
>--+-----------------------------------+----------------------------->
'-TRUSTSTORE=value-+----------------+
'-TRUSTPWD=value-'
>--+---------------------------------+--WSDLID=value----------------><
'-USERNAME=value-+----------------+
'-PASSWORD=value-'
Parameter use
Each parameter must start on a new line.
If a parameter is too long to fit on a single line, use an asterisk (*) character at
the end of the line to indicate that the parameter continues on the next line.
Everything (including spaces) before the asterisk is considered part of the
parameter.
For example:
852
LOCATION=/dir/*
placeOrder.wsdl
This is equivalent to:
LOCATION=/dir/placeOrder.wsdl
A # character in the first character position of the line is a comment character.
The line is ignored.
CCSID=Cp037|value
The character encoding used to write the WSDL file to z/FS. A list of
character encodings that can be specified is available in the Supported
Encodings topic in the Java manuals. For Java 1.4, the character encodings
are available from:
http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html
URI of the WSRR server. The scheme should be HTTP or HTTPS. The port
number defaults to 80.
KEYSTORE=value
Only required if the scheme specified in HOSTPORT is HTTPS. Fully
qualified filename of the Keystore file.
KEYPWD=value
The password to decrypt the keystore file.
LOCATION=value
Fully qualified filename for the WSDL document read from WSRR.
DFHSRWS creates the file (but not the directory structure) if it does not
already exist.
LOGFILE=value
The fully qualified filename into which DFHSR2WS writes its activity log and
trace information. DFHSR2WS creates the file (but not the directory structure)
if it does not already exist. Normally you will not need to use this file, but it
may be helpful to diagnose problems.
PASSWORD=value
853

TRUSTPWD=value
The password to decrypt the truststore file.
TRUSTSTORE=value
The fully qualified filename of the truststore file.
USERNAME=value
The username to access WSRR.
WSDLID=value
The unique WSRR document ID (also known as the bsrURI). The bsrURI for
a WSDL document is shown in WSRR Web interface by viewing its Custom
Properties.
Completion code
Table 17-2 shows the possible completion codes for DFHSR2WS.
Table 17-2 Completion codes for DFHSR2WS
Completion Code
Meaning
OK. The job completed successfully and only Informational

messages have been issued.
input parameters.
input parameters.
12
Error. The job did not complete successfully. One or more error
messages were issued to SYSOUT during execution.
17.7 Security considerations

When the HTTPS transport is used, SSL needs to be configured between either
the z/OS batch utilities or CICS and WSRR.
17.7.1 Configuring SSL between the z/OS batch utilities and WSRR
The z/OS batch utilities require a key store and a trust store to be provided.
These can be created using a key configuration program such as ikeyman.
854
WebSphere Application Server which hosts WSRR provides some sample key
stores called DummyClientKeyFile.jks, DummyServerKeyFile.jks, and trust
stores called DummyClientTrustFile.jks and DummyServerTrustFile.jks. These
can be used as-is for testing the z/OS batch utilities with WSRR by specifying the
client key and trust files in the z/OS batch utilities and the server key and trust
files in WebSphere. As the keys in these stores are shipped with WebSphere,
they should be replaced.
As an example of using self-signed certificates, you could change the keys by
opening the client key file using ikeyman, delete the websphere dummy client
certificate and create a new self-signed certificate. Then extract the certificate
and add it into the server's trust file. Next, open the servers' key file, delete the
websphere dummy server certificate and create a new self-signed certificate,
then extract the certificate and add it into the client's trust file. The client and
server will then be able to use SSL with the new certificates.
17.7.2 Configuring SSL between CICS and WSRR

If the WebSphere Application Server within which WSRR is running is configured
to use global security, CICS needs to interact with WSRR via HTTPS. When the
HTTPS transport is used, SSL needs to be configured between CICS and
WSRR. The configuration for CICS is done through RACF.
As an example using self-signed certificates, a digital certificate and
public/private key pair must be created in RACF for the user ID the CICS region
runs under. This certificate must then be appended to a keyring in RACF as the
default certificate. The keyring is specified to the CICS region through the
KEYRING SIT parameter. The certificate should also be extracted and added to
the WebSphere trust store. The relevant certificate from the WAS key file should
be extracted and added to the keyring in RACF that is specified in the CICS SIT
parameter.
For more information, refer to the CICS TS V3.1 documentation - topic
Configuring CICS to use SSL:
http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/topic/com.ibm.c
ics.ts31.doc/dfht5/topics/dfht560.htm
Or, refer to the WebSphere Application Server documentation on Secure
Sockets Layer:
websphere.base.doc/info/aes/ae/csec_ssl.html
855
856
Part 5
Part
Appendixes
857
858
Appendix A.
IBM product descriptions

This appendix provides a brief description of the IBM products used within each
phase of the SOA lifecycle for the SOA scenarios.
The appendix is organized into the following sections:
IBM products used to model on page 860
IBM products used to assemble on page 862
IBM products used to deploy on page 866
IBM products used to manage on page 869
859
IBM products used to model

This section includes a brief product description as well as a reference to more
detailed information for the following IBM products used to model within the SOA
lifecycle:
WebSphere Business Modeler on page 860
Rational Software Architect on page 860
Rational Data Architect on page 861
WebSphere Business Modeler

IBM WebSphere Business Modeler, known as Modeler, is targeted at Business
Analysts to help you capture your business design. You can use Modeler for
documentation and compliance purposes: providing a visual and textual
representation of your processes, organization, resources, collaborations and
business measurements. You can import any static diagrams that you have
created previously in Microsoft Visio. Modeler includes a simulation tool with
which you can analyze your processes and test how well your processes will hold
up under different operating assumptions. You can use this analysis to refine and
optimize your business design. Modeler is built on the Eclipse tool framework
making it easy for you to share information about your business design with other
parts of your organization and tools. In particular, you can export your design into
WebSphere Integration Developer and Rational Software Architect so that your
application developers can use that as a blueprint for designing process flows for
automating your business design.
More information about IBM WebSphere Business Model can be found here:
http://www.ibm.com/software/integration/wbimodeler/
Rational Software Architect

IBM Rational Software Architect is an Eclipse based UML and Java integrated
design and development tool that leverages model-driven development for
creating well-architected applications and for building services in a serviceoriented architecture (SOA). It also includes the J2EE development tooling found
in IBM Rational Application Developer.
With Rational Software Architect you can unify all aspects of software design and
development.
860
Develop applications and Web services more productively than ever

Exploit the latest in modeling language technology
Review and control the structure of Java and service-oriented applications
Leverage an open and extensible modeling platform
Simplify your design and development tool solution
Integrate with other facets of the lifecycle
Rational Software Architect supports UML 2.0 for analysis and design using Use
Case, Class, Sequence, Activity, Composite Structure, State Machine,
Communication Component and Deployment diagrams. It supports UML class
diagram editing for Java, Enterprise Java Beans and Database objects. As well
as supporting full features of UML, it provides many additional capabilities.
Rational Software Architect is useful for turning the output of WebSphere
Modeler into service specifications and component-detailed designs that you can
then hand over to software developers for implementation.
Rational Software Architect has support for plugging in design patterns that help
automate development and promote re-use. It comes already populated with the
classic patterns described in Design Patterns: Elements of Reusable ObjectOriented Software by Erich Gamma, et al [GAMMA]. You can obtain other
predefined patterns or create your own to capture specific design practices that
you use commonly throughout your software.
More information about IBM Rational Software Architect can be found here:
http://www.ibm.com/software/awdtools/architect/swarchitect/features/
index.html
Rational Data Architect

IBM Rational Data Architect helps data architects model, visualize, relate, and
develop data assets to understand data assets and their relationships to each
other, accelerate new or composite application development, reuse prior design
and development investments, and assess and manage schema changes. Built
with integration challenges in mind, it combines traditional data modeling
capabilities with metadata discovery, mapping, and analysis, and creates
integrated and abstracted views and deploys them directly onto WebSphere
Information Integrator accelerating value delivery. It plugs into the Eclipse
modeling framework, and provides full lifecycle design, development and
debugging for database schema, SQL, and Java-based procedures, triggers, and
functions.
More information about IBM Rational Data Architect can be found on this Web
site:
http://www.ibm.com/software/data/integration/rda/
Appendix A. IBM product descriptions
861
IBM products used to assemble

detailed information for the following IBM products used to assemble within the
SOA lifecycle:
Rational Application Developer on page 862

CICS Web Services Assistant on page 863
WebSphere Developer for zSeries on page 864
Bowstreet Portlet Factory on page 865
WebSphere Integration Developer on page 865
Rational Application Developer

IBM Rational Application Developer is an Eclipse based integrated development
environment for constructing, testing, assembling, deploying and debugging
applications that are built with Java/J2EE, Web Services and many other open
standards.
Rational Application Developer is optimized for IBM WebSphere software, but
also supports non-IBM run-time environments, such BEA WebLogic and JBOSS.
IBM Rational Application Developer for WebSphere Software is powered by the
Eclipse open source platform so developers can adapt and extend their
development environment to match their needs and increase their productivity.
When used with the IBM Software Development Platform, developers can access
a broad range of requirements and change-management functions directly from
Rational Application Developer for WebSphere Software. Some key features and
benefits are:
Accelerate portal, SOA and J2EE using RAD tools and wizards.
Leverage existing skills and shorten the Java learning curve with
drag-and-drop UI components and point-and-click database connectivity.
Improve code quality with automated tools for applying coding standard
reviews, component and Web Service unit testing and multi-tier runtime
analysis.
Integrate your business applications with interoperable Web services and
service-oriented architectures.
Visualize and graphically edit code through the UML Visual Editor for Java
and EJB.
Collaborate and share assets across the team using built-in IBM Rational
ClearCase LT version control.
Adapt and extend your development environment with Eclipse-based plug-ins
to match your needs.
862
Quickly build and deploy interactive reports using drag-and-drop UI

components and Crystal Reports.
More information about IBM Rational Application Developer can be found here:
http://www.ibm.com/software/awdtools/developer/application/index.htm
l
CICS Web Services Assistant

The CICS Web Services Assistant, included with IBM CICS Transaction Server
V3.1, is a set of batch utilities used to create Web Services for CICS applications,
as well as enable CICS applications to invoke Web Services.
The CICS Web services assistant provides two utility programs:
DFHLS2WS: This utility is used to generates a Web Service binding file from
a language structure. It can also be used to generates a Web Service
description.
DFHWS2LS: This utility is used to generate a Web Service binding file from a
Web service description. It can also generate a language structure that you
can use in your application programs.
The assistant supports rapid deployment of CICS applications for use by service
providers and service requesters, with the minimum of programming effort. When
using the CICS Web Services Assistant, you do not have to write your own code
for parsing inbound messages and for constructing outbound messages; CICS
maps data between the body of a SOAP message and the application programs
data structure.
In most cases, CICS can generate and install the resource definitions
automatically. You do have to define PIPELINE resources, but in many cases you
can use one of the pipeline configuration files provided with CICS
(basicsoap11provider.xml, basicsoap11requester.xml).
The assistant can create a WSDL document from a simple language structure, or
a language structure from an existing WSDL document, and supports COBOL,
C/C++, and PL/I. However, the assistant cannot deal with every possibility, and
there will be times when you will need to take a different approach.
If you decide not to use the CICS Web Services Assistant, you will have to:
Provide your own code or parsing inbound messages and constructing
outbound messages (unless you use WebSphere Developer).
Provide your own pipeline configuration file.
Define and install your own URIMAP and PIPELINE resources.
863
More information about IBM CICS Transaction Server V3.1, Web Services
Assistant can be found at this Web site:
http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp
WebSphere Developer for zSeries

WebSphere Developer for zSeries V6.0.1, is built upon the Rational Software
Developer Platform (Eclipse based), facilitates the development of both Java and
z/OS-based applications. WebSphere Developer contains tools that support the
development of Web services and the XML enablement of existing CICS COBOL
applications.
The XML Services for the Enterprise (XSE) capability of WebSphere Developer
provides tools that let you adapt COBOL-based applications so that they can
consume and produce XML messages. XSE supports the creation of driver
programs that work with existing CICS (or IMS) applications.
The Web Services Enablement wizard is the XSE tool that supports the
bottom-up approach for creating Web services based on existing CICS COBOL
programs. It takes as input the COMMAREA copybook. The XML structure and
data types are then derived from the COBOL data declarations. Based on these,
the Web Services Enablement wizard generates the set of artefacts.
Tip: Building the ultimate CICS development and unit test environment
The combination of WebSphere Developer for zSeries V6.0.1 and the bundled
CICS Transaction Server for WebSphere Developer test environment, and the
CICS Transaction Gateway V6.0.2, provides an incredible powerful
environment to develop by direct exposure and indirect exposure Web
Services for CICS.
We recommend that you refer to the following article on IBM developerWorks
for information about building this CICS development and test environment:
http://www.ibm.com/developerworks/websphere/library/techarticles/0509_barosa
/0509_barosa.html
IBM WebSphere Developer for zSeries V6.0.1 prerequisites are:

IBM Rational Application Developer or Rational Software Architect V6.0.1.1
+ EGL feature must be pre-installed
WebSphere Developer for zSeries CD images (disks) 1-4 are required, and
CD 5 includes the CICS Transaction Server for WebSphere Developer test
environment
The CICS Transaction Gateway V6.0.1 (or V6.0.2) is a separate CD image.
864
More information about IBM WebSphere Developer for zSeries V6 can be found
here:
http://www.ibm.com/software/awdtools/devzseries/
Bowstreet Portlet Factory

Now acquired by IBM, Bowstreet Portlet Factory for WebSphere is a
development technology that accelerates the development, customization,
deployment and maintenance of portlets for WebSphere Portal. With Bowstreet
Portlet Factory, Bowstreet for short, developers can quickly and easily repurpose
a company's core assets, automatically assembling them into custom, high-value
portlets. These portlets can then be deployed into WebSphere Portal.
The Bowstreet solution is built on open standards and supports Java, J2EE, XML
and JSR 168. Bowstreet speeds up portlet development through dynamic
generation of code which can be quickly modified by business users. It can
rapidly generate portlets for existing systems such as Domino, Siebel, SAP,
PeopleSoft, Hyperion and many others. The portlets created can automatically
present themselves as standalone Web applications, Web services or portlets
based on JSR 168 specification without requiring any coding of assets.
WebSphere Integration Developer

IBM WebSphere Integration Developer (WID) is also an Eclipse based tool
designed to help create business process flows, state machines and business
rules.
WebSphere Integration Developer V6.0 simplifies integration with its Service
Component Architecture (SCA). SCA uses Business Process Execution
Language for assembling business process tasks into workflows, which can then
be deployed to IBM WebSphere Process Server.
WebSphere Integration Developer can directly import business models from the
IBM Business Modeler. You can then use a wiring editor for assembling service
components, for importing service interface definitions and for setting binding
policies to build SOA enabled applications.
More information about IBM WebSphere Integration Developer can be found
here:
http://www.ibm.com/software/integration/wid/
865
IBM products used to deploy

detailed information for the following IBM products used to deploy within the SOA
lifecycle:
WebSphere Application Server Network Deployment on page 866

WebSphere Enterprise Service Bus on page 867
WebSphere Message Broker on page 867
WebSphere Portal on page 868
WebSphere Process Server on page 868
WebSphere Information Integration Server on page 869
WebSphere Application Server Network Deployment

IBM WebSphere Application Server Network Deployment serves two roles within
the SOA Foundation. It is the hosting environment for basic SOA business
services primarily those implemented with J2EE Enterprise JavaBeans
(EJBs). These services can be exposed with WSDL and integrated through
standard Web service protocols and encodings, or can be integrated in a more
tightly coupled fashion through Remote Method Invocation/InterORB Protocol
(RMI/IIOP) bindings.
WebSphere Application Server also serves as the underlying execution platform
for WebSphere Portal, WebSphere Process Server, WebSphere Enterprise
Service Bus, and a variety of other offerings within the IBM portfolio. This
foundational role enables these products to be tightly integrated (albeit hosting a
set of loosely-coupled service artefacts) with a common approach to installation,
clustering, scaling, administration, service and security.
WebSphere Application Server is offered in a variety of flavors, including a very
compact and simple platform for J2EE applications based on Apache Geronimo,
the WebSphere Community Edition (CE); WebSphere Application Server Base
Edition is a standalone, single server application server that provides full
run-time support for J2EE V1.4 and Web services.
A customized variant packaged with tooling and targeted specifically at the ISV
community that serves the small and medium business marketplace, the
WebSphere Application Server Express Edition and a scalable version that
supports clustering, dynamic fail-over, and a centralized administration model,
the WebSphere Application Server Network Deployment Edition (ND).
WebSphere Extended Deployment (XD) builds on the capabilities of WebSphere
ND and offers a dynamic goals-directed, high performance environment for
running mixed application types and workload patterns in WebSphere.
866
More detailed information about IBM WebSphere Application Server family can
be found at this Web site:
http://www.ibm.com/software/webservers/appserv/was/
More detailed information about IBM WebSphere Application Server Network
Deployment Edition can be found at this Web site:
http://www.ibm.com/software/webservers/appserv/was/network/

IBM WebSphere Enterprise Service Bus provides Web services connectivity,
JMS messaging and service-oriented integration for SOA. It instantiates the
enterprise service bus architectural pattern, providing for a basic fabric for
transparent interconnection of services across an enterprise distributed network.
The WebSphere Enterprise Service Bus includes support for service bus
mediations for reconciling different types of connectivity, including support for
transformation of service requests, content based routing and constructing
side-logging for auditing or traceability purposes.
WebSphere Enterprise Service Bus is optimized to operate on service requests
that have been bound using SOAP encodings and context processing semantics.
It supports a variety of binding transports, including HTTP, the default embedded
JMS message provider in WebSphere Application Server, and WebSphere MQ.
More information about IBM WebSphere Enterprise Service Bus can be found
here:
http://www.ibm.com/software/integration/wsesb/

IBM WebSphere Message Broker delivers an advanced Enterprise Service Bus
providing connectivity and universal data transformation for both standard and
non-standards-based applications and services.
WebSphere Message Broker enhances the WebSphere Enterprise Service
Busby by providing support for message transformation support for non-XML
message types such AL3, HL7, Swift, HIPAA and EDI. WebSphere Message
Broker provides optional support for DataStage TX for complex message
transformations. It also has built-in support to help you implement complex event
processing without programming.
WebSphere Message Broker has its roots in message-based integration, a form
of business composition and hub-centered mediation that predated the latest
standards for SOA. While it is reasonable to think of WebSphere Message Broker
as extending the capabilities of WebSphere Enterprise Service Bus, most often it
867
will be appropriate to use them together in a bridged interconnection, leveraging

the abilities of WebSphere Message Broker to provide interconnection with
non-XML based services, native interconnectivity with CICS and IMS, and for
those cases where you need complex event processing and transformation, and
then using WebSphere Enterprise Service Bus to optimize your interconnectivity
between XML and standard SOA-based services.
More information about IBM WebSphere Message Broker can be found here:
http://www.ibm.com/software/integration/wbimessagebroker/
WebSphere Portal
IBM WebSphere Portal delivers a single point of personalized interactions with
applications, content, processes and people.
WebSphere Portal is a hosting environment for the user interaction logic of your
SOA application. More than that, the Portal server provides a platform on which
multiple service user interfaces can be aggregated on a single user page within a
layout template defined by the business. This provides for a unique combination
of structured layout and freedom for end users to customize the content they find
most important to getting their job done.
In addition, portlets rendered within the page layout can be configured with
published properties that when managed through the WebSphere Portals built-in
property broker can be used to create visual integration between the services
rendered by each of those Portlets. In effect, WebSphere Portal offers the
enterprise user the ability to form a customized visual composition of business
services.
WebSphere Portal is built on the J2EE and Web Services foundations provided
by WebSphere Application Server. WebSphere Portal enables rapid assembly of
application artefacts via the portlets.
More information about IBM WebSphere Portal can be found here:
http://www.ibm.com/software/genservers/portal/

IBM WebSphere Process Server is the primary hosting environment for business
processing. Built on WebSphere Enterprise Service Bus, WebSphere Process
Server includes support for both BPEL based process flows as well as business
state machines. WebSphere Process Server also supports the integration of
business rules in process and service selection. The Process Server is the first
product within the IBM suite to offer direct support for the Service Component
Architecture SOA programming model.
868
WebSphere Process Server integrates with WebSphere Portal to deliver

business process management through a portal there is support for human
tasks within a business process. Human tasks are defined as activities within the
process definition that will be carried out by human end-users. This includes
built-in support for task assignment, pick-lists, scheduling and escalation policies
in case a task is not processed in a timely fashion.
More information about IBM WebSphere Process Server can be found here:
http://www.ibm.com/software/integration/wps/
WebSphere Information Integration Server

IBM WebSphere Information Integration server is design specifically to enable
information integration services as defined by the SOA Foundation. It provides
composition of data from a variety of underlying data sources, enabling you to
compose views on data that match the information needs of our composed
business services. WebSphere Information Integration server can be used to
build views, set import and caching strategies, and virtualize the schema of
multiple, heterogeneous data systems into a homogenized relational type
system. For example, you can combine data from IMS DL/I, VSAM, DB2 and
Oracle databases to build a view on that joined data that appears to your
application as though it is all coming from a single relational database.
More detailed information about WebSphere Information Server can be found at
this Web site:
http://www.ibm.com/software/data/integration/db2ii/
IBM products used to manage

detailed information for the following IBM products used to manage within the
SOA lifecycle:
WebSphere Business Monitor on page 869

Tivoli Composite Application Manager for SOA on page 870
Tivoli OMEGAMON XE for Messaging on page 870
Tivoli Access Manager on page 871
Tivoli Federated Identity Manager on page 872
WebSphere Business Monitor

IBM WebSphere Business Monitor enables you to monitor business processes in
real-time, providing a visual display of business process status.
869
WebSphere Business Monitor the compliment to WebSphere Business Modeler.

It helps you create dashboards for visualizing the performance of your business
based on the key performance indicators that you identified in your business
design. You can use this to track time, cost and resources used within your
processes. WebSphere Business Monitor provides tools to let you set situational
triggers and notifications to bring your attention to potential bottlenecks or
workload imbalances in your business.
Ultimately WebSphere Business Monitor helps you better understand how your
business design achieves your business objectives, and provides guidance on
how to refine and optimize that business design in the case your goals are not
being met.
More information about IBM WebSphere Business Monitor can be found here:
http://www.ibm.com/software/integration/wbimonitor/
Tivoli Composite Application Manager for SOA

IBM Tivoli Composite Application Manager (ITCAM) offering is designed
specifically to enable IT service management. It has been designed to
understand the unique semantics and loosely coupled characteristics of serviceoriented architecture (SOA) based services. ITCAM has three editions that are
relevant directly to the SOA Foundation: ITCAM for WebSphere, ITCAM for SOA,
and ITCAM for Response Time Tracking. These cover the gamut from application
server monitoring and resource consumption, deep-dive diagnostics and
correlation as service invocations cascade across multiple systems, and service
level response times and problem isolation.
Tivoli Composite Application Manager for SOA utilizes the foundation services of
Tivoli Enterprise Monitoring Services.
More information about IBM Tivoli Composite Application Manager can be found
at:
http://www.ibm.com/software/tivoli/solutions/application-management/
Tivoli OMEGAMON XE for Messaging

IBM Tivoli OMGEGAMON XE for Messaging is part of the Tivoli monitoring
products suite.
Tivoli OMEGAMON product came as part of the Candle acquisition by IBM. It
helps you to:
Improve WebSphere MQ, Message Broker, MQ Integrator and InterChange
Server Availability
Identify common problems and automate corrective actions.
870
Auto-discovery and immediate monitoring of complex environments

Drill-down to locate a problem, identify the root cause and resolve
bottlenecks or outages
Proactively Prevent Problems
Correctly configure and deploy your WebSphere MQ infrastructure
Detect and repair problems as they happen, or alert you to an imminent
concern
Provides key MQ and Message Broker metrics for real-time and historical
data analysis
Simplify Management with a Single Tool
Manages WebSphere MQ, Message Broker, MQ Integrator and
InterChange Server in distributed and mainframe environments
User-customized displays including business, platform and resource views
More information about IBM Tivoli OMEGAMON XE can be found at this Web
site:
http://www.ibm.com/software/tivoli/products/omegamon-xe-websphere-bu
s-int/

Tivoli Access Manager for e-business is a versatile solution for authentication
and authorization problems. Primarily focused on Web applications, Access
Manager implementations vary from simple Single Sign-on (SSO) to more
complex security infrastructure deployments.
Tivoli Access Manager for e-business can help you manage growth and
complexity, control escalating management costs, and address the difficulties of
implementing security policies across a wide range of Web and application
resources. It works by centrally managing security and audit policy for
enforcement points that can be placed as a proxy in front of Web applications, or
through authorization and authentication plugins direct into a Web server or
application-server environment. You can use Tivoli Access Manager to control
wired and wireless access to applications and data to help bar unauthorized
users. For authorized users, Tivoli Access Manager integrates with Web
applications and servers to deliver a secured and unified business experience. It
helps you secure access to business-critical applications and data spread across
the extended enterprise, allowing highly available, scalable transactions with
partners, customers, suppliers, and employees.
871
More information about IBM Tivoli Access Manager can be found at this Web
site:
http://www.ibm.com/software/tivoli/products/access-mgr-e-bus/
Tivoli Federated Identity Manager

IBM Tivoli Federated Identity Manager provides a simple, loosely-coupled model
for managing identity and access to resources that span companies or security
domains. Rather than replicate identity and security administration at both
companies, IBM Tivoli Federated Identity Manager provides a simple model for
managing identities and providing them with access to information and services
in a trusted fashion. For companies deploying service-oriented architecture
(SOA) and Web Services, Tivoli Federated Identity Manager provides
policy-based integrated security management for federated Web services. The
foundation of Federated Identity Management is trust, integrity, and privacy of
data.
Tivoli Federated Identity Manager implements a number of industry standard
mechanisms, including SAML, the Liberty Alliance, and the Web Service
Federation Language (WS-Federation) specification for federating user
information and authentication schemes that may be used across different parts
of your business or between you and your business partners.
Tivoli Federated Identity Manager operates on the recognition that no one entity
in the world will have sole authority over the authenticity of users in the internet,
or even the relationships between multiple business partners. Instead, it enables
you to recognize the authority that each partner has in establishing the
authenticity of the users that exist at each partner, and then coordinating how
that authenticity may be used to control access to your own services and
resources.
This can dramatically reduce operational expenses by eliminating duplicate
registry entries for all your users at each location that hosts services you want to
use. It simplifies your users job by enabling a single sign-on to all the systems
your user needs. The single sign-on also increases the overall integrity of your
system by reducing the number passwords that your users must remember.
More information about Tivoli Federated Identify Manager can be found here:
http://www.ibm.com/software/tivoli/products/federated-identity-mgr/
IBM Tivoli Composite Application Manager family products

This section includes complimentary product information for the ITCAM.
872
More information about the IBM Tivoli Composite Application Manager family of
products can be found with the following resources:
IBM Tivoli Composite Application Manager products page:
http://www.ibm.com/software/tivoli/sw-atoz/indexC.html
IBM Redbook IBM Tivoli Composite Application Manager V6.0 Family:
Installation, Configuration, and Basic Usage, SG24-7151
IBM Tivoli Composite Application Manager for Response Time

Tracking V6.0
IBM Tivoli Composite Application Manager for Response Time Tracking V6.0
(ITCAM for RTT) can proactively recognize, isolate, and resolve transaction
performance problems using robotic and real-time techniques. It is an end-to-end
transaction management solution that monitors end-user response time and
helps you visualize a transactions path through your application systems,
including response time contributions of each step. You can drill down to each
step that the transaction takes as it travels across multiple systems, and measure
how each component of a transaction contributes to the overall response time.
The entire transaction analysis process is transparent to customers and
application developers.
IBM Tivoli Composite Application Manager for SOA V6.0

IBM Tivoli Composite Application Manager for SOA (ITCAM for SOA) can
monitor, manage, and control the Web services layer of IT architectures while
drilling down to the application or resource layer to identify the source of
bottlenecks or failures, and pinpoint services that take the most time or use the
most resources.
ITCAM for SOA includes the Web Services Navigator, a plug-in to IBM Rational
and other Eclipse-based tools, which provides deep understanding of service
flows, patterns and relationships to developers and architects using operational
data from Tivoli Data Warehouse.

V6.0
IBM Tivoli Composite Application Manager for WebSphere (ITCAM for
WebSphere) can help you quickly pinpoint, in real time, the source of bottlenecks
in application code or server resources. Real-time information includes
throughput, response time, and details for a specific transaction. ITCAM for
WebSphere also provides predefined reports that you can use to display
historical data, so you can plan for future growth.
873
IBM Tivoli Composite Application Manager for CICS

Transactions V6.0
ITCAM for CICS Transactions is a data collector installed on CICS systems to
provide data for ITCAM for Response Time Tracking or ITCAM for WebSphere.
ITCAM for CICS Transactions does not provide in-depth application analysis or
CICS system analysis; this requires Tivoli OMEGAMON XE for CICS on z/OS.
ITCAM for CICS Transactions provides the following information:
CICS call summary and response time

CICS transaction response time
CICS processor and memory usage
ITCAM for CICS Transactions is not a standalone product. It needs either ITCAM
for Response Time Tracking, ITCAM for WebSphere, or both.
IBM Tivoli Composite Application Manager for IMS

Transactions V6.0
ITCAM for IMS Transactions is a data collector installed on IMS systems to
provide data for ITCAM for Response Time Tracking or ITCAM for WebSphere.
ITCAM for IMS Transactions does not provide in-depth application analysis or
IMS system analysis; this requires IBM Tivoli OMEGAMON XE for IMS on z/OS.
ITCAM for IMS Transactions provides the following information:
IMS transaction response time

IMS processor and memory usage
ITCAM for IMS Transactions is not a standalone product. It needs ITCAM for
Response Time Tracking, ITCAM for WebSphere, or both.
OMEGAMON XE for WebSphere Business Integration V1.1

IBM Tivoli OMEGAMON XE for WebSphere Business Integration helps improve
the availability and performance of business-critical applications and business
integration systems. It can identify common problems and automate corrective
actions using predefined industry best-practice situations, while monitoring key
WebSphere MQ and WebSphere Business Integration Message Broker metrics.
It improves WebSphere MQ, Message Broker, MQ Integrator and
InterChange Server Availability:
Identify common problems and automates corrective actions
Auto-discovery and immediate monitoring of complex environments
Drill-down to locate a problem, identify the root cause, and resolve
bottlenecks or outages
874
Proactively Prevent Problems

Correctly configure and deploy your WebSphere MQ infrastructure
Detect and repair problems as they happen, or alert you to an imminent
concern
Provides key WebSphere MQ and Message Broker metrics for real-time
and historical data analysis
Simplify Management with a Single Tool
Manages WebSphere MQ, Message Broker, MQ Integrator and
InterChange Server in distributed and mainframe environments
User-customized displays including business, platform and resource views
When used collectively, the ITCAM products provide end-to-end transactional
view of monitored systems with detail analysis of resource utilization in a
heterogeneous environment.
IBM Tivoli Composite Application Manager product family and

Candle terminology
IBM acquired the Candle company which was incorporated into the Tivoli brand
of solutions. It is important to note that the ITCAM family of products is a result of
integration of Candle OMEGAMON products and IBM Tivoli products.
Table 17-3 provides a mapping of the new IBM Tivoli terminology and the old
Candle terminology. Although the products have acquired the new IBM
terminologies and names, you can see references to the old OMEGAMON
names within the product and documentation. ITCAM for SOA is designed to
operate within the IBM Tivoli Monitoring.
Table 17-3 Summary of ITCAM product family and Candle terminology
Candle/OMEGAMON Terminology
IBM Tivoli management services
OMEGAMON Platform
OMEGAMON for distributed products
Candle Management Server (CMS)
CandleNET Portal Server
CandleNET Portal
Situation Event Console
Enterprise Event Console/Event Console
875
876
Candle/OMEGAMON Terminology
Candle Management Workstation
Data Warehouse
Candle Data Warehouse
Appendix B.
Additional material
This redbook refers to additional material that can be downloaded from the
Internet as described here.
Locating the Web material

The Web material associated with this redbook is available in softcopy on the
Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG247386
Alternatively, you can go to the IBM Redbooks Web site at:
ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with
the redbook form number, SG247386.
Using the Web material

The additional Web material that accompanies this redbook includes the
following file:
File name
SG247386.zip
Description
Zipped integration scenario samples
877
System requirements for downloading the Web material

The following system configuration is recommended:
Hard disk space:
Operating System:
200KB
Windows
How to use the Web material

Unzip theSG247386.zip file to a suitable location. The following directory
structure will be created:
\ITSO\WSRR\xxx\
Where, xxx represents one of the following directories:
\plugins\
used in Chapter 13, Configuring governance on page 461
\scripts\
\src\
\WESB\
used in Chapter 14, Integrating WSRR with WebSphere ESB on page 511
Each of these directories contains files and data used in the integration scenarios
covered in this redbook. Refer to the specific integration chapters for additional
details.
878
Glossary
B
broker archive. A file that is the unit of deployment
to the broker that can contain any number of
compiled message flow and message set files and a
single deployment descriptor. A separate broker
archive file is required for each configuration that is
deployed.
Business Process Execution Language
(BPEL). An XML-based language for the formal
specification of business processes and business
interaction protocols. BPEL extends the Web
Services interaction model and enables it to support
business transactions.
C
Common Object Request Broker Architecture
(CORBA). An architecture and a specification for
distributed object-oriented computing that separates
client and server programs with a formal interface
definition. See also Internet Inter-ORB Protocol.
E
enterprise archive (EAR). A specialized type of
JAR file, defined by the J2EE standard, used to
deploy J2EE applications to J2EE application
servers. An EAR file contains EJB components, a
deployment descriptor, and Web archive (WAR) files
for individual Web applications. See also Web
archive, Java archive.
Enterprise JavaBeans (EJB). A component
architecture defined by Sun Microsystems for the
development and deployment of object-oriented,
distributed, enterprise-level applications.
Extensible Access Control Markup Language

(XACML). XACML is an XML based language that
is designed to express security rules, policies and
policy sets that define the access rights of users to
resources.
Extensible Markup Language (XML). (1) A
standard metalanguage for defining markup
languages that is based on Standard Generalized
Markup Language (SGML). XML simplifies the
process of authoring and managing structured
information and transmitting and sharing structured
information across diverse computing systems.
(2) A text-based tag language used for document
processing and for publishing information on the
Web.
Extensible Stylesheet Language (XSL). A
language for specifying style sheets for XML
documents. XSL Transformation (XSLT) is used with
XSL to describe how an XML document is
transformed into another document.
Extensible Stylesheet Language Transformation
(XSLT). An XML processing language that is used
to convert an XML document into another document
in XML, PDF, HTML, or other format.
I
Information Technology Infrastructure Library
(ITIL). A framework of best practice approaches
intended to facilitate the delivery and the
management of high quality information technology
(IT) services.
Internet Inter-ORB Protocol (IIOP). A protocol
used for communication between Common Object
Request Broker Architecture (CORBA) object
request brokers. See also Common Object Request
Broker Architecture.
879
J
J2EE Connector architecture (JCA). A standard
architecture for connecting the J2EE platform to
heterogeneous enterprise information systems
(EIS).
Java 2 Platform Enterprise Edition (J2EE). An
environment for developing and deploying
enterprise applications, defined by Sun
Microsystems Inc. The J2EE platform consists of a
set of services, application programming interfaces
(APIs), and protocols that provide the functionality
for developing multitiered, Web-based applications.
Java API for XML-based RPC (JAX-RPC). A
specification that describes application
programming interfaces (APIs) and conventions for
building Web services and Web service clients that
use remote procedure calls (RPC) and XML.
JAX-RPC is also known as JSR 101.
Java archive (JAR). A compressed file format for
storing all the resources that are required to install
and run a Java program in a single file. See also
enterprise archive, Web archive.
Java Authentication and Authorization Service
(JAAS). In J2EE technology, a standard API for
performing security-based operations. Through
JAAS, services can authenticate and authorize
users while enabling the applications to remain
independent from underlying technologies.
Java Management Extensions (JMX). A means
of doing management of and through Java
technology. JMX was developed through the Java
Community ProcessSM program, by Sun
Microsystems, Inc. and some leading companies in
the management field. JMX is a universal, open
extension of the Java programming language for
management that can be deployed across all
industries, wherever management is needed.
Java Message Service (JMS). An application
programming interface that provides Java language
functions for handling messages.
880
Java Naming and Directory Interface

(JNDI). An extension to the Java platform that
provides a standard interface for heterogeneous
naming and directory services.
Java Native Interface (JNI). A programming
interface that allows Java code to interoperate with
functions that are written in other programming
languages.
JavaServer Pages (JSP). A server-side
scripting technology that enables Java code to be
dynamically embedded within Web pages (HTML
files) and executed when the page is served, in order
to return dynamic content to a client.
R
Remote Method Invocation (RMI). A protocol that
is used to communicate method invocations over a
network. Java Remote Method Invocation is a
distributed object model in which the methods of
remote objects written in the Java programming
language can be invoked from other Java virtual
machines, possibly on different hosts.
Remote Method Invocation over Internet
InterORB Protocol (RMI/IIOP). Part of the Java 2
Platform, Standard Edition (J2SE) model that
developers can use to program in the Java language
to work with RMI interfaces, but use IIOP as the
underlying transport.
remote procedure call (RPC). A protocol that
allows a program on a client computer to run a
program on a server.
S
Secure Sockets Layer (SSL). A security protocol
that provides communication privacy. With SSL,
client/server applications can communicate in a way
that is designed to prevent eavesdropping,
tampering, and message forgery.
Service Data Objects (SDO). An open standard

for enabling applications to handle data from
heterogeneous data sources in a uniform way. SDO
incorporates J2EE patterns but simplifies the J2EE
data programming model.
service-oriented architecture (SOA). A collection
of services that communicate with each other. The
communication might involve either simple data
passing or two or more services coordinating some
activity.
Simple Object Access Protocol (SOAP). A
lightweight, XML-based protocol for exchanging
information in a decentralized, distributed
environment. SOAP can be used to query and return
information and invoke services across the Internet.
State Adaptive Choreography Language
(SACL). SACL is an XML representation of state
machines. SACL allows you to define the states that
exist within your state machine and the transitions
that can occur to move entities from one state to
another.
U
Uniform Resource Identifier (URI). (1) A
compact string of characters for identifying an
abstract or physical resource.
(2) A unique address that is used to identify content
on the Web, such as a page of text, a video or sound
clip, a still or animated image, or a program. The
most common form of URI is the Web page address,
which is a particular form or subset of URI called a
Uniform Resource Locator (URL). A URI typically
describes how to access the resource, the computer
that contains the resource, and the name of the
resource (a file name) on the computer.
W
Web archive (WAR). A compressed file format,
defined by the J2EE standard, for storing all the
resources required to install and run a Web
application in a single file. See also enterprise
archive, Java archive.
Web Ontology Language (OWL). The Web
Ontology Language (OWL) is a W3C endorsed
format that can be used to define an ontology. It can
define relatively rich semantics including relations
between classes of entities (for example
disjointedness), cardinality (for example exactly
one), equality, properties, characteristics of
properties (for example symmetry), and enumerated
classes.
Web Services Description Language (WSDL).
(1) A set of definitions that consist of service, port,
message, bindings, and port type. WSDL provides a
way for service providers to describe the basic
format of Web service requests over different
protocols or encodings.
(2) An XML-based specification for describing
networked services as a set of endpoints operating
on messages containing either document-oriented
or procedure-oriented information.
Web Services Invocation Framework (WSIF). A
Java API that supports dynamic invoking of Web
services, regardless of the format in which the
service is implemented or the access mechanism.
Web Services Invocation Language (WSIL). An
XML document format that facilitates the discovery
of existing Web services and provides a set of rules
for how inspection-related information should be
made available for consumption.
Universal Description, Discovery, and

Integration (UDDI). UDDI is both a client-side API
and a SOAP-based server implementation that can
be used to store and retrieve information on service
providers and Web services.
Glossary
881
X
XML Path Language (XPath). An XSL
sublanguage designed to uniquely identify or
address parts of a source XML document, for use
with XSLT. XPath also provides basic facilities for
manipulation of strings, numbers and Booleans. See
Extensible Markup Language and Extensible
Stylesheet Language Transformation.
XML Schema Definition Language (XSD). A
language for describing XML files that contain XML
schema.
XML schema. An international standard that
defines a language for describing the structure of
XML documents. An XML schema formally
describes and constrains the content of XML
documents by indicating which elements are allowed
and in which combinations. (An XML Schema is an
alternative to a document type definition (DTD), and
can be used to extend functionality in the areas of
data typing, inheritance, and presentation.) The
XML Schema language is ideally suited to
describing the messages that flow between
business applications.
XML Services for the Enterprise (XSE). A
capability of WebSphere Developer which provides
tools that let you adapt COBOL-based applications
so that they can consume and produce XML
messages.
XML shredder. A function that parses an XML
document, extracting rows of data from an XML
table. Also referred to as parsing.
882
Abbreviations and acronyms

AIX
Advanced Interactive eXecutive
HTML
HyperText Markup Language
APAR
authorized program analysis report
HTTP
HyperText Transport Protocol
API
application programming interface
IBM
BAR
Broker Archive
International Business Machines

Corporation
BPEL
Business Process Execution Language
IIOP
Internet Inter-ORB Protocol
Tivoli Change and Configuration

Management Database
IRA
Intelligent Remote Agent
ISO
International Organization for

Standardization
CCMDB
CICS
Customer Information Control System
CLI
command line interface
ISV
independent software vendor
CMDB
Configuration Management Database
ITCAM
COBOL
Common Business Oriented Language
IBM Tivoli Composite Application

Manager
COE
Center of Excellence
ITCCMDB IBM Tivoli Change and Configuration

Management Database
CORBA
Common Object Request Broker

Architecture
ITIL
Information Technology Infrastructure

Library
CRUD
create, retrieve, update, and delete
ITM
CSD
CICS System Definition
ITSO
DCA
Data Collector Adapter
International Technical Support

Organization
DLA
Discovery Library Adapter
J2C
J2EE Connector Architecture
DLFS
Discovery Library File Store
J2EE
Java 2 Platform, Enterprise Edition
DOS
disk operating system
JAAS
EAI
Enterprise Application Integration
Java Authentication and Authorization

Service
EAR
enterprise archive
JAR
Java archive
EBCDIC
Extended Binary Coded Decimal

Interchange Code
JAX-RPC Java API for XML-based RPC

JCA
J2EE Connector architecture

job control language
EDI
electronic data interchange
JCL
EIF
Event Integration Facility
JDBC
Java Database Connectivity
EIS
Enterprise Information Systems
JDK
Java Development Kit
EJB
Enterprise Java Bean
JES
Job Entry Subsystem
ESB
Enterprise Service Bus
JMS
Java Message Service
ESQL
Extended Structured Query Language
JMX
Java Management eXtensions
FTP
File Transfer Protocol
JNDI
Java Naming and Directory Interface
GUI
Graphical User Interface
JRE
Java Runtime Environment
high-level language
JSP
JavaServer Pages
HLL
883
JSR
Java Specification Request
SPI
Security Policy Index
JVM
Java virtual machine
SQL
Structured Query Language
LDAP
Lightweight Directory Access Protocol
SSH
Secure Shell
MQ
managers and queues
SSL
Secure Sockets Layer
MSS
Managed Software System
SSO
Single Sign-on
OASIS
Organization for the Advancement of

Structured Information Standards
TCORE
Tivoli Common Object Repository
TDW
Tivoli Data Warehouse
ODBC
Open Database Connectivity
TEC
Tivoli Enterprise Console
OTEA
OMEGAMON TEC Event Adapter
TEMA
OWL
Web Ontology Language
TEMS
RACF
Resource Access Control Facility
TEP
RAD
rapid application development
TEPS
RAM
Rational Asset Manager
TSO
Time Sharing Option
RDF
Resource Description Framework
UDB
Universal Database
RFID
radio frequency ID
UDDI
RHAS
Red Hat Advanced Server
Universal Description, Discovery and

Integration
RMI
Remote Method Invocation
UI
User Interface
RMI/IIOP Remote Method Invocation over Internet

InterORB Protocol
UML
Universal Markup Language
URI
Uniform Resource Identifier
RPC
remote procedure call
URL
Uniform Resource Locator
RSA
Rational Software Architect
VSAM
Virtual Storage Access Method
SACL
WAR
Web Archive
SAML
Security Assertion Markup Language
WESB
SCA
Service Component Architecture
WID
WebSphere Integration Developer
SCDL
Service Component Definition

Language
WMB
WMQ
WebSphere MQ
WPS
SDK
software development kit
SDO
Service Data Object
SHA
Secure Hash Algorithm
WS-BPEL Business Process Execution Language

for Web services
SLA
service level agreement
WSDL
Web Services Description Language
SLES
SuSE Linux Enterprise Server
WSIF
Web Services Invocation Framework
SMO
service message objects
WSIL
Web Services Inspection Language
SMTP
Simple Mail Transport Protocol
WSRR
SOA
service-oriented architecture
WebSphere Service Registry and

Repository
SOAP
Simple Object Access Protocol
XACML
SOR
statement of requirements
Extensible Access Control Markup

Language
XML
Extensible Markup Language
884
XPath
XML Path language
XPointer XML Pointer Language

XSD
XML Schema Definition
XSE
XML Services for the Enterprise
XSL
Extensible Stylesheet Language
XSLT
Extensible Stylesheet Language

Transformations
Abbreviations and acronyms
885
886
Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information about ordering these publications, see How to get IBM
Redbooks on page 890. Note that some of the documents referenced here may
be available in softcopy only.
Patterns: SOA Foundation Service Creation Scenario, SG24-7240
Patterns: SOA Foundation Service Connectivity Scenario, SG24-7228
Patterns: Integrating Enterprise Service Buses in a Service-Oriented
Architecture, SG24-6773
Patterns: Implementing an SOA using an Enterprise Service Bus, SG24-6346
Getting Started with WebSphere Enterprise Service Bus V6, SG24-7212
Web Services Handbook for WebSphere Application Server 6.1, SG24-7257
Architecting Access to CICS within an SOA, SG24-5466
WebSphere Message Broker Basics, SG24-7137
IBM Tivoli Composite Application Manager V6.0 Family: Installation,
Configuration, and Basic Usage, SG24-7151
Best Practices for SOA Management, REDP-4233
Understanding SOA Security Design and Implementation, SG24-7310
Other publications
These publications are also relevant as further information sources:
Service-Oriented Architecture Compass: Business Value, Planning, and
Enterprise Roadmap, by Norbert Bieberstein, et al. IBM Press, 2005,
ISBN-10: 0131870025
887
Online resources and product documentation

The following Web sites and documents are also relevant as further information
sources:

Web service standards for Service Registry and Repository
http://www.ibm.com/developerworks/webservices/library/specification/
ws-servregrep/
WebSphere Service Registry and Repository product page
http://www.ibm.com/software/integration/wsrr/
WebSphere Service Registry and Repository Information Center
http://publib.boulder.ibm.com/infocenter/sr/v6r0/index.jsp
Introducing WebSphere Service Registry and Repository, Part 1
9_mckee/0609_mckee.html
Introducing WebSphere Service Registry and Repository, Part 2
9_mckee2/0609_mckee2.html
Introducing WebSphere Service Registry and Repository APIs
1_baldwin/0611_baldwin.html
Using collections in the WebSphere Service Registry and Repository to
resolve versioned imports, Part 1: Using GenericObjects
1_kufluk/0701_kufluk.html
Customizing the WebSphere Service Registry and Repository user interface,
Part 1
1_smithson/0611_smithson.html
WebSphere Service Registry and Repository Support
http://www.ibm.com/software/integration/wsrr/support/
WebSphere Service Registry and Repository SupportPacs
http://www.ibm.com/support/docview.wss?rs=171&uid=swg27008751#1
888
WebSphere Service Registry and Repository Eclipse plug-in

http://www.ibm.com/support/docview.wss?rs=3163&context=SSWLGF&dc=D40
0&uid=swg24013925&loc=en_US&cs=UTF-8&lang=en
WebSphere
WebSphere MQ Information Center
http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp
WebSphere Application Server V6.0 Information Center
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp
CICS
Publishing a Web service to WebSphere Service Registry and Repository
from CICS Transaction Server V3.1
0_millwood/0610_millwood.html
CICS TS SupportPac CA1N - Support for the WebSphere Service Registry
and Repository
CICS TS V3.1 Information Center
http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp
Service-oriented architecture
IBM SOA Foundation - An Architectural Introduction and Overview
http://download.boulder.ibm.com/ibmdl/pub/software/dw/webservices/ws
-soa-whitepaper.pdf
Introduction to SOA programming model
http://www.ibm.com/developerworks/webservices/library/ws-soa-progmod
el/
Introduction to SOA governance
http://www.ibm.com/developerworks/library/ar-servgov/

Tivoli Composite Application Manager for SOA - Version 6.1.0 - Installation
and Users Guide, GC32-9492
Related publications
889
Tivoli Composite Application Manager for SOA Information Center

http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?toc
=/com.ibm.itcamsoa.doc/toc.xml
IBM Tivoli Composite Application Manager for SOA product information
http://www.ibm.com/software/tivoli/products/composite-application-mg
r-soa/

WebSphere Message Broker V6.0 Information Center
Build flexible ESB mediations with WebSphere Message Broker and
0_patten/0610_patten.html
WMB V6 Client for WebSphere Service Registry and Repository
How to get IBM Redbooks

You can search for, view, or download Redbooks, Redpapers, Hints and Tips,
draft publications and Additional materials, as well as order hardcopy Redbooks
or CD-ROMs, at this Web site:
ibm.com/redbooks
Help from IBM

IBM Support and downloads
ibm.com/support
IBM Global Services
ibm.com/services
890
Index
A
access control
administration 309311
overview 309
scripts for managing policy 322
type
create 309
delete 309
retrieve 309
transition 310
update 309
Access Services
SOA reference architecture model 13
action property 190
add properties to objects 440442
addChecksum 484485
adding permissions to roles 469
addPermissionToRole 197, 289, 322
addPermissionToRole2 289, 322
addPrincipalToRole 197, 288, 323
addRole 197, 288, 323
Admin (JMX) interface
overview 155
Admin MBean operations
addPermissionToRole 289
addPermissionToRole2 289
addPrincipalToRole 288
addRole 288
createOntologySystem 287288
deleteConfiguration 287
deleteOntologySystem 288
exportMetaData 288
getConfigurationId 287
getConfigurationIds 287
getPermissionsForRole 289
getRolesWithPermissions 288
importMetaData 288
loadConfiguration 287
persistPolicy 289
persistRoleMappings 289
removeAllRolePermissions 288
removeAllRoles 288
removePermissionFromRole 288
removePrincipalFromRole 288
removeRole 288
retrieveAllConfigurationNames 287
retrieveConfiguration 287
updateConfiguration 287
AdminException 285, 291292, 297
Administration 331
administrator permission 193
AL3 867
AllAuthenticatedUsers 187
application architecture 19
AppServer 660
Assemble
SOA lifecycle 8
attribute tables 681682
AttributeDeclaration 133, 135
auditing 77
authorization policy file 196
AuthorizeDevelopment 165
B
BaseObject 101103, 114
BindAddress 660
binding 22, 28, 55, 95, 514, 517
dynamic 22, 36
Java Message Service bindings 517
SCA binding 517, 535
static 22, 58
Web Service bindings 517
WebSphere Adapter bindings 518
WebSphere MQ bindings 518
WebSphere MQ JMS bindings 517
BM Tivoli Composite Application Manager for SOA
overview 641
BOOTSTRAPPORT 267268, 276278
Bowstreet Portlet Factory
overview 865
BrowseClassificationSystem 394
BSRSDOHelper 123
bsrURI 104, 128129, 141143, 168, 312, 801, 854
defined 104
temporary 141
Business Application Services
891

Business Process Details 675
Business Process Execution Language 98
Business Process Execution Language for Web
Services 25, 657
Business Processes for Service 674
Business Processes for Service Port 675
button-action 408, 410
button-definitions 407, 409
button-message 408
C
C 863
C++ 863
CA1N 826
calculateMD5Checksum 486
callout responses 519
Candle Data Warehouse 876
Candle Management Server 875
Candle Management Workstation 876
CandleNET Portal 875
CandleNET Portal Server 875
canonical data model 46
Change and Release Management 36
checkWSDLPorts 489490
CICS
overview 827831
SOA 831
Transaction Server 863
overview 827
TXSeries 829
Web Services Assistant 863
CICS SupportPac
downloading 832
installation 831834
overview 826
Class 861
classification functions 108
Classification Systems 330
classifications 8688
ontology 87
taxonomies 87
Web Ontology Language 87
within WSRR 87
ClassificationURI 387
classifiedByAllOf 192
892
classifiedByAnyOf 192
classifying objects 358363
browsing classifications 359
classifying an entity 361
loading an OWL file 358
removing a classification 361
client-side interception 651
CMDB
See Configuration Management Database
CMS
See Candle Management Server
collection 401410
definition file 151152
name, title, description 403
skeleton collection view 402
view areas 401
view buttons 407
view columns 404
column-definitions 407
com.ibm.ssl.keyStore 430
com.ibm.ssl.trustStore 430
command line
administration 283
command line interface 74
import/export 315
overview 154
sample scripts 306
createGenericObject 306
createXMLDocument 306
deleteBaseObject 306
deleteConfig 307
export 306
findBaseObject 306
import 307
loadConfig 307
promote 307
retrieveConfig 307
transition 307
updateConfig 307
Common Data Model 657658, 662
Common Object Repository 656, 659, 661, 664
common relationships 221
Communication Component 861
complex type 371
ComplexTypeDefinition 111, 133, 135
ComplexTypeDefinition relationships 242
component model 18
composite application
defined 20
composite state 159
Composite Structure 861
ComputerSystem 660
concepts 83, 370379, 385, 445451
classifying a complex type as a template 371
creating a concept from a template 374
creating concepts for objects 445447
creating concepts using local documents
448451
defining a concept template 371
deleting a concept 378
viewing templates 372
viewing the details of a concept 377
concrete types 111
configuration 283285, 411413
configuration document 283
configuration type 283
content 283, 411
managing 411413
name 283, 411
supported configurations 284
system indicator 284, 411
type 284, 411
Configuration Management Database 632, 696
ConfigurationType 285
ConnectorException 296297
content model
See information model
create method 204
createGenericObject script 306
createOntologySystem 287288, 307, 412
createRequest 142
createResponse 143
createXMLDocument script 306
creating content in WSRR 124
Custom Mediation 521
Customer Information Control System
See CICS
CWSP 842, 844
configuration file 844845
overview 826
running 843
D
Data Collector Adapter 648
Data Collectors 648, 651

data graphs 100
data objects 100
Data Warehouse 876
Database Lookup 520
DataFactory 123124, 127128
DataGraphType 140
DataStage TX 867
DB2 869
DB2 Universal Database Enterprise Server Edition
installing 256258
decoupling
Enterprise Service Bus 29
default permission 192
define relationships between objects 442445
delete method 205
deleteBaseObject script 306
deleteConfig script 307
deleteConfiguration 287, 322, 412
deleteOntologySystem 288, 307, 322, 412
deleting artefacts 369370
deleting content from WSRR 130
delta books 656
dependency depth 217
Deploy
SOA lifecycle 9
deploying
265275
Deployment diagrams 861
deployment time 23
derived objects 93, 95, 98, 168, 186, 218219, 230,
504509
defined 218
dependencies 507
detail
definition file 152
DetailView 405
DFHLS2WS 834, 863
DFHSR2WS 847
JCL 850
overview 826
running 848
DFHWS2LS 826, 863
DFHWS2SR 834
JCL 837
overview 826
running 835
DFHWSPB 843
Index
893
discovery 22
Discovery Library Adapter 648, 654, 659662,
702718
Business Process Execution Language for Web
Services 657
configuring 708713
delta books 656
Deployed 661
IBM Tivoli Composite Application Manager for
SOA 657
installing 705707
managed 661
overview 656657, 703
refresh books 656
using 714718
657
DLA
See Discovery Library Adapter
document instance
creating 124128
document relationships 224
document types 8998
Service Component Architecture 9697
Service Component Description Language 89
Web Services Description Language 89, 9496
WS-Policy 89, 98
XML metadata 98
XML Schema Definition 89, 9193
downcast 110
dynamic binding 22, 36
dynamic programming model 100
E
Eclipse plug-in 73, 415451
See also Eclipse UI
installation 417427
Eclipse UI
See also Eclipse plug-in
416451
configuring 428431
creating concepts for objects 445447
creating concepts using local documents
448451
import documents into local workspace
435438
894
publishing documents 438439

searching the registry 431435
EDI 867
EIF
See Event Integration Facility
EIFLogger 734, 742
EJB client 136
ElementDeclaration 133134
ElementDeclaration relationships 241
Endpoint Lookup 521, 525536
usage 528
Enterprise Event Console/Event Console 875
Enterprise Java Beans 861
Enterprise Service Bus 2834, 512
and service-oriented architecture 28
decoupling 29
defined 30
hub and spoke architecture 31
in a service-oriented archtecture 15
mediation support 33
protocol independence 34
substitution 34
entityBsrUri 167
Environment Promotion 319321
defined 319
sample script 319
ESB
See Enterprise Service Bus
Event Emitter Mediation 521
Event Integration Facility 687, 728, 734, 740, 747,
751
EventMap 735
executeNamedQuery 142
executeNamedQueryWithParameters 142
executeQuery 142
Export 384, 514
export script 306
ExportDocument 384
exportMetaData 288, 322
Extensible Access Control Markup Language 196
extensible markup language
defined 26
Extensible Stylesheet Language Transformations
161, 520, 525, 528, 777
F
Fail 521
Fail terminal 521
Fault_610 680, 743, 757758, 760, 765, 768

FilterExpression 192
findBaseObject script 306
G
GenericObject 83, 123, 126128, 130, 135, 168,
191, 384385
creating 124
defined 81
getAllAttributeDeclarations 133
getAllBindings 133
getAllComplexTypeDefinitions 133
getAllElementDeclarations 133
getAllGenericObjects 135
getAllMessages 133
getAllOperations 133
getAllParts 133
getAllPolicyDocuments 133
getAllPorts 133
getAllPortTypes 133
getAllServices 133
getAllWSDLDocuments 133
getAllXMLDocuments 133
getAllXSDDocuments 133
getConfigurationId 287, 412
getConfigurationIds 287
getGovernanceConnection 304
getGovernanceRecord 135, 168
getInboundDependencies 220
getOntologyConnection 304
getOutboundDependencies 220
getPermissionsForRole 197, 289, 323
getPolicyConfiguration 323
getPolicyDocument 133
getProperties 305
getRoleMappingConfiguration 323
getRoles 323
getRolesWithPermissions 197, 288
getServiceRegistryRepositoryProxy 305
getSessionConnection 303
getUserDefinedRelationshipNames 135
getWSDLDocBindings 134
getWSDLDocMessages 134
getWSDLDocOperations 134
getWSDLDocParts 134
getWSDLDocPorts 134, 490
getWSDLDocPortTypes 134
getWSDLDocServices 134
getWSDLDocSOAPBindings 134
getWSDLDocSOAPPorts 134
getWSDLDocument 133
getWSDLPorts 135
getWSDLPortTypes 135
getWSDLServices 135
getXMLDocument 133
getXSDAttributeDeclarations 135
getXSDComplexTypeDefs 135
getXSDDocument 133
getXSDElements 134
getXSDSimpleTypeDefs 134
governance 4049, 5557, 6465, 7677,
157244, 461509
See also SOA governance
auditing 77
configuring 461509
governed collections 169179
adding an object 171
best practices 179187
removing an object 174
notification 76
removing governance 481
root object 168
service lifecycle 76
validation 76
Governance API 477
GovernanceManagePermission 194
governanceNotifiers 212
GovernanceRecord 135, 167187
attributes
entityBsrUri 167
governedObjects 167
state 167
GovernanceTransitionPermission 194
governanceValidators 208
governed entity 158
governed object 158
GenericObject 168
lifecycle 159
making an object governable 477
PolicyDocument 168
SCAModule 168
transitioning the lifecycle state 479
Index
895
WSDLDocument 168
XMLDocument 168
XSDDocument 168
GovernedCreatePermission 193
GovernedDeletePermission 194
governedObjects 167
GovernedRetrievePermission 193
GovernedRetrievePermissionA 195
GovernedRetrievePermissionB 195
GovernedUpdatePermission 194
GovernedUserUpdatePermission 195
GraphQuery 105, 130132, 191
defined 132
H
HIPAA 867
HL7 867
hub and spoke architecture 31
I
IBM Discovery Library Identity Markup Language
656
IBM IT Service Management 631
IBM Tivoli Access Manager
overview 871
IBM Tivoli Composite Application Manager
Candle product integration 875
overview 634
IBM Tivoli Composite Application Manager for CICS
Transactions 635
overview 874
IBM Tivoli Composite Application Manager for IMS
Transactions 635
overview 874
IBM Tivoli Composite Application Manager for Response Time Tracking 634, 638
overview 873
166, 634, 638, 640653
components 647
integration scenarios with WebSphere Service
Registry and Repository 654
overview 870, 873
product features 644
situation 678690
overview 679
predefined 680
896
Event Handler 687689, 698

configuring 731746
event properties 737
installation 729730
IBM Tivoli Composite Application Manager for WebSphere 635
overview 873
IBM Tivoli Data Warehouse 640
IBM Tivoli Enterprise Console 638, 687, 689, 729,
733, 739, 746, 752754
IBM Tivoli Enterprise Monitoring Agent 875
overview 638
IBM Tivoli Enterprise Monitoring framework
636640, 692, 746
IBM Tivoli Enterprise Monitoring Server 875
overview 636
IBM Tivoli Enterprise Portal 875876
IBM Tivoli Enterprise Portal clients
overview 637
IBM Tivoli Enterprise Portal Server 875
overview 637
IBM Tivoli Federated Identity Manager
overview 872
IBM Tivoli Management Framework 753
IBM Tivoli management services 875
IBM Tivoli Monitoring 638, 875
IBM Tivoli OMEGAMON XE for Messaging
overview 870
IDML
See IBM Discovery Library Identity Markup Language
impact analysis 213244, 499509
inbound dependencies 216
outbound dependencies 214
Import 384, 514
import documents into local workspace 435438
import script 307
import/export 311318
export 311
import 313
ImportDocument 384
ImportDocuments 394
importedWSDLs 500
importMetaData 288, 322
IMS DL/I 869
In terminal 521
information model 7172, 79118

BaseObject 101103
document types 8998
parsing 67, 8182, 8485, 90, 93, 96, 168,
218219, 230
query 103118
See also query
examples 105117
GraphQuery 105
limitations 118
predicates 106
PropertyQuery 105
relationship map 111
shortcuts and wildcards 107
treat as 110
Service Data Objects 99101
data graphs 100
data objects 100
service description entities 8083
defined 72, 80
GenericObject 83
defined 81
logical derivations 82
defined 81
physical documents 81
defined 80
service description metadata 8488
ontology 87
taxonomies 87
within WSRR 87
defined 72, 80
properties 8485
relationships 8586
templates 8889
XPath 99
Information Technology Infrastructure Library 632,
696
installing
DB2 Universal Database Enterprise Server Edition 256258
WebSphere Application Server 254256
WebSphere Application Server ND 277279

258264
remote DB 275277
InstanceNotFoundException 296297
integration architecture 19
Intelligent Remote Agent 648
interfaces and APIs 7275
Admin (JMX) interface
overview 155
overview 154
Eclipse plug-in 415451
See also Eclipse plug-in
Java API (EJB) 120135
GraphQuery 132
Java client 120
PropertyQuery 132
querying content in WSRR 130
retrieving content from WSRR 128
ServiceRegistryClient 121
updating content in WSRR 129
query interface 72
SOAP API 139144
bsrURI 141
DataGraphType 140
portType 142
PropertyQueryResult 141
WSRR type 140
supported APIs 74
user interfaces 73
Eclipse plug-in 73
Web interface 73
Web services API 136144
EJB client 136
ontology Web service 138
Web services client 136
Web UI 144154
introspect 17, 82, 100
IPInterface 660
IPv4Address 660
IT Service Management
ITCAMListener 733, 741
ITIL
See Information Technology Infrastructure Li-
Index
897
brary
J
Java API (EJB) 120135
GraphQuery 132
Java client 120
PropertyQuery 132
ServiceRegistryClient 121
Java client 120
Java Message Service bindings 517
JMSEndpoint 820
JMSExportBinding 110
JMSImportBinding 110
JMX
administration 282, 292298
K
keyStore 430
L
lazy initialization 198
lifecycle 711, 158187
definitions 160
governed object 159
lifecycle flow 11
management with scripts 323
SOA governance 158187
state machine 159
transitioning the lifecycle state 479
using 476482
WSRR default 163167
assemble 165
created 164
deploy 165
manage 166
model 164
retired 167
lifecycle ontology file 160163
generating 161
modifying 162
898
ListMyFavourites 394
ListMySubscriptions 394
LoadClassificationSystem 394
loadConfig script 307
loadConfiguration 287, 322, 412
LoadDocument 394
loadOntologySystem 322
loadPolicyConfiguration 323
loadRoleMappingConfiguration 323
locating WSRR MBean 286
defined 8182
parsing 8182
logical objects 82
defined 82
LogicalObject relationships 229
logicalobjects
from parsing 230
M
making an object governable 158, 477
Manage
SOA lifecycle 10
mapping users to roles 475
match policy 527, 530
MaxMessageSize_610 680
MaxResponseTimeCritical_610 681
MaxResponseTimeWarning_610 681
MBean 286
createOntologySystem 307
discovering WSRR MBean notifications 289
invoking MBean operations 289
ServiceRegistryRepository 282, 285286, 294,
412
supported Admin operations 197, 287
MBeanException 292, 296297
mediation 514515
mediation flow 518519
callout responses 519
request flow 518519
response flow 518519
mediation flow component 514, 518
mediation module 514, 516518
mediation primitives 520521
Custom Mediation 521
Database Lookup 520
Endpoint Lookup 521, 525536

usage 528
Event Emitter Mediation 521
Extensible Stylesheet Language Transformations 520
Fail 521
Message Element Setter 521
Message Filter 520
Message Logger 520
Stop 521
mediation support 33
message 27
Message Element Setter 521
Message Filter 520
Message Logger 520
MessageArrivalClearing_610 681
MessageArrivalCritical_610 681
MessageSize_610 680
metadata API 100
Model
SOA lifecycle 8
modelled relationships 213, 218242
modelledRelationships parameter 220
Module 384
ModuleDocument 384
monitoring agent 648649
MQEndpoint 820
mqsichangebroker 785
mqsicreatebroker 785
My Service Registry 330
N
name 190
navigation
definition file 150
navigation tree 390394, 397
NetView for z/OS 638
notification 76
NotificationProperties 207
notifiers 197, 203206
developing custom notifiers 486491
interfaces 203206
create method 204
delete method 205
transition method 205
update method 205
properties 211
O
object types
Export 384
ExportDocument 384
GenericObject 384
Import 384
ImportDocument 384
Module 384
ModuleDocument 384
PolicyDocument 384
SCAExportBinding 385
SCAImportBinding 384
SCAModule 384
SCAWSDLPortType 385
SLSBImportBinding 385
SOAPAddress 384
SOAPBinding 384
Subscription 385
WebServiceExportBinding 385
WebServiceImportBinding 385
WSDLBinding 384
WSDLDocument 384
WSDLMessage 384
WSDLOperaton 384
WSDLPart 384
WSDLPort 384
WSDLPortType 384
WSDLService 384
XMLDocument 384
XMLElement 384
XSDAttribute 384
XSDComplexType 384
XSDDocument 384
XSDSimpleType 384
ObjectType 383, 385
OMEGAMON Distributed 638
OMEGAMON for distributed products 875
OMEGAMON Monitoring Agent 875
OMEGAMON Platform 875
OMEGAMON TEC Event Adapter 688
OMEGAMON XE for WebSphere Business Integration 635
overview 874
OMEGAMON z/OS 638
ontology 87
creating an ontology system 308
defined 70
delete 322
Index
899
load 322
removing an ontology system 308
operation 28
Operational Efficiency and Resilience 36
Oracle 869
OriginalObject 168171, 173174, 176177, 179,
185, 191, 199201, 204206
OriginalObject relationships 223
Out terminal 521
outputMBeanInterface 294295
OWL
See Web Ontology Language
P
parsing 67, 8182, 8485, 90, 93, 96, 168,
218219, 230
Partner Services
patterns
router pattern 806809
transcoder pattern 803806
permission 189195
action property 190
srrDelete 190
srrManageGov 190
srrRetrieve 190
srrTransition 190
srrUpdate 190
ssrCreate 190
administrator permission 193
default permission 192
GenericObject 191
GovernanceManagePermission 194
GovernanceTransitionPermission 194
GovernedCreatePermission 193
GovernedDeletePermission 194
GovernedRetrievePermission 193
GovernedRetrievePermissionA 195
GovernedRetrievePermissionB 195
GovernedUpdatePermission 194
GovernedUserUpdatePermission 195
GraphQuery 191
name 190
OriginalObject 191
PolicyDocument 191
900
PropertyQuery 191
QueryObject 191
SCAModule 191
target property 191
user permission 195
WSDLDocument 191
XMLDocument 191
XSDDocument 191
persistPolicy 197, 289, 323
persistRoleMappings 197, 289, 323
perspective 394400
defined 394
definition file 147
mappings 398
name, title, role 396
navigation tree 397
skeleton perspective file 395
defined 80
dependencies 500507
Service Component Description Language 81
Web Services Description Language 81
WS-Policy 81
XML Schema Definition 81
PL/I 863
plugins 197213
configuring 207213, 494499
deploying 491494
developing custom plugins 482499
notifiers 197, 203206
custom 486491
interfaces 203206
create method 204
delete method 205
update method 205
properties 211
packaging 206
validators 197203
chains 210
custom 483486
interfaces 199202
create method 200
delete method 201
update method 200
validate method 202
properties 207
PolicyDocument 133, 168, 191, 384
port 28
port type 28, 94
portType 126, 142
predicates 106
Process Services
programming model 9
promote script 307
properties 8485, 335346
adding a new custom property 336
deleting a custom property 344
editing a property 340
PropertyQuery 105, 130132, 191
defined 132
PropertyQueryResult 135, 140141
defined 141
protocol independence 34
publishing documents 331335, 438439
Q
query 103118, 330, 382390
See also searching the registry
definition file 150
examples 105117
GraphQuery 105
limitations 118
predicates 106
PropertyQuery 105
querying by classification 387
querying by property 386
querying by relationship 386
treat as 110
using alternative views 385
view query 382390
query interface 72
QueryClassificationsAllOf 388
QueryClassificationsAnyOf 388
QueryDefinitions 383
QueryExactClassificationsAllOf 388
QueryExactClassificationsAnyOf 388
QueryObject 123, 128, 191
creating 128
QueryWizardPrepare 394
quick search 329
R
RAD
See Rational Application Developer
Rational Application Developer 62
overview 862
Rational Data Architect
overview 861
Rational Software Architect 416417, 860
overview 860
Rational Software Developer Platform 864
Redbooks Web site 890
Contact us xxi
ReflectionException 296297
refresh books 656
concrete types 111
supertypes 111, 114
XSD files 111, 116
relationships 8586, 347357
common 221
ComplexTypeDefinition 242
creating a new relationship 347
deleting a relationship 357
document 224
editing an existing relationship 354
ElementDeclaration 241
LogicalObject 229
modelled 213, 218242
OriginalObject 223
SOAPAddress 241
SOAPBinding 237
user defined 213, 243244
WSDLBinding 235
WSDLDcoument 225
WSDLMessage 233
WSDLOperation 231
WSDLPart 234
WSDLPort 239
WSDLPortType 230
WSDLService 238
XSDDocument 227
Remote Method Invocation/InterORB Protocol
(RMI/IIOP) 866
remote procedure call 27
removeAllRolePermissions 197, 288, 323
Index
901
removeAllRoles 197, 288, 323

removePermissionFromRole 197, 288, 323
removePrincipalFromRole 197, 288, 323
removeRole 197, 288, 323
reportAllConfigurations 322
request flow 518519
response flow 518519
ResponseTimeCritical_610 681
ResponseTimeWarning_610 681
retrieveAllConfigurationNames 287
retrieveConfig script 307
retrieveConfiguration 207, 287, 412
retrieveWithDepth 142
reusable business functions
deployment time 23
runtime 23
role mapping 463476
adding roles 468
mapping users to roles 475
role mapping file 196
root object 168
RPC
See remote procedure call
run_addVehicle.bat 814
run_testCustomer.bat 814
run_testEntityFlow.bat 815
run_testITService.bat 816
run_testMQ.bat 817
runtime 23
Runtime Integration 36
S
SACL
See State Adaptive Choreography Language
SAML 872
SCA
See Service Component Architecture
SCA bindings 517, 535
SCAExportBinding 111, 385
SCAImportBinding 110, 384
SCAModule 168, 191, 384
SCAWSDLPortType 111, 385
script
import and export of WSRR entities
902
exportMetaData 322
importMetaDataa 322
managing access control policy
addRole 323
getRoles 323
persistPolicy 323
removeAllRoles 323
removeRole 323
managing configuration
managing lifecycles
setupDefaultLifecyclePermissions 323
updateLifecycleDefinition 323
managing ontologies
sample command line interface 306
createGenericObject 306
createXMLDocument 306
deleteBaseObject 306
deleteConfig 307
export 306
findBaseObject 306
import 307
loadConfig 307
promote 307
retrieveConfig 307
transition 307
updateConfig 307
SDO
See Service Data Objects
sdo-int 136
sdo-int.jar 730
sdoType 406
searching the registry 363369, 431435

See also query
security 139, 187196, 274, 285, 462476
CICS 854
configuring 462476
permission 189195
See also permission
role mapping 463476
roles 187, 463
user defined roles 188
z/OS 854
Sequence 861
server-side interception 651
service 28, 95
defined 5, 20, 23
service binding definitions 94
Service Component Architecture 9697, 513, 661,
865
defined 514
Service Component Description Language 81, 89
service consumers 22, 515
logical node 695
Service Data Objects 75, 99101, 120, 191, 383,
406, 514
data graphs 100
data objects 100
defined 99
valid object types 384
service definition 43
service deployment lifecycle 43
active 44
deprecate 44
plan 44
sunset 44
test 44
defined 72, 80
GenericObject 83
defined 81
defined 81
defined 80
Service Component Description Language
81
WS-Policy 81
ontology 87
taxonomies 87
within WSRR 87
defined 72, 80
properties 8485
relationships 8586
Service Details 669671
Service Development Lifecycle 36
Service Documents 330
service endpoint definitions 94
Service Endpoint Registries/Repositories 36
service interface definitions 94
service message model 46
service message objects 514515, 519, 521525
manipulation 525
structure 522524
context section 524
data section 523
header section 524
Service Metadata 330
service migration 45
service monitoring 47
service orientation
defined 20
service ownership 47
Service Port Details 672674
service providers 21, 515
logical node 695
service registry 22, 46
in SOA governance 46
service registry and repository
See also WebSphere Service Registry and Repository
defined 1517
in a service-oriented architecture 1517, 3440
Service Registry view 416417, 426427,
434435, 440, 442, 445, 447, 450
service security 48
service testing 48
service versioning 45
service-oriented architecture
Index
903
a business view 418

an IT view 1840
components
service consumer 22
service provider 21
service registry 22
defined 20
by role 20
composite application 20
service 20, 23
service orientation 20
definitions
application architecture 19
component model 18
integration architecture 19
drivers
flexible pricing 22
increasing speed 22
reducing costs 22
return on investment 22
simplifying integration 22
service
deployment time 23
implementation-independent 23
loosely bound 23
reusable 23
runtime 23
Web services 25
ServiceRegistryClient 121, 136
ServiceRegistryClient.jar 730, 784785
ServiceRegistryException 285
ServiceRegistryGovernance 198, 487
ServiceRegistryGovernanceNotifier 204, 483, 487
ServiceRegistryGovernanceValidator 199200,
483
ServiceRegistryNotifier 204, 483, 487
ServiceRegistryNotifierJMS 213
ServiceRegistryRepository 282, 285286, 294, 412
ServiceRegistryRepositoryProxy 293294
ServiceRegistrySession 198, 487
ServiceRegistryStatus 200203, 210
return codes 202
ServiceRegistryValidationException 200202, 210
ServiceRegistryValidator 199, 483
ServiceRegistryWebServiceException 142
Services Management workspace 663664
overview 663
Services Overview 666668
setenv.bat 265266, 269, 271, 275280, 810
904
setenv.sh 268, 279280

ShowPreferences 394
Simple Object Access Protocol
body 27
defined 27
encoding rules 27
envelope 27
headers 27
message format 27
remote procedure call representation 27
transports 27
SimpleTypeDefinition 111, 134
situation 678690
attribute tables 681682
overview 679
predefined 680
Fault_610 680
MaxMessageSize_610 680
MaxResponseTimeCritical_610 681
MaxResponseTimeWarning_610 681
MessageArrivalClearing_610 681
MessageArrivalCritical_610 681
MessageSize_610 680
ResponseTimeCritical_610 681
ResponseTimeWarning_610 681
Situation Event Console 875
SLSBImportBinding 111, 385
SMO
See service message objects
SOA
See service-oriented architecture
SOA Foundation 6
SOA governance 4049, 57, 6465, 7677,
157244, 461509
See also governance
auditing 77
configuring 461509
defined 40
GovernanceRecord 167187
governed object 159
lifecycle 158187, 476482
WSRR default 163167
assemble 165
created 164
deploy 165
manage 166
model 164
retired 167
making an object governable 158
notification 76
root object 168
service definition 43
service deployment lifecycle 43
active 44
deprecate 44
plan 44
sunset 44
test 44
service message model 46
service migration 45
service monitoring 47
service ownership 47
service registry 46
service security 48
service testing 48
service versioning 45
validation 76
SOA lifecycle 5, 711, 158187, 476482
See also lifecycle
Assemble 8
definitions 160
Deploy 9
lifecycle flow 11
Manage 10
Model 8
state machine 159
SOA management 3639, 626631
Access Services 13
Business Application Services 13
17
Information Services 13
Infrastructure Services 18
Interaction Services 12
IT Service Management 17
Partner Services 14
Process Services 12
SOAP
See Simple Object Access Protocol
SOAP API 139144
bsrURI 141
DataGraphType 140
portType 142
PropertyQueryResult 141
WSRR type 140
SOAPAddress 384
SOAPAddress relationships 241
SOAPBinding 134, 384
SOAPBinding relationships 237
SOAPPort 134
SRDispatchVirtualService 790, 794, 820
SRGetVirtualService 790791
SRGovernanceValidator 209
SRProcessVirtualService 790, 793
SrrAuthCheckedPolicyXacml 196
SrrAuthzRoleMappingXacml 196
srrCreate 190, 193
srrDelete 190, 194
SRRetrieveEntity 791, 797
SRRetrieveITService 791, 795
srrManageGov 190, 194
srrRetrieve 190, 193
srrTransition 190, 194
srrUpdate 190, 194
SRTemplateValidator 209
SRXMLHelper 123124, 127
state 167
defined 160
state machine 159, 861
static binding 22, 58
static programming model 100
Stop 521
Subscription 385
supertypes 111, 114
supported APIs 74
Swift 867
T
target property 191
taxonomies 87
TCORE
See Tivoli Common Object Repository
TDW
See Tivoli Data Warehouse
TEC
See Tivoli Enterprise Console
TEMA
Index
905
See Tivoli Enterprise Monitoring Agent

templates 8889
TEMS
See Tivoli Enterprise Monitoring Server
TEPS
See Tivoli Enterprise Portal Server
overview 871
Tivoli Common Object Repository 656
Tivoli Composite Application Manager
Candle product integration 875
overview 634
Tivoli Composite Application Manager for CICS
Transactions 635
overview 874
Tivoli Composite Application Manager for IMS
Transactions
overview 874
Tivoli Composite Application Manager for Response
Time Tracking 634, 638
overview 873
166, 634, 638, 640653
components 647
integration scenarios with WebSphere Service
Registry and Repository 654
overview 641, 870, 873
product features 644
situation 678690
overview 679
predefined 680
Event Handler 687689, 698
configuring 731746
event properties 737
installation 729730
Tivoli Composite Application Manager for WebSphere 635, 638
overview 873
Tivoli Data Warehouse 640
Tivoli Enterprise Console 638, 687, 689, 729, 733,
739, 746, 752754
Tivoli Enterprise Monitoring Agent 875
overview 638
Tivoli Enterprise Monitoring framework 636640,
692, 746
Tivoli Enterprise Monitoring Server 875
overview 636
906
Tivoli Enterprise Portal 875876

Tivoli Enterprise Portal clients
overview 637
Tivoli Enterprise Portal Server 875
overview 637
Tivoli Federated Identity Manager
overview 872
Tivoli Management Framework 753
Tivoli management services 875
Tivoli Monitoring 638, 875
Tivoli OMEGAMON XE for Messaging
overview 870
transition script 307
treat as 110
trustStore 430
types 27
U
UDDI
See Universal Description, Discovery, and Integration
UML 2.0 861
Unified Service Metadata 329
Universal Description, Discovery, and Integration
defined 28, 65
update method 205
updateConfig script 307
updateConfiguration 207, 287, 322, 412
upgrading
279
URLEndpoint 820
Use Case 861
user defined relationships 213, 243244
user interfaces 73
Eclipse plug-in 73, 415451
Web interface 73
user permission 195
UserDefinedProperty 114
UserDefinedRelationship 114
V
validation 76
ValidationProperties 207
validators 197203
chains 210
developing custom validators 483486
interfaces 199202
create method 200
delete method 201
update method 200
validate method 202
properties 207
ViewDetail 405
VSAM 869
W
WASPORT 267268, 276278
Web interface 73
Web Ontology Language 16, 87, 307308, 322,
661
defined 70
Web Service bindings 517
Web Service Federation Language (WS-Federation) 872
Web services
and SOA 25
client 136
core elements
extensible markup language 26
Simple Object Access Protocol 27
SOAP 27
Universal Description, Discovery, and Integration 28
XML 26
installation 546
Web services API 136144
EJB client 136
Web services client 136
Web Services Description Language 16, 25, 58,
6768, 8081, 89, 91, 9496, 126, 179, 329331,
335, 516, 532, 657, 660
binding 28, 95
CICS 826
creating using Java API 125
defined 27, 54
import Web Services Description Language documents 500
message 27
operation 28
parsing 67, 82, 90, 96, 219, 230
port 28
port type 28, 94
publishing from CICS 842
publishing from z/OS 834
retrieve 435
retrieving from z/OS 847
searching for 417
service 28, 95
service binding definitions 94
service endpoint definitions 94
service interface definitions 94
types 27
versions 662
Web Services Inspection Language
defined 28
Web UI 144154, 327379, 381413
Administration 331
Classification Systems 330
collection 151152, 401410
concepts 370379
See also concepts
concepts and architecture 144154
customizing 381413
definition files 146154
collection 151152
detail 152
hierarchy 147
navigation 150
perspective 147
query 150
detail 152
layout 145147
My Service Registry 330
navigation 150
navigation tree 390394
perspective 147, 394400
properties 335346
publishing documents 331335
query 103118, 150, 330, 382390
quick search 329
relationships 347357
Index
907
searching the registry 363369

Service Documents 330
Service Metadata 330
Unified Service Metadata 329
using 329331
Web user interface
See Web UI
WebService 661
WebServiceExportBinding 111, 385
WebServiceImportBinding 111, 385
WebSphere 526
WebSphere Adapter bindings 518
installing 254256
WebSphere Application Server Base Edition
overview 866
WebSphere Application Server Express Edition
overview 866
WebSphere Application Server ND
installing 277279
WebSphere Application Server Network Deployment
overview 866
WebSphere Broker JMS Transport 775
WebSphere Business Modeler 62
overview 860
WebSphere Business Monitor
overview 869
WebSphere Community Edition (CE)
overview 866
WebSphere Developer for zSeries V6.0.1 864
key terms 514
structure 515521
WSRR definition 536543
WebSphere ESB
See WebSphere Enterprise Service Bus
WebSphere Extended Deployment (XD)
overview 866
WebSphere Information Integration Server
overview 869
WebSphere Information Server 63
WebSphere Integration Developer 6263,
417418, 431, 513, 520, 526, 860
overview 865
WebSphere Message Broker 771823
components 776
908
supported transports
WebSphere Broker JMS Transport 775
WebSphere MQ Enterprise Transport 775
WebSphere MQ Mobile Transport 775
WebSphere MQ Multicast Transport 775
WebSphere MQ Real-time Transport 775
WebSphere MQ Telemetry Transport 775
WebSphere MQ Web Services Transport
775
WebSphere Message Broker V6 Client for WebSphere Service Registry and Repository 382,
771823
installation 780786
overview 786789
patterns 803823
setting up 809823
prerequisites 779
WebSphere MQ bindings 518
WebSphere MQ Enterprise Transport 775
WebSphere MQ JMS bindings 517
WebSphere MQ Mobile Transport 775
WebSphere MQ Multicast Transport 775
WebSphere MQ Real-time Transport 775
WebSphere MQ Telemetry Transport 775
WebSphere MQ Web Services Transport 775
WebSphere Portal
overview 868
overview 868
See also service registry and repository
administration
command line 283
JMX 282, 292298
wsadmin 282, 285292
wsadmin scripts 321323
authorization policy file 196
concepts 370379
See also concepts
configuration 283285
See also configuration
supported configurations 284
content model
See information model

deploying 265275
Eclipse UI 416451
See also Eclipse UI
Environment Promotion 319321
defined 319
sample script 319
impact analysis 213244, 499509
import/export 311318
export 311
import 313
information model 7172, 79118
See also information model
BaseObject 101103
document types 8998
query 103118, 382390
Service Data Objects 99101
templates 8889
XPath 99
installing 258264
integration scenarios with Tivoli Composite Application Manager for SOA 654
limits 5966
plugins 197213, 482499
See also plugins
pre-requisite software 249
properties 335346
publishing documents 331335, 438439
relationships 347357
See also relationships
remote DB
installing 275277
requirements 248249
role mapping file 196
searching the registry 363369, 431435
security 187196, 274, 285, 462476
See also security
permission 189195
See also permission
roles 187

SOA governance 4049, 57, 6465, 7677,
157244
See also SOA governance
auditing 77
notification 76
validation 76
supported databases 248
supported platforms 248
topology selection criteria 249
upgrading 279
Web UI 144154, 327379, 381413
See also Web UI
WebSphereCell 660
WebSphereCluster 660
WebSphereNode 660
WebSphereServer 660
WESB
See WebSphere Enterprise Service Bus
WID
See WebSphere Integration Developer
WMB
See WebSphere Message Broker
wsadmin
discover WSRR MBean notifications 289
invoke operations on WSRR Mbean 289
script
import and export of WSRR entities
exportMetaData 322
importMetaData 322
managing access control policy
addRole 323
getRoles 323
persistPolicy 323
removeAllRoles 323
Index
909
removeRole 323
managing configuration
managing lifecycles
managing ontologies
setting up 285
troubleshooting WSRR administration 291
administration 282, 285292
administration scripts 321323
WS-BPEL
See Business Process Execution Language for
Web Services
WSDL
See Web Services Description Language
WSDL2Java 138
WSDLBinding 105, 133134, 384
WSDLBinding relationships 235
WSDLDocument 88, 104, 116, 126127, 133, 140,
168, 191, 384, 398, 487
WSDLDocument relationships 225
WSDLMessage 133134, 384
WSDLMessage relationships 233
WSDLOperation 133134, 384, 507
WSDLOperation relationships 231
WSDLPart 133, 384
WSDLPart relationships 234
WSDLPort 105, 133135, 140, 384, 486487
WSDLPort relationships 239
WSDLPortType 118, 126, 133135, 384
WSDLPortType relationships 230
WSDLService 105110, 116, 133135, 140,
383385, 398
WSDLService relationships 238
WSEndpoint 660
WSIL
See Web Services Inspection Language
WSOperation 660661
WS-Policy 81, 89, 98
WSPort 659, 661
WSPortType 661
910

WSRR type
SOAP 140
wsrr.properties 782783
wsrrcli 299
wsrrcli.bat 300
wsrrcli.conf 300
wsrrcli.sh 300
wsrrcli.conf 811
WSRRCodeSDOClient 137
WSRRConnectionFactory 302
WSRRLocation 733, 741
WSRRPropertyName 735
WSRRPropertyValue 736
wsrrsetparms 782, 784
X
XACML
See Extensible Access Control Markup Language
XML
See extensible markup language
XML metadata 98
XML Path Language
See XPath
XML Pointer Language 99
XML Schema Definition 16, 81, 89, 9193
defined 27, 54
import 126
include 126
parsing 67, 82, 85, 90, 93
redefine 126
XML Services for the Enterprise (XSE) 864
XMLDocument 133, 168, 191, 384
XMLElement 384
XPath 72, 99, 114
defined 99
XPointer
See XML Pointer Language
XSD
See XML Schema Definition
XSD files 111, 116
XSDAttribute 384
XSDComplexType 384
XSDDocument 133, 168, 191, 384
XSDDocument relationships 227
XSDSimpleType 384
XSLT
See Extensible Stylesheet Language Transformations

XSLT editor 607608
XSLT mapping 606607
XSLTransformationRequest 602, 606, 613
XSLTransformationResponse 607
Index
911
912
WebSphere Service Registry

and Repository Handbook
(1.5 spine)
1.5<-> 1.998
789 <->1051 pages
Back cover
WebSphere Service
Registry and
Repository Handbook
Best practices
Sample integration
scenarios
SOA governance
Service-oriented architecture offers the promise of business agility

and resilience through reuse, loose coupling, flexibility,
interoperability, integration and governance. These are realized by
separating service descriptions from their implementations, and
using this descriptive metadata across the service lifecycle.
Standards-based service metadata artefacts, such as Web Service
Description Language, XML schema, policy or Service Component
Architecture documents, capture the technical details of what a
service can do, how it can be invoked, or what it expects other
services to do. Semantic annotations and other metadata can be
associated with these artefacts to offer insight to potential users of
the service about how and when it can be used, and what
purposes it serves.
IBM WebSphere Service Registry and Repository (WSRR) is the
master metadata repository for service interaction endpoint
descriptions. As the integration point of service metadata, WSRR
establishes a central point for finding and managing service
metadata. Once service metadata is placed in WSRR, visibility is
controlled, versions are managed, proposed changes are analyzed
and communicated, and usage is monitored.
This IBM Redbook discusses the architecture and functions of IBM
WebSphere Service Registry and Repository along with sample
integration scenarios that can be used as examples for
implementing WebSphere Service Registry and Repository in a
customer service-oriented architecture environment.
SG24-7386-00
ISBN 0738489972
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
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

Websphere Service Registry and Repository Handbook: Front Cover

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Websphere Service Registry and Repository Handbook: Front Cover

Uploaded by

Copyright:

Available Formats

Front cover

Sample integration scenarios

International Technical Support Organization

First Edition (March 2007)

Copyright IBM Corp. 2007. All rights reserved.

2.1.2 The limits of WebSphere Service Registry and Repository . . . . . . . 59