InfoSphere MDM Server V9.0: Developers Guide MDMDevelopers

User Manual:

Open the PDF directly: View PDF .
Page Count: 856

Download
Open PDF In Browser	View PDF

IBM InfoSphere Master Data Management Server

Licensed Materials – Property of IBM

InfoSphere Master Data Management Server Version 9.0
Developers Guide

IBM InfoSphere Master Data Management Server

Licensed Materials – Property of IBM

InfoSphere Master Data Management Server Version 9.0
Developers Guide

Licensed Materials – Property of IBM

Note
Before using this information and the product it supports, read the general information under Appendix A, “Notices,” on
page 817.

Edition Notice
This edition applies to version 9.0.0 of IBM InfoSphere Master Data Management Server and to all subsequent
releases and modifications until otherwise indicated in new editions.
This document is licensed to you under the terms of the International Program License Agreement or other
applicable IBM agreement. You must ensure that anyone who uses this document complies with the terms of the
International Program License Agreement and any other applicable IBM agreement.
This document may only be used for your internal business purposes. This document may not be disclosed outside
your enterprise for any reason unless you obtain IBM’s prior written approval for such disclosure.
You may not use, copy, modify, or distribute this document except as provided in the International Program License
Agreement or other applicable IBM agreement.
© Copyright International Business Machines Corporation 1996, 2009.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Licensed Materials – Property of IBM

Contents
Part 1. InfoSphere MDM Server
platform . . . . . . . . . . . . . . 1
Chapter 1. InfoSphere MDM Server
architectural overview . . . . . . . . 3
Understanding components . . . . . . .
Learning the core components layers . . . .
Understanding common components . . . .
Learning the extension framework layers . . .
Understanding behavior extensions . . . .
Understanding data extensions . . . . .
Understanding new transactions . . . .
Creating entity models and extensions with
Workbench tools. . . . . . . . . .
Learning the Request-Response processor . .
Understanding consumers layers . . . . .
Understanding component interactions . . .
Understanding business modules . . . . .
Understanding infrastructure modules . . .
Understanding customization restrictions . .

.
.
.
.
.
.
.

. 4
. 5
. 7
. 9
. 9
. 10
. 10

.
.
.
.
.
.
.

10
10
12
13
14
14
15

Chapter 2. Customizing InfoSphere
MDM Server . . . . . . . . . . . . 17
Understanding extensions . . . . . . . . .
Understanding additions . . . . . . . . . .
Creating extensions and additions . . . . . . .
Creating extensions and additions with InfoSphere
MDM Server Workbench . . . . . . . . . .
Understanding the extension handler component . .
Creating extensions . . . . . . . . . . . .
Starting an extension . . . . . . . . . . .
Extending business objects . . . . . . . . .
To extend business objects . . . . . . . .
Extending database tables for new functions . . .
To create a new extension database table for new
functions . . . . . . . . . . . . . .
To alter an existing core product database table
Defining extended functions in the request and
response framework XSD . . . . . . . . . .
To define extended functions in the Request and
Response framework XSD . . . . . . . .
To define functions in the Response XSD . . .
Understanding transaction context passing and the
DWLControl object . . . . . . . . . . . .
Instantiating and passing transaction contexts . .
Extending a transaction context. . . . . . .
Logging transaction context information . . . .
Creating event behavior extensions . . . . . .
Extending functions through the rules engine . . .
Understanding Java behavior extensions. . . . .
To extend transaction behavior using Java . . .
Creating additions to add new data and
functionality . . . . . . . . . . . . . .
Creating client additions . . . . . . . . .
© Copyright IBM Corp. 1996, 2009

18
18
19
19
20
23
24
24
24
25
26
26
26
26
28
29
29
29
30
31
31
32
33
33
35

To create new business objects . . . . . . .
Registering extended and new business objects . .
To register extended and new business objects in
the metadata repository . . . . . . . . .
Adding metadata to added or extended tables and
columns . . . . . . . . . . . . . . .
To add metadata to added or extended tables
and columns . . . . . . . . . . . . .
To test an extension or addition . . . . . . .
Recognizing extensions and additions in InfoSphere
MDM Server . . . . . . . . . . . . . .
To update product features to recognize
extensions and additions . . . . . . . . .
Accessing samples of extensions and additions . .
Understanding InfoSphere MDM Server runtime
metadata . . . . . . . . . . . . . . .
Maintaining metadata with InfoSphere MDM Server
Workbench . . . . . . . . . . . . . .
Understanding component functions . . . . . .
Using the pureQuery data access layer . . . . .
Using data interfaces to access the database . .
Using pureQuery utility classes. . . . . . .
Understanding component level code. . . . .
Creating pluggable business object queries . . . .
Implementing pluggable business object queries . .
Customizing an existing pluggable business object
query . . . . . . . . . . . . . . . .
Using pureQuery data access layer in pluggable
business object queries . . . . . . . . . .
Understanding the structure of a constant . . . .
Extending the BObjQuery class . . . . . . . .
To extend the BObjQuery class . . . . . . .
To override an existing query . . . . . . .
To create a new query . . . . . . . . . .
To extend the BObjQueryFactory implementation
class . . . . . . . . . . . . . . . .
To register a new factory implementation . . .
Creating a new pluggable business object query . .
To create a new BObjQuery class . . . . . .
To extend and register the appropriate query
factory . . . . . . . . . . . . . . .
Calling the query facility from the component
inquiry method . . . . . . . . . . . .
Implementing SQLJ-based queries . . . . . . .
To create a SQLJ-based pluggable business object
query . . . . . . . . . . . . . . .
Creating a pluggable persistence mechanism . . .
To replace the persistence mechanism . . . .
Using business object query objects for pluggable
persistence . . . . . . . . . . . . .
Customizing an existing pluggable persistence
strategy. . . . . . . . . . . . . . .
To customize a persistence strategy by including
new columns and extension tables. . . . . .
To extend a persistence strategy . . . . . .

35
36
36
37
37
40
40
40
40
41
42
42
43
44
45
45
46
47
49
49
49
50
50
50
51
51
51
51
52
52
52
53
54
56
56
57
58
59
60

iii

Licensed Materials – Property of IBM

Chapter 3. Managing specs and spec
values . . . . . . . . . . . . . . . 61
Understanding specs and the MDM metadata
project . . . . . . . . . . . . . . . .
Learning spec project structure . . . . . . . .
Understanding spec composition . . . . . . .
Understanding spec profiles . . . . . . . . .
Understanding internal spec schemas. . . . . .
Understanding external spec schemas . . . . .
Understanding localized spec schemas . . . . .
Learning national language support (NLS) . . . .
Understanding design considerations and
constraints governing internal spec schemas . . .
Understanding internal schema validations . . . .
Deploying specs to the runtime. . . . . . . .
Using spec values in the runtime . . . . . . .
Adding spec values. . . . . . . . . . . .
Updating spec values . . . . . . . . . . .
Manipulating spec values. . . . . . . . . .
Using AttributeValueBObj path elements . . . .
Using AttributeValueBObj value elements . . . .
Using AttributeValueBObj action elements . . . .
Understanding spec value searches . . . . . .
Understanding spec design considerations for
searchable attributes . . . . . . . . . . .
Understanding deployment considerations for spec
searchable attributes . . . . . . . . . . .
Using spec searchable attributes in the runtime . .
Understanding localized searches . . . . . . .
Understanding multiple criteria search semantics . .
Validating searches . . . . . . . . . . . .
Understanding data type specific considerations . .
Illustrating an end-to-end scenario of a spec and its
usage . . . . . . . . . . . . . . . .
Example: Identifying the required spec attributes
in simple business terms . . . . . . . . .
Example: Creating a spec using the InfoSphere
MDM Server Workbench . . . . . . . . .
Example: Deploying the metadata package for a
spec to the InfoSphere MDM Server runtime . .
Example: Associating a spec with a product . .
Example: Adding a product with values
corresponding to a new spec . . . . . . .
Example: Searching for a product with specific
spec values . . . . . . . . . . . . .

62
63
64
65
66
67
68
69
71
77
78
78
79
80
81
81
82
82
85
85
87
88
88
89
89
90
91
92
93
94
95
96
98

Chapter 4. Understanding InfoSphere
MDM Server common code type
framework . . . . . . . . . . . . . 99
Understanding Code type additions and extensions
Understanding assets generated by the workbench
when adding or extending code types . . . . .
Understanding Web services enablement for code
types . . . . . . . . . . . . . . . .
Example: Extending the
BaseCodeTypeBObjConverter . . . . . . .
InfoSphere MDM Server code type categories . .

101
101
102
103
103

Chapter 5. Understanding InfoSphere
MDM Server common features . . . . 109
iv

InfoSphere MDM Server v9.0: Developers Guide

Adding or extending a data entity . . . . . .
Example: To add or extend a data entity . . .
Populating additional metadata for entries made in
Ext_EntityNameInstancePK.properties . . . . .
Understanding the external validators that support
additional metadata . . . . . . . . . . .
To turn on an external validator . . . . . .

110
110
111
111
112

Chapter 6. Configuring Multi-Instance
Federated Deployment . . . . . . . 113
Understanding federated deployment metadata
configurations . . . . . . . . . . . . .
Understanding federated transaction behaviors . .
Sample: searchPartyFederated response
messages . . . . . . . . . . . . . .
Customizing the federated deployment framework

Chapter 7. Subtyping entities

114
115
116
117

. . . . 119

Knowing when to use entity subtypes . . . . .
Knowing when to use data extensions . . . . .
Creating entity subtypes. . . . . . . . . .
To create an extension subtype to a leaf entity of
a subtype hierarchy . . . . . . . . . .
Supporting subtyped entities in database tables
Configuring entity subtypes . . . . . . . .
Understanding transactions that service subtypes
Processing child objects . . . . . . . . . .
Understanding inquiry transactions . . . . . .
Understanding persistence transactions . . . . .

119
119
120
122
122
122
124
124
125
126

Chapter 8. Understanding entity
suspects management and entity data
stewardship frameworks . . . . . . 129
Understanding the entity suspect management data
model . . . . . . . . . . . . . . . .
Understanding entity suspect management base
classes for EObj and BObj . . . . . . . . .
Learning entity suspect management BObjQuery,
QueryFactory, and ResultSetProcessor classes . . .
Example: EntitySuspectBObjQuery and
EntityMatchResultBObjQuery class diagram . .
Example:
EntitySuspectModuleBObjPersistenceFactory
and EntitySuspectModuleBObjQueryFactory
class diagram . . . . . . . . . . . .
Example: Entity suspect management
GenericResultSetProcessor class diagrams . . .
Understanding EntitySuspectComponent input and
output objects . . . . . . . . . . . . .
Example: EntitySuspectListBObj containing
multiple instances of EntitySuspectBObjs . . .
Example: EntitySuspectBObj containing multiple
instances of EntityMatchResultBObjs . . . .
Example: EntityMatchResultBObj containing
suspect match result information . . . . . .
Example: EntitySuspectSearchBObj containing
search suspect transaction parameters and an
optional domain specific request object . . . .
Understanding entity suspect management
business component level methods . . . . . .

130
130
130
131

132
132
133
134
134
135

135
136

Licensed Materials – Property of IBM
Understanding entity suspect management
controllers . . . . . . . . . . . . . .
Learning entity suspect management code types
Understanding notifications for entity suspect
persistence transactions . . . . . . . . . .
Example: Notification for an entity suspect
persistence transaction . . . . . . . . .
Understanding the entity data stewardship data
model . . . . . . . . . . . . . . . .
Example: Data stewardship data model class
diagram . . . . . . . . . . . . . .
Understanding data stewardship base classes for
EObj and BObj . . . . . . . . . . . . .
Learning data stewardship BObjQuery,
QueryFactory, and ResultSetProcessor classes . . .
Example: Data stewardship BObjQuery,
QueryFactory, and ResultProcessor class
diagrams . . . . . . . . . . . . . .
Understanding EntityDataStewardComponent
input and output objects . . . . . . . . .
Example: ConsolidatedEntityBObj containing an
option target entity object and one or more
entity objects to be collapsed . . . . . . .
Example: SplitEntityRequestBObj containing an
entity id and an entity request object ProductId and ProductRequestBObj . . . . .
Example: EntityListBObj containing a list of
domain specific entities . . . . . . . . .
Example: LinkedEntitiesRequestBObj containing
an entity id and an entity request object ProductId and ProductRequestBObj . . . . .
Understanding entity data stewardship business
component level methods . . . . . . . . .
Understanding entity data stewardship controllers
Understanding soft delete . . . . . . . . .
Learning the generic entity suspect processing and
data stewardship configuration elements . . . .

136
136
138
138
139
139
139
140

. 159
. 159
. 160

.
.
.

. 160
. 160
. 161

. 161

Chapter 12. Configuring Smart
Inquiries . . . . . . . . . . . . . 165

142

Chapter 13. Customizing search SQL
queries . . . . . . . . . . . . . . 169

142
143

143
144
144
144
145

148
148
150
151

Chapter 10. Configuring external
business rules . . . . . . . . . . . 153
Using the extension framework . . . . . . .
Using the external rule framework . . . . . .
Understanding the default rules engine. . . . .
To change the rule engine . . . . . . . .
Understanding considerations in using a Rules
Engine . . . . . . . . . . . . . . .
Understanding rule engine methods . . . . . .
Understanding external rules . . . . . . . .
Example: The matchParty transaction configured
to run in the JRules rule engine . . . . . .
Assigning the rule ID. . . . . . . . . . .

.
.
.

141

140

147
.
.
.
.

Creating keys using the default key generator
Understanding the custom key generator . .
To use your customized key generator class
To use different key generator classes for
different business entities . . . . . .
Understanding pluggable primary keys . .
To use pluggable primary keys . . . .
Understanding unique and persistent ID
generation framework . . . . . . . .

How disabling unused features and tables affects
transactions . . . . . . . . . . . . . . 165
Disabling unused features and tables for Smart
Inquiries . . . . . . . . . . . . . . . 167
Administering Smart Inquiries. . . . . . . 167

Chapter 9. Configuring logging and
error handling . . . . . . . . . . . 147
Understanding InfoSphere MDM Server messages
Understanding unique identifiers for system log
messages . . . . . . . . . . . . . .
Understanding severity levels . . . . . . .
Logging InfoSphere MDM Server messages . .
Adding or extending messages . . . . . .

Chapter 11. Configuring pluggable
keys . . . . . . . . . . . . . . . 159

153
153
154
155
155
155
156
157
157

Understanding the Search framework . . . .
Sample: Searching with SQL queries. . . .
Understanding InfoSphere MDM Server Search
implementation. . . . . . . . . . . .
Comparing search methods. . . . . . . .
Understanding requirements for adding and
editing SQL statements . . . . . . . . .
Customizing search features . . . . . . .
To add prewritten SQL queries . . . . .
To edit prewritten SQL queries . . . . .
Understanding SQL lookup constraints . . . .
Constructing dynamic SQL statements . . . .
To construct dynamic SQL statements . . .
Adding new search input and output . . . .
To add search input and output . . . . .
Understanding business object inheritance. . .
Adding new comparison operators . . . . .
Sample: Adding the custom operator type code

. 170
. 172
. 174
. 175
.
.
.
.
.
.
.
.
.
.
.

176
176
176
177
178
179
180
180
180
180
181
182

Chapter 14. Configuring the service
activity monitoring facility . . . . . . 185
Understanding service activity monitoring facility
information . . . . . . . . . . . . . . 185
Obtaining data from the service activity monitoring
facility. . . . . . . . . . . . . . . . 186
To activate the service activity monitoring facility
188

Chapter 15. Customizing the language
and locale in InfoSphere MDM Server . 189
Defining the supported languages . . . .
Support for errors and code table data . . .
Understanding how InfoSphere MDM Server
handles the user locale . . . . . . . .
Specifying the locale . . . . . . . . .
Specifying the locale when neither language
locale is provided . . . . . . . . .

.
.

. 190
. 190

. . 191
. . 192
or
. . 193

Contents

Licensed Materials – Property of IBM
Specifying the locale when only the language
value is provided . . . . . . . . . . .
Specifying the locale when only the locale value
is provided . . . . . . . . . . . . .
Specifying the locale when both the language
and the locale are provided. . . . . . . .
Understanding how InfoSphere MDM Server
handles the application locale . . . . . . . .
Setting up code table data . . . . . . . . .
Adding additional code table data . . . . .
Understanding InfoSphere MDM Server
behavior when retrieving code table data . . .
Understanding InfoSphere MDM Server
behavior when validating code table data in
transactions . . . . . . . . . . . . .
Adding currency codes . . . . . . . . .
Customizing the database . . . . . . . . .
Customizing column size for text data . . . .
Collating the database . . . . . . . . .

Chapter 16. Defining inquiry levels

193
193
195
195
195
196
197

200
203
204
204
205

207

Objects and transactions that child objects can be
retrieved for . . . . . . . . . . . . .
Modifying inquiry levels . . . . . . . .
Configuring new inquiry levels . . . . .
Configuring a new child for a parent business
object . . . . . . . . . . . . . .
Extending inquiry levels. . . . . . . .
Administering inquiry levels . . . . . .

. 209
. 210
. 210

Chapter 17. Retrieving audit history

211

Understanding criteria for history inquiry
transactions . . . . . . . . . . . . .
Sample: History inquiry transactions . . .
Understanding the audit history tables . . .
Understanding point-in-time history inquiries .
Understanding database considerations for history
inquiry . . . . . . . . . . . . . .

. 207
. 207
. 207

.
.
.
.

211
212
213
214

. 215

Chapter 18. Retrieving historical
information for party or contract
images within a range of dates . . . . 217
Configuring view instances and view drivers. .
History inquiry date range images transactions .
Developer example . . . . . . . . . .
Sample request . . . . . . . . . . .
Sample response . . . . . . . . . .
Code interactions . . . . . . . . . . .
Possible errors . . . . . . . . . . .
Configuring transaction logging to function with
history inquiry date range images . . . . .
Packaging and deployment . . . . . . .

.
.
.
.
.
.
.

217
218
218
218
219
222
222

. 223
. 223

Chapter 19. Storing and retrieving the
Transaction Audit Information Log . . 225
Understanding transaction audit information log
information . . . . . . . . . . . . .
Configuring transaction audit information logs .
To turn TAIL on or off globally . . . . .

InfoSphere MDM Server v9.0: Developers Guide

. 225
. 226
. 226

To configure TAIL logging to use in
synchronous or asynchronous mode . . . .
To turn TAIL on for redundant updates . .
To turn TAIL logging on or off for a particular
external transaction . . . . . . . . .
To turn TAIL logging on or off for a particular
internal transaction . . . . . . . . .
Understanding transaction audit information log
data tables . . . . . . . . . . . . .
Understanding transaction audit information
logging . . . . . . . . . . . . . .
Retrieving transaction audit information log
information . . . . . . . . . . . . .
Understanding getTransactionLog transactions .
Understanding inquiry levels . . . . . . .
Sample: Transaction audit information log
requests . . . . . . . . . . . . .
Setting up new transactions in the transaction
audit information log. . . . . . . . . .
To update the CDBUSINESSTXTP table . .
To update the CDINTERNALTXNTP table. .
To update the BUSINTERNALTXN table . .
To update the INTERNALTXNKEY table . .
To update the EXTERNALTXNKEY table . .
Understanding getTransactionLog elements and
attributes . . . . . . . . . . . . . .

. 227
. 227
. 227
. 227
. 227
. 229
. 229
. 230
. 230
. 231
.
.
.
.
.
.

233
233
234
235
235
236

. 236

Chapter 20. Running parallel tasks
using the Concurrent Execution
Infrastructure (CEI) . . . . . . . . . 239
Understanding the CEI design. . . . . . . .
Learning the CEI API interfaces . . . . . . .
Understanding the CEI queue-based
implementation. . . . . . . . . . . . .
Understanding the CEI sequential implementation
Selecting queue-based versus sequential CEI
implementation. . . . . . . . . . . . .
Understanding CEI workflow . . . . . . . .
Understanding CEI models . . . . . . . . .
Configuring the CEI . . . . . . . . . . .
To configure the WebSphere MQ JMS provider
for WebSphere Application Server . . . . .
To configure the application server MDB listener
port . . . . . . . . . . . . . . .

239
241
242
244
245
245
247
249
250
252

Chapter 21. Setting source values and
data decay . . . . . . . . . . . . 253
Understanding interface specifications . . . .
To enable defaulted source values for an
existing business object . . . . . . . .
Testing source values . . . . . . . . . .
Sample: Testing source values . . . . . .
Learning data decay transactions . . . . . .
Understanding attributes related to data decay .
Configuring data decay . . . . . . . . .
To configure transactions to return data decay
information . . . . . . . . . . . .

. 254
.
.
.
.
.
.

256
257
257
257
258
258

. 258

Chapter 22. Understanding
performance tracking . . . . . . . . 259

Licensed Materials – Property of IBM
Understanding performance tracking statistics
Learning levels of tracking . . . . . . .
Learning performance tracking levels . . .
Example: Performance tracking . . . .
Understanding performance statistics capturing
Using the ARM 4.0 agent . . . . . . .
To enable ARM 4.0 performance tracking .
To disable ARM 4.0 performance tracking .

.
.
.
.
.
.
.

.
.
.
.

259
260
261
261
261
. 264
. 264
. 264

Chapter 23. Aliasing transactions . . . 265
Sample: Transaction Aliasing .
To run aliasing transactions. .

.
.

. 266
. 267

Chapter 24. Configuring the Request
and Response Framework . . . . . . 269
Understanding the Request and Response
Framework . . . . . . . . . . . . . .
Understanding transaction flow . . . . . . .
Understanding DWLServiceController . . . . .
Understanding RequestHandler . . . . . . .
Understanding parser components . . . . . .
Understanding the InfoSphere MDM Server XML
parser . . . . . . . . . . . . . . . .
To use the InfoSphere MDM Server XML parser
Understanding constructor components . . . .
Understanding the InfoSphere MDM Server XML
constructor . . . . . . . . . . . . . .
Understanding the business proxy . . . . . .

269
270
271
274
274
274
274
275
275
276

Chapter 25. Creating composite
transactions using customized
business proxies . . . . . . . . . . 277
Using best practices to develop customized
business proxies . . . . . . . . . . . .
Choosing an appropriate InfoSphere MDM
Server transaction . . . . . . . . . . .
Choosing an appropriate InfoSphere MDM
Server transaction parameter . . . . . . .
Minimizing redundant data returns . . . . .
Caching read-only data . . . . . . . . .
Using base business proxies . . . . . . .
Developing stateless transactions . . . . . .
Implementing customized business proxies . . .
Example: Step 1 – Determining the Request
structure . . . . . . . . . . . . . .
Example: Step 2 – Registering the transaction in
the database . . . . . . . . . . . . .
Example: Step 3 – Adding the transaction name
to the properties file . . . . . . . . . .
Example: Step 4 – Implementing the business
proxy . . . . . . . . . . . . . . .
Example: Step 5 – Deploying the business proxy
with InfoSphere MDM Server . . . . . . .
To run the customized business proxy example

Example: Reusing DWLControl values with
GlobalFields . . . . . . . . . . . . .
Example: Correlating the transactions in the
composite . . . . . . . . . . . . .
Example: Substituting values from another
Request or Response . . . . . . . . . .
Example: Qualifying an object name with
criteria . . . . . . . . . . . . . .
Example: Comparing strings . . . . . . .
Example: Comparing numeric values . . . .
Example: Comparing dates . . . . . . . .
Examples of substitution . . . . . . . .
Creating composite transactions with if-then-else
logic . . . . . . . . . . . . . . . .
Creating composite transactions with looping logic
Providing error messages using the error handling
service. . . . . . . . . . . . . . . .
Creating boolean expressions . . . . . . . .
Examples of boolean expressions . . . . . .
Creating object-set expressions . . . . . . .
Examples of object-set expression. . . . . .
Configuring the composite XML transaction . . .
Understanding requirements for submitting
composite XML transactions . . . . . . . .
Understanding requirements for customizing the
composite response . . . . . . . . . . .

287
288
289
291
292
292
293
293
295
297
299
299
301
302
303
304
305
306

Chapter 27. Understanding the
response publisher . . . . . . . . . 307
Understanding the response publisher and
extension framework . . . . . . . . .
To enable the extension framework for the
response publisher transaction. . . . .
To publish a transaction . . . . . . .

. 307

.
.

. 307
. 308

277
278
278
279
279
279
279
280
280
281
281
282
283
283

Chapter 26. Creating composite XML
transactions . . . . . . . . . . . . 285
Understanding composite XML transaction syntax 286
Understanding basic composite transactions . . . 287

Chapter 28. Understanding batch
transaction processing . . . . . . . 309
Understanding the InfoSphere MDM Server J2SE
batch processor architecture . . . . . . .
Designing J2SE batch input and output . . . .
Running J2SE Batch Processor batch jobs . . .
Configuring the J2SE batch processor . . . .
Managing J2SE batch throughput . . . . . .
Reviewing J2SE errors and logs . . . . . .
Building custom batch jobs for the J2SE Batch
Processor framework . . . . . . . . . .
Understanding the InfoSphere MDM Server
WebSphere Extended Deployment Batch
architecture . . . . . . . . . . . . .
Creating XJCL for batch jobs . . . . . . .
Running XJCL batch jobs . . . . . . . .
Reviewing XJCL errors and logs . . . . . .
Building custom batch jobs for the InfoSphere
MDM Server WebSphere Extended Deployment
batch processor . . . . . . . . . . . .

.
.
.
.
.
.

310
311
312
312
315
316

. 316

.
.
.
.

317
318
321
321

. 321

Chapter 29. Using and configuring
Web Services . . . . . . . . . . . 323
Understanding Web Services . . .
Understanding WSDL file structures.

.
.

Contents

. 323
. 324

vii

Licensed Materials – Property of IBM
Understanding Web Services operations and data
types . . . . . . . . . . . . . . . .
Understanding Web Services invocation . . . .
Making data extensions available through Web
Services . . . . . . . . . . . . . . .
To make data extensions available through Web
Services . . . . . . . . . . . . . .
Understanding data type definitions. . . . . .
To add extension data types . . . . . . .
Understanding business object converters . . . .
To extend business object converters. . . . .
Making additions available through Web Services
Describing Web Service WSDL and XSD files
Implementing Web Services . . . . . . . .
To implement Web Services . . . . . . .
Invoking Web Services . . . . . . . . . .
Invoking Web Services using JAX-RPC . . . . .
To invoke Web Services using JAX-RPC . . .
Invoking Web Services with atomic transactions
To invoke Web Services with atomic transactions
Invoking Web Services with WS-Security . . . .
To invoke Web Services with WS-Security . . .
Invoking Web Services with atomic transactions
and WS-Security . . . . . . . . . . . .
To invoke Web Services with atomic transactions
and WS-Security . . . . . . . . . . .
Configuring Web Services security for WebSphere
Application Server . . . . . . . . . . .
To enable Web Services security for WebSphere
Application Server . . . . . . . . . .
To disable Web Services security for WebSphere
Application Server . . . . . . . . . .

326
337
338
338
338
339
340
340
342
342
343
343
346
346
347
348
349
349
350
351
352
352
353
353

Chapter 30. Using the external Web
Services Adapter . . . . . . . . . . 355
Installing the Web Services Adapter .
Configuring the Web Services Adapter
Web Services interface . . . .
Deprecated Web Services interface

.
.
.
.

355
356
356
357

Chapter 31. Customizing Event
Manager . . . . . . . . . . . . . 359
Understanding Event Manager business rules . .
Understanding the Event Manager design
overview . . . . . . . . . . . . . . .
Understanding events detected by the passage of
time . . . . . . . . . . . . . . . .
Understanding events triggered by a transaction
Understanding explicit events . . . . . . . .
Using Event Manager with InfoSphere MDM
Server . . . . . . . . . . . . . . . .
Understanding the Event Manager data model . .
Setting up definition tables for Event Manager . .
Setting up business systems and business entities
To set up a business system and business entity
for Event Manager . . . . . . . . . .
Setting up event definitions and categories . . .
To set up event definitions and categories for
Event Manager . . . . . . . . . . . .
Setting up business rules for the event definitions

viii

InfoSphere MDM Server v9.0: Developers Guide

359
360
362
363
364
364
365
366
367
367
367
368
368

To define a business rule for an event definition
for Event Manager . . . . . . . . . .
Setting up the processing option for event
detection . . . . . . . . . . . . . . .
To define the processing option for an event
category forEvent Manager . . . . . . . .
Maintaining operational data manually . . . . .
Maintaining operational tables. . . . . . . .
Maintaining the PROCESSCONTROL table . . .
Maintaining the PROCESSACTION table . . . .
Maintaining operational data using transactions
Writing business rules . . . . . . . . . .
Implementing rules using Java . . . . . . .
Writing the business adapter . . . . . . . .
Calling Event Manager from the business system
Detecting events for all configured event categories
Detecting events for explicit event categories . . .
Creating user explicit events . . . . . . . .
Starting time-based event detection . . . . . .
Configuring the EventDetectionScheduleController
Configuring the notification topic . . . . . .

370
370
372
372
372
372
373
374
374
375
376
377
378
379
379
380
381
381

Chapter 32. Setting and administering
the security service. . . . . . . . . 383
Configuring the security service . . . . . . .
Understanding the Security Data Manager . . .
Configuring the user management run time API
Understanding the runtime security service . . .
Understanding the default transaction
authorization provider . . . . . . . . . .
Configuring LDAP transaction authorization
providers . . . . . . . . . . . . . . .
To configure the LDAP transaction authorization
provider . . . . . . . . . . . . . .
Configuring a custom transaction authorization
provider . . . . . . . . . . . . . . .
To configure a custom transaction authorization
provider . . . . . . . . . . . . . .
Using a custom authentication assertions parser
To use a custom authentication assertion parser

384
384
385
386
387
388
389
389
389
390
390

Chapter 33. Controlling the visibility
and accessibility of data . . . . . . 391
Setting Rules of Visibility . . . . . . . . .
Understanding Data Persistency entitlements
Understanding Rules of Visibility permissions
Understanding Rules of Visibility data rules . .
Understanding the Data Entitlement object
model . . . . . . . . . . . . . . .
Creating and refining a rule . . . . . . . .
Setting rule parameters or constraints . . . .
Implementing simple and complex constraint
types . . . . . . . . . . . . . . .
Using the Date Arithmetic operand type . . . .
Understanding how database tables are affected by
Rules of Visibility . . . . . . . . . . . .
Sample: Using RoV rules . . . . . . . . .
Protecting operational resources . . . . . . .
Enabling protected resources . . . . . . .
Implementing authorization . . . . . . .

392
392
394
394
395
397
397
397
398
398
398
399
399
399

Licensed Materials – Property of IBM
Understanding operations on protected
resources . . . . . . . . . . . . .
Setting up access tokens for users and groups
Customizing access to protected resources . .

. 400
400
. 403

Chapter 34. Using the Configuration
and Management components . . . . 405
Understanding configuration . . . . . . . .
Learning the Configuration and Management
architectural overview . . . . . . . . . .
Understanding the stand-alone enterprise
application . . . . . . . . . . . . . .
Understanding J2EE clustered enterprise
application . . . . . . . . . . . . . .
Understanding custom clustered enterprise
application . . . . . . . . . . . . . .
Understanding configuration definitions and
schemas . . . . . . . . . . . . . . .
Understanding Configuration and Management
database structure . . . . . . . . . . . .
Using the Application Configuration Client . . .
Understanding the Configuration class . . . . .
Understanding configuration methods . . . . .
Understanding the ConfigContext class and public
Node getConfigItemsMap() method . . . . . .
Adding configuration nodes and items . . . . .
To add configuration nodes and items . . . .
Broadcasting configuation changes . . . . . .
To broadcasting configuration data changes . .
Working with configuration data . . . . . . .
Understanding configuration elements in the
Configuration and Management component . . .

405
406
406

Chapter 36. Paginating search results

.
.
.
.
.

503
504
506
506
506

.
.

. 507
. 507

. 507

407

Chapter 37. Customizing task
management. . . . . . . . . . . . 509

408

Understanding task management transactions .
Understanding task management activity flow .
Modifying task management . . . . . . .

409
411
414
414
415
416
416
417
417
417
417
419

Chapter 35. Validating data . . . . . 475
Understanding the Validate() method process . .
Understanding external validation . . . . . .
Learning external validation types . . . . . .
Understanding external validation execution
sequence . . . . . . . . . . . . . . .
Understanding validation database tables . . . .
Understanding external validation rules . . . .
Understanding recursive validation against an
object graph . . . . . . . . . . . . . .
Excluding validation for a specific transaction . .
Example: Using external validations . . . . . .
Understanding internal validation process . . . .
Understanding business key validation . . . . .
Learning business key validation framework
components . . . . . . . . . . . . .
Learning business key validation configuration
elements . . . . . . . . . . . . . .
Learning business key validation attribute types
Learning business key validation rules . . . .
Customizing business key validation . . . . .
To define business keys and validation . . . .
To override business key validation logic for a
group . . . . . . . . . . . . . . .
To disable business key validation . . . . .

Understanding the primary activities of the
pagination feature . . . . . . . . . .
Understanding pagination parameters . . .
Configuring pagination . . . . . . . .
Extending pagination. . . . . . . . .
To implement pagination for a new service
To implement pagination for new search
transactions using pre-written queries . .
Handling pagination - special scenarios . .
To handle pagination when the Component
class is delegating the request to another
Component . . . . . . . . . . .

476
476
476
477
478
480
484
485
486
489
490
490
495
496
496
498
498
500
501

503

. 509
. 510
. 512

Chapter 38. Understanding Multi time
zone deployment . . . . . . . . . . 515
To configure the multi time zone deployment
feature . . . . . . . . . . . . . . .
Understanding the requesterTimeZone element . .
To define the requesterTimeZone value . . . .
Understanding time zone changes for Web Services
Implementing the multi time zone deployment
feature . . . . . . . . . . . . . . .
Adding new business objects . . . . . . .
Getting the current system time . . . . . .
Formatting end dates and expiry dates . . . .
Using timestamp data from the request header

516
517
517
518
519
519
520
521
521

Chapter 39. Implementing the Entity
Standardization framework . . . . . 523
Understanding the Entity Standardization
framework . . . . . . . . . . . . . .
To enable and disable the Entity Standardization
framework . . . . . . . . . . . . .
Learning about standardization database tables
Configuring data standardization for business
objects. . . . . . . . . . . . . . . .
To configure standardization for business objects
Understanding standardization constraints . . .
To define internal constraints through metadata
To define external constraints . . . . . . .
To associate constraints with a standardizer . .
Creating custom standardizers. . . . . . . .

523
524
525
526
526
527
528
529
529
530

Chapter 40. Implementing and
configuring the Notification
Framework . . . . . . . . . . . . 531
Understanding the Notification Framework . .
Learning the Notification Framework data
model . . . . . . . . . . . . . .
Understanding notification types and contents
Configuring notifications . . . . . . . .
To enable notifications at the application level
To enable notifications at the type level. . .
Contents

. 531
. 532
533
. 534
534
. 535

Licensed Materials – Property of IBM
To enable notifications at the channel level .
To disable notifications at the application level
To disable notifications at the type level . .
To disable notifications at the channel level .
Creating notifications for data distribution. . .
To create data distribution notifications. . .
Implementing notifications . . . . . . . .
To build notification business objects . . .
Sample notification business object . . . .
To invoke the notification mechanism to send
messages . . . . . . . . . . . . .
Sample notification implementation . . . .

. 535
535
. 535
. 535
. 536
. 536
. 537
. 537
. 537
. 538
. 539

Chapter 41. Understanding the
PIMDataTransformer module . . . . . 541
Understanding PIMDataTransformer module
methods . . . . . . . . . . . . . .
Understanding how the PIMDataTransformer
module uses metadata . . . . . . . . .
Understanding the PIMDataTransformer module
export format . . . . . . . . . . . .
Using the PIMDataTransformer module with ETL
tools . . . . . . . . . . . . . . .
Using the PIMDataTransformer module . . .

. 542
. 542
. 542
. 542
. 543

Chapter 42. External rules for the
Platform domain . . . . . . . . . . 545
Chapter 43. Learning the platform
domain configuration elements. . . . 549

Part 2. Introduction to the Party
domain . . . . . . . . . . . . . 551
Chapter 44. Configuring Suspect
Duplicate Processing . . . . . . . . 557
Suspect category names and descriptions . . .
Suspect Duplicate Processing configuration points
Configuring SDP on or off . . . . . . .
Configuring Persist Duplicate Parties on or off
Customizing critical data elements . . . .
Customizing matching matrices . . . . .
Customizing searching and matching . . .
Customizing adjustments to Party Matching .
Customizing the action to take when suspect
duplicates are found . . . . . . . . .
Configuring SDP notifications . . . . . .
Configuring real-time and offline SDP using
InfoSphere MDM Server Evergreening . . .
Configuring Acxiom AbiliTec integration with
SDP . . . . . . . . . . . . . .
Configuring IBM Information Server
QualityStage integration for SDP . . . . .
Wholly replacing the Suspect Duplicate
Processing implementation . . . . . . .
Configuring external rules for SDP . . . . .
InfoSphere MDM Server party matching matrices
for suspect duplicate processing . . . . . .

InfoSphere MDM Server v9.0: Developers Guide

. 558
558
. 559
559
. 560
. 561
. 563
. 564
. 564
. 566
. 568
. 574
. 574
. 580
. 582
. 590

Match relevancy . . . . . . . . . .
Reading the party matching matrix . . . .
Configuring Critical Data Change processing . .
CDC configuration points . . . . . . .
Configure CDC processing on or off . . . .
Customizing critical data elements . . . .
Bypassing CDC processing . . . . . . .
Customizing the types of critical data changes
allowed in a CDC request . . . . . . .
Determining which business objects have
pending critical data changes . . . . . .
Defining which business objects always use
CDC . . . . . . . . . . . . . .
Defining which business objects are updated
when pending changes are accepted . . . .
Define how suspects are re-identified when
pending changes are accepted . . . . . .

Chapter 45. Configuring Party Search

.
.
.
.
.
.
.

591
591
591
593
594
594
594

. 595
. 595
. 595
. 596
. 596

597

Party search features . . . . . . . . . . .
Party search activity flow . . . . . . . . .
Configuring and customizing Party Search features
Configuring Common Search Exclusion . . .
Configuring the Maximum Search Result Limit
Customizing the InfoSphere MDM Server search
strategy . . . . . . . . . . . . . .
Configuring internal search operations . . . .
Configuring SQL searches in InfoSphere MDM
Server . . . . . . . . . . . . . . .
Configuring search result sorting and ranking
Excluding name standardization during search
Configuring the standardized or nickname
search . . . . . . . . . . . . . . .
Customizing phonetic searches . . . . . .
Customizing phonetic key generation . . . .
Applying configuration settings for phonetic
search . . . . . . . . . . . . . . .
Populating the phonetic key with a batch utility
Configuring minimum wildcard search length
validation . . . . . . . . . . . . .

597
598
599
600
601
601
602
602
610
611
612
612
613
617
618
621

Chapter 46. Standardizing name,
address, and phone number
information . . . . . . . . . . . . 623
When InfoSphere MDM Server uses
standardization . . . . . . . . . . . . .
InfoSphere MDM Server standardization overview
Standardizers . . . . . . . . . . . . .
Using the Default standardizer . . . . . .
Using QualityStage for standardization . . . .
Using Trillium for standardization . . . . .
Overriding the standardization for business objects
To override standardization on an address
object . . . . . . . . . . . . . . .
Settings and results for
StandardFormatingIndicator and
StandardFormatingOverride . . . . . . .
Settings and results for
StandardFormattingIndicator . . . . . . .
About the Refresh AbiliTec link . . . . . . .

623
624
628
629
629
634
635
636

636
637
638

Licensed Materials – Property of IBM

Chapter 47. Customizing Summary
Data Indicators. . . . . . . . . . . 641
Summary Data Indicator transactions . . . .
How Summary Data Indicators affect transactions
Configuring Summary Data Indicators . . . .
Extending Summary Data Indicators . . . .
Administering Summary Data Indicators . . .

. 641
641
. 642
. 643
. 643

Chapter 48. Customizing Party Privacy 645
Customizing Party Privacy preferences .
Code Interactions design overview . .

.
.

Chapter 49. Customizing Campaigns

. 645
. 646

647

Customizing Campaign business key validation
rules . . . . . . . . . . . . . . .
Modifying retrieve campaign-associated details
rules . . . . . . . . . . . . . . .

. 647
. 647

Chapter 50. Configuring the Know
Your Customer compliance feature . . 649
Understanding Know Your Customer compliance
transactions . . . . . . . . . . . . .
Extending the Know Your Customer compliance
feature . . . . . . . . . . . . . .
Configuring Know Your Customer compliance
external validation rules . . . . . . . . .
Configuring Know Your Customer compliance
business logic external rules . . . . . . .
Configuring Know Your Customer compliance
business key validations . . . . . . . . .
Configuring Event Manager for Know Your
Customer compliance . . . . . . . . .
Understanding compliance requirements for
deleting parties . . . . . . . . . . . .

. 649
. 649
. 650
. 650
. 651
. 651
. 652

Chapter 51. Configuring Party
Demographics . . . . . . . . . . . 653
Chapter 52. Customizing Party Life
Events . . . . . . . . . . . . . . 655
Party data for event detection rules .
Event detection rules . . . . . .
Party Event transactions . . . . .
Configuring InfoSphere MDM Server
Manager to use Party Life Events. .

. . . .
. . . .
. . . .
and Event
. . . .

. 655
. 656
. 656
. 657

Chapter 53. Deleting party information
from InfoSphere MDM Server . . . . 659
Transactions affected by the Delete Capability
Extending the Delete capability . . . . .

.
.

. 659
. 663

Chapter 54. Integrating IBM
InfoSphere Information Server
QualityStage with InfoSphere MDM
Server . . . . . . . . . . . . . . 665
Prerequisites for activating QualityStage features in
InfoSphere MDM Server. . . . . . . . . . 666

Activating QualityStage features in InfoSphere
MDM Server . . . . . . . . . . . . .
Installing DataStage and QualityStage jobs . .
Deploying services for the RMI interface using
WISD . . . . . . . . . . . . . . .
Configuring client QualityStage integration . .
Deploying services for Web Services using
WISD . . . . . . . . . . . . . . .
Configuration settings for QualityStage and
InfoSphere MDM Server. . . . . . . . . .
Configuring security enabled servers . . . . .
To share LTPA between InfoSphere MDM Server
and IBM InfoSphere Information Server . . .
To enable security attribute propagation . . .
QualityStage name and address standardization in
InfoSphere MDM Server. . . . . . . . . .
Using QualityStage in Suspect Duplicate
Processing . . . . . . . . . . . . . .
Customizing services that use InfoSphere
Information Server Web services . . . . . . .

667
667
668
669
670
671
672
672
673
673
673
673

Chapter 55. Integrating AbiliTec with
InfoSphere MDM Server . . . . . . . 675
Definitions of terms used when discussing AbiliTec
integration . . . . . . . . . . . . . .
References for more AbiliTec information . . . .
About the Refresh AbiliTec link . . . . . . .
Configuring AbiliTec in InfoSphere MDM Server
Customizing and extending the AbiliTec link in
InfoSphere MDM Server. . . . . . . . . .
Customizing the external mapping rules . . .
New AbiliTec link accessor . . . . . . . .
Evergreening the Abilitec link . . . . . . . .
Configuring the AbiliTec link . . . . . . . .
Modifying the Evergreening rules . . . . . .
Modifying InfoSphere MDM Server extensions for
Evergreening . . . . . . . . . . . . .
The AbiliTec link in Suspect Processing. . . . .
Match category adjustment . . . . . . . .
Reidentify suspects . . . . . . . . . .
Manual AbiliTec link management . . . . . .
External validation of the AbiliTec link . . . .
Refresh AbiliTec link sample XML . . . . . .
Request XML . . . . . . . . . . . .
Response XML . . . . . . . . . . . .

676
676
676
677
678
678
681
681
682
682
682
683
683
683
683
684
684
684
684

Chapter 56. Integrating Dun &
Bradstreet with InfoSphere MDM
Server . . . . . . . . . . . . . . 687
D&B matching integration scenario . . . . .
Matching profiles and file layouts for D&B
integration . . . . . . . . . . . . .
Running the InfoSphere MDM Server batch
matching process . . . . . . . . . . .
Customizing matching profiles and parsers .
Customizing the behavior of the
refreshPartyExtIdentification transaction for D&B
integration . . . . . . . . . . . . .
Customizing external business rules for D&B
integration . . . . . . . . . . . . .
Contents

. 688
. 689
. 693
. 694

. 696
. 697

Licensed Materials – Property of IBM
Customizing the D&B Accessor .

. 699

Chapter 57. Integrating Entity Analytic
Solutions products with InfoSphere
MDM Server . . . . . . . . . . . . 701
EAS extension and configuration points . . .
EAS integration design overview . . . . . .
EAS data and transaction mappings . . . . .
EAS code value mappings . . . . . . . .
InfoSphere MDM Server transaction mapping to
EAS . . . . . . . . . . . . . . .
Configuring and extending the EAS integration
Extending the integration for EAS UMF or
InfoSphere MDM Server business object
extensions . . . . . . . . . . . .
Configuring source system types . . . . .
Configuring the transport mechanism . . .
Configuring UMF message details . . . .

.
.
.
.

Chapter 66. Configuring Product
Search . . . . . . . . . . . . . . 759

. 710
713

759

.
.
.
.

714
717
717
717

Chapter 59. Party domain
configuration elements . . . . . . . 723

Part 3. Introduction to the Product
domain . . . . . . . . . . . . . 725
Chapter 60. Configuring the product
type hierarchy . . . . . . . . . . . 729
Specifying required attributes for a product type
729
Creating new product types . . . . . . . . 730
When to create hard versus soft product types
731
Creating a hard product type . . . . . . . 732

Chapter 61. Configuring product
structures and relationships . . . . . 739
.
.
.
.
.
.
.

739
741
741
743
744
744
744
745

Chapter 62. Managing product data in
multiple languages . . . . . . . . . 747
Chapter 63. Managing product terms
and conditions . . . . . . . . . . . 749
Terms and Conditions rule framework . . . .
How to use the Terms and Conditions rule .
Setting up a new Terms and Conditions rule
External validations for terms and conditions. .

xii

InfoSphere MDM Server v9.0: Developers Guide

Chapter 65. External validators for
products . . . . . . . . . . . . . 757

702
703
705
710

Chapter 58. External rules for the
Party domain . . . . . . . . . . . 719

Understanding composition products and bundles
Understanding association products . . . . .
Understanding root and variant products . . .
Understanding product structure strategies . .
Learning the ResolveProductStrategy rule . .
Learning the BundleStrategy rule . . . . .
Learning the VariantStrategy rule. . . . .
To create new product structure strategies . .

Chapter 64. Configuring product
category attributes . . . . . . . . . 755

. 750
. 752
752
. 753

Product search features . . . . . . . . . .
Configuring and customizing Product Search
features . . . . . . . . . . . . . . .
Customizing the InfoSphere MDM Server search
strategy . . . . . . . . . . . . . .
Configuring SQL searches in InfoSphere MDM
Server . . . . . . . . . . . . . . .

759

759
760

Chapter 67. Managing product
suspects and product data
stewardship . . . . . . . . . . . . 763
Managing product suspects. . . . . . .
Sample: Input sample of addProductSuspect
Managing product data stewardship. . . .
Collapsing multiple products . . . . . .
Splitting products . . . . . . . . . .
Previewing collapse multiple products . . .
Getting linked products . . . . . . . .
Understanding how product resolution impacts
existing transaction behavior . . . . . .

.
.
.
.
.
.
.

763
764
765
765
767
768
768

. 768

Chapter 68. External rules for the
Product domain . . . . . . . . . . 771
External rules for product category attributes.
Identifying products and categories by
equivalencies . . . . . . . . . . .

. 772

. 775

Chapter 69. Product domain
configuration elements . . . . . . . 777

Part 4. Introduction to the Account
domain . . . . . . . . . . . . . 779
Chapter 70. Entity model for the
Account domain . . . . . . . . . . 783
Chapter 71. Managing terms and
conditions for agreements . . . . . . 785
Chapter 72. External validators for the
Account domain . . . . . . . . . . 787
External validators for the Contract business
Managed account validators . . . .
Value Package validators . . . . .
Generic Account domain validators . .
External validators for ContractRelationship
External validators for Account terms and
conditions . . . . . . . . . . .

entity
. . .
. . .
. . .
. . .
.

787
788
789
789
790

. 790

Licensed Materials – Property of IBM

Chapter 73. Example of how to use
managed accounts . . . . . . . . . 793

Chapter 76. Account domain
configuration elements . . . . . . . 811

Managing value packages . . . . . .
Samples of managing value packages .
Extending a value package . . . . . .

Chapter 77. Product information and
support . . . . . . . . . . . . . . 813

.
.
.

. 793
. 794
. 803

Chapter 74. Agreement business
services. . . . . . . . . . . . . . 805
TermCondition Rules framework . . . . . .
getAllTermsConditionsByEntityID . . . . .
EvaluateTermConditions. . . . . . . . .
EvaluationTermConditions – TermConditionRule
Framework . . . . . . . . . . . . .
EvaluationTermConditions – Response . . . .
Rules available in DefaultExternalRules . . .

. 805
. 805
. 805

Part 5. Appendixes . . . . . . . . 815
Appendix A. Notices . . . . . . . . 817
Appendix B. Trademarks . . . . . . 821

. 806
. 807
. 808

Index . . . . . . . . . . . . . . . 823

Chapter 75. External rules for the
Account domain . . . . . . . . . . 809

Contents

xiii

Licensed Materials – Property of IBM

xiv

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Part 1. InfoSphere MDM Server platform
Chapter 1, “InfoSphere MDM Server architectural overview,” on page 3
Chapter 2, “Customizing InfoSphere MDM Server,” on page 17
Chapter 3, “Managing specs and spec values,” on page 61
Chapter 4, “Understanding InfoSphere MDM Server common code type
framework,” on page 99
Chapter 5, “Understanding InfoSphere MDM Server common features,” on page
109
Chapter 6, “Configuring Multi-Instance Federated Deployment,” on page 113
Chapter 7, “Subtyping entities,” on page 119
Chapter 8, “Understanding entity suspects management and entity data
stewardship frameworks,” on page 129
Chapter 9, “Configuring logging and error handling,” on page 147
Chapter 10, “Configuring external business rules,” on page 153
Chapter 11, “Configuring pluggable keys,” on page 159
Chapter 12, “Configuring Smart Inquiries,” on page 165
Chapter 13, “Customizing search SQL queries,” on page 169
Chapter 14, “Configuring the service activity monitoring facility,” on page 185
Chapter 15, “Customizing the language and locale in InfoSphere MDM Server,”
on page 189
Chapter 16, “Defining inquiry levels,” on page 207
Chapter 17, “Retrieving audit history,” on page 211
Chapter 18, “Retrieving historical information for party or contract images
within a range of dates,” on page 217
Chapter 19, “Storing and retrieving the Transaction Audit Information Log,” on
page 225
Chapter 20, “Running parallel tasks using the Concurrent Execution
Infrastructure (CEI),” on page 239
Chapter 21, “Setting source values and data decay,” on page 253
Chapter 22, “Understanding performance tracking,” on page 259
Chapter 23, “Aliasing transactions,” on page 265
Chapter 24, “Configuring the Request and Response Framework,” on page 269
Chapter 25, “Creating composite transactions using customized business
proxies,” on page 277
Chapter 26,
Chapter 27,
Chapter 28,
Chapter 29,
Chapter 30,
Chapter 31,

“Creating composite XML transactions,” on page 285
“Understanding the response publisher,” on page 307
“Understanding batch transaction processing,” on page 309
“Using and configuring Web Services,” on page 323
“Using the external Web Services Adapter,” on page 355
“Customizing Event Manager,” on page 359

Chapter 32, “Setting and administering the security service,” on page 383
Chapter 33, “Controlling the visibility and accessibility of data,” on page 391
Chapter 34, “Using the Configuration and Management components,” on page
405
© Copyright IBM Corp. 1996, 2009

Licensed Materials – Property of IBM

Chapter 35,
Chapter 36,
Chapter 37,
Chapter 38,
Chapter 39,

“Validating data,” on page 475
“Paginating search results,” on page 503
“Customizing task management,” on page 509
“Understanding Multi time zone deployment,” on page 515
“Implementing the Entity Standardization framework,” on page 523

Chapter 40, “Implementing and configuring the Notification Framework,” on
page 531
Chapter 41, “Understanding the PIMDataTransformer module,” on page 541
Chapter 42, “External rules for the Platform domain,” on page 545
Chapter 43, “Learning the platform domain configuration elements,” on page
549

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 1. InfoSphere MDM Server architectural overview
IBM® InfoSphere™ Master Data Management Server (InfoSphere MDM Server) is
an enterprise application that provides a unified operational view of your
customers, accounts, and products and an environment that processes updates to
and from multiple channels.
It aligns these front office systems with multiple back office systems in real time,
providing a single source of truth for master data. InfoSphere MDM Server uses a
component-based Extensible Markup Language (XML) and Java™ 2 Enterprise
Edition (J2EE) architecture to rapidly integrate with other systems and deliver
flexibility and scalability.
InfoSphere MDM Server is an enterprise application that can either be used in its
standard configuration, or modified through customization. You can customize
InfoSphere MDM Server through a number of externalized features that control its
operation.
The InfoSphere MDM Server Workbench can be used to create and extend
InfoSphere MDM Server and associated Web-based user interfaces to aid with
stewardship over the managed information. The Workbench provides a modeling,
code generation, Java development environment, and testing environment.
The Workbench supports an iterative approach to development with full
round-tripping support. The Workbench is integrated with IBM Rational® Software
Architect to provide access to standard software development capabilities such as:
v
v
v
v
v

Requirements management
Source code control
Asset management
Deployment
Testing

This documentation focuses on the InfoSphere MDM Server backend systems,
especially from the system development and administration point of view. It also
includes many method descriptions and code samples for developers. The major
points of discussion relate to the externalized portions of the infrastructure
components, the server-side tier components, and how both can be used to extend
InfoSphere MDM Server functionality.
This section contains high-level information on the InfoSphere MDM Server
architecture to help you understand how it can be customized to meet your needs.
InfoSphere MDM Server is a J2EE application conforming to the J2EE 1.4 standard.
It is designed and built using a Service Oriented Architecture (SOA) and is
composed of loosely coupled multiple infrastructure and business components. The
InfoSphere MDM Server services tier is deployed on a J2EE application server and
the database tier uses a relational database management system. For a complete list
of supported application servers, databases, and other software, see the IBM
InfoSphere Master Data Management Server Installation Guide.
The business services are made up of a collection of services provided with the
product and any custom services built using the InfoSphere MDM Server
© Copyright IBM Corp. 1996, 2009

Licensed Materials – Property of IBM

Workbench. In addition to the business services, the service tier also offers
administration services and a Web-based business administration user interface.
You can interface with InfoSphere MDM Server using one of the supported
interfaces including:
v RMI
v JMS
v Batch
v Web Services
InfoSphere MDM Server supports an XML based transaction interface. It comes
with a request and a response schema, defined in XSD. All input XML files must
conform to the request schema, while InfoSphere MDM Server always responds
with an XML conforming to the response schema. The schemas define the structure
of the business objects, which should be passed in or returned from InfoSphere
MDM Server services. For a complete list of all the available services and the
corresponding input and output business objects, refer to the IBM InfoSphere Master
Data Management Server Transaction Reference Guide. You can also interface with
InfoSphere MDM Server using data formats other than XML.
Additionally, InfoSphere MDM Server also provides the ability to accept batch
feeds for transactions.
Internally, InfoSphere MDM Server consists of two categories of modules, which
are business modules and infrastructure modules.
In this section, you will learn:
“Understanding components”
“Learning the core components layers” on page 5
“Understanding common components” on page 7
“Learning the extension framework layers” on page 9
“Learning the Request-Response processor” on page 10
“Understanding consumers layers” on page 12
“Understanding component interactions” on page 13
“Understanding business modules” on page 14
“Understanding infrastructure modules” on page 14
“Understanding customization restrictions” on page 15

Understanding components
The InfoSphere MDM Server blueprint describes the major components in the
different tiers and layers of the InfoSphere MDM Server architecture.
The diagram visually represents the tiers and layers of InfoSphere MDM Server.
The following sections describe these tiers and layers in more detail.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

MDM Consumers
Data
Stewardship
UI

Administration
UI

UI Generator
Application

External Components
Client
Applications

ESB / MQ /
EAI Broker

Request Framework
Service Controller
Web Services

XML
Composite
Transaction
Handler

Messaging
Adapter

Request Handler

Rule
Sets

IM / AIM Integration

Security

MDM Core
Admin
Services

Rules
Engine

Constructor

Business Transaction Manager

Extension Framework

Common
Services

Pre/Post
Txn

Extension
Controller

Evergreen
Processor

Parser

Business Proxies

Java
Classes

Party
Services

Account
Services

Pre/Post
Action

Business Logic Components

Code
Tables
Rule Data

Common
Components

Data Extensions

Transaction Audit
Information Log

Event
Manager

Performance
Tracker

MDM Component

IICE

FileNet

Entity & Relationship
Analytics (EAS)

IM&A

iLog jRules

PureQuery

External
Validation

QualityStage

Suspect Processing
Components

Utility
Components

Extension
Tables
Data

External
Rules

DataStage
Product
Services

Controller Components

Behavior Extensions

MDM
Workbench

WAS XD
Batch
Processor

Batch
Processor

Notification

Error
Messaging

3rd Party Integration

Operational
Structures
Data

Logging

History
Structures
History Data

Rules of
Visibility

MetaData

Configuration
Manager

Integrated Component

Client Component

Acxiom

Matching

Standardization

Caching

Dun & Bradstreet

Service Activity
Monitoring Facility

Task
Management

Spec

Significant Pluggable Component

Figure 1. InfoSphere MDM Server components and architecture

The organization of this guide is based on the tiers and layers in this diagram.

Learning the core components layers
The InfoSphere MDM Server core components are the kernel of the product. The
core is logically organized into a set of modules based on business function.
Each module of the core offers a set of cohesive services within its business
function. The modules are:
v Administration services
v
v
v
v
v
v
v

Business services
Account services
Party services
Product services
Contract services
History services
InfoSphere MDM Server Query Connect

Controller components
Each module is made up of controller components and business components. The
controller components are facades that provide an object interface for the services

Chapter 1. InfoSphere MDM Server architectural overview

Licensed Materials – Property of IBM

and aggregate underlying business components and provide a means for the
business components to collaborate together to carry out services.
Controllers come in two types:
v Transaction Controllers, which are stateless session beans and contain services
that are transactional in nature, for example, AddParty
v Finder Controllers, which are Java objects and contain inquiry services, for
example SearchParty

Business logic components
Controller components delegate responsibility of service fulfillment to business
components. The business components are coarse-grained Java objects with the
following primary responsibilities:
v Processing business rules that are either encapsulated within the boundaries of
the component or are externalized elsewhere
v Managing interactions with the database, such as persisting and inquiring on
data
v Invoking the extension framework at predefined points.
v Using common components to carry out common infrastructure activities, such
as logging and performance tracking.
v Using pureQuery to persist data and inquire data on the operational tables and
use JDBC for inquiring on tables

Suspect processing components
The suspect processing components are business components that contain the logic
to search, match, identify, and collapse suspect duplicate parties as part of normal
transaction processing.

Utility components
Utility components are components that offer infrastructure services to the business
and controller components. Examples of utility components include factories,
service locators and resource file readers. Utility components can also be adapters
that provide abstract interfaces to third party components to allow for pluggable
capabilities.

Operational and history tables
The core application comes with two sets of tables. The operational tables contain
the data for the hub based on the data model. The history tables are a mirror of
the operational tables with additional attributes to support audit and full point in
time inquiry on any master data. The history tables are populated through
database triggers.

Code tables
The code tables provide you with the ability to store reference data such as
relationship types, identification types, and others.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Understanding common components
InfoSphere MDM Server uses a set of common components that are not product or
domain specific. The following sections explain these common components and
details how InfoSphere MDM Server uses them.
v External rules—Provides the means for separating the specification of business
rules from the implementation of them. In other words, it allows business rules
to be implemented outside of InfoSphere MDM Server, so you can plug in your
own customized version of the rule. External rules can run externalized rules
implemented in Java or a rules engine.
Business rules that may be client-specific and may need to be customized are
implemented externally in Java or in the ILog JRules rules engine. While
running a transaction, the External Rule component is invoked at these points.
Also, the Event Manager component runs external rules to determine if an event
has occurred. Examples include data survivorship rules when collapsing parties
together, how to rank and sort search results and how to determine if a person
has retired.
v Event Manager—The Event Manager is a common J2EE component that invokes
client-defined business rules at predefined times to determine if an event has
occurred based on a given business object graph, for example, if a customer has
recently retired, this can trigger an event to transfer holdings into a retirement
plan. Detected events are recorded and can be notified on.
v External validations—Provides table-driven validations of business objects and
their attributes, and come prepackaged with a set of validators and supports
plugging in new Java validators.
External validations are used to validate all product and client-defined business
objects that are provided as part of a transaction request. The Administration UI
is used to maintain all external validations for both product and client-defined
business objects. An example validation is MINLENGTH Person.lastName < 30
v Notifications—Publishes messages to destinations based on defined topics. It
provides a mechanism that allows products and clients to define their own
notifications with customized content.
Notifications is used at specific points within InfoSphere MDM Server and is
centered on suspect duplicate processing. For example, a notification is sent
when InfoSphere MDM Server identifies two parties that may be a duplicate. It
is used by the Event Manager to publish notifications when specified events are
detected.
v Configuration and Management—Defines configurable features, possible
configuration options and the best option for configuring InfoSphere MDM
Server. Some InfoSphere MDM Server features can be configured dynamically
across a clustered environment.
The Configuration and Management component is used to control the global run
time behavior of the product. You can use the Configuration console to select
and deploy configuration options across a clustered environment.
v Rules of Visibility—Defines data-level entitlements and control who sees what,
and who can change what in the data. The visibility rules determine what
elements or instances of elements a user can see based on given constraints. The
persistency entitlement rules determine what elements or instances of elements a
user can add or update based on given constraints.
v Performance Tracker—The Performance Tracker is the ARM-compliant
component that receives and tracks response times for distributed transactions,
InfoSphere MDM Server transactions and sub-transactions.

Chapter 1. InfoSphere MDM Server architectural overview

Licensed Materials – Property of IBM

The Performance Tracker is used to log performance statistics which includes the
elapsed time of a transaction and the elapsed time of various parts of a
transaction. Performance tracking and the level of tracking is a configuration
option. Examples of levels include transaction response time only, database
activities response time, client extensions response time, among others.
v Error messaging—Allows clients to use table-driven error messages. Services are
used to retrieve and format messages according to a given locale.
Error messaging is used to retrieve and format parameter-driven messages when
an exception, a business or system error, is caught during processing of a
transaction request. The Administration UI is used to maintain existing product
messages and new client-defined messages.
v Logging—Writes messages to log files and offers Log4J and Java Platform
logging implementations. It is used to write information, warning and error
messages to separate logs.
v Metadata—Defines a schema of business objects and the relationships between
them, mapping to relational database tables, the transactions and actions, which
are internal transactions, and the definition of request and response messages.
Metadata is used to define:
– InfoSphere MDM Server business objects and attributes
– InfoSphere MDM Server transactions and actions
– Extended metadata
v Transaction audit information log—Used to track various transactions in the
system for logging and audit purposes.
v Matching—Compares an inbound party object against a candidate list created
by party search, in order to determine whether the party matches any parties
that are already in the system. The matching matrices used in this process are
configurable.
v Caching—Stores data temporarily in memory in order to speed up the
operations of the system. It can be configured in a number of different ways and
supports query refresh functionality and eviction policies.
v Persistence—Data Persistence and retrieval is handled by pureQuery, a
database-neutral, object relational mapping product, from IBM. This is a
significant change from previous releases, where data persistence was handled
by Entity EJBs and retrievals were done by direct JDBC.
v Search—Performed as part of the suspect duplicate processing process to find
possible match candidates within the system that resemble an incoming party
object. The person and organization search component that can be configured to
use various enhancements such as, among others, Common Search Exclusion,
Pluggable Search SQL, Configurable Inquiry levels and Phonetic search.
v Standardization—Provides services to standardize various data elements
including names and addresses.
v Task Management—Manages the task lifecycles, provide task management
transactions to other components, and to provide a runtime execution
environment for each task.
As a common component, Task Management supports generic task-oriented
design. It provides the following features to system administrators and
end-users:
– Administer task definitions
– Manage the lifecycle of a task
v External components—InfoSphere MDM Server provides a framework for batch
processing. The Batch Processor is a common J2SE component that supports

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

pluggable readers/writers, multiple instances and concurrent processing within
an instance for high throughput. The Batch Processor invokes the Request
Framework for each transaction read and therefore all InfoSphere MDM Server
services and client-defined services and extensions can be processed in batch.
There are two Batch processors included: one is based on WebSphere® XD; and
one is a standalone Java Standard Edition (JSE) application.
The Evergreen Processor is an application of the Event Manager. It uses the
Event Manager to monitor the InfoSphere MDM Server repository, and detect
and notify when suspect duplicate parties are found.

Learning the extension framework layers
Because InfoSphere MDM Server source code is not accessible to clients, there are a
number of extension and configuration mechanisms available to adapt the product
to their environment. The extension framework is one of these mechanisms.
The two primary types of extensions are data extensions and behavior extensions. A
data extension allows a client to add new data elements. A behavior extension
allows a client to plug in new business rules or functionality. Also, InfoSphere
MDM Server uses its own extension framework to plug in some modules, such as
rules of visibility, in order to keep it loosely coupled and easily configurable to
turn “on” or “off”.
Chapter 2, “Customizing InfoSphere MDM Server,” on page 17 discusses how to
configure and customize features, using the InfoSphere MDM Server Extension
Framework.
See also:
“Understanding behavior extensions”
“Understanding data extensions” on page 10
“Understanding new transactions” on page 10
“Creating entity models and extensions with Workbench tools” on page 10

Understanding behavior extensions
InfoSphere MDM Server provides a mechanism for extending the behavior of the
product in an event-based way. The Pre/Post Transaction and Pre/Post Action
points within the product can be extended to provide additional functionality.
A transaction equates to a published service, or Controller Component operation.
An action equates to an operation on a business logic component. There may be
other predefined points that can be extended and they are documented as part of
the service specification. Clients can write extensions to InfoSphere MDM Server
behavior as Java code or in a rules engine language. Extensions are organized into
extension sets, which are similar to the rule sets within a rules engine. Examples
include generic prospective client rules or line of business specific rules like life
insurance client rules. The Extension Controller is the gateway from the core
application to behavior extensions and is invoked at extension points listed above.
It is provided with:
v Data about extension point that invoked it
v The transaction’s object hierarchy
v The action’s object hierarchy, in the case of an action extension point
v The transaction header that was provided in the original InfoSphere MDM
Server request
Chapter 1. InfoSphere MDM Server architectural overview

Licensed Materials – Property of IBM

The Extension Controller uses the parameters to determine if any extension sets
must be further evaluated. Relevant extension sets are then interrogated and
qualified extensions, either Java or rules sets, are invoked.

Understanding data extensions
InfoSphere MDM Server provides a mechanism for extending the data model.
Clients can add new attributes to existing tables as well as add new tables. Clients
can add new attributes to existing tables as well as add new tables. Extended data
elements can be persisted and retrieved as part of existing InfoSphere MDM Server
transactions without the need to modify InfoSphere MDM Server code.
InfoSphere MDM Server has the following responsibilities when dealing with
extended data:
v Parsing extended data as part of an XML service request and creating extended
business objects
v Invoking validation routines on the extended business objects
v Populating the extended data elements as part of the InfoSphere MDM Server
metadata so that features such as external validation rules can be used
v Invoking methods on the extended business object when required to persist or
retrieve the extended data elements
v Constructing XML data as part of the service completion

Understanding new transactions
If new transactions, or services, are required, you can use the InfoSphere MDM
Server application framework.
Clients can build transactions by constructing new controller/business components
and using the existing request framework and common components.

Creating entity models and extensions with Workbench tools
InfoSphere MDM Server also comes with InfoSphere MDM Server Workbench, a
development tool to help with the creation of a custom entity model and related
data and behavior extensions.
The Workbench comes in the form of a plugin to Rational Software Architect. For
more information, the chapter Chapter 2, “Customizing InfoSphere MDM Server,”
on page 17 discusses how to configure and customize features using the
InfoSphere MDM Server Extension Framework.

Learning the Request-Response processor
The InfoSphere MDM Server Request-Response processor provides a consistent
entry point to InfoSphere MDM Server and is used to receive requests and issues
responses in any format.
The request framework performs the following functions:
v Accepts and parses a request containing a single or composite transactions.
v Authorizes the request.
v Participates in a distributed transaction or initiates a new transaction if required.
v Invokes the requested service using the appropriate controller component.
v Constructs and returns the response.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The request framework provides the ability to receive requests and return
responses in any format, for example, XML, flat file and named value pairs, and
according to any schema, such as the predefined InfoSphere MDM Server schema,
client-defined schema or industry-defined schema. It provides this flexibility
through pluggable components.

Service Controller
The Service Controller is a common component that provides a simple and elegant
entry point in to InfoSphere MDM Server. It is a thin, stateless session bean with a
tx_required transactional property that delegates fulfillment of the request to the
Request Handler.

Request Handler
The Request Handler orchestrates services from underlying components in order to
fulfill the majority of responsibilities listed above. At a high level, it obtains and
invokes a parser capable of parsing the request, authorizes the request, runs the
parsed transaction through the Business Transaction Manager, obtains and invokes
a constructor capable of assembling the response and then returns the result.

Parsers and constructor
The Request-Response processor provides the means for dynamic, pluggable
parsing.InfoSphere MDM Server comes with an XML parser and constructor based
on the InfoSphere MDM Server extensible schema. Pluggable parsing and
construction allows you to plug in one or more parsers and constructors that
adhere to their own standards or to industry standards such as ACORD, oLife and
IFX. This feature provides for ease of integration since services are assembled using
a familiar vocabulary.

Business proxies
A business proxy is the component that invokes transactions on the InfoSphere
MDM Server core application. A transaction, also called a service, is an operation
on a specific controller component. New business proxies can be plugged in to
accommodate client-specific composite transactions. The Business Transaction
Manager is responsible for obtaining the appropriate proxy based on criteria
including the transaction type, for example, AddParty. You can write your own
customized proxies to support product implementation requirements, such as the
need for specialized composite transactions.

XML Composite Transaction framework
The XML Composite Transaction framework provides the ability execute multiple
InfoSphere MDM Server transactions as part of a single XML request. The results
from one transaction response can be used in a subsequent transaction request
with conditional or looping logic if required.

Web services
InfoSphere MDM Server provides a Web services compliant interface that accepts
the consumer’s Web service SOAP and invokes the Service Controller in the
request framework. Each InfoSphere MDM Server transaction is associated with a
WSDL file.

Chapter 1. InfoSphere MDM Server architectural overview

Licensed Materials – Property of IBM

Messaging Adapter
The request framework provides an synchronous interface by employing JMS. It
provides a means to send InfoSphere MDM Server requests by means of messages
over message-oriented middleware.

Understanding consumers layers
There are numerous methods for invoking InfoSphere MDM Server services. Some
methods are part of the InfoSphere MDM Server product and others are
components in a client’s environment.

InfoSphere MDM Server user interfaces
InfoSphere MDM Server supports user interfaces to help manage stored
information:
v The Business Administration Web application is used to configure InfoSphere
MDM Server. For example, this UI is used for maintaining code tables, users,
groups, external validations, and so on.
v The Data Stewardship Web application is used for general party maintenance,
group and hierarchy maintenance and as part of suspect processing. The UI can
be used to add and update party information, search for parties marked as
suspects, collapse or split suspect parties, and so on.
v The User Interface Generator is a InfoSphere MDM Server Workbench tool that
you can use to build user interfaces that surface information managed within a
hub instance to users, based on their roles. The User Interface Generator
generates Web-based user interfaces using industry standards such as UML and
J2EE, helping you to reduce the skills gap involved in building robust Web
applications as part of an InfoSphere MDM Server solution.
The User Interface Generator is an Eclipse tool that takes a user model and
generates a role-based user interface for a J2EE Web application. A user model is
a UML model that describes a set of individuals and how they interact with an
IT solution. From the user model, the User Interface Generator can generate a
user interface that can then consume the InfoSphere MDM Server services.

Client interfaces
The way InfoSphere MDM Server is integrated in to a business environment is
different for each implementation, as it depends on the system architecture, tools
and technical limitations and constraints. Possible ways of invoking InfoSphere
MDM Server services through the Request-Response processor include:
v An ESB, MQ broker or EAI broker
v Dashboard or portal user interfaces
v Client applications such as CRM and back-office administration systems

InfoSphere MDM Server components
InfoSphere MDM Server uses a set of common components that are not product or
domain specific.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Understanding component interactions
The following diagram shows the interactions among the components in the
architecture to carry out a basic transaction.

MDM Consumers
Administration
UI

Data
Stewardship
UI

UI Generator
Application

Client
Applications

ESB / MQ /
EAI Broker

Request Framework
Web Services

Messaging
Adapter

XML
Composite
Transaction
Handler

Service Controller

Request Handler

Extension
Controller

Rules
Engine

Rule
Sets

Pre/Post
Txn
Pre/Post
Action

9
Behavior Extensions

5
15

Security

MDM Core

Extension Framework
7

Parser

16Constructor

Business Transaction Manager
Business Proxies

Java
Classes

Admin
Services

Common
Services

Account
Services

Party
Services

Product
Services

6
Controller Components
8
Business Logic Components

10
Suspect Processing
Components

Utility
Components
PureQuery

MDM
Workbench

Extension
Tables
Data
Data Extensions

Code
Tables
Rule Data

Operational
Structures
Data

History
Structures
History Data

Figure 2. Understanding InfoSphere MDM Server component interactions

The diagram shows a transaction being processed by InfoSphere MDM Server, and
the interaction of the InfoSphere MDM Server components. The component
interactions are:
1. The service controller receives request from InfoSphere MDM Server
consumer.
2. The request is delegated to Request Handler, which gets a parser from a
factory.
3. The request parsed into business objects.
4. The security component used to authorize transaction.
5. The Business Transaction Manager (BTM) gets a business proxy capable of
handling the request.
6. The business proxy invokes method on required controller component.

Chapter 1. InfoSphere MDM Server architectural overview

Licensed Materials – Property of IBM

7. The controller component performs preprocessing, which includes invoking
the external validation engine to validate incoming data, and invoking the
extension controller to execute any ″pre-transaction″ extensions.
8. The controller component invokes required business logic component
methods.
9. The business logic component performs preprocessing, which includes
invoking the extension controller to run any “pre-action” extensions.
10. The business logic component runs business logic, including invoking external
business rules component to run the externalized business logic.
11. The business logic component invokes the persistency layer to persist data in
database.
12. The database triggers are used to create history data.
13. The business logic component performs post-processing, which includes
invoking the extension controller to run any post action extensions.
14. The control returns to controller component, which may invoke other business
logic component methods. Once this is complete, the control performs postprocessing, which includes invoking extension controller to execute any post
transaction extensions and invokes the Transaction Audit Information Log
component to audit the transaction.
15. The Control returns to business proxy. The business proxy can run additional
InfoSphere MDM Server transactions, using controller component methods.
16. The control is returned to the request handler which gets a response
constructor from a factory. The business objects are de-serialized into XML
and the response is returned to the InfoSphere MDM Server consumer.

Understanding business modules
The InfoSphere MDM Server business modules provide business services,
including party, financial services, business services and others.
All business modules have a similar structure, consisting of a pair of a controller
components and a set of underlying business components. All persistence
transactions (the transactions that modify the data) are handled by a transaction
controller, while all gets and searches are handled by a finder controller.
Each controller implements an interface that defines the transaction it can process.
This interface is also the published API for client use. Transactions correspond to
methods on the interface. The controllers act as a façade for each business module
and aggregate underlying business components, providing a means for the
business components to collaborate in providing services.
The business components implement the core business logic for each service. These
components also work with the persistence layer to persist or to read the data.
Additionally these components use various infrastructure modules to use the
respective service.

Understanding infrastructure modules
These modules provide infrastructure and system services, and frameworks. Due
to the variation in the type of services, the structure of these modules differs from
module to module, however, all the modules use a similar service oriented
architecture. In many cases the implementations are pluggable to allow clients to
customize the behavior or to add their own completely different behavior.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Some of the significant infrastructure components shipped with InfoSphere MDM
Server are:
v Request and response framework—Provides a consistent entry point and
request and response processing for InfoSphere MDM Server applications along
with pluggable parsers, constructors and business proxies.
v Security—Provides interfaces and implementation for authentication as well as
transactional authorization. The default implementation of Security only
provides transactional authorization.
v Notification—Provides the ability to send notification messages on certain
events in the system.
v Rule of visibility—A highly complex and elaborate data authorization module
to ensure requesting users have the appropriate read and write access to the
data being inserted, updated or read.
v Transaction audit information log—A mechanism to log various transactions in
the system for logging and audit purposes
v Standardization—Provides services to standardize various data elements
including names and addresses.

Understanding customization restrictions
One of the prime objectives of InfoSphere MDM Server architecture is to support
customization and extension of the core product. This is achieved by providing
extension hooks for extending services, business rules as well as data. Most of the
infrastructure components allow for pluggable implementations, allowing clients to
customize the behavior by writing and configuring their own plug-ins.
All extensions, customizations and configurations to InfoSphere MDM Server are
handled without impacting existing product assets. In order to preserve the ability
to upgrade from release to release, do not alter the following assets from your
InfoSphere MDM Server product:
v Core XML schemas (XSDs)
Tip: Client extensions may be added to the XSDs.
v Properties files
v Data Definition Language (DDL) files
v Business objects
v Controller and business components
v Java implemented external rules and ILog JRule rule files
Important: Where required, skeleton extension files are provided for extension
XSD and extension XML schema files, as well as for the extension properties file.

Chapter 1. InfoSphere MDM Server architectural overview

Licensed Materials – Property of IBM

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 2. Customizing InfoSphere MDM Server
InfoSphere MDM Server can be customized, allowing you to create additions,
extensions and metadata specs.
Important: All custom names must be prefixed with a three letter abbreviation
followed by underscore, for example ABC_getItem. These naming guidelines apply
to all custom database tables, transaction names and any other customized
elements.
In this section, you will learn:
“Understanding extensions” on page 18
“Understanding additions” on page 18
“Creating extensions and additions” on page 19
“Creating extensions and additions with InfoSphere MDM Server Workbench”
on page 19
“Understanding the extension handler component” on page 20
“Creating extensions” on page 23
“Starting an extension” on page 24
“Extending business objects” on page 24
“Extending database tables for new functions” on page 25
“Defining extended functions in the request and response framework XSD” on
page 26
“Understanding transaction context passing and the DWLControl object” on
page 29
“Creating event behavior extensions” on page 31
“Extending functions through the rules engine” on page 31
“Understanding Java behavior extensions” on page 32
“Creating additions to add new data and functionality” on page 33
“Registering extended and new business objects” on page 36
“Adding metadata to added or extended tables and columns” on page 37
“To test an extension or addition” on page 40
“Recognizing extensions and additions in InfoSphere MDM Server” on page 40
“Accessing samples of extensions and additions” on page 40
“Understanding InfoSphere MDM Server runtime metadata” on page 41
“Maintaining metadata with InfoSphere MDM Server Workbench” on page 42
“Understanding component functions” on page 42
“Using the pureQuery data access layer” on page 43
“Creating pluggable business object queries” on page 46
“Implementing pluggable business object queries” on page 47
“Customizing an existing pluggable business object query” on page 49
“Using pureQuery data access layer in pluggable business object queries” on
page 49
“Understanding the structure of a constant” on page 49
“Extending the BObjQuery class” on page 50
© Copyright IBM Corp. 1996, 2009

Licensed Materials – Property of IBM

“Creating a new pluggable business object query” on page 51
“Implementing SQLJ-based queries” on page 53
“Creating a pluggable persistence mechanism” on page 56

Understanding extensions
Extensions are customized code that provide additional functionality by extending
data elements or extending the behavior of existing transactions. This expanded
functionality is executed on top of the default InfoSphere MDM Server code.
There are two primary classifications of extensions within InfoSphere MDM Server:
v Extending data - adding additional attributes to existing database tables
v Extending behavior - adding new functionality to transactions, or underlying
actions within transactions
You can add new data elements to existing business objects or to newly defined
business objects. You can also add new behavior to existing business transactions
and actions within transactions, or to newly defined business transactions.
Note: Extensions do not allow you to add completely new functions to InfoSphere
MDM Server. To do this you must use an addition.

Understanding additions
Additions add new functions, using new code and database tables that are
independent of existing code.
Any business objects introduced when you create an addition are completely
independent of existing data elements and transactions, and add new functionality
without affecting existing functions. An addition may:
v Add new transactions to existing modules. The new transactions can accept and
return either existing InfoSphere MDM Server business objects, or new
client-defined business objects.
v Add a new subject area or module. For example, adding a new physical body
profile area that has its own set of transactions and related data elements.
Note: You can extend common services that InfoSphere MDM Server uses. For
example, you can extend Notifications to add new types of notifications.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Creating extensions and additions
The basic process for creating extensions and additions is:
Procedure
High-Level Design

v Collect the business requirements.
The business requirements help you determine whether you need
to create external rules, an extension or an addition, and plan the
work you need to do.
v Depending on the business requirements, plan the changes that you
need to make.
v Decide whether you need to create external rules, an extension or
an addition and the transactions you need to create.
v Plan for the required new:
– database fields, entity and business objects
– for additions, controllers and components
– data validation and error handling
– class hierarchy
– package and class organization
v

Coding

Based on the business requirements, you can plan the changes you
will need to make.

v Code the classes, interfaces, and methods. Based on the plan you
have created, use the Workbench to create the classes and
interfaces. Finish implementing all the non-generated parts of the
classes that are required. See the InfoSphere MDM Server Workbench
Users Guide for more information.
v Ensure that all custom names are prefixed with a three letter
abbreviation followed by an underscore, for example, ABC_getItem.
These naming guidelines apply to all custom business objects,
database tables, and transaction names.
v When Creating Extensions, new entity additions, new services and
new code table values, please use value greater than 1,000,000 as
primary key for database entities describing metadata. All values
less than 1,000,000 are reserved for InfoSphere MDM Server as
integer PK values.
v When configuring new inquiry levels (tale INQLVL, column inqlvl),
please use values 100 and up. Values range from 0 to 99 are
reserved for InfoSphere MDM Server.

Deploy and Test

v Deploy the extension or addition
v Ensure the InfoSphere MDM Server application can see the EJB
project with the addition or extension.
v Test the extension or addition.

Creating extensions and additions with InfoSphere MDM Server
Workbench
This section outlines the concepts for the creation of additions and extensions
using InfoSphere MDM Server Workbench.

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

Using InfoSphere MDM Server Workbench, you define, develop and deploy a set
of related additions and extensions together as a single module. InfoSphere MDM
Server Workbench stores information about each module in a file with the name
module.mdmxmi. This is referred to as the module model.
Additions are defined in the module model as entities with attributes and
transactions. Entities map directly to database tables and attributes to columns in
the table. When you define a new entity, basic transactions are automatically added
to the model to enable creation, retrieval and updates of entity instances.
Data extensions are defined in a similar way to additions, but do not have
associated transactions because extension attributes are retrieved and modified
using the transactions of the business object that is extended.
Behavior and query extensions may also be defined in the module model.
Once the additions and extensions have been defined, Java code, EJBs, Web
services, SQL scripts and other required files are generated automatically from the
module model. You must manually modify some of the generated files in order to
complete the implementation: required and recommended customization points in
the files are flagged with an MDM_TODO comment so that they can be easily located.
Once you have completed any required manual customization of the generated
files, the modified InfoSphere MDM Server application, including the new module,
is ready to deploy and test.

Understanding the extension handler component
InfoSphere MDM Server provides an extension handler component that manages
extension plugins.
The extension handler component supplies:
v The ability to plug in client extension sets
v The ability to plug in new product modules while keeping them loosely coupled
from the core of the product itself
v A mechanism for a push functionality as part of an integration strategy.
The extension handler responds to events within the product and then evaluates
whether any extension sets need to be invoked. An extension set can be either a
rule set or a Java class.
The product hooks into the extension handler at the pre/post of every method in
controllers and components of a transaction and provides a set of parameters:
v The event within the transaction including transaction type/category, action
type/category, trigger types, and so on
v Transaction data-object hierarchies and working object hierarchies
v Elements that came in as part of the XML header, such as line of business,
company, user details.
The extension handler then interrogates the parameters and determines which
extension sets to execute based on cached data defined within its tables.
The benefits of this mechanism are that it:

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Keeps extensions loosely coupled from the product, which allows InfoSphere
MDM Server to be upgraded without affecting the extensions
v Allows extensions to be implemented in either the rule script or Java
v Manages the relationship to, and capitalizes on rules engines which are excellent
at evaluating conditions and taking action by leveraging InfoSphere MDM
Server business component services
v Provides a means to partition extension sets according to a client’s needs.
If the database configuration settings have both ILR and Java rule extension sets,
InfoSphere MDM Server uses the Java rule extension sets by default.
For more information on where the Java extension sets are used see:
v Information on com.dwl.tcrm.externalrule.TAILAdditionalDetail in Chapter 19,
“Storing and retrieving the Transaction Audit Information Log,” on page 225
v Operand Builder in “Setting Rules of Visibility” on page 392
v Party Summary Indicator Refresher in Chapter 47, “Customizing Summary Data
Indicators,” on page 641
v Skip Operation Rule in Chapter 12, “Configuring Smart Inquiries,” on page 165
v Defaulted Source Value in Chapter 21, “Setting source values and data decay,”
on page 253
v EndDate Rule in next session, in “Creating event behavior extensions” on page
31
v com.dwl.tcrm.externalrule.Notification, in Chapter 40, “Implementing and
configuring the Notification Framework,” on page 531
The following table shows the extension sets provided with the product.
InfoSphere MDM Server also supports the IRL external rule format. If an IRL JAR
file is packaged within the provided DWLCustomerILogRules.jar, it will be searched
by its classpath. Otherwise, it is searched by its physical path.
Note: All ILR files shown in this table are located in the directory
/com/dwl/tcrm/ilr/.
ID

NAME
9

JAVACLASSNAME

RULESETNAME
CustomerInsuranceRules.ilr

INACTIVE
_IND

ConsumerInsuranceRule

com.dwl.tcrm.externalrule.CustomerInsuranceRules

DataEntitlementEngine

com.dwl.base.entitlement.PersistencyEntitlementsEngine

RuleOfVisibilityEngine

com.dwl.base.entitlement.VisibilityEntitlementsEngine

RuleOfVisibilityEngine for Txn

com.dwl.base.entitlement.VisibilityEntitlementsEngine

updatePartyNotification

com.dwl.tcrm.externalrule.Notification

notification.ilr

EndDateAddContractPartyRole

com.dwl.tcrm.externalrule.EndDateRules

EndDateRules.ilr

EndDateUpdateContractPartyRole

com.dwl.tcrm.externalrule.EndDateRules

EndDateRules.ilr

EndDateAddContract

com.dwl.tcrm.externalrule.EndDateRules

EndDateRules.ilr

DefSrcValOrganizationExt

com.dwl.base.defaultSourceValue.component.DefaultedSourceValueComponent

DefSrcValPersonExt

com.dwl.base.defaultSourceValue.component.DefaultedSourceValueComponent

getDefSrcValOrganizationExt

com.dwl.base.defaultSourceValue.component.DefaultedSourceValueComponent

getDefSrcValPersonExt

com.dwl.base.defaultSourceValue.component.DefaultedSourceValueComponent

updDefSrcValPartyExt

com.dwl.base.defaultSourceValue.component.DefaultedSourceValueComponent

ROVSearchPerson

com.dwl.base.entitlement.PersistencyEntitlementsEngine

ROVSearchOrganization

com.dwl.base.entitlement.PersistencyEntitlementsEngine

ROVSearchContract

com.dwl.base.entitlement.PersistencyEntitlementsEngine

ROVSearchFSParty

com.dwl.base.entitlement.PersistencyEntitlementsEngine

EMMessenger

com.dwl.tcrm.em.TCRMEMMessenger

AbiliTecLinkRefreshNotifier

com.dwl.tcrm.em.AbiliTecLinkRefreshActionNotifier

UpdatePartyAlertIndForAddAlert

com.dwl.tcrm.externalrule.UpdatePartyAlertInd

UpdatePartyAlertIndForUpdAlert

com.dwl.tcrm.externalrule.UpdatePartyAlertInd

For transaction searchPerson

com.dwl.base.integration.DWLResponsePublisher

For transaction getPerson

com.dwl.base.integration.DWLResponsePublisher

For transaction addPerson

com.dwl.base.integration.DWLResponsePublisher

For transaction getContract

com.dwl.base.integration.DWLResponsePublisher

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

NAME

JAVACLASSNAME

RULESETNAME

INACTIVE
_IND

For transaction addContract

com.dwl.base.integration.DWLResponsePublisher

For transaction updateContract

com.dwl.base.integration.DWLResponsePublisher

SkipIdentifiersExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPartyLobRelationshipsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPartyPrivacyPreferencesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPartyAddressesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPartyContactMethodsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPartyRelationshipsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipFinancialProfileExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipgetAllPartyValuesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipgetAllPartyAlertsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPersonAlertsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipOrganizationAlertsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContractAlertsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContractAdminSysKeysExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContractComponentsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContractPartyRolesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContractPartyRoleAlertsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContractRoleLocationsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContrPtyRoleSituationsEx

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContrPtyRoleIdentifiersExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContractRelationshipsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipIncomeSourcesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPartyBankAccountsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPartyChargeCardsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPartyPayrolldeductionsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPtyAddrPrivPreferencesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPtyContactMtdPrivPrefExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContactMethodExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContrPtyRlRelationshipsExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkiptAddressExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipAddressValuesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipAddressNotesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPtyLocationPrivPrefExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipPrivacyPreferencesExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContrPtyRolesByPartyExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipContractsByPartyExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipgetHoldingExt

com.dwl.tcrm.externalrule.SkipOperationRule

SkipgetAllAlertsExt

com.dwl.tcrm.externalrule.SkipOperationRule

AddPartyIdenInd

com.dwl.tcrm.externalrule.IdentifierSummaryIndicatorRefresher

UpdatePartyIdenInd

com.dwl.tcrm.externalrule.IdentifierSummaryIndicatorRefresher

AddPartyPrivPrefInd

com.dwl.tcrm.externalrule.PrivPrefSummaryIndicatorRefresher

UpdatePartyPrivPrefInd

com.dwl.tcrm.externalrule.PrivPrefSummaryIndicatorRefresher

AddPartyValueInd

com.dwl.tcrm.externalrule.PartyValueSummaryIndicatorRefresher

UpdatePartyValueInd

com.dwl.tcrm.externalrule.PartyValueSummaryIndicatorRefresher

AddPartyRelationshipInd

com.dwl.tcrm.externalrule.ContactRelSummaryIndicatorRefresher

UpdatePartyRelationshipInd

com.dwl.tcrm.externalrule.ContactRelSummaryIndicatorRefresher

AddPartyBankAccountInd

com.dwl.tcrm.externalrule.BankAccountSummaryIndicatorRefresher

UpdatePartyBankAccountInd

com.dwl.tcrm.externalrule.BankAccountSummaryIndicatorRefresher

AddPartyChargeCardInd

com.dwl.tcrm.externalrule.ChargeCardSummaryIndicatorRefresher

UpdatePartyChargeCardInd

com.dwl.tcrm.externalrule.ChargeCardSummaryIndicatorRefresher

AddPartyPayrollDeductInd

com.dwl.tcrm.externalrule.PayrollDeductSummaryIndicatorRefresher

UpdatePartyPayrollDeductInd

com.dwl.tcrm.externalrule.PayrollDeductSummaryIndicatorRefresher

AddPartyIncomeSourceInd

com.dwl.tcrm.externalrule.IncomeSourceSummaryIndicatorRefresher

UpdatePartyIncomeSourceInd

com.dwl.tcrm.externalrule.IncomeSourceSummaryIndicatorRefresher

AddPartyAlertInd

com.dwl.tcrm.externalrule.AlertSummaryIndicatorRefresher

UpdatePartyAlertInd

com.dwl.tcrm.externalrule.AlertSummaryIndicatorRefresher

100

AddContEquivInd

com.dwl.tcrm.externalrule.ContEquivSummaryIndicatorRefresher

101

UpdateContEquivInd

com.dwl.tcrm.externalrule.ContEquivSummaryIndicatorRefresher

102

AddPartyInteractionInd

com.dwl.tcrm.externalrule.InteractionSummaryIndicatorRefresher

103

UpdatePartyInteractionInd

com.dwl.tcrm.externalrule.InteractionSummaryIndicatorRefresher

104

AddPartyAddressInd

com.dwl.tcrm.externalrule.AddressSummaryIndicatorRefresher

105

UpdatePartyAddressInd

com.dwl.tcrm.externalrule.AddressSummaryIndicatorRefresher

106

AddPartyContactMethodInd

com.dwl.tcrm.externalrule.ContactMethodSummaryIndicatorRefresher

107

UpdatePartyContactMethodInd

com.dwl.tcrm.externalrule.ContactMethodSummaryIndicatorRefresher

108

AddPartyLobRelationshipInd

com.dwl.tcrm.externalrule.LobRelSummaryIndicatorRefresher

109

UpdatePartyLobRelationshipInd

com.dwl.tcrm.externalrule.LobRelSummaryIndicatorRefresher

110

AddPartyInd

com.dwl.tcrm.externalrule.PartySummaryIndicatorRefresher

111

UpdatePartyInd

com.dwl.tcrm.externalrule.PartySummaryIndicatorRefresher

112

SkipContractComponentValueExt

com.dwl.tcrm.externalrule.SkipOperationRule

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

NAME

JAVACLASSNAME

RULESETNAME

INACTIVE
_IND

113

SkipContractRoleLocPurposeExt

com.dwl.tcrm.externalrule.SkipOperationRule

114

DefSrcValOrganizationExtFP

com.dwl.fp.base.defaultSourceValue.component.DefaultedSourceValueComponent

Y
Y

115

DefSrcValPersonExtFP

com.dwl.fp.base.defaultSourceValue.component.DefaultedSourceValueComponent

116

getDefSrcValOrganizationExtFP

com.dwl.fp.base.defaultSourceValue.component.DefaultedSourceValueComponent

117

getDefSrcValPersonExtFP

com.dwl.fp.base.defaultSourceValue.component.DefaultedSourceValueComponent

118

GetTAILAdditionalDetail

com.dwl.tcrm.externalrule.TAILAdditionalDetail

119

AccessTokenEnabler

com.dwl.base.accessToken.AccessTokenEnabler

120

AccessTokenObfuscator

com.dwl.base.accessToken.AccessTokenObfuscator

121

QualityStageAddPartyMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

122

QualityStageUpdatePartyMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

123

FeedInitiator

com.dwl.thirdparty.integration.eas.initiator.FeedInitiator

124

DeletePartyContextBuilder for deleteParty

com.dwl.thirdparty.integration.eas.contextbuilder.DeletePartyContextBuilder

125

InactivatePartyContextBuilder for inactivateParty

com.dwl.thirdparty.integration.eas.contextbuilder.InactivatePartyContextBuilder

126

NameContextBuilder for addOrganizationName

com.dwl.thirdparty.integration.eas.contextbuilder.NameContextBuilder

127

NameContextBuilder for updateOrganizationName

com.dwl.thirdparty.integration.eas.contextbuilder.NameContextBuilder

128

NameContextBuilder for addPersonName

com.dwl.thirdparty.integration.eas.contextbuilder.NameContextBuilder

129

NameContextBuilder for updatePersonName

com.dwl.thirdparty.integration.eas.contextbuilder.NameContextBuilder

130

EmailContextBuilder for addPartyContactMethod

com.dwl.thirdparty.integration.eas.contextbuilder.EmailContextBuilder

131

EmailContextBuilder for updatePartyContactMethod

com.dwl.thirdparty.integration.eas.contextbuilder.EmailContextBuilder

132

AddressContextBuilder for addPartyAddress

com.dwl.thirdparty.integration.eas.contextbuilder.AddressContextBuilder

133

AddressContextBuilder for updatePartyAddress

com.dwl.thirdparty.integration.eas.contextbuilder.AddressContextBuilder

134

NumberContextBuilder for addPartyChargeCard

com.dwl.thirdparty.integration.eas.contextbuilder.NumberContextBuilder

135

NumberContextBuilder for updatePartyChargeCard

com.dwl.thirdparty.integration.eas.contextbuilder.NumberContextBuilder

136

NumberContextBuilder for addPartyIdentification

com.dwl.thirdparty.integration.eas.contextbuilder.NumberContextBuilder

137

NumberContextBuilder for updatePartyIdentification

com.dwl.thirdparty.integration.eas.contextbuilder.NumberContextBuilder

138

NumberContextBuilder for addPartyContactMethod

com.dwl.thirdparty.integration.eas.contextbuilder.NumberContextBuilder

139

NumberContextBuilder for
updatePartyContactMethod

com.dwl.thirdparty.integration.eas.contextbuilder.NumberContextBuilder

140

AttributeContextBuilder for addPerson

com.dwl.thirdparty.integration.eas.contextbuilder.AttributeContextBuilder

141

AttributeContextBuilder for updatePerson

com.dwl.thirdparty.integration.eas.contextbuilder.AttributeContextBuilder

142

AttributeContextBuilder for addPartyChargeCard

com.dwl.thirdparty.integration.eas.contextbuilder.AttributeContextBuilder

143

AttributeContextBuilder for updatePartyChargeCard

com.dwl.thirdparty.integration.eas.contextbuilder.AttributeContextBuilder

144

AttributeContextBuilder for addPartyContactMethod

com.dwl.thirdparty.integration.eas.contextbuilder.AttributeContextBuilder

145

AttributeContextBuilder for
updatePartyContactMethod

com.dwl.thirdparty.integration.eas.contextbuilder.AttributeContextBuilder

146

QualityStageAddPartyAddessMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

147

QualityStageUpdatePartyAddressMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

148

QualityStageAddPartyIdentificationMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

149

QualityStageUpdatePartyIdentificationMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

150

QualityStageAddPersonNameMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

151

QualityStageUpdatePersonNameMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

152

QualityStageAddOrganizationNameMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

153

QualityStageUpdateOrganizationNameMatch

com.dwl.tcrm.em.QualityStagePartyMatchingRule

Creating extensions
Before you write your extensions, you must define and describe the extensions
within the InfoSphere MDM Server database, along with the set of condition
parameters that must be true for the extension to be run.
When creating an extension, all custom names must be prefixed with a three letter
abbreviation followed by an underscore, for example, ABC_getItem. These naming
guidelines apply to all custom business objects, database tables, and transaction
names.
You define the extensions and their condition parameters from the Data Extension
option within InfoSphere MDM Server Workbench . The process of defining the
extension is documented in the InfoSphere MDM Server Workbench Guide.
InfoSphere MDM Server provides two approaches to data extension persistency.
One approach is to persist extension attributes in an existing core database table.
The alternative is to persist the extension attributes in a new extension database
table.

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

The following table is a guideline to help developers decide which approach to use
when implementing data extension:
Create new table for data
extension

Alter core table for data
extension

Compatibility Issues

None

Changing core tables could
lead to compatibility issues
with future releases of the
product.

DB I/O Performance

Inquiry transactions require
two DB calls: one for the
core table, and another one
for the extension table.

When using the inquiry
framework only one DB call
is required for inquiry
transactions.

Mapping Extension
Attributes

Extension entity object is
mapped to the extension
table using pureQuery Java
annotations. .

The extension entity object is
mapped to the same table as
the original entity object was
mapped to, using pureQuery
Java annotations.

Ability to Tune

Low

High

Data History

History for the extension
columns is kept in its own
history table

Two history records are
created in the core history
table for insert/update
transactions.

Starting an extension
When you create an extended function, you must add additional attributes to
existing database tables, and the associated business objects and views must be
updated to perform with the extended function.
The InfoSphere MDM Server Workbench should be used to create your extension.
See the InfoSphere MDM Server Workbench User Guide for more information.

Extending business objects
When you have extended a database table and introduced a new entity object, you
need to map that to a new business object.
An inheritance technique is used-the business object of interest must be sub-typed
and mapped to the extended entity object.
Note: The extended business object must implement IExtension or IDWLExtension,
and the name must end with Ext. For example, PersonExt, AddressExt are valid
names, while PersonExtension, PersonEx, PersonEXT, ExtendedPerson are invalid
names.
See also:
“To extend business objects”

To extend business objects
1. Register the extended business objects by adding their class paths to the
extension properties file.
The extension business object can flow through existing transactions or newly
defined transactions. You must register the extended business objects by adding

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

their class paths to the extension properties file. Also, the extension business
object and its attributes must be defined as data in the group/element data
tables and the Rules of Visibility tables.
See “To register extended and new business objects in the metadata repository”
on page 36 for more information.
2. Provide transaction-level logic for the addRecord(), updateRecord(), and
getRecord() functions.
Each extension object inherits from the parent object. The extended business
object should override all of these with transaction-level logic for the add,
update and get functions.
The addRecord() and updateRecord() method in the extension object provide
persistence of the extended data when the base product data is persisted. In
other words, the addRecord() method on the extension is invoked when the
data contained within the product business object is persisted. Likewise for
updateRecord().
3. Provide extension data retrieval logic for the getRecord() method stub and
update the tcrm_extension.properties file.
The getRecord() method stub provides the inquiry transaction to retrieve
client- extended business object values. To use the getRecord() method stub,
override the getRecord() method stub with your extension data retrieval logic
and add an entry to the tcrm_extension.properties file for the extended
business object, in the format:
baseBObjName_Extension=FullExtendedBObjClassName

For example, TCRMContractRoleLocationBObj_Extension=com.dwl.tcrm.samples.
extension.component.RoleLocationBObjExt.
4. Define the validations for the extended attributes using the external validations
component, or define them internally within the extended business object.
You can use the external validation component if you are creating a validation
that is specific to your company, and use the external validation to define
validations for the extended attributes such as minlength, disallowed values,
and others. Or, if you are creating a validation that is specific to the InfoSphere
MDM Server product, the validations can be defined internally within the
extended business objects. There are two validate methods stubs that are called
in a similar fashion to the add and update stubs, validateAdd() and
validateUpdate(). The validate stubs are invoked as part of the validation
process.
Note: For an example, see the Contact sample that is available on the
InfoSphere MDM Server Support site.

Extending database tables for new functions
InfoSphere MDM Server provides two approaches to extend the database.
To extend the database, you can either:
v Create a new extension database table.
v Alter an existing core product database table.
See also:
“To create a new extension database table for new functions” on page 26
“To alter an existing core product database table” on page 26

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

To create a new extension database table for new functions
1. Create a new database table that forms a one-to-one relationship with the
existing table.
2. Copy the primary key from the table being extended.
3. If history is required on the extension table, create a history table with the
appropriate database triggers.
4. Map the new extension table to the new entity object and business object.

To alter an existing core product database table
1. Make the alterations to the core database table.
2. If history is required on the extended columns, drop the existing triggers on the
core database table, alter the corresponding core history table and create the
appropriate database triggers.

Defining extended functions in the request and response framework
XSD
The Request framework XSD is responsible for parsing the extended business
objects (BObjs) on request, and converting them to XML on response. The business
objects for the extended function need to be defined in the extension XSD, or, if the
XML schema is used, the extension schema.
For an extension, you create a new business object as a child of the existing
business object you are extending. For example, in the Contact table extension
sample, the contact functionality is being extended, so the Person and Organization
BObjs, which are related to that function, are extended. For an addition, you create
a new business object in the Extension XSD.
When defining the addition or the extension business object in the request XSD, it
is important to specify the correct attributes and their order.
See also:
“To define extended functions in the Request and Response framework XSD”
“To define functions in the Response XSD” on page 28

To define extended functions in the Request and Response
framework XSD
v If you want to define functions in the request XSD:
1. Define all attributes which can be passed into the request for the addition or
the extension business object. For extension business objects, attributes from
the super class do not need to be defined.
2. Ensure that every attribute defined in the request XSD has a corresponding
setter method in the addition or extended business object.
v If you want to define extended business objects in the XSD:
The DWLExtension, TCRMExtension, and CommonExtensionBObj objects are
defined as follows in DWLCommonRequest_extension.xsd and
DWLCommonResponse_extension.xsd:

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

1. If the object you are extending contains the DWLExtension element, add the
extension object definition to DWLCommonRequest_extension.xsd and
DWLCommonResponse_extension.xsd.
For example, to add XDefaultSourceValueBObjExt to extend
DWLDefaultedSourceValueBObj:

2. If the object you are extending contains the TCRMExtension element, add the
extension object definition to tcrmRequest_extension.xsd and
tcrmResponse_extension.xsd.
For example, to add XPersonBObj2Ext to extend TCRMPersonBObj:

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

The following example snippit of the request XML contains both of the
extended objects:

......

XPersonBObj2Ext

100

...

XDefaultSourceValueBObjExt

2009-01-11

3. In the constructor, invoke the init() method, and initialize all the EObjs
contained within this new business object
4. Insert all new fields in the init() method metaDataMap, following the
InfoSphere MDM Server nullable field design, for example:
metaDataMap.put("XXXFieldName", null);

5. If you are creating new transactions that provide addition functionality, add
the transactions for new business objects to the CdBusinessTxTp table.
6. For the Security Module, create a record for the new transaction in the User
Access and Group Access tables using the Extension Framework option in
the System Maintenance menu of the InfoSphere MDM Server user interface.
See the InfoSphere MDM Server System Maintenance Guide for more
information.

To define functions in the Response XSD
1. Define all attributes that can be returned back from the system in its response.
For extension business objects, only the attributes declared in the class itself
should be defined in the XSD. Addition business objects must each contain
their own attributes as well the following three attributes inherited from the
super class:
v ComponentID
v ObjectReferenceId
v DWLStatus
See the definition of a core business object for some examples.
2. Each attribute defined in the XSD must have a corresponding getter method
declared in the business object.
The built-in XML constructor shipped with the system, which constructs the
response XML for both core product business objects as well as addition and
extended business objects, orders the attributes of each object following the
rules described below:
v All simple String-type attributes must be placed before complex attributes
which return other business objects or vectors of business objects.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v The order of attributes within a simple or complex attribute depends on
whether the attribute is an extension business object or an addition business
object.
v The order also depends on the order of elements defined in the
corresponding response XSD.

Understanding transaction context passing and the DWLControl object
The transaction context passing feature provides InfoSphere MDM Server with a
consistent transaction context for each transaction.
v A single context instance is created for each transaction.
v This transaction context is available to all the code executing within the
transaction.
v Transaction contexts can be customized, allowing you to add new attributes.
v Transaction context information can be written out for debugging and logging
purposes.
See also:
“Instantiating and passing transaction contexts”
“Extending a transaction context”
“Logging transaction context information” on page 30

Instantiating and passing transaction contexts
InfoSphere MDM Server creates an instance of DWLControl at a central point
before DWLControl is set to the business object (BObj) or entity object (EObj). Then
the transaction context information in the DWLControl object is passed through the
transaction in the BObj or EObj, or by using a method signature.
When adding a new feature or updating existing code, you should not create a
new DWLControl object. Instead, use the existing transaction context in the BObj
or EObj, or in a method signature, for consistent transaction context behavior.

Extending a transaction context
The transaction context passing feature provides you with the ability to add your
own attributes to a transaction context.
The following sample XML snippet shows the DWLControl object with an
extension:

Security Only User
100
UserAll1

testTransactionContext

test

Two new context attributes have been added to DWLControl in the sample:
name=”associatedContexts" and value="testTransactionContext"
name="currentContext" and value="test"

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

You can extend the transaction context by using the recommended template:
NewContextValue

Fill in the NewContextName and NewContextValue with the preferred name and value
pair in the template in the request XML. The request XML can provide multiple
extension properties.
The transaction context is wrapped in the ControlExtensionProperty class, which
has three fields: name, value, and includedInResponse.
The default value for the field includedInResponse in the
ControlExtensionProperty class is true, meaning that this context extension will be
returned in the response XML file. If you want to hide the context extension in
response XML file, you must set the includedInResponse flag to false in the client
code. See the sample code above for detail.
Sample code that retrieves the transaction context extension follows:
//context extension name
String attName = null;
//context extension value
ControlExtensionProperty attValue = null;
Hashtable properties = new Hashtable();
DWLControl context =//get DWLControl instance from BObj/EObj or method signature;
Map extMap = (Map)context.getControlExtensionMap();
if(extMap != null && !extMap.isEmpty()){
Iterator it = extMap.keySet().iterator();
//loop through all the elements
while (it.hasNext()) {
//retrieve context extension from map:
attName = (String)it.next();
if(attName != null && attName.length() >0) {
attValue = (ControlExtensionProperty)extMap.get(attName);
//put the key/value pair to hashtable for later use:
properties.put(attName, attValue. getValueAsString());
//if clients want to hide context extension in response,
//the includedInResponse flag must be set to false.
//E.g. attValue.setIncludeInResponse(false);
...
}
}

Logging transaction context information
InfoSphere MDM Server records transaction context information to the
Customer.log file at the point after request parsing when the logger is set at the
FINEST logging level.
The following is a sample of transaction context information as recorded in a
Customer.log file:
...
2007-05-03 12:41:53,484 INFO
- DWLAdminXMLRequestParser : parseRequest :
total time in milliseconds 16
2007-05-03 12:41:53,484 DEBUG
- com.dwl.base.DWLControl:
100
en
cusadmin

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
5013000
testTransactionContext
test

...

Creating event behavior extensions
The previous section outlined extending a transaction to extend the controller
component operations of InfoSphere MDM Server. This section discusses extending
an action to extend the business component operations of InfoSphere MDM Server.
The InfoSphere MDM Server extension framework allows you to extend InfoSphere
MDM Server behavior in an event-based way. The following points within the
product can be extended to provide additional functionality:
v Pre-transaction-controller-level
v Post-transaction-controller-level
v Pre-action-component-level
v Post-action-component-level
v Predefined points.
There may be other predefined points within the business component operations of
InfoSphere MDM Server features that can be extended-these are documented in the
chapter for that feature.
As an example, assume the following new business rule needs to be implemented:
when adding a person into the role of owner onto a contract, if that person is less
than the age of 18, then an alert must be associated to the party role indicating a
minority owner.
Logically, then, to implement this rule, you need to create an extension of the
action of adding a person into a party role, or, more specifically, you need to write
an external rule that is executed at the post of the
IContract.addContractPartyRole controller method.

Extending functions through the rules engine
If you do not want to use Java to create extensions, you can use a rules engine to
extend functions.
When you create an event behavior extension through the rules engine, the adapter
asserts a rule fact which includes the extension parameters and the current
business object; it then calls on the rule engine to activate the rules. The results of
executing the rule, including any error status, are ultimately returned to the
originating controller method.
For more information on rules and rule engines, see Chapter 10, “Configuring
external business rules,” on page 153.
Implementing business rules by using a rules engine consists of developing the
rule script, such as a JRules ilr file, and then registering that file with the extension
handler and defining under what conditions to activate rules in that rule set.
Depending on the business requirements, you must determine whether or not the
full transaction, the working object hierarchy, or both, should be asserted to the
Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

rule engine’s working memory, or just into the root objects in the hierarchy. If you
need complete information for a transaction, you need to pass the whole root
object—if a rule execution requires complete data for a transaction, then the
transaction-level business object must be passed to the rule engine.
For example, a rule set containing all insurance-specific rules can be created. This
rule set is to be invoked whenever the line of business element in the XML header
is ″Insurance″. The ″minority-aged owner″ rule as described above would look like:
When
ExtParameter(getAction().equals("addContractPartyRole"));
PartyRole(getRoleType().equals("Owner"); getParty().getAge() <=18)
Then
var contractComponent = new (IContract)ContractComponent
var alert = new Alert
alert.setAlertType("Minority Aged Owner")
...
contractComponent.addAlert(alert)

A rule-engine extension is a standard rule-engine file—an ilr file with the default
ROV rules engine. The ruleExtensionSet adapter class asserts a rule fact that
contains the parameters described above and the current working object as defined
in the assert rule parameter.
assertFact(params);
assertFact(params.getTransactionObjectHierarchy());

Note: Since a rule-engine extension is defined as a rule file, it may contain
multiple rules; in that case, each rule must determine internally whether it is the
one to be executed this time or not.
For example:
when
{
ExtensionParameters( getTriggerCategoryType().equalsIgnoreCase("Post
Transaction");
?txn:getTransactionType();
(txn.equalsIgnoreCase("AddContract")
}
then
{
}

The extension handler determines only which rule file is to be ″fired″ by the rule
engine, not the specific rule within the file.
For more information on coding rules, see the sample iLog rules files provided
with InfoSphere MDM Server.

Understanding Java behavior extensions
Java behavior extensions can be created by developers and are used by default to
implement additional business rules, or when a new module needs to be invoked.
The new Java class module may be either:
v technical code that integrates to other systems
v code that does transformations on data
v code that hooks to engines such as a rules of visibility engine or a dynamic
grouping engine.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

For example, at the ″post of all inquiry transactions″ we may want to invoke the
rules of visibility engine to filter out data the user is not entitled to view.
A Java extension is a class which extends
com.dwl.base.extensionFramework.ClientJavaExtensionSet. It must provide an
execute(ExtensionParameters) method.
See also:
“To extend transaction behavior using Java”

To extend transaction behavior using Java
1. Define the extension parameters passed to the execute(ExtensionParameters)
method as follows:
public class ExtensionParameters {
protected String transactionType;
protected String transactionCategoryType;
protected String actionType;
protected String actionCategoryType;
protected String triggerCategoryType;
protected String lineOfBusiness;
protected String geographicalRegion;
protected String company;
protected DWLControl control;
protected Object workingObjectHierarchy;
protected Object transactionObjectHierarchy;
protected Object additionalDataMap;
protected String[] inquiryParameters;
protected DWLStatus extensionSetStatus;

2. The Java rule—a Java class—gets this extension parameter object, and can
access information from it to execute the object’s logic. A Java rule class can
contains multiple rules. In this case, ruleId is used to determine which rule is
run.
For more information on coding Java rules, see the sample Java rules files
provided with InfoSphere MDM Server.

Creating additions to add new data and functionality
Additions are new code tables and database tables that are independent of existing
code. They add new functionality without affecting existing functions.
An addition may:
v Add new transactions to existing modules. The new transactions can accept and
return either existing InfoSphere MDM Server business objects, or new
client-defined business objects.
v Add a new subject area or module. For example, adding a new physical body
profile area that has its own set of transactions and related data elements.
In creating an addition, the same technical framework as the InfoSphere MDM
Server architecture is used. This is illustrated in the figure below.

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

Addition

Additional Business
Objects

Extended
XML Schema

<>
<>

Additional
Entity Beans

EXTxxxTxn
<>
EXTxxxFinder

Additional
Entity Objects

Extended
database

JDBC for Read Access

Base

Business Objects

XML Schema
(DTD)

controls txn

Audit
database

<>
<>

TCRMxxxTxn

DWLServiceController

Entity Objects

database

TCRMxxxFinder
JDBC for Read Access

Infrastructure
Components

The steps to creating an addition are similar to creating an extension, and involve:
v Creating new database functional and code tables—this process is similar to the
one for creating extensions
v Creating new entity objects—this process is similar to the one for creating
extensions
v Business objects as data—this process is similar to the one for creating
extensions existing business objects do not need to be extended
v Controller components to provide transactions
v Business components to provide services to the transactions
v in the Request framework, a new Business Proxy for the transaction. The
InfoSphere MDM Server Request framework allows clients to plug in business
proxies to control the flow of transactions or perform additional steps before
calling InfoSphere MDM Server transactions—see the Request framework sample
for more information
Important: When you add new transactions to existing modules, ensure that the
transaction names are unique. Overloading transactions is not supported by
InfoSphere MDM Server. With unique transaction names, InfoSphere MDM Server
will be able to properly and uniquely identify transaction during run time and log
a correct entry for it into the TAIL.
For specific information on performing these steps, refer to the Reminder Addition
sample that is available on the InfoSphere MDM Server Support site.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

See also:
“Creating client additions”
“To create new business objects”

Creating client additions
Client additions generally involve creating new database tables and new
transactions, including add, update and get. These additions must be linked to the
existing InfoSphere MDM Server functionality without actually modifying any
existing code.
This linking is achieved through external elements, in particular:
v
v

XSDs
properties files

The InfoSphere MDM Server Workbench should be used to create client additions.
See the IBM InfoSphere Master Data Management Server Workbench User Guide for
more information.

To create new business objects
Following the technical architecture, entity objects map to business objects. When
you have added a new database table and introduced a new entity object, you
need to map the new entity object to a new business object.
Note: The new business object must implement IExtension or IDWLExtension, and
the name must not end with Ext. For example, Person and Phone are valid name
examples, while PersonExt and PhoneExt are invalid names.
1. Register the new business objects by adding their class paths to the extension
properties file.
The new business object can flow through newly defined transactions. You
must register the new business objects by adding their class paths to the
extension properties file. Also, the new business object and its attributes must
be defined as data in the group/element data tables, and the Rules of Visibility
tables.
See “To register extended and new business objects in the metadata repository”
on page 36 for more information.
2. Define the validations for the new attributes by either using the external
validations component, or defining them internally within the new business
object.
If you are creating a validation that is specific to your company, use the
external validation component to define validations for the extended attributes
such asminlength, disallowed values, and others.
If you are creating a validation that is specific to the InfoSphere MDM Server
product, the validations can be defined internally within the new business
objects. There are two validate methods stubs that are called in a similar
fashion to the add and update stubs, validateAdd() and validateUpdate(). The
validate stubs are invoked as part of the validation process.
v Create two new Controllers—TxnBean and Finder—to service the business
objects:
v TxnBean controller is a session bean extending InfoSphere MDM Server base
transaction controller. This controller provides services to add and update

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

new functionality. It also delegates persistence responsibility to new
components. The TxnBean controllers must also have plug-ins for pre- and
post-execute.
v Finder controller is a Java class extension InfoSphere MDM Server base
finder controller. This component provides services for inquiry transactions.
It also delegates inquiry logic to the business logic component created in the
next step.
3. Create a component to perform the business logic for the new functionality.
This component provides methods used by the various controllers and other
components to service these new business objects. These components extend
IDWLCommonComponent.

Registering extended and new business objects
Any addition or extension business object requires its metadata to be captured in
the metadata repository. The metadata repository is a collection of database tables
which capture information like Java class name, attributes of the class, the order in
which they appear in, say an XML, response, if they are part of the business key or
not, and so on. This metadata is used by various modules and must be kept in
sync with the actual definition of the business object. Information for all core
product business objects is already contained in the metadata repository and
should not be modified.
The task in this section describes how to setup the metadata repository for the
addition and extension business objects.
See also:
“To register extended and new business objects in the metadata repository”

To register extended and new business objects in the
metadata repository
1. Insert the class information into the V_GROUP table. The value of the
object_name column must be the fully-qualified Java class name of the business
object.
2. Insert all elements of this class or group into the V_ELEMENT table. The list of
these elements is determined by the following way:
v Insert all elements of this class or group into the V_ELEMENT table. The list
of these elements is determined by the following way:
v List all public getter methods-methods that start with ’get’ in the Java class
and all super classes, excluding all methods with the get, getClass,
getControl, getRecord, and getEObj
v Insert one record into V_ELEMENT that corresponds to the remaining getter
methods. The value of the attribute_name column should be the name of the
getter method without the prefix ″get″. In other words, if there is a getter
method called getAccountNumber, then the attribute name is
AccountNumber.
v As a convention, the value of the element_name should be the same as the
attribute_name.
v Set the value of the response_order column for all the elements records. The
response_order must be an integer value, which must sort the elements
(attributes) of the given object in the same order as they appear in the
response DTD, as described in a previous section. As a guideline, give some
space in between the order values to allow for future attributes to be inserted

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

in between the existing ones—for example use 10, 20, 30... as the
response_order values. For extension business object, the response_order only
need to be set for its own getter methods, that is, the getter methods
declared in the class itself and not the ones declared in the super class.

Adding metadata to added or extended tables and columns
When you add or extend tables and columns in InfoSphere MDM Server, and add
or update transactions, if you wish them to use metadata, you must populate the
metadata tables or columns.
See also:
“To add metadata to added or extended tables and columns”

To add metadata to added or extended tables and columns
The following shows the ddl for the Reminder table sample provided with
InfoSphere MDM Server:
CREATE TABLE REMINDER (
REMIND_ID BIGINT NOT NULL ,
PRIORITY_TP_CD BIGINT ,
CONT_ID BIGINT ,
REMIND_RECORDED_BY VARCHAR(20) ,
REMIND_DTM TIMESTAMP ,
REMIND_DESC LONG VARCHAR NOT NULL ,
REMIND_USER_ID VARCHAR(20) ,
RECORDED_DTM TIMESTAMP ,
LAST_UPDATE_DT TIMESTAMP NOT NULL WITH DEFAULT CURRENT TIMESTAMP,
LAST_UPDATE_USER VARCHAR(20) )
IN USERSPACE1 ;
ALTER TABLE REMINDER
ADD PRIMARY KEY
(REMIND_ID);
ALTER TABLE REMINDER
ADD CONSTRAINT F_REM_CONTACT_ID FOREIGN KEY
(CONT_ID)
REFERENCES CONTACT (CONT_ID)
ON DELETE RESTRICT
ON UPDATE RESTRICT;

There are four transactions that must have metadata added to them:
v
v
v
v

addReminder
updateReminder
getReminderByPartyId
getReminderByReminderId

The following data must be populated for Metadata. It can be populated using the
XML services provided with this feature.
To populate the metadata for a table, column or transaction.
1. Add a new record to the CDDWLTABLETP table of the REMINDER table:
insert into cddwltabletp values (100000001, 'REMINDER', '', current timestamp,
null, 'N', 1).

2. Add the following new records to the CDDWLCOLUMNTP table for columns:

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM
insert into cddwlcolumntp values (100000001,
current timestamp, '');
insert into cddwlcolumntp values (100000002,
current timestamp, '');
insert into cddwlcolumntp values (100000003,
current timestamp, '');
insert into cddwlcolumntp values (100000004,
null, current timestamp, '');
insert into cddwlcolumntp values (100000005,
current timestamp, '');
insert into cddwlcolumntp values (100000006,
current timestamp, '');
insert into cddwlcolumntp values (100000007,
current timestamp, '');
insert into cddwlcolumntp values (100000008,
current timestamp, '');
insert into cddwlcolumntp values (100000009,
current timestamp, '');
insert into cddwlcolumntp values (100000010,
null, current timestamp, '');

100000001, 'REMIND_ID', null,
100000001, 'PRIORITY_TP_CD', null,
100000001, 'CONT_ID', null,
100000001, 'REMIND_RECORDED_BY',
100000001, 'REMIND_DTM', null,
100000001, 'REMIND_DESC', null,
100000001, 'REMIND_USER_ID', null,
100000001, 'RECORDED_DTM', null,
100000001, 'LAST_UPDATE_DT', null,
100000001, 'LAST_UPDATE_USER',

3. Add the following transactions to the CDBUSINESSTXTP table
insert into cdbusinesstxtp values(100000001, 'addReminder', null, null,
current timestamp, 'Y', 'P', null, 1);
insert into cdbusinesstxtp values(100000002, 'updateReminder', null, null,
current timestamp, 'Y', 'P', null, 1);
insert into cdbusinesstxtp values(100000003, 'getReminderByPartyId', null, null,
current timestamp, 'Y', 'I', null, 1);
insert into cdbusinesstxtp values(100000004, 'getReminderByReminderId', null,
null, current timestamp, 'Y', 'I', null, 1);

4. Add the following Request and Response objects to the BUSINESSTXREQRESP
table:
insert into businesstxreqresp values (100000001, 100000001, 'TCRM', 'Reminder',
'I', null, null, null, 'cusadmin', current timestamp, null);
insert into businesstxreqresp values (100000002, 100000001, 'TCRM', 'Reminder',
'O', null, null, null, 'cusadmin', current timestamp, 'N');
insert into businesstxreqresp values (100000003, 100000002, 'TCRM', 'Reminder',
'I', null, null, null, 'cusadmin', current timestamp, null);
insert into businesstxreqresp values (100000004, 100000002, 'TCRM', 'Reminder',
'O', null, null, null, 'cusadmin', current timestamp, 'N');
insert into businesstxreqresp values (100000005, 100000003, null, null, 'I', 2,
'thePartyId', 1, 'cusadmin', current timestamp, null);
insert into businesstxreqresp values (100000006, 100000003, null, null, 'I', 5,
'theTCRMControl', 2, 'cusadmin', current timestamp, null);
insert into businesstxreqresp values (100000007, 100000003, 'TCRM', 'Reminder',
'O', null, null, null, 'cusadmin', current timestamp, 'Y');
insert into businesstxreqresp values (100000008, 100000004, null, null, 'I', 1,
'theReminderIdPK', 1, 'cusadmin', current timestamp, null);
insert into businesstxreqresp values (100000009, 100000004, null, null, 'I', 5,
'theTCRMControl', 2, 'cusadmin', current timestamp, null);
insert into businesstxreqresp values (100000010, 100000004, 'TCRM', 'Reminder',
'O', null, null, null, 'cusadmin', current timestamp, 'N');

5. Add the following reminder object to the V_GROUP table:
INSERT INTO V_GROUP ( APPLICATION, GROUP_NAME, OBJECT_NAME, LAST_UPDATE_DT,
CODE_TYPE_IND )
VALUES ( 'TCRM', 'Reminder', 'com.dwl.tcrm.samples.addition.component.
TCRMReminderBObj', CURRENT TIMESTAMP, 'N' );

6. Add the following record to the GROUPDWLTable table:
insert into groupdwltable values(100000001, 'TCRM', 'Reminder', 100000001,
'cusadmin', current timestamp)

7. Add the following elements to the V_ELEMENT table:

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('ComponentID', 'Reminder', 'TCRM', 'ComponentID', current
timestamp, 10, 'TCRM', 'Reminder', null, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('ObjectReferenceId', 'Reminder', 'TCRM', 'ObjectReferenceId',
current timestamp, 20, 'TCRM', 'Reminder', null, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('ReminderIdPK', 'Reminder', 'TCRM', 'ReminderIdPK', current
timestamp, 30, 'TCRM', 'Reminder', 100000001, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('PriorityType', 'Reminder', 'TCRM', 'PriorityType', current
timestamp, 40, 'TCRM', 'Reminder', 100000002, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('PriorityValue', 'Reminder', 'TCRM', 'PriorityValue', current
timestamp, 50, 'TCRM', 'Reminder', null, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('PartyId', 'Reminder', 'TCRM', 'PartyId', current timestamp, 60,
'TCRM', 'Reminder', 100000003, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('RecordedBy', 'Reminder', 'TCRM', 'RecordedBy', current timestamp,
70, 'TCRM', 'Reminder', 100000004, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('ReminderTime', 'Reminder', 'TCRM', 'ReminderTime', current
timestamp, 80, 'TCRM', 'Reminder', 100000005, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('ReminderDescription', 'Reminder', 'TCRM', 'ReminderDescription',
current timestamp, 90, 'TCRM', 'Reminder', 100000006, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('ReminderUserId', 'Reminder', 'TCRM', 'ReminderUserId', current
timestamp, 100, 'TCRM', 'Reminder', 100000007, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('RecordedTime', 'Reminder', 'TCRM', 'RecordedTime', current
timestamp, 110, 'TCRM', 'Reminder', 100000008, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('ReminderLastUpdateDate', 'Reminder', 'TCRM',
'ReminderLastUpdateDate', current timestamp, 120, 'TCRM', 'Reminder',
100000009, null);
INSERT INTO V_ELEMENT (ELEMENT_NAME, GROUP_NAME, APPLICATION, ATTRIBUTE_NAME,
LAST_UPDATE_DT, RESPONSE_ORDER, ELEMENTAPPNAME, ELEMENTGROUPNAME,
DWLCOLUMN_TP_CD, CARDINALITY_TP_CD)
VALUES ('ReminderLastUpdateUser', 'Reminder', 'TCRM',
'ReminderLastUpdateUser', current timestamp, 130, 'TCRM',
'Reminder', 100000010, null);
Chapter 2. Customizing InfoSphere MDM Server

To test an extension or addition
Test your new extensions or additions using the IBM InfoSphere Master Data
Management Server testing mechanism.
1. Create sample transaction XML files as required to service your functionality.
2. Run standard test procedures.

Recognizing extensions and additions in InfoSphere MDM Server
Once you have created an extension, an addition or metadata specs in InfoSphere
MDM Server, you must also revise the InfoSphere MDM Server features to
recognize and work with the new modifications.
See also:
“To update product features to recognize extensions and additions”

To update product features to recognize extensions and
additions
The InfoSphere MDM Server features that need to be updated are as follows:
v Transaction Audit Log - To integrate with the Transaction Audit Log, see
“Setting up new transactions in the transaction audit information log” on page
233 and “Understanding database considerations for history inquiry” on page
215.
v Rules of Visibility - To integrate with RoV, you must register the business
objects with the group and element table-see the information below-and create
or update the data associations to include the new objects. You must also set up
entitlements to grant users add/update/view rights for the data associations.
See “Understanding Rules of Visibility permissions” on page 394.
v Error logging - You must populate IBM InfoSphere Master Data Management
Server Error reporting database tables to make use of error handling within their
added functionality.
v Group element - Register new and extended business objects with the Group
and Element tables. Add a record to the Group table for a business object with
its name and other required properties. Insert all fields of the business object as
records in the Element table. Each record contains the name of the field, an
indicator to show if its part of business key, and other information about the
BObj. RoV, external validation and suspect processing reference this table for
information on all business objects in the system.
v Nullable fields - See the Contract Table Extension sample for information on
integrating nullable fields with an addition or extension.
v Security - See Chapter 32, “Setting and administering the security service,” on
page 383.

Accessing samples of extensions and additions
Samples to help you understand how to create and implement various types of
extension and additions for InfoSphere MDM Server are available.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Samples are not installed with the product and can be found on the InfoSphere
MDM Server distribution media.

Understanding InfoSphere MDM Server runtime metadata
This section introduces the concept of runtime metadata.
Metadata is a generic name given to any information that describes the structure of
data. It is often described as data about data.
The InfoSphere MDM Server runtime uses metadata to provide a flexible,
lightweight mechanism for defining structures of data that have a range of uses.
Some examples of business entities that use metadata in the runtime include:
v PRODUCTTYPE (for defining product type hierarchy). See also Chapter 60,
“Configuring the product type hierarchy,” on page 729.
v SPEC (for defining extension to class entities). See also Chapter 3, “Managing
specs and spec values,” on page 61.
v TASKDEFINITION (for defining task definition in Task Management). See also
Chapter 37, “Customizing task management,” on page 509.
The following is a partial data model showing how InfoSphere MDM Server
runtime manages metadata for the above business entities.

The CDMETADATAPACKAGETP and CDMETADATAINFOTP tables provide a code table driven
reference point to the metadata deployed on the InfoSphere MDM Server runtime.
When the metadata are deployed to the InfoSphere MDM Server runtime using
InfoSphere MDM Server services, the CDMETADATAPACKAGETP and CDMETADATAINFOTP
tables are validated to ensure records are defined in these two code tables. Also,
some services are provided with the code table as reference. For example, the
Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

getSpecsByMetadataPackage service is provided to allow a user to retrieve all
specs by metadata package that are deployed on the InfoSphere MDM Server
runtime.
The actual metadata pertaining to a particular business entity is defined in the
business entity or other entities related to it. For example, metadata for task
definition is defined in the TASKDEFINITION and CATASKLAUNCHACTIONTP entities;
metadata for specs is defined in the SPEC, SPECFMT, and SPECFORMATTRANSLATION
entities.

Maintaining metadata with InfoSphere MDM Server Workbench
The development of some metadata, such as task definition, is relatively straight
forward. It uses the concrete data model provided by InfoSphere MDM Server. A
user (typically a business user) designs the data required by the data model and
executes the appropriate services to populate the data.
On the other hand, the development of spec as metadata is more involved. Because
of the nature of specs, users essentially create a dynamic data model using
XML/XSD technology to extend the concrete data model. This requires planning
and design from business users as well as technical users. Although services are
provided to populate spec metadata, the InfoSphere MDM Server Workbench
provides a set of tools to help you in the planning, design, and maintenance of
spec metadata.
In addition to spec metadata, the InfoSphere MDM Server Workbench provides a
set of wizards to help you to develop metadata for Product type hierarchy.
After you develop the metadata, the InfoSphere MDM Server Workbench provides
deployment tools to help you to deploy the metadata to the InfoSphere MDM
Server runtime.
For more information on developing metadata specs, see Chapter 3, “Managing
specs and spec values,” on page 61.

Understanding component functions
Entity objects (EObj) - matches all the column names defined in a table and the
related get/set method. The EObj is used to pass data between the data access
layer and other components.
Business objects (BObj) are value objects in InfoSphere MDM Server. They
encapsulate one or more EObjs. These objects contain getters and setters which in
turn retrieve or set values in EObjs. Compared to an EObj, the getter/setters
methods in a BObj perform data format conversions. To support the XML interface
to InfoSphere MDM Server, the setter methods in BObjs only take string
parameters as input. These strings parameters then need further data conversion to
match the enclosing EObjs. For example, to set a timestamp field from string input
data, the String must be converted to Timestamp. Further, these BObjs contain a
get/set method pair to retrieve an EObj, and two special methods that are
overridden from e superclass for internal validation: validateAdd(int, DWLStatus),
validateUpdate(int, DWLStatus)
Data access layer represents a way of accessing a database table.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Data interface is a generated interface that provides select, insert, update and
delete access to a database table.
InquiryData interface is an interface that provides additional select, insert, update
and delete methods to access the database. .
pureQuery is an IBM data access layer implementation that is used by InfoSphere
MDM Server.
InfoSphere MDM Server components are business components within InfoSphere
MDM Server which contain methods to perform all the business logic. For
example, a Party component has methods to add , update and retrieve party.
InfoSphere MDM Server controllers are used as functional entry points to
InfoSphere MDM Server. There are two types of controllers: transactional; and non
transactional. The methods within these controllers are all the transactions offered
by InfoSphere MDM Server.
Transactional controllers are session beans that participate in an ongoing
transaction or create a new transaction if there is none. They allow the add and
update persistence transactions to run within a transactional context-for example,
TCRMCorePartyTxnBean is a transactional controller with methods likes addParty,
and updateParty
Non-transactional controllers are generic finder classes that service inquiry or
search transactions. These are light weight classes that do not use transactional
capabilities offered by the application serve-for example, TCRMCorePartyFinder is a
finder controller with methods like getParty, SearchParty and others. These
controllers delegate the transactions to business components-defined above-to
perform business logic.
Common Services features are common modules that are necessary for performing
certain nonfunctional operations. For example, the Extension framework contains
all the classes to support the extension mechanism within InfoSphere MDM Server.
Some of the other features with common service features are Rules of Visibility and
Transaction Audit Log. All of these features have their own components to execute
feature-specific logic.

Using the pureQuery data access layer
The pureQuery component is an IBM data access layer implementation that is used
by InfoSphere MDM Server.
The pureQuery data access layer changes the way EObjs are added, updated and
retrieved from the database. This changes the component level code for add,
update and get. It also changes anywhere that the object is returned in the
BObjQuery framework.
The EObj code is changed to include annotations which map the fields to columns
in a database table.

EObj code examples
pureQuery Java annotations are used to map the EObj to its database table. For
example:

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM
@Table(name="XCONTACT")
public class EObjXContactextends EObjCommon{

All the fields on the EObj should be annotated to map the field to the database
column. For example:
@Id
@Column(name="CONTIDPK")
public LongContIdPK;
@Column(name="RISKSCORE")
public StringRisk_Score;

New methods setPrimaryKey and getPrimaryKey methods are used internally
when generating primary keys for the EObj. For example:
public void setPrimaryKey(ObjectaUniqueId){
//set primary key field here
this.setContIdPK((Long)aUniqueId);
}
public Object getPrimaryKey(){
//return Primary Key in string format
return this.getContIdPK();
}

Add any special processing required. If there is specialized processing that you
require on this EObj before or after either an add or an update, you can add the
following methods to your EObj:
v beforeAddEx()
v afterAddEx()
v beforeUpdateEx()
v afterUpdateEx()
For example:
protectedvoidbeforeAddEx(){
if(getStartDt()==null){
setStartDt(getCurrentTimestamp());
}
}

See also:
“Using data interfaces to access the database”
“Using pureQuery utility classes” on page 45
“Understanding component level code” on page 45

Using data interfaces to access the database
The data interfaces are used to define the simple select, insert and update
statements that are used to access the database.
The Workbench generates the data interface and its DataImpl implementation class.
The implementation class is where the actual SQL execution logic is generated.

Example
import java.util.Iterator;
import java.sql.Timestamp;
import com.ibm.pdq.annotation.Select;
import com.ibm.pdq.annotation.Update;
public interface EObjXContactData {

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
// Select XCONTACT by parameters
@Select(sql="select CONTIDPK, RISKSCORE, RISKRECORDEDDT, LASTUPDATEDT, LASTUPDATEUSER,
LASTUPDATETXID from XCONTACT where CONTIDPK = ? ")
Iterator getEObjXContact(Long ContIdPK);
// Create XCONTACT by EObjXContact Object
@Update(sql="insert into XCONTACT (CONTIDPK, RISKSCORE, RISKRECORDEDDT, LASTUPDATEDT,
LASTUPDATEUSER, LASTUPDATETXID) values( :ContIdPK, :Risk_Score, :Risk_Recorded_Dt,
:lastUpdateDt, :lastUpdateUser, :lastUpdateTxId)")
int createEObjXContact(EObjXContact e);
// Update one XCONTACT by EObjXContact object
@Update(sql="update XCONTACT set CONTIDPK = :ContIdPK, RISKSCORE = :Risk_Score,
RISKRECORDEDDT = :Risk_Recorded_Dt, LASTUPDATEDT = :lastUpdateDt,
LASTUPDATEUSER = :lastUpdateUser, LASTUPDATETXID = :lastUpdateTxId where CONTIDPK
= :ContIdPK and LASTUPDATEDT = :oldLastUpdateDt")
int updateEObjXContact(EObjXContact e);
// Delete XCONTACT by parameters
@Update(sql="delete from XCONTACT where CONTIDPK = ? ")
int deleteEObjXContact(Long ContIdPK);
}

Note that the Workbench generates this code slightly differently using constants to
define the actual SQL statements.
These createEObjXContact and updateEObjXContact methods are used in the
component level methods to add and update the EObj.

Using pureQuery utility classes
There are three utility classes for working with pureQuery in the InfoSphere MDM
Server project.
They are:
v com.dwl.base.db.DataManager
v com.dwl.base.db.DataAccessFactory
v com.dwl.base.db.QueryConnection

Examples
The DataManager is used to get QueryConnection instances as follows:
DataManager.getInstance().getQueryConnection()

The DataAccessFactory is used to create the Data implementation instance for the
given Data interface and QueryConnection:
(EObjXContactData) DataAccessFactory.getQuery(EObjXContactData.class, queryConnection)

The QueryConnection is needed to create the Data implementation instance as
shown above and to close the connection to the database:
try {
queryConnection.close();
} catch (Exception e) {}

Understanding component level code
When adding and updating entity objects, it is preferable to use the three utility
classes for working with pureQuery as mentioned in “Using pureQuery utility
classes.” Once the Data implementation instance has been created we can use the
generated create and update methods.

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

Example
EObjXContact Add Record example:
QueryConnection queryConnection = null;
try {
queryConnection = DataManager.getInstance().getQueryConnection();
EObjXContactData xContactData =
(EObjXContactData) DataAccessFactory.getQuery(EObjXContactData.class, queryConnection);
xContactData.createEObjXContact(getEObjXContact());
} finally {
try {
queryConnection.close();
} catch (Exception e) {}
}

EObjXContact Update Record example:
QueryConnection queryConnection = null;
try {
queryConnection = DataManager.getInstance().getQueryConnection();
EObjXContactData xContactData =
(EObjXContactData) DataAccessFactory.getQuery(EObjXContactData.class, queryConnection);
xContactData.updateEObjXContact(getEObjXContact());
} finally {
try {
queryConnection.close();
} catch (Exception e) {}
}

When accessing the database in custom transactions or external rules, you can use
the generated method style queries to get the EObj much like you do for adding
and updating entity objects:
QueryConnection queryConnection = null;
Iterator iterator = null;
try {
queryConnection = DataManager.getInstance().getQueryConnection();
EObjXContactData xContactData =
(EObjXContactData) DataAccessFactory.getQuery(EObjXContactData.class, queryConnection);
iterator = xContactData.getEObjXContact(contactId);
} finally {
try {
queryConnection.close();
} catch (Exception e) {}
}

Creating pluggable business object queries
Pluggable business object queries encapsulate the logic that retrieves business
objects from persistent storage. This enables you to customize database access for
business objects and allows the extension framework to reduce the database access
that is required for data extensions to the core product.
All inquiry transactions of the product have pluggable query support except for
the following areas:
v DWLCommonServices Module Services (that is, TAIL, Default Source Value, Code
Table Services)
v DWLAdminServices Module
v CoreUtilities Module (Code Table Services)

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Implementing pluggable business object queries
InfoSphere MDM Server business object query classes enable the encapsulation and
easy customization of core database access functionality. The BObjQuery interface
allows you to implement new query methodologies, other than the core
implementation provided with the product, JDBC.
The AbstractSQLBObjQuery class provides the base pureQuery query
implementation provided with the InfoSphere MDM Server product. This class
contains the logic necessary to conduct pureQuery JDBC-driven queries. Each
proprietary InfoSphere MDM Server business object (BObj) has its own BObjQuery
class that extends from this AbstractBObjQuery class. When using the JDBC
implementation of InfoSphere MDM Server, extending the GenericBObjQuery class
(or one of its InfoSphere MDM Server BObjQuery subclasses) is the recommended
approach for creating any new business object query classes. Extending a
InfoSphere MDM Server BObjQuery subclass of AbstractSQLBObjQuery is only
recommended when you are replacing the BObjQuery as the result of coding an
EObj extension.
The AbstractSQLJBObjQuery class provides the base SQLJ query implementation. It
contains the necessary logic to conduct SQLJ-based queries. When using the SQLJ
implementation for new business object query classes, IBM recommends that you
extend the AbstractSQLJBObjQuery class. For details about SQLJ-based queries, see
“Implementing SQLJ-based queries” on page 53.
Each BObjQuery class is registered with a class factory corresponding to the module
to which it belongs, and interfaces exist for each module of the InfoSphere MDM
Server product. For example, PartyModuleBObjQueryFactory is the interface
implemented by the factory implementation class,
PartyModuleBObjQueryFactoryImpl. The implementation class is responsible for the
retrieval of all BObjQuery classes configured for use by services in the Party
module.
The class diagram below depicts the interfaces and abstract classes discussed in
this section along with the implementation class pertaining to the Party module
query factory example.

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Customizing an existing pluggable business object query
You can extend a core business object’s query implementation by either overriding
an existing query or creating a new, customized query.
This requires that the particular class be subclassed and a new implementation
supplied for the query to be customized. The factory class must also then be
extended to pick up this new query class, and the extended factory itself must be
registered with InfoSphere MDM Server.

Using pureQuery data access layer in pluggable business object
queries
When using the pureQuery data access layer in your business object queries, you
need provide the implementation of only two methods in most GenericBObjQuery
subclasses.
The methods are as follows:
v protected Class provideQueryInterfaceClass()
v protected IGenericResultSetProcessor provideResultSetProcessor()

Understanding the structure of a constant
Each constant in the query class has been carefully defined.
The basic structure of each constant is:
Table 1. structure of a constant
Structure of name:

QUERY

(mandatory)

(optional)

(mandatory)

v HISTORY
v ACTIVE
v
INACTIVE
v ALL
v IMAGES

Note: when no criteria are specified, a query by primary key is implied.
The following are some examples:
v AlertBObjQuery
– ALERTS_IMAGES_QUERY
– ALERT_HISTORY_QUERY
– ALERT_QUERY
–
–
–
–

ALERTS_HISTORY_QUERY
ALERTS_ACTIVE_QUERY
ALERTS_INACTIVE_QUERY
ALERTS_ALL_QUERY
Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

– ALERT_OF_PARTY_HISTORY_QUERY
– ALERT_OF_PARTY_QUERY
v CampaignAssociationBObjQuery
– CAMPAIGN_ASSOCIATION_HISTORY_QUERY
– CAMPAIGN_ASSOCIATION_QUERY
–
–
–
–
–

CAMPAIGN_ASSOCIATIONS_BY_CAMPAIGN_ID_HISTORY_QUERY
CAMPAIGN_ASSOCIATIONS_BY_CAMPAIGN_ID_ACTIVE_QUERY
CAMPAIGN_ASSOCIATIONS_BY_CAMPAIGN_ID_INACTIVE_QUERY
CAMPAIGN_ASSOCIATIONS_BY_CAMPAIGN_ID_ALL_QUERY
CAMPAIGN_ASSOCIATIONS_ACTIVE_QUERY

Extending the BObjQuery class
You can extend the query implementation of a core business object by either
overriding an existing query or creating a new, customized query.
You may need to create a new query to add to an existing BObjQuery class in
order to handle the introduction of new business functionality to the system.
See also:
“To extend the BObjQuery class”
“To override an existing query”
“To create a new query” on page 51
“To extend the BObjQueryFactory implementation class” on page 51
“To register a new factory implementation” on page 51

To extend the BObjQuery class
1. Complete one of the following tasks: “To override an existing query” or “To
create a new query” on page 51
2. Complete this task: “To extend the BObjQueryFactory implementation class” on
page 51
3. Complete this task: “To register a new factory implementation” on page 51
Note: Pseudo-code snippets are used to provide a simplified illustration of the
steps. Actual code samples are provided with the InfoSphere MDM Server
Samples that are available for download from the Support site.

To override an existing query
1. Determine which constant represents the query you wish to customize. For the
basic structure of each constant, see “Understanding the structure of a
constant” on page 49.
2. Use the Workbench to generate a subclass of the BObjQuery that implements
that query.
3. Modify the SQL statement in the InquiryData interface that was generated with
your BObjQuery.
4. Determine the order and type of parameters the existing query requires. See
your BObjQuery’s superclass for more information. In cases where the
parameters are not used in exactly the same order and number, you will need
to implement the provideSQLParams() method to process the parameters you
need for your new query in the order required by your new SQL statement.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Some queries require business object as input, for example, Party/Contract
Search. As such, business objects are provided to the BObjQuery classes as
named parameters—see the map namedParameters on the AbstractBObjQuery
class—rather than in the positional parameters List.
Note: Customizing or modifying any one particular query constant changes the
way this query constant is invoked anywhere it is currently used in the
product.

To create a new query
Note: As mentioned in the previous scenario, the provideSQLStatement() method
must be overridden to support the retrieval of the new SQL statement.
1. Add a new query constant in the GenericBObjQuery subclass.
public final static String REMINDER_QUERY =
"getReminderByPartyID (Object[])";

2. Provide an annotation for the select statement and a signature for the method:
@Select(sql="SELECTREMINDER.REMIND_ID,REMINDER.PRIORITY_TP_CD,
REMINDER.CONT_ID,REMINDER.REMIND_RECORDED_BY,REMINDER.REMIND_DTM,
REMINDER.REMIND_DESC,REMINDER.REMIND_USER_ID,REMINDER.RECORDED_DTM,
REMINDER.LAST_UPDATE_DT,REMINDER.LAST_UPDATE_USERFROMREMINDER
WHEREREMINDER.CONT_ID=?")
Iterator> getReminderByPartyID(Object[] parameters);

To extend the BObjQueryFactory implementation class
Extend the appropriate query factory to pick up the extended BObjQuery class. In
this case, the PartyModuleBObjQueryFactoryImpl class is extended and the
createPartyIdentificationBObjQuery() method is overridden.
Here is a sample code snippet:
public BObjQuery createPartyIdentificationBObjQuery(String queryName,
DWLControl dwlControl) {
if ((queryName == null) || queryName.trim().equals(""))
throw new IllegalArgumentException("Query Name cannot be empty or null.");
return new PartyIdentificationBObjExtQuery(queryName, dwlControl);
}

To register a new factory implementation
Register your extended query factory implementation class with the product by
modifying the appropriate properties file for the module. For the Party module, the
factory implementation is configured in the TCRM.properties file – see the key
Party.BObjQueryFactory – along with all other modules specific to InfoSphere
MDM Server. Factory implementations for generic services, such as
DWLBusinessServices, are likewise configured in the DWLCommon.properties file.
Sample modified property in TCRMCommon.properties:
Party.BObjQueryFactory=
com.yourcompany.party.bobj.query.extension.PartyModuleBObjQueryFactoryImplExt

Creating a new pluggable business object query
The method for introducing a pluggable query support for a new business object is
similar to the method for customizing one.
In order to understand the procedures here, you must read and be familiar with
“Customizing an existing pluggable business object query” on page 49.
Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

If you wish to create a SQLJ-based BObj query, see “Implementing SQLJ-based
queries” on page 53.
There are three basic steps to creating a new pluggable BObj query:
v “To create a new BObjQuery class”
v “To extend and register the appropriate query factory”
v “Calling the query facility from the component inquiry method”
See also:
“To create a new BObjQuery class”
“To extend and register the appropriate query factory”
“Calling the query facility from the component inquiry method”

To create a new BObjQuery class
1. Create a new BObjQuery class, extending from GenericBObjQuery JDBC
implementation.
2. Register your queryNames as constants in the class, and create a new
InquiryData interface to annotate the queries.
3. Implement the abstract method provideQueryInterfaceClass().
4. Implement the abstract method provideResultSetProcessor() on the class to
conditionally retrieve the appropriate result set processors for each query
created.

To extend and register the appropriate query factory
1. Extend the appropriate existing query factory class and register it with the
appropriate query factory class.
2. Create a new method to retrieve your query class.
Sample code snippet:
public BObjQuery createNewObjectBObjQuery(String queryName,DWLControl dwlControl) {
if ((queryName == null) || queryName.trim().equals(""))
throw new IllegalArgumentException(
"Query Name cannot be empty or null.");
return new NewObjectBObjQuery(queryName, dwlControl);
}

Note: If you are not using an existing InfoSphere MDM Server component, you
must implement logic to retrieve the appropriate query factory for that module,
which is configured in the tcrm_extension.properties file, in order to make use of
the pluggable query facility. The getBObjQueryFactory() methods in each of the
existing InfoSphere MDM Server components takes care of this.

Calling the query facility from the component inquiry method
The inquiry method needs to make calls to the query facility in order to pick up
the appropriate query logic for the implementation and process the results
retrieved from the database.
The following pseudo-code sample details this process:
//Retrieve the query factory for the component's module and create the appropriate
//BObjQuery class
BObjQuery bObjQuery = getBObjQueryFactory()
.createPartyIdentificationBObjQuery(
PartyIdentificationBObjQuery.PARTY_IDENTIFIER_BY_ID_QUERY,theTCRMControl);

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
//set any parameters to be resolved into the SQL (along with position) onto the
//query object
bObjQuery.setParameter(0, new Long(identifierId));
// retrieve type value from BObj.
TCRMPartyIdentificationBObj partyid = (TCRMPartyIdentificationBObj)
bObjQuery.getSingleResult();

Implementing SQLJ-based queries
InfoSphere MDM Server includes an SQLJ query implementation class,
AbstractSQLJBObjQuery, to support SQLJ-based queries.
The core query implementations provided with the InfoSphere MDM Server
product are based on JDBC. If you choose to use SQLJ-based database access
instead of or together with JDBC, you should still base your queries on the
BObjQuery interface.
The SQLJ query implementation class AbstractSQLJBObjQuery supports
SQLJ-based queries. Instead of implementing the BObjQuery interface directly, the
AbstractSQLJBObjQuery class extends AbstractBObjQuery class implementation to
reuse most of the implementation code.
The AbstractSQLJBObjQuery class provides the base SQLJ query implementation. It
contains the necessary logic to conduct SQLJ-based queries.
Note: When using the SQLJ implementation for new business object query classes,
IBM recommends that you extend the AbstractSQLJBObjQuery class.
The InfoSphere MDM Server SQLJ implementation includes the following
supporting classes:
v SQLJCommand class
v ISQLJCommandFactory interface
SQLJCommand describes comprehensive information about a SQLJ executable
statement. A SQLJCommand is executed by delegating the execution to its target,
which is an ISQLJCommandFactory object. A unique name is used to identify each
SQLJ executable statement in the ISQLJCommandFactory.
Each SQLJ statement should be defined in a method of its factory class that
implements ISQLJCommandFactory. Upon request, the factory class is also
responsible for executing each specific SQLJ statement. The result of an SQLJ
statement is always converted to a ResultSet object. This enables the SQLJ
implementation to reuse the same ResutSetProcessor classes to fetch query results
as are used for JDBC.
Each SQLJ statement runs in a given connection context. If you are working in a
multithreaded environment, do not use the default context; instead use the empty
class, SQLJContext.
The class diagram below depicts the interfaces and abstract classes discussed in
this topic, along with the implementation class that is used by the sampleMDM
Query Connect transaction.
The method for introducing a SQLJ-based pluggable query is similar to creating a
JDBC based business object query. Sample code is used in this section to provide a
simplified illustration of the necessary steps. Actual code samples are provided
Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

with the InfoSphere MDM Server Query Connect Samples that are available for
download from the InfoSphere MDM Server Support site.
In order to fully understand the procedures described in this section, you must
read and be familiar with “Creating a new pluggable business object query” on
page 51.
Important: This class diagram includes no detailed information for the classes
AbstractBObjQuery, TCRMPersonSearchResultSetProcessorSample, and
TCRMResultSetProcessor. Only SQLJ-related information is presented in the
SQLQuery class.

See also:
“To create a SQLJ-based pluggable business object query”

To create a SQLJ-based pluggable business object query
1. Create the ISQLJCommandFactory class.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

a. Create a new class in a .sqlj file, implementing the ISQLJCommandFactory
interface.
b. Register your sqljCommandNames as constants in the class, and affiliate the
retrieval logic with each SQLJ statement.
c. Define an Iterator for each SQLJ statement.
#sql iterator PersonIdentificationIterator (String,String,String,String,
String,Long,String,Timestamp,String,String,Long,Timestamp);

d. Implement each SQLJ statement in a method, converting the Iterator object
as a ResultSet object to return it back.
private ResultSet searchPersonByIdentification(Long idTp, String idNum)throws
DWLBaseException,SQLException{
PersonIdentificationIterator iter = null;
Long nameUsageTp = getNameUsageType();
//static sql that search person by its identification type +
//identification number + name usage type
#sql [ctx] iter = {SELECT PERSONNAME.GIVEN_NAME_ONE PNGIVENNAME1,
PERSONNAME.GIVEN_NAME_TWO PNGIVENNAME2, PERSONNAME.GIVEN_NAME_THREE
PNGIVENNAME3, PERSONNAME.GIVEN_NAME_FOUR PNGIVENNAME4,
PERSONNAME.LAST_NAME PNLASTNAME, PERSONNAME.CONT_ID PNCONTID,
PERSONNAME.SUFFIX_DESC PNSUFFIXDESC, PERSON.BIRTH_DT BIRTHDT,
PERSON.GENDER_TP_CODE GENDERTPCODE,IDENTIFIER.REF_NUM IDREFNUM,
IDENTIFIER.ID_TP_CD IDTPCD,CONTACT.INACTIVATED_DT INACTIVATEDDT
FROM PERSONNAME, PERSON,IDENTIFIER,CONTACT WHERE IDENTIFIER.ID_TP_CD =
:idTp AND IDENTIFIER.REF_NUM = :idNum AND IDENTIFIER.CONT_ID =
PERSON.CONT_ID AND IDENTIFIER.CONT_ID = PERSONNAME.CONT_ID AND
PERSONNAME.NAME_USAGE_TP_CD = :nameUsageTp AND PERSON.CONT_ID =
CONTACT.CONT_ID ORDER BY
PERSONNAME.LAST_NAME,PERSONNAME.GIVEN_NAME_ONE};
return iter.getResultSet();
}

e. Implement the methods getSQLJCommand() and executeSQLJCommand().
public SQLJCommand getSQLJCommand(String commandName){
SQLJCommand sqljCommand = new SQLJCommand();
sqljCommand.setCommandName(commandName);
sqljCommand.setTarget(this);
return sqljCommand;
}
public ResultSet executeSQLJCommand(SQLJCommand sqljCmd)throws
DWLBaseException, SQLException{
//set the connection context, this connection context is shared by
//SQLJ statement
setContext(sqljCmd.getContext());
//get the logic no of the SQLJCommond
int commandNo = sqljCmd.getCommandNo();
//get the parameters in object array
Object[] args = sqljCmd.getArgs();
ResultSet rs = null;
//call methods that contains SQLJ executable statement according
//to the command number
switch(commandNo){
case SEARCH_PERSON_BY_IDENTIFICATION:
if (args == null || args.length < 2){
throw new TCRMException("Missing parameter for sqlj command
[" + commandNo + "]");
}
rs = searchPersonByIdentification((Long)args[0],(String)args[1]);
break;
case SEARCH_PERSON_BY_IDENTIFICATION_WILDCARD:
......
}
return rs;
}

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

2. Create the BObjQuery class.
a. Create a new BObjQuery class, extended from the AbstractSQLJBObjQuery
SQLJ implementation.
b. Associate the new ISQLJCommandfactory class that you created in step 1
with the new BObjQuery.
c. Register your queryNames as constants in the class, and affiliate the
retrieval logic with each — that is, the SQLJ command.
d. Implement the abstract methods provideSQLJStatement() and
provideResultSetProcessor() on the class to conditionally retrieve the
appropriate SQLJ command and ResultSet processors for each created query.
3. Extend and register the appropriate query factory. For details, see “To extend
and register the appropriate query factory” on page 52.
4. Call the query facility from the component inquiry method. For details, see
“Calling the query facility from the component inquiry method” on page 52.

Creating a pluggable persistence mechanism
The business object query class enables the encapsulation and customization of
persistence transactions.
All persistence transactions have pluggable persistence support except the
following transactions:
1. TCRMPartyAlertComponent (Party service): Migration is not done for
deprecated methods
2. TAILAdminServicesComponent (DWLCommonServices): The update method
uses DataManager for persisting data, and not the pluggable query mechanism.
As such, pluggable persistence is not available.
3. DWLAdminServices: These services do not use pluggable queries and therefore
are not enabled to facilitate pluggable persistence mechanisms.
4. TCRMHouseHoldBObj: The persistence operation related to
EObjLocationGroup has been retained in TCRMPartyComponent
(updateHouseholdMember method)
See also:
“To replace the persistence mechanism”
“Using business object query objects for pluggable persistence” on page 57
“Customizing an existing pluggable persistence strategy” on page 58
“To customize a persistence strategy by including new columns and extension
tables” on page 59
“To extend a persistence strategy” on page 60

To replace the persistence mechanism
The code from the EObjCommonHook has not been migrated to
AbstractBObjQuery as it is specific to the pureQuery implementation. If you are
replacing the persistence mechanism, you must perform the following steps.
1. Replace the implementation of the AbstractBObjQuery class.
2. Override the throwDuplicateKeyException. This exception indicates that the
primaryKey supplied already exists.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Using business object query objects for pluggable
persistence
The InfoSphere MDM Server pluggable business object query classes enable the
encapsulation and easy customization of core database access functionality. The
new Persistence interface allows you to implement persistence strategies, other
than the core implementation provided with the product.
The AbstractSQLJBObjQuery class provides the base pureQuery query
implementation provided with the InfoSphere MDM Server product. This class
contains the logic necessary to conduct pureQuery JDBC-driven queries as well as
persistence transactions. Each proprietary business object (BObj) has its own
BObjQuery class that extends from this AbstractBObjQuery class. These
implementations take advantage of logic to open and close JDBC connection, and
common logic that is run during any persistent transactions, that is, they retry
logic on add transactions.
Business-specific implementations of the AbstractBObjQuery mechanism and the
classes that extend it, such as PersonBObjQuery, contain add, update and delete
methods to implement the relevant persistence logic. These classes also override
the persist method of the AbstractBObjQuery to invoke the appropriate method.
Class factory interfaces are also provided per module and as such,
implementations of this interface allow for the creation of the appropriate
implementation of the query and persistence mechanism (XYZBObjQuery).
The class diagram shows the interfaces and abstract classes discussed in this
section:

Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

Customizing an existing pluggable persistence strategy
You can extend a core business object’s persistence implementation by overriding
one or more of the add, update, or delete methods.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The factory implementation class must also be extended to pick up this new
persistence BObjQuery class implementation, and the extended factory must be
registered with the product (tcrm_extension.properties or
DLWCommon_extenions.properties).

To customize a persistence strategy by including new
columns and extension tables
1. Create a new class that extends from the base business object. For example, use
XContractBObjExt to extend TCRMContractBObj.
2. Add a constructor that accepts persistenceStrategyName and DWLCommon.
This new constructor invokes the super class’s constructor, for example:
public XContractExtBObjQuery(String persistenceStrategyName,
DWLCommon objectToPersist) {
super(persistenceStrategyName, objectToPersist);
}

3. Override the persist method. Invoke the base class implementation, if the
objectToPersist, the variable that stores the BObj, is the same base class type. If
it is not the same base class type, invoke the extended EObj class. For example:
protected void persist() throws Exception {
if (!(objectToPersist instanceof XContractBObjExt)) {
super.persist();
} else
if (persistenceStrategyName.equals(CONTRACT_ADD)) {
addXContract();
} else if (persistenceStrategyName.equals(CONTRACT_UPDATE)) {
updateXContract();
} else if (persistenceStrategyName.equals(CONTRACT_DELETE)) {
deleteXContract();
}
}

4. Modify the extended EObjExtData. The insert, update queries must have all the
base table columns along with the new extended column. Here is example of
how to assign values to the new column:
public static final String createEObjXContractExtSql = "insert into CONTRACT
(CONTRACT_ID, CURRENCY_TP_CD, ..., Agreement_Score, ...) values
(?1.contractIdPK, ?1.currencyTpCd, ...,?2.AgreementScore, ...)";
@Update(sql=createEObjXContractExtSql)
int createEObjXContractExt(EObjContract e1, EObjXContractExt e2);

Note: The example shows how values can be extracted from multiple EObjs.
The prefix qualification of the fields in the SQL indicates the object to be used.,
that is,
a. contractIdPK indicates that the value of CONTRACT_ID is assigned from
the e1 of type EObjContract and
b. agreementScore indicates that the value of agreement_score is assigned from
the e2 of type EObjXContractExt.
See
com.ibm.mdm.samples.extension.contract.entityObject.EObjXContractExtData
for implementation information
5. Extend the appropriate existing query factory class and override persistence
related create methods to retrieve your query class.
6. Register your extended query factory implementation class with the product by
modifying the appropriate properties file for the module (either
DWLCommon_extension.properties or tcrm_extension.properties).
Chapter 2. Customizing InfoSphere MDM Server

Licensed Materials – Property of IBM

7. Modify all the inquiry transactions to show the new column. See “Customizing
an existing pluggable business object query”.
You can use the initial mdmxmi file that was created for the first extended column to
add additional columns to the extension.

To extend a persistence strategy
You can modify the existing persistence strategies to accommodate writing
information to file in addition to the existing database tables, for example. The
com.ibm.mdm.samples.extension.persistence in the samples package provides an
example of this.
1. Create a class that extends the BObjQuery implementation class.
2. Add a constructor that accepts persistenceStrategyName and DWLCommon.
This new constructor invokes the super class’s constructor. For example:
public XSpecFormatExtBObjQuery(String persistenceStrategyName,
DWLCommon objectToPersist) {
super(persistenceStrategyName, objectToPersist);
}

Override the persistence method you wish to extend - either add, update or
delete, for example:
//step 1:
protected void addSpecFormat() throws Exception{
super.addSpecFormat(); //Retained logic provided by SpecFormatBOBjQuery
//step2: add your custom logic here – the line below is an example only.
persistInternalXSD();
}

3. Create a class that extends the appropriate BObjQueryFactoryImpl to pick up
the extended BObjQuery class. In this example, the
SpecModuleBObjQueryFactoryImpl is extended and the
createSpecFormatBObjPersistence method is overridden:
public Persistence createSpecFormatBObjPersistence(String persistenceStrategyName,
DWLCommon objectToPersist){
return new SpecFormatBObjQueryExt(persistenceStrategyName, objectToPersist);
}

4. Register the extended query factory implementation class with the product by
modifying the appropriate properties file for the module. For example, for the
Spec service, the factory implementation is configured in the
DWLCommon_extension.properties file. The factory implementation for TCRM
services, such as Party, Product, Financial, are configured in the
TCRM_Extension.properties, for example:
Spec.BObjPersistenceFactory =
com.ibm.mdm.samples.extension.persistence.spec.bobj.query.SpecModuleBObjQueryFactoryImplExt

The persistence mechanism is now extended.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 3. Managing specs and spec values
InfoSphere MDM Server specs, referred to simply as specs, are a type of metadata
used to define extensions to class entities within the InfoSphere MDM Server data
model. It is important to note that the term specs in this context is not a shortened
version of the word specifications.
Because a spec acts as an extension of the data model, you can use it to extend a
class entity without the need to alter the physical definition of the database schema
and without the usual need to restart the application server. An implementation
incorporating specs would include the following:
v An XSD to define the structure of data you intend to use to extend a class entity.
v An XML document adhering to the XSD structure provides the data, known as
spec values or dynamic attributes, that are used to extend the class entity.
v A business object, with an underlying class entity that supports specs, that
associates to the XML document is a spec value business object.
Some examples of business objects and their underlying entities that support specs
include:
v TCRMDemographicsSpecValueBObj (party demographics data)
v ProductSpecValueBObj (product spec values)
v ContractSpecValueBObj (contract spec values)
In this section, you will learn:
“Understanding specs and the MDM metadata project” on page 62
“Learning spec project structure” on page 63
“Understanding spec composition” on page 64
“Understanding spec profiles” on page 65
“Understanding internal spec schemas” on page 66
“Understanding external spec schemas” on page 67
“Understanding localized spec schemas” on page 68
“Learning national language support (NLS)” on page 69
“Understanding design considerations and constraints governing internal spec
schemas” on page 71
“Understanding internal schema validations” on page 77
“Deploying specs to the runtime” on page 78
“Using spec values in the runtime” on page 78
“Adding spec values” on page 79
“Updating spec values” on page 80
“Manipulating spec values” on page 81
“Using AttributeValueBObj path elements” on page 81
“Using AttributeValueBObj value elements” on page 82
“Using AttributeValueBObj action elements” on page 82
“Understanding spec value searches” on page 85
“Understanding spec design considerations for searchable attributes” on page
85
© Copyright IBM Corp. 1996, 2009

Licensed Materials – Property of IBM

“Understanding deployment considerations for spec searchable attributes” on
page 87
“Using spec searchable attributes in the runtime” on page 88
“Understanding localized searches” on page 88
“Understanding multiple criteria search semantics” on page 89
“Validating searches” on page 89
“Understanding data type specific considerations” on page 90
“Illustrating an end-to-end scenario of a spec and its usage” on page 91

Understanding specs and the MDM metadata project
The InfoSphere MDM Server Workbench provides a project type, called the MDM
metadata project, to represent a metadata package. After a metadata project is
created, different types of metadata (such as specs) can be created within it. A
metadata package represents a collection of metadata content of varying types.
When you finish creating the metadata, the enclosing metadata package can be
deployed to the InfoSphere MDM Server runtime using the InfoSphere MDM
Server Workbench. Alternatively, you can also deploy the metadata package using
the MDMENV command line deployment tool.
An optional set of locales is also associated with a metadata project. If these locales
are provided to be used with the project, they are stored in the mdm.locales file, in
the locales directory, in the project root. They provide a representation of the
locales supported by the target deployment system and are defined as
elements, specified by the InfoSphere MDM Server locale
schema. For example:

en
English

A metadata project can reference other metadata projects to adopt their locale
configuration. This process is cumulative, and the locale configuration is inherited
though a project reference hierarchy. Project references are stored within the project
file, in the project root. The references are defined as project elements as follows:

...

project1
project2
...
projectN
root

...

The project is a standard Eclipse file created by the InfoSphere MDM Server
Workbench from information supplied when a new project is created. It contains
additional information about the project, such as its name.

Using MDM specs in the metadata project
After you create a metadata project in the InfoSphere MDM Server Workbench,
you can create a spec in the project to begin working on it. As described in
“Understanding spec composition” on page 64, the core of a spec contains three

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

schemas: internal, external, and localized. When a spec is first created using the
InfoSphere MDM Server Workbench, only the internal schema is created. This
schema is to hold the dynamic data model that you want to create. Therefore this
schema must be set up correctly by you to meet your business requirements.
After you finish creating the internal schema, you can use the InfoSphere MDM
Server Workbench to generate the external schema and the localized schema. In
addition it generates a nlsTemplate.properties file that can be used as the
template of a translation properties file. See “Understanding the translation
template file” on page 70 for more information.

Learning spec project structure
For specs, the InfoSphere MDM Server Workbench creates the following project
structure. You extend this structure as required to provide updates to the spec
definitions and new spec formats.
The logical file structure consists of the following folders and files. Note that not
all these folders and files are required for any given spec definition.
folder
locales folder
mdm.locales file
specs folder
folder
.spec file
folder
.internal.xsd file
.external.xsd file
.localized.xsd file
nlsTemplate.properties file
nls folder
_.properties file

The descriptions of these folders and files are:
folder
This folder holds the metadata package. See “Understanding specs and the
MDM metadata project” on page 62 for more information.
locales folder
This folder holds the mdm.locales file.
mdm.locales file
This optional file holds the set of locales supported by the target
deployment system. See “Understanding default locales for the InfoSphere
MDM Server Workbench” on page 71 for more information.
specs folder
This folder holds the spec definitions.
folder
This folder holds a particular spec definition.
.spec file
This file holds the information about the spec profile.
folder
This folder holds the definition of a given spec format. Initially, InfoSphere
MDM Server Workbench generates a single, default spec format, 0000001.
You can create additional spec formats as required. See “Understanding the
spec format number” on page 65for more information.
Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

.internal.xsd file
The internal schema holds the dynamic data model for you business
requirements. You must implement this file.
.external.xsd file
The external schema is based on the internal schema and provides a less
restrictive definition of the spec for use at runtime under certain
configuration. This file is generated by the InfoSphere MDM Server
Workbench.
.localized.xsd file
The localized schema is based on the internal schema and provides
support for the localization of XML governed by the internal schema. This
file is generated by the InfoSphere MDM Server Workbench.
nlsTemplate.properties file
The translation template file is automatically generated by the InfoSphere
MDM Server Workbench.
folder
This folder holds an optional set of properties files which provide National
Language Support for associated schemas. See “Learning national language
support (NLS)” on page 69 for more information.
_.properties file
Zero or more properties files can be added to provide alternate translations
for the schemas.

Understanding spec composition
This section describes the various parts that make up a spec. As described in
“Learning spec project structure” on page 63, the InfoSphere MDM Server
Workbench creates several folders and files, some of which are maintained and
generated by the InfoSphere MDM Server Workbench; some of which are
maintained by the user.
A spec is composed of a profile, an internal schema, external schema, localized
schema and national language support.
v The spec profile is a collection of properties associated with a spec.
v The internal schema is an XSD that defines the structure of the information
needed to extend a class entity.
v The external schema is an XSD derived from the internal schema, but it has
certain key restrictions removed to facilitate interface requirements that are not
fulfilled by the internal schema (for example, Rules of Visibility).
v The localized schema is an XSD derived from the internal schema that contains
only those elements requiring NLS support.
v The national language support (NLS) for specs allow for both of the following:
– the translation of parts of the internal schema itself, and
– the inclusion of translated content in an XML document governed by the
internal schema

Understanding the spec format
Another important aspect of spec definition is the versioning of spec, also known
as the spec format. The definitions of specs often evolve over time depending on
business requirements. For example, additional elements may be required, or
additional allowable values may be required if an element is validated against

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

some allowable values. In these cases, care must be taken to ensure that the new
version of a spec does not break backward-compatibility with any spec values that
were created based on an older version of a spec. An example of an incompatible
spec update is adding a mandatory XML element to the XSD. This renders existing
spec values incompatible because they were created without that XML element.
The existing spec values will fail to validate against the XSD if these incompatible
changes are introduced. See “Understanding internal schema validations” on page
77 for more information.
A spec format collects together the internal, external and localized schemas, along
with associated translation properties file. Although a spec format is typically
derived from a pre-existing spec format, the old and new spec formats are
independent of each other.
In general, a spec contains one or more spec formats. This allows the development
of specs where existing schemas require modification. All potential modifications to
a spec fall into two categories; those that are compatible with the previous version
of the spec, and those that are incompatible. When making incompatible
modifications to a spec, the internal schema cannot be simply updated with the
required changes, because this would cause existing spec values to fail validation.
To provide continued support for existing spec values and allow for modifications
to the schemas, both the old and new schemas must coexist. If modifications to a
spec cause existing spec values already deployed in the InfoSphere MDM Server
runtime to become incompatible, a new version of the spec can be captured in a
new spec format. See “Understanding internal schema validations” on page 77 for
more information.

Understanding the spec format number
Within an InfoSphere MDM Server metadata project, each spec format appears as a
directory within the spec. These directories have numeric names such as 00000001,
which identify the spec format numbers. Spec format numbers are 8 digit decimal
strings padded with leading zeros and are used to uniquely identify the spec
format within the spec.
When a spec is created using the InfoSphere MDM Server Workbench, an initial
spec format 00000001 is automatically created.
A new spec format is created by duplicating an existing spec format folder. You are
responsible for allocating an appropriate spec format number and making the
corresponding modifications to the new internal schema. The new spec format
number must be one higher than the largest existing spec format number.

Understanding spec profiles
The spec profile is a collection of properties associated with a spec. It contains the
InfoSphere MDM Server spec schema, spec name, spec namespace prefix, metadata
key and optional start and end dates.
name

The name of the spec. It must match the name of the spec folder and the
internal schema.

namespace
The namespace of the spec.
metadataKey
A unique identifier of the spec made up of a simple Type-4 UUID,
Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

conveyed in its string representation as hex digits. The metadata key is
allocated when the spec is initially created and should not be changed.
When a spec is successfully deployed to the InfoSphere MDM Server
runtime, this value is stored in the METADATA_KEY column in the
CDMETADATAINFOTP table.
startDate
The date at which the spec becomes active.
endDate
The date at which the spec expires.
You can modify the start and end dates of the spec to constrain its lifetime on the
InfoSphere MDM Server runtime. Ensure that the start date is earlier than the end
date.
The spec profile is defined within a .spec file named after the spec. This file can be
modified using the Spec Model Editor in the InfoSphere MDM Server Workbench.
The structure of a sample .spec file is shown below:

[specname]
http://www.example.com/[specname]
e7577b29-f4c2-4fc0-808d-1db39e2a532f
2007-10-15T00:00:00.000+0100
2010-10-15T00:00:00.000+0100

The date is represented as a string of the form YYYY-MM-DDThh:mm:ss.S+Z, where:
YYYY

Represents the year

Represents the month

Represents the day

Represents the start of the time field

Represents the hour

Represents the minute

Represents the seconds

Represents the milliseconds expressed with 3 digits

The time zone expressed in 4 digits as offset of the GMT where the first
two digits express hours; the last two digits are the minutes. So a +1 hour
will be written 0100.

Understanding internal spec schemas
The internal schema defines the structure of the dynamic data model, which is the
extension to class entities within the InfoSphere MDM Server data model, needed
by the business requirement. The internal schema is an XSD document that is used
at runtime to validate spec values, provided as an XML document at runtime. It
also defines the sequence, the number of occurrences, and the data type of the
XML elements in the XML document.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Although the internal schema is standard XSD, a number of constraints on the
language specification must be adhered to. See “Understanding design
considerations and constraints governing internal spec schemas” on page 71 for
more information.
The default internal schema created by the wizard is shown below:

The InfoSphere MDM Server Workbench creates this internal schema automatically
with the appropriately configured content. If you create this internal schema
manually, you must configure the following aspects according to the following
specifications:
v elementFormDefault=’qualified’ must be specified.
v The targetNamespace must be configured with the spec namespace prefix and
spec name.
v The xsd and mdmspec namespace prefixes must be declared. Use of alternate
prefixes for these namespaces is prohibited.
v The spec name must be declared as a namespace prefix. Use of an alternate
prefix for this namespace is prohibited.
v A root element with the same name as the spec must be declared.
v The introduction of other XML constructs such as simpleType, complexType, and
others must conform the with spec schema constraints.
v The internal schema name must be in the form .internal.xsd.

Understanding external spec schemas
The external schema is a transformation of the internal schema that relaxes the
rules for mandatory elements. The result is a schema where all elements are
optional, even though some of these elements are otherwise defined as mandatory
in the internal schema. This allows the Rules of Visibility feature or related
concepts to be supported.
For example, when certain elements must be removed from a view of an XML
document governed by the internal schema, such as restricted query results, if
those elements are mandatory in the internal schema, the internal schema can no
longer be used for validation. In such a case, the external schema is used instead.
The InfoSphere MDM Server Workbench generates the external schema when you
build the metadata project in the InfoSphere MDM Server Workbench. If you create
the external schema manually, you must configure the following aspects according
to the following specifications:
Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

v The target namespace for the external schema is the same as the internal schema
except that the path internal is replaced by external. For example, if the
namespace for a spec named testSpec appears in the internal schema as follows:
http://www.ibm.com/mdm/data/specs/testSpec/internal/00000001

The equivalent namespace for the external schema would be:
http://www.ibm.com/mdm/data/specs/testSpec/external/00000001

v All elements within the external schema must be optional. If the internal schema
does not use the minOccurs=’0’ attribute to make an element optional, this will
be enforced in the external schema. Where a minOccurs attribute is provided,
the original value is retained within an annotation. For example, the following
complex type definition in the internal schema:

leads to the following complex type definition in the external schema:

v The external schema name must be in the form .external.xsd.

Understanding localized spec schemas
The external schema is a transformation of the internal schema that holds elements
that require national language support (NLS). Such elements must be a type that
inherits directly or indirectly from the localizedString complex type. This complex
type is defined by the InfoSphere MDM Server schema for specs, which also
contains the associated type and namespace definitions needed to create a
complete document. The localized schema allows the validation of separate XML
documents containing translated elements for instances of a spec. See “Using
InfoSphere MDM Server schema for specs” on page 75 for more information on the
localizedString complex type.
The localized schema name must be in the form .localized.xsd.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Learning national language support (NLS)
National language support for specs can be split into two categories with different
target audiences. The first type of NLS allows the translation of parts of the
internal schema itself, including the spec names, element names, and enumeration
values. The second type of NLS allows the inclusion of translated content in an
XML document governed by the internal schema.

Understanding national language support for schemas
The first type of NLS support for specs allows the translation of parts of the
internal schema. The internal, external and localized schemas provide a way to
validate associated XML documents that come from a runtime system. In addition,
they can assist with providing a user interface to display the XML content.
Whether or not to use the schemas as part of a user interface depends on the
nature of the information being exchanged. If the schema describes information
that is relatively static, it may be appropriate to build a dedicated user interface in
order to present the information. This user interface can make its own provision
for NLS support. In this case, no reference to the schema is required to support the
user interface and so translation of its content is not required.
If the information being exchanged is very dynamic and changing frequently, it
may not be possible to build a dedicated user interface. Instead, you may have to
provide a generic interface that exposes the XML content to the user, using the
XSD schema as a framework for its presentation. This generic interface extracts
information such as element names from the schema to populate the user interface.
In this case, because the schema is referenced to support the user interface, the
schema content must be translated.
NLS support for schemas consists of a set of one or more translation properties
files, one per language, that are used to provide alternative translations to the
following parts of the schema:
v Translations for the spec name
v Translations for element names
v Translations for enumeration values
Within an InfoSphere MDM Server metadata project, these files are in the nls
folder, inside each spec format folder. They are associated with the spec format
rather than the spec, as they can change between different versions of the spec.
When making a compatible change to an internal schema, the corresponding NLS
properties files can be updated directly as needed.
These properties files are named after the locale for which they contain
translations. The form of the filename is:
_.properties
__.properties

Where is the ISO 639-1 code for the locale and is the
ISO 3166-1-alpha-2 country code. For example:
exampleSpec_en.properties
exampleSpec_en_US.properties

The InfoSphere MDM Server Workbench generates a translation template file that
you can use as a basis to implement these translation properties files.
Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

For more information on ISO local and country codes, see:
v http://www.loc.gov/standards/
v http://www.iso.org/iso/country_codes/iso_3166_code_lists

Understanding the translation template file
The translation template file, nlsTemplate.properties, contains the required keys
for the translation of elements contained in the internal schema. The template is
automatically generated by the InfoSphere MDM Server Workbench and is
updated every time a change is made to the internal schema. You can use the
template as a basis for creating the properties files needed to contain the translated
content. You cannot edit the template file directly; any changes made to the
template file will be lost when the internal schema is updated.
An example of a simple template file is:
SPEC.NAME=
#SPEC.SHORT.DESC=
#SPEC.LONG.DESC=
ELEMENT.NAME.diameter=
#ELEMENT.SHORT.DESC.diameter=
#ELEMENT.LONG.DESC.diameter=

Understanding translations for spec names
Each properties file contains a mandatory translation for the spec name. Optionally,
you can also provide short and long descriptions of the spec. The SPEC property
prefix holds this information in the properties file:
SPEC.NAME=
#SPEC.SHORT.DESC=
#SPEC.LONG.DESC=

Understanding translations for element names
Each properties file contains a mandatory translation for each element within the
internal schema. Optionally, you can also provide short and long descriptions. The
ELEMENT property prefix holds this information in the properties file:
ELEMENT.NAME.=
#ELEMENT.SHORT.DESC.=
#ELEMENT.LONG.DESC.=

For example, given the following element definition:

You provide the following mandatory and optional keys in the translation
properties file:
ELEMENT.NAME.color=...
#ELEMENT.SHORT.DESC.color=...
#ELEMENT.LONG.DESC.color=...

Understanding translations for enumeration values
Each properties file contains a mandatory translation for each enumeration value
within the internal schema. Optionally, you can also provide short and long
descriptions. The ENUM.VALUE property prefix holds this information in the
properties file:

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
ENUM.VALUE..=
#ENUM.VALUE.SHORT.DESC..=
#ENUM.VALUE.LONG.DESC..=

For example, given the following simple type with enumeration values:

You provide the following mandatory and optional keys in the translation
properties file:
ENUM.VALUE.SIZE.medium=...
ENUM.VALUE.SIZE.small=...
ENUM.VALUE.SIZE.large=...
#ENUM.VALUE.SHORT.DESC.SIZE.medium=...
#ENUM.VALUE.LONG.DESC.SIZE.medium=...
#ENUM.VALUE.SHORT.DESC.SIZE.small=...
#ENUM.VALUE.LONG.DESC.SIZE.small=...
#ENUM.VALUE.SHORT.DESC.SIZE.large=...
#ENUM.VALUE.LONG.DESC.SIZE.large=...

Understanding national language support for XML documents
The second type of NLS support for specs allows the inclusion of translated
content in an XML document governed by the internal schema. In some situations,
it may be necessary for XML documents governed by an internal schema to
contain multiple values for an element, so that it can be described in more than
one language.
Rather than explicitly binding this set of values into the single XML document, a
set of additional XML documents is provided, one per language, to contain this
information. These separate XML documents are governed by a localized schema.
The localized schema is a subset of the internal schema containing only those
elements that inherit directly or indirectly from the localizedString complex type.
This complex type is defined by the InfoSphere MDM Server schema for specs,
which also contains the associated type and namespace definitions needed to create
a complete document. See “Understanding national language support for schemas”
on page 69 for more information on the localizedString complex type.

Understanding default locales for the InfoSphere MDM Server
Workbench
The configured set of locales defines the languages that translations of schemas can
be provided for. The set of locales associated with a project must match the
environment that the metadata is deployed to. You must modify the set of locales
to match the required set.

Understanding design considerations and constraints governing
internal spec schemas
The internal schema is the schema that you must implement to meet your business
requirement.

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

In addition to being compliant with normal XSD specifications, the internal schema
must adhere to a number of additional constraints. The InfoSphere MDM Server
Workbench validates the internal schema against these constraints and generates
the corresponding external and localized schemas.
v Schema document encoding—The spec schema must specify and use UTF-8
encoding. It must therefore start with the line . Other encoding that is normally allowed by the XSD
specifications are not currently supported by specs.
v Target namespace—The target namespace for the internal schema must be in the
form:
//internal/

The target namespace prefix is specified by the MDM Spec wizard. The spec
format number defines the version level of the schema. On the file system, the
name of the spec format folder where the internal schema is located, must match
the spec format number in the target namespace.
For example, when declaring a spec named MyExampleSpec, with a namespace
prefix of http://www.myCompany.com/mdm, the namespace for the first spec format
is:

In addition, an xmlns prefix for the target namespace must match be declared
and must match the name of the spec. See the last line of the schema snippet
above.
v The elementFormDefault constraint—A default namespace cannot be used
within the internal schema, and the schema must include the XSD schema
attribute elementFormDefault in the form elementFormDefault=″qualified″.
References within the internal schema must be fully-qualified using the standard
XSD : format. For example, the following element
declaration is supported:

The following element declaration is not supported:

v Allowable primitive types—Only a limited set of the primitive types made
available in the XML standard are permitted within the internal schema. They
are:
– xsd:boolean
–
–
–
–
–
–
–

xsd:long
xsd:string
xsd:datetime
xsd:decimal
xsd:date
xsd:time
mdmspec:localizedString (see “Using InfoSphere MDM Server schema for
specs” on page 75)

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

For example, is in not allowed
because it uses a non-supported primitive type.
v Type contraints—The following constraints are available for the following data
types:
– String: Minimum Length, Maximum Length, Pattern, Enumeration, Look Up
Reference, Minimum Occurrence, and Maximum Occurrence
– Boolean: Pattern, Minimum Occurrence, and Maximum Occurrence
– Long, Date, Time, DateTime: Minimum Value, Maximum Value, Pattern,
Enumeration, Look Up Reference, Minimum Occurrence, and Maximum
Occurrence
– Decimal: Total Digits, Fraction Digits, Pattern, Enumeration, Look Up
Reference, Minimum Value, Maximum Value, Minimum Occurrence, and
Maximum Occurrence
v References to other XSD schemas—Because spec schemas must not refer to
other XSD documents, any required element, simple type or complex type
definitions must appear within the spec schema that uses them.
There are two exceptions to this rule:
– The internal schema must include a namespace prefix declaration for the
InfoSphere MDM Server schema for specs. This schema, which must always
be allocated the namespace prefix mdmspec, is defined as:
http://www.ibm.com/mdm/system/specs/mdmspec/internal/00000001

– The internal schema must include a namespace prefix declaration for the XSD
schema itself. The XSD schema, which must always be allocated the
namespace prefix xsd, is defined as:
http://www.w3.org/2001/XMLSchema

Therefore, the following namespace prefix declarations must always appear
within the internal schema:
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns:mdmspec='http://www.ibm.com/mdm/system/specs/mdmspec/internal/00000001'

In addition, to allow the internal schema to make use of types such as
mdmspec:localizedString, the InfoSphere MDM Server schema for specs must be
imported as shown below. This statement should only be included if such
references are contained within the internal schema. Adding this statement
without including such references will result in a warning:

v Using global elements—All elements within the internal schema must be
defined as global elements.
Element definitions must not appear within a complex type definition. For
example, the following is not permitted:

Complex types can contain tags if they use the "ref=" attribute
instead of the "name=" attribute to refer to elements defined globally. So, the
above example can be correctly represented as follows:

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

v Identifying the root element—Because all elements are global elements, there
must be a convention to define the root element within the internal schema. For
the internal schema to be valid, it must have a global element with the same
name as the spec.
For example, a spec named MyExampleSpec would include a root element
definition as follows:

...

The type of the root element is always a complex type defined in the same
internal schema.
v Valid and invalid definitions of types—Enumerations can only be defined on
simple types. They cannot be defined anonymously on elements. Simple and
complex types must be defined explicitly, as global elements, not anonymously
within other XSD elements.
For example, the following enumeration definition is permitted:

This enumeration is not permitted:

v Permitted constructs—The following constructs are permitted within an internal
schema:
– schema
– annotation
– complexType
– simpleType
– restriction

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

–
–
–
–

sequence
element
enumeration
enumeration value

Attributes are not permitted in internal schemas.
v Elements that reference code tables—Internal schemas can contain elements
that refer to records within an InfoSphere MDM Server code table. In order to
support this, the InfoSphere MDM Server schema for specs provides two
pre-defined types, codeTableEnum and ElementInfo. See “Using InfoSphere
MDM Server schema for specs” for more information.
For example, to define an element called myCodeTableReference that refers to a
code table called MYCODETABLE, you must include the codeTableEnum and
ElementInfo types in the element definition as follows:

v Elements of the type localizedString—Internal schemas can contain elements of
type localizedString. Notice in the definition of an element of this type, the id
attribute is mandatory. The reason is that the value of this attribute is what links
the value within the internal schema with that of the localized schema. This is
especially important because:
– The element name alone is not enough to determine the translation of a
multi-occurring element.
– The runtime depends on this correspondence when performing localized
searches.
v Elements marked as searchable—Internal schemas can contain elements that are
identified as searchable by specifying a value of true for the searchable element
within an annotation.
This can be achieved in the following way:

true

Using InfoSphere MDM Server schema for specs
The InfoSphere MDM Server schema for specs defines several data types that
handle locale sensitive data and InfoSphere MDM Server code table data. If you
define a spec that requires these two types of support, you only need to import
this schema into your internal schema:

v The localizedString type is used to assist the provision of translated material
within XML documents governed by the internal schema.
v The codeTableEnum type is used to refer to a code table.
v The ElementInfo type is used within annotations defined under element name
definitions only (not references) in the schemas for the following reasons:
– To create a record in the external schema of an element’s original minOccurs
attribute value within the corresponding internal schema.
– To allow element definitions to identify an associated code table to which
they refer.
– To identify if the values associated with an element definition are to be
searchable within the runtime. Element name definitions only means that the
following usage is currently permitted:

true

However, the following usage is not permitted:

true

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Using InfoSphere MDM Server schema for locales
The InfoSphere MDM Server schema for locales provides support for introducing
translatable content into internal schemas.

Understanding internal schema validations
A spec is validated during the development process when you use the InfoSphere
MDM Server Workbench. The spec is also validated by the deployment tools and
by the InfoSphere MDM Server runtime.
The nature of validation is dependent on the environment, but key validation
criteria include:
v The hierarchical file structure of the InfoSphere MDM Server metadata project is
validated to ensure the correct structure and necessary folders are present.
v The schemas are validated against the XML schema syntax to ensure that they
are well formed.
v The internal schema is validated against the spec constraints that govern the
development of spec.
v The NLS files match the internal schema.
v The NLS files represent supported locales.

Understanding compatible and incompatible changes to spec
schemas
Incompatible changes to a spec are any kind of modification to the spec schema
that may cause validation to fail when the schema is applied to an existing XML
document on the system.
For example, raising the minimum allowable value for an XML element from 0 to 1
may cause an XML document that was already created to contain a value of 0 to
become invalid.
Examples of incompatible changes include:
v Adding a mandatory data element
Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

v Lowering the maximum allowable value
v Removing an enumeration value from a restricted type
v Changing the data type of an element
Examples of compatible changes include:
v Adding an optional data element
v Raising the maximum allowable value
v Adding an enumeration value to a restricted type
v Defining a new simple or complex data type
v Identifying an attribute as searchable

Deploying specs to the runtime
InfoSphere MDM Server provides several services to handle the maintenance and
retrieval of specs. For example, a user can use the addSpec service to deploy a spec
to the InfoSphere MDM Server runtime, provided that:
v The proper CDMETADATAPACKAGETP and CDMETADATAINFOTP records are set up.
v The three schemas are well-formed and comply with InfoSphere MDM Server
metadata specifications for specs.
v Updates to a spec is backward-compatible with previous versions.
These considerations make the maintenance of spec using InfoSphere MDM Server
services a non-trivial task.
Instead of using services, the InfoSphere MDM Server Workbench provides a set of
tools to help you to develop, deploy and maintain specs. The tools automate many
of the non-trivial tasks, such as generating the external schema and the localized
schema, validating the schemas, deploying the specs to the InfoSphere MDM
Server runtime, and maintaining versioning of the specs. Using the InfoSphere
MDM Server Workbench, you can focus on implementing the internal schema,
which is essential to meeting your business requirements.
If the specs are searchable, after deployment some additional administrative steps
must be performed to ensure that search is optimally configured to achieve
response time expectations with minimal resource usage. In the case of no native
XML support in the database, as with DB2 z/OS 8, some additional administrative
steps must be performed to ensure that search is functional. These administrative
steps are detailed in the IBM InfoSphere Master Data Management Server System
Management Guide.
For system requirements for the InfoSphere MDM Server Workbench, see the
InfoSphere MDM Server Workbench User Guide.

Using spec values in the runtime
During runtime, the InfoSphere MDM Server uses the schemas to validate the spec
values, which are received in the form of an XML document. When spec values are
added or updated, they are validated against the internal schema before they are
persisted. If the spec values fail to validate against the internal schema, an error is
returned to the runtime environment.
This section uses the following spec to demonstrate how spec values can be added
and updated in the InfoSphere MDM Server runtime. This spec defines the
dynamic data model for a pen.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Adding spec values
A request that is intended to add spec values requires the use of the
AttributeValueBObj object and CDATA section.
The following request snippet shows the spec values in an add request in a
product. The AttributeValueBObj object is wrapped in a ProductSpecValueBObj
object along with the optional ProductSpecValueNLSBObj, which provides
translations for the localized strings and complies with the localized XSD file. This
Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

internal spec value can be successfully validated against the spec (the internal
XSD) as illustrated in “Using spec values in the runtime” on page 78. Note that the
localized XSD is not provided.

...

Elégant et stylé.

]]>

...

1
Sleek and stylish.

10
100

Ballpoint

]]>

Updating spec values
A request that is intended to update spec values requires the use of one or more
AttributeValueBObj objects, and the , , and elements inside
the AttributeValueBObj object.
The following request snippet shows the spec values in an update request in a
product. The AttributeValueBObj object is wrapped in a ProductSpecValueBObj
object. The spec values can be successfully validated against the spec shown in
“Using spec values in the runtime” on page 78.

...

update
/penSpec/penDescription
Sleek, stylish and easy to write with.

update
/penSpec/penPhysicalDimensions

]]>

For this example, two updates are performed:
v the value of the penDescription spec value is changed

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v the entire penPhysicalDimensions spec value is updated
When this update is applied to the spec values added in “Adding spec values” on
page 79, the updated spec values are:

1
Sleek, stylish and easy to write with.

8
100

Ballpoint

Note: Spec values do not prevent redundant updates. Specifically, if an update
transaction results in any change to the XML document, even if it results in the
exact same XML document, that change will be persisted to the database even
though it is redundant.
For an example of an entire runtime request and response that manipulates spec
values, see the InfoSphere MDM Server Transaction Reference Guide.

Manipulating spec values
You can manipulate the spec values corresponding to a spec using the
AttributeValueBObj object associated with the business object. The
AttributeValueBObj object is made up of the following three prescribed elements:
v Action—Supports the values of add, update, replace, and remove.
v Path—A simple XPath expression that identifies the target element of the Action
element.
v Value—The value provided for the Action element.
In an add request, only one AttributeValueBObj object should be provided. If the
Path and Action elements within it are provided, they are ignored.
In an update request, zero or more AttributeValueBObj objects can be provided.
The update request operates on each of the AttributeValueBObj objects based on
the information in the Path, Value, and Action elements.
The Path, Value, and Action elements are described in detail:
v “Using AttributeValueBObj path elements”
v “Using AttributeValueBObj value elements” on page 82
v “Using AttributeValueBObj action elements” on page 82

Using AttributeValueBObj path elements
The Path element in AttributeValueBObj references an element in the XML
document. It uses an XPath expression to reference the element in the XML
document.
In the example provided in “Updating spec values” on page 80, the simple penType
element can be referenced as /penSpec/penType.
The more complex element that specifies the many dimensions of a pen can be
referenced as /penSpec/penPhysicalDimensions.
Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

If multiple pen descriptions are allowed by the spec, then a second pen description
can be referenced as /penSpec/penDescription[2].
To index the first element, the value 1 is used. Indexing with the number 0, or a
number greater than the maximum number of occurrences allowed by the internal
schema results in an error.
Lastly, all of these pen descriptions can be referenced as /penSpec/penDescription.

Using AttributeValueBObj value elements
The Value element in AttributeValueBObj represents the value that the action is to
apply to the XML document.
In the example provided in “Updating spec values” on page 80, the first update is
for the simple value:
Sleek, stylish and easy to write with.

The second update is for the complex value. A CDATA section is used so that the
special XML characters do not need to be escaped:

]]>

Using AttributeValueBObj action elements
The Action element in AttributeValueBObj tells the runtime what to do with the
XML document.
The allowable values for the Action element are: add, update, replace, and remove.

Understanding the add action for the AttributeValueBObj element
The add action adds elements to the XML document under the element specified
by the Path element. If the elements are multi-occurring, they are appended at the
end of the list of existing child elements.
v Action—The String add.
v Path—Mandatory. This is a reference to an existing element that can have one or
more child elements.
v Value—Mandatory. This specifies either a simple value (i.e. no XML) or complex
value (i.e. XML fragment), whose root element corresponds to the element
identified by the Path element.
v Example—Assuming multiple occurrences of the pen description are allowed by
the spec, the following add action:

add
/penSpec/penDescription
Comfortable grip.

changes the XML document shown in “Adding spec values” on page 79 to:

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

1
Sleek and stylish.
Comfortable grip.

10
100

Ballpoint

Notice that the added element appears after the existing pen description.

Understanding the update action for the AttributeValueBObj
element
The update action updates elements in the XML document under the element
specified by the Path element. If a simple value is supplied in the Value element,
the old value under the element is replaced entirely with that value. If a complex
value in the form of an XML fragment is supplied, the XML fragment is merged
with the existing XML document. If there are new child elements provided, they
are added to the document as a result of the merge.
v Action—The String update.
v Path—Mandatory. This is a reference to an existing element.
v Value—Mandatory. This specifies either a simple value (i.e. no XML) or complex
value (i.e. XML fragment), whose root element corresponds to the element
identified by the Path element.
v Example—The following update action, which includes an update of a simple
value and a complex value:

update
/penSpec/penDescription
Sleek, stylish and easy to write with.

update
/penSpec/penPhysicalDimensions

8
]]>

changes the XML document shown in “Adding spec values” on page 79 to:

1
Sleek, stylish and easy to write with.

8
100

Ballpoint

Notice that the length element remains as 100, illustrating that the update
resulted in a merge with the original XML document.

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

Understanding the replace action for the AttributeValueBObj
element
The replace action replaces an existing XML fragment in the XML document with
the provided complex value. No merge occurs in the replace action, which may
result in the removal of child elements.
v Action—The String replace.
v Path—Mandatory. This is a reference to an existing element.
v Value—Mandatory. The value provided will be used to replace the existing
value.
v Example—The following replace action:

replace
/penSpec/penPhysicalDimensions

]]>

changes the XML document shown in “Adding spec values” on page 79 to:

1
Sleek and stylish.

Ballpoint

Notice that the diameter element is removed from the XML document. If the
diameter element is a mandatory element, validation would fail.

Understanding the remove action for the AttributeValueBObj
element
The remove action removes the elements indicated by the Path element. If multiple
elements are referenced by the Path element, all those elements are removed. You
can use an index to reference a specific element for removal. For example, if
multiple pen descriptions are allowed in the example spec, you can use
/penSpec/penDescription[2] to refer to the second pen description.
v Action—The String remove.
v Path—Mandatory. This is a reference to an existing element. It cannot be a
reference to the root element of the XML document.
v Value—Not applicable. If this element is provided, it is ignored.
v Example—The following remove action:

remove
/penSpec/penDescription

changes the XML document shown in “Adding spec values” on page 79 to:

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
1

10
100

Ballpoint

Understanding spec value searches
For supported entities with a searchable spec use, attributes that have been marked
as searchable on the spec definition can be searched upon within the runtime.
In the context of a search service, this soft criteria is identified using a simple
XPath expression, in addition to 0 or more values depending on the operator
chosen. This section discusses considerations that need to be made when marking
attributes as searchable, what must be done when deploying these searchable
attributes to the runtime, and how search is used in the runtime.

Understanding spec design considerations for searchable attributes
The supported InfoSphere MDM Server databases vary significantly in their ability
to facilitate querying XML documents, spec values, ranging from no native XML
support on DB2 z/OS 8, to full native support on Oracle 11g, DB2 V9.7 and DB2
V9.5 on Linux Unix and Windows, and DB2 z/OS 9.
As a result, there are two solutions that support searching spec values across all
platforms: one that takes advantage of the native XML capabilities of the
underlying database, and the other that maintains a simple index internal to the
application to facilitate search.
The following must be taken into consideration before taking advantage of the
spec search feature:
v Determine if you want to, and can, support case-insensitive searches and set the
configuration item accordingly.
v Determine if you can afford to have the runtime dynamically derive the effective
dates of spec values matched on search. Out of the box, these values are not
maintained when dependent entities are updated (i.e., entity spec use). The
alternative is to have a regularly scheduled batch process run at off-peak hours
to update the spec value effective dates. This behavior is configurable through
the /IBM/DWLCommonServices/SpecValueSearch/Recursive/enabled configuration
point and is disabled by default.
v Searching against localized spec values requires that the IDs of an internal spec
correlate with a localized spec. This is described in detail in “Understanding
localized spec schemas” on page 68.
v On DB2® z/OS® V8, limitations are imposed on the indexable values. For
example, xsd:string or mdmspec:localizedString values that exceed 255 will
have a truncated index value, and xsd:long values that have too many digits
can not be indexed at all due to the constraints of the underlying relational data
type in the index table required for this platform.
v The database operating system, version and type must be correctly specified
(according to your environment) using the following configuration items:
– /IBM/DWLCommonServices/DataBase/OS
– /IBM/DWLCommonServices/DataBase/type
– /IBM/DWLCommonServices/DataBase/version

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

v The spec values must conform to the structure defined in the spec, otherwise the
spec value search will not work. As a result, the external validation ‘Variable
Type Data Validation’, described in Chapter 35, “Validating data,” on page 475,
must be enabled in the runtime.
v Time and date related XML schema types are considered UTC if no timezone
was declared.
v DB2 z/OS v9 does not have support for casting to xs:date, xs:time, or
xs:dateTime, the DB2 Version 9.1 for z/OS Date and Time Data Types. Because
of this, the comparisons for these data types will be string based. The string
comparison may not give the correct result for time and date or Time data with
time zone components. For example, here are how two times could be ordered
incorrectly: 13:20:00-04:00, 13:21:00-05:00 (9:20, 8:21). For the same reason, the
two dateTimes could be also be ordered incorrectly. Maintaining a consistent
time zone across all spec values and searches may suffice. For more information,
you can search the DB2 Version 9.1 for z/OS information center for ″Casts
between XML schema data types″.
Following the ‘PenSpec’ example introduced in the section “Using spec values in
the runtime” on page 78, if we wished to make the penDescription searchable, we
would simply add a searchable annotation to the element of the active spec format.
So the original penDescription element

would be modified as follows

true

After updating this compatible change to the runtime, the penDescription can be
searched upon using the searchProductInstance service. It should also be noted
that even though the searchability of a spec is defined on the active spec format,
spec values that correspond to older spec formats can also be matched on.
When a spec is reused between multiple entities, it is expected that only a subset
of the entities will require searchability. To ensure that spec value indexes are not
redundantly maintained and that consuming applications of InfoSphere MDM
Server understand that spec values of the other entities are not intended for search,
a flag on the spec use is provided. If a spec is reused, requires searchability from
both entities, but the searchability requirements vary, the creation of 2 independent
specs should be strongly considered.
It is the active internal schema that dictates which attributes are searchable. Thus,
if a data type has changed on a searchable attribute in an incompatible way (i.e.,
from xsd:string to xsd:int), then all corresponding values should be migrated to
comply to the new spec because of the data comparison requirements of this query.
Also, care must be taken when choosing searchable attributes as there are indexing
considerations depending on the database configured with InfoSphere MDM
Server.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

For databases that have native XML support, Oracle 11g, DB2 V9.7 and DB2 V9.5
on Linux Unix and Windows, and DB2 z/OS 9, the following must be considered
when indexing:
v Search performance can be influenced by the structure of your spec. Guidelines
for creating indexes over XML data and how to use the indexes effectively can
be found by searching for the following items on the developerWorks® site,
http://www.ibm.com/developerworks/:
– ″Best Practice Managing XML Data″
– ″Exploit XML indexes for XML Query performance in DB2 9″
v Some platforms only support the indexing of a subset of data types. Refer to
each database’s technical documentation for specifics describing what is
supported. Here are a few suggestions:
– DB2 v9.5 Data Types associated with index XML pattern expressions. See the
DB2 v9.5 information center for details.
– DB2 v9.5 Create Index Statement. See the DB2 v9.5 information center for
details.
– DB2 Version 9.1 for z/OS Data types associated with pattern expressions. See
the DB2 v9.1 for z/OS information center for details.
v Index support may be limited for case-insensitive searches. Some platforms don’t
support function-based XML indexes. As a result, case-insensitive searches can
have corresponding indices because they depend on fn:contains and
fn:upper-case. Case-insensitive searching can be disabled using the following
configuration item: /IBM/Product/SpecValueSearch/CaseSensitive/enabled, and
wildcard searches can be disabled by filtering out the contains type code to
disallow its use.
v Case-insensitive searching can be disabled using the following configuration
item: /IBM/Product/SpecValueSearch/CaseSensitive/enabled.
v Where fn:upper-case indices are supported, case-insensitive search still may not
perform at the levels required. In this case, it may be preferable to maintain an
upper-cased version of the attribute on the spec value. For example, if there is a
string attribute named description on the spec that you would like to support
case-insensitive search, you could do the following:
– create an attribute called description_upper on the spec
– mark both description and description_upper as searchable on the spec
– add a behavior extension that will derive the description_upper attribute any
time it changes – for example, extend addProductSpecValue,
updateProductSpecValue, so that any value for description that is passed in,
for example, Stylish, a corresponding upper-cased version is stored in
description_upper: STYLISH.
– add a behavior extension that converts description search criteria into
description_upper criteria.

Understanding deployment considerations for spec searchable
attributes
Use the deploy tool described in the IBM InfoSphere Master Data Management Server
Workbench Users Guide, Deploying metadata spec components to an InfoSphere
MDM Server runtime system.

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

Using spec searchable attributes in the runtime
Following the example in “Using spec values in the runtime” on page 78, you can
search for all products that have a pen description of Sleek and stylish by providing
the following:
v the specId for the spec containing the attribute you want to search on.
v the path to the attribute you want to search upon. This is a simple XPath
expression which corresponds to the internal XSD.
v the code type for the operation you want to perform.
v the value to be used in the search.
A sample request for this type of search is as follows:

searchProductInstance
ProductSearchBObj

/penSpec/penDescription
1

1
Sleek and stylish

For consumers dynamically forming a search request, it is expected that they will
construct the request using spec XSD files previously retrieved from InfoSphere
MDM Server. Specifically, the path will be derived from the path to the searchable
attribute within the schema corresponding to the active spec format, and the
operators and allowable values, where they are required, are derived from the data
type of the searchable attribute. For more information on allowable values, see
“Validating searches” on page 89. It should also be noted that for all platforms, the
indexes are automatically kept up-to-date because the spec values change within
the runtime and always reflect the data within the spec values, unless otherwise
noted.

Understanding localized searches
If localized content is to be searched, the path corresponding to the internal XSD,
not to the localized XSD, must be used.
For example, a localized search request for the French equivalent of Sleek and stylish
would be as follows:
200
...

searchProductInstance
ProductSearchBObj

/penSpec/penDescription
1

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Elégant et raffiné

Understanding multiple criteria search semantics
In accord with our existing search semantics, all criteria provided for the same
attribute, or path, are ORed with each other and all different attributes, or paths,
and their corresponding criteria can be thought of as ANDed with each other.
The following request, assuming penType is also identified as searchable, can be
interpreted as a search for all fountain pens with descriptions of stylish or chic:

searchProductInstance
ProductSearchBObj

/penSpec/penDescription
1

1
stylish

1
chic

/penSpec/penType
1

1
Fountain

Validating searches
When a search is performed against spec values, there are a number of validations
performed by the runtime against the provided criteria.
If any of these validations fail, the transaction fails with an aggregate of the errors
found, where possible. These validations include:
SpecValueSearchBObj
v Allowable number of SpecValueSearchBObjs can not be exceeded. The
maximum number of these objects allowed is defined by the
/IBM/Product/SpecValueSearch/MaxSpecValueSearchBObjs configuration
item and defaulted to 5. Note that this limit is in place because of the
performance implications of the resulting query as the number of
SpecValueSearchBObjs increase.

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

v The path must correspond to the searchable attribute. For example, if
/penSpec/penId were passed in as the path, an error would result
because penId is not identified as searchable within the spec definition.
v The path does not contain namespace prefixes. For example, if
/penSpec1:penSpec/penSpec1:penDescription were passed in as the
path, an error results.
v Both path and specId are mandatory. If the optional
SpecValueSearchBObj is provided in a search transaction, the values for
the path and specId attributes must be provided.
v The path and specId cannot be repeated. That is, the same path and
specId can not appear in multiple SpecValueSearchBObjs provided
within the same search transaction.
v SpecValueSearchCriteriaBObj is mandatory. At least one
SpecValueSearchCriteriaBObj object must be provided with every
SpecValueSearchBObj.
SpecValueSearchCriteriaBObj
v The allowable number of SpecValueSearchCriteriaBObj must not
exceeded. The maximum number of these objects is defined by the
/IBM/Product/SpecValueSearch/MaxSpecValueSearchCriteriaBObjs
configuration item and is defaulted to 20.
v An operator is mandatory and must correspond to the supported type.
All supported operators are defined within the CDXMLCOMPOPTP
table and can be further customized as described in the chapter
Chapter 13, “Customizing search SQL queries,” on page 169.
v The number of values corresponds to the operator. For example, the
between operator requires exactly 2 values, whereas equals requires
exactly 1.
v The values correspond to the given operator. For example, an operator
of less than cannot be used on a data type of xsd:boolean.
v Values must correspond to the XML schema data type. For example,
assuming that length were identified as searchable, if the provided value
for a search on /penSpec/penPhysicalDimensions/length does not
correspond to xsd:decimal as defined in the internal XSD, an error
results.
v Search criteria must not exceed configured length restrictions. Length
restrictions are identified by the following configuration items with their
default values indicated in brackets:
/IBM/DWLCommonServices/SpecValueSearch/MaxLongTotalDigitsSize
(19)
/IBM/DWLCommonServices/SpecValueSearch/
MaxDecimalTotalDigitsSize (31)
/IBM/DWLCommonServices/SpecValueSearch/
MaxDecimalFractionDigitsSize (19)
/IBM/DWLCommonServices/SpecValueSearch/MaxStringValueSize (255)

Understanding data type specific considerations
v Date/Time/DateTime:—The usage of time zones is assumed to be consistent
between the stored spec values and the searches performed upon them. For
example, if time zones are not specified in the spec values, then they should not
be stored in the spec values. Similarly, if they are specified in the spec values,

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

then the timezone should be specified within the search criteria. In all cases, if a
time related spec value attribute is missing a time zone, it is assumed to be
Universal Time Clock (UTC).
v String:—Whether the search is case sensitive or not is configurable.

Understanding database specific considerations
For databases that have native XML support, Oracle 11g, DB2 V9.7 and DB2 V9.5
on Linux Unix and Windows, and DB2 z/OS 9:
v The values of the configured search criteria length restrictions can be made
much larger than the default values because in many cases there are fewer
restrictions on the size of these data types for databases that have good support
for SQL and XML and native XML support.
v Search is typically constrained by the level of indexing support that the
underlying database provides. Examples of such limitations include searches that
are case-insensitive and limitations to supported data types. Please refer to
“Understanding design considerations and constraints governing internal spec
schemas” on page 71 for further details.
For databases with no native XML support, DB2 z/OS 8:
v Transactions that result in the manipulation of the spec value will update the
index table or tables within the same transaction. In the example above, this
corresponds to the PRODUCTVALINDEX and PRODUCTVALNLSINDEX tables.
This can be disabled using the following configuration item (i.e., in the case of
initial load): /IBM/DWLCommonServices/SpecValueSearch/IndexTable/
MaintainValues/enabled.
v The values of the configured search criteria length restrictions mentioned above
should correspond to the underlying data type lengths within the database. For
example, /IBM/DWLCommonServices/SpecValueSearch/MaxStringValueSize should
be set to 255 to correspond with the length of the STRING_VALUE column in
the PRODUCTVALINDEX table. The default configuration corresponds to the
default data type lengths of the index table.
– Strings are truncated to the value defined by the /IBM/DWLCommonServices/
SpecValueSearch/MaxStringValueSize configuration item when indexed.
– If a string of a spec value exceeds this constraint, then a truncated version is
stored in the index table, and for all other values, a warning is logged and the
index is not stored.
– If the maximum string value size configuration item /IBM/DWLCommonServices/
SpecValueSearch/MaxStringValueSize is changed, then the indexes must be
rebuilt.

Illustrating an end-to-end scenario of a spec and its usage
This topic illustrates the process involved in designing and creating the spec,
deploying it to the InfoSphere MDM Server runtime, and using it with a business
entity, using a ProductSpecValueBObj. Note that the principles illustrated here are
applicable for other spec value business objects, such as ContractSpecValueBObj.
This process is illustrated using a business requirement to add a rental deposit box
to a service product. The goal is to create a dynamic data model associated with a
service product. The following examples illustrate the requirements and the roles
involved.
See also:
Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

“Example: Identifying the required spec attributes in simple business terms”
“Example: Creating a spec using the InfoSphere MDM Server Workbench” on
page 93
“Example: Deploying the metadata package for a spec to the InfoSphere MDM
Server runtime” on page 94
“Example: Associating a spec with a product” on page 95
“Example: Adding a product with values corresponding to a new spec” on
page 96
“Example: Searching for a product with specific spec values” on page 98

Example: Identifying the required spec attributes in simple
business terms
The first step of designing a spec is to capture the business requirements in simple
business terms.
Based on the business requirements for a rental deposit box, you must identify the
following attributes:
v Box size
v Box dimension
v Replacement fee for lost key
v Annual rental fee
You must also identify that the rental deposit box should be available for market
on Jan. 02, 2007.
After you have defined the attributes for the spec in simple business terms,
provide the details of the attributes, taking data types and constraints into
consideration.
Based on the business requirements, the attribute details should be the following:
Box size
Look Up Ref=CDPURPOSETP
Min Occurrence = 0
Box dimension
Simple Type / String
Maximum Value=30
Minimum Occurrence = 0
Replacement fee for lost key
Derived Type / Amount Derived Type
Minimum Occurrence = 0
Annual rental fee
Derived Type / Amount Derived Type
Minimum Occurrence = 0
Amount Derived Type
Simple Type / Decimal

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Min Inclusive Value=0.0
Max Inclusive Value=10,000,000.00
Fraction Digits=2

Example: Creating a spec using the InfoSphere MDM Server
Workbench
After defining the details of the attributes, you can use the InfoSphere MDM
Server Workbench to create the schema to implement the spec.
1. In the InfoSphere MDM Server Workbench, select the MDM Metadata Project
wizard to create a new metadata project. Name the project MySpecMetadata.
A locales folder and a specs folder are created.
2. Select the MDM Spec wizard to create a spec in the metadata project. Name the
spec RentalDepositBox.
A RentalDepositBox folder is created under the specs folder. The initial spec
format ID 00000001 is created as a folder under the RentalDepositBox folder.
The initial internal schema, RentalDepositBox.internal.xsd, is opened in an
XSD editor in the workspace. The source view of the internal schema looks like
the following:

3. Edit the internal schema to implement the spec according to the attribute
details you define in “Example: Identifying the required spec attributes in
simple business terms” on page 92.
The final internal schema looks like the following:

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

4. Open the spec profile, RentalDepositBox.spec, and specify the start date of Jan.
02, 2007 for this spec.
Note that a metadata key is generated in the profile.
5. Build the MySpecMetadata project in the workspace.
After the project is built successfully, the external schema,
RentalDepositBox.external.xsd, and the translation template file,
nlsTemplate.properties, are created.
At this point, the design of the spec is completed.
Note: No localized schema is generated for this example because the internal
schema does not use the localizedString data type.

Example: Deploying the metadata package for a spec to the
InfoSphere MDM Server runtime
After the design of the spec is completed, you must deploy the spec to an
InfoSphere MDM Server runtime so that it can be used by other business entities.
1. In the InfoSphere MDM Server Workbench, export the MySpecMetadata project
and select Export MDM metadata to an MDM Server to deploy the spec to the
runtime. You must provide the InfoSphere MDM Server connection information
in order for the InfoSphere MDM Server Workbench to connect to the runtime.
During deployment, the InfoSphere MDM Server Workbench sends a number
of MDM services to deploy the spec, including:
v addCodeType services to add the project name MySpecMetadata to the
CDMETADATAPACKAGETP table; and the metadata key in the spec profile
to the CDMETADATAINFOTP table.
v addSpec service to add the spec and spec format to the SPEC and
SPECFORMAT table.
When the spec is successfully deployed, the following messages are displayed
in the Console in your workspace:
Info:
Info:
Info:
Info:
Info:

Connecting to MDM Server..
MDM Server connection successful
Started deploying metadata package MySpecMetadata.
Metadata package MySpecMetadata deployed successfully.
Validation of spec RentalDepositBox from metadata package MySpecMetadata is successful.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Info: The spec RentalDepositBox from metadata package MySpecMetadata will be deployed now.
Info: The spec RentalDepositBox from metadata package MySpecMetadata deployed successfully.
Info: Deploying metadata package MySpecMetadata finished. 1 specs deployed, 0 specs updated,
0 specs deleted and 0 specs failed.

2. Optionally, you can run the getSpecByName service, using the spec name
RentalDepositBox and the spec namespace from the spec profile, to verify that
the spec is deployed successfully.

getSpecByName

RentalDepositBox
http://www.myCompany.com/mdm
0
ALL
ALL

The deployed spec is returned in the response as follows:

getSpecByName

SUCCESS

4098
516122047189304657
RentalDepositBox
http://www.myCompany.com/mdm
1220471890687
78095571-d1d3-4210-945e-c18db14c0b3e
1220471888625
MySpecMetadata
860122047189323435
2007-01-02 00:00:00.000
2008-09-03 15:58:13.25
cusadmin
690122047189089076

Note that the deployment captures some of the metadata project properties as
follows:
v —the metadata project name
v >—the metadata key in the spec profile
v >—the name of the spec
v >—the start date of the spec

Example: Associating a spec with a product
After the spec is deployed, you must make this spec available for use with the
intended business entity. In the Party Domain, the
TCRMDemographicsSpecValueBObj object (party demographic data) can use the
spec directly. In the Product Domain and Account Domain, most entities must have
an ENTITYSPECUSE association with the spec before the spec can be used.
This step assumes you are using the spec in the Product Domain.
Based on the default service product type, execute an addEntitySpecUse service to
create the example rental deposit box spec:

addEntitySpecUse
EntitySpecUseBObj

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

PRODUCTTYPE
5
516122047189304657
1
Govern product common attribute values
2
Not cascaded to descendents
Y
1220471888625
78095571-d1d3-4210-945e-c18db14c0b3e
2007-08-01
2017-08-01

When the association is added successfully, the response is returned as follows:

addEntitySpecUse

SUCCESS

984122047514862573
PRODUCTTYPE
5
516122047189304657
1
Govern product common attribute values
2
Not cascaded to descendents
Y
1220471890687
78095571-d1d3-4210-945e-c18db14c0b3e
PRODUCT
2007-08-01 00:00:00.0
2017-08-01 00:00:00.0
305122047501575094
cusadmin
2008-09-03 16:52:28.625

Example: Adding a product with values corresponding to a
new spec
After a spec is successfully associated for use with a business entity, you can create
instances of a business entity and provide spec values that confirm to the spec.
When you took the steps “Example: Associating a spec with a product” on page
95, you associated the rental deposit box spec for use with a service product type.
You can now create a product based on the service product type and specify spec
values for the rental deposit box.
To create the product, execute the addProductInstance service as follows:

addProductInstance
ServiceProductBObj

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

5
Medium Deposit Box
1
Standalone

860122047189323435

2015-01-01

1
4x6
200.00
120.00

]]>

When the product instance is successfully added, the response, including the spec
values for the deposit box, is returned as follows:

addProductInstance

SUCCESS

4129
872122047803262505
5
Medium Deposit Box
1
Standalone
2008-09-03 17:40:32.625
cusadmin
141220477975406109
2008-09-03 17:40:33.468

4117
897122047803279637
516122047189304657
860122047189323435
872122047803262505
2008-09-03 17:39:35.406
2015-01-01 00:00:00.0
2008-09-03 17:40:32.796
cusadmin
141220477975406109

Chapter 3. Managing specs and spec values

Licensed Materials – Property of IBM

Note: The spec values in the response are enclosed in tags, and the < and
> characters in the XML are escaped with the < and > entities.

Example: Searching for a product with specific spec values
This set of product values that you added when you learned how “Example:
Adding a product with values corresponding to a new spec” on page 96 can now
be searched for and matched on a spec value search.
To a search for all products with an annual rental fee <= $120, use the following:

searchProductInstance
ProductSearchBObj

/RentalDepositBox/AnnualRentalFee
516122047189304657

3
120.00

Running this search returns at least the newly added item in the response.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 4. Understanding InfoSphere MDM Server common
code type framework
The common code type framework provides consistent and easy use of code table
functions.
The InfoSphere MDM Server common code type framework includes two different
sets of APIs:
v admin code type service APIs are designed to provide administrators with the
ability to store code table data directly to database and to inquire code table data
directly from database.
v operational code type service APIs, provide the operational service consumers the
ability to inquire code table data, which uses the data caching mechanism.
Code types are divided into three different categories based on how they are used
in InfoSphere MDM Server:
v Category 1 (C1)—Represents the restricted design-time code types. InfoSphere
MDM Server design and runtime are based on the existence of a pre-populated
and fixed set of records on these code types. Category 1 code types are
considered fixed system code types. Some examples of these code types are:
CdAcessorKey, CdAccessorTp, CdAttributeTp, and CdErrTypeTp.
v Category 2 (C2)—Represents the general design-time code types. The default
InfoSphere MDM Server setup is based on the existence of a pre-populated set
of records on these code types. Category 2 code types are considered non-fixed
system code types. You can add your own code types which will be used by
your software components. Some examples of these code types are:
CdOperatorTp, CdBusinessTxTp, and CdSuspectTp.
v Category 3 (C3)—Represents the domain operational code types. You can modify
these code types at your discretion. There is no hard coded logic in InfoSphere
MDM Server that relies on a specific record in these code types. Some examples
of these code types are: CdHierarchyTp, CdHoldingTp, CdRelTp, and
CdContractRelTp.
These two set of code type service APIs share some common characteristics, and
they also have some differences.

Licensed Materials – Property of IBM
Table 2. Common and differing characteristics for admin and operational code type APIs.
Characteristics that are common to both
code type service APIs:

Characteristics that differ for both code
type service APIs:

v Both admin and operational code type
services support inquiring on all C2 and
C3 code types and return corresponding
code type business objects.

v Only admin code type service APIs
support persistence transactions
addAdminCodeType and
updateAdminCodeType, which apply to
C2 and C3 code types. No persistent
transactions are available for operational
code type service APIs.

v Both admin and operational code type
services support web services – all admin
code type transactions and operational
code type transactions are web service
supported.

v Admin code type service APIs support
inquiring on all C1, C2, and C3 code
types. Operational code type service APIs
only support inquiring C2 and C3 code
types.
v Only admin code type service APIs
support point-in-time (PIT) transactions.
Operational code type service APIs do not
support PIT transactions.
v Admin code type service APIs directly
access code type tables and do not use the
cache mechanism. Operational code type
services APIs use the cache mechanism.
v Admin code type service APIs do not
support the fallback feature. Operational
code type service APIs do support the
fallback feature.

The following are admin code type service APIs; refer to the IBM InfoSphere Master
Data Management Server Transaction Reference Guide for details on using them:
v
v
v
v
v
v
v
v

addAdminCodeType
updateAdminCodeType
getAdminCodeType
getAllAdminCodeTypes
getAllAdminCodeTypesByLangId
getAllAdminCodeTypesByLocale
getCodeTypeMetadata
getAllCodeTypeMetadata

The following are operational code type service APIs:
v getOperationalCodeType
v getAllOperationalCodeTypes
v getAllOperationalCodeTypesByLangId
v getAllOperationalCodeTypesByLocale
v reloadAllOperationalCodeTypes
Additionally, the framework offers the following APIs, defined in
CodeTypeComponentHelper, to validate the integrity of the code, to validate the
value of a referenced code type entry in the context of other entities, or both:
v isCodeValid
v getCodeTypeByCode
v getCodeTypeByValue

100

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v isCodeValuePairValid

Migrating to InfoSphere MDM Server common code type
framework
In order to simplify the process of migrating to the common code type framework
when you are using custom implementations for your code tables, begin by
implementing them based on the InfoSphere MDM Server common code type
framework – as outlined above.
“Understanding Code type additions and extensions”
“Understanding assets generated by the workbench when adding or extending
code types”
“Understanding Web services enablement for code types” on page 102
“InfoSphere MDM Server code type categories” on page 103

Understanding Code type additions and extensions
Code type additions differ from most InfoSphere MDM Server additions. When
working with code type additions, you are not required to create controller and
component classes, nor are you required to create the corresponding persistent or
inquiry services. Instead, code type additions are able to use the existing admin
and operational code type APIs, but you must still create the corresponding Java
classes and metadata information.
For more information on InfoSphere MDM Server extensions and additions, see
Chapter 2, “Customizing InfoSphere MDM Server,” on page 17.
Code type addition and extension are supported in both admin code type APIs
and operational code type APIs in Common Code Type Framework.
InfoSphere MDM Server workbench can create the necessary Java classes and
property file changes, including the metadata SQL statements and XSD changes,
for the new code type additions or code type extensions. See the IBM InfoSphere
Master Data Management Server Workbench User Guide for instructions on how to
create code type additions and extensions.

Understanding assets generated by the workbench when adding or
extending code types
InfoSphere MDM Server workbench can create the necessary Java classes and
property file changes, including the metadata SQLs and XSD changes, when you
create new code type additions or you modify existing code type extensions. See
the IBM InfoSphere Master Data Management Server Workbench User Guide for specific
instructions on how to create new code type additions or modify existing code
type extensions.
The following sections provide you with some additional details on the assets
generated by the workbench when adding or extending code types.

Understanding the process for adding new code types
When the InfoSphere MDM Server workbench generates a new asset for a new
code type, it categorizes the code table as a C3 code type by default, which is
Chapter 4. Understanding InfoSphere MDM Server common code type framework

101

Licensed Materials – Property of IBM

reflected in the Java class TypeMetadataBObj. Say, for example, you
are creating a new code table cdSampleTp using workbench. The following
resources will be generated:
v SampleTypeBObj.java – the new code type BObj class.
v SampleTypeMetadataBObj.java – defines the code type category code and all
table column names for the new code type, each column’s nullable
characteristics, as well as foreign key table names of the code type if there are
any.
v SampleTypeBObj = com.customerCompany.common.codetype.obj is generated. You
must manually append it to the tcrm_extension.properties file.
v SampleTypeBObj = com. customerCompany.common.codetype.obj is generated. You
must manually append it to the DWLAdminService_extension.properties file.
v codetype.metadata.cdsampletp.classname = com.
customerCompany.common.codetype.obj.SampleTypeMetadataBObj is generated.
You must manually append it to the codetable.properties file.
v Generated XSD files – Workbench will generate the new code type (e.g.
CdSampleTp) related XSD element definitions, which you must manually add to
DWLAdminRequest_extension.xsd, DWLAdminResponse_extension.xsd, and
tcrmResponse_extension.xsd using an XSD editor.
v Generated metadata SQL statements for SampleTypeBObj. These SQL statements
must be manually executed on the application database server to register the
newly created code type objects with InfoSphere MDM Server.

Understanding the process for changing existing code types
Creating extension of an existing code type business object is very similar to
creating extension of a regular business object, because all InfoSphere MDM Server
code types are implemented as business objects in the InfoSphere MDM Server
Common code type framework. The following list is a summary of the code type
extension variations compared to the standard extension mechanism.
v Properties files – Similarly to the process for adding a new code type, all the
required definitions in the properties files for the extended code type must be
manually added to the corresponding properties file.
v XSD definitions – Workbench will generate the XSD definition for the extended
code type, which you must then manually incorporate in the following files:
– DWLAdminRequest_extension.xsd, containing the request object definition for
the extended code type business object.
– DWLAdminResponse_extension.xsd and tcrmResponse_extension.xsd,
containing the response object definition for the extended code type business
object.
v Generated metadata SQL statements – Similarly to the process for adding a new
code type, these generated SQL statements must be manually executed on the
application database server to register the newly created code type objects with
InfoSphere MDM Server.

Understanding Web services enablement for code types
Web services for code type framework is available for all InfoSphere MDM Server
code types, including any that are added or extended.
In order to enable web services for a custom code type, follow the general
guidelines in Chapter 29, “Using and configuring Web Services,” on page 323.

102

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The InfoSphere MDM Server common code type framework uses a generic data
converter, BaseCodeTypeBObjConverter, which is a template class that encapsulates
conversion logic for the code type’s business objects to and from their transfer
objects. The concrete converter class for any new code type can extend
BaseCodeTypeBObjConverter. If you want to reuse a web services implementation
in an existing framework, you can create your own converter by extending the
BaseCodeTypeBObjConverter (which is shipped with the code type framework)
and implement the method init() to call as many method addMapEntry() as the
number of attributes in the code type object.
“Example: Extending the BaseCodeTypeBObjConverter”

Example: Extending the BaseCodeTypeBObjConverter
public class SampleTypeBObjConverter extends BaseCodeTypeBObjconverter {
public SampleTypeBObjConverter () {
init();
}
// addMapEntry(String transferObjectXPath, String businessObjectXPath,
// Class transferObjectDataType, int transferObjectType)
protected void init() {
addMapEntry("TypeCode/Code/_value", "tp_cd/name", TypeCode.class,
PRIMARY_KEY_CODE_TYPE);
addMapEntry("Language/Code/_value", "lang_tp_cd/lang_tp_value", LanguageType.class,
CODE_TYPE);
addMapEntry("Description", "description", String.class, STRING_TYPE);
...
}
...
}

InfoSphere MDM Server code type categories
The following tables shows the major C1, C2 and C3 code types in InfoSphere
MDM Server. An updated list of code tables can be obtained by invoking the
getAllCodeTypeMetadata service.
Table 3. C1 code types
Code type names

Category type

CDACCESSORKEYTP

CDACCESSORTP

CDASSERTRULETP

CDATTRIBUTETP

CDCARDINALITYTP

CDCOMPOPTP

CDCONSTRAINTTP

CDCONDITIONTP

CDDATAACTIONTP

CDDWLCOLUMNTP

CDDWLPRODUCTTP

CDDWLTABLETP

CDELEMENTTP

CDERRTYPETP

CDFAILACTIONTP

CDINQLVLQUERYTP

CDOPERANDTP

CDPERMISSIONTP

Chapter 4. Understanding InfoSphere MDM Server common code type framework

103

Licensed Materials – Property of IBM
Table 3. C1 code types (continued)
Code type names

Category type

CDSTNDOPERANDTP

CDSTNDOPERATORTP

CDSUSPECTSOURCETP

CDSPECCASCADETP

PARAM_TYPE

Table 4. C2 code types
Code type name

Category type

CDBUSINESSTXTP

CDCONDITIONVALTP

CDEVENTCAT

CDEVENTDEFTP

CDINTERNALTXNTP

CDMETADATAINFOTP

CDMETADATAPACKAGETP

CDNODETP

CDOPERATORTP

CDPROTOCOLTP

CDREPOSITORYTP

CDRESOLUTIONTP

CDSUSPECTTP

CDTASKLAUNCHACTIONTP

CDTXPARAMTP

CDXMLCOMPOPTP

COMPONENTTYPE

Table 5. C3 code types
Code type name

104

Category type

CDACCETOCOMPTP

CDACCOUNTREQUIREDTP

CDACCOUNTTP

CDACTIONADJREASTP

CDADDRUSAGETP

CDADMINFLDNMTP

CDADMINSYSTP

CDAGEVERDOCTP

CDAGREEMENTSTTP

CDAGREEMENTTP

CDALERTCAT

CDALERTSEVTP

CDALERTTP

CDARRANGEMENTTP

CDAVAILABILITYTP

CDBILLINGSTTP

CDBILLTP

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Table 5. C3 code types (continued)
Code type name

Category type

CDBUYSELLAGREETP

CDCAMPAIGNTP

CDCDCREJREASONTP

CDCDCSTTP

CDCHARGECARDTP

CDCLAIMROLETP

CDCLAIMSTATUSTP

CDCLAIMTP

CDCLIENTIMPTP

CDCLIENTPOTENTP

CDCLIENTSTTP

CDCOMPLCATTP

CDCOMPLDOCTP

CDCOMPLIANCETP

CDCOMPLTARGETTP

CDCONDITIONATTRIBUTETP

CDCONDITIONOWNERTP

CDCONDITIONUSAGETP

CDCONTMETHCAT

CDCONTMETHTP

CDCONTRACTRELSTTP

CDCONTRACTRELTP

CDCONTRACTROLETP

CDCONTRACTSTTP

CDCONTRCOMPTP

CDCOUNTRYTP

CDCURRENCYTP

CDDATADEPTHTP

CDDEMOGRAPHICSTP

CDDOMAINTP

CDDOMAINVALUETP

CDENDREASONTP

CDENUMANSWERCATTP

CDENUMANSWERTP

CDERRMESSAGETP

CDERRSEVERITYTP

CDEVALUATIONCONTEXTTP

CDEVALUATIONSTATUSTP

CDFREQMODETP

CDGENERATIONTP

CDGROUPINGCATTP

CDGROUPINGTP

CDHIERARCHYCATTP

CDHIERARCHYTP

CDHIGHESTEDUTP

Chapter 4. Understanding InfoSphere MDM Server common code type framework

105

Licensed Materials – Property of IBM
Table 5. C3 code types (continued)

106

Code type name

Category type

CDHOLDINGTP

CDIDSTATUSTP

CDIDTP

CDINACTREASONTP

CDINCOMESRCTP

CDINDUSTRYTP

CDINTERACTIONCAT

CDINTERACTIONTP

CDINTERACTPTTP

CDINTERACTRESPTP

CDINTERACTSTTP

CDINTERACTRELTP

CDLANGTP

CDLASTUSEDPURPOSETP

CDLINKREASONTP

CDLOBRELTP

CDLOBTP

CDMARITALSTTP

CDMATCHENGINETP

CDMATCHRELEVTP

CDMETHODSTATUSTP

CDMISCVALUEATTRTP

CDMISCVALUECAT

CDMISCVALUETP

CDNAMEUSAGETP

CDNODEDESIGTP

CDORGNAMETP

CDORGTP

CDORIGINATIONTP

CDPAYMENTMETHODTP

CDPPREFSEGTP

CDPPREFTP

CDPREFIXNAMETP

CDPRIMARYTARGETMARKETTP

CDPRIORITYCATTP

CDPRIORITYTP

CDPRODCONTRACTRELTP

CDPRODRELATIONTP

CDPRODRELTP

CDPRODSTRUCTURETP

CDPRODTP

CDPRODUCTIDENTIFIERTP

CDPURPOSETP

CDPPREFACTIONTP

CDPPREFCAT

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Table 5. C3 code types (continued)
Code type name

Category type

CDPPREFREASONTP

CDPRODUCTSTATUSTP

CDPROVSTATETP

CDQUESTIONCATTP

CDQUESTIONNAIRETP

CDQUESTIONTP

CDRELASSIGNTP

CDRELTP

CDRESIDENCETP

CDROLECATTP

CDROLETP

CDRPTINGFREQTP

CDRULEUSAGETP

CDSERVICELEVELTP

CDSHAREDISTTP

CDSOURCEIDENTTP

CDSPECUSETP

CDSTANDARDIZATIONSRCTP

CDSTANDARDIZATIONSTATUSTP

CDSTATUSREASONTP

CDSTEWARDSHIPSTATUSTP

CDSUSPECTREASONTP

CDSUSPECTSTATUSTP

CDTASKACTIONTP

CDTASKCATTP

CDTASKSTATUSTP

CDTAXPOSITIONTP

CDTERMINATIONREASONTP

CDUNDELREASONTP

CDUSERROLETP

CDVALFREQTP

Chapter 4. Understanding InfoSphere MDM Server common code type framework

107

Licensed Materials – Property of IBM

108

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 5. Understanding InfoSphere MDM Server common
features
InfoSphere MDM Server has a collection of common features. The common
features are generic in nature and support generic entity types that are associated
with them. Common features use EntityName and InstancePK to identify
associated entities. The following features are the common features:
v Access Date value
v Alert
v
v
v
v
v
v

Campaign
Content reference
Default source value
Entity role
Entity spec use
Event manager

v Grouping
v Hierarchy
v
v
v
v
v

Line of business
Macro role
Miscellaneous value
Party compliance
Party critical data change

v
v
v
v
v

Privacy preferences
Questionnaire
Task management
Terms and condition
Interactions

There are two main ways in which the combination of EntityName and InstancePK
are used by the common features:
v Many of the common features validate an entity’s existence based on the
supplied EntityName and InstancePK combination before they associate the
entity with them.
v Many of the common features use the supplied EntityName and InstancePK
combination to load the business objects of the associated entity, and then return
the business object.
In previous releases, InfoSphere MDM Server used
EntityNameInstancePK.properties and Ext_EntityNameInstancePK.properties to
store the information related to validate an entity existence or load an entity.
InfoSphere MDM Server now uses the updated Transaction and Object Metadata
stored in the database.
In this section, you will learn:
“Adding or extending a data entity” on page 110
“Populating additional metadata for entries made in
Ext_EntityNameInstancePK.properties” on page 111
© Copyright IBM Corp. 1996, 2009

109

Licensed Materials – Property of IBM

“Understanding the external validators that support additional metadata” on
page 111

Adding or extending a data entity
To use extended or newly defined business objects with common features,
additional metadata needs to be populated.
If you used InfoSphere MDM Server Workbench to add or extend data, then the
Workbench adds required additional metadata. Otherwise, you need to add the
metadata manually.
See also:
“Example: To add or extend a data entity”

Example: To add or extend a data entity
If the Reminder business object is created as outlined in the following table, you
must also follow steps below to populate additional metadata:
Table 6. Information for creating a reminder business object
COLUMN NAME

TABLE NAME

COLUMN VALUE

EXPLANATION

GROUP_NAME

V_GROUP

TCRMReminderBObj

A new entry to be added
to V_GROUP table for
business object

NAME

CDINTERNALTXTP

getReminder

Transaction which takes
Primary Key and returns
Business Object

ReminderComponent

An entry for the new
component added

COMPONENT_TYPE_VALUE COMPONENTTYPE

1. Populate the ALIAS_NAME column in the V_GROUP table by setting the
REMINDER value as the ALIAS_NAME for the entry which has a
GROUP_NAME with a value of TCRMReminderBObj. In the case of data
extensions, the parent business object’s ALIAS_NAME should be reused while
setting the ALIAS_NAME for the extended entity.
2. Ensure that an entry is made in the V_ELEMENTATTRIBUTE table for the
Primary Key of Reminder business object.
3. Ensure com.ibm.mdm.reminder.component.ReminderComponent is the
COMPONENT_CLASS value for the COMPONENTTYPE table entry which has
ReminderComponent as the COMPON_TYPE_VALUE.
4. Ensure the entry for getReminder in CDINTERNALTXNTP has a
COMPONENT_TYPE_ID referencing
COMPONENTTYPE.COMPONENT_TYPE_ID, which has
COMPON_TYPE_VALUE of ReminderComponent.
These are the sample SQL statements generated by the Workbench for the scenario
described above:
INSERT INTO V_GROUP ( APPLICATION, GROUP_NAME, OBJECT_NAME, LAST_UPDATE_DT, CODE_TYPE_IND,ALIAS_NAME ) VALUES
( 'TCRM', 'Reminder', 'com.dwl.tcrm.samples.addition.component',' TCRMReminderBObj', CURRENT TIMESTAMP, 'N','REMINDER' );
insert into GROUPTXMAP (ENTITY_TX_MAP_ID, GROUP_NAME,BUSINESS_TX_TP_CD,APPLICATION, LAST_UPDATE_TX_ID,LAST_UPDATE_USER,LAST_UPDATE_DT) VALUES
(10001,'Reminder',100000004,'TCRM',null,CURRENT_TIMESTAMP);
insert into COMPONENTTYPE( COMPONENT_TYPE_ID,DWL_PROD_TP_CD,COMPON_TYPE_VALUE,COMPON_LONG_DESC,LAST_UPDATE_DT,COMPONENT_CLASS)

110

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

VALUES (100001,1,'TCRMReminderComponent',null,CURRENT_TIMESTAMP,'com.dwl.tcrm.samples.addition.TCRMReminderComponent');
insert into CDINTERNALTXNTP(INTERNAL_BUS_TX_TP,NAME,DESCRIPTION,EXPIRY_DT,LAST_UPDATE_DT,COMPONENT_TYPE_ID ) VALUES
(1000001,'getReminderByReminderId',null,null,CURRENT_TIMESTAMP,100001);
insert into BUSINTERNALTXN VALUES(BUS_INTERN_TXN_ID,BUSINESS_TX_TP_CD,INTERNAL_BUS_TX_TP,INT_TX_LOG_IND,LAST_UPDATE_DT) VALUES
(100000001,100000004,1000001,'Y',CURRENT_TIMESTAMP);

Populating additional metadata for entries made in
Ext_EntityNameInstancePK.properties
InfoSphere MDM Server provides a utility to populate additional metadata for the
entries added in Ext_EntityNameInstancePK.properties.

Running the EntityNameInstancePKMigration script
The entityNameInstancePKMigration utility is a J2SE utility and you can run from
the command line. The execution script runMigrationUtility.sh is located in the
/utils/entityNameInstancePKMigration/scripts directory.
You can customize the script to suit your environment.
A Readme.txt file is also provided in the /utils/
entityNameInstancePKMigration/scripts directory with instructions for this utility.

Executing generated SQL statements in your environment
Running the runMigrationUtility.sh script results in an SQL file generated with
the name in the format generated_updateMetaData_XXXXX.sql. This SQL file is in
the same directory where you ran the script You must run the SQL commands
mentioned in the generated SQL file manually against the database to populate
additional metadata.
A sample properties file called Ext_EntityNameInstancePK.properties and a
generated SQL file called generated_updateMetaData_1236345780819.sql are
available in the /utils/entityNameInstancePKMigration/
samples directory for your reference.

Understanding the external validators that support additional metadata
InfoSphere MDM Server includes external validation rules to make additional
metadata fields mandatory for Add type transactions.
These external validators affect the following elements:
Table 7. Elements affected by external validators
Group name

Element name

DWLVGroup

AliasName

AdminEObjCdInternalTxnTp

component_type_id

DWLInternalTxn

ComponentTypeId

AdminEObjComponentType

component_class

InternalTransactionTypeBObj

component_type_id

ComponentTypeBObj

component_class

Chapter 5. Understanding InfoSphere MDM Server common features

111

Licensed Materials – Property of IBM

You can turn off these validators and pass null values for the mentioned elements;
however, these additional metadata elements must be populated for the new or
extended business objects which will be used by common features.
See also:
“To turn on an external validator”

To turn on an external validator
Run the following DB2 scripts to enable the external validators related to Common
EntityName/InstancePK.
update
update
update
update
update
update
update
update

112

V_ELEMENT_VAL
V_ELEMENT_VAL
V_ELEMENT_VAL
V_ELEMENT_VAL
V_ELEMENT_VAL
V_ELEMENT_VAL
V_ELEMENT_VAL
V_ELEMENT_VAL

set
set
set
set
set
set
set
set

EXPIRY_DT=null
EXPIRY_DT=null
EXPIRY_DT=null
EXPIRY_DT=null
EXPIRY_DT=null
EXPIRY_DT=null
EXPIRY_DT=null
EXPIRY_DT=null

InfoSphere MDM Server v9.0: Developers Guide

last_update_dt=CURRENT_TIMESTAMP
last_update_dt=CURRENT_TIMESTAMP
last_update_dt=CURRENT_TIMESTAMP
last_update_dt=CURRENT_TIMESTAMP
last_update_dt=CURRENT_TIMESTAMP
last_update_dt=CURRENT_TIMESTAMP
last_update_dt=CURRENT_TIMESTAMP
last_update_dt=CURRENT_TIMESTAMP

where
where
where
where
where
where
where
where

VALIDATION_CODE=38308
VALIDATION_CODE=38309
VALIDATION_CODE=38310
VALIDATION_CODE=38311
VALIDATION_CODE=38312
VALIDATION_CODE=38313
VALIDATION_CODE=38314
VALIDATION_CODE=38315

;
;
;
;
;
;
;
;

Licensed Materials – Property of IBM

Chapter 6. Configuring Multi-Instance Federated Deployment
The multi-instance federated deployment framework provides services for inquiry
and search transactions to communicate across multiple geographically-distributed
InfoSphere MDM Server instances.
The multi-instance federated deployment model contains complete application
instances from a data-model and services perspective. Each application instance
contains a subset of data that is based on a particular criteria, such as LOB or
country. An example of this deployment model would be three party domain
application instances, one located in Switzerland, one in France (a cluster node)
and another in the UK:
v Users in Switzerland can view Swiss, French and UK data.
v Users in the UK and France can view UK and French data, but are not allowed
to see Swiss data for legal reasons.

The federated deployment framework uses metadata to describe the physical
topology of federated deployment. Metadata consists of federated profiles that
contain a collection of federated instances, each with groups of instance attributes.
The multi-instance federated deployment feature provides federation at the
services layer. This means that when the federated party search is performed
across all the instances in the profile, each individual instance executes party
search service. Each party search service includes all the business behavior
configured on the service, such as Rules of visibility, behavior and data extensions,
and so on.
In this section, you will learn:
© Copyright IBM Corp. 1996, 2009

113

Licensed Materials – Property of IBM

“Understanding federated deployment metadata configurations”
“Understanding federated transaction behaviors” on page 115
“Customizing the federated deployment framework” on page 117

Understanding federated deployment metadata configurations
Each federated instance has its own copy of the metadata that is created or
updated by Administration Services transactions. Metadata should be kept
synchronized between instances of a federated profile.

A federated instance definition contains the following information:
v Logical name of the instance
v Type of communication protocol to be used to communicate with the instance
v Fully-qualified Java name of the adapter class that is used to issue the remote
transaction request, using the specified communication protocol
v Indication if it is a local instance
v List of instance attributes describing the communication protocol details, such as
port number and host name
The Federated Deployment framework provides an RMI adapter to enable RMI
communication between instances. The RMI adapter requires mandatory host and
port instance attributes and an optional prefix attribute for the WebLogic
application server.
The following table contains examples of instance attributes for the RMI protocol.
Table 8. Examples of instance attributes for the RMI protocol
Name

Value

host

hostname.acmi.com

port

9811

prefix

corbaloc:iiop: (default)

Each federated instance definition has a list of Users or Groups or both that are
permitted to access the federated instance. The Federated Deployment framework
will not send a transaction to the federated instance if the User sending the
transaction does not have access rights to that instance.
A federated profile definition contains the following information:

114

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Logical name of the profile
v List of federated instances contained in the profile

Understanding federated transaction behaviors
There are three transactions supported with the Federated Deployment framework.
They are:
v searchPartyFederated
v getPartyFederated
v getPartyWithContractsFederated
The multi-instance federated deployment framework can be configured to support
additional services for inquiry and search transactions to communicate across
multiple geographically-distributed InfoSphere MDM Server instances. See
“Customizing the federated deployment framework” on page 117 for more details.
Using the example of a multi-instance federated deployment with one instance
located in Switzerland, one in France (a cluster node) and another in the UK that
was discussed in Chapter 6, “Configuring Multi-Instance Federated Deployment,”
on page 113, consider a scenario in which two different users both issue a
searchPartyFederated transaction on the local instance UK with the intent to search
parties in federated profile A.
v The first user, SwissGuest, has access to the UK, Switzerland and France
instances in profile A. When SwissGuest issues a searchPartyFederated
transaction on the local UK instance, the result is that a local searchParty
transactions is issued to the local UK instance and remote searchParty
transactions are sent to the Switzerland and France instances.
v The second user, FrenchGuest, has access only to the UK and France instances.
Consequently, when FrenchGuest issues a searchPartyFederated transaction on
the local UK instance, the result is that a local searchParty transactions is issued
to the local UK instance, but a remote searchParty transaction is sent only to the
France instance. The Switzerland instance is not searched.
The transaction is considered to be successful if a search result is returned from at
least one federated instance.

Chapter 6. Configuring Multi-Instance Federated Deployment

115

Licensed Materials – Property of IBM

The federated get transactions take an additional input parameter for the federated
instance name. The federated instance name is used to send transactions to a
specific federated instance. Consider a scenario in which the user SwissGuest
issues a getPartyFederated transaction on instance UK with the intent to query
party from instance Switzerland. Since SwissGuest has access to instance
Switzerland, the remote getParty transaction is issued to the federated instance
Switzerland.
The Federated Deployment framework has logic that enables it to paginate across
combined records in all instances in a federated profile. The federated pagination
algorithm uses and values in the federated
request to determine which federated instances contain records in the requested
range.
If the pagination parameters and are provided
in the federated transaction request, the response contains the following:
v element in to describe the total number
of available records across the entire federated profile
v element under each
to describe number of available records
under that particular instance.
See also:
“Sample: searchPartyFederated response messages”

Sample: searchPartyFederated response messages
The following is an example of the searchPartyFederated response message. The
Response contains , which includes multiple
elements, one for each federated instance in
the profile.

SUCCESS

116

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
4
5
true
8

searchPartyFederated

SUCCESS

UK
4

...

Switzerland
4

...

France
0

10003
Server Communication Error
READERR
100
200003
0

Customizing the federated deployment framework
Federated transactions have special federated proxies that convert the federated
transaction names (such as getPartyFederated) to actual transaction names (such as
getParty) and then send the transactions to the Federator module.
The Federator module retrieves federated profile or instance metadata, checks user
access rights, and sends transaction requests to the appropriate federated instance.

Chapter 6. Configuring Multi-Instance Federated Deployment

117

Licensed Materials – Property of IBM

The Federated Deployment framework provides the RMIProtocolAdapter class to
enable RMI communication between instances. In order to support other
communication protocols, new protocol adapters can be written and configured in
Federated Deployment metadata.

All protocol adapters must implement the ProtocolAdapter interface. The
sendRequest() method takes DWLTransaction as the input parameter and returns
DWLFederatedInstanceResultBObj. RMIProtocolAdapter sends transaction requests
to remote instances using the standard MDM request XML format
(parser=TCRMService). The response is returned from remote instance in the same
format that you specify in the Constructor context property in the federated
transaction request. RMIProtocolAdapter uses
XMLFederatedResponseConstructorHelper to extract the response object from the
remote transaction response and places it in the finalResponse field of the
DWLCommon object returned as part of DWLFederatedInstanceResultBObj. The
standard MDM Server response constructor, XMLResponseConstructor, retrieves
the formatted response message from the finalResponse field and adds it to the
federated transaction response message unmodified.
If you write custom message constructors and you want to use the Federated
Response framework, you need to write a custom constructor helper class. The
helper class must implement the FederatedResponseConstructorHelper interface
and be configured in the DWLCommon_extension.properties file using
Constructor.tcrm.FederatedDeployment.[constructor] as a key.
For example
Constructor.tcrm.FederatedDeployment.TCRMService=
com.ibm.mdm.common.federated.deployment.XMLFederatedResponseConstructorHelper

118

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 7. Subtyping entities
The entity subtyping feature provides a mechanism for redirecting service calls to
appropriately process business objects having an inheritance relationship.
This feature can be implemented only with new subtype entity additions, not with
subtype entities that are currently a part of the InfoSphere MDM Server product.
This section provides an overview of how to effectively configure and write new
entities to enable the processing of their subtypes.
In this section, you will learn:
“Knowing when to use entity subtypes”
“Knowing when to use data extensions”
“Creating entity subtypes” on page 120
“Supporting subtyped entities in database tables” on page 122
“Configuring entity subtypes” on page 122
“Understanding transactions that service subtypes” on page 124
“Processing child objects” on page 124
“Understanding inquiry transactions” on page 125
“Understanding persistence transactions” on page 126

Knowing when to use entity subtypes
Entity subtypes are useful when the business meaning of an entity changes due to
the addition of another set of attributes.
When this happens, a new set of services and business logic must be provided to
uniquely process the core set of attributes along with the new ones. Business keys,
validations and rules of visibility, for example, would be configured uniquely for a
business object that is a subtype of another. Again, entities that exist as part of an
InfoSphere MDM Server domain cannot participate in this feature.

Knowing when to use data extensions
Data extensions are extensions to existing entities.
They are useful when the existing services for a business object are sufficient to
process the additional attributes that are being added to an entity. That is, no new
business logic, unique business key configurations, validations or rules of visibility,
for example, are needed to meet the requirement of processing the business object.
Note: For information about how to create data extensions, see Chapter 2,
“Customizing InfoSphere MDM Server,” on page 17.

119

Licensed Materials – Property of IBM

Creating entity subtypes
Entity subtypes are created through the introduction of new data structures in the
database to store the groupings of additional attributes required by each subtype.

Party

Living Thing

Human

Non-Living Thing

Pet

Male

With the introduction of each new subtype, new granular services (such as add,
update and get) may be created for it. The existing parent services for each of these
corresponding services will be able to process the entity subtypes by sensing and
redirecting the service call to the appropriate implementation for that entity type.
For features such as Transaction Logging or TAIL, invoking a parent method and
processing a subtype will be logged as a service call having been made to the
subtype itself.
For example: addLivingThing(Pet myPet) would be logged as having executed
addPet(Pet my Pet).
Configurations for business keys, rules of visibility and validations are unique for
each subtype. Failing to provide these configurations will not result in any default
to the configuration of a supertype of the entity.
A business object that participates in an entity subtype hierarchy may only be
extended to be further subtyped if it results in the creation of a leaf node for the
new subtype. For example, Living Thing may be subtyped further to create a
subtype/sibling type to Human (i.e., Pet), but no new supertype to Living Thing
may be introduced.

120

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The following diagram depicts a further subtype Male.

See also:
“To create an extension subtype to a leaf entity of a subtype hierarchy” on page
122

Chapter 7. Subtyping entities

121

Licensed Materials – Property of IBM

To create an extension subtype to a leaf entity of a subtype
hierarchy
1. Follow the data addition guidelines to define the new subtype as a data
addition entity.
2. 2. Make the new type component extend from its supertype component.
3. 3. Follow the same development and configuration guideline in this chapter to
enable the type hierarchy support for the new entity.

Supporting subtyped entities in database tables
There may be only one root type in the type hierarchy. This root type must have a
column specified to track the group_name (see v_group.group_name), or entity
type for the data being persisted with those attributes. This information must be
persisted during the addition of the entity and is critical when it comes to
resolving the entity type during an inquiry transaction when only a primary key,
for example, is provided.

Configuring entity subtypes
An entity and any of its services that are intended to participate in the type
sensing and redirection of processing of this feature must be configured in the
V_GROUP, CDBUSINESSTXTP, and CDINTERNALTXTP database tables in the
system. The metadata supporting the detection and redirection of a service is
cached.
The parent_grp_name column in the V_GROUP table has been introduced to
indicate the supertype of a business object. Every business object participating in
an entity subtype hierarchy must be configured to indicate the parent type. There
may be only one root type in the type hierarchy.
Note: The root type database table must also have a column specified to track the
group_name, or entity type for the data being persisted with those attributes. This
information is critical when it comes to resolving the entity type during an inquiry
transaction when only a primary key, for example, is provided.

122

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

For example, the entries for the above conceptualized business objects might be:
Table 9. V_GROUP
group_name

application

object_name

Party

TCRM

com.newdomain.component.
PartyBObj

parent_grp_name

NonLivingThing

TCRM

com.newdomain.component.
NonLivingThingBObj

Party

LivingThing

TCRM

com.newdomain.component.
LivingThingBObj

Party

Human

TCRM

com.newdomain.component.
HumanBObj

LivingThing

Pet

TCRM

com. newdomain.component.
PetBObj

LivingThing

Male

TCRM

com.extension.component.
MaleBObj

Human

Additionally, every service where the entity should be recognized in order to
redirect its processing should be configured to indicate the appropriate parent type.
Again, there may be only one root transaction in each transaction hierarchy. The
transaction hierarchies for external (cdbusinesstxntp) and internal (cdinternaltxntp)
transactions, should be nearly the same or identical.
For example, the entries a set of services for the above conceptualized business
objects might be:
Table 10. CDBUSINESSTXTP
business_tx_tp_cd

name

dwl_prod_tp_cd

1000000

addParty

parent_business_tx_tp_cd

1000001

addLivingThing

1000002

addNonLivingThing

1000000

1000003

addHuman

1000001

1000004

addPet

1000001

9000001

addMale

1000003

1000005

updateParty

1000006

updateLivingThing

1000007

updateNonLivingThing

1000005

1000008

updateHuman

1000006

1000000

1000005

updatePet

1000006

9000002

updateMale

1000008

1000009

getParty

1000010

getLivingThing

1000009

1000011

getNonLivingThing

1000009

1000012

getHuman

1000010

1000013

getPet

1000010

9000003

getMale

1000012

Table 11. CDINTERNALTXTP
internal_bus_tx_tp

name

component_type_id

2000000

addParty

parent_internal_bus_tx_tp

2000001

addLivingThing

2000000

2000002

addNonLivingThing

2000000

2000003

addHuman

2000001

2000004

addPet

2000001

8000001

addMale

2000003

Chapter 7. Subtyping entities

123

Licensed Materials – Property of IBM
Table 11. CDINTERNALTXTP (continued)
internal_bus_tx_tp

name

component_type_id

parent_internal_bus_tx_tp

2000005

updateParty

2000006

updateLivingThing

2000007

updateNonLivingThing

2000005

2000008

updateHuman

2000006

2000009

updatePet

2000007

8000002

updateMale

2000008

2000010

getParty

2000011

getLivingThing

2000010

2000012

getNonLivingThing

2000010

2000013

getHuman

2000011

2000014

getPet

2000011

8000003

getMale

2000013

2000004

The value for component_type_id indicates the business component upon which
the transaction or service resides. For example:
Table 12. componenttype
component_type_id

dwl_prod_tp_cd

compon_type_value

Component_class

PartyComponent

com.newdomain.component.
PartyComponent

LivingThingComponent

com.newdomain.component.
LivingThingComponent

NonLivingThingComponent

com.newdomain.component.
NonLivingThingComponent

HumanComponent

com.newdomain.component.
HumanComponent

PetComponent

com.newdomain.component.
PetComponent

MaleComponent

com.newdomain.component.
MaleComponent

Understanding transactions that service subtypes
Transactions servicing subtyped entities do so by identifying that a business object
is a subtype and then redirecting the type to the more specific transaction for that
identified entity by using the prescribed metadata in the tables just described. The
identification of a subtype or a transaction that services subtyped entities occurs
prior to any pre-processing at either the controller or component level, or both.
The redirection of the service call takes place as part of the executeTx()
implementation at both the controller and component level. That is, subtypes may
be detected during a call to either a service on the controller or component.
Note: As a rule, overloading transaction and services is not a recommended
practice when creating new transactions.

Processing child objects
The Party may also have a number of Addresses associated with it, so the
PartyBObj may also contain one or more PartyAddressBObj, for example. It may be
desirable to customize the logic around the storage and/or retrieval of these child
objects.

124

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

An approach to override the implementation/retrieval of these business objects has
been provided in the getChildFormethods. There are two
steps to implement this approach:
Step 1: In parent type component, make the child object retrieval or persist logic
pluggable by defining it in a separate protected method. For example in
PartyComponent:
Example:
public DWLResponse handleGetParty(String thePartyId, DWLControl control)
throws Exception {
......
//retrieve party object partyBObj
getChildForPartyBObj(partyBObj,control);
......

//prepare response and return

}
protected void getChildForPartyBObj(PartyBObj partyBObj, DWLControl control)
throws DWLBaseException{
Vector vecPartyIdentification = (Vector)
((this.getAllIdentifiers(partyBObj.getPartyId(), control)).getData());
if (vecPartyIdentification!=null && vecPartyIdentification.size()>0){
for (int i=0; iSUSPECT and
MATCHRESULT, where is the name of the
entity domain. For example, PRODUCT. For a Data Model of the Product domain,
see Chapter 67, “Managing product suspects and product data stewardship,” on
page 763.
The entity suspect match result detail description is in an XML format and can
vary between different match engines. The specs of the match engines are to be
configured within the InfoSphere MDM Server spec framework. InfoSphere MDM
Server provides a default spec as shown below for any match engine which does
not have its own spec:

Chapter 8. Understanding entity suspects management and entity data stewardship frameworks

137

Licensed Materials – Property of IBM

Understanding notifications for entity suspect persistence transactions
Notification messages containing data relevant to the persistence transactions of
the entity suspects will be generated if the feature is enabled. Three types of
notification are defined for entity suspects during transactions: add, update, and
delete. Refer to Chapter 38 “Configuring and implementing notifications” for
configuration details. Notification messages are constructed in a generic
EntitySuspectNotification component, as shown in the class diagram below, based
on the type of the entity suspect persistence services.
The notification message is in XML format generated by the getXML() method,
which constructs the message header using getNotificationHeaderXML(), and the
message body using getNotificationBodyXML().
See also:
“Example: Notification for an entity suspect persistence transaction”

Example: Notification for an entity suspect persistence
transaction

138

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Understanding the entity data stewardship data model
The framework assumes that an entity link table is used to store the history of
entity duplicate resolution actions, such as collapsing and splitting. This link table
has none domain specific field name in the expectation that only table name will
be different based on domain entity. However each implementation can have
additional columns. See the data model diagram below using the Product domain
as an example.
See also:
“Example: Data stewardship data model class diagram”

Example: Data stewardship data model class diagram

Understanding data stewardship base classes for EObj and BObj
The object diagram below shows the entity link generic base classes for data
stewardship EObj and BObj, and as an example, the product domain specific
implementation classes:

Chapter 8. Understanding entity suspects management and entity data stewardship frameworks

139

Licensed Materials – Property of IBM

The common EObj is based on the data model assumption that all of the defined
fields are common across different entities. Any specific domain entity can
introduce its own fields as required. EObjInactiveProdLink only has table name
difference and no specific field. For example:
@Table (name="INACTIVEPRODLINK")

The common BObj is also based on the data model assumption that all of the
defined fields are common across different entities. Any specific domain entity can
introduce its own fields as required. ProductLinkBObj has no specific fields.

Learning data stewardship BObjQuery, QueryFactory, and
ResultSetProcessor classes
Following the InfoSphere MDM Server query framework, all query classes extend
GenericBObjQuery.
However, the EntityLinkBObjQuery interface is introduced for this framework to
hold all the constants. Specific domain implementation is at domain query class
level, as in the ProductLinkBObjQuery class in the example below. Query factory
implementation is domain specific. The following diagrams show the BObjQuery
and QueryFactory and the Product domain implementation classes as examples.
See also:
“Example: Data stewardship BObjQuery, QueryFactory, and ResultProcessor
class diagrams”

Example: Data stewardship BObjQuery, QueryFactory, and
ResultProcessor class diagrams

The entity link resultset processor for entity data stewardship management is
implemented in domain specific project only. It extends directly the
GenericResultSetProcessor as shown in the following diagram of the Product
domain:

140

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Note: All pureQuery classes for suspect data are implemented in domain specific
way.

Understanding EntityDataStewardComponent input and output objects
The following table summarizes the input and output objects of the component
level implemented in the EntityDataStewardComponent. These methods are
invoked by the controller level transactions.
Table 16. EntityDataStewardComponent input and output objects
Method Name

Input

Output

collapseMultipleEntities

ConsolidatedEntityBObj

splitEntity

SplitEntityRequestBObj

EntityListBObj

getLinkedEntities

LinkedEntitiesRequestBObj

MultipleEntityLinksBObj

All the base classes listed above provide common attributes for entity data
stewardship. Domain specific implementation should extend these classes. The
following diagrams below show the Product domain implementing classes as
examples.
See also:
“Example: ConsolidatedEntityBObj containing an option target entity object and
one or more entity objects to be collapsed” on page 142
“Example: SplitEntityRequestBObj containing an entity id and an entity request
object - ProductId and ProductRequestBObj” on page 142
“Example: EntityListBObj containing a list of domain specific entities” on page
143
“Example: LinkedEntitiesRequestBObj containing an entity id and an entity
request object - ProductId and ProductRequestBObj” on page 143

Chapter 8. Understanding entity suspects management and entity data stewardship frameworks

141

Licensed Materials – Property of IBM

Example: ConsolidatedEntityBObj containing an option target
entity object and one or more entity objects to be collapsed

Example: SplitEntityRequestBObj containing an entity id and
an entity request object - ProductId and ProductRequestBObj

142

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Example: EntityListBObj containing a list of domain specific
entities

Example: LinkedEntitiesRequestBObj containing an entity id
and an entity request object - ProductId and
ProductRequestBObj

Chapter 8. Understanding entity suspects management and entity data stewardship frameworks

143

Licensed Materials – Property of IBM

Understanding entity data stewardship business component level
methods
The component level methods provide generic functionalities of the entity data
stewardship transactions. Domain specific entity must have their own components
to handle additional requirements. The diagram below shows the implementation
component of the Product domain.

Understanding entity data stewardship controllers
All entity data stewardship transactions are to be defined in the domain specific
controllers, for example, ProductTxnBean and ProductFinderImpl of the Product
domain. The names of the transaction should indicate the entity type. The
controller level transaction should invoke its corresponding component level
method.
As an example, the transaction collapseMultipleProducts in controller
ProductTxnBean invokes the method collapseMultipleEntities in
ProductDataStewardCompoment.

Understanding soft delete
A default implementation for data stewardship is to validate the status of the
entities to ensure they are active before the collapse or split operations. The
IEntityResolution interface, as shown below, achieves this purpose. Any entity that
implements the interface and returns false for the isEntityActive method call will
be considered soft deleted.
If an entity is soft deleted, no further changes are allowed to the entity or its child
object. The state of the entity is considered frozen, and it retains all of its existing
data as-is after the soft delete. Any domain specific entity object to be enabled for
data stewardship should implement this interface to indicate whether its status is
active.

144

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
public interface IEntityResolution extends IDWLComponent {
public boolean isEntityActive();
}

The code table CdResolutionTp is introduced for the purpose of indicating the
reason why an entity is inactivated.
Table 17. CdResolutionTp code table
Resolution
Type

Name

Description

Consolidated

Resolution through collapse/merge operation

Split

Resolution through split operation

Learning the generic entity suspect processing and data stewardship
configuration elements
Entity suspect processing and data stewardship features are configured using the
Configuration and Management component.
For information about generic entity suspect processing and data stewardship
configuration elements, see “Understanding configuration elements in the
Configuration and Management component” on page 419.

Chapter 8. Understanding entity suspects management and entity data stewardship frameworks

145

Licensed Materials – Property of IBM

146

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 9. Configuring logging and error handling
InfoSphere MDM Server handles application and system messages by capturing
the problem or condition and reporting back to the caller with a meaningful
message. For certain validation failures, the response can contain multiple
messages if the request has multiple valid inputs.
At run time, InfoSphere MDM Server tracks various messages to a log destination.
These messages can be used to troubleshoot, diagnose, and debug the runtime
problems.
The message text reported to the caller is external to the InfoSphere MDM Server
application code so that developers can change or add messages without
modifying the application code.
In this section, you will learn:
“Understanding InfoSphere MDM Server messages”
“Understanding unique identifiers for system log messages” on page 148
“Understanding severity levels” on page 148
“Logging InfoSphere MDM Server messages” on page 150
“Adding or extending messages” on page 151

Understanding InfoSphere MDM Server messages
InfoSphere MDM Server messages are stored in a database. For more information
on the database schema used to store the messages, refer to the Data Model
ErrorHandling.pdf, which shows the error handling subject area of the data model.
The InfoSphere MDM Server code uniquely identifies each message, using four
parameters and four tables that detail the parameters:
v Component ID—Uniquely identifies the component or subject matter of the
message. This is defined in the COMPONENTTYPE table.
v Error type code—Identifies the type of problem or situation (such as a user error
versus a warning). This is defined in the CDERRTYPETP table.
v Error code—Identifies the reason for the message. This is defined in the
CDERRORMESSAGETP table.
v Language—Identifies the language in which the message displays. This is
defined in the CDLANGTP table. The application code uses the value passed in
the control header as the language to use for retrieving the error message.
For more information on each of these parameters and their associated tables,
consult the data dictionary for the corresponding database table in the IBM
InfoSphere Master Data Management Server Data Dictionary.
You can use a combination of the component ID, error type code, and error code to
point to the same error message text stored in the CDERRMESSAGETP table. This
allows you to identify each error message, and to reuse the error message text for
multiple error situations in the application.

147

Licensed Materials – Property of IBM

The Rules of Visibility and external validation features also use the error handling
mechanism. Error codes used by Rules of Visibility are specified in the
ERR_MESSAGE_ID field in the ENTITLECONSTRAINT table and the ones used
by external validation are specified in the ERROR_CODE field in the
V_ELEMENT_VAL and V_GROUP_VAL tables. Both ERR_MESSAGE_ID and
ERROR_CODE represent ERR_REASON_TP_CD in the ERRREASON table.
You can set error severity levels to level five (warnings) in the ERRREASON table.
If all errors encountered by the application are warnings, the transaction goes
through successfully, and the warnings are reported back to the caller in the object
which caused the warning. Modifying the severity of an error message can change
the behavior of the transaction: certain errors that have their severity changed from
a severity level of ″error″ to ″warning″ may still fail, but at a later stage in
processing. For example, if the error resulting from a missing or empty mandatory
field is changed to a warning, the transaction will still fail if the field is not
nullable in the database.
All messages are cached within the InfoSphere MDM Server application. If you
make any changes to the messages, you must restart the enterprise application
before the changes are available.

Understanding unique identifiers for system log messages
To simplify troubleshooting, InfoSphere MDM Server has a serviceability feature
that assigns every system log error or warning message with a unique, ten
character message prefix.
Having unique message identifiers for every system log message is useful because
they enable administrators and IBM Support personnel to:
v Easily identify the component from which the message originated.
v Track additional information to help to more quickly resolve the reported issue.
The format used for these unique message identifiers is CDK, where:
v CDK identifies the message as being from the InfoSphere MDM Server product.
v is a two character code that identifies the InfoSphere MDM Server
component that logged the message, such as MA for the Management Agent.
v is a four digit, unique numeric identifier.
v is a one character code identifying the severity type of the message:
– W – warning message
– E – error, exception, or fatal message
For example, CDKMA2036E identifies an error message logged by the InfoSphere
MDM Server Management Agent.
Note: If you are developing a custom application to work with InfoSphere MDM
Server, you may wish to identify your messages with a unique ID that enables you
to distinguish the custom application messages from the core InfoSphere MDM
Server messages. IBM recommends that you use CDKUS as your message ID prefix.

Understanding severity levels
The severity of a message refers to how severe the problems is. All InfoSphere
MDM Server messages are associated with a severity level.

148

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Error codes severity levels are defined in the CDERRSEVERITYTP table. By default
most problems defined for a customer do not have an explicit severity; instead,
this is interpreted by the application as a fatal severity level. If the application
encounters one or more errors with a severity level of fatal while executing a
persistence transaction, it rolls back the transaction and returns the errors in the
response.
The com.dwl.base.logging.IDWLLogger interface introduces logging severity levels.
The following table shows how IDWLLogger levels are mapped to Log4J and Java
logger levels:
Levels in IDWLLogger

Associated level in Log4j
logger

Associated level in Java
logger

OFF

FATAL

SEVERE

ERROR

SEVERE

WARN

WARNING

INFO

CONFIG

INFO

CONFIG

FINE

DEBUG

FINE

FINER

DEBUG

FINER

FINEST

DEBUG

FINEST

ALL

Although there are 13 levels shown in the table, InfoSphere MDM Server only uses
six levels. Developers building their own extensions, additions, or external rules
should follow the same guidelines when logging their messages.
v ERROR—Indicates severe error events that lead the application to abort. Here
are some typical examples:
– A system level error is caused by a throwable object

v
v

– Any system failure is due to a programming error such as null pointer
exception, or missing mandatory configuration
WARN—Indicates potentially harmful situations, but the application continues
to run. These situations are of interest to end-users or system managers
INFO—Indicates informational messages that are understandable to end-users
and system administrators, such as information about the execution flow
through major controller- and component-level methods (for example, in
preExecute and postExecute methods, and also in the entry and exit points of
external rules).
CONFIG—Indicates messages that provide a variety of static configuration
information to assist in debugging problems that may be associated with
particular configurations (for example, information on the application version,
properties versions, database type and version, and others).
FINE—Indicates fine-grained information events that are most useful to debug
the application, and are broadly interesting to developers who do not have a
specialized interest in the specific subsystem; for example, logging SQL

Chapter 9. Configuring logging and error handling

149

Licensed Materials – Property of IBM

statements, high-level Rules of Visibility messages, external rules, business
validations that are client’s error, and others.
v FINER—Indicates very granular informational events. In general, Finer should
be used for detailed tracing messages, such as showing low-level Rules of
Visibility messages, any logging within loops, and similar items.
Each logging API allows the level to be configured for run time to control the level
of detail in the log destination. This level can be set at any level within the logger
hierarchy ranging from root; that is, the global or application level, to any package,
sub-package, or class level. See the respective API documentation for more
information on how to do set the levels.
It is important that the level is set to an appropriate value based on the runtime
environment. If the level is more granular, the level provides more detail but slows
the application performance. On the other hand, only capturing the error level
logs, reduces, or even eliminates, most messages with the exception of errors,
making the application faster but more difficult to debug. The default level setting
is an error, and the following are guidelines for runtime environment messages:
v For development environment messages, use FINER to CONFIG.
v For testing environment messages, use:
– ERROR for faster performance but less information about the error.
– INFO or WARNING for more information about the error but slower
performance.
v For production environment messages, use ERROR.

Logging InfoSphere MDM Server messages
Use InfoSphere MDM Server messages to troubleshoot, diagnose, and debug
runtime problems. They can include fatal or warning messages. In general errors
are logged at the error log level, with the exception of request validation errors,
which are logged at the information level.
The InfoSphere MDM Server logging feature is highly configurable, and uses one
of the two available logging APIs:
v Java Development Kit (JDK) logging
v Log4J logging
Each API offers comparable logging features, which are fully employed in
InfoSphere MDM Server logging. There are three configuration files used to
configure the logging behavior:
v DWLLog.properties—Contains the underlying logging API used; that is, this file
sets the value for LoggerFactory property. You can use either:
– com.dwl.base.logging.DWLJDKLoggerFactory for JDK logging
– com.dwl.base.logging.DWLLog4jLoggerFactory for Log4J logging
v JDKLog.properties—Configures JDK logging; this is required only if JDK
logging is being used. See Java 2 platform’s core logging specifications for more
information on various configuration options available.
v Log4j.properties—Configures Log4J logging; this is required only if Log4J
logging is being used. See Log4J documentation for more information on various
configuration options available.
The exact location of the log messages is configurable in JDK as well as Log4J. See
the configuration files for the current log destination.

150

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

InfoSphere MDM Server uses the fully-qualified class name to create a logger for
each class that needs logging. This creates a logger hierarchy at the class level and
enables the developer or operator to filter log messages based on class,
sub-package or package level. Both JDK and Log4J provide configuration to define
such filters.

Adding or extending messages
Developers can customize messages by adding new ones or extending existing
messages. Use the com.dwl.tcrm.utilities.TCRMExceptionUtils class to handle error,
status, and exception classes and scenarios. See the API documentation in the class
for more information.
The following code shows an example use of this class:
public class TheClass {
private IDWLErrorMessage errHandler = null;
public TheClass() {
errHandler = TCRMClassFactory.getErrorHandler();
}
...
void public theMethod() throws TCRMException {
try {
...
} catch (TheException ex) {
TCRMExceptionUtils.throwTCRMException(ex, ....., errHandler);
}
}
...
}

Type and error codes for new components must be defined in the database tables
in order to be used with extensions and additions.
In addition, use the InfoSphere MDM Server common logging API in additions,
extensions, and external rules. The com.dwl.base.logging.IDWLLogger instance can
be obtained by calling the com.dwl.base.logging.DWLLoggerManager.getLogger
method. The IDWLLogger interface defines various log methods and logging
severity levels. Use the appropriate severity level for each logged message, as
described above.
This code snippet shows an example of the recommended method for using the
logging API:
public class TheClass {
private static IDWLLogger logger=DWLLoggerManager.getLogger(TheClass.class);
...
void public theMethod() {
logger.fine("Entereing TheClass.theMethod()");
...
logger.fine("Exiting TheClass.theMethod()");
}
...
}

Note: See the API documentation for more information about adding or extending
messages for each class and interface.

Chapter 9. Configuring logging and error handling

151

Licensed Materials – Property of IBM

152

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 10. Configuring external business rules
External business rules are pieces of business logic that have been externalized in
order to permit customizations to the logic to be incorporated into InfoSphere
MDM Server transaction processing. While every configuration option, validation
requirement, or property file entry could be considered an external rule, this
section discusses rules that embody the more complex business logic processing
and decision-making.
There are two methods of configuring external business rules:
v Using the Extension Framework
v Using the External Rules Framework
In this section, you will learn:
“Using the extension framework”
“Using the external rule framework”
“Understanding the default rules engine” on page 154
“Understanding considerations in using a Rules Engine” on page 155
“Understanding rule engine methods” on page 155
“Understanding external rules” on page 156
“Assigning the rule ID” on page 157

Using the extension framework
The Extension Framework provides a mechanism for modifying the behavior of a
service or transaction at predefined points in the application framework.
Using the Extension Framework is detailed in Chapter 2, “Customizing InfoSphere
MDM Server,” on page 17. In addition, configuring extensions using the Extension
framework is described in the Defining Extensions section of the IBM InfoSphere
Master Data Management Server System Management Guide.

Using the external rule framework
In contrast to the Extension Framework, which provides predefined points (that is,
pre- and post-execution) for the modification of behavior of every transaction, the
External Rule Framework allows for the customization of core business logic for
specific product features.
The External Rule Framework is leveraged in a number of product features serving
to externalize key logic that is likely to require customization to meet the needs of
the specific business. The survivorship rules for merging two parties into one, for
example, is something that is likely to differ from business to business. The
remainder of this chapter describes how to use the External Rule Framework and
the InfoSphere MDM Server external rules.
You can develop external business rules as Java classes or as rules to be executed
within an external rule engine, such as JRules from ILOG, an IBM company. The
majority of rules that are delivered with the product are Java rules. There is a
small subset of rules that have been implemented for execution within the JRules
© Copyright IBM Corp. 1996, 2009

153

Licensed Materials – Property of IBM

rule engine. However not every Java rule that has been provided has a
corresponding rules engine implementation.
Rules of both types, Java classes or rule engine rules, may be written and
configured to coexist as desired. To determine which method to use for each rule,
keep the following considerations in mind:
v What is the purpose of the rule you are about to implement?
– Rules that contain business knowledge (eligibility rules, product bundling
rules) perform business judgment (suspect processing rules) or produce
business event (party lifestyle management, business data corruption
detection) may be implemented as either rule engine (that is, ILog JRules - .ilr
rules) rules or as Java rules.
– Rules that provide the ability to customize transaction processing logic and
do not represent business policy or regulation, but are used as a plug-in point
should be implemented as Java rules.
v What is the life cycle of the rule?
– Rules that have a short life cycle or that change frequently should be
developed to be executed by a rules engine.
v Does the rule need to be accessible to other programs?
– The rules and data (such as enumerations) executed within a rules engine are
not accessible to other programs (for example, consuming Java code). If the
rule must be accessible this way, write a Java rule.
v Consider the type and volume of data that the application would potentially be
providing to the rules engine and volume of data the will be provided to the
rules within the Rules Engine.
v What is the skill set of the developers?
– Developing rules for use by a rules engine requires a different skill set than
writing pure Java rules. For example, rules written for the JRules rule engine
require the creation of a Business Object Model (BOM) in Rules Studio. The
BOM is an abstraction of the execution object model (XOM) of the application
(for example, InfoSphere MDM Server) and it must be created using your
own vocabulary, terms and needs.

Understanding the default rules engine
The rule engine that ships with the product is JRules from ILOG, an IBM company.

The External Rules Framework interacts with the JRules engine through a
standardized interface, com.dwl.base.rules.RuleEngine. The JRules engine itself is
″wrapped″ in the JRuleEngine adapter class, and it is this class that is specified in
the database as the rule engine type for each rule-engine rule.

154

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The rule engine implementation used by the External Rules Framework may be
replaced if desired. That is, the JRules engine may be replaced with another rules
engine as long as an adapter class for the replacement rules engine is created and
implements the generalized Rules Engine interface.
See also:
“To change the rule engine”

To change the rule engine
1. Create a new adapter class and implement the RulesEngine interface.
2. Update the RULEENGINEIMPL table to configure the new rule engine for the
appropriate external rules.
The fully qualified class name of the new adapter class should be configured in
the RULE_ENGINE_TYPE column for the rules it will get used for.

Understanding considerations in using a Rules Engine
While InfoSphere MDM Server provides the flexibility of developing business rules
as Java classes or as rules within external Rule Engine, some considerations should
be given when making this choice.
v Consider the purpose of the rule you are about to implement:
– Rules that contain business knowledge (Eligibility Rules, Product Bundling
Rules), perform business judgment (Suspect processing rules) or produce
business event (Party lifestyle management, business data corruption
detection) can be implemented as ILog rules or as Java rules.
– Rules that provide the ability to customize transaction processing logic and
do not represent business policy or regulation, but are used mostly as a
plug-in point should be implemented as Java rules.
v Consider life-cycle of the rule. Rules that have frequent and short change cycle
belong in rules engine.
v Keep in mind that the rules and data (such as enumerations) within a rules
engine aren’t accessible to other programs such as external java code.
v Take into consideration the data and volume of data the will be provided to the
rules within Rules Engine.
v Developing rules in a rules engine requires a different skill set than Java
development and still requires rigor and diligence of a development process.
v Rules should be written using a Business Object Model (BOM):
– BOM is created in Rules Studio as an abstraction of the InfoSphere MDM
Server Execution Object Model (XOM).
– BOM must be created using your vocabulary, terms and needs.

Understanding rule engine methods
The rule engine interface defines a standard set of methods that the rules engine is
expected to implement.
Those methods are:
v loadRules()
v assertFact()
Chapter 10. Configuring external business rules

155

Licensed Materials – Property of IBM

v fireRules()
v clearFacts()
These are a subset of the operations offered by a typical commercial rules engine,
but they are the ones used by the External Rule Component.

Understanding external rules
Executing an external rule involves passing an ExternalRuleFact to an
ExternalRuleComponent via the ExternalRule interface. The ExternalRuleComponent
uses rule implementation information stored in the database to either execute a
Java class or activate a rule engine to perform the rule processing. The
ExternalRuleFact, ExternalRuleComponent, and ExternalRule interface are all part
of the core API for the product’s external rule implementation.

The ExternalRuleFact is an object defined in the
dwl.base.externalrule.ExternalRuleFact class. It contains a rule ID, an input object
and an output object, as well as an optional component object on which the rule can
execute methods during processing if necessary. These objects generally also come
with all their associated business objects.
Setting up the dwl.base.externalrule.ExternalRuleFact involves providing the rule
ID, an input object and optionally a component object on which the rule can
execute methods during processing if necessary. The ExternalRuleComponent is
then invoked (executeRule()) passing this ExternalRuleFact.
“Example: The matchParty transaction configured to run in the JRules rule
engine” on page 157

156

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Example: The matchParty transaction configured to run in the
JRules rule engine
This is what the component-level code of the matchParty transaction looks like in
order to execute the rule configured to run in the JRules rule engine. It is
implemented in com.dwl.base.externalrule.partymatch.ilr.
//set input
aExternalRuleFact.setInput(input);
//set rule id
aExternalRuleFact.setRuleId("1");
// call external rule
aExternalRuleComponent.executeRule(aExternalRuleFact);

The component-level code of the searchParty transaction contains similar code in
order to run rule 9, which is implemented as a Java class:
// set input
aExternalRuleFact.setInput(input);
//set rule id
aExternalRuleFact.setRuleId("9");
//set TCRMPartyComponent as component object
aExternalRuleFact.setComponentObject(this);
//call external rule
aExternalRuleComponent.executeRule(aExternalRuleFact);

In this case, the component object (TCRMPartyComponent itself) is also passed
within the rule fact.

Assigning the rule ID
Each rule that has been implemented is listed in the EXTRULE table, completely
independent of its implementation. This table assigns the rule ID.

The rule ID is then mapped to a specific implementation in the EXTRULEIMPLEM
table. This table maps the rule ID to an external rule implementation ID, specifies
whether the rule is currently in force (active), and whether it is a rules engine (R)
or Java (J) implementation. The rule location—a JRules ruleset file, for
example—and the rule engine type together specify how the rule is to be executed.

Chapter 10. Configuring external business rules

157

Licensed Materials – Property of IBM

The rule type and external rule implementation ID point to the required rule,
either in the JAVAIMPL:

or the RULEENGINEIMPL table:

Important:
v Records in RULEENGINEIMPL table, are not run if EXTRULEIMPLEM has the
implementation changed to Java rules.
v Similarly, rules implemented in Java do not require any configuration in the
RULEENGINEIMPL table because these do not make use of a rules engine.

158

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 11. Configuring pluggable keys
Pluggable keys provide a single point of entry for defining the primary key for a
record into a database table. You can use your own implementation to create the
primary key on specific tables or on all tables
Each record in the InfoSphere MDM Server database for operational data such as
contact, product, and address, is identified by a single primary key. The primary
key can be generated by one of three methods:
v By using the default key generator that comes with InfoSphere MDM Server
v By plugging in a custom key generator
v By passing a primary key with the object in the service request, known as a
pluggable primary key
InfoSphere MDM Server also provides a framework to generate various types of
keys such as party identifiers; this is known as the key generation framework.
In this section, you will learn:
“Creating keys using the default key generator”
“Understanding the custom key generator”
“Understanding pluggable primary keys” on page 160
“Understanding unique and persistent ID generation framework” on page 161

Creating keys using the default key generator
The default key generator provides a convenient way to generate random, numeric
values that can be used as primary keys. The default key generator is specified in
the DWLCommon.properties file by the following property:
id_factory = com.dwl.base.util.DWLIDFactory

This default generator generates numeric keys in the format:
rrrrrrrrrrrrii

where:
v r = random number
v i = an optional instance identifier
The instance identifier is a value you can configure. The instance identifier can be
used in a clustered environment to eliminate the possibility of key collisions with
multiple server instances. To configure the instance identifier on each server,
specify a value for the following configuration element: /IBM/DWLCommonServices/
KeyGeneration/instancePKIdentifier

Understanding the custom key generator
If you want to generate primary keys in another format, you can write your own
key generate class and configure InfoSphere MDM Server to use it. For example,
you could prefix a primary key with a company code followed by some random
number.
© Copyright IBM Corp. 1996, 2009

159

Licensed Materials – Property of IBM

You can also write different key generator classes for use with different business
entities. For example, you could generate a primary key of 15 digits for
questionnaires and 18 digits for questions.
See also:
“To use your customized key generator class”
“To use different key generator classes for different business entities”

To use your customized key generator class
1. Write your own Java class to generate primary keys based on your
requirements.
This Java class must implement the com.dwl.base.util.IDWLIDFactory
interface. The primary key that is generated must be an integer and in
accordance to the BIGINT data type used for the primary keys in the database.
2. Configure your key generator class in the DWLCommon_extension.properties file.
For example:
id_factory = com.mycompany.MyIDFactory

To use different key generator classes for different business
entities
1. Write your own Java classes to generate primary keys of different formats
based on your requirements.
These Java classes must implement the com.dwl.base.util.IDWLIDFactory
interface. The primary key that is generated must be an integer and in
accordance to the BIGINT data type used for the primary keys in the database.
2. Configure your key generator classes in the DWLCommon_extension.properties
file.
To use an specific generator class for a business entity, append the table name
in lowercase that corrresponds to the business entity, to an id_factory property.
For example:
id_factory_questionnaire = com.mycompany.MyQuestionnaireIDFactory
id_factory_question = com.mycompany.MyQuestionIDFactory
id_factory = com.mycompany.MyIDFactory

Understanding pluggable primary keys
The pluggable primary key feature allows you to provide explicit primary keys to
use when creating business entities in InfoSphere MDM Server. For example, an
external system is integrating with InfoSphere MDM Server and you want
InfoSphere MDM Server to create a primary key that is the same as the primary
key on the external system.
The pluggable primary key feature is available with any Add transaction in which
one or more business objects are supplied. This also includes composite
update-type transactions in which a new child business object is being added as
part of the composite update transaction.

160

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

See also:
“To use pluggable primary keys”

To use pluggable primary keys
Specify a child PrimaryKeyBObj object with the primary key value, under the
business object.
When you supply the PrimaryKeyBObj object, the key generator is bypassed. For
example, the following XML representation shows a pluggable primary key for a
campaign business object.

Mortgage Promotion
This is Mortgage Promotion

RichBank
1
1
2001-05-08
2001-05-08

100

CampaignIdPK
5014000

Understanding unique and persistent ID generation framework
The unique and persistent ID generation framework provides the ability to:
v Generate different types of identifiers such as numeric, alphanumeric, numeric
string and alphabetic
v Generate different types of identifiers of variable length
v Return a set of identifiers instead of a single identifier
v Ability to plug custom ID generators
v Ability to configure validation rules for checking the generated identifiers
An example use of the framework is to generate party identifiers that become
persistent identifies that live across collapse party transactions.

Chapter 11. Configuring pluggable keys

161

Licensed Materials – Property of IBM

You can use the unique and persistent ID generation framework to add domain
specific identifier generators and plug any custom generators by following the
programming model prescribed by the framework. The enhancement to the
framework is implemented as asset of interfaces and the default implementation.
The framework also exposes configuration properties that can be used for hooking
custom generators.
The framework provides default implementations for generating generic identifiers
and party identifiers. This implementation can be invoked by business applications
to obtain an identifier that can be used as a primary or candidate key.

The unique and persistent ID generation framework defines the following
interfaces and implementations:
v com.dwl.base.IDWLIDFactory
v com.dwl.base.MDMIDGenerator
v com.dwl.base.MDMDomainIDValidator
The framework also provides the default implementations of the above interfaces
through the following classes:
v com.dwl.base.util.DWLIDFactory
v com.ibm.base.util.MDMDomainIDFactory
v com.dwl.tcrm.utilities.PartyIdentifierFactory
v com.dwl.base.uril.NumericIDGenerator
v com.dwl.base.uril.NumericStringIDGenerator
v com.dwl.base.uril.AlphaIDGenerator
v com.dwl.base.uril.AlphaNumericIDGenerator
v com.dwl.tcrm.utilities.PartyIdentifierValidator
For details of the classes and interface, refer to the Java API documentation. The
unique and persistent ID generation framework uses the following configuration
elements:
v /IBM/DWLCommonServices/IDGeneration/NumericIDGenerator/className
v /IBM/DWLCommonServices/IDGeneration/NumericStringIDGenerator/className
v /IBM/DWLCommonServices/IDGeneration/AlphaIDGenerator/className
v /IBM/DWLCommonServices/IDGeneration/AlphaNumericIDGenerator/className
In addition to the above properties that are applicable at the InfoSphere MDM
Server platform level, the framework also provides the following elements specific
to Party domain.
v /IBM/Party/IdentifierGeneration/Factory/className

162

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v /IBM/Party/IdentifierGeneration/Validator/className
v /IBM/Party/IdentifierGeneration/Validation/enabled
See the “Understanding configuration elements in the Configuration and
Management component” on page 419 topic for details about these configuration
elements.

Chapter 11. Configuring pluggable keys

163

Licensed Materials – Property of IBM

164

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 12. Configuring Smart Inquiries
The InfoSphere MDM Server implementation only uses part of its data model,
while the rest of the model, related to unused features and tables, is not used. You
can configure your implementation to completely turn off parts of the data model
related to unused features and tables.
When these parts of the model are turned off, the core product does not issue any
database I/O request against unused tables, and does not affect any functionality
around the used parts of the model. These Smart Inquiries improve processing
efficiency.
For related information, see Chapter 47, “Customizing Summary Data Indicators,”
on page 641.
In this section, you will learn:
“How disabling unused features and tables affects transactions”
“Disabling unused features and tables for Smart Inquiries” on page 167

How disabling unused features and tables affects transactions
Disabling parts of the data model for Smart Inquiries is done by using the
extension framework and the component-level, preExecute extension method.
When the extension framework is invoked, it sets the skipExecutionFlag to true
and the action does not continue to do DB I/O calls and return null/empty results.
The skip rule affects operational actions only when they are executed in composite
inquiry transaction. The rule does not affect the granular transaction itself.
For example, if the disabling extension for getAllPartyRelationships action is
activated, there are no DB I/O calls for party relationship when you run the
getParty transaction. That is because the getAllPartyRelationships action is
executed within the getParty transaction. However, there are DB I/O calls when
you directly run the getAllPartyRelationships transaction because the action is
executed as a granular transaction.
Note: Disabling a part of the data model does not affect the add and update
transactions related to that part of the model.
The following table shows the operational action transactions and the related
function area. When you turn off the operational action on the left, DB I/O for the
related function area on the right are not performed if the action is executed as a
part of a composite inquiry transaction.
Table 18. Operational actions and related function areas
Operational actions

Function area NOT performed

getAddress

Address

getAllAddressNotes

Address note

getAllAddressValues

Address Value

getAllContractAdminSysKeys

Contract Admin System Key

165

Licensed Materials – Property of IBM
Table 18. Operational actions and related function areas (continued)
Operational actions

166

Function area NOT performed

getAllContractAlerts

Contract Alert

getAllContractComponents

Contract Component

getAllContractComponentValues

Contract Component Value

getAllContractPartyRoleAlerts

Contract Party Role Alert

getAllContractPartyRoleIdentifierByContractRoleId

Contract Party Role Identifier

getAllContractPartyRoleRelationships

Contract Party Role Relationship

getAllContractPartyRoles

Contract Party Role

getAllContractPartyRolesByParty

Contract Party Role

getAllContractPartyRoleSituations

Contract Party Role Situation

getAllContractRelationships

Contract Relationship

getAllContractRoleLocationPurposes

Contract Role Location Purposes

getAllContractRoleLocations

Contract Role Location

getAllContractsByParty

Contract

getAllContractSpecValues

Contract Spec Value

getAllIncomeSources

Income Source

getAllOrganizationAlerts

Organization Alert

getAllPartyAddresses

Party Address group

getAllPartyAddressPrivacyPreferences

Party Address privacy preference

getAllPartyAlerts

Party Alert

getAllPartyBankAccounts

Bank Account

getAllPartyChargeCards

Charge Card

getAllPartyContactMethodPrivacyPreferences

Party contact method privacy
preference

getAllPartyContactMethods

Party contact method group

getAllPartyIdentifications

Identifier

getAllPartyLobRelationships

Party line of business relationship

getAllPartyLocationPrivacyPreferences

Location group privacy preference

getAllPartyPayrollDeductions

Payroll Deduction

getAllPartyPrivacyPreferences

Party privacy preference

getAllPartyRelationships

Contact Relationship

getAllPartyValues

Party Value

getAllPersonAlerts

Person Alert

getAllPrivacyPreferences

Privacy preference

getAllProductAdminSysKeys

Product Admin System Key

getAllProductCategoryAssociations

Product Category Association

getAllProductIdentifiers

Product Identifier

getAllProductInstanceRelationships

Product Instance Relationship

getAllProductSpecValues

Product Spec Value

getContactMethod

Contact method

getFinancialProfile

Financial Profile

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Table 18. Operational actions and related function areas (continued)
Operational actions
getHolding

Function area NOT performed
Holding

Disabling unused features and tables for Smart Inquiries
The extensions for disabling parts of the data model are inactivated in the gold
data.
These extensions must be activated to disable the related part of the data model.
To disable part of the data model for smart inquiries:
v Activate the extension, using the SQL statement:
update extensionset set inactive_ind = 'N' where extension_set_id =?

Where ? is the extension set ID for the specified extension for that disabling
model.
For example, to disable the FinancialProfile function area, which has the
extension set ID number 47, activate the disabling extension, by executing the
following SQL:
update extensionset set inactive_ind = 'N' where extension_set_id =47

See also:
“Administering Smart Inquiries”

Administering Smart Inquiries
Smart Inquiries does not require any special administration.

Chapter 12. Configuring Smart Inquiries

167

Licensed Materials – Property of IBM

168

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 13. Customizing search SQL queries
InfoSphere MDM Server allows clients to either write their own SQL queries to
execute customized searches, or to use the existing search methods.
You will learn the terminology used throughout this section, followed by an
overview of the search framework, and finally, you will learn how InfoSphere
MDM Server implements the framework to provide this point of customization in
the product, and how the addition of custom operators for spec value searches are
allowed for.

Learning search terminology
The following terms are used when discussing customizing SQL for searches:
v Pre-written SQL—Specifies a complete and valid SQL statement that can be
executed against a database. A collection of pre-written SQL statements can be
initialized at the startup, and an appropriate SQL can be selected based on the
search request input parameters.
v SearchBy methods—Specifies the search methods defined
in the component. These methods implement most of the search logic including
the construction of SQL statement, determination of which input parameters to
include or exclude from the search and which fields to return in the search as
well as input parameter standardization. Examples of these methods include
searchPersonByName, searchPersonByIdentification, searchOrganizationByName
etc.
v Criterion—Defines a single field, which is being searched on. The ordered
collection of all criterions, as they appear in the SQL, defines the SQL criteria.
v Comparison Operator—Defines the comparison being performed for each
criterion field. Examples include ″=″, ″LIKE″ etc.
v Search Input Parameters—Specifies the field values passed in a request as the
search business object attributes and the primary fields to be searched on.
v Supplementary Search Parameters—Specifies any additional parameters
required to execute the search transaction. Those additional parameters are
referred to as supplementary search parameters. The values for such parameters
are not included in the search business object, instead are accessed from system
configuration, for example, a properties file or the request header.
In this section, you will learn:
“Understanding the Search framework” on page 170
“Understanding InfoSphere MDM Server Search implementation” on page 174
“Comparing search methods” on page 175
“Understanding requirements for adding and editing SQL statements” on page
176
“Customizing search features” on page 176
“Understanding SQL lookup constraints” on page 178
“Constructing dynamic SQL statements” on page 179
“Adding new search input and output” on page 180
“Understanding business object inheritance” on page 180
“Adding new comparison operators” on page 181
© Copyright IBM Corp. 1996, 2009

169

Licensed Materials – Property of IBM

Understanding the Search framework
The Search framework is a lightweight framework designed as an InfoSphere
MDM Server common service. Interfaces and classes, which constitute the search
framework, can be classified into two main categories: SQL definition classes; and
SQL execution classes.

Learning SQL definition classes
The SQL definition classes and interfaces define the structure of a search SQL
statement.
Using these classes, the clients can create new search SQL statements, fetch SQL
statements, and pass these to the framework’s execution classes to perform the
search. The following list shows the classes that are included in this category.
v SearchSql—Represents the SQL to be executed for the search transaction. This
SQL can either be selected from a library of pre-written SQL statements or
dynamically constructed using the search input class. In addition to the SQL
statement, it also captures the input and output for the SQL statement. The input
is represented by an ordered collection of CriterionElement objects while the
output is captured by an instance of an implementation of IResultSetProcessor,
which is initialized with an ordered list of fields returned by the SQL statement.
v SearchField—Defines a search related field. It can be a field used in the search
criteria or a field included in the search results. The attributes of this class
include name and type of the search field.
v ComparisonOperator—Represents a comparison operator, which is applied to a
search field in the SQL. Examples include ″=″ or ″LIKE″. Since there is a known
finite list of operators, the class provides instances of each of these operators and
is not extensible and cannot be instantiated by any other class.
v CriterionElement—Represents an individual criterion element. Each element is
composed of a field name as well as the comparison operator for that field. If
the same field can be provided multiple times as search criteria (for example,
CategoryName in searchProductInstance), an additional sequence number can be
provided to uniquely identify each criterion. If the same field can be provided
multiple times as search criteria (for example, CategoryName in
searchProductInstance), an additional sequence number can be provided to
uniquely identify each criterion. Finally, criterion elements are discriminated
whether they are supplementary, or not.
v ISearchInput—Defines the interface to be implemented by any search input
class. A search input class wraps the existing SearchBObj class. One search input
class is needed for each SearchBObj class. The interface provides methods to
extract and standardize input parameters.
v SearchInput—SearchInput is abstract class that implements the ISearchInput
interface and provides some common implementation logic for search input
concrete classes. The SearchInput classes map the attributes of their respective
search business object to the corresponding search field. These classes also
implement logic to provide values for the supplementary search fields. A
hierarchy similar to the one used for the search business object classes is used to
model these search input classes. As a general rule, there should be one search
input class for each search business object class. Each search business object
results in exactly one search result set business object. The same is true of search
input and the corresponding search result set processor class.

170

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Learning SQL execution classes
The SQL execution classes provide services to execute a search SQL statement and
process its results. The following list shows the classes that are included in this
category.
v ISearch—Specifies an interface that defines the search component interface to
provide different search related services, including fetching pre-written SQL
statements, finding a matching pre-written SQL, and executing a search SQL.
v SearchComponent—Specifies a concrete implementation of the ISearch interface.
v IResultSetProcessor—Specifies an interface that defines the contract that should
be implemented by any search result processor classes.
The implementing class processes the results of a search query. These classes are
initialized with an ordered list of fields returned by the search query. This list is
then used by the class to extract the data from the query results and set the data in
the corresponding search result business object class. Given that the search result
business objects do not inherit from other search result business objects, the search
result processor classes do not follow the inheritance structure either. As a general
rule, there should be one search result processor class for each search result
business object.
Note: Query and SQLInput classes are not part of the search framework but are
used by the framework for executing SQL statements.

Learning search framework classes
The search framework class diagram shows the main classes and their associations
that make up the search framework:

Learning stored SQL statements
These SQL statements are fetched and cached in the application. The following
diagram shows the tables and their relationships, which contain the SQL
statements.

Chapter 13. Customizing search SQL queries

171

Licensed Materials – Property of IBM

The following provides a brief description of these tables:
v searchsql—Contains pre-written SQL statements.
v searchcriterion—Contains an ordered list of criterion fields for the given
pre-written SQL.
v searchresultfield—Contains an ordered list of search result fields for the given
pre-written SQL.
v sqlstatement—Contains the actual SQL statement that will be executed.
v cdcompoptp—Contains the available comparison operators.
v cdsrchfld—A code table which represents individual search fields that take part
in the search transactions. These can be search input (criterion) or output (result)
fields. If a search field is mapped directly to an attribute of a business object
(search or search result), it will be defined using the foreign key (application,
group and element) to the v_element table. All other search fields will be
defined using the srch_fld_name column. Each search field has a type as defined
by the cdelementtp table.
v cdelementtp—Defines all available search field types.
v v_element—An existing table which defines all attributes of the business objects.
See also:
“Sample: Searching with SQL queries”

Sample: Searching with SQL queries
The following examples illustrate how the search framework classes define the
structure of a SQL statement.

Simple example
In this example, InfoSphere MDM Server is searching for a person’s last name,
given name one and party ID, using parts of the person’s address information: the
address line 1, city name and the province code.

172

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The following SQL statement can be used to perform this search transaction.
SELECT P.CONT_ID, P.LAST_NAME, P.GIVEN_NAME_ONE
FROM PERSONNAME P, ADDRESS A, LOCATIONGROUP LG, ADDRESSGROUP AG
WHERE P.CONT_ID = LG.CONT_ID
AND LG.LOCATION_GROUP_ID = AG.LOCATION_GROUP_ID
AND AG.ADDRESS_ID = A.ADDRESS_ID
AND A.ADDR_LINE_ONE LIKE ?
AND A.CITY_NAME = ?
AND A.PROV_STATE_TP_CD = ?

The following diagram shows how the above SQL can be represented using the
classes provided by the search framework.
Search SQL
String
SELECT P.CONT_ID,P.LAST.NAME,P.GIVEN_NAME_ONE
FROM PERSONNAME P,ADDRESS A,LOCATIONGROUP LG,ADDRESSGROUP AG
WHERE P.CONT_ID=LG.CONT_ID AND LG.LOCATION_GOUP_ID = AG.LOCATION_GROUP_ID
AND AG.ADDRESS_ID = A.ADDRESS_ID
AND A.ADDR_LINE_ONE LIKE ?
AND A.CITY_NAME = ?
AND A.PROV_STATE_TP_CD = ?

CriterionElement
SearchField

A.ADDR_LINE_ONE

CriterionElement
SearchField
A.CITY_NAME

ComparisonOperator

IResultSetProcessor

1
2

SearchField
P.CONT_ID

SearchField
P.LAST_NAME

ComparisonOperator

SearchField
P.GIVEN_NAME_ONE

CriterionElement
SearchField

A.PROV_STATE_TP_CD

ComparisonOperator
=

Complex example
In the following example, the search framework is set up to search for products
given a product type id and several category names. There are two ways in which
multi-occurring search criteria can be specified in the predefined SQL. One is to
explicitly identify each repeated element, as in the following example SQL:
SELECT PROD.NAME, PROD.PRODUCT_TYPE_ID, PROD.SHORT_DESCRIPTION,
PROD.PROD_STRUC_TP_CD, PROD.STATUS_TP_CD, PROD.PRODUCT_ID
FROM PRODUCT PROD, CATEGORY CAT, PRODUCTCATEGORYASSOC PCASS
WHERE PROD.PRODUCT_ID = PCASS.PRODUCT_ID
AND CAT.CATEGORY_ID = PCASS.CATEGORY_ID
AND PROD.PRODUCT_TYPE_ID = ?
AND (CAT.NAME = ? OR CAT.NAME = ?)

Chapter 13. Customizing search SQL queries

173

Licensed Materials – Property of IBM

This SQL statement would be matched on only when exactly 2 categories were
specified as search criteria, and requires that the SAME_CRITERION_SEQ value of
the category name search criterion be specified (and unique – starting from 1,
incremented by 1).
If, however, you wish for the multi-occurring attribute (also known as repeatable
criteria) to be of an unspecified number and simply wish for them to be ORed
with each other (as is typically the default behavior for multi-occurring fields), use
the “/*<” and “>*/” place holders in the prewritten SQL. This SQL will be
reconstructed using what is specified within these placeholders. So if the following
SQL is configured:
SELECT PROD.NAME, PROD.PRODUCT_TYPE_ID, PROD.SHORT_DESCRIPTION,
PROD.PROD_STRUC_TP_CD, PROD.STATUS_TP_CD, PROD.PRODUCT_ID
FROM PRODUCT PROD, CATEGORY CAT, PRODUCTCATEGORYASSOC PCASS
WHERE PROD.PRODUCT_ID = PCASS.PRODUCT_ID
AND CAT.CATEGORY_ID = PCASS.CATEGORY_ID
AND PROD.PRODUCT_TYPE_ID = ?
AND /**/

If four category names are present as search criteria, then the following SQL would
result before the query is executed:
SELECT PROD.NAME, PROD.PRODUCT_TYPE_ID, PROD.SHORT_DESCRIPTION,
PROD.PROD_STRUC_TP_CD, PROD.STATUS_TP_CD, PROD.PRODUCT_ID
FROM PRODUCT PROD, CATEGORY CAT, PRODUCTCATEGORYASSOC PCASS
WHERE PROD.PRODUCT_ID = PCASS.PRODUCT_ID
AND CAT.CATEGORY_ID = PCASS.CATEGORY_ID
AND PROD.PRODUCT_TYPE_ID = ?
AND (CAT.NAME = ? OR CAT.NAME = ? OR CAT.NAME = ? OR CAT.NAME = ?)

This requires a single CRITERIONELEMENT to be specified with a
SAME_CRITERION_SEQ value of null or 1 to be specified.
Note: Errors will result in the application if you try to mix the above two
variations for the same criteria name. That is, for example, the two independent
strings, "CAT.NAME = " and /**/, must never appear within the same
SQL statement and the category name criterion elements must be set up for only
one or the other type.

Understanding InfoSphere MDM Server Search implementation
Many search implementations in InfoSphere MDM ServerI use this search
framework, including Product, Party and Contract.
Typically, for those services that tap into the search framework, a search rule is
called.
The search rule is an external and customizable logic, which can be implemented
as a regular Java class or as ILog JRule. Regardless of which implementation is
used, it performs the same logic and since the client implementation has the ability
to override the default implementation, it offers the maximum flexibility to modify
the search behavior. The default implementation of the search rule provides the
following functionality:
v You can call the SearchComponent to execute the search using a pre-written
SQL, which can handle the current input parameters.
v If no pre-written SQL is found, you can carry out the search transaction by
invoking the appropriate searchBy methods.
v You can apply inquiry level to fetch additional details.
In this section, you will learn:

174

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Comparing search methods
The following table provides a comparison of different search methods available to
implement a search transaction.
Factor

Pros

Pre-written SQL

v Customizable by
client
v
v
v

Cons

When to use

v No predefined
v One pre-written
criteria method is
SQL can only
available for the
handle one
Easier SQL
input parameter
combination of
optimization
combination.
input parameters.
Advanced SQL
Overuse of this
v A predefined
features
method may result
criteria method is
SQL may be
in an excessive
available, however
pre-compiled for
number of
its implementation
better performance
pre-written SQL
is not as per
statements.
Ease of use for all
specific search
existing search
transaction
types
requirements
(functional or
nonfunctional, e.g.
performance).
v Advanced SQL
features or an SQL
specific to the
DBMS is to be
used to perform
the search.

searchBy
v Ease of use for all

predefined search
criteria
v Additional and
specialized logic
possible for each
predefined criteria

Dynamic SQL
construction

v Criteria are
predefined by the
InfoSphere MDM
Server product so
clients cannot
customize it.

v A predefined
criteria method is
available for the
input parameter
combination and
its implementation
is as per the
v Current®
specific
implementation
requirements for
requires multiple
the search
SQL calls to fetch
transaction.
the required search
result.

v A generic
implementation to
handle SQL
v Slight variations in
construction for
search criteria can
various
be handled with
combinations of
generic code
input parameters
without having to
can be complex
write SQL for each
v Optimizing the
resulting SQL will
require the
construction code
to be modified
which may not be
practical.
v Customizable by
client

v Similar to
pre-written SQL,
but is preferable if
there is a slight
variation in certain
group input search
parameters and the
number of
combinations are
too many to be
coded as
pre-written SQL
for each
combination.

Chapter 13. Customizing search SQL queries

175

Licensed Materials – Property of IBM

Understanding requirements for adding and editing SQL statements
Keep the following points in mind when adding or editing search SQL statements:
v The SQL statement must be valid SQL for the current RDBMS. Using standard
SQL syntax is recommended as this helps to port the application to other
databases without modifying the SQL. Only use RDBMS-specific features if the
standard SQL syntax does not meet your needs.
v The SQL statement must be a SELECT statement.
v The SQL must have placeholders for each field-the criterion elements-being
searched on.
v Each criterion element included in the SQL must map to an attribute in the
search business object or be marked as a supplementary parameter.
v The columns included in the select list must map to the attributes of the search
result business object. It can be a direct one-to-one, one-to-many, many-to-one, or
a transformation mapping. It is up to the search result processor class to
implement this mapping.
v There are minimum column requirements for each type of search. This is to
ensure that the resulting search result business object meets the minimum data
requirement. For example, for party, person and organization search, the partyId
field must be included in the select list to uniquely identify the party.

Customizing search features
InfoSphere MDM Server clients have the flexibility to extend and customize search
logic while using the search framework to provide the lower level services.
When customizing the Search feature, you can add to the default collection of
pre-written SQL statements, or to update an existing SQL statement to meet your
specific needs. This is be done by adding to or updating the pre-written SQL
statement data.
Note: In order to customize the search function, you must understand SQL, and
have an in-depth understanding of the InfoSphere MDM Server data model.
See also:
“To add prewritten SQL queries”
“To edit prewritten SQL queries” on page 177

To add prewritten SQL queries
1. Determine which search method should be used in the search statement.
A search statement is defined by its input criteria and the entity being searched,
for example, Person vs. Organization.
Note: Adding or updating a prewritten SQL statement which handles the same
combination of input parameters as an existing searchBy
method hides the original searchBy method. Ensure that
the SQL search statement you are creating is unique, unless you intend to
override an existing search statement.
2. Write an SQL statement for the search.
3. Identify the search input class that this pre-written SQL statement belongs to.
See “Adding new search input and output” on page 180 for a list of search

176

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

input and output classes and the search fields available in each class, as well as
information on how the class is mapped to the database.
4. Identify both input search criteria and output search fields for the given
prewritten SQL in the CDSRCHFLD table.
5. Insert the data in the following tables for the given SQL:
v SQLSTATEMENT
v SEARCHSQL
v SEARCHCRITERION
v SEARCHRESULTFIELD
The following is an example SQL script to insert data into these tables.
Note: Please note that the insert into SQLSTATEMENT table for DB2 on
z/OS does not work properly if the SQL statement column value is greater
than 256 chars. In this case, you must import the data into the
SQLSTATEMENT table instead of inserting it.
INSERT INTO SQLSTATEMENT VALUES
(3,
'SELECT PS.GIVEN_NAME_ONE, PS.GIVEN_NAME_TWO, ...',
CURRENT TIMESTAMP);
INSERT INTO SEARCHSQL VALUES
(3,
'com.dwl.tcrm.coreParty.search.TCRMPersonSearchInput',
3,
'Search Party by field1, field2, field3, ...',
'com.dwl.tcrm.coreParty.component.TCRMPersonSearchResultSetProcessor',
'Y',
CURRENT TIMESTAMP);
INSERT
INSERT
INSERT
INSERT

INTO
INTO
INTO
INTO

INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
COMMIT;

SEARCHCRITERION
SEARCHCRITERION
SEARCHCRITERION
SEARCHCRITERION

VALUES
VALUES
VALUES
VALUES

SEARCHRESULTFIELD
SEARCHRESULTFIELD
SEARCHRESULTFIELD
SEARCHRESULTFIELD
SEARCHRESULTFIELD
SEARCHRESULTFIELD

(3,
(3,
(3,
(3,

VALUES
VALUES
VALUES
VALUES
VALUES
VALUES

1,
2,
3,
4,

(3,
(3,
(3,
(3,
(3,
(3,

47,
48,
34,
35,
1,
2,
3,
4,
5,
6,

2,
1,
1,
1,

51,
52,
53,
54,
55,
43,

'N',
'N',
'N',
'N',

CURRENT
CURRENT
CURRENT
CURRENT

CURRENT
CURRENT
CURRENT
CURRENT
CURRENT
CURRENT

TIMESTAMP);
TIMESTAMP);
TIMESTAMP);
TIMESTAMP);

TIMESTAMP);
TIMESTAMP);
TIMESTAMP);
TIMESTAMP);
TIMESTAMP);
TIMESTAMP);

6. Restart the application servers to allow for the changes to take effect.
7. Test the new search SQL statement by running a search transaction with a set
of input parameters, which match the SQL statement criteria.

To edit prewritten SQL queries
1. Determine which search method should be used in the search statement.
A search statement is defined by its input criteria and the entity being searched,
for example, Person vs. Organization.
Note: Adding or updating a prewritten SQL statement which handles the same
combination of input parameters as an existing searchBy
method hides the original searchBy method. Ensure that
the SQL search statement you are creating is unique, unless you intend to
override an existing search statement.
2. Write an SQL statement for the search.

Chapter 13. Customizing search SQL queries

177

Licensed Materials – Property of IBM

3. Identify the search input class this prewritten SQL statement belongs to. See
“Adding new search input and output” on page 180 for a list of search input
and output classes and the search fields available in each class, as well as
information on how the class is mapped to the database.
4. Identify both input search criteria and output search fields for the given
prewritten SQL statement in the CDSRCHFLD table.
5. Edit the data in the following tables for the given SQL:
v SQLSTATEMENT
v SEARCHSQL
v SEARCHCRITERION
v SEARCHRESULTFIELD
The following is an example SQL script to insert data into these tables.
Note: The insert into SQLSTATEMENT table for DB2 on z/OS does not work
properly if the SQL statement column value is greater than 256 chars. In this
case, you must import the data into the SQLSTATEMENT table instead of
inserting it.
INSERT INTO SQLSTATEMENT VALUES
(3,
'SELECT PS.GIVEN_NAME_ONE, PS.GIVEN_NAME_TWO, ...',
CURRENT TIMESTAMP);
INSERT INTO SEARCHSQL VALUES
(3,
'com.dwl.tcrm.coreParty.search.TCRMPersonSearchInput',
3,
'Search Party by field1, field2, field3, ...',
'com.dwl.tcrm.coreParty.component.TCRMPersonSearchResultSetProcessor',
'Y',
CURRENT TIMESTAMP);
INSERT
INSERT
INSERT
INSERT

INTO
INTO
INTO
INTO

INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
COMMIT;

SEARCHCRITERION
SEARCHCRITERION
SEARCHCRITERION
SEARCHCRITERION

VALUES
VALUES
VALUES
VALUES

SEARCHRESULTFIELD
SEARCHRESULTFIELD
SEARCHRESULTFIELD
SEARCHRESULTFIELD
SEARCHRESULTFIELD
SEARCHRESULTFIELD

(3,
(3,
(3,
(3,

VALUES
VALUES
VALUES
VALUES
VALUES
VALUES

1,
2,
3,
4,

(3,
(3,
(3,
(3,
(3,
(3,

47,
48,
34,
35,
1,
2,
3,
4,
5,
6,

2,
1,
1,
1,

51,
52,
53,
54,
55,
43,

'N',
'N',
'N',
'N',

CURRENT
CURRENT
CURRENT
CURRENT

CURRENT
CURRENT
CURRENT
CURRENT
CURRENT
CURRENT

TIMESTAMP);
TIMESTAMP);
TIMESTAMP);
TIMESTAMP);

TIMESTAMP);
TIMESTAMP);
TIMESTAMP);
TIMESTAMP);
TIMESTAMP);
TIMESTAMP);

Understanding SQL lookup constraints
In order for the pre-written SQL statement to be successfully fetched in the FETCH
algorithm, there are a number of points to keep in mind while designing the search
SQL statements. They are:
v The SQL lookup algorithm only considers the search input parameters passed
into the search business object to perform the lookup.

178

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v A pre-written SQL will only be selected if each non-null and non-blank input
parameter passed into the request has a corresponding criterion element in the
SQL criteria and the SQL does not contain any additional non-supplementary
criterion elements.
v A criterion element may appear multiple times in the SQL. The algorithm only
uses the unique collection of criterion elements to look up the SQL and ignores
the duplicate instances of the same criterion element. The same input parameter
is used while executing the query as a value for all instances of that criterion
element.
v Lookup only considers the criterion element including the name and the
comparison operator. Other elements of the SQL criteria are not considered. For
example, the combination operator (AND, OR), and the order of criterion
elements are not considered during the lookup.
v If there are multiple SQL statements with the same collection of criterion
elements, InfoSphere MDM Server selects the first one in the list, and ignores the
other SQL statements. This scenario should be avoided.
The following table provides examples of the algorithm results for different
combinations of search input parameters and the SQL criteria.
#

Input Parameters

SQL Criteria

Match

Comments

[A,=] -see note

[B,=]

Yes

Order of elements is not
relevant.

[B,=]

[A,=]

[A,LIKE]

[B,=]

A’s comparison operator is
different

[B,=]

[A,=]

[B,=]

[C,=]

C is a non-supplementary
criterion whose input
parameter is not provided

Yes

All non-supplementary
elements are provided.

B does not have a criterion
element.

Yes

B is duplicate but the unique
collection of criterion
elements has a complete
match.

[A,=]
4

[A,=]

[B,=]

[C,=,supplementary]
[A,=]

[A,=]

[C,=]

[B,=]

[A,=]

[C,=]
6

[A,=]

[B,=]

[B,=]
[B,=]

Note: Where A is the search field name, for example, last name or address line or
date of birth, and ″=″ is the comparison operator.
Please note that these constraints are only valid if the SQL is included in the
pre-written SQL collection. If the SQL is being dynamically constructed based on
the input parameters, the above constraints do not apply.

Constructing dynamic SQL statements
The search framework supports the dynamic creation of an SQL statement, based
on the search business object.
Chapter 13. Customizing search SQL queries

179

Licensed Materials – Property of IBM

This can be accomplished by editing the appropriate search rule to add logic to
construct the SQL query to be used for the current search transaction.
The best place to customize the search to add dynamic construction of SQL would
be the search rule.
See also:
“To construct dynamic SQL statements”

To construct dynamic SQL statements
1. Create an SQL string to use for the current search. Construct the WHERE
clause of the SQL statement from the search business object’s non-null and
non-blank attributes. The SELECT column list may or may not depend on the
input parameters.
2. Create an ordered collection of CriterionElements, which represent the SQL
criteria.
3. Create an instance of the appropriate search result set processor class to handle
the list of columns being selected.
4. Create an instance of SearchSQL, using the SQL statement, criterion elements
and the search result set processor.
5. Create an instance of the appropriate search input class by passing in the
search business object.
6. Execute the search using the search component by passing the search SQL
statement and the search input class.

Adding new search input and output
Clients may require searching on or searching for additional fields not provided by
the existing implementation.
See also:
“To add search input and output”

To add search input and output
1. Define new classes by extending the existing search business objects.
2. Define new search input classes to handle the new search business object
extensions and overwrite methods to build search input parameters.
3. Write new search result set processor, if new fields are being searched for, by
implementing the IResultSetProcessor interface.
4. Determine the search method to be used for this search request; the two
options are prewritten SQL statement or dynamic SQL statement construction.

Understanding business object inheritance
All search-related fields for IBM InfoSphere Master Data Management Server are
added to the CDSRCHFLD table.
Currently the v_element table contains all the attributes of all search and search
result business objects. However, since some of these classes have an inheritance
relationship, all the parent attributes are repeated for the child object as well. For
instance, the group PersonSearch contains all PartySearch attributes, in addition to
its own attributes.

180

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

In the object model however, parent attributes exist only once in the
TCRMPartySearchBObj, and then the TCRMPersonSearchBObj inherits them. Since
a search field is identified by a unique name, duplicate rows in the v_element table
for essentially the same attribute would break the unique constraint on the search
field. To avoid this problem, the object model uses the attribute that belongs to the
highest class—or group as it is called in the v_element table—in the hierarchy. For
instance, all TCRMPartySearchBObj attributes are mapped to elements belonging to
the PartySearch group in the v_element table; the same attributes belonging to the
PersonSearch group are ignored.

Adding new comparison operators
This section describes how support for a custom operator can be added to the spec
value search capabilities of InfoSphere MDM Server.
To add a custom operator, the following must be done:
v a new type code must be added to the CDXMLCOMPOPTP table
v a method must be overridden at the search query construction level of the
application, and
v the class containing this method must be defined in configuration in order to be
instantiated instead of the default class
The standard code table services can be used to add the custom type code (and its
translated values) to the CDXMLCOMPOPTP code table. See the IBM InfoSphere
Master Data Management Server Common Data Dictionary for details. There are
primarily two attributes for this new type code: the type code itself and the name.
Depending on the database platform configured to work with InfoSphere MDM
Server, the corresponding spec value search query class should be subtyped:
Table 19. Query class name subtypes by database platform
Database

Query Class Name (in
com.ibm.mdm.common.spec.search.sql)

DB2 V9.5 for Linux, Unix, and
Windows

NativeDBSpecValueSearchSQLDB2

DB2 V9.7 for Linux, Unix, and
Windows

NativeDBSpecValueSearchSQLDB2

Oracle 11g

NativeDBSpecValueSearchSQLOracle

DB2 V9 for z/OS

NativeDBSpecValueSearchSQLDB2v90z

DB2 V8 for z/OS

EntityIndexTableSpecValueSearchSQL

The fully qualified name of the custom class should then be stored in the
/IBM/Product/SpecValueSearch/SpecValueSearchSQL/className configuration item.
Note that there is a default value for the class, configured dynamically by
InfoSphere MDM Server at runtime; however, you can define a static class if you
know which database you are using.
Finally, the processCustomizeOperation method should be implemented to handle
the custom operator type. It should include validations specific to this operator,
handle the construction of the query snippet given the requirements of the new
operator.
See also:
Chapter 13. Customizing search SQL queries

181

Licensed Materials – Property of IBM

“Sample: Adding the custom operator type code”

Sample: Adding the custom operator type code
Because searching for elements in a set of specified values is not supported, this
guide will illustrate this using a simple example of adding an in operator to the
searchProductInstance service.
For our example, we assume that our new entry has a type code of 1000001 and
name of in and that you are running on DB2 V9.5 for Linux, Unix, and Windows,
the custom class can be represented as follows:
class MySpecValueSearchSQL extends NativeDBSpecValueSearchSQLDB2 {
protected String processCustomizeOperation(
SpecValueSearchCriteriaBObj svsc, String path, String datatype,
boolean isLocaleSpecific, boolean isCaseSensitive
)throws Exception {
//e.g. return fn:upper-case(.) = (fn:upper-case("a"),fn:upper-case("b"))
StringBuffer sqlSnippet=new StringBuffer();
if("1000001".equals(svsc.getOperatorType())){
//1000001 is in
//do some validations base on criteriaBObj, throw business exception if needed
sqlSnippet.append(provideSelfAxis(datatype,isCaseSensitive)+" = (");
for(int i=0;i0){
sqlSnippet.append(",");
}
sqlSnippet.append(convertXQueryDatatype(datatype,
svsc.getItemsValue().elementAt(i),isCaseSensitive));
}
sqlSnippet.append(")");
}else{
super.processCustomizeOperation(svsc, path, datatype,
isLocaleSpecific, isCaseSensitive);
}
return sqlSnippet.toString();
}
}

For DB2 V8 for z/OS, the class can be represented slightly differently, because the
internal index table is used:
class MySpecValueSearchSQL extends EntityIndexTableSpecValueSearchSQL {
protected String processCustomizeOperation(
SpecValueSearchCriteriaBObj svsc, String path, String datatype,
boolean isLocaleSpecific, boolean isCaseSensitive
)throws Exception {
//e.g. return UPPER(svi.string_value) in ( ? , ? )
StringBuffer sqlSnippet=new StringBuffer();
if("1000001".equals(svsc.getOperatorType())){
//1000001 is in
//do some validations base on criteriaBObj, throw business exception if needed
String columnName=SpecValueSearchConstant.datatypeDBFieldMap.get(datatype);
String columnAlais="svi."+columnName+" ";
if(datatype.equalsIgnoreCase("mdmspec:localizedString")
|| datatype.equalsIgnoreCase("xsd:string")){
if(!isCaseSensitive)
columnAlais="UPPER(svi."+columnName+") ";
}

182

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
sqlSnippet.append(columnAlais+" in (");
for(int i=0;i0){
sqlSnippet.append(",");
}
sqlSnippet.append(" ? ");
}
//additional space needed at tail
sqlSnippet.append(") ");
}else{
super.processCustomizeOperation(svsc, path, datatype,
isLocaleSpecific, isCaseSensitive);
}
return sqlSnippet.toString();
}
}

Chapter 13. Customizing search SQL queries

183

Licensed Materials – Property of IBM

184

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 14. Configuring the service activity monitoring facility
The service activity monitoring facility provides a way to capture the system
information generated by the InfoSphere MDM Server product.
The data provided by the service activity monitoring facility could be used to
produce system reports for capacity planning and identifying areas of
optimization, and can demonstrate how InfoSphere MDM Server services and
transactions are being used in a given installation.
The service activity monitoring facility provides information about every
transaction request processed by InfoSphere MDM Server. The following
information is made available through a JMX notification mechanism:
v transaction name
v start time
v size of the request and response
v transaction duration
v transaction outcome
Optionally, this data can also be captured in a log file.
In this section, you will learn:
“Understanding service activity monitoring facility information”
“Obtaining data from the service activity monitoring facility” on page 186
“To activate the service activity monitoring facility” on page 188

Understanding service activity monitoring facility information
This table describes the InfoSphere MDM Server data provided by the Service
Activity Monitoring facility.
Table 20. Data captured by the Service Activity Monitoring facility
Element name

Type

Data origin

transactionName

java.lang.String

DWLTransaction.getTxnType()
Important: For composite transactions, the
thransactionName value is constructed as the combination
of all the transaction names inside the composite
transaction, separated by slashes, prefixed with
CompositeTx. For example: CompositeTx/searchParty/
addParty/updateParty.

requestName

java.lang.String

DWLControl.getRequestName()

requesterName

java.lang.String

DWLControl.getRequesterName()

requesterLanguage

java.lang.String

DWLControl.getRequesterLanguage()

requesterLocale

java.lang.String

DWLControl.getRequesterLocale()

lineOfBusiness

java.lang.String

DWLControl.getLineOfBusiness()

company

java.lang.String

DWLControl.getCompany()

geographicalRegion

java.lang.String

DWLControl.getGeographicalRegion()

transactionCorrelatorId

java.lang.String

DWLControl.getTransactionCorrelatorId()

externalCorrelationId

java.lang.String

DWLControl.getExternalCorrelationId()

clientTransactionName

java.lang.String

DWLControl.getClientTransactionName()

clientSystemName

java.lang.String

DWLControl.getClientSystemName()

sessionId

java.lang.String

DWLControl.getSessionId()

185

Licensed Materials – Property of IBM
Table 20. Data captured by the Service Activity Monitoring facility (continued)
Element name

Type

Data origin

requestOrigin

java.lang.String

DWLControl.getRequestOrigin()

transactionId

java.lang.String

DWLControl.getTxnId()

customerDeployedVersion

java.lang.String

DWLControl.getCustomerDeployedVersion()

customerEnvironment

java.lang.String

DWLControl.getCustomerEnvironment()

customerRequestVersion

java.lang.String

DWLControl.getCustomerRequestVersion()

inquireAsOfDate

java.lang.String

DWLControl.getInquireAsOfDate()

inquireFromDate

java.lang.String

DWLControl.getInquireFromDate()

inquireToDate

java.lang.String

DWLControl.getInquireToDate()

requestID

java.lang.Long

DWLControl.getRequestID()

requestSize

java.lang.Integer

The size of the request message in bytes.

responseSize

java.lang.Integer

The size of the response message in bytes.

transactionStatus

java.lang.String

DWLStatus.getStatus()

startDateTime

java.sql.Timestamp

Timestamp at the begging of the transaction.

endDateTime

java.sql.Timestamp

Timestamp at the end of the transaction.

executionTime

java.lang.Long

Duration of transaction in milliseconds.

osName

java.lang.String

System.getProperty(‘os.name’) +
System.getProperty(‘os.version’)

applicationName

java.lang.String

Application Name as configured in Configuration and
Management.

applicationVersion

java.lang.String

Application Version as configured in Configuration and
Management.

applicationDeploymentName

java.lang.String

Deployment Name as configured in Configuration and
Management.

applicationInstanceName

java.lang.String

Instance Name as configured in Configuration and
Management.

federatedInstanceName

java.lang.String

DWLControl.getfederatedInstanceName

requestTime

java.lang.String

DWLControl.getRequestTime

updateMethodCode

java.lang.String

DWLControl.getUpdateMethodCode

inquiryLanguage

java.util.Vector

DWLControl.getItemsInquiryLanguage

returnResponse

java.lang.String

DWLControl.getReturnResponse

pageStartIndex

java.lang.String

DWLControl.getPageStartIndex

pageEndIndex

java.lang.String

DWLControl.getPageEndIndex

returnAvailableResultCount

java.lang.String

DWLControl.getReturnAvailableResultCount

availableResultsCount

java.lang.String

DWLControl.getAvailableResultsCount

Obtaining data from the service activity monitoring facility
You can obtain the data produced by the service activity monitoring facility
through JMX notification. Optionally, you can use a Log4J log file to capture these
JMX notifications.

JMX notification
When enabled, the service activity monitoring facility provides activity information
about every transaction in the form of a JMX notification.
Note: See “To activate the service activity monitoring facility” on page 188 for
details about how to enable the service activity monitoring facility.
The following class diagram provides an example of the JMX notification process.

186

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

1. The notification com.dwl.base.report.mbean.TransactionDataNotification is sent
from the MBean com.dwl.base.report.mbean.TransactionDataBroadcasterMBean.
2. The notification containing the com.dwl.base.report.TransactionData object can
be obtained by calling the getTransactionData() method on the
TransactionDataNotification class.
Each TransactionData object contains the map with information regarding a single
InfoSphere MDM Server transaction. The names and type of the objects in the map
are provided in Chapter 14, “Configuring the service activity monitoring facility,”
on page 185.
In order to capture the JMX notification, InfoSphere MDM Server registers the
listener with the MBean Server, providing the object name of the MBean that
issued the notification. The object name is platform-specific and partially depends
on the values of the installation parameters configured during installation of
InfoSphere MDM Server.
Below is an example of an object name for TransactionDataBroadcasterMBean in
InfoSphere MDM Server:
DWL:type=com.dwl.base.report.mbean.TransactionDataBroadcasterMBean,
deployment=deployment1,J2EEApplication=deployment1,process=server1,
cell=userNode01Cell,node=userNode01

Log4J log file
The service activity monitoring facility provides activity information about every
transaction in the form of JMX notification. InfoSphere MDM Server supplies an
implementation of JMX listener to capture these JMX notifications and send it to
the Log4J log file for output.
The class name of the InfoSphere MDM Server JMX listener is configured in the
Report.Listener.MBean.Impl.className property in the DWLCommon.properties file.
When the /IBM/DWLCommonServices/Report/Listener/enabled configuration setting
is set to true, InfoSphere MDM Server registers the listener with the local MBean
server.
When the listener receives the JMX notification, it captures activity information in
the transactiondata.log file located on the same host. The file name, location, and
Log4J settings can be modified by changing the values of several
log4j.appender.transactionData_file properties in the Log4J.properties file.

Chapter 14. Configuring the service activity monitoring facility

187

Licensed Materials – Property of IBM

By default, the Log4J log file is configured to use the
org.apache.log4j.DailyRollingFileAppender class as an appender. With
DailyRollingFileAppender, the output is written to the log files.
The files roll over at user-defined time interval that can be configured in the
DatePattern property in the Log4J.properties file. For example, if you choose to
have the files roll over at the midnight each day (’.’yyyy-MM-dd), the output is
written into the transactiondata.log during the day and at midnight the file will
be copied to transactiondata.log.2006-06-19 and logging continues to the
transactiondata.log over the course of the next day.
Service activity data are printed into the log file in a comma-separated format to
make it easier to import the data into database or a spreadsheet, which could be
used to make a report about system activities.
Each line in the log file corresponds to one transaction. The data in the
comma-separated line is arranged in the same order as in the table above, Data
captured by the service activity monitoring facility. Depending on the transaction type,
not all the fields have values; for example, the inquireAsOfDate field for persistent
transactions is empty. Null fields are rendered in the log as empty strings ″″.

To activate the service activity monitoring facility
1. Use the Configuration and Management module of InfoSphere MDM Server to
change the value of the /IBM/DWLCommonServices/Report/Broadcaster/enabled
property to true.
This configuration setting is dynamic, so when the value changes, the
application server applies the change without requiring a restart.
Note: For information about using the Configuration and Management
module, see Chapter 34, “Using the Configuration and Management
components,” on page 405.
2. To enable the service activity monitoring facility to capture the activity data in
a log file, use the Configuration and Management module of InfoSphere MDM
Server to change the value of the /IBM/DWLCommonServices/Report/Listener/
enabled property to true.
When enabled, this configuration setting registers the listener with the MBean
Server, providing the object name of the MBean that issued the notification.
This configuration setting is static, so when the value changes, you must restart
the application server to apply the change.
See the “Understanding configuration elements in the Configuration and
Management component” on page 419 topic for details about these configurations.

188

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 15. Customizing the language and locale in
InfoSphere MDM Server
You can define the language and locale for your implementation of InfoSphere
MDM Server which enables the application to be deployed and used across
various geographies.
Some of the highlights include:
v A single executable code that is used for all supported locales
v A single deployment that can support multiple locales simultaneously. The
installation allows the installer to select additional languages to be deployed, in
addition to the default English language.
v In addition to the default English language, translations for locale-sensitive
strings are provided for the following languages:
– French
– German
– Greek
–
–
–
–
–

Italian
Spanish
Portuguese
Polish
Simplified Chinese

– Traditional Chinese
– Korean
– Japanese
v Operational data can be provided in any language in transactions, not just the
languages listed above. InfoSphere MDM Server uses UNICODE, which enables
data to flow through the system without any loss or corruption.
In this section, you will learn:
“Defining the supported languages” on page 190
“Support for errors and code table data” on page 190
“Understanding how InfoSphere MDM Server handles the user locale” on page
191
“Specifying the locale” on page 192
“Understanding how InfoSphere MDM Server handles the application locale”
on page 195
“Setting up code table data” on page 195
“Customizing the database” on page 204

189

Licensed Materials – Property of IBM

Defining the supported languages
The supported languages are defined in the CDLANGTP table in the database. If you
need to support other languages you must define them in this table. The following
are some sample records from this table:
Table 21. Sample Records in the CDLANGTP Table
LANG_TP_CD

NAME

LOCALE

100

English

200

French

300

Spanish

400

Chinese (Simplified)

500

Chinese (Traditional)

zh_TW

The LANG_TP_CD values are used internally by InfoSphere MDM Server. The LOCALE
values follow commonly used Java locale values.

Support for errors and code table data
InfoSphere MDM Server provides support for errors and code table data at both
the application level and at the operational data level.
At the application level, business error messages and system error messages are
provided in the selected language. Business error messages are stored in the
database and they are retrieved using the InfoSphere MDM Server error handling
component. See Chapter 9, “Configuring logging and error handling,” on page 147
for more information.
An example of a business error message is “The following is required:
PartyId”, indicating some mandatory data is required. This type of message is
specific to the individual requests; it is returned in the response based on the
language or locale specified in the request. See “Understanding how InfoSphere
MDM Server handles the user locale” on page 191 for more information.
System error messages are stored in InfoSphere MDM Server as resource bundles
and they are retrieved using the Java API. An example of a system error message
is “The property is not defined in the properties file”, indicating some
configuration error condition. This type of message applies to the entire
application. It is returned in the response based on the locale configured for the
application runtime environment.
System error messages are generally accompanied by user-friendly messages that
are also translated to the local language of the user. See “Understanding how
InfoSphere MDM Server handles the application locale” on page 195 for more
information.
At the operational data level, code table data is set up using the code table service,
and when a request requires a code type, the corresponding code value is returned
in the response based on the language specified in the request. See “Setting up
code table data” on page 195 for more information.

190

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Understanding how InfoSphere MDM Server handles the user locale
A request sent to InfoSphere MDM Server includes operational data and other
transaction control information used to handle the user locale.
In the XML representation of the request, the transaction control information is
represented by the element. The element contains
two child elements that the user of the request can use to specify the user’s
language. They are and . The user can use
either one of these elements, or both. These values are specific to the request, and
therefore specific to the user of the request. They are used for the following
purposes:
v Retrieving code table values that are defined in the database, based on the
language.
v Retrieving error messages that are defined in the database, based on the
language.
The following is a snippet of the XML representation of an addParty request:

5014017

cusadmin
fr
...

addParty
TCRMPartyBObj

...

2
Tomás
Sáenz
...

In this request, the user requesting this transaction indicates the language of his
choice is French. He is adding person with a Spanish family name Sáenz and first
name Tomás, and a specific .
When the transaction is successfully processed, the response is returned as shown
in this snippet of the XML representation of an addParty response:

SUCCESS
Chapter 15. Customizing the language and locale in InfoSphere MDM Server

191

Licensed Materials – Property of IBM
43579

...
200
fr
...

addParty

SUCCESS

...
5331138746277062
...

Tomás
Sáenz
...
2
Docteur
...

Since the family name and first name are textual information, the names are stored
as-is. The of 2 returns the corresponding in the
language specified in the element, in which case is French.

Specifying the locale
InfoSphere MDM Server provides several ways to specify the language and the
locale.
InfoSphere MDM Server provides two values to use to specify the language. They
are and in the element.
These two values correspond to one of the records in the CDLANGTP table.
However, some client applications may not be able to provide both values. One
such example is a Web application. Typically, a Web application can only provide
the locale.

192

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Given that a request may provide or , or
both, InfoSphere MDM Server needs to ensure that these values are acceptable. It
does so by calling the DWLControl.resolve() API after it parses the request. This
API attempts to derive the fallback values which are the best match between the
values provided in the request and the values defined in the CDLANGTP table.
The following sections describe how this API resolves the language and the locale.
See also:
“Specifying
“Specifying
“Specifying
“Specifying
page 195

the
the
the
the

locale
locale
locale
locale

when
when
when
when

neither language or locale is provided”
only the language value is provided”
only the locale value is provided”
both the language and the locale are provided” on

Specifying the locale when neither language or locale is
provided
If neither nor is provided in the
element, the request fails because InfoSphere MDM Server cannot
determine the language of the user.

Specifying the locale when only the language value is
provided
If only the value is provided in the element,
the value must exist as one of the LANG_TP_CD values in the CDLANGTP table.
The corresponding LOCALE value in the table is then set as the
value in the element. The following example shows the
element providing only the :

...
200
...

Based on the sample records shown in the CDLANDTP table, the
element become as follows:

...
200
fr
...

If the value provided is not in the CDLANGTP table, the
request will fail.

Specifying the locale when only the locale value is provided
If only the value is provided in the element, the
value, or one of its derivations, must exist as one of the LOCALE values in the
CDLANGTP table.

Chapter 15. Customizing the language and locale in InfoSphere MDM Server

193

Licensed Materials – Property of IBM

If the value, or one of its derivations, does not exist in the CDLANGTP table, the
locale en, for English, is used. The corresponding LANG_TP_CD value in the table is
then set as the value in the element. The
derivation of the locale is based on the Locale fallback logic in Java.
Example 1
If the provided is es:

...
es
...

Based on the sample records shown in the CDLANDTP table, the
element is updated to Spanish:

...
300
es
...

Example 2
If the provided is fr_FR:

...
fr_FR
...

Based on the sample records shown in the CDLANDTP table, the fallback locale for
fr_FR, which is fr, and the element is updated to French:

...
200
fr
...

Example 3
If the provided is ru:

...
ru
...

Based on the sample records shown in the CDLANDTP table, the fallback locale
for ru, which is en is found, and the element is updated to English:

...
100
en
...

194

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Specifying the locale when both the language and the locale
are provided
If both the and values are provided in the
element, the combination of these values must be an exact match
of one of the records in the CDLANGTP table. Otherwise, the request fails.

Understanding how InfoSphere MDM Server handles the application
locale
The application locale refers to the locale used by the system administrator to
manage the application.
This is the locale that determines the language for assets such as:
v Log messages that have a severity level of FATAL to WARN—see the
com.dwl.base.logging.IDWLLogger API.
v Runtime exception messages for exceptions that are raised at the application
level.
v Other runtime exception messages in situations where the
element is not available, for example, exceptions that occur before the request is
successfully parsed.
v Messages resulting from asynchronous processing in InfoSphere MDM Server,
for example, Event Manager in InfoSphere MDM Server.
The application is determined by the system’s properties in the Java runtime
environment in which the InfoSphere MDM Server application starts up in the
application server. From the Java perspective, these properties are defined as
user.language and user.country in the JVM. There are various ways to specify
these properties: they can be specified explicitly; or they can be defaulted from the
operating system. These settings are outside of the scope of InfoSphere MDM
Server. Refer to the documentation from the application server and the operating
system for information on setting these values.

Setting up code table data
InfoSphere MDM Server is shipped with code table values and error messages
translated in each of the available languages. The code table values and error
messages are stored in various database tables.
These tables can be classified as one of two types:
v Language independent code table
v Language dependent code table
A language independent code table holds data in only one language. The data is
used mainly to configure the application and ideally should be in the language
that best suits the language of the system administrators. At installation time, the
installer must select one language to populate these tables with. An example of
such a table is COMPONENTTYPE. This table stores the Java objects that
InfoSphere MDM Server supports, and the descriptions of these records are in the
language that is intended for the system administrator.
A language dependent code table holds data in one or more languages. The data is
used to provide translated values in the language of the end user. By default,
English data is always populated in these tables. At installation time, the installer
Chapter 15. Customizing the language and locale in InfoSphere MDM Server

195

Licensed Materials – Property of IBM

can select one or more languages that the installation base expects to support. An
example of such a table is CDADDRUSAGETP. This table stores the address usage
types that InfoSphere MDM Server supports and they should include the various
languages corresponding to the end users.
For the language dependent code tables, they have lang_tp_cd which maps to
lang_tp_cd column in the CDLANGTP table. Fallback logic is applied when caching
these code table records.
The caching mechanism relies on the language and locale to build a language and
locale hierarchy. This hierarchy contains all the records in the CDLANGTP table that
have a null expiry_dt or if the expiry_dt is in the future and
CODE_TABLE_TRANSLATION has value as ‘Y’.
The language dependent code table records are cached for the languages in the
hierarchy. For example, for CDIDTP, the records are cached for supported languages
that have CODE_TABLE_TRANSLATION flag set to ‘Y’ in CDLANGTP. For the other
languages that have CODE_TABLE_TRANSLATION flag set to ‘N’, you can add a record
to CDIDTP, but they are not in cache and cannot be retrieved. In order to use
them, you must set the CODE_TABLE_TRANSLATION flag to ‘Y’ for that language.
See also:
“Adding additional code table data”
“Understanding InfoSphere MDM Server behavior when retrieving code table
data” on page 197
“Understanding InfoSphere MDM Server behavior when validating code table
data in transactions” on page 200
“Adding currency codes” on page 203

Adding additional code table data
Code table data for additional languages and additional type codes can be added
to InfoSphere MDM Server.
Typically, there are two reasons for adding additional code table data:
v You must add support for a language other than those provided in the base
product. In this case, you must first add a record for the language in the
CDLANGTP table. Then refer to the data model to populate the code table data
and error messages for the language.
v You must add additional type codes for existing tables. In this case, you must
add additional records in the tables for the type codes and all the translated
values.
In either case, you must ensure that the English set of code types and code values
is the complete set. InfoSphere MDM Server uses English as the default language if
the language or locale provided by the user do not produce a match in the
CDLANGTP table—see “Specifying the locale” on page 192 for information on
specifying the locale. Therefore, it is important that the English set of any code
tables and error messages is the complete set. In addition, InfoSphere MDM Server
provides a flexible way of populating code table data, which relies on the English
set of data as the baseline.

196

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Flexibility in populating code table data
For all the code tables, InfoSphere MDM Server only requires that the English set
of data—LANG_TP_CD=100 and LOCALE=en—be the complete set. All other languages
are not required to be the complete set. When InfoSphere MDM Server retrieves a
code type for a language and that combination of code type and language is not
defined in the code table, InfoSphere MDM Server attempts to find the fallback
values based on the value in the element. When
no match is found, InfoSphere MDM Server ultimately returns the English code
type.
This flexibility is particularly advantageous when there are only slight variations in
the languages. One such example is the difference between American English and
British English, where there are occasional spelling variations between these two
languages. If you want to add support for British English in InfoSphere MDM
Server, you only need to add records to the code tables where the British English
spelling is different. You do not need to add the entire set of records.

Understanding InfoSphere MDM Server behavior when
retrieving code table data
InfoSphere MDM Server provides several distinct transactions for administrator
and operational service consumers to maintain code table data.
Note: For detailed information and a complete list of these services, see Chapter 4,
“Understanding InfoSphere MDM Server common code type framework,” on page
99, the IBM InfoSphere Master Data Management Server Common Services Transaction
Reference Guide, and the IBM InfoSphere Master Data Management Server Transaction
Reference Guide.
The transactions that InfoSphere MDM Server provides to enable operational
service consumers to retrieve code table data are:
v
v
v
v

getAllOperationalCodeTypes
getAllOperationalCodeTypesByLocale
getAllOperationalCodeTypesByLangId
getOperationalCodeType

Because of the flexibility to populate data, as described in “Flexibility in
populating code table data,” these transactions return code table data that best
match the condition. To illustrate the behaviors of these transactions, assume the
following data in the CDLANGTP table.
Table 22. Sample Records in the CDLANGTP Table
LANG_TP_CD

NAME

LOCALE

100

English

200

French

300

Spanish

Assume the following data in the CDADDRUSAGETP table:
Table 23. Sample Records in the CDADDRUSAGETP Table
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

100

Primary Residence

Chapter 15. Customizing the language and locale in InfoSphere MDM Server

197

Licensed Materials – Property of IBM
Table 23. Sample Records in the CDADDRUSAGETP Table (continued)
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

100

Other Residence

100

Business

100

Mailing

200

Résidence principale

200

Autre résidence

200

Envoi

300

Otra residencia

300

Empresa

Transaction — getAllOperationalCodeTypes
If the getAllOperationalCodeTypes transaction is submitted for the
CDADDRUSAGETP table, based on the data in the sample records tables, the
following records are returned.
Table 24. Sample Records in the CDADDRUSAGETP Table
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

100

Primary Residence

100

Other Residence

100

Business

100

Mailing

200

Résidence principale

200

Autre résidence

200

Envoi

300

Otra residencia

300

Empresa

This transaction returns all the records defined in the table.

Transaction — getAllOperationalCodeTypesByLocale
This transaction returns all code types for the given locale. The number of records
returned for each locale is always the same as that in the base locale, en. In other
words, if a record is not defined for a non-English locale, the record based on the
fallback rules is returned.
Important: The set of data for the base locale en must be a complete set.
Example 1
If the getAllOperationalCodeTypesByLocale transaction is submitted for the
CDADDRUSAGETP table and locale en, based on the data in the sample records
tables, the following records are returned.

198

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Table 25. Results of the getAllOperationalCodeTypesByLocale Transaction
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

100

Primary Residence

100

Other Residence

100

Business

100

Mailing

Example 2
If the getAllOperationalCodeTypesByLocale transaction is submitted for the
CDADDRUSAGETP table and locale es, based on the data in the sample records
tables, the following records are returned.
Table 26. Results of the getAllOperationalCodeTypesByLocale Transaction
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

100

Primary Residence

300

Otra residencia

300

Empresa

100

Mailing

Example 3
If the getAllOperationalCodeTypesByLocale transaction is submitted for the
CDADDRUSAGETP table and locale fr_FR, based on the data in the sample
records tables, the following records are returned.
Table 27. Results of the getAllOperationalCodeTypesByLocale Transaction
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

200

Résidence principale

200

Autre résidence

100

Business

200

Envoi

Transaction — getAllOperationalCodeTypesByLangId
The behavior of this transaction is similar to that of the
getAllOperationalCodeTypesByLocale transaction. This transaction returns exactly
the number of records defined in the complete set of data for the base language
type code 100. However, if a record is not defined for the locale, the fallback record
is returned.
Example 1
If the getAllOperationalCodeTypesByLangId transaction is submitted for the
CDADDRUSAGETP table and LANG_TP_CD 200, based on the data in the sample
records tables, the following records are returned.

Chapter 15. Customizing the language and locale in InfoSphere MDM Server

199

Licensed Materials – Property of IBM
Table 28. Results of the getAllOperationalCodeTypesByLangId Transaction
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

200

Résidence principale

200

Autre résidence

100

Empresa

200

Envoi

Transaction — getOperationalCodeType
This transaction returns the exact match if the record exists. If no exact match
exists, the fallback record based on the locale corresponding to the language type
code is returned.
Example 1
If the getOperationalCodeType transaction is submitted for the
CDADDRUSAGETP table, LANG_TP_CD 200, and ADDR_USAGE_TP_CD 1, based on the
data in the sample records tables, the following record is returned.
Table 29. Results of the getOperationalCodeType Transaction
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

200

Résidence principale

Example 2
If the getOperationalCodeType transaction is submitted for the
CDADDRUSAGETP table, LANG_TP_CD 300, and ADDR_USAGE_TP_CD 1, based on the
data in the sample records tables, the following record is returned.
Table 30. Results of the getOperationalCodeType Transaction
LANG_TP_CD

ADDR_USAGE_TP_CD

NAME

100

Primary Residence

Understanding InfoSphere MDM Server behavior when
validating code table data in transactions
InfoSphere MDM Server allows users to specify the type code, value, or both in the
request. It validates these values to ensure that they are acceptable values, and
uses a fallback approach to validate these values.
Much of the data that users submit in the requests are based on code table values.
For example in the snippet of the XML representation of an addParty response, the
type code is set for the element in the request. When InfoSphere
MDM Server produces the response for this request, InfoSphere MDM Server looks
up the corresponding value in the user’s and sets it in the
element.
InfoSphere MDM Server allows the user to specify the type code, or the value, or
both in the request. It validates these values to ensure that they are acceptable
values. It also uses a fallback approach that is similar to the approach described in

200

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

“Understanding InfoSphere MDM Server behavior when retrieving code table
data” on page 197 to validates these values.

Providing type code only
Example 1
This example shows the request and the response when the is
fr.
Request for = fr

Response for = fr

...

...
200
fr
...

...

...
1
Résidence principale

...

fr
...

...

...
1
...

Based on the data in the sample records tables, an exact match of the address
usage type code 1 and locale fr exists in the CDADDRUSAGETP table.
Example 2
This example shows the request and the response when the is
es.
Request for = es

Response for = es

...

...
300
es
...

...

...
1
Primary Residence

...

es
...

...

...
1
...

Based on the sample data, no exact match of the address usage type code 1 and
locale es exists in the CDADDRUSAGETP table. Therefore, the fallback is derived
as follows:
Chapter 15. Customizing the language and locale in InfoSphere MDM Server

201

Licensed Materials – Property of IBM

v The fallback for locale es is en
v The language type code for en is 100
v The record for address usage type code 1 and address usage value Primary
Residence is returned

Providing type value only
Example 1
This example shows the request and the response when the is
fr_FR.
Request for = fr_FR

Response for = fr_FR

...

...
200
fr
...

...

...
4
Envoi

...

fr_FR
...

...

...
Envoi

...

Based on the sample data, no exact match of the address usage type value Envoi
and locale fr_FR exists in the CDADDRUSAGETP table. Therefore, the fallback is
derived as follows:
v The fallback for locale fr_FR is fr
v The language type code for fr is 200
v The record for address usage value Envoi and 200 is
returned

Providing both type code and type value
Example 1
This example shows the request and the response when the is
es.

202

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Request for = es

Response for = es

...

...
300
es
...

...

...
1
Primary Residence

...

es
...

...

...
1
Primary Residence

...

Based on the sample data, no exact match of the address usage type code 1, type
value Primary Residence and locale es exists in the CDADDRUSAGETP table.
Therefore, the fallback is derived as follows:
v The fallback for locale es is en
v The language type code for en is 100
v The record for address usage type code 1, address usage value Primary
Residence, and language type code 100 exists. Therefore, this is a valid record.

Adding currency codes
InfoSphere MDM Server stores each amount value with an associated currency
type. The currency types are defined in the CDCURRENCYTP table.
When you add new currency code types, you must populate the
CURRENCY_CODE column with the correct three letter currency code as assigned
by ISO standards. For more information, see http://www.iso.org/iso/en/prodsservices/popstds/currencycodeslist.html. This ensures that appropriate formatting
rules are applied when displaying the corresponding currency amounts. In the
database, the amount value is stored with 3 decimal places, allowing for currencies
that require 3 decimal places, such as Bahraini Dinar (BHD).
The currency type is associated with the amount value, and an external validation
is available to ensure that if a currency type is provided, that an amount is also
provided.
Currently, InfoSphere MDM Server has the following database tables that contain
one or more currency amount columns, which are affected by globalization:
v INCOMESOURCE
v
v
v
v
v

CONTRACT
CONTRACTCOMPONENT
CLAIM
HOLDING
BILLINGSUMMARY

Chapter 15. Customizing the language and locale in InfoSphere MDM Server

203

Licensed Materials – Property of IBM

Customizing the database
The InfoSphere MDM Server database can be customized for text data and for
database collation.
InfoSphere MDM Server supports the following databases:
v DB2 UDB
v DB2 for z/OS
v Oracle
The installation creates a database that uses the UTF-8 encoding for all character
data types. Using UNICODE encoding ensures that characters from any language
can be persisted.
See also:
“Customizing column size for text data”
“Collating the database” on page 205

Customizing column size for text data
InfoSphere MDM Server stores text data in the database using the CHAR or VARCHAR
data type.
The column size for this data is measured in number of bytes. Because of the
nature of UTF-8 encoding, one text character may be encoded by as many as 4
bytes.
In the worst case scenario, the column size created by the installation can only
accommodate number of text characters that is ¼ of the column size. Therefore,
after the database is installed, you should analyze the type of data you expect to
store in the database and adjust the column size accordingly. You should do this on
a case by case basis and do this according to the business requirement.
For example, the LAST_NAME column in the PARTYAME table is used to store a
person’s family name. By default, the column size for this field is 30. Therefore, in
the worst case scenario, only 7 text characters can be stored. In order to store 30
text characters, you will need to increase this column size by 4 times. However, the
default column size is more than enough if you only plan to store persons with
ethnic Han Chinese family names, since ethnic Han Chinese family names are
limited to 2 text characters in length.
If you expect to store non-ASCII characters in InfoSphere MDM Server, you should
increase the length of some derived fields.
Note: Typically, derived fields are prefixed with U, and are defined in the file
named Insensitive_search_enabled.sql.
When non-case-sensitive searches are enabled for DB2 LUW, all searchable fields,
such as SERVICE_ORG_NAME, have a corresponding derived field, such as
USERVICE_ORG_NAME, where the value is stored in upper case to facilitate searches.
By default, the original and derived fields are of the same length.
However, variable-length character encoding, such as UTF-8 case mappings, can
produce strings of different lengths than the original. For example, a value stored
in the searchable field, such as ″Eßen,″ may take up more bytes than the original

204

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

when converted to upper case, such as ″ESSEN.″ As a result, the length of these
derived fields must be increased if they will contain non-ASCII characters.

Collating the database
Database collation settings affect the matching and ordering of results fetched from
the database.
Use the following collation settings for the supported databases:
Table 31. database collation settings
Database

Collation settings

DB2

UCA400_NO

DB2 for z/OS

Unicode

Oracle

Use the NLS_SORT monolingual linguistic setup, if the tables contain data in
only one language. Monolingual linguistic setup uses less memory and
performs better than multilingual linguistic sort setup. If the tables contain
more than one language, multilingual linguistic setup is necessary. If you
are using this sorting setup, consider:
v Adding additional memory to compensate for the memory usage
v Adding a linguistic index to enhance query performance

Chapter 15. Customizing the language and locale in InfoSphere MDM Server

205

Licensed Materials – Property of IBM

206

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 16. Defining inquiry levels
Inquiry levels are parameters that define the level of detail for objects being
returned in a search, or inquiry, transaction.
Inquiry levels can be defined, allowing new combinations of objects to be returned.
The core product business objects supported for inquiry-level customization are
Person, Organization, and Contract.
InfoSphere MDM Server offers a variety of inquiry transactions that accept one or
more inquiry levels as parameters. InfoSphere MDM Server uses these parameters
to select the correct objects to return as a part of the transaction.
In this section, you will learn:
“Objects and transactions that child objects can be retrieved for”
“Modifying inquiry levels”

Objects and transactions that child objects can be retrieved for
Child objects can be selectively retrieved for the following transactions:
v getParty
v getPerson
v getOrganization
v getContract
v getProductInstance
Object access path modifications occur if the configuration of these objects is
changed:
v Person
v Organization
v Contract
v Product

Modifying inquiry levels
You can customize, extend, and modify the inquiry levels used in your InfoSphere
MDM Server implementation
See also:
“Configuring new inquiry levels”
“Configuring a new child for a parent business object” on page 209
“Extending inquiry levels” on page 210
“Administering inquiry levels” on page 210

Configuring new inquiry levels
To configure a new inquiry level:

207

Licensed Materials – Property of IBM

Use the Administration Services to add or update an inquiry level configuration.
Be aware of the following points when configuring new inquiry levels:
v Allowed and Reserved Ranges—The permitted numeric range of integers for
new inquiry levels is from 100 and up. Levels 99 and under are reserved for
internal use by the IBM InfoSphere Master Data Management Server product .
Note: Do not use or change the existing configurations of any of the reserved
ranges.
– Expiring Inquiry Level and Child Groups—The inquiry level for an object
and the child objects they retrieve for an object may be expired using the
expiry_dt field. If an Inquiry Level is expired, that record is not made
available to the system for further processing. Only active Inquiry Levels are
retrieved by the system for use.
– Cumulative Inquiry Levels—Inquiry levels may be cumulative. This means
that particular level includes ALL objects configured for every inquiry level
below it, regardless of whether or not any of the lower levels are cumulative .
For example, if level 120 has cumulative_ind = ’Y’ or is cumulative, all groups
configured for level 120 down to level 100 are returned as the set of child
objects to return for that particular object. In sum, levels are not skipped
when one is defined as cumulative.
Note: Client-defined inquiry levels—level 100 and above—are not cumulative to
include product-defined inquiry levels (0-99).
– Configure only the child Groups to be returned for the parent
Group—There is no need to configure the Group for the Person, Organization
or Contract object as a child of the inquiry level for itself. By definition,
inquiry level objects are child objects so, at a minimum, the parent object
itself is always be returned. For example, there is no need to configure
Contract level 1 to contain child Contract, to ensure its return.
– Configuration Warning Messages—It is possible to configure an inquiry level
incorrectly. When this happens, Status 5 warning messages indicate which
objects for the inquiry level are in error. For example, if an inquiry level is
defined for Person, say 101, that returns child objects PersonName,
PartyIdentification, and IncomeSource, when running a getParty() transaction
(level 101), a configuration warning is returned, stating that the parent of the
IncomeSource object is configured incorrectly. IncomeSource requires the
FinancialProfile to be configured for Party as well, because IncomeSource,
PartyChargeCard, PartyBankAccount, and TCRMPartyPayrollDeductionBObj
are within the processing of FinancialProfile. These dependencies are noted in
the charts supplied detailing the current configuration of the IBM InfoSphere
Master Data Management Server objects (Contract, Organization, Person) and
their inquiry levels. The following is an example of the warning message:

10
DWLErrorMessageComponent
Parent object of ContractPartyRoleIdentifier was not configured
properly for inquiry level. Add record for parent object of
ContractPartyRoleIdentifier in table INQLVLGRP.
Some objects may not be returned due to inquiry level
configuration errors in table INQLVLGRP
0
15204
5

208

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

– Use the Transaction Reference Guide: See the IBM InfoSphere Master Data
Management Server Transaction Reference Guide for out-of-the-box details on the
objects returned for inquiry levels for getParty (getPerson (Person object),
getOrganization (Organization object) and getContract (Contract object).

Configuring a new child for a parent business object
There are two cases where you can configure a new child object for a parent
business object:
v New child objects are added to the Person, Organization or Contract objects to
accommodate client requirements for an addition or extension to the IBM
InfoSphere Master Data Management Server product.
v An existing child business object of Person, Organization or Contract is not
currently being returned through its composite inquiry transaction (that is,
through getPerson, Organization, or Contract) for any of the product-defined
inquiry levels, the extension framework may used to retrieve it as an extension.
The parent object can also be configured to return this child object for new
inquiry levels.
For both of these cases, see Chapter 2, “Customizing InfoSphere MDM Server,” on
page 17 for details on incorporating new objects, using the extension framework.
To make the new child object configurable with new inquiry levels:
1. Ensure the child object has an entry in the V_GROUP table and is registered for
the ’TCRM’ application.
2. Create an entry in the INQLVLGRP table to affiliate the object with a particular
parent object’s inquiry level, either Contract, Person, or Organization.
Note: At any extension point in existing getPerson, getOrganization or
getContract transactions, the DWLControl object holds a Map of inquiry level
information for the objects returned by the transaction. The structure of this
Map is shown below:
Structure of Map:
customizationInquiryLevelMap

parent group name
(Contract)

Map of child groups

child group name

boolean T/F

3. If the name of the new child group exists in the child group map:
v Execute your inquiry logic
v Set the boolean value for the child group name to true.
Note: If this value is not set, an invalid configuration warning message
surfaces when the transaction is completed.
Example code snippet:
//retrieve the parent groups for the current transaction
Map parentGroups = null;
groupMap
= dwlControl.getCustomizationInquiryLevelMap();
Chapter 16. Defining inquiry levels

209

Licensed Materials – Property of IBM

//retrieve the map of the child groups for the parent group needed
//(i.e., Contract)
Map childGroups = null;
childGroups
= groupMap.get(TCRMFinancialGroupNames.CONTRACT);
//if the child group is in the map configured for the parent group,
//execute the inquiry transaction for this child group - otherwise do
//nothing.
if (childGroups != null && childGroups.containsKey
(TCRMFinancialGroupNames.CONTRACT_ALERT){
Vector contractAlerts = getAllContractAlerts(contractId,
TCRMRecordFilter.ACTIVE, dwlControl);
childGroups.put(TCRMFinancialGroupNames.CONTRACT_ALERT, new
Boolean(true));
//continue here with any logic to be executed on the returned vector
//of ContractAlert objects
}

Extending inquiry levels
See Chapter 2, “Customizing InfoSphere MDM Server,” on page 17 for details on
incorporating new objects, using the extension framework.

Administering inquiry levels
Inquiry Levels do not require special administration.

210

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 17. Retrieving audit history
InfoSphere MDM Server has an audit, or history, database.
The audit database is a duplicate of the operational database, with the exception of
the code and rule tables, along with additional audit attributes. The audit tables
are populated at the time of execution of any InfoSphere MDM Server transaction,
via the default set of triggers for the InfoSphere MDM Server product. These tables
store the actual data that has been added or updated in the transaction. InfoSphere
MDM Server allows any inquiry transaction (get***) to return either current or
point-in-time data. If a valid element occurs in the request control,
the ″get″ transaction takes its data from the audit tables rather than the operational
ones.
In this section, you will learn:
“Understanding criteria for history inquiry transactions”
“Understanding point-in-time history inquiries” on page 214
“Understanding database considerations for history inquiry” on page 215

Understanding criteria for history inquiry transactions
The retrieval of audit data from these tables brings back records according to the
following criteria. The records:
v Have a last update date in the past that is earlier than and closest to the date
entered by the client.
v Have an end date, if relevant, that is NULL—that is, only one copy of the record
can be active at any point in time
The format for the DWLControl element must:
v Have at least a date portion that complies with the date format specified in the
/IBM/CoreUtilities/DateValidation/dateFormat configuration. See
“Understanding configuration elements in the Configuration and Management
component” on page 419 for more information.
v Use a space to separate the date and time portion if a time portion is entered; a
time portion is optional; if a time portion is not entered the default time is set to
23:59:59.0, for Oracle, or 23:59:59.000, for DB2
v Specify time (24hr) in hours and minutes separated by a colon, for example
11:14; seconds are not considered
The following element is valid assuming the value of
/IBM/CoreUitlities/DateValidation/dateFormat resolves to the following format:
YYYY_MM_DD

where _ represents the configured separator, -, in the /IBM/CoreUtilities/
DateValidation/dateSeparator configuration::
2002-06-13 11:14

Note that 2002-06-13 would also be valid,
with the time assumed to be the default.

211

Licensed Materials – Property of IBM

The /IBM/DWLCommonServices/DateValidation/dateFormat record specifies the
format for the year, month, and date portion of the date field.
See also:
“Sample: History inquiry transactions”
“Understanding the audit history tables” on page 213

Sample: History inquiry transactions
The XML transactions for both a point-in-time request and the resulting response
are shown below.
Note that the inquireAsOfDate in the request control is 2002-10-23. The record
returned has an IncomeSourceHistCreateDate of 2002-09-27.

Request: getIncomeSource

20010

DWL Customer
100
07-07-2002 10:00:00
66

Integration Environment

Product Development
DWL Inc.
North America
1234567890
Integration001
XML Tester
2002-10-23 11:14:54.0
007008009
DWL Customer
001002003004005
1
DWL Customer Team

getIncomeSource

4721033184131194

Response: getIncomeSource

SUCCESS
40869

XML Tester
Integration001
DWL Inc.

Integration Environment

212

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

66
North America
2002-10-23 11:14:54.0
Product Development
100
DWL Customer
07-07-2002 10:00:00
007008009
1234567890

getIncomeSource

SUCCESS

1024
108880.00
2
CDN$
U

2002-09-27 22:35:35.684889

DBCLIENT

2092722353526795

4721033184131194

2002-09-27 22:35:31.195

Adriano
1
Annual Salary

2002-09-27 22:35:31.195

5
5891033184130452

Understanding the audit history tables
The audit tables have a structure identical to the operational tables with the
exception of five additional audit attributes, which are italicized and are described
below the table. Operational tables for code tables and rules do not have
corresponding audit tables. By conducting an inquiry using audit attributes, it is
possible to see exactly what the operation record looked like for any given point in
time. The table below shows the comparable contact and h_contact tables.
Table 32. comparable contact and h_contact tables
contact

h_contact
h_contact_id: BIGINT NOT NULL (PK)
h_action_code: CHAR(1) NOT NULL
h_created_by: VARCHAR(10) NOT NULL
h_create_dt: TIMESTAMP NOT NULL (PK)
Chapter 17. Retrieving audit history

213

Licensed Materials – Property of IBM
Table 32. comparable contact and h_contact tables (continued)
contact

h_contact
h_end_dt: TIMESTAMP

cont_id: BIGINT NOTNULL (PK)

cont_id: BIGINT NOTNULL

acce_comp_tp_cd: BIGINT (FK)

pref_lang_cd: BIGINT (FK)

created_dt:TIMESTAMP NOT NULL

inactivated_dt: TIMESTAMP

contact_name: VARCHAR(255)

person_org_code: CHAR(1) NOT NULL

solicit_ind: CHAR(1)

confidential_ind: CHAR(1)

client_imp_tp: BIGINT (FK)

client_st_tp: BIGINT (FK)

client_potent_tp_cd: BIGINT (FK)

rpting_freq_tp_cd: BIGINT (FK)

last_statement_dt: TIMESTAMP

alert_ind: CHAR(1)

last_update_dt: TIMESTAMP NOT NULL

provided_by_cont: BIGINT(FK)

last_update_user VARCHAR(20)(FK)

and other fields...

The additional attributes are:
v h_cont_id—The history record key; one of the composite primary key values
(PK)
v h_action_code—Insert (Add) or Update
v h_created_by—The requesterName element in the Control portion of the
add/update transaction that generated the history record
v h_create_dt—When created, one of the composite primary key values (PK)
v h_end_dt—Where relevant, for expired attributes such as identification

Understanding point-in-time history inquiries
The sequence diagram shown below outlines the steps in the process flow of a
getHierarchy service executed for a particular point in time.

214

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Understanding database considerations for history inquiry
This section provides more information on the database triggers that ship with
IBM InfoSphere Master Data Management Server. The history inquiry function of
IBM InfoSphere Master Data Management Server relies on a set of triggers to
populate the product’s audit tables. These tables are all prefixed with ″H_″ and
otherwise generally share the same name as the operational table it stores audit
information for, with a few exceptions due to table name length restrictions.
With each add or update, the triggers write a historical record of the record
updated or added to the audit tables for the operational tables affected during the
transaction. As such, the triggers that come with the IBM InfoSphere Master Data
Management Server product allow the audit tables to store both historical and
current client information. A record in a audit or history table is considered current
when the HIST_END_DATE has no value. In other words, the historical record has
not yet been ended.
Note: If the triggers shipped with the IBM InfoSphere Master Data Management
Server product are modified or dropped, there can a be significant impact on both
history inquiry functions and the retrieval of the transaction audit log.
IBM InfoSphere Master Data Management Server provides two sets of triggers
with the database installation:
v A set of compound triggers—CreateTriggers_compound.sql
v A set of simple triggers—CreateTriggers_simple.sql
If the compound triggers are installed, each of the operational tables within the
IBM InfoSphere Master Data Management Server product database has two active
triggers.
The active triggers work with the IBM InfoSphere Master Data Management Server
operational tables-all non-code tables in the database; for example, the CONTACT
table is an operational table, but CDLANGTP is not. A number of admin services
tables also include related history tables and triggers. Any insertion or update from
the table activates one of the triggers. This trigger then populates the current
image of the business object to the corresponding audit table as a new record. Each
audit record has a HIST_ACTION_CODE column that shows the type of trigger
Chapter 17. Retrieving audit history

215

Licensed Materials – Property of IBM

that was activated to cause the audit record to be created—either a ″I″ value for
insert, or ″U″ value for update. Each audit record also populates a
HIST_CREATE_DT, which stores the actual date/time of the trigger activation.
The audit records also contain a HIST_END_DT column, which is populated
depending on the trigger type. For an insert, HIST_END_DT is simply set as
NULL. For an update, the new audit record has the HIST_END_DT set to NULL,
and the update trigger finds the last audit image of the same operational record
and sets HIST_END_DT to the current trigger activation time, subtracting one
microsecond. Subtracting one microsecond ensures that the timeline of the audit
records are synchronized.
IBM InfoSphere Master Data Management Server uses these audit records to
compare how a business object has changed between two points in time. It can
also retrieve a specific image of the business object for a given point in the past.
If simple triggers are installed, each of the operational tables within the IBM
InfoSphere Master Data Management Server product database has only one trigger
for update actions. A number of admin services tables also have related history
tables and triggers included. When new records are inserted into any operational
table, no audit histories are recorded. When records are updated, the update
trigger is activated and audit records are created. The HIST_CREATE_DT column
is populated by the LAST_UPDATE_DT column of the operational record. The
LAST_UPDATE_DT is retrieved from the previous image of the updating
operational record. The new image of the LAST_UPDATE_DT in the operational
record is set as the HIST_END_DT and 1 microsecond is subtracted from the
HIST_END_DT to ensure the history timeline is synchronized.
Optionally, delete triggers may be installed into IBM InfoSphere Master Data
Management Server product database. The scripts to install either simple delete
triggers and one for compound delete triggers are available with the database
installation scripts. Installing the delete triggers is optional and must be run
manually. Once the delete triggers are installed, all delete actions are recorded in
the audit tables.

216

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 18. Retrieving historical information for party or
contract images within a range of dates
Historical queries show how data has changed over a defined period of time.
More specifically, Point In Time (PIT) history is retrieved for each change that has
occurred to a set, of predefined business objects, also known as view drivers,
within a particular date range.
In this section, you will learn:
“Configuring view instances and view drivers”
“History inquiry date range images transactions” on page 218
“Developer example” on page 218
“Code interactions” on page 222
“Configuring transaction logging to function with history inquiry date range
images” on page 223

Configuring view instances and view drivers
Date range images allows you to see what the client file looked like at particular
points in time, and to view certain types of changes, the object-level drivers that
trigger the creation of an image, that have occurred to the client file between two
given dates.
A view instance is a set of drivers that may be configured for use with one of the
above mentioned inquiry transactions. A driver is a business object. In order to
effectively configure and use a view instance, you must ensure that only supported
drivers are used to create the instance, and that an appropriate view instance is
supplied with the images transactions.
Any number of view instance configurations may be created. The supported
drivers supplied with InfoSphere MDM Server are listed for each transaction
below:
Table 33. Available supported drivers
Transaction

Supported drivers

getImagesByFSParty

ContractPartyRole

getImagesByContract

ContractAlert, ContractComponent,
ContractRelationship,
ContractPartyRoleIdentifier,
ContractPartyRoleSituation,
ContractRoleLocation,
ContractPartyRole

getImagesByParty

Alert, IncomeSource, Organization,
OrganizationName, PartyAddress,
PartyContactMethod,
PartyIdentification, PartyRelationship,
Person, PersonName, Suspect

217

Licensed Materials – Property of IBM

If an Alert or Suspect driver is triggered, these specific objects are not returned as
part of the out-of-the-box getParty.

History inquiry date range images transactions
v getImagesByFSParty
v getImagesByContract
v getImagesByParty

Developer example
This feature is accessible to the end user via the InfoSphere MDM Server XML
interface. As such, an XML request/response structure has been defined.
See also:
“Sample request”
“Sample response” on page 219

Sample request

10015

DWL Customer
100
07-07-2002 10:00:00
66
Integration
Product Development
DWL Inc.
North America
1234567890
Integration001
XML Tester
2003-04-01
2005-11-15
007008009
DWL Customer
001002003004005
1
DWL Customer Team

getImagesByParty
TCRMImageRequestBObj

11
partyhistory

PartyId
690105640627887901
1

Attribute description

218

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v TAILTransactionLogInfo:Value may be Y/N. If not included default is that no
transaction log information is returned. In order to use this flag, the Transaction
Logging feature for all transactions relating to the configured view drivers
transactions must be turned ON.
v ImageInstanceType:Value from the viewinstance table - the specific image
configuration type code.
v ImageInstanceValue:Value from the viewinstance table - the specific image
configuration type name; for example, FullParty.
v InquiryRequestType:The type of inquiry parameter being used to conduct this
inquiry transaction; for example, use partyId when retrieving historical images
of a party.
v InquiryRequestValue:The actual value of the inquiry parameter; for example,
the partyId or contractId.
v ImageInquiryLevel:The inquiry level requested forservices invoked to provide
the response images. As each image response is the result of a Point In Time
getParty, getFSParty, or getContract, history inquiry transaction, the user may
specify the level of detail that they would like to see in the image. See the IBM
InfoSphere Master Data Management Server Transaction Reference Guide for inquiry
level information for these transaction.

Sample response
Images are returned in a first in, first out order (FIFO). The first instance of an
image without affiliated transaction logging information is provided to show what
the record looked like directly before the first change was made to it within the
requested date range, specified in the DWLControl as the inquireFromDate and
inquireToDate.

SUCCESS
83980

XML Tester
Integration001
DWL Inc.

Integration Environment

66
North America
2003-04-01
2005-11-15
Product Development
100
DWL Customer
07-07-2002 10:00:00
007008009
1234567890
DWL Customer Team

getImagesByParty

SUCCESS

1012

Chapter 18. Retrieving historical information for party or contract images within a range of dates

219

Licensed Materials – Property of IBM
N
4
Medium
1
Client
1
Active
1
14.4K Baud
N
2003-08-11 15:48:59.033
Party Way
Y
265106063133929501
2003-08-11 15:48:59.295
460106063133900301
cusadmin
P
100
English
N
1
Annually
2
Passport
1988-07-23 00:00:00.0
1
Afghanistan
1
Afghanistan
M
3
College
2
Single
2
2003-08-11 15:48:59.3
460106063133900301
cusadmin
265106063133929501
N

1010

2005-08-11 23:59:59.0

877106063133931201
482000001
2
Active
1
SSN
265106063133929501

2003-08-11 15:48:59.312

460106063133900301

cusadmin

2000-08-11 00:00:00.0

1013
Party
Way
cusadmin
2003-08-11 15:48:59.361
1
Legal
336106063133936101

2003-08-11 15:48:59.361

460106063133900301
cusadmin
265106063133929501
Mr

220

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
14
Mr.
2002-05-02 00:00:00.0
PARTY
WAY

76
addContract
XML Tester
Integration001
DWL Inc.
2003-06-22 18:11:19.369
North America
Product Development
66
07-07-2002 10:00:00
100
cusadmin
007008009
12345678901234
DWL Customer Team

1012
N
4
Medium
1
Client
1
Active
1
14.4K Baud
N
2003-08-10 15:48:59.033
Party Way
Y
265106063133929501
2003-08-10 15:48:59.295
12345678901234
cusadmin
P
100
English
N
1
Annually
2
Passport
1988-07-23 00:00:00.0
1
Afghanistan
1
Afghanistan
M
3
College
2
Single
2
2003-08-11 15:48:59.3
12345678901234
cusadmin
265106063133929501
N

1010

2005-08-11 23:59:59.0

877106063133931201
482000001
2
Active
1
SSN

Chapter 18. Retrieving historical information for party or contract images within a range of dates

221

Licensed Materials – Property of IBM
265106063133929501

2003-08-11 15:48:59.312

12345678901234

cusadmin

2000-08-11 00:00:00.0

1013
Party
Way
cusadmin
2003-08-11 15:48:59.361
1
Legal
336106063133936101

2003-08-11 15:48:59.361

12345678901234
cusadmin
265106063133929501
Mr
14
Mr.
2002-05-02 00:00:00.0
PARTY
WAY

1013
Party
Jones
cusadmin
2003-08-11 15:48:59.361
8
Previous
2296394519877212

2003-08-10 15:48:59.361

12345678901234
cusadmin
265106063133929501
Mr
14
Mr.
2002-05-02 00:00:00.0
PARTY
JONES

Code interactions
Code interactions for History Inquiry Date Range Images include errors.
See also:
“Possible errors”

Possible errors
Errors that may be thrown by History Inquiry Date Range Images include:
v Component—TCRMHistoryComponent

222

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Method—getImagesByParty, getImagesByFSParty, getImagesByContract
Errors that this method throws include:
Party does not exist
To date must be after from date
From date must be supplied
Invalid date format
No records found
Component—PartyHistoryComponent or ContractHistoryComponent or
AlertHistoryComponent
v Methods—all
This methods throws errors for the existing history methods; however, new
component numbers will be surfaced.
v
v
v
v
v
v

Configuring transaction logging to function with history inquiry date
range images
To retrieve system information about what triggered a change, transaction logging
must be configured to use Configuration and Management components.
For each driver object you are configuring, ensure that the relevant internal and
external transactions have been enabled for logging.
See also:
“Packaging and deployment”

Packaging and deployment
Class

Project

Package

Physical Unit for Deployment
(jar, ejb jar, ear)

TCRMHistoryController

ProductServices

com.dwl.tcrm.history

ProductServices.jar

TCRMHistoryComponent

ProductServices

com.dwl.tcrm.history

ProductServices.jar

TCRMImageListBObj

ProductServices

com.dwl.tcrm.history

ProductServices.jar

TCRMImageBObj

ProductServices

com.dwl.tcrm.history

ProductServices.jar

TCRMImageRequestBObj

ProductServices

com.dwl.tcrm.history

ProductServices.jar

TCRMImageRequestParamBObj

ProductServices

com.dwl.tcrm.history

ProductServices.jar

TCRMPartyHistoryComponent

Party

com.dwl.tcrm.party.component

Party.jar (ejb jar)

TCRMAlertHistoryComponent

DataServices

com.dwl.tcrm.dataservices.
component

DataServices.jar (ejb jar)

TCRMContractHistoryComponent

FinancialServices

com.dwl.tcrm.financial. component

Financial.jar (ejb jar)

Chapter 18. Retrieving historical information for party or contract images within a range of dates

223

Licensed Materials – Property of IBM

224

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 19. Storing and retrieving the Transaction Audit
Information Log
The Transaction Audit Information Log (TAIL) module provides services for the
storage and retrieval of transaction log information for the InfoSphere MDM Server
product.
You can log the following:
v External/business transactions
v Associated internal transactions
v Key elements associated with the external transactions, such as the party ID
v Key elements associated with the internal transactions, such as the party ID
v Successful transactions, failed transactions, or both
The Transaction Audit Information Log feature has mainly database-driven
configuration options. TAIL may be configured to log any persistent or
inquiry-based business transactions, as well as some or all of their associated
internal transactions. Both successful and failed transactions can be logged. The
execution of search services may not be logged.
Transaction audit information can be logged to the database either synchronously,
as part of the transaction, or asynchronously.
An InfoSphere MDM Server transaction can consist of a number of internal
transactions (or actions) that are executed as a part of the larger external
transaction. For example, when TAIL logs an external transaction, also called a
business transaction, it can be configured to also log all, some, or none of its
internal transactions. When an audit transaction is retrieved, any of the internal
transactions that have been logged are also retrieved.
In this section, you will learn:
“Understanding transaction audit information log information”
“Configuring transaction audit information logs” on page 226
“Understanding transaction audit information log data tables” on page 227
“Understanding transaction audit information logging” on page 229
“Retrieving transaction audit information log information” on page 229
“Understanding getTransactionLog transactions” on page 230
“Understanding inquiry levels” on page 230
“Setting up new transactions in the transaction audit information log” on page
233
“Understanding getTransactionLog elements and attributes” on page 236

Understanding transaction audit information log information
For each given business transaction, several pieces of information can be logged in
the transaction audit information log.
The following information can be logged to the TAIL database tables for a business
transaction:
© Copyright IBM Corp. 1996, 2009

225

Licensed Materials – Property of IBM

v TRANSACTIONLOG table—Logs an entry for the external/business transaction
type being executed. It also logs items from the DWLControl object from the
initial transaction request. If a business transaction is configured to be logged,
there will always be a record created in this table.
v TRANSACTIONLOGGER table—Logs an entry for the transactions executed that
resulted in failure.
v INTERNALLOG table—Logs all of the internal transactions executed within the
context of the external transaction. For example, an addIncomeSource transaction
may be an internal transaction to an external addPerson transaction. Only the
internal transactions that have been configured to be logged will have entries
created in this table for a given business transaction.
v INTERNALLOGTXNKEY table—Creates entries for each transaction key and its
corresponding values for each internal transaction executed. The
INTERNALTXNKEY database table is preconfigured/prepopulated with
information on which keys are logged for a particular internal transaction. These
keys are typically top-level specified elements (in the V_ELEMENT table) of the
business object (see the V_GROUP table) for a particular transaction. For
example, for an IncomeSource business object, the PartyId will be logged along
with its actual value (element_value).
v EXTERNALLOGTXNKEY table—Creates entries for each transaction key and its
corresponding value for a particular external transaction executed. The
EXTERNALTXNKEY database table is similar to the INTERNALTXNKEY table
in that it is preconfigured and prepopulated with information on which keys are
logged for a particular transaction. Internal transaction information is stored in
the INTERNALTXNKEY table, and external transaction information is stored in
the EXTERNALTXNKEY table. For example, for an addPerson transaction the
PartyId and PersonPartyId from the return object PersonBObj are logged along
with its actual value (element_value).

Configuring transaction audit information logs
You can perform a number of transaction audit information log configuration tasks.
See also:
“To turn TAIL on or off globally”
“To configure TAIL logging to use in synchronous or asynchronous mode” on
page 227
“To turn TAIL on for redundant updates” on page 227
“To turn TAIL logging on or off for a particular external transaction” on page
227
“To turn TAIL logging on or off for a particular internal transaction” on page
227

To turn TAIL on or off globally
v To turn TAIL logging on, in the Configuration and Management component, set
/IBM/DWLCommonServices/TAIL/enabled to true.
v To turn TAIL logging off, in the Configuration and Management component, set
/IBM/DWLCommonServices/TAIL/enabled to false. TAIL logging is turned off by
default.

226

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

To configure TAIL logging to use in synchronous or
asynchronous mode
v To configure TAIL logging to use asynchronous mode, in the Configuration and
Management component, set /IBM/DWLCommonServices/TAIL/Asynchronous/
enabled to true.
v To configure TAIL logging to use synchronous mode, in the Configuration and
Management component, set /IBM/DWLCommonServices/TAIL/Asynchronous/
enabled to false. By default TAIL logging uses synchronous mode.

To turn TAIL on for redundant updates
v To turn TAIL logging on, in the Configuration and Management component, set
/IBM/DWLCommonServices/TAIL/RedundantUpdate/enabled to true.
v To turn TAIL logging off, in the Configuration and Management component, set
/IBM/DWLCommonServices/TAIL/RedundantUpdate/enabled to false. This is the
default setting, which means by default TAIL logs are not created for update
transactions that do a redundant update.

To turn TAIL logging on or off for a particular external
transaction
v To turn TAIL logging on for a particular external transaction, in the
CDBUSINESSTXTP table set the value in the TX_LOG_IND column for the
particular component to Y.
v To turn TAIL logging on for a particular external transaction, in the
CDBUSINESSTXTP table set the value in the TX_LOG_IND column for the
particular component to N.

To turn TAIL logging on or off for a particular internal
transaction
v To turn TAIL logging on for a particular internal transaction, in the
BUSINTERNALTXN table set the value in the INT_TX_LOG_IND column for the
particular component to Y.
v To turn TAIL logging on for a particular internal transaction, in the
BUSINTERNALTXN table set the value in the INT_TX_LOG_IND column for the
particular component to N.

Understanding transaction audit information log data tables

Chapter 19. Storing and retrieving the Transaction Audit Information Log

227

Licensed Materials – Property of IBM

The data tables with default values that must be deployed with the TAIL module
include:
v CDBUSINESSTXTP—This table holds the external, or callable, transaction code
types, names, and transaction log indicator required to configure a particular
transaction for logging by TAIL; the terms callable and external refer to
transactions that exist at the controller-level. Default data is supplied in this
table for use with InfoSphere MDM Server. By default, all external transactions
are logged if /IBM/DWLCommonServices/TAIL/enabled is set “true” in the
Configuration and Management component.
v CDINTERNALTXNTP—This table holds all of the internal transaction code
types and names so that internal transactions may be logged during a particular
external transaction-the term internal refers to transactions or methods that exist
at the component-level.
v BUSINTERNALTXN—This table holds values for external transactions and their
internal transactions, as well as an indicator for whether each internal
transaction within a external transaction is to be logged. See Chapter 34, “Using
the Configuration and Management components,” on page 405 for more
information on configuring these options. By default, all internal transactions are
logged when /IBM/DWLCommonServices/TAIL/enabled is set to false for
Transaction Logging in the Configuration and Management component.
v INTERNALTXNKEY—This table holds all values necessary for a particular
internal transaction to log particular keys that in turn may be used for log
retrieval. All of the following fields will be configured as keys (element_name)
for a business object: PartyId, ContractId, ContractIdPK, PersonPartyId,
OrganizationPartyId. If the business object does not contain any of the
aforementioned fields, then only the primary key of the business object is stored
as a key.
EXTERNALTXNKEY —This table holds all the values necessary for a particular
external transaction to log its corresponding transaction keys that in turn may be
used for log retrieval.
v V_GROUP—This table contains metadata about all of the business objects.

v V_ELEMENT—This table stores information about all elements of a business
object.

228

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Understanding transaction audit information logging
TAIL logging, as a global setting, can be turned on or off using the Configuration
and Management components.
Note: For more information, see Chapter 34, “Using the Configuration and
Management components,” on page 405.
Logging to TAIL occurs seamlessly within InfoSphere MDM Server, as long as the
business transaction has been configured for logging.
TAIL can also be configured to log particular external transaction alone and for
some or all of its internal transactions. For example, it can be used to flag the
transaction log indicator for a particular transaction listed in the
CDBUSINESSTXTP table to Y. This mainly impacts the CDBUSINESSTXTP and
BUSINTERNALTXN database tables in InfoSphere MDM Server. You can turn
logging on and off at the transaction level, using the System Maintenance
Transaction Audit Log screen.
For more information, see the IBM InfoSphere Master Data Management Server System
Management Guide.

Retrieving transaction audit information log information
The getTransactionLog transaction allows InfoSphere MDM Server common
components to use TAIL. This transaction can be used for TCRM applications or
DWLAdminService applications.
This transaction works the same way as the deprecated getTAIL transaction when
used for TCRM application (InfoSphere MDM Server domains),, however, the
request/response wrappers are different; the transaction getTAIL uses
TCRMTAILRequestBObj and TCRMTAILResponseBObj, while getTransactionLog uses
DWLTAILRequestBObj and DWLTAILResponseBObj. The getTransactionLog transaction
uses an external rule to retrieve additional detail.
To keep backward compatibility, the deprecated getTAIL transaction in
ITCRMTAILController can still be used. It takes TCRMTAILRequestBObj as input and
the TCRMResponse it returns contains TCRMTAILResponseBObj.
The transaction getTransactionLog in IDWLTAILController takes
DWLTAILRequestBObj as input and the DWLResponse it returns contains
DWLTAILResponseBObj.
TAIL information can be retrieved through the getTransactionLog request
transaction. The more parameters you add to a TAIL request, the more specific the
results of the request will be, in other words, the more parameters supplied, the
narrower the result set is. For example, if a PartyId and a business transaction
type are specified, the transaction logs returned in the result set area are only those
that satisfy both conditions.

Chapter 19. Storing and retrieving the Transaction Audit Information Log

229

Licensed Materials – Property of IBM

Understanding getTransactionLog transactions
The following is a high-level sequence diagram of the getTransactionLog
transaction.

Understanding inquiry levels
TAIL inquiry levels determine the type and extent of information that is returned.
There are two different levels of inquiry that may be specified when executing a
getTransactionLog transaction:
v Level 0 retrieves only transaction log objects and external log transaction key
objects from TAIL database tables.
v Level 1 Level 0 details plus the internal log and internal log transaction key
objects from the TAIL database tables.
Most InfoSphere MDM Server inquiry transactions may be executed against the
audit database tables to retrieve historical data for a particular point in time in the
past. TAIL reuses this history inquiry logic when retrieving additional information
with its transaction log, for example, in a Level 1 getTransactionLog request. In
order to bring back this information, a special additional details indicator must set.
The additional details indicator can be set to ″Y″ or ″N″ to include the point in
time history when retrieving the log. Retrieving additional details in
getTransactionLog is implemented in the external rule class
com.dwl.tcrm.externalrule.TAILAdditionalDetail. AdditionalDetailIndicator is
not applicable to DWLAdminService by default.

230

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The point in time history retrieved for the transaction logs include either the
results of a InfoSphere MDM Server getFSParty or a getContract transaction (level
3). These transactions are executed by using either the PartyId, PersonPartyId,
OrganizationPartyId, ContractIdPK, or ContractId taken from the element values of
the external log transaction key object for external transactions and internal log
transaction key object. In addition, the history inquiry is executed for the point in
time at which the original transaction was logged-the transaction log created date.
To clarify, the date used as the inquireAsOfDate (see Chapter 17, “Retrieving audit
history,” on page 211 for a full explanation) is the created date_created_dt of the
transaction log object. One minute is added to this time, because the history
inquiry functionality ignores seconds values. In addition, the time at which for the
history inquiry transaction gets taken from the date at which the transaction log
was created. See the IBM InfoSphere Master Data Management Server Transaction
Reference Guide for more information on the getFSParty and getContract
transactions.
The transaction runs to retrieve these additional details depends on the transaction
keys indicated for that transaction in the pre-populated EXTERNALTXNKEY and
INTERNALTXNKEY database table for external and internal transactions,
respectively. Keys include PartyId, ContractId, PersonPartyId, OrganizationPartyId,
ContractIdPK for the business objects of a transaction. If the key is a ContractId or
ContractIdPK, a getContract transaction is executed, otherwise, a getFSParty is
executed if one of the party keys exists.
See also:
“Sample: Transaction audit information log requests”

Sample: Transaction audit information log requests
Below is a sample getTransactionLog request.

10015

cusadmin
100
07-07-2002 10:00:00
66
Integration Environment
Product Development
DWL Inc.
North America
1234567890
Integration001
XML Tester
2002-11-05
2002-11-06
007008009
WebSphere Customer Center
001002003004005
1
Superuser

getTAIL
TCRMTAILRequestBObj

1
7
PartyAddress

Chapter 19. Storing and retrieving the Transaction Audit Information Log

231

Licensed Materials – Property of IBM
Trainee

PartyId
2751033184712380

TAIL Example – getTransactionLog Request for tcrm application

552424999

cusadmin
100
07-07-2002 10:00:00
77
Integration Environment
Product Development
DWL Inc.
North America
1234567890
Integration001
XML Tester
2006-04-27 23:55:38.984

007008009
Tail test
DWL QA
customer
001002003004005
1

getTransactionLog
DWLTAILRequestBObj

addContract

ContractIdPK
3603601

TAIL example – getTransactionLog Request for
DWLAdminService application

50097

cusadmin
100
66
Integration Environment
Product Development
DWL Inc.
North America
1234567890
Integration001

232

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
XML Tester
2002-01-01
2015-01-01
007008009
customer
001002003004005
1
SuperUser

getTransaction
DWLTAILRequestBObj

1
377
cusadmin

tp_cd
1000000

Setting up new transactions in the transaction audit information log
To set up a new transaction in the InfoSphere MDM Server for transaction logging,
several tables must be updated.
See also:
“To
“To
“To
“To
“To

update
update
update
update
update

the
the
the
the
the

CDBUSINESSTXTP table”
CDINTERNALTXNTP table” on page 234
BUSINTERNALTXN table” on page 235
INTERNALTXNKEY table” on page 235
EXTERNALTXNKEY table” on page 236

To update the CDBUSINESSTXTP table
Enter values for the new transaction in the CDBUSINESSTXTP table.
The value of the tx_log_ind field in this table governs whether the transaction is
logged or not. This table is also used for security purposes, however it is discussed
only in the context of transaction logging in this section.
BUSINESS_TX_TP_CD
the numeric code for the transaction name. IBM InfoSphere Master Data
Management Server reserves all numeric codes up to 1,000,000,000.
NAME
transaction name. This must be identical to the method name on the
controller class/bean
DESCRIPTION
transaction description.
EXPIRY_DT
the date at which the transaction expires.

Chapter 19. Storing and retrieving the Transaction Audit Information Log

233

Licensed Materials – Property of IBM

LAST_UPDATE_DT
the date at which this record was last modified.
TX_LOG_IND
configured to Y/N for logging the external (controller-level) transaction to
the transaction audit/information log. Y- means log the transaction, Nmeans do not log the transaction
TX_OBJECT_TP
transaction object type-whether the transaction is an inquiry (I), persistent
(P) or search (S) transaction is indicated here.
If the transaction is not registered in this table, it fails, with a message indicating
that the transaction is not registered.
For example:

FATAL

106

Parser DWLTransaction Failed
READERR

0
4928
0

com.dwl.base.requestHandler.exception.RequestParserException: transaction
getAlert is not registered

To update the CDINTERNALTXNTP table
Enter records for all potential internal, component-level transactions in the
CDINTERNALTXNTP table.
INTERNAL_BUS_TX_TP
The numeric code for the internal transaction. IBM InfoSphere Master Data
Management Server reserves all numeric codes up to 1,000,000,000.
NAME
Internal transaction name This must be identical to the method name on
the component class/bean
DESCRIPTION
Internal transaction description
EXPIRY_DT
The date at which the transaction expires
LAST_UPDATE_DT
The date at which this record was last modified
COMPONENT_TYPE_ID
It references to COMPONENT_TYPE_ID in COMPONENTTYPE table.

234

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

To update the BUSINTERNALTXN table
Enter records for all potential combinations of external/internal transaction
execution in the BUSINTERNALTXN table. For example, an addContract
transaction may contain an internal transaction for addOrganizationName.
Similarly, an addOrganization may contain an internal transaction for
addOrganizationName. The mapping of external to internal transactions is stored
in this table. Each external transaction has its own logging configuration for its
internal transactions, also stored in this table.
BUS_INTERN_TXN_ID
The numeric code for the external/internal transaction configuration
record. IBM InfoSphere Master Data Management Server reserves all
numeric codes up to 1,000,000,000.
BUSINESS_TX_TP_CD
The numeric code for the transaction name. IBM InfoSphere Master Data
Management Server reserves all numeric codes up to 1,000,000,000.
INTERNAL_BUS_TX_TP
The numeric code for the internal transaction. IBM InfoSphere Master Data
Management Server reserves all numeric codes up to 1,000,000,000.
INT_TX_LOG_IND
Configured to Y/N for logging the internal (component-level) transaction
to the transaction audit/information log. Y means log the internal
transaction, N means do not log the internal transaction.
LAST_UPDATE_DT
The date at which this record was last modified.

To update the INTERNALTXNKEY table
Enter the records into the INTERNALTXNKEY table to log the appropriate
business object keys to be logged when the internal transaction is executed. By
default, keys that render additional details from InfoSphere MDM Server include
only the following keys: PartyId, ContractId, ContractIdPK, PersonPartyId,
OrganizationPartyId.
The primary key of each business object is also stored for the internal transaction.
The entries in this table depend on values existing in the V_GROUP and
V_ELEMENT tables. Therefore, if any transaction contains a new business object,
the group and the elements for this new business object must be registered in those
tables accordingly before the INTERNALTXNKEY table may be populated.
INTERN_TX_KEY_ID
The numeric code for the key configuration record. IBM InfoSphere Master
Data Management Server reserves all numeric codes up to 1,000,000,000.
INTERNAL_BUS_TX_TP
The numeric code for the internal transaction. IBM InfoSphere Master Data
Management Server reserves all numeric codes up to 1,000,000,000.
APPLICATION
Application name (TCRM)
GROUP_NAME
Business term for the type of business object registered in the v_group
table.

Chapter 19. Storing and retrieving the Transaction Audit Information Log

235

Licensed Materials – Property of IBM

ELEMENT_NAME
The name of the attribute or key that will have its value stored during
transaction logging - this must match the business object field name.
LAST_UPDATE_USER
The ID of the last user to update this record
LAST_UPDATE_DT
The date when this record was last modified

To update the EXTERNALTXNKEY table
Enter the records into the EXTERNALTXNKEY table to log the appropriate
business object’s Transaction keys to be logged when the external transaction is
executed. By default, keys that render additional details from InfoSphere MDM
Server include only the following keys: PartyId, ContractId, ContractIdPK,
PersonPartyId, OrganizationPartyId.
The primary key of each business object is also stored for the external transaction.
The entries in this table depend on values existing in the V_GROUP and
V_ELEMENT tables. Therefore, if any transaction contains a new business object,
the group and the elements for this new business object must be registered in those
tables accordingly before the EXTERNALTXNKEY table may be populated.
EXTERN_TX_KEY_ID
The numeric code for the key configuration record. InfoSphere MDM
Server reserves all numeric codes up to 1,000,000,000.
BUSINESS_TX_TP_CD
The numeric code for the external transaction. InfoSphere MDM Server
reserves all numeric codes up to 1,000,000,000.
APPLICATION
Application name (TCRM, DWLADMINSERVICE).
GROUP_NAME
Business term for the type of business object registered in the V_GROUP
table.
ELEMENT_NAME
The name of the attribute or key that will have its value stored during
transaction logging. This must match the business object field name
defined in the V_ELEMENT table.
LAST_UPDATE_USER
The ID of the last user to update this record.
LAST_UPDATE_DT
The date when this record was last modified.

Understanding getTransactionLog elements and attributes
The following describes the elements and attributes used in the previous example:
inquireFromDate
The start date, or the date from which you retrieve the transaction log.
This mandatory field is supplied to provide the day at which the user
wants to start retrieving the transaction log information. If only this
parameter is supplied, the transaction log is retrieved only for

236

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

00:00:00.0.000 to 23:59:59.0.000. If it is the current day, transactions will be
retrieved up to the current time that day.
inquireToDate
The end date, or the date to which you retrieve your log. This is not a
mandatory field.
Regarding entering specific times with dates
Time portions are accepted but not required for the dates. The date and
time must be of a format configured in the /IBM/DWLCommonServices/
DateValidation/dateFormat configuration. If a time is not entered for an
inquireToDate, the default time is 23:59:59:0.000. If a time is not entered for
an inquireFromDate, the time is defaulted to 0:00:00:00. Times that are
entered through the XML request are accurate to the minute, to allow for
the way that the database InfoSphere MDM Server is using-either DB2 or
Oracle-handles time.
Note: If you enter an inquireFromDate only, you retrieve transactions for
that day only. Any time entered is ignored and the log is retrieved for that
day between 0:00:00.0 am and 23:59:59.0 pm.
TCRMTxType
The name of the transaction-for example, getTransactionLog
TCRMTxObject
The Name Of The Transactional Object-for example, DWLTAILRequestBObj
DWLTxType (when use for DWLAdminService)
The name of the transaction—for example, getTransactionLog
DWLTxObject (when use for DWLAdminService)
The name of the transactional object—for example, DWLTAILRequestBObj
AdditionalDetailIndicator
Either Y or N. This tag indicates whether additional information should be
returned from InfoSphere MDM Server as a part of the transaction log. The
AdditionalDetailIndicator is used only by InfoSphere MDM Server and has
no meaning to the TAIL Service itself. For this release, only the results of a
getFSParty or getContract are retrieved-inquiry levels for these audit
transactions are defaulted to 3 for both. For example, if a PartyId or
ContractId or both are placed into the TAILStackBObj as a key for the
transaction being logged, these keys are used to spawn a getFSParty or
getContract transaction.
BusinessTransactionValue
The transaction name filter. Results may be filtered by either name or type
code; if both are entered they must match.
BusinessTransactionType
The transaction type code filter. Results may be filtered by either name or
type code; if both are entered they must match.
ClientSystemName
An alphanumeric field to filter the returned TAIL objects by a specific
client’s system name which have issued the subject InfoSphere MDM
Server transactions
ClientTransactionName
An alphanumeric field to filter the returned TAIL objects by a specific
client’s transaction name

Chapter 19. Storing and retrieving the Transaction Audit Information Log

237

Licensed Materials – Property of IBM

ExternalCorrelationId
An alphanumeric field to filter the returned TAIL objects by a specific
external correlation identifier. ExternalCorrelationId is a field used for
transaction traceability, that is, it is used to identify all InfoSphere MDM
Server transactions which have been executed within the scope of a larger
business process driven by another enterprise application. The enterprise
applications can specify their own ExternalCorrelationId, via DWLControl
in single transactions and via GlobalFields in Composite Transactions.
ExternalCorrelationId is stored in TAIL tables for later audit inquiries.
InquiryLevel
Valid values are 0 or 1.
v An inquiry level of 0: Retrieves the TAILTransactionLogBObjs (data
from the TransactionLog database table) and
TAILExternalLogTxnKeyBObjs (data from the ExternalLogTxnKey table).
A sample request and response for getTransactionLog inquiry level 0
may be found in this chapter.
v An inquiry level of 1: Retrieves the TAILTransactionLogBObjs and its
associated Bobjs. For example, TAILExternalLogTxnKeyBObjs,
TAILInternalLogBObjs, TAILInternalLogTxnKeyBObjs, and a
point-in-time history response for either a getParty or getContract
transaction, depending on whether a partyId or contractId had been
logged for the transaction now being retrieved. A sample request and
response for getTAIL inquiry level 1 may be found in this chapter.
UserID
This value entered for this filter is based on the value of the requester
name in DWLControl object and allows for the filtering of transaction logs
for the specific user that executed them.
TAILRequestParamBObj
Houses the request type and value required as filters for the TAIL retrieval.
RequestType
The element name that will be used as a filter parameter. PartyId,
ContractId and ContractIdPK are examples of these. Other allowable
values are pre-populated in the internalTxnKey table of the TAIL database.
RequestValue
Specifies the actual PartyId or ContractId value itself, for example,
1234567890.

238

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 20. Running parallel tasks using the Concurrent
Execution Infrastructure (CEI)
The Concurrent Execution Infrastructure, or CEI, provides the ability to perform
party or contract searches for operations that execute concurrently within the
managed environment of an EJB container.
The CEI can be used for other operations that are independent and suited to be
performed in parallel.
There are no IBM InfoSphere Master Data Management Server transactions related
to CEI. It is used to support the implementation of transactions.
CEI supports two implementations: queue-based and sequential.
In this section, you will learn:
“Understanding the CEI design”
“Learning the CEI API interfaces” on page 241
“Understanding the CEI queue-based implementation” on page 242
“Understanding the CEI sequential implementation” on page 244
“Selecting queue-based versus sequential CEI implementation” on page 245
“Understanding CEI workflow” on page 245
“Understanding CEI models” on page 247
“Configuring the CEI” on page 249

Understanding the CEI design
The CEI supports executing attach methods in parallel in the EJB container by
refactoring the attach methods into classes that implement the Work interface and
using them to schedule work with the CEI WorkManager. There is one work class
for each attach method.
The following diagram describes this relationship:

239

Licensed Materials – Property of IBM

The following diagram represents the interfaces and classes that make up the CEI
API:

240

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Learning the CEI API interfaces
The CEI API consists of several components, or interfaces: WorkManager, Work,
WorkItem and RemoteWorkItem, WorkEvent, and WorkException,
WorkCompletedException and WorkRejectedException.
v WorkManager—WorkManager is the main interface for scheduling and waiting
on work completion. The client creates work instances and schedules them one
by one by calling the WorkManager’s schedule method.
The WorkManager can, although it is not required to, begin the work
immediately after it has been scheduled. The client need not make any
additional calls for the work to start. In response to scheduling work, a client
receives an instance of a work item.
After the client has completed scheduling all work instances, it can wait for
completion either as a whole or on an individual work instance basis, by calling
the waitForAll or waitForAny methods, respectively. When waiting for work
completion, the client can either set a timeout or it can wait indefinitely.
v Work—Work is the contract that must be implemented by client specific work
classes. The work class must expose a run method, which is enforced by the fact
that Work extends Runnable.
All client specific work classes must extend the abstract class
com.dwl.base.work.WorkBase and provide DWLControl and DWLStatus objects
using the setter method. WorkManager will use the transaction ID from the
DWLControl object to correlate concurrent work.
v WorkItem—Upon scheduling work, the WorkManager returns instances of
classes that implement WorkItem. This interface allows clients to check on the
status of work being executed by the container.
Chapter 20. Running parallel tasks using the Concurrent Execution Infrastructure (CEI)

241

Licensed Materials – Property of IBM

v WorkEvent—The WorkEvent interface only provides an enumeration of possible
values of the work status.
v WorkException, WorkCompletedException, and
WorkRejectedException—WorkException is the generic exception type thrown
by the classes of the concurrent execution infrastructure. More specific
exceptions are thrown when work cannot be started (WorkRejectedException) or
completes with an exception (WorkCompletedException).

Understanding the CEI queue-based implementation
The CEI supports a queue-based implementation. This implementation, as well as
the API, are interim solutions that offer a way to execute work concurrently in an
EJB container, while still remaining compliant with the J2EE specification.
The implementation uses message queues and the classes that support it are
presented in the following diagram:

242

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Queue-based implementation for CEI consists of several components:
QueuedWorkManagerBean, QueueWorkProcessorBean, WorkItemsCache,
QueuedWorkItem, and QueuedWork.
v QueuedWorkManagerBean—A session enterprise bean that implements a local
WorkManager interface.
The WorkManager schedules work by placing messages into the scheduled work
queue. It determines the completion of work by listening to the completed work
queue for the corresponding response messages. Listening is synchronous; that
is, the wait calls are blocked, unless a timeout is specified.
The QueuedWorkManagerBean needs to have intimate knowledge of the work
items is creates. Therefore it is dependent on the actual class that implements
WorkItem or QueuedWorkItem. Because the work instance will execute in
exactly the same EJB container as the work manager, the message placed in the
Chapter 20. Running parallel tasks using the Concurrent Execution Infrastructure (CEI)

243

Licensed Materials – Property of IBM

queue by the work manager only needs to contain enough information to allow
the work processor bean to relate it back to the work item in the work item
cache. This reduces the volume of data that travels through the queue, thus
improving performance. The WorkManager is also responsible for updating the
status of the work item.
WorkManager will use the transaction ID obtained from the DWLControl object
to correlate concurrent work submited by the same transaction. The DWLControl
object must be set on the Work instance using setter methods from the abstract
com.dwl.base.work.WorkBase class before placing Work in the queue.
v QueuedWorkProcessorBean—A message driven enterprise bean that is set to
listen to the scheduled work queue. Each message in this queue represents work
items scheduled by the work manager, which the queued work processor bean
identifies in the work items cache and executes.
Following the execution, a message is placed back into the completed work
queue using the message correlation ID to support the work manager in
matching results back to their corresponding work. Because the work instance
executes in the same EJB container in which it originates, there is no need for
the results to travel back through the queue. Only a token that identifies the
work item in the work items cache is required.
The WorkManager is also responsible for updating the status of the work item.
As the work manager also updates the status, access to the status field must be
synchronized.
v WorkItemsCache—There is one work item cache instance per EJB container and
it contains all work items currently scheduled by the work manager. This cache
is used jointly by the work manager and the work processor and access to it has
to consequently be synchronized.
v QueuedWorkItem—A plain Java class that encapsulates the state of work
submitted by a client. Its status property reflects the stage at which the work is
in its execution. In the case of this queue-based implementation, work items
always implement the WorkItem interface as work items and work instances
never leave the EJB Container.
v QueuedWork—Asn abstract class representing the work to be executed and it is
provided only as an example. Clients should provide their own class that
implements the Work interface, to avoid dependencies on the CEI
implementation classes.

Understanding the CEI sequential implementation
The CEI provides an alternative implementation which uses a sequential approach
to execute work. This approach is a fallback mechanism which helps debug Work
implementations. The choice between concurrent and sequential implementation is
configuration-driven.
The class diagram below shows the classes that are required to support an
implementation of the CEI API that launches the work instances sequentially:

244

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The SequentialWorkManagerBean plays both the roles of the work manager and
work processor. Schedule calls only create work item instances and the wait calls
use the collection of work items passed in to run the work instances one by one in
a loop.

Selecting queue-based versus sequential CEI implementation
When the CEI implements a queue-based versus sequential-based implementation,
there is only one direct dependency on the client. When obtaining the home of the
work manager bean, the client needs to do an explicit narrow to the class of the
bean by passing either QueuedWorkManagerLocalHome or
SequentialWorkManagerLocalHome to PortableRemoteObject.narrow.
To eliminate this dependency and to easily switch between concurrent and
sequential execution implementations, the client should use configuration
information to determine both the name of the home reference and the name of the
home class. Determine the local home and cast it to its base type, EJBLocalHome.
The local bean obtained through the create call should be cast to its base type,
WorkManager.

Understanding CEI workflow
The CEI workflow is threefold: scheduling work for processing, processing the
work, and waiting for and retrieving results of processed work.
Chapter 20. Running parallel tasks using the Concurrent Execution Infrastructure (CEI)

245

Licensed Materials – Property of IBM

v Schedule work for processing—This interaction happens for each work that the
client requires executed concurrently. The QueuedWork classifier role is played
by classes that represent the actual work to be processed. No further action is
required by the client to initiate the work. To check on the status of the work,
the client can use the work item returned by the work manager. Upon
scheduling, the status of the work can become either accepted or rejected. The
following flow diagram illustrates the schedule work for processing workflow:

v Processing work—This interaction takes place once for each individual work for
which there is a message in the scheduled work queue. The work processor
retrieves the message from the scheduled work queue, de-serializes the work
from it, and invokes its run method. It then serializes the work again and puts it
in a message in the completed work queue. The following flow diagram
illustrates the processing work workflow:

Multiple instances of the QueuedWorkProcessorBean take part in this interaction
simultaneously. The actual number of instances is determined by the
configuration of the EJB container’s message listener ports.
v Wait for and retrieve results of processed work—In this interaction, the client,
after scheduling all the work to be executed concurrently with the work
manager, waits until all the work is completed. The waitForAll call is blocking

246

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

and returns only when all work has completed. The work processor is
responsible for synchronizing on the completion of all work.

Understanding CEI models
The CEI supports two models: component and deployment
v CEI component model—In this model, several components support the CEI
with dependencies that exist among them, as described in the diagram that
follows. The client is only dependent on the CEI interfaces and is completely
separated from their implementation. This allows for the implementation to
change at a latter date without affecting the client.
The QueuedWorkManager interacts with both the ScheduledWork queue and the
CompletedWorkQueue directly. The QueuedWorkProcessor receives messages
form the ScheduledWork queue via the EJB container but places messages in the
CompletedWork queue directly.

Chapter 20. Running parallel tasks using the Concurrent Execution Infrastructure (CEI)

247

Licensed Materials – Property of IBM

v CEI deployment model—In this model, the CEI is deployed in every EJB
container where there is a client requiring it, as shown in the following diagram.
Each EJB container in clustered environments must be set up with its own pair
of ScheduledWork and CompletedWork to guarantee that the responses return to
the EJB container that produced the request message.

248

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The queues are set up as transient; that is, in case of failure, all scheduled items
are lost. For this reason clients should use the timeout to avoid deadlocks.
Most importantly, the listener port must be configured to allow for more than
one message driven bean instance to process messages simultaneously. The
larger this number, the higher the degree of concurrency, although a number that
is too large will produce trashing. Typically, the longer the average duration of
the work execution is, the higher the degree of concurrency.

Configuring the CEI
The CEI must be configured before you can use it. It cannot be extended and does
not require any special administration.
Before you configure the CEI, be familiar with the CEI components. The CEI is
delivered as part of the DWLCommonServices EJB module within the InfoSphere
MDM Server Enterprise Application. The components of the CEI are Enterprise
JavaBeans, Java classes, and message queues.
v Enterprise JavaBeans (EJBs)—The CEI consists of three EJBs:
– QueuedWorkManager—A stateless session bean used to schedule and
synchronize on the completion of concurrent jobs.
– QueuedWorkProcessor—A message driven bean used to concurrently execute
jobs.
– SequentialWorkManager—A stateless session bean used to execute jobs
sequentially while still exposing the same concurrent execution API.
Chapter 20. Running parallel tasks using the Concurrent Execution Infrastructure (CEI)

249

Licensed Materials – Property of IBM

v Java classes—The WorkManagerHelper class is provided as a more convenient
way to use the concurrent execution API. Although this class does not impose
any deployment requirements, it does expose one configurable property.
v Message queues—Two message queues are required for the CEI to function:
– ScheduledWork—Holds messages that represent jobs to be processed.
– CompletedWork—Holds messages that represent processed jobs.
The CEI has the same infrastructure requirements as InfoSphere MDM Server. To
enable the CEI, you must configure the following components:
v WebSphere MQ Server—Configure WebSphere MQ when you install the
InfoSphere MDM Server product. The install script automatically configures
WebSphere MQ Server with these required objects:
– The queue manager, using the default name
CUSTOMER.QUEUE.MANAGER. You can also change the name of the queue
manager during the installation. The install script also starts the queue
manager.
– The server communication channel, using the default name
CUSTOMER.CHL.SVRCON. You can also change the name of the channel
during the installation.
– The queue listener on a port that you must enter during the installation. The
default port number is 1414. The install script also starts the queue listener.
– Two queues named CUSTOMER.SCHEDULED.WORK and
CUSTOMER.COMPLETED.WORK.
v WebSphere Application Server—The InfoSphere MDM Server install script
creates the WebSphere MQ JMS provider and application server MDB listener
port within WebSphere Application Server.
v CEI properties—The runtime properties for CEI are defined in the following
configurations:
–
–
–
–

/IBM/DWLCommonServices/ConcurrentExecution/enabled
/IBM/DWLCommonServices/ConcurrentExecution/defaultWaitTimeout
/IBM/DWLCommonServices/ConcurrentExecution/Cache/purgeFrequency
/IBM/DWLCommonServices/ConcurrentExecution/Cache/timeToLive

For more information on these, see “Understanding configuration elements in
the Configuration and Management component” on page 419.
See also:
“To configure the WebSphere MQ JMS provider for WebSphere Application
Server”
“To configure the application server MDB listener port” on page 252

To configure the WebSphere MQ JMS provider for WebSphere
Application Server
1. Set the queue connection factory with the following configuration:

250

Option

Description

Name

Specify QueueConnectionFactory.

JNDI Name

Specify com/dwl/base/work/queued/
QueueConnectionFactory

Container

Specify managed Authentication
Alias-MQUser

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Option

Description

Queue Manager

Specify CUSTOMER.QUEUE.MANAGER

Host

Specify your WebSphere MQ Server host
name (the name of the computer on which
WebSphere MQ Server is running).

Port

Specify 1414

Channel

Specify CUSTOMER.CHL.SVRCONN

Transport Type

Specify Client

XA-Enabled

Specify No

2. Set the queue destination with the following configuration:
Option

Description

Name

Specify CUSTOMER.SCHEDULED.WORK

JNDI Name

Specify com/dwl/base/work/queued/
ScheduledWorkQueue

Persistence

Specify Non-Persistent

Expiry

Specify Unlimited

Base Queue Name

Specify CUSTOMER.SCHEDULED.WORK

Base Queue Manager Name

Specify CUSTOMER.QUEUE.MANAGER

Queue Manager Host

Specify your WebSphere MQ Server host
name (the name of the computer on which
WebSphere MQ Server is running).

Queue Manager Port

Specify 1414

Server Connection Channel

Specify CUSTOMER.CHL.SVRCONN

3. Set the queue destination with the following configuration:
Option

Description

Name

Specify CUSTOMER.COMPLETED.WORK

JNDI Name

Specify com/dwl/base/work/queued/
ScheduledWorkQueue

Persistence

Specify Non-Persistent

Expiry

Specify Unlimited

Base Queue Name

Specify CUSTOMER.SCHEDULED.WORK

Base Queue Manager Name

Specify CUSTOMER.QUEUE.MANAGER

Queue Manager Host

Specify your WebSphere MQ Server host
name (the name of the computer on which
WebSphere MQ Server is running).

Queue Manager Port

Specify 1414

Server Connection Channel

Specify CUSTOMER.CHL.SVRCONN

Chapter 20. Running parallel tasks using the Concurrent Execution Infrastructure (CEI)

251

Licensed Materials – Property of IBM

To configure the application server MDB listener port
Set the message listener port with the following configuration:

252

Option

Description

Name

Specify ScheduledWork

Initial State

Specify Started

Connection Factory JNDI

Specify com/dwl/base/work/queued/
QueueConnectionFactory

Destination JNDI Name

Specify com/dwl/base/work/queued/
ScheduledWorkQueue

Maximum Sessions

Specify 10.
Note: The number of maximum sessions
determines how many jobs will be processed
concurrently. Setting this to a very large
value results in lower overall application
performance.

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 21. Setting source values and data decay
The purpose of source values is to establish a standardized approach to store and
retrieve information, or values, that come from an external sources when the
attributes of those values do not fit the structure of InfoSphere MDM Server
products.
Source values allow you to identify the system, application, or user that provided
the value. It also stores the date the value was collected, as well as a history of the
source that provided the value and the date when that value changes.
The source value system must add, update and get the following type of
information within InfoSphere MDM Server:
v Record the source system, application or user that provided the specified
function details, for example privacy preference, campaign, and others
v Record the date when the information is collected
v Keep a history of the source and source date.
The source value system is in several areas within InfoSphere MDM Server. The
source value system works with any entity. It is also included in the specific
function transaction. For example, when a change is made to a party’s privacy
preference, source value system is a part of the function transaction. The source
value system is required in the following function areas:
v Privacy Preference
v Campaigns
v Source System is also included in seven entities in core Party Module. These
entities are:
– Person
– Organization
– Person Name
– Org Name
– Party Identification
– Party ContactMethod
– Party Address
All data and service-level extension points are available to extend source values
and data decay.
Note: Source values and data decay do not require special administration.
In this section, you will learn:
“Understanding interface specifications” on page 254
“Testing source values” on page 257
“Learning data decay transactions” on page 257
“Understanding attributes related to data decay” on page 258
“Configuring data decay” on page 258

253

Licensed Materials – Property of IBM

Understanding interface specifications
There are no controller level services specifically defined for source values.
The existing services can be extended to support source values through the
implementation of IDefaultedSourceValue interface. The methods of this interface
are explained below.

Learning addDefaultedSourceValue
The addDefaultedSourceValue() method adds a single instance of the defaulted
source value object to the database.
Inputs:
v DWLDefaultedSourceValueBObj with no associations
Returns:
v DWLDefaultedSourceValueBObj with no associations
Mandatory Fields:
v entityName
v instancePK
v attributeName
v forcedValue
Note: This is to be implemented as an extension. For example, a client passes
InfoSphere MDM Server a TCRMOrganizationObject that contains an extension
object, TCRMOrganizationExtBObj. The extension object contains a list of
DWLDefaultedSourceValueBObj. Loop through this vector to call the add
method, and add the record.
Exceptions:
v entityName not supplied
v entityName not valid
v attributeName not supplied
v attributeName not valid
v forcedValue not supplied
v duplicate business key—entityName, instancePKP, attributeName

Learning updateDefaultedSourceValue
The updateDefaultedSourceValue() method updates a single instance of defaulted
source value object to database for the given key, which is DefaultedSourceValueId.
Inputs:
v DWLDefaultedSourceValueBObj with no associations.
Returns:
v DWLDefaultedSourceValueBObj with no associations.
Mandatory Fields:
v entityName

254

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v instancePK
v attributeName
v forcedValue
Note: For example, a client passes InfoSphere MDM Server a
TCRMOrganizationObject that contains an extension object,
TCRMOrganizationExtBObj. The extension object contains a list of
DWLDefaultedSourceValueBObj. Loop through this vector to call this method,
and update the record.
Exceptions:
v entityName not supplied
v entityName not valid
v attributeName not supplied
v attributeName not valid
v forcedValue not supplied
v entityName and instancePK not valid
v duplicate business key—entityName, instancePKP, attributeName

Learning getDefaultedSourceValue()
The getDefaultedSourceValue() method retrieves a list of the defaulted source value
objects to the client.
Inputs:
v entityName, instancePK
Returns:
v List of DWLDefaultedSourceValueBObj with no associations.
Mandatory Fields:
v entityName
v instancePK
Note: This is to be implemented as an extension. For example, a client passes
InfoSphere MDM Server a TCRMOrganizationObject that contains an extension
object, TCRMOrganizationExtBObj. The extension object returns a list of
DWLDefaultedSourceValueBObj.
Exceptions:
v Entity Name and InstancePK do not exist.

Learning deleteDefaultedSourceValue
The method deleteDefaultedSourceValue() deletes an existing
defaultedSourceValue.
Inputs:
v DWLDefaultedSourceValueBObj with no associations.
Returns:
v DWLDefaultedSourceValueBObj that was deleted.
Chapter 21. Setting source values and data decay

255

Licensed Materials – Property of IBM

Mandatory Fields:
v defaultedSourceValueId
See also:
“To enable defaulted source values for an existing business object”

To enable defaulted source values for an existing business
object
1. Create a new business object, with a name ending in .ext, that extends the
original business object and implements IDefaultedSourceValueParent and
IExtenstion.
For example:
public class TCRMOrganizationBObjExt
extends TCRMOrganizationBObj
implements IDefaultedSourceValueParent, IExtension

2. Add and implement a copy constructor method to the above business object.
For example:
public TCRMOrganizationBObjExt(TCRMOrganizationBObj

BObj)

3. Implement code for the methods defined in IDefaultedSourceValueParent, that
is getItemsDWLDefaultedSourceValueBObj, setDWLDefaultedSourceValueBObj,
instancePK and entityName. Please note thatinstancePK() should usually return
the IdPK for the business object, however it can return null too. The
entityName()also returns a hard coded string value.
4. Define the required entries in tcrm_extension.properties.
For example:
TCRMOrganizationBObjExt = com.dwl.tcrm.externalrule
ObjectNavigator.com.dwl.tcrm.externalrule.TCRMOrganizationBObj
Ext = getItemsDWLDefaultedSourceValueBObj,#ObjectNavigator.com.dwl.tcrm.
coreParty.component.TCRMOrganizationBObj

5. Modify the DefautlSourceValue.ilr file, specifically rule
DefaultSourceValueSelector by adding an ″else if″ to check if the passing object
is instance of the corresponding business object and to instantiate an extended
object form it.
For example:
// ...
else if (?bObj instanceof TCRMOrganizationBObj)
{
?bObj = new TCRMOrganizationBObjExt((TCRMOrganizationBObj)?bObj);
}
// ...

6. Define the information of the new business object in
tcrmRequest_extension.xsd and tcrmResponse_extension.xsd.
7. Add information of the new business object into the V_GROUP and
V_ELEMENT tables.
8. Implement the rules in the corresponding tables (EXTRULE and
EXTRULEIMPLEM ) in order to trigger defaulted source value rules for a
desired criteria.

256

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Testing source values
InfoSphere MDM Server includes two sample extensions implementing the Source
Values: one for TCRMOrganizationBObj.established_dt and one for
TCRMPersonBObj.birth_dt.
Use the extensibility model to extend the business object (TCRMOrganizationBObj)
to include a list of source values for the BObj.
See also:
“Sample: Testing source values”

Sample: Testing source values
The following is a part of a sample XML request in order to add or update the
defaulted source values passed in TCRMOrganizationBObj:

100

Test Corp.
100
...
9

TCRMOrganizationBObjExt

org

established_dt
Jan 2002
Jan 25, 2002
Default date value for January

org

established_dt

Dec 10, 2002
Default date value for null

Learning data decay transactions
The following transactions are relevant to data decay:
v public DWLAccessDateValueBObj
addAccessDateValue(DWLAccessDateValueBObj dateValue) throws
DWLBaseException;
v public DWLAccessDateValueBObj
updateAccessDateValue(DWLAccessDateValueBObj dateValue) throws
DWLBaseException;
Chapter 21. Setting source values and data decay

257

Licensed Materials – Property of IBM

v public DWLAccessDateValueBObj getAccessDateValue(String dateAccessValId,
DWLControl control) throws DWLBaseException;
v public Vector getAllAccessDateValuesByAttrib(String entityName, String
instancePK, DWLControl control) throws DWLBaseException;
v public DWLAccessDateValueBObj
deleteAccessDateValue(DWLAccessDateValueBObj dateValue) throws
DWLBaseException;

Understanding attributes related to data decay
There are three fields associated with data decay:
v last_used_dt (TIMESTAMP)
v last_verified_dt (TIMESTAMP)
v source_ident_tp_cd
These fields have been added to the following tables:
v Contact
v Personname
v Orgname
v Locationgroup
v Identifier

Configuring data decay
The transactions getPerson, getPersonName, getAllPersonName, getOrganization,
getOrgName, getAllOrgName can be configured to return
DWLAccessDateValueBObj which supplies the data decay information.
See also:
“To configure transactions to return data decay information”

To configure transactions to return data decay information
In the DWLCommon.properties file, under the key, set the value of
attrib_access_date_value to true. The default setting is false.

258

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 22. Understanding performance tracking
InfoSphere MDM Server provides the ability to capture performance statistics for
transactions within components of the architecture. Performance tracking levels are
configurable, allowing you maximal flexibility in choosing the statistics you
require. This allows the user a full range of detail, from having performance
tracking turned off altogether, to having all instrumented components gather
statistics. The performance data is captured by the Logging component or by an
ARM 4.0 implementation identified through configuration.
Application Response Measurement (ARM) is a standard under The Open Group
(http://www.opengroup.org/management/arm/) for measuring the availability
and performance of transactions. The fact that InfoSphere MDM Server uses ARM
4.0 allows for integration with such products as the IBM Tivoli® Composite
Application Manager for Response Time Tracking (ITCAM for RTT).
Important: ARM 3.0 performance tracker has been deprecated. The previous
implementation of the performance tracker that worked with ARM 3.0 has been
deprecated due to a lack of adoption of the ARM 3.0 API in the industry. The code
for the old performance tracker is still provided, but because no InfoSphere MDM
Server code uses it, the resulting performance log file contains only the logs
associated with client instrumentation. As a result, it is highly recommended that
you upgrade to the new tracker, and discontinue the use of the old tracker.
Instrumentation for client extensions is now provided within InfoSphere MDM
Server minimizing, if not eliminating, the need for client instrumentation. Lastly,
the ARM 3.0 library, arm.jar, is also deprecated and you should no longer use it.
However, the classes within this library have not been deprecated. To upgrade the
client code, you must remove the arm.jar from the development environment,
rebuild the workspace and fix the resulting errors.
See the Performance Tracking section of the IBM InfoSphere Master Data Management
Server System Management Guide for more information.
In this section, you will learn:
“Understanding performance tracking statistics”
“Learning levels of tracking” on page 260
“Learning performance tracking levels” on page 261
“Understanding performance statistics capturing” on page 261
“Using the ARM 4.0 agent” on page 264

Understanding performance tracking statistics
InfoSphere MDM Server tracks performance from several specific points in the
instrumentation.
At each point of instrumentation within InfoSphere MDM Server, the following
information is provided: request ID, request name (end-to-end transaction name),
transaction name, parent correlator ID, correlator ID and a context specific note.
The duration of the transaction is calculated by the mechanism that captures the
performance information.

259

Licensed Materials – Property of IBM

Learning instrumentation points
The instrumentation points within InfoSphere MDM Server include:
v ComponentLayer
v ComponentLayerExtension
v ComponentLayerPrePost
v
v
v
v
v
v
v

ControllerLayer
ControllerLayerExtension
ControllerLayerPrePost
DatabaseDetails
DatabaseQuery
ExecuteTx
ExternalBusinessRules

v ExternalValidation
v InternalValidation
v
v
v
v
v

Notification
PartyMatcher
RequestHandler
RequestParser
ResponseConstructor

v SecurityAuthorization
v Standardization
v SuspectProcessing
v ThirdPartyExtension
v TransactionManager
Where applicable, client extensions are also monitored. For example, if a custom
RequestParser is used, performance statistics can be captured for it using the
RequestParser instrumentation.

Learning levels of tracking
When performance tracking is turned on, the Performance Monitor captures
elapsed times for the following categories of a transaction depending on the level
chosen:
v OFF: No tracking
v Level 1: Measures the overall transaction time from the time the thread enters
the application controller
v Level 2: Measures components transaction time, validation, external components,
such as Trillium and client extensions, as well as level 1 measurements
v Level 3: Measures the amount of time for DWLRequestHandler,
XMLRequestParser and XMLResponseConstructor component to parse incoming
XML and to prepare XML response, as well as level 2 measurements.
For example, if performance logging at Level 2 is turned on, elapsed times to
perform an operation on a business component such as addParty() as well as a
breakdown of that operation—validations, database access, extension, and external
services elapsed times—are captured. This breakdown is made possible through
the use of transaction correlators.

260

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Learning performance tracking levels
Several different levels of performance tracking are available for InfoSphere MDM
Server.
A range of performance tracking levels are supported within InfoSphere MDM
Server, with more data being captured as the tracking level increases. A special
performance tracking level of -1 is provided to allow you the maximum flexibility
in configuring performance tracking. All configuration is done through the
Configuration and Management components and requires the application to be
restarted for the change to take effect. Performance tracking is turned off by
default.

Learning tracking level descriptions
The performance tracking levels and the data they provide are:
v Level -1—Custom performance tracking. When this level is set, all user-enabled
instrumentation points are used. To enable performance logging at the
ExternalBusinessRule instrumentation point, for example, set the
/IBM/DWLCommonServices/PerformanceTracking/ExternalBusinessRules/enabled
configuration property to true. If you want to log only performance statistics for
external business rules, set all other configuration properties to false.
v Level 0—Performance tracking is disabled. This is the default level.
v Level 1—Measures the overall transaction time from the time the thread enters
the application controller.
v Level 2—Measures components transaction time, validation, external
components, such as client extensions, as well as level 1 measurements.
v Level 3—Measures the amount of time for Request Handler, Request Parser and
Response Constructor components to parse incoming XML and to prepare XML
response, as well as level 2 measurements.
See also:
“Example: Performance tracking”

Example: Performance tracking
If performance logging at Level 2 is enabled, elapsed times to perform an
operation on a business component such as addParty() as well as a breakdown of
that operation—validations, database access, extension, and external services
elapsed times—are captured. This breakdown is made possible through the use of
transaction correlators. Custom logging levels, when /IBM/DWLCommonServices/
PerformanceTracking/ExternalBusinessRules/enabled is configured, only come in
to play when the tracking level is set to -1.

Understanding performance statistics capturing
Performance statistics can be captured by the InfoSphere MDM Server Logging
component and by an ARM agent.
Performance statistics can be captured in 2 ways in InfoSphere MDM Server: by
the InfoSphere MDM Server Logging component and by an ARM 4.0 agent.

Chapter 22. Understanding performance tracking

261

Licensed Materials – Property of IBM

Learning the logging component
By default, if the tracking level is set to a value other than 0, the performance
statistics are sent to the InfoSphere MDM Server Logging component. This is
because the /IBM/DWLCommonServices/PerformanceTracking/
ARM40TransactionFactory/className configuration property is set to the value of
‘None’. In addition to containing all performance statistics described in “Learning
performance tracking levels” on page 261, based on the chosen tracking level, for
readability, the logs are indented according to the parent/child relationships of the
correlator IDs.
About Transaction Correlators
A transaction is a defined unit of end-user work. A transaction may consist of
other transactions, called sub-transactions that it initiates as a part of its processing.
For example, an addParty transaction checks first that the party exists, and then
adds the party and all its attributes through sub-transactions, as shown in the
diagram below.

Add
A1

Query
B1

Add
B2

Add Contact
C1

Add Person
C2

Add PersonName
C3

Add Address
C4

Add ContactMethod
C5

Add Extension
C6
A unique token, called a correlator is assigned to each instance of each transaction
and sub-transaction. By putting two correlators together—parent transaction
correlator, sub-transaction correlator—a performance agent or management

262

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

application can trace the full calling hierarchy of the transaction. In the sample
above we have correlator pairs: (A1, B1); (A1, B2); (B2, C1); (B2, C2); and so on.
These parent-child correlator pairs are logged with the performance data and help
correlate the log entries that belong to a particular transaction group, allowing a
graph like the one above to be recreated from a series of log entries for any given
transaction.
Sample Log File Output
Because the performance statistics are captured by the Logging component, the
performance statistic output can be configured based on what their logger of
choice has to offer. For example, with Log4j, all performance logs can be redirected
to a separate file named performancemonitor.log with the following configuration:
log4j.appender.performanceLog=org.apache.log4j.RollingFileAppender
log4j.appender.performanceLog.Encoding=UTF-8
log4j.appender.performanceLog.Threshold=ALL
log4j.appender.performanceLog.layout.ConversionPattern=%d : %m%n
log4j.appender.performanceLog.layout=org.apache.log4j.PatternLayout
log4j.appender.performanceLog.File=/IBM/MDM/logs/performancemonitor.log
log4j.logger.com.dwl.base.performance.PerformanceMonitorLog=INFO,performanceLog

In the ConversionPattern above, Log4j is providing the time and data, via %d,
corresponding to when each performance log message was printed: 2006-10-10
12:02:02,213
See the Logging component documentation for more details on how to configure
your logs.
The following is a sampling of log messages you may see under the following
conditions:
v The tracking level is set to -1 and the only instrumentation enabled is
Component level
v An addContract transaction was submitted to InfoSphere MDM Server
v The above Log4j configuration was chosen
Attention:
example

The Correlation IDs were manually shortened for the purposes of this

2006-10-10 12:02:02,213 :
504000 addContract : addParty_COMPONENT : 0 : 448115 : 0 : : SUCCESS
504000 addContract : addPartySimple_COMPONENT : 448115 : 523115 : 0 : : SUCCESS
504000 addContract : addPerson_COMPONENT : 523115 : 561159 : 0 : : SUCCESS
504000
addContract : addPersonName_COMPONENT : 561159 : 851115 : 16 : : SUCCESS
504000
addContract : getAllPersonNames_COMPONENT : 851115 : 106115 : 0 : : SUCCESS
504000
addContract : addPersonName_COMPONENT : 561159 : 218115 : 16 : : SUCCESS
504000
addContract : getAllPersonNames_COMPONENT : 218115 : 711599 : 0 : : SUCCESS
504000
addContract : addDefaultedSourceValue_COMPONENT : 561159 : 436115 : 0 : : SUCCESS
504000 addContract : addPartyIdentification_COMPONENT : 523115 : 794115 : 15 : : SUCCESS
504000
addContract : getAllPartyIdentifications_COMPONENT : 794115 : 703115 : 15 : : SUCCESS

Notice that only ‘COMPONENT’ transactions are logged. If other instrumentation
points were enabled, then you would see their performance statistics interlaced
with the ones above, with the appropriate tabbing and context. Also, each entry in
the log file is of the following format:
[spaces based on sub-transaction depth] : :
: : : :

Chapter 22. Understanding performance tracking

263

Licensed Materials – Property of IBM

Using the ARM 4.0 agent
The ARM 4.0 agent offers powerful performance tracking capabilities in InfoSphere
MDM Server.
Using a third party application like the IBM ITCAM for RTT to track the
application performance and transaction availability via ARM 4.0 is a much more
powerful way of tracking performance within InfoSphere MDM Server, allowing
for powerful reporting and alert capabilities among other options.
See also:
“To enable ARM 4.0 performance tracking”
“To disable ARM 4.0 performance tracking”

To enable ARM 4.0 performance tracking
Enable ARM Agent by setting the /IBM/DWLCommonServices/PerformanceTracking/
ARM40TransactionFactory/className configuration property to anything other than
None.
This causes the InfoSphere MDM Server Performance Tracker to try to instantiate a
class with the given name as the implementation of the
org.opengroup.arm40.transaction.ArmTransactionFactory interface. See the
documentation of the ARM agent that you are using to determine how to install it
for InfoSphere MDM Server. At a minimum, the className of the
ArmTransactionFactory must be provided, and this class and all supporting classes
must be available within the classpath of InfoSphere MDM Server.

To disable ARM 4.0 performance tracking
Disable ARM 4.0 performance tracking by setting the /IBM/DWLCommonServices/
PerformanceTracking/ARM40TransactionFactory/className configuration property
to None.
This reverts the performance tracker back to using the Logging component.

264

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 23. Aliasing transactions
The Aliasing feature allows you to change the terminology of transactions to match
your line of business.
Although InfoSphere MDM Server is designed to support different lines of
business such as banking, its terminology may not always be used in a particular
line of business (for example, in banking, accounts are represented as contracts)
and it may be difficult for some users to understand terminology that is not what
they are accustomed to.
The InfoSphere MDM Server Aliasing service and the pluggable parser/constructor
features of the Request framework (discussed in Chapter 24, “Configuring the
Request and Response Framework,” on page 269) enable the InfoSphere MDM
Server installation to be customized to use terminology that is familiar to the users.
The line of business terminology is usually reflected in the XML request sent to the
application. With the aliasing service, InfoSphere MDM Server is able to process
these two different XML requests as if they are the same request.
The aliasing process is done during the InfoSphere MDM Server default XML
parsing and XML constructing, as shown in the diagram below. The default XML
parser component accepts the alias XML, and validates the alias XML against the
appropriate XSD or schema. For each line of business there will be one set of XSD
and schema.
After the validation process is done, the default XML parser component calls the
alias service to get the original element name. When the default XML parser gets
the original names, it constructs the business objects and calls the controller to
execute the transaction. During the construction period, the default constructor
component returns the alias name, based on the type of XML response
XSD/Schema that is expected.

Aliased XML

DTD

XML Parsing
Process

XML Schema

Value Objects

Cached Aliased
Data

In this section, you will learn:
“Sample: Transaction Aliasing” on page 266
“To run aliasing transactions” on page 267

265

Licensed Materials – Property of IBM

Sample: Transaction Aliasing
InfoSphere MDM Server, with an XML client interface, accepts different XML files
with aliased element names as its transaction request.
The example below shows two XML Request Files, one with original element
names and the other with alias element names.
TCRMTx structure is the payload of the request. It states the type of business
transaction to execute (TCRMTxType), the type of top level object involved in the
transaction (TCRMTxObject), and the value of the object (any embedded objects).
There can only be one top level object.
Important: myTCRM.xsd refers to the request XSD, and RequestControl structure is
the header of the request.
XML Request file with original element names

400011

Tester
100

addContract
TCRMContractBObj

1
1
5

200
2001-01-01
300.00
54

...................

XML Request file with Alias element names

400011

Tester
100

addAgreement
AgreementBObj

266

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

1
1
5

200
2001-01-01
300.00
54

...................

To run aliasing transactions
1. In the request/response XMLs, use the banking XSDs or DTDs.
2. Populate the following tables:
v GROUPALIAS
v DATAOWNER
v TRANSACTIONALIAS
v ELEMENTALIAS
3. In the tcrm_extension properties file, uncomment the following items:
v DataOwner.banking
v DataOwner.tCRMResponse_banking
v ResponseRootElement.tCRMResponse_banking
v ResponseRootSchema.banking.dtd or ResponseRootSchema.banking.xsd

Chapter 23. Aliasing transactions

267

Licensed Materials – Property of IBM

268

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 24. Configuring the Request and Response
Framework
The Request and Response Framework provides a consistent entry point into
InfoSphere MDM Server enterprise applications.
It offers common infrastructure services such as authorization checking, transaction
demarcation, and others for all incoming transactions. It provides a number of
configuration options and extension points to customize it.
In this section, you will learn:
“Understanding the Request and Response Framework”
“Understanding transaction flow” on page 270
“Understanding DWLServiceController” on page 271
“Understanding RequestHandler” on page 274
“Understanding parser components” on page 274
“Understanding the InfoSphere MDM Server XML parser” on page 274
“Understanding constructor components” on page 275
“Understanding the InfoSphere MDM Server XML constructor” on page 275
“Understanding the business proxy” on page 276

Understanding the Request and Response Framework
The Request and Response Framework perform various functions using several
components that make up the framework.
The request framework performs the following functions:
v Accepts and parses a request containing a single or composite transactions.
v Authorizes the request.
v Participates in a distributed transaction or initiates a new transaction if required.
v Invokes the requested service using the appropriate controller component.
v Constructs and returns the response
The class diagram below shows the various Request and Response Framework
components. The request parser factory, parser, response constructor factory, and
constructor are all independent components; you can also plug in your own
customized components in place of any of these. The request handler is a
component that interacts with these underlying components to carry out the
request.
The DWLRequestHandler, DWLParserFactory and DWLConstructorFactory
manage various request formats, such as the default XML format (which uses
XMLRequestParser and XMLResponseConstructor) and batch sample flat files fixed
format (which use batch sample parsers and constructors pairs). Custom parsers,
parser factories, constructors and constructor factories can be plugged in to
manage client-defined request formats.

269

Licensed Materials – Property of IBM

Understanding transaction flow
As the Request and Response Framework receives a transaction request, it takes it
through a series of predefined steps designed to process a request and generate a
transaction response.
The following flow illustrates these actions. This request and response workflow
uses the InfoSphere MDM Server default XML format as an example.
1. DWLServiceController receives the request from the client application and
dispatches it to the appropriate request handler (in this case,
DWLRequestHandler). DWLServiceController uses the RequestType parameter
to determine which request handler to use. See “Understanding
DWLServiceController” on page 271.
2. DWLRequestHandler interacts with underlying components to carry out the
request. See “Understanding RequestHandler” on page 274.
3. RequestParserManager determines the type of parser factory to use (in this
case, DWLParserFactory). RequestParserManager uses the same RequestType
parameter as DWLServiceController to determine the request parser factory to
use.
4. DWLParserFactory creates a request parser based on the value of the parser
key in the HashMap:context (in this case, default XMLRequestParser). The
parser is returned to RequestParserManager and then returned to
DWLRequestHandler.
5. XMLRequestParser parses out the DWLTransaction object. In the object,
DWLControl and transaction type are set.
6. HashMap:context contains an optional key: OperationType. If the
OperationType has a value of parse, DWLRequestHandler class returns the
result of parsing, which is the DWLTransaction object, to the caller. If the
OperationType has a value of process, DWLRequestHandler passes the
DWLTransaction object on to the business proxy for further processing.
OperationType is optional; if it is not set, or if it is set with a value of all,

270

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

DWLRequestHandler retrieves a parser first, then uses the parser to parse out
a DWLTransaction object, followed by business processing through business
proxy.
7. DWLTxnProcessor uses business proxies to invoke the InfoSphere MDM
Server business services layer.
8. ResponseConstructorManager determines the type of response constructor
factory to use, based on the ResponseType parameter, in this case
DWLConstructorFactory.
9. DWLConstructorFactory creates one ResponseConstructor based on the
ConstructorParam in context (in this case, it uses the default,
XMLResponseConstructor).
10. Constructor provides a response object and sends the object back to client
application.

Understanding DWLServiceController
DWLServiceController is the entry point for InfoSphere MDM Server. It is a
stateless session bean that the client application uses to access the service remotely
and enable distributed transaction management.
DWLServiceController provides the following method:
public Serializable processRequest(HashMap context, Serializable request)

The method throws a DWLResponseException error, if the exception occurs
because of underlying components.
The first input parameter, HashMap context, contains a name-value pair of context
properties which are used by the Request and Response Framework to handle the
request appropriately. Depending on the values contained in HashMap context, a
different request handler, parser factory, parser, and constructor factory
construction are used. The following properties are used by the system:
v TargetApplication—Specifies the application to which this request is sent. The
only value supported is tcrm, which signifies InfoSphere MDM Server as the
target application.
v RequestType—Drives the selection of a request handler and parser factory. To
use the standard request handler and parser factory that comes with the core
product, use the value standard.
v Parser–-Selects the parser for the current request. To use the standard XML
parser to parse InfoSphere MDM Server XML requests, use the value
TCRMService.
v ResponseType—Selects the type of constructor factory. To use the standard
factory that comes with the core product, use the value standard.
v Constructor—Selects the constructor to use for the response. To use the standard
constructor that returns the InfoSphere MDM Server response XML, use the
value TCRMService .
v OperationType—An optional property that is used by the standard request
handler to perform the specific operation instead of the full processing. Possible
values include Parse, Process, and All. The default value is All. Using the Parse
property, the request handler only performs the parsing step, using the Process
property it skips parsing but performs the processing and construction, and
using the All property, it completes all the steps.

Chapter 24. Configuring the Request and Response Framework

271

Licensed Materials – Property of IBM

Using the Parser and Constructor keys in HashMap context, the client application
can determine which parser is to be invoked and which constructor to use to
construct the expected response. For example, the client can send a request in
TCRMService XML format and expect a response in an ACORD XML format.
These properties work in conjunction with the Request and Response Framework
configuration, so ensure that the properties passed in are mapped in the
DWLCommon.properties configuration file. All standard plug-ins are defined in
the configuration. If you require values other than the standard ones, then make
the appropriate changes to the configuration. Also, to support sending additional
properties, you must configure a custom request handler, parser, or constructors
depending upon individual property.
The second processRequest() input parameter, Serializable request, represents
the request data to be processed. Any object that implements the Serializable
interface can be passed as request data. It is up to the parser to parse this object
and create data structures for the target application. For example, XML can be
passed in this parameter as a String and the appropriate XML parser parses the
XML and creates Java objects to be used as input data.
The return value from the method is also any object that implements a Serializable
interface. For example, in the case of an XML, it can be a String containing the
XML response. The following sample of the DWLCommon.properties configuration
file shows how the above property values are mapped to the appropriate types:

272

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The method throws a DWLResponseException error, if the exception occurs
because of underlying components.

Chapter 24. Configuring the Request and Response Framework

273

Licensed Materials – Property of IBM

Understanding RequestHandler
RequestHandler acts as the main dispatcher class for handling the request. It is
responsible for interacting with the parser, constructor and indirectly with the
business proxy for parsing, response construction and business processing of the
request.
The InfoSphere MDM Server default request handler, DWLRequestHandler,
implements the default request handling logic.

Understanding parser components
The parser is responsible for parsing the request and constructing business objects
that contain the data sent in the request. These business objects are returned back
to the request handler for subsequent business processing through the business
proxy layer.
The Request and Response Framework allows callers to select the parser for every
incoming request. Multiple parsers can be configured in the same deployment. The
framework comes packaged with multiple parsers to handle different request
formats, including the InfoSphere MDM Server default XML request format and
the composite XML parser.
You can build your own parsers to handle a specific request format. A parser must
implement the com.dwl.base.requestHandler.interfaces.IRequestParser interface.
You must configure the new parser in the DWLCommon_extension.properties file
to make it available to the Request and Response Framework. Refer to the Javadoc
for more information on the interface and the methods that should be
implemented.
The parser implementation class is created using a factory class. This factory class
is also pluggable. A default parser factory class,
com.dwl.base.requestHandler.RequestParserFactory is provided to create the parser
based on the Parser value in the incoming context parameter. You may decide to
create a new parser factory implantation and configuring it in the
DWLCommon_extension.properties file. The new class must implement the
com.dwl.base.requestHandler.interfaces.IRequestParserFactory interface. See the
Javadoc for more information on this interface. The selection for the parser factory
is accomplished by using the RequestType parameter passed into the context.

Understanding the InfoSphere MDM Server XML parser
InfoSphere MDM Server provides an XML parser for parsing InfoSphere MDM
Server XML as defined by myTCRM.xsd. The implementation class for this parser
is com.dwl.tcrm.coreParty.xmlHandler.XMLRequestParser.
See also:
“To use the InfoSphere MDM Server XML parser”

To use the InfoSphere MDM Server XML parser
1. Declare all transactions in the CDBUSINESSTXTP table.
The TX_OBJECT_TP column in this table defines the corresponding transaction
object type. Possible values are as follows:
v P—Persistence

274

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v I—Inquiry
v S—Search
For example, if TX_OBJECT_TP is set to P, DWLTransactionPersistent is parsed
out.
2. If you do not want to use XML validation, turn off XML validation as a
standard SAXParser feature by changing the value of /IBM/
DWLCommonServices/XML/useValidatingParser to false.
See Chapter 34, “Using the Configuration and Management components,” on
page 405 for more information.
The default value for this flag is true. By changing it to false, the default XML
request parser shipped with InfoSphere MDM Server globally turns off
validation for all incoming request XML files.
Note: Turning off the validation causes unpredictable results if the incoming
XML is invalid according to the published XML schema. Avoid turning off the
validation. Turning off the validation may be desirable in a production
environment, to save the time that would be spent on validation, and where
validations can be run after testing and verifying all the various combinations
of request XML files. However, leave validation on if the validation time is
acceptable or the request XML structure cannot be predicted.

Understanding constructor components
A constructor within the Request and Response Framework is responsible for
constructing the response that is returned to the caller. Each incoming transaction
request can select its own constructor by passing it the appropriate value for the
Constructor parameter in the context: HashMap input parameter for the
DWLServiceController.
You can build your own constructors if you need to handle a specific response
format. A constructor must implement the
com.dwl.base.requestHandler.interfaces.IResponseConstructor interface. Refer to the
Javadoc for more information on this interface and the methods that should be
implemented. The new constructor should be configured in the
DWLCommon_extension.properties file to make it available to Request and Response
Framework.
The constructor implementation class is created using a factory class. This factory
class is also pluggable. A default constructor factory class,
com.dwl.base.requestHandler.ResponseConstructorFactory is provided, which
creates the constructor based on the Constructor value in the incoming context
parameter. You can create a new constructor factory implantation and configure it
in the DWLCommon_extension.properties file. The new class must implement the
com.dwl.base.requestHandler.interfaces.IResponseConstructorFactory interface. See
the Javadoc for more information a bout this interface. The selection for the parser
factory is done by using the ResponseType parameter passed into the context.

Understanding the InfoSphere MDM Server XML constructor
InfoSphere MDM Server provides a response constructor to build an XML response
as defined by tcrm_response.xsd. The implementation class for this parser is
com.dwl.tcrm.coreParty.xmlHandler.XMLResponseConstructor.

Chapter 24. Configuring the Request and Response Framework

275

Licensed Materials – Property of IBM

Understanding the business proxy
The business proxy acts as a bridge between the Request and Response Framework
and InfoSphere MDM Server.
A default business proxy is provided to interface with InfoSphere MDM Server.
The implementation class for this business proxy is
com.dwl.base.requesthandler.DWLTxnBP. It delegates each incoming call to the
appropriate InfoSphere MDM Server controller by looking it up in the customer
configuration files. The incoming transaction name is used as the key to find the
controller name. The response from InfoSphere MDM Server is returned back to
the request handler.
See “Using best practices to develop customized business proxies” on page 277 for
information on creating customized business proxies.

276

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 25. Creating composite transactions using
customized business proxies
Composite transactions allow you to group related business transactions that you
want executed as one unit of work. There are two methods for creating composite
transactions:
v Using customized business proxies—Discussed in this chapter.
v Using XML—Discussed in Chapter 26, “Creating composite XML transactions,”
on page 285
The default com.dwl.base.requestHandler.DWLTxnBP business proxy handles the
three types of IBM InfoSphere Master Data Management Server transactions:
Search, Inquiry, and Persistent. The business proxy’s main function is to delegate the
transaction to the appropriate controller to execute in the Request framework,
based on the transaction name. This business proxy has very little business logic
except to detect the type of transaction.
Customized business proxies can be implemented to handle addition business logic
before delegating the transaction to the controller. This section describes
customizing a business proxy so that multiple transactions are triggered at the
business proxy level to fulfill a business requirement. For best practices
information, see “Building custom batch jobs for the InfoSphere MDM Server
WebSphere Extended Deployment batch processor” on page 321.
In this section, you will learn:
“Using best practices to develop customized business proxies”
“Implementing customized business proxies” on page 280

Using best practices to develop customized business proxies
You can write custom business proxies to support specific logic. Most often, the
requirement is to build composite transaction logic within a custom business proxy.
This type of business proxy is called a composite business proxy. Non-composite
custom transactions may also be supported using custom business proxy.
Being able to compose new transactions by using existing InfoSphere MDM Server
transactions is a very powerful mechanism offered within the Request and
Response Framework. Since business proxies are Java classes, they can manage any
custom logic no matter how complex it is. Additionally because they use existing
InfoSphere MDM Server transactions, they do not need to duplicate that logic;
instead the business proxy should only contain the composite business logic.
With the flexibility and power offered by custom business proxy comes the risk
that less than optimal code may be written affecting the performance and
scalability of the system. Developers must keep in mind the performance
implications during the design and implementation of their business proxies.
See also:
“Choosing an appropriate InfoSphere MDM Server transaction” on page 278
“Choosing an appropriate InfoSphere MDM Server transaction parameter” on
page 278
© Copyright IBM Corp. 1996, 2009

277

Licensed Materials – Property of IBM

“Minimizing redundant data returns” on page 279
“Caching read-only data” on page 279
“Using base business proxies” on page 279
“Developing stateless transactions” on page 279

Choosing an appropriate InfoSphere MDM Server transaction
If you are using an existing InfoSphere MDM Server transaction for a business
proxy, choose the transaction that meets both your functional and your
performance requirements.
Often, there is more than one transaction that can be used to fulfill the functional
requirement, with different performance characteristics. These performance
differences are because of the amount of data being managed and the validations
performed on that transaction. An example of choosing an incorrect transaction is
using an InfoSphere MDM Server composite transaction to update a granular
object (for example, using the updateParty composite transaction to update only
the party identification and not the parent party object). In this case, because the
request contains the parent object, the system has to handle it in addition to
handling the child object. This results in extra processing and slower performance.
A better transaction to choose is the updateIdentification transaction, a granular
transaction.
Another example is the use of composite inquiry transactions which return the
parent object along with a number of child objects. In certain scenarios it may be
desirable to use the granular transaction to get the child objects directly instead of
getting them through the composite transaction. You can also accomplish this by
creating a custom inquiry level and passing it into a composite transaction.
In some cases, InfoSphere MDM Server might have transactions that fulfill your
functional requirements but that do not meet your performance requirements. For
example, an InfoSphere MDM Server transaction that returns large volume of data
as per its requirements, where you may require only a small part of that data.
Using the InfoSphere MDM Server transaction would result in redundant data
being returned and then discarded. If the amount of redundant data returned
outweighs the useful data, using this transaction is not acceptable. If there are no
existing transactions that meet both your functional and performance needs,
consider writing an customized transaction for such scenarios to return only the
data you need.

Choosing an appropriate InfoSphere MDM Server transaction
parameter
After choosing the best transactions for your requirements, it is equally important
to choose the right parameters for those transactions. This is especially true for
search and inquiry transactions and their parameters, which control the amount of
data returned from such transactions.
Using a value that returns too much redundant data will slow down performance.
Two parameters to consider are the inquiry level and the filter. Inquiry levels
define the level of detail to return for the object, and filters determine whether to
return active, inactive or all records.
Choosing the right inquiry level means selecting a value, which returns the
necessary level of detail, without also returning too much redundant data.
InfoSphere MDM Server offers predefined inquiry levels and the corresponding list

278

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

of child objects which are returned. You should use the lowest inquiry level which
will return the desired objects required by the caller. If the inquiry level which
returns the desired objects also brings back too many redundant objects, you can
define a custom inquiry level and configure it to return only the desired objects.
For the filter, using a value of active will work in most cases. Using the value all
returns active and inactive records. Do not use this value unless you specifically
want to return inactive records and active records.

Minimizing redundant data returns
In addition to selecting the right transactions and their parameters, it is also
important to understand the various scenarios the code must handle, based on the
input request, in order to minimize the amount of unnecessary data that is
returned.
In some scenarios particular data set may be required, but the same data may be
redundant for a different scenario. For example a business proxy may be written to
handle different combinations of input objects to add or update them. If the
request does not contain an object, the code should not make a call to fetch the
corresponding data.
Additionally, delay returning the data as much as possible. For instance, validate
the input request before starting to return the data. This ensures that data is not
returned for cases when the input request was invalid.

Caching read-only data
InfoSphere MDM Server internally caches read-only data, for example, code table
and other configuration items.
If the business proxy has custom logic which works for read-only data that is not
managed by InfoSphere MDM Server, cache these values and do not return them
for every transaction.

Using base business proxies
Extend the com.dwl.base.requesthandler.DWLTxnBP business proxy and use its
methods for interfacing with InfoSphere MDM Server controllers.
This method uses less code for the new business proxy, and can take advantage of
any current and future performance features while connecting with InfoSphere
MDM Server controllers.

Developing stateless transactions
InfoSphere MDM Server offers stateless transactions, and the business proxies
should do the same. Do not return the same data more than once.
Do not accumulate the state for the incoming transactions either. Doing so
potentially takes up all the available JVM memory and can bring down the server
process.

Chapter 25. Creating composite transactions using customized business proxies

279

Licensed Materials – Property of IBM

Implementing customized business proxies
The following sections describe how to implement customized business proxies,
step-by-step.
See also:
“Example: Step 1 – Determining the Request structure”
“Example: Step 2 – Registering the transaction in the database” on page 281
“Example: Step 3 – Adding the transaction name to the properties file” on page
281
“Example: Step 4 – Implementing the business proxy” on page 282
“Example: Step 5 – Deploying the business proxy with InfoSphere MDM
Server” on page 283
“To run the customized business proxy example” on page 283

Example: Step 1 – Determining the Request structure
Begin this customization by deciding on the request for this transaction. Assign a
name for this transaction—for example, updatePartyAddressCompositeSample.
Evidently, this request must contain data about the address. It should also contain
data about the party’s identification in order to use this information as search
criteria for the party.

Understanding criteria for searching the party
One way to perform a searchParty transaction is to search by the identification
type and identification number, and whether the search is for a person or
organization. For example, search for the person with the driver licence number
xyz.
For the context of this transaction, the searchParty result is valid only if exactly one
party is returned by the searchParty transaction.

Understanding criteria for matching the address
When a party is returned, the response must also bring back the address or
addresses for that party, so that the business proxy can try to match the addresses
with the address in the request.
For the context of this transaction, the business proxy tries to match the address
based on the AddressUsageType. For example, given a mailing address in the
request:
v if a mailing address already exists in the party information, update the address
v if a mailing address does not exist, add the mailing address to the party
information

Using InfoSphere MDM Server data elements
The data elements required for this transaction can be easily described by the
TCRMPartyBObj, TCRMPartyAddressBObj and TCRMPartyIdentificationBObj
objects. A sample request for this transaction looks like the following:

100013

280

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

cusadmin
100

updatePartyAddressCompositeSample
TCRMPartyBObj

3
Main Street
Atlanta
30346
108

1
482000001

Note: Data elements shown in red above indicate mandatory elements for this
transaction.

Using non-IBM InfoSphere Master Data Management Server data
elements
If this transaction contains data elements that are not in the InfoSphere MDM
Server data model, you must implement an extension or addition. This step is
essential in order for the parser in the Request framework to validate transaction
requests in XML format. For more information on creating extensions and
additions, see Chapter 2, “Customizing InfoSphere MDM Server,” on page 17.

Example: Step 2 – Registering the transaction in the database
Add the transaction name for this transaction
(updatePartyAddressCompositeSample) to the CDBUSINESSTXTP table with a
TX_OBJECT_TP value of ″P″, for ″persistent″ transaction type. The DWLTxnProcessor
in the Request framework looks up allowable transaction names in the database
that are registered with IBM InfoSphere Master Data Management Server.

See “Using best practices to develop customized business proxies” on page 277 for
more information.

Example: Step 3 – Adding the transaction name to the
properties file
Add this transaction name to the DWLCommon_extension.properties file. The
DWLTxnProcessor class looks up this properties file to send the transaction to the
appropriate business proxy based on transaction name.
Chapter 25. Creating composite transactions using customized business proxies

281

Licensed Materials – Property of IBM
...
BusinessProxy.tcrm.updatePartyAddressCompositeSample=
com.dwl.tcrm.samples.compositeTxn.DWLSampleUpdatePartyAddressCompositeTxnBP
...

The above property specifies the specific business proxy implementation class to
use for the transaction name ″updatePartyAddressCompositeSample″.
See “Using best practices to develop customized business proxies” on page 277 for
more information.

Example: Step 4 – Implementing the business proxy
Implement a business proxy (for example,
DWLSampleUpdatePartyAddressCompositeTxnBP) that extends the DWLTxnBP class. This
business proxy contains the business logic to perform the party search and address
matching, whereas the base DWLTxnBP class provides the built-in logic to ultimately
call the controller bean to update or add the address.
The class diagram for the extension:

The following code snippet shows the execute() method in this business proxy:
public class DWLSampleUpdatePartyAddressCompositeTxnBP extends DWLTxnBP {
...
...
public Object execute(Object theObj) throws BusinessProxyException {
long beginTime = System.currentTimeMillis();
Object theResponseObject;
try {
// assuming that the updatePartyAddressCompositeSample
// transaction is set up as type P (persistent
// transaction) in the CDBUSINESSTXTP table
DWLTransactionPersistent theDWLTxnObj = (DWLTransactionPersistent) theObj;
// create either an add or update address transaction
//based on the business requirement
DWLTransactionPersistent theDWLAddressTxnObj =
createAddOrUpdateAddressTransaction(theDWLTxnObj);
// now that we have the correct transaction,
// defer to the base class to call the controller to
// execute the add or update transaction
theResponseObject = super.execute(theDWLAddressTxnObj);
} finally {
long endTime = System.currentTimeMillis();

282

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
DWLTraceLog.printMessage("DWLSampleUpdatePartyAddressCompositeTxnBP : execute :
total time in milliseconds " + (endTime - beginTime));
}
return theResponseObject;
}
...
...
}

In the code snippet above, the private createAddOrUpdateAddressTransaction()
method implements the business logic to determine whether an add or update
address transaction is required. Once this transaction is determined, it calls the
execute() method in the superclass to find the appropriate controller bean. The
following flowchart shows the business logic implemented by this method:

Example: Step 5 – Deploying the business proxy with
InfoSphere MDM Server
In general, if you have any customized business proxies and they are packaged as
part of an EJB Jar file, you need to add the EJB Jar file to the MDM.ear file.
If your customized business proxies are packaged as part of a regular Jar file, add
the regular Jar file as a dependent JAR file referenced by the MDM.ear. In addition,
add a reference to this Jar file in the manifest file of the BTMEJBsForCustomer.jar.

To run the customized business proxy example
1. Run one of the following scripts in the DB/ddl folder in the
CustomerSamples.jar, depending on your database:
v for DB2—SetupCompositeTxn.sql or SetupCompositeTxn_zos.sql
v for Oracle—SetupCompositeTxn_ora.sql.
Note: For Oracle, you must also add a user access-related SQL statement to
assign the user the right to run the sample transaction.
This SQL script adds the transaction name
updatePartyAddressCompositeSample to the BUSINESSTXTP table.
2. Add the following property to the DWLCommon_extension.properties file:
BusinessProxy.tcrm.updatePartyAddressCompositeSample=
com.dwl.tcrm.samples.compositeTxn.DWLSampleUpdatePartyAddressCompositeTxnBP

3. Submit the addPerson transaction to add a person using the AddPerson.xml
provided in the test/updatePartyAddressCompositeTxnBP folder in the Customer
CenterSamples.jar.
This transaction sets up the person to test the business proxy in the next few
steps.
4. Submit the updatePartyAddressCompositeSample transaction using the
UpdatePartyAddress_Composite_Person_NewAddress.xml provided in
thetest/updatePartyAddressCompositeTxnBP folder in the Customer
CenterSamples.jar. Ensure that the user has permission to execute new
composite transactions.
This XML contains a address that has no match on an existing address usage
type. Hence a new address is added to the person.
5. Submit the updatePartyAddressCompositeSample transaction using the
UpdatePartyAddress_Composite_Person_UpdateAddress.xml provided in
thetest/updatePartyAddressCompositeTxnBP folder in the Customer
CenterSamples.jar.

Chapter 25. Creating composite transactions using customized business proxies

283

Licensed Materials – Property of IBM

This XML contains a address that has a match on an existing address usage
type, and so the address is updated.

284

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 26. Creating composite XML transactions
InfoSphere MDM Server includes a Composite Transaction Framework to support
composite XML requests.
Composite transactions allow you to group related business transactions that you
want executed as one unit of work. There are two methods for creating composite
transactions:
v Using customized business proxies—Discussed in Chapter 25, “Creating composite
transactions using customized business proxies,” on page 277
v Using XML—Discussed in this chapter.
A composite XML transaction is a grouping of single transactions that are processed
together as one unit of work. If all transactions within the composite are
successfully executed, all the transactions will be committed. If any one transaction
in the composite fails, any transactions that have been executed will be rolled back.
In the most basic form, a composite transaction contains a series of single
transactions. The transactions are executed one after another. For example, an
addCompleteParty composite transaction may contain three single transactions:
addParty, addPartyInteraction and addPartyGroupingAssociation. These three
transactions are processed as one unit of work. During processing, the composite
transaction can substitute any required items in a request before sending it to be
processed. In the composite above, the addPartyInteraction transaction needs to
refer to the PartyId from the party created in the first addParty transaction. You
can use the syntax provide by the Composite Transaction Framework to substitute
the InteractionParty value in the addPartyInteraction request with the PartyId in
the addParty response.
Note: See “Example: Substituting values from another Request or Response” on
page 289 for details on substitution.

Understanding conditional logic for composite XML transactions
Another usage of composite transactions is to implement conditional logic. The
Composite Transaction Framework provides implementation of two kinds of
conditional logic:
v if-then-else—Allows you to choose which transactions in the composite to execute
based on the response of some previous transaction in the composite. For
example, a searchPersonAddOrUpdate composite transaction may contain three
single transactions: searchPerson, addPerson, and updatePerson. If the
searchPerson transaction does not return any party, then the addPerson
transaction will be executed. On the other hand, if the searchPerson transaction
returns a match, then the updatePerson transaction will be executed. For
information on implementing the “if-then-else” condition, see “Creating
composite transactions with if-then-else logic” on page 295.
v looping—Allows you to iterate through a collection of objects in the response and
perform another transaction on each of the object. For example, a
searchPersonUpdateEachPerson composite transaction may contain two single
transactions: searchPerson and updatePerson. After the searchPerson transaction
returns a collection of matched parties, the updatePerson transaction will be

285

Licensed Materials – Property of IBM

executed for each of the parties found. For information on implementing the
looping condition, see “Creating composite transactions with looping logic” on
page 297.

Understanding when to use composite XML transactions
You can consider using a Composite XML transaction to group related business
transactions that you want executed in one unit of work. Also if you plan to
implement simple ″if-then-else″ or ″looping″ logic among these transactions, a
Composite XML transaction is also a good candidate. The Composite Transaction
Framework provides syntax in XML format that you can use to create composite
transactions easily to fulfill these requirements.
However, since single transactions in a composite are executed in one unit of work,
you should refrain from grouping too many single transactions in one composite.
The more single transactions there are in the composite, the longer it takes to
complete the unit of work, hence you are likely to face transaction timeout
problems. It is recommended you have no more than four single transactions in a
composite. The following sections demonstrate how to create composite transaction
requests, configure InfoSphere MDM Server to enable composite transactions and
to submit the requests to InfoSphere MDM Server.
In this section, you will learn:
“Understanding composite XML transaction syntax”
“Understanding basic composite transactions” on page 287
“Creating composite transactions with if-then-else logic” on page 295
“Creating composite transactions with looping logic” on page 297
“Providing error messages using the error handling service” on page 299
“Creating boolean expressions” on page 299
“Creating object-set expressions” on page 302
“Configuring the composite XML transaction” on page 304
“Understanding requirements for submitting composite XML transactions” on
page 305
“Understanding requirements for customizing the composite response” on page
306

Understanding composite XML transaction syntax
This section helps you to learn the XML data structure and syntax defined by the
framework, which you can use to create composite XML transactions.
The following sections describe how to create different types of composite XML
transactions that are supported by the product, which include:
v Basic composite transactions, which is a series of single transactions that get
executed sequentially
v Composite transactions with decision making, or if-then-else, logic
v Composite transactions with looping logic
Note: A composite transaction can contain only transactions or
transactions, but not a mixture of both in the same
composite. However, the data structure and syntax that you would use to create a
composite are the same, regardless whether the single transactions are

286

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

or . These sections use as
examples in the discussion. You can replace with
.

Understanding basic composite transactions
A basic composite transaction is a series of single transactions. As such, the main
body of a basic composite transaction contains two or more (or
) XML requests. To hold these individual XML requests, you
use the root tag , followed by the optional
XML data. The composite XML document references the
corresponding CompositeTransactionRequest.xsd for XML validation. For example:

...
...

Note: If the transactions are , you use the
CompositeAdminTransactionRequest.xsd.
See also:
“Example:
“Example:
“Example:
“Example:
“Example:

Reusing DWLControl values with GlobalFields”
Correlating the transactions in the composite” on page 288
Substituting values from another Request or Response” on page 289
Qualifying an object name with criteria” on page 291
Comparing strings” on page 292

“Example: Comparing numeric values” on page 292
“Example: Comparing dates” on page 293
“Examples of substitution” on page 293

Example: Reusing DWLControl values with GlobalFields
The optional XML data after the root tag contains the
DWLControl values that you can apply to any of the in the
XML request that follows. For example:

cusadmin
100
...
...

Chapter 26. Creating composite XML transactions

287

Licensed Materials – Property of IBM

100181

{ GlobalFields.requesterName }
{ GlobalFields.requesterLanguage }
...
...

...
...

100190

User1
200
...
...

...
...

In general, you define all the values in the and reuse
these values in every single transaction. The above example illustrates how you
can also explicitly specify these values in any individual transaction.
To reuse the values, use the format { GlobalFields.xxx }, where
xxx is the corresponding tag name within the tag.

Example: Correlating the transactions in the composite
Correlating the transactions refers to the mechanism with which to label a
particular single transaction in the unit of work. The reason for correlating the
transactions is obvious-it is to enable you to do things such as ″I want my third
request to use some values based on the first response″, for example.
To correlate the transactions in the composite, you specify a unique numeric ID
with the element in , as follows:

Cusadmin
100

100181

{ GlobalFields.requesterName }
{ GlobalFields.requesterLanguage }

111

288

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

...
...

100190

{ GlobalFields.requesterName }
{ GlobalFields.requesterLanguage }

555

...
...

You will learn how to use the correlator ID to refer to different parts of the
composite transaction in “Example: Substituting values from another Request or
Response.”

Example: Substituting values from another Request or
Response
Composite transactions use substitution expressions to substitute values in the
single request or requests at transaction time. That is, some values are not known
at the time of submitting the composite transaction, and are only known when the
values are resolved after the requests in the composite have been executed. A
substitution expression contains a backward reference to an attribute value. A
backward reference is defined as a reference to a part of a request or response in a
composite transaction. Substitution expressions enable you to replace attribute
values dynamically in any request during transaction time.
The syntax for specifying substitution expression is as follows:
{id.ref_num.ref_nature.[object_name_ref.]+attrib_name_ref}

Note: Substitution expressions can only include a backward reference to an
attribute of a business object; it cannot include a backward reference to a business
object.
The following list shows each symbol used in the syntax and its definition.
Symbol: {
The start of the substitution expression.
Value: This must be the { character.
Symbol: id
Constant string.
Value: This must be id.
For backwards compatibility, you can also use the constant strings Id,
transactionCorrelatorId or TransactionCorrelatorId.
Symbol: ref_num
The value must be one of the numeric correlator IDs that is specified in
one of the tags in the composite.
Value: A numeric value.
Chapter 26. Creating composite XML transactions

289

Licensed Materials – Property of IBM

Symbol: ref_nature
This value must be request or response. If this value is request, the
backward reference refers to the request object corresponding to the
correlator ID specified above; if this value is response, it refers to the
response object.
If this value is not specified, the response object is assumed.
Value: This must be request or response, or it can be left blank.
Symbol: object_name_ref
One or more business object names in the request or response. If more than
one name is specified, the reference will narrow to the last specified object
in the business object hierarchy.
If the object that you want to refer to in the object hierarchy is returned in
a collection, you must qualify the object name. You can do it in one of two
ways: (i) by index, or (ii) by evaluating criteria.
To qualify the object name by index, use the form [i], where i is the
0-based index. Use this form if you know the order in which the instances
are returned in the collection. However, if the desired position is not
present at runtime, an exception will be thrown.
To qualify the object name by evaluating criteria, use the form [where
criteria]. To learn how to use criteria to qualify an instance, see
“Example: Qualifying an object name with criteria” on page 291 and
“Examples of substitution” on page 293.
In general, qualifying an instance with criteria is more practical, since you
do not have control over the order in which InfoSphere MDM Server
returns objects.
Note: If an object name is defined as a collection in the object hierarchy
but the object name is not qualified in the substitution expression, an
exception will be thrown at transaction time. Conversely, If an object name
is defined as a single instance in the object hierarchy but the object name is
qualified, an exception will be thrown
Value: This must be a name in the request or response that resolves to a
business object.
Symbol: attrib_name_ref
This is mandatory as it refers to the attribute whose return value you want
substituted in new request object.
Value: This must be a name in the request or response that resolves to an
attribute in a business object.
Symbol: }
The end of the substitution expression.
Value: This must be the } character.
The following is a sample composite XML request that illustrates the use of
substitution.

...
...

290

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
100181

...
...

111

addPerson
TCRMPersonBObj
...
...

...
...

100190

...
...
555

addPartyInteraction
TCRMInteractionBObj

2002-07-29
...
...

{id.111.response.TCRMPersonBObj.PartyId}

...
...

Example: Qualifying an object name with criteria
When a child object of a parent object is defined as a collection, you can qualify
which instance in the collection you want to refer to with criteria. To do so, use the
form after an object name:
object_name[where criteria]

The most basic form of criteria is:
left_operand

comparison_operator

right_operand

Chapter 26. Creating composite XML transactions

291

Licensed Materials – Property of IBM

The left_operand must be an attribute name belonging to the object name being
qualified. The right_operand must resolve to a value or a keyword—see
“Understanding supported keywords” on page 301. The comparison_operator must
one of the following operators:
v = (equal to)
v != (not equal to)
v < (less than)
v <= (less than or equal to)
v > (greater than)
v >= (greater or equal to)
When you use one of these operators to compare an attribute with a value, you
should take into account of the data type of the attribute. There are specific
requirements when comparing: strings, numeric values, and dates.
Similar to most programming languages, you can create more complex criteria
using boolean operators, which include:
v ( ) (grouping)
v and (logical ’and’)
v or (logical ’or’)
There are a number of examples in “Examples of substitution” on page 293 that
illustrate the uses of criteria.

Example: Comparing strings
When you compare an attribute with a string value, the string value must be
enclosed with quotation marks. The following example shows the correct way to
compare the LastName attribute in a substitution expression.
{id.123.response.TCRMPersonBObj.TCRMPersonNameBObj[where LastName !=
'Smith'].PersonNameIdPK}

The following example shows an incorrect way to compare the LastName attribute
in a substitution expression.
{id.123.response.TCRMPersonBObj.TCRMPersonNameBObj[where LastName !=
Smith].PersonNameIdPK}

If the word Smith is not enclosed with quotation marks, the expression will throw
an exception at runtime time.
Currently, the only comparison operators that are valid for comparing strings are =
(equal to) and != (not equal to). The operators <, <=, > and >= are not
valid for string comparison. If you use one of these four operators, an exception
will be thrown.

Example: Comparing numeric values
When you compare an attribute with a numeric value, the numeric value must
appear in the expression as is. The following example shows the correct way to
compare the NameUsageType attribute in a substitution expression.
{id.123.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType > 2].
PersonNameIdPK}

The following example shows an incorrect way to compare the NameUsageType
attribute in a substitution expression.

292

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
{id.123.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType > '2'].
PersonNameIdPK}

When you compare numeric values, you can use any one of the six comparison
operators.

Example: Comparing dates
When you compare an attribute with a date value, the date value must be
wrapped in the date function—see “Understanding supported functions” on page
300. The date function is required to explicitly indicate that the value is a date.
The following example shows the correct way to compare the LastUpdateDate
attribute in a substitution expression.
{id.123.response.TCRMPersonBObj.TCRMPersonNameBObj[where LastUpdateDate >
date('2005-05-17 16:48:11.047')].
PersonNameIdPK}

The following example shows an incorrect way to compare the NameUsageType
attribute in a substitution expression.
{id.123.response.TCRMPersonBObj.TCRMPersonNameBObj[where LastUpdateDate >
'2005-05-17 16:48:11.047'].PersonNameIdPK}

If you do not wrap the date value with the date function, the framework assumes
that the value is a string and may not be able to compare the values correctly.
When you compare date values, you can use any one of the six comparison
operators.

Examples of substitution
The following examples show valid syntax that can be used in substitution
expressions.
v Example 1:
{id.123.response.TCRMPersonBObj.PartyId}

Gets the PartyId from the TCRMPersonBObj object. The TCRMPersonBObj object
comes from the response that has a correlator ID 123.
v Example 2: This example shows the most basic form of substitution expression.
{id.222.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType = 1].
PersonNameIdPK}

Gets the PersonNameIdPK from the TCRMPersonNameBObj object where the
NameUsageType equals 1. The TCRMPersonBObj object comes from the
response that has a correlator ID 222.
v Example 3: This example shows the use of criteria to compare a numeric value.
{transactionCorrelatorId.222.TCRMPersonBObj.TCRMPersonNameBObj
[where LastName = 'Smith'].PersonNameIdPK}

Similar to above. When the ″.response″ symbol is omitted, the response object is
assumed. Also, you can use transactionCorrelatorId instead of id. The symbol
transactionCorrelatorId is retained for backwards compatibility purposes.
v Example 4: This example shows the use of criteria to compare a string value.
{id.111.request.TCRMPersonBObj.TCRMPartyAddressBObj[2].StartDate}

Gets the StartDate from the third TCRMPartyAddressBObj object. The
TCRMPersonBObj object comes from the request that has a correlator ID 111.
v Example 5: This example shows the use of criteria by index.
Chapter 26. Creating composite XML transactions

293

Licensed Materials – Property of IBM
{id.333.response.TCRMPersonBObj.TCRMPartyContactMethodBObj[where
PartyContactMethodIdPK = 9900].TCRMPartyContactMethodPrivPrefBObj
[where EndDate = date('2005-12-31 12:00:00.000')].StartDate}

Gets the StartDate from the TCRMPartyContactMethodPrivPrefBObj object whose
end date is equal to the date specified. The
TCRMPartyContactMethodPrivPrefBObj object belongs to the
TCRMPartyContactMethodBObj object whose PartyContactMethodIdPK equals 9900.
The TCRMPersonBObj object comes from the response that has a correlator ID 333.
v Example 6: This example shows the use of criteria in more than one object in the
object hierarchy. It also shows the use of criteria to compare a date value.
{id.444.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType != 1 and
PrefixType = 12].LastName}

Gets the LastName from the TCRMPersonNameBObj object where the NameUsageType
does not equal 1 and PrefixType equals 12. The TCRMPersonBObj object comes
from the response that has a correlator ID 444.
v Example 7: This example shows the use of boolean and comparison operators to
create more complex criteria.
{id.555.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType =
id.200.request.TCRMPersonBObj.TCRMPersonNameBObj.NameUsageType].LastName}

Gets the LastName from the TCRMPersonNameBObj object where the NameUsageType
equals the NameUsageType from the TCRMPersonNameBObj object in the request
that has a correlator ID 200. The TCRMPersonNameBObj is a part of the
TCRMPersonBObj object from the response that has a correlator ID 555.
This example shows that the right-hand side of a comparison operator can be a
fully qualified name that refers to another part of the composite transaction. In
previous examples, the right-hand side value is a constant.
v Examples 8-12: The following are some examples of invalid substitution, which
will cause exception to be thrown either during parsing or transaction.
{id.555.response.TCRMPersonBObj.TCRMPersonNameBObj[where
id.200.request.TCRMPersonBObj.TCRMPersonNameBObj.NameUsageType =
NameUsageType].LastName}

This example is similar to the last valid example given above, except that the
left-hand side and right-hand side values of the comparison operator are
reversed. The syntax requires that the left-hand side value be an attribute of the
object being qualified. By definition, an attribute name cannot contain any
period, hence an exception will be thrown during parsing time.
{id.234.response.TCRMPersonBObj.TCRMPartyAddressBObj[2]}

This example is syntactically incorrect because the last symbol in the substitution
cannot be qualified with an index. An exception will be thrown during parsing
time.
{id.234.response.TCRMPersonBObj.TCRMFinancialProfileBObj}

This example is syntactically correct and can be parsed successfully. However,
this substitution does not evaluate to a value since TCRMFinancialProfileBObj is
a business object. The backward reference used in the substitution expression
must resolve to an attribute. This example will throw an exception at transaction
time.
{id.234.response.TCRMPersonBObj.TCRMPersonNameBObj[where LastName = Smith].
PersonNameIdPK}

This example is syntactically incorrect because the string value being compared
is not enclosed with quotation marks. An exception will be thrown during
parsing time.
{id.234.response.TCRMPersonSearchResultBObj.PartyId}

294

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

This example is syntactically correct and can be parsed successfully. However, if
the request producing this response is an searchPerson transaction, the
transaction will return zero or more instances of the
TCRMPersonSearchResultBObj objects in a collection. By not qualifying which
TCRMPersonSearchResultBObj object you want to refer to, this example will throw
an exception at transaction time.

Creating composite transactions with if-then-else logic
A composite transaction with ″if-then-else″ logic allows you to select which single
requests to execute based on some condition. It is an extension of the basic
composite transaction. Refer to “Understanding basic composite transactions” on
page 287 before continuing with this section.
The XML construct for the ″if-then-else″ logic in the composite XML transaction is
very similar to the XSLT syntax. To include ″if-then-else″ logic in a
composite XML, use this syntax:

...
...

The XML must contain one or more XML, and zero or one
XML. Each XML corresponds to the ″if″ or ″else-if″ condition,
and the XML corresponds to the ″else″ condition. Only one of these
condition will be met.
Between the and XML tags, you can include one or more
(or ) XML requests. When the boolean expression
for that condition is evaluated to true, each of the requests will be executed.
You can also include another XML between the and XML
tags. This in effect allows you do nest ″if-then-else″ logic.
Similar to the condition, between the and XML
tags, you can include one or more (or ) XML
requests, or another XML to create nesting logic. The
condition is met only if none of the conditions has the boolean expression
evaluated to true. Another XML data that you can include is the XML.

Chapter 26. Creating composite XML transactions

295

Licensed Materials – Property of IBM

The XML provides a way to provide a meaningful business error
message when the condition is met. The XML is explained
in “Providing error messages using the error handling service” on page 299.
The following is an sample composite XML transaction with ″if-then-else″ logic.
There are two requests in this composite: searchPerson and getPerson. The
″if-then-else″ logic is as follows:
1. Do a searchPerson transaction.
2. If the searchPerson transaction returns exactly 1 match, do a getPerson
transaction of inquiry level 1 to get all details about the person. Otherwise,
produce a business error message.

...
...

100181

...
...
111

searchPerson
TCRMPersonSearchBObj
...
...

100190

...
...
555

getPerson

{ id.111.response.TCRMPersonSearchResultBObj.PartyId }

296

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The correlator ID for the searchPerson transaction in this composite is 111. One
or more (or ), another or
.

Creating composite transactions with looping logic
A composite transaction with looping logic allows you to iterate through a
collection of objects and executes other requests based on each object. It is an
extension of the basic composite transaction. (Refer to “Understanding basic
composite transactions” on page 287 before continuing with this section.)
The XML construct for the looping logic in the composite XML transaction is very
similar to the XSLT syntax. To include looping logic in a composite
XML, use this syntax:

...
...

The XML tag contains a mandatory select attribute and a var
attribute. The select attribute points to an object-set-expression, which is the kind
of expression that will be evaluated to a collection of objects at runtime. The var
attribute is a reference name that you can give in order to associate it with each
object in the collection when the collection is iterated through. When the reference
name is used in the rest of the composite, the reference name must be prefixed
with a $ character.
Between the and XML tags, you can include one or more
(or ) XML requests. When the object-set
expression is evaluated to return a collection of objects, each of the requests will be
executed as many times as there are objects in the collection. You can also include
another XML between the and XML tags. This in
effect allows you do further qualify the loop with ″if-then-else″ logic.
The following is a sample composite XML transaction with looping logic. There are
two requests in this composite: getPerson and updatePartyAddress. The looping
logic is as follows:
1. Do a getPerson transaction for party ID 3004000123.
2. For each of the TCRMPartyAddressBObj objects returned from the
TCRMPersonBObj:
v If the EndDate has not been set, update the StartDate.
v Otherwise, just produce an error message.

...
...

100181

...
...

111

getPerson

Chapter 26. Creating composite XML transactions

297

Licensed Materials – Property of IBM

3004000123
3/tcrmParam>
...
...

100190

...
...
555

updatePartyAddress
TCRMPartyAddressBObj

{$anAddress.PartyAddressIdPK}

{$anAddress.PartyId}
2000-01-31
...
...

Address already expired

For more information on object-set expressions, see “Creating object-set
expressions” on page 302.
For more information on boolean expressions, see “Creating boolean expressions”
on page 299.
For more information on substitution expressions, see “Example: Substituting
values from another Request or Response” on page 289.
For more information on looking up error messages, see “Providing error messages
using the error handling service” on page 299.

298

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Providing error messages using the error handling service
In a lot of the cases, when the condition is met after all the expected
conditions fail — that is, if none of the conditions is met — you would
like to provide a meaningful message in the response describing the situation. You
can use the XML tag provided by the Composite Transaction
Framework to retrieve the message from the database.
The benefits of using the XML are:
v The XML syntax is short and easy to remember.
v All messages are centralized in the database and retrievable through the error
handling service.
v Messages can be language specific.
The syntax for the XML tag is:
default_description

The errorId and lang attributes correspond to the key fields needed to query the
database for the error message. The default_description value is the String that will
be used if the error message cannot be retrieved from the database.

Adding error messages to the database
If you want to add an error message to the database for the XML to
retrieve, you must add a record to the ERRREASON table and one to the
CDERRMESSAGETP table. For example, if you want to add the error message
?Default error message for composite transaction? for errorId 200000 and lang 100
(assuming that the lang value 100 is already in the CDLANGTP table), you must
add these records in the two tables:
v ERRREASON
v CDERRMESSAGETP
Note: In the ERRREASON table, the ERR_REASONTP_CD and
ERR_MESSAGE_TP_CD values are the errorId and must be the same in the record.

Creating boolean expressions
A boolean expression is used in the test attribute of the XML tag. The
boolean expression should evaluate to true or false. When the expression evaluates
to true, the corresponding condition is met, the content between the
and XML tags will be executed.
The most basic form of a boolean expression is:
left_operand operator right_operand

where operator is one of the logical or comparison operators. Similar to most
programming languages, you can use a combination of operators to operate on a
number of operands, to create more complex boolean expressions.
For example, the following boolean expression will test whether the person’s last
name is ″Smith″:
id.222.response.TCRMPersonNameBObj.LastName = 'Smith'

Chapter 26. Creating composite XML transactions

299

Licensed Materials – Property of IBM

Note: In the above example, the left operand is very similar to the backward
reference format used in substitution expressions. If you are not familiar with
substitution expression and backward reference, refer to “Example: Substituting
values from another Request or Response” on page 289 before continuing with this
section.
A slightly more complex boolean expression is:
id.222.response.TCRMPersonNameBObj.LastName = 'Smith' and
id.222.response.TCRMPersonNameBObj.GivenNameOne = 'John'

This boolean expression will test whether the person’s last name is ″Smith″ and
first name is ″John″.

Understanding the position of the operand
In some programming languages, there is no restriction on whether an operand
appears on the left-hand side or right-hand side of the operator. For example, the
expression LastName = ’Smith’ and the expression ’Smith’ = LastName are both
allowed. This is, however, not the case with boolean expressions used in composite
XML transaction.
In composite XML transaction, the left-hand side operand in a boolean expression
can only be one of the following:
v A backward reference to an attribute value
v The count function—see “Understanding supported functions”
The right-hand side operand can only be one of the following:
v
v
v
v

A backward reference to an attribute value
A keyword—see “Understanding supported keywords” on page 301
A constant value—for example, ’John Smith’, ’Y’, 1234
The date function—see “Understanding supported functions”

If the wrong type of operand appears in the boolean expression, an exception will
be thrown at parsing time.

Understanding supported functions
The framework supports two functions that can be used in expressions:
v count
v date
The format of the count function is count(argument), where argument is a
backward reference to a business object. The count function returns a numeric
value that equals to the number of occurrences of the specified business object.
For example, to test if there is no TCRMPersonSearchResultBObj returned in a
response:
count(id.111.response.TCRMPersonSearchResultBObj) = 0

Note: The count function can only be used in the left operand in an expression.
The count function is intended to test the number of occurrences in a collection,
hence the argument is expected to resolve to a collection at runtime. If the
argument resolves to a single instance, the count function will throw an exception.

300

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The format of the date function is date(argument), where argument is the string
representation of a date. The date function ensures that the string argument can be
converted into a date object.
For example, to test if the LastUpdateDate is equal to a specific date:
id.111.response.TCRMPartyBObj.PartyLastUpdateDate = date('2005-12-31 12:00:00.000')

Note: The date function can only be used in the right operand in an expression.

Understanding supported keywords
The only supported keyword is null. Use the null keyword with another backward
reference to test whether that reference exists or not.
For example, to test if the person’s alert indicator has not been set:
id.111.response.TCRMPersonBObj.AlertIndicator = null

To test if the person has no financial profile:
id.111.response.TCRMPersonBObj.TCRMFinancialProfileBObj = null

Note: Note: The null keyword is intended to be used with a backward reference
that resolves to a single instance. If the backward reference resolves to a collection,
an exception will be thrown.
See also:
“Examples of boolean expressions”

Examples of boolean expressions
The following examples show valid syntax that can be used in boolean
expressions:
v id.234.response.TCRMPersonBObj.PartyId = 454809
Tests if the PartyId of the TCRMPersonBObj object equals 454809. The
TCRMPersonBObj object comes from the response that has a correlator ID 234.
v id.444.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType =
1].LastName = 'Smith'
Tests if the LastName equals ″Smith″. The LastName is from the
TCRMPersonNameBObj object where the NameUsageType equals 1. The
TCRMPersonBObj object comes from the response that has a correlator ID 444.
v id.900.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType =
1].GivenNameTwo = null
Tests if the TCRMPersonNameBObj object where the NameUsageType is 1 has
no GivenNameTwo. The TCRMPersonBObj object comes from the response that
has a correlator ID 900.
v id.333.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType =
1].LastName = 'Smith' or
id.444.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType =
1].LastName = 'Smith'
Tests if the LastName equals ″Smith″ in either of the TCRMPersonNameBObj
objects, one coming from the response that has a correlator ID 333 and the other
that has a correlator ID 444.

Chapter 26. Creating composite XML transactions

301

Licensed Materials – Property of IBM

v id.333.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType =
1].LastName = id.444.response.TCRMPersonBObj. TCRMPersonNameBObj[where
NameUsageType = 1].LastName
Tests if the LastName from the TCRMPersonNameBObj object with the
correlator ID 333 equals the LastName from the TCRMPersonNameBObj object
with the correlator ID 444.
v count(id.042.response.TCRMPersonBObj.TCRMPartyAddressBObj) > 1
Tests if the number of TCRMPartyAddressBObj object is greater than 1. The
TCRMPersonBObj object comes from the response that has a correlator ID 042.
The following are some examples of invalid boolean expression, which will cause
exception to be thrown either during parsing or transaction.
v 454809 = id.234.response.TCRMPersonBObj.PartyId
This example is syntactically incorrect because the left operand cannot be a
literal. An exception will be thrown during parsing time.
v id.333.response.TCRMPersonBObj.TCRMPersonNameBObj[where NameUsageType =
1].LastName = 'Smith' and GivenNameOne = 'John'
You may attempt to write such an expression to perform a logical ″and″ on the
LastName and GivenNameOne of the same TCRMPersonNameBObj object.
However, this example is syntactically incorrect because GivenNameOne is not
qualified. An exception will be thrown during parsing time. If you do want to
write such an expression, the GivenNameOne attribute name must be prefixed
like the LastName attribute name.
v id.234.response.TCRMPersonBObj.PartyId = TCRMPartyAddressBObj[where
AddressUsageType = 1].PartyId
You may attempt to write such an expression to compare an attribute of a parent
object — that is, TCRMPersonBObj.PartyId — with another attribute of a child
object of the same parent object — that is,
TCRMPersonBObj.TCRMPartyAddressBObj[where AddressUsageType =
1].PartyId. However, this example is syntactically incorrect because the right
operand does not conform to the backward reference syntax. An exception will
be thrown during parsing time. If you do want to write such an expression, the
right operand must be prefixed with id.234.response.TCRMPersonBObj.
v id.900.response.TCRMPersonBObj.TCRMPersonNameBObj = null
This example is syntactically correct and can be parsed successfully. However,
the TCRMPersonBObj object returns zero or many instances of the
TCRMPersonNameBObj objects, in a collection. At runtime, the collection cannot
be operated on with the null keyword. Therefore, this example will throw an
exception at transaction time. If you do want to test if no
TCRMPersonNameBObj object is returned, you would write:
count(id.900.response.TCRMPersonBObj.TCRMPersonNameBObj) = 0

Creating object-set expressions
An object-set expression is used in the select attribute of the XML tag.
The object-set expression should evaluate to a collection of objects. When the
collection is returned, the content between the and XML
tags will be iterated through as many times as there are objects in the collection.
The following object-set expression returns all the TCRMPartyAddressBObj objects in
the TCRMPersonBObj object:
id.222.response.TCRMPersonBObj.TCRMPartyAddressBObj

302

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The object-set expression is very similar to the backward reference format used in
substitution expressions. The only difference is that the backward reference in an
object-set expression must resolve to an object, and not an attribute of an object. If
you are not familiar with substitution expression and backward reference, refer to
“Example: Substituting values from another Request or Response” on page 289
before continuing with this section.
See also:
“Examples of object-set expression”

Examples of object-set expression
The following examples show valid syntax that can be used in object-set
expressions:
v id.222.response.TCRMPersonSearchResultBObj
Loops through all the TCRMPersonSearchResultBObj objects from the response
that has a correlator ID 222.
v id.333.TCRMPersonBObj.TCRMPartyAddressBObj[where AddressUsageType =
1].TCRMPartyLocationPrivPrefBObj
Loops through all the TCRMPartyLocationPrivPrefBObj objects from the
TCRMPartyAddressBObj object where the AddressUsageType is 1. The
TCRMPersonBObj object comes from the response that has a correlator ID 333.
v id.111.request.TCRMPersonBObj.TCRMPartyAddressBObj[2].
TCRMPartyLocationPrivPrefBObj
Loops through all the TCRMPartyLocationPrivPrefBObj objects from the third
TCRMPartyAddressBObj object. The TCRMPersonBObj object comes from the
response that has a correlator ID 111.
v id.111.request.TCRMPersonBObj.TCRMPartyAddressBObj.
TCRMPartyLocationPrivPrefBObj
Loops through all the TCRMPartyLocationPrivPrefBObj objects from all the
TCRMPartyAddressBObj objects in the TCRMPersonBObj object. The TCRMPersonBObj
object comes from the response that has a correlator ID 111.
The following are some examples of invalid object-set expression, which will cause
exception to be thrown either during parsing or transaction:
v id.234.response.TCRMPersonBObj.PartyId
This example is syntactically correct and can be parsed successfully. However,
this expression resolves to an attribute name, and not an object. Therefore, this
example will throw an exception at transaction time.
v id.333.response.TCRMPersonBObj.TCRMPersonNameBObj[2]
This example is syntactically incorrect because an object-set expression cannot
end with an index. This example will throw an exception at parsing time.
v id.234.response.TCRMPersonBObj.TCRMFinancialProfileBObj
This example is syntactically correct and can be parsed successfully. However,
the TCRMPersonBObj object can have zero or one instance of
TCRMFinancialProfileBObj object; the TCRMFinancialProfileBObj does not exist
as a collection under the TCRMPersonBObj object. Therefore, this example will
throw an exception at transaction time.

Chapter 26. Creating composite XML transactions

303

Licensed Materials – Property of IBM

Configuring the composite XML transaction
As you see in “Understanding composite XML transaction syntax” on page 286, a
composite request and response adhere to a predefined format, which can be
considered as a grouping of TCRMService requests/responses or
DWLAdminService requests/responses. Following the Request Framework (see
Chapter 24, “Configuring the Request and Response Framework,” on page 269),
you need to configure a parser that knows how to parse the composite request and
a constructor that knows how to construct a composite response. You also need to
configure the BTM (Business Transaction Manager) to handle the composite
transaction object after parsing in order for the BTM to forward the object to IBM
InfoSphere Master Data Management Server for execution. These configurations
are already set up for you in the product, but it is worth mentioning in this section
for your reference.

Understanding the parser and constructor configuration
The parser and constructor for composite transactions are set up in the
DWLCommon_extension.properties file.
v CompositeParser.tcrm.DWLService=com.dwl.tcrm.coreParty.
composite.impl.XMLCompositeParserImpl
This property points to the composite parser that the Request Framework uses
to parse composite XML request for TCRMService (where the target application
is tcrm).
v CompositeConstructor.tcrm.DWLService=com.dwl.tcrm.coreParty.
composite.impl.XMLCompositeResponseConstructorImpl
This property points to the composite response constructor that the Request
Framework uses to construct composite XML response for TCRMService (where
the target application is tcrm).
v CompositeParser.DWLAdminService.DWLService=com.dwl.base.
admin.xml.composite.DWLAdminXMLCompositeParserImpl
This property points to the composite parser that the Request Framework uses
to parse composite XML request for DWLAdminService (where the target
application is DWLAdminService).
v CompositeConstructor.DWLAdminService.DWLService=com.dwl.base.
admin.xml.composite.DWLAdminXMLCompositeResponseConstructorImpl
This property points to the composite response constructor that the Request
Framework uses to construct composite XML response for DWLAdminService,
where the target application is DWLAdminServic).
v The values for these properties refer to the implementation parsers and
constructors that are provided with the product. Refer to the javadoc for
additional details about these implementation classes.

Understanding the Business Transaction Manager configuration
The Business Transaction Manager (BTM) handlers that handle the composite
transaction object are set up in the TxManager.properties file.
v com.dwl.base.requestHandler.composite.IDWLRequestBObj=
com.dwl.base.composite.txn.CompositeHandlerImpl
The property name is the type name of the object that is created after parsing. In
this case, it is the interface name of the composite request object. The value of
this property points to the BTM request handler implementation class provided
with the product.

304

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v com.dwl.base.requestHandler.composite.IDWLRequestBObj_response=
com.dwl.base.composite.txn.CompositeResponseHandlerImpl
The property name is the type name of the object that is created after parsing,
followed by ″_response″. The ″_response″ suffix indicates the use of a response
handler in the BTM. The response handler allows you to iterate through two or
more single transactions, within the same unit of work. The value of this
property points to the BTM response handler implementation class provided
with the product.
The use of a response handler is configured in conjunction with a delegate lookup.
The delegate lookup in the BTM provides the mechanism for ″chaining″ the
responses, within the same unit of work. The delegate lookup is set up in the
DelegateLookup.properties file.
v CompositeTxn=com.dwl.base.composite.txn.CompositeDelegateImpl
The property name is the transaction name to which the response handler
applies. In the Composite Transaction framework, a generic transaction name
CompositeTxn is used to indicate all composite transactions. The value of this
property points to the implementation class for the delegate lookup provided
with the product.
Refer to the Javadoc for additional details about these implementation classes.

Understanding requirements for submitting composite XML
transactions
Submitting a composite XML transaction is no different than submitting any single
transaction in InfoSphere MDM Server through the processRequest() method in
the DWLServiceController session bean:
processRequest(HashMap context, Serializable request)

In order to have InfoSphere MDM Server look up the correct parser and
constructor as described in Chapter 24, “Configuring the Request and Response
Framework,” on page 269, you need to use key/value pairs that are specific to
composite transactions in the context argument. For example:
HashMap context = new HashMap();
context.put("TargetApplication", "tcrm");
context.put("RequestType", "standard");
context.put("ResponseType", "standard");
context.put("CompositeTxn", "yes");
context.put("CompositeParser", "DWLService");
context.put("CompositeConstructor", "DWLService");
context.put("OperationType", "all");
context.put("requesterName", "cusadmin");
context.put("requesterLanguage", "100");

The key/value pairs that are essential for submitting a composite transaction are as
follows:
v The TargetApplication key must have a value of tcrm or DWLAdminService,
depending on the application.
v The CompositeTxn key must have a value of yes. If this value is set to no or this
key is missing, the transaction is not processed as a composite transaction.
v The CompositeParser key has a value of DWLService, in order to look up the
parser implementation class defined by the
CompositeParser..DWLService property in the
DWLCommon_extension.properties file.
Chapter 26. Creating composite XML transactions

305

Licensed Materials – Property of IBM

v The CompositeConstructor key has a value of DWLService, in order to look up
the constructor implementation class defined by the
CompositeConstructor..DWLService property in the
DWLCommon_extension.properties file.

Understanding requirements for customizing the composite response
The product provides two response constructors, one for application tcrm and the
other for DWLAdminService; see Chapter 24, “Configuring the Request and Response
Framework,” on page 269. These constructors append every single response in the
composite XML response and put them under a root tag.
These two constructors extend the AbstractCompositeResponseConstructor class. If
you want to customize your own response constructor, you should create your
constructor by extending the AbstractCompositeResponseConstructor class. You
may consider customizing your own response constructor if you want to use a
different root tag for the individual response or the composite response, or if you
want to validate the composite response against another DTD or schema.
The AbstractCompositeResponseConstructor class contains several abstract
methods that you need to override:
v setApplicationName()—Calls the setApplicationName(String) method to
override the application name of the individual response.
v setTxnResponseRoot()—Calls the setTxnResponseRoot(String) method to
override the root tag of the individual response.
v modifyXMLHeader(XMLHeader)—Calls the setter methods of the XMLHeader
argument to override attributes—for example, the root tag, DTD/schema—of the
XMLHeader argument. The XMLHeader object provides callback methods for the
AbstractCompositeResponseConstructor class to call when constructing the
composite response.
To use your customized constructor, follow the instructions in Chapter 24,
“Configuring the Request and Response Framework,” on page 269 to add a
property in the DWLCommon_extension.properties file, and the instructions in
“Understanding requirements for submitting composite XML transactions” on page
305 to set the CompositeConstructor key in the context when submitting the
composite request.

306

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 27. Understanding the response publisher
The InfoSphere MDM Server response publisher component integrates with other
enterprise applications or integration products such as WebSphere Business
Integration. The Request and Response Framework can publish a transaction
response to a JMS queue before returning it to the caller.
In this section, you will learn:
“Understanding the response publisher and extension framework”

Understanding the response publisher and extension framework
The response publisher functionality is implemented using the extension
framework. The extension can be configured to execute on various conditions;
these conditions are driven by the input context parameters passed in with the
transaction. By default this extension is turned off.
See also:
“To enable the extension framework for the response publisher transaction”
“To publish a transaction” on page 308

To enable the extension framework for the response publisher
transaction
1. Run the following SQL statement:
UPDATE EXTENSIONSET SET INACTIVE_IND = 'N'

where JAVA_CLASS_NAME = 'com.dwl.base.integration.DWLResponsePublisher'
This SQL enables the response publisher Java extension for the following
predefined transactions:
v addContract
v addPerson
v getContract,
v getPerson
v searchPerson
v updateContract
Note: The response publisher is not restricted to the six predefined
transactions. You can enable another transaction to be published.
2. Restart the application server where InfoSphere MDM Server is deployed, so
that the SQL update takes effect.
Once activated the Java extension publishes the response based on the
following conditions in the context parameters:
v Transaction_Type with a value of P. Possible values for transaction type can
be P (Persistant transactions), I (Inquiry transactions), S (Search transactions).
v Transaction_Name with a value of addContract, or any of the defined
transactions in the database.
v TargetApplication with a value of tcrm.
v Constructor with a value of TCRMService.
© Copyright IBM Corp. 1996, 2009

307

Licensed Materials – Property of IBM

These conditions can be customized to meet your requirements. For example, it
is possible to configure the extension to publish all transactions based on only
the value of TargetApplication. See Chapter 2, “Customizing InfoSphere MDM
Server,” on page 17 for more details on how to configure extensions.
3. Ensure that a queue is configured within your JMS provider and that the queue
is bound to the default JNDI name before using the response publisher.
By default, the Java extension publishes the response to a JMS queue. The
default JNDI names used by the Java extension are as follows:
v Queue Connection Factory=com/dwl/integration/QueueConnectionFactory
v Queue=com/dwl/integration/IntegrationQueue

To publish a transaction
1. Modify and run the following SQL statements accordingly:
INSERT INTO CDCONDITIONVALTP VALUES (,9,,'transaction type',
CURRENT TIMESTAMP);
INSERT INTO CDCONDITIONVALTP VALUES (,15,'',
'transaction name',CURRENT TIMESTAMP);
INSERT INTO CDCONDITIONVALTP VALUES (,13,'tcrm','application name',
CURRENT TIMESTAMP);
INSERT INTO CDCONDITIONVALTP VALUES (,14,'TCRMService','reponse
constructor name',CURRENT TIMESTAMP);
INSERT INTO EXTENSIONSET VALUES (,'for transaction
','extension to publish response objects',
'com.dwl.base.integration.DWLResponsePublisher',null,1,'Y',4,'N',1,CURRENT
TIMESTAMP,'user defined');
INSERT INTO EXTSETCONDVAL VALUES (,< VAL_TP_PK1>,,
CURRENT TIMESTAMP,null);
INSERT INTO EXTSETCONDVAL VALUES (,< VAL_TP_PK2>,,
CURRENT TIMESTAMP,null);
INSERT INTO EXTSETCONDVAL VALUES (,< VAL_TP_PK3>,,
CURRENT TIMESTAMP,null);
INSERT INTO EXTSETCONDVAL VALUES (,< VAL_TP_PK4>,,
CURRENT TIMESTAMP,null);

2. Write extensions to perform other operations if necessary.

308

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 28. Understanding batch transaction processing
There are two ways to perform batch transaction processing.
Based on your implementation, you can use either InfoSphere MDM Server J2SE
Batch processor framework, or the InfoSphere MDM Server WebSphere Extended
Deployment batch framework, if you use WebSphere Application Server. The
InfoSphere MDM Server WebSphere Extended Deployment batch framework is a
feature in InfoSphere MDM Server.
The J2SE Batch processor framework is a J2SE client application. You can use this
framework to run transactions in a batch mode or to build custom batch jobs.
The InfoSphere MDM Server WebSphere Extended Deployment batch framework
includes a Long Running Execution Environment (LREE) and a batch application
framework. The batch application runs within the LREE, which itself is a J2EE
enterprise application. You can use this framework to run batch jobs.
InfoSphere MDM Server J2SE Batch Processor framework
v The InfoSphere MDM Server J2SE batch processor framework reads the batch
input, delegates the call to the service interface for server-side processing, and
writes the response to the batch output.
v Using this application, you can run transactions in a batch mode for default
formatted input and output file and data, for example, line-delimited XML
requests and responses. Using batch framework for this purpose involves
preparing batch input and configuring various batch framework parameters.
InfoSphere MDM Server WebSphere Extended Deployment Batch framework
v Using the InfoSphere MDM Server WebSphere Extended Deployment Batch
framework you can run existing transactions in a batch mode for ready-to-use
input and output file and data formats; for example, line-delimited XML
requests and responses. To run existing transactions in batch mode, you must
prepare the batch input and the batch job, and configure various XJCL batch job
parameters.
v You can also build custom batch jobs to run custom transactions, and to support
custom input and output files and data formats. Custom transactions can use
your additions or the composite transactions built using composite business
proxies which run transactions internally. To build custom batch jobs, you need
to write and deploy one or more Java plug-ins, in addition to preparing the
batch input and batch job, and configuring various batch job parameters.
In this section, you will learn:
“Understanding the InfoSphere MDM Server J2SE batch processor architecture”
on page 310
“Designing J2SE batch input and output” on page 311
“Running J2SE Batch Processor batch jobs” on page 312
“Configuring the J2SE batch processor” on page 312
“Managing J2SE batch throughput” on page 315
“Reviewing J2SE errors and logs” on page 316

309

Licensed Materials – Property of IBM

“Building custom batch jobs for the J2SE Batch Processor framework” on page
316
“Understanding the InfoSphere MDM Server WebSphere Extended Deployment
Batch architecture” on page 317
“Creating XJCL for batch jobs” on page 318
“Running XJCL batch jobs” on page 321
“Reviewing XJCL errors and logs” on page 321
“Building custom batch jobs for the InfoSphere MDM Server WebSphere
Extended Deployment batch processor” on page 321

Understanding the InfoSphere MDM Server J2SE batch processor
architecture
The batch processor is a multithreaded, long-running application that can process
large volumes of batch data.
It can process multiple records from the same batch input simultaneously, and
increase the throughput. Additionally, you can run multiple instances of the batch
processor simultaneously, each one processing a separate batch input and pointing
to the same server, or a different server.
The batch processor architecture diagram shows a high-level view of the batch
processor application.

Each batch record in the batch input flows through the batch processor in the
following sequence:
1. The reader consumer reads the record from the batch input. A pluggable reader
is used to read each record. The reader distinguishes each record in the batch
input. The reader does not dissect the record into fields; that is done by the
parser. See the section on building custom batch jobs for information about
developing a custom reader.
2. Once the record is read, the submitter consumer sends it to the
Request/Response framework for parsing and processing. Selecting the parser
is based on the values passed in the context parameter of the server request.
The parser transforms the input request into one or more business objects. After
passing through business proxy, business processing and persistence logic are
applied to the business objects. The application responses are sent to the

310

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

constructor in order to construct the desired batch output response. Similar to
the parser, selecting the constructor is based on the values passed in the context
parameter of the server request. The constructed response is returned to the
batch processor.
3. The pluggable writer consumer returns the response to the batch output
destination.
The batch processor handles each record in its unit of work. In other words, it
supports a checkpoint of one. You can define a threshold value to set the
maximum number of allowed exceptions. If the number of exceptions reaches this
threshold, the batch processor stops further processing of the current batch input
and logs runtime messages to a log destination. These logs are useful for
diagnosing and debugging issues. A number of runtime parameters are available
for configuration. Properties files are used for this configuration. For more
information on configuration option, see the section on running batch jobs.

Designing J2SE batch input and output
The batch processor application is not dependent on any specific batch input or
output source or data format. Instead, it has externalized the components that
perform reading, parsing, response construction, and writing tasks.
The batch processor is shipped with some pre-built readers and writers that can be
used as is; these tools are described later in this section. The Request/Response
framework also contains some parsers and constructors that can be used for a
given batch job.
If the batch input and output structures can be handled by a combination of the
pre-built readers, writers, parsers, and constructors, then you do not need to do
develop any external components. For example, if the batch input is an XML data
format where each line contains one XML request data and the expected output is
also XML with each line containing one XML response data, then you can use the
pre-built components to handle this input and output. However, if either the input
or output structure, or both, cannot be handled with the available components,
new pluggable components must be written. For more information, see the section
on building custom batch jobs for more information.
The available reader and writers are:
v File line reader—This can be used to read the batch input from a file where
each line in the file represents one record. This reader is implemented by the
com.dwl.batchframework.queue.FileReaderQueue class.
v File line writer—This writer writes the output to an output file with each batch
record on a separate line. This writer is implemented by the
com.dwl.batchframework.queue.FileWriterQueue class.
v Chained file writer—This writer writes the output to one or more output files.
The number of output files to write to is configured using the
Writer.properties file. The writer is implemented by the
com.dwl.batchframework.queue.WriterChainedQueue class.
v Extended file reader—This reader is able to read a variety of XML requests that
conform to the platform service request schemas such as TCRMService,
DWLAdminService, DWLCompositeServiceRequest, or any XML request that is
configurable via the properties file. In the process, the parser populates all
configuration properties that are necessary to inform the server for the request
parser, response constructor or target application. This reader is implemented by
the com.ibm.mdm.batchframework.queue.XFileReaderQueue class. To use this
Chapter 28. Understanding batch transaction processing

311

Licensed Materials – Property of IBM

reader, in addition to the usual property definitions, a property TxTokens with
the value of the top level element of the XML request (that is, TCRMService,
DWLAdminService, or DWLCompositeServiceRequest) must be included in the
batch_extension.properties file. Here is an example:
ParseAndExecConfiguration.TxTokens=TCRMService. The value of the TxTokens
field can not be used anywhere in the body of the request XML. Default
namespace XML files are supported, but DTD files are not.
For more information on available parsers and constructors, see the section on
configuring the Request/Response framework.

Running J2SE Batch Processor batch jobs
A batch startup script is provided within the Batch Processor distribution. The
script is named runbatch.sh within the bin folder. Depending on where the
application server files are installed, some script variables must be set—see the
script for more details.
The following parameters are passed to the runbatch script. These are positional
parameters and must be passed in this sequence:
v Input URL—Mandatory parameter. The Input URL points to the batch input
source. For file-based input, this is the absolute or relative path along with file
name of the input file.
v Output URL—Mandatory parameter. The Output URL points to the batch
output destination. For file-based input, this is absolute or relative path along
with file name of the output file.
v Batch Extension Properties file—Optional parameter. Name of the extension
batch properties file, which contains additional batch configurations.
Once started, the Batch Processor starts processing the batch records by reading
them from the specified input, dispatching them for server-side processing and
then writing the response into the specified output.
Note: If multiple instances of processors are used, the sequence in which records
are processed is not guaranteed, and the output records may not be in the same
order as the input records. If batch records must be processed in the order
specified by the batch input, you must set the number of consumer instances to 1
for all consumers.
Once the Batch Processor has read all of the input records and has written their
corresponding results to the output, the Batch Processor terminates. On
termination, the status displays the number of records processed, and the time it
took to process the batch is shown in milliseconds

Configuring the J2SE batch processor
You must configure the batch processor on both the client-side and server-side.
On the client-side, there are configuration options for readers, writer, server
connectivity, throughput control, logging and others. On the server-side you must
configure the parsers, constructors, business proxy, and other settings.
The following properties files are used to configure the batch processor’s
client-side.

312

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Batch.properties
Contains some of the core configuration options for the batch processor.
#--------------------------------------------------------# Application setting
# Maximum number of business application exceptions allowed
# Examples are party not found or parser error.
# Value of -1 implies ignore any exceptions
#--------------------------------------------------------MaxExceptionsAllowed = -1
#--------------------------------------------------------# Memory monitoring configuration
# Application monitors memory and suspends reading from
# input if free memory drops too low.
# suspendReadOnMemory is percentage of JVM memory such that
# when free memory falls below this percentage, reader is suspended.
# resumeReadOnMemory is percentage of JVM memory such that a
# suspended reader is resumed once free memory exceeds this limit.
# suspendDuration is time in ms to nap when low memory detected.
# After this time, memory is checked again and we either
# resume or sleep again.
#--------------------------------------------------------suspendDuration = 200
suspendReadOnMemory = 10
resumeReadOnMemory = 15
#--------------------------------------------------------# If deadlocks are occuring, this value may be used to randomize
# the order that records from the input are passed on for
# processing. Each block of 'x' records are read from input
# as a group, then passed on in random order. Only blocks
# of records are randomized on the assumption that all 'x'
# records will be completed before starting to process the
# next record. Set to 0 or less to disable randomization.
#--------------------------------------------------------randomizedWindowSize = 0
#--------------------------------------------------------# deadlockRetryErrorCodes contains a comma-separated list of
# error codes that should be considered as indicative of a
# deadlock situation on the server. If any of these errors
# are returned from the server, retry the request. The maximum
# number of retries are set by deadlockMaxRetries. Set the
# list to an empty list or retries to 0 or less to disable
# retries.
# When specify the error codes in deadlockRetryErrorCodes,
# they should be unique strings of indication for the errors
# happened in the transaction.
# In some cases where possible, wrap the error codes with
# XML Tags as whole strings.
#
#--------------------------------------------------------deadlockRetryErrorCodes =
deadlockMaxRetries = 0
#--------------------------------------------------------# Settings to automatically adjust consumer counts to maintain
# a desired throughput, or to periodically report the
# throughput.
# To use either auto-adjust or reporting, you must set
# throughputSampleTime. This is a time (in seconds). Once
# every x seconds (x=throughputSampleTime), various measurements
# are taken of the application performance.
# Auto-adjust:
# maximumThroughput set desired maxium processing records number per minute, only advance user
# is encouraged to set it a positive value:
# set -1 to disable auto adjust
# set 0 to let the auto adjust process to reach maxium throughput within system's capacity
# set positive value N: if N < maxium throughput then auto adjust process will
# try to reach throughput N but not beyond it; if N >= maxium throughput then auto adjust process
# will try to reach maxium throughput.
# Auto-adjust also requires that the 'Processors'
# setting below has exactly 3 entries: a reader, a submitter,
# and a writer. The number of 'submitter' consumers is adjusted
# to affect throughput. Throughput is averaged over a sliding
# time scale, looking at average performance over the period
# of time in throughputWindowSize (minutes).
# throughputWindowSize*15 must be greater than the value
# of throughputSampleTime (eg, throughputSampleTime=2 (s) and
# throughputWindowSize=2 (min) would be fine). This is
# required so that there are enough performance samples taken
# to get a reasonable average throughput.
# Reporting:
# throughputReportingPeriod is the time in minutes between
# reporting average throughput. Throughput is reported in
# records per minute, averaged over the reporting period.
# Reporting does not depend on the number of entries in
# 'Processors'. Set to -1 to disable reporting.
# The auto-adjust feature does not require reporting in order
# to function, and reporting does not require auto-adjust to
# be enabled.
#--------------------------------------------------------maximumThroughput = -1
throughputSampleTime = -1
throughputWindowSize = -1
throughputReportingPeriod = -1
#--------------------------------------------------------# Server setting

Chapter 28. Understanding batch transaction processing

313

Licensed Materials – Property of IBM
# timeout is in seconds, 0 is infinite, default is 5 minutes
#--------------------------------------------------------ServerConfiguration.provider_url =
ServerConfiguration.jndi_prefix =
ServerConfiguration.timeout = 0
#ServerConfiguration.context_factory = com.ibm.websphere.naming.WsnInitialContextFactory
ServerConfiguration.context_factory =

#--------------------------------------------------------# If remote call fails (i.e RemoteException) specify below
# number of maximum number of retries to attempt and the time interval
# between. This exception is considered critical and will
# halt further processing
# Typical values:
# MaxTries = 1
# RetryDelay = 5000 ms (i.e 5 seconds)
#--------------------------------------------------------ServerConfiguration.MaxTries = 1
ServerConfiguration.RetryDelay = 5000
#--------------------------------------------------------# MULTI INSTANCE NAME (JNDI)
#
# This sepcifies the Customer instance name to reference to.
# Default values:
# instance_name =
# - configure next line (if nec)
#--------------------------------------------------------ServerConfiguration.instance_name =
#Queue setting
ReaderQueue = com.dwl.batchframework.queue.FileReaderQueue
#ReaderQueue = com.ibm.mdm.batchframework.queue.XFileReaderQueue
#WriterQueue = com.dwl.batchframework.queue.FileWriterQueue
WriterQueue = com.dwl.batchframework.queue.WriterChainedQueue
TransitQueue = com.dwl.batchframework.queue.FIFOQueue
#Processor setting
#--------------------------------------------------------# Processor settings
#
# Processors - list of processors to create
#
# number - number of consumers to create for this processor
# classname - full classname of consumer for this processor
# prime - number of records required in in-queue
# startout - start out in ms. If less than one, will start out
# depending on prime setting only.
# processors are started either by prime or timeout setting,
# hence whichever comes first.
#--------------------------------------------------------Processors = Reader,Submitter,Writer
Reader.number = 1
Reader.classname = com.dwl.batchframework.consumers.ReaderConsumer
# Initial consumer number for submitter processor. Advanced user can make change,
# but number should not be greater than 100.
Submitter.number = 5
Submitter.classname = com.dwl.batchframework.consumers.ParseAndExecuteConsumer
Writer.number = 1
Writer.classname = com.dwl.batchframework.consumers.WriterConsumer
#---------------------------------#Input/Output Data file encoding
#---------------------------------com.dwl.batchframework.queue.FileReaderQueue.encoding=UTF-8
com.dwl.batchframework.queue.FileWriterChainedQueue.encoding = UTF-8
com.dwl.batchframework.queue.FileWriterQueue.encoding = UTF-8
com.dwl.batchframework.queue.QAWriter.encoding = UTF-8
com.ibm.mdm.batchframework.queue.XFileReaderQueue = UTF-8
############################################################################################
#BatchProcessor's SuccessWriter ignores MDM success response and just print out BatchMessage
#messageID. It is unnecessary to set MDM success response to Writer Queue. It can cause
#MemoryUsage increase and memory leak.
############################################################################################
setMDMSuccessResponseToQueue=false
#############################################################################################
#Use BatchProcessor to load multiple input data files.
#Define sif input data location,sif input data file names,and log file location
#Execute runbatch.sh without any argument
# e.g.
#SIF_INPUT_PATH=/usr/IBM/MDM/BAR_MDM850_12032008_1210_DB2_BE01/BatchProcessor/
#SIF_INPUT_FILE_NAMES=Party.sif,Contract.sif
#SIF_OUTPUT_PATH=/usr/IBM/MDM/BAR_MDM850_12032008_1210_DB2_BE01/BatchProcessor/logs
##############################################################################################
SIF_INPUT_PATH=
SIF_OUTPUT_PATH=
SIF_INPUT_FILE_NAMES=

Configuration options contained in this file belong to one of the following
categories:

314

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Server connectivity parameters, the server URL, connection timeout and
others
v Reader/Writer classes, the reader and writer classes to use for this batch
job and the encoding scheme to use to read and write the files
v Throughput control parameters, which can be controlled by following
properties:
– Number of consumer instances, which controls the number of
consumer thread to create for concurrent processing of the respective
processing step
– Memory monitoring configuration, which monitors memory and
suspends reading from input if free memory drops too low, after free
memory exceeds the setting limit, the reader is resumed.
– Throughput auto adjustment, which controls the throughput in a
range
– Throughput reporting, which controls the reporting throughput
v Deadlocks Control configuration, which allows the user to specify a
number of records to be read as a group, then passed on for processing
in a random order. Also allows identifying deadlock-related error codes
and a retry count. If server-side processing results in an error with one
of the specified error codes, the transaction is retried up to the specified
limit.
v Error threshold — Maximum number of errors allowed for a given batch
run
batch_extension.properties
Contains parameters used by the batch processor to construct server-side
context before calling the DWLService controller. These context parameters
define the parser and constructor to be used for that request, among other
settings.
log.propertiesDWLLog.properties, JDKLog.properties, and Log4J.properties
Configuration items to manage log destination and level of detail
For details on these options, see the properties file. For server-side configuration
information, see the section on Chapter 24, “Configuring the Request and Response
Framework,” on page 269.

Managing J2SE batch throughput
Batch operators have a number of different options to increase their batch
throughput. If a bottleneck occurs on the client side, use one or both of the
following strategies:
v Multiple Batch Processor application runtime instances—This involves running
two more Batch Processor applications simultaneously. Each application instance
must work with a separate batch input and output; however they can share the
same server-side application instance or operate against a dedicated instance.
v Concurrent processing within a Batch Processor instance— As mentioned
before, Batch Processor is a multithreaded application that supports concurrent
processing of batch records. The number of threads—consumer processes—can
be configured in the Batch Processor configuration. In general, a higher number
of threads yields a higher throughput up to a certain limit. This limit is usually
defined by a number of factors including physical resources—such as CPU, disk
and memory on the client—or the server-side machine—complexity and size of
the request being processed and so on. Batch developers and operators should
Chapter 28. Understanding batch transaction processing

315

Licensed Materials – Property of IBM

test and tune throughput parameters to suite their environment to optimize
throughput. Since different consumer processes take different processing times,
the pacing option is available. Pacing enables you to slow down the upstream
processes if the downstream processes take too long to finish. This way, the
intermediate queues to hold the records do not fill-up and cause memory or
other runtime exceptions.
If the bottleneck is on the server-side, then servers can be scaled to meet the
throughput requirements. You can either:
v Increase the physical resources for the given server instance
v Add more server instances to create a cluster.

Reviewing J2SE errors and logs
If the server application returns an error, it is recorded in the batch output. If the
number of errors exceeds the maximum number of allowed errors, the batch run is
terminated.
Additionally diagnostic and debugging messages are logged into the log
destination. This is configured in the log.propertiesDWLLog.properties,
JDKLog.properties, and Log4J.properties files.

Building custom batch jobs for the J2SE Batch Processor framework
You can build custom batch jobs, in conjunction with the Request/Response and
Extension framework.
Building custom batch jobs are a good option when:
v The required batch input or output is not supported by the default components.
You can build one, all, or a combination of reader, writer, parser and constructor
components. Depending on your requirements, some pre-built components can
be used with the ones you develop for your requirements. For more information
see the sections on:
– Configuring the Request/Response Framework for information on developing
a custom parser and constructor
– Developing custom reader components
– Developing custom writer components
v The available transactions do not meet the requirements for the batch
transaction, The batch processor does not prescribe or depend on any specific
back-end transaction. If the back-end does not support the transaction required
by the batch job, you can develop a custom transaction. You can either:
– Write an addition transaction using the extension framework provided in
DWL common services
– Write a custom business proxy, a composite business proxy
– Write both, using existing back-end transactions internally
Each of these extension mechanisms are defined in their respective section of the
Developers Guide.

Developing custom reader components
The reader component of the batch processor reads the batch input and returns it
one record at a time. The batch processor does not depend on any specific batch

316

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

input; instead it relies on the reader to read the input by passing it the input URL
as passed from the command line arguments.
Any reader running within the batch processor implements the
com.dwl.batchframework.interfaces.IQueue interface. For more information on this
interface and its methods, see the Javadoc API.
Once the reader has been initialized, the batch processor invokes the Remove
method on the reader to remove one message from the read queue (the batch
input) and return it for subsequent processing.
The new reader implementation class must be configured into the batch processor
by setting the ReaderQueue property in the Batch.properties file.

Developing custom writer components
Similar to the way it uses a reader component, the batch processor delegates the
call to a writer component for writing the batch output. New writers can be
developed by implementing the com.dwl.batchframework.interfaces.IQueue
interface and setting the implementation class name as the value for WriterQueue
property in the Batch.properties file.
The IQueue interface, implemented by the reader and writer classes uses
com.dwl.batchframework.interfaces.IMessage interface to represent individual
record data. A default implementation of the IMessage interface
(com.dwl.batchframework.queue.BatchMessage ) is provided in the batch processor.
You can use this default implementation in your custom reader and writer classes
or you can build a new IMessage implementation.

Understanding the InfoSphere MDM Server WebSphere Extended
Deployment Batch architecture
WebSphere Extended Deployment Batch is a long-running batch application that
can process large volumes of batch data. Because it can process multiple batch jobs,
it is able to process multiple records from multiple batch inputs simultaneously,
increasing the throughput.
InfoSphere MDM Server WebSphere Extended Deployment Batch is a J2EE client
application that:
v Runs within the InfoSphere MDM Server WebSphere Extended Deployment
batch framework
v Reads the batch input
v Delegates calls to the Request/Response framework for server-side processing
v Writes the response to the batch output
The InfoSphere MDM Server WebSphere Extended Deployment Batch architecture
diagram shows a high-level view of the InfoSphere MDM Server WebSphere
Extended Deployment Batch application.

Chapter 28. Understanding batch transaction processing

317

Licensed Materials – Property of IBM

Each batch record in the batch input flows through InfoSphere MDM Server
WebSphere Extended Deployment Batch in the following sequence:
1. Submit the XJCL job to InfoSphere MDM Server WebSphere Extended
Deployment. This can be done using the Compute Grid Job management
console through a web browser or using the lrcmd command line tool. Refer to
the InfoSphere MDM Server WebSphere Extended Deployment product
documentation for more information.
2. Each record from the batch input is read by the stream implemented within the
InfoSphere MDM Server WebSphere Extended Deployment Batch application.
The stream distinguishes each record in the batch input, then loads and
processes the records in the InfoSphere MDM Server WebSphere Extended
Deployment Batch sequentially.
3. The InfoSphere MDM Server WebSphere Extended Deployment Batch
application then submits the records for business processing. After the business
and persistence logic is applied, the InfoSphere MDM Server WebSphere
Extended Deployment Batch application receives the response.
4. Finally, the response is written to the batch output destination by the output
batch data stream.
The InfoSphere MDM Server WebSphere Extended Deployment Batch application
handles each record in its unit of work. If an exception occurs during the
processing of a record, InfoSphere MDM Server WebSphere Extended Deployment
Batch stops further processing of the current batch input and logs runtime
messages to a log destination. The logs can be used for diagnosing and debugging
issues. At this point, the XJCL job fails; you can restart the job after you have fixed
the problem that caused the failure to occur.
A number of runtime parameters are available for configuration. XJCL files are
used for this configuration. See the section on “Creating XJCL for batch jobs” for
more details on configuration options.

Creating XJCL for batch jobs
The InfoSphere MDM Server WebSphere Extended Deployment Batch application
is driven by an XJCL batch job that defines the unit of work that has to be
processed by the application. It specifies input, output and log batch data stream
parameters.

318

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The following is a template for the XJCL batch job. It can be used as the basis for
creating a new XJCL batch job.

ejb/BatchJobStepController

sequential

com.ibm.wsspi.batch.checkpointalgorithms.recordbased

ejb/BatchJobStepProcessor

input
com.ibm.mdm.ws.batch.LineReaderBatchDataStream

output
com.ibm.mdm.ws.batch.LineWriterBatchDataStream

log
com.ibm.mdm.ws.batch.LogWriterBatchDataStream

You need to replace all values enclosed in angle brackets, <>, with values that
reflect your environment.
Another file reader can be used for enabling parsing of input files with
transactions that contain line feeds in them. To use the reader, change the
corresponding portion of the file above. The property TxTokens must specify the

Chapter 28. Understanding batch transaction processing

319

Licensed Materials – Property of IBM

top level element for the XML request, TCRMService, DWLAdminService, or
DWLCompositeServiceRequest, as the case may be.

input
com.ibm.mdm.ws.batch.MultiLineReaderBatchDataStream

Table 34. Parameters for XJCL batch job
Value

Description

Example

1
Specifies the number of records that
are processed before the checkpoint
algorithm performs global transaction
commit. In case of failure, the
transaction will be rolled back until
the last committed checkpoint.

Location and name of the input file,
containing records for processing.

C:/InputFolder/InputFile

Character encoding of the input file.

UTF-8

Location and name of the output file C:/OutputFolder/OutputFile
that will contain results of processing.

Character encoding of the output file.

Location and name of the log file that C:/LogFolder/LogFile
will contain the log for the
MDMBatch application.

MDMBatch application logging detail
level.

UTF-8

WARN

Character encoding of the log file.

UTF-8

Host name of the server running
InfoSphere MDM Server.

host.domain.com

Port number on which InfoSphere
MDM Server is listening for requests.

2809

User ID for the secure connection to
WebSphere Application Server if
security is enabled. If security is not
enabled on WebSphere Application
Server, leave this value empty.

wasuser

User password for the secure
connection to WebSphere Application
Server if security is enabled. If
security is not enabled on WebSphere
Application Server, leave this value
empty.

wasuserpassword

The user ID of the requester. The
cusadmin
requester name is validated by the
security service, and recorded when
audit information, such as last update
information, is captured.

The MDM code identifier for the
local of the requester; this locale is
used for NLS.

100

A template for creating batch jobs can be found in /MDMBatch/
MDMBatch_template_xjcl.xml, where is the location where
InfoSphere MDM Server is installed.
For more details on XJCL batch jobs see the WebSphere Extended Deployment
product documentation.

320

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

For more details on InfoSphere MDM Server, see the related InfoSphere MDM
Server product documentation.

Running XJCL batch jobs
Once an XJCL batch job is created, along with its corresponding input file, it can be
submitted to the Long Running Job Scheduler using either the Compute Grid Job
Management Console or using the lrcmd command line tool.
For more information on the Compute Grid Job Management Console or the lrcmd
command, refer to the WebSphere Extended Deployment product documentation.

Reviewing XJCL errors and logs
If the server returns an error while processing a record, the error is recorded in the
batch output and the batch job is terminated.
The Long Running Execution Environment will indicate that the batch job failed
and it will change the batch job’s state to restartable. At this point, you can inspect
the job logs to determine the reason for the failure. Once problem corrected, you
can restart the batch job, continuing execution from the last committed checkpoint.

Building custom batch jobs for the InfoSphere MDM Server
WebSphere Extended Deployment batch processor
The InfoSphere MDM Server WebSphere Extended Deployment batch processor
framework supports custom batch job development, in conjunction with the
Request/Response and Extension framework.
Two reasons to consider custom development are:
v The required batch input or output is not supported by out-of-the-box
components.
The solution to this scenario requires building one, all, or a combination of input
batch data stream, output batch data stream, parser and constructor components.
Depending on your requirements, some prebuilt components can be used with
ones you develop for your requirements.
See Chapter 24, “Configuring the Request and Response Framework,” on page
269 for information on developing a custom parser and constructor.
v The available transactions do not meet the requirements for the batch
transaction
The InfoSphere MDM Server WebSphere Extended Deployment batch processor
does not prescribe or depend on any specific back-end transaction. If the
back-end does not support the transaction required by the batch job, to solve
this scenario you must develop a custom transaction. This is done in one of two
ways:
– Write an addition transaction using the extension framework provided in the
common services
– Write a custom business proxy, a composite business proxy, or both, which
use existing back-end transactions internally.
Each of these extension mechanisms are defined in their respective sections in
this guide. See Chapter 2, “Customizing InfoSphere MDM Server,” on page 17
and Chapter 26, “Creating composite XML transactions,” on page 285.
Chapter 28. Understanding batch transaction processing

321

Licensed Materials – Property of IBM

322

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 29. Using and configuring Web Services
This section describes the use and configuration of the InfoSphere MDM Server
Web Services.
The InfoSphere MDM Server Web Services feature exposes InfoSphere MDM Server
functions through WS-I Basic Profile 1.0 compliant Web services. This is important
in a diverse enterprise IT landscape because it allows for improved interoperability
with other applications. In addition to that benefit, the extensive tools support for
Web services allows developers to generate client code for a large number of
platforms and languages based on the WSDL files that describe the Web services.
In this section, you will learn:
“Understanding Web Services”
“Understanding WSDL file structures” on page 324
“Understanding Web Services operations and data types” on page 326
“Understanding Web Services invocation” on page 337
“Making data extensions available through Web Services” on page 338
“Understanding data type definitions” on page 338
“Understanding business object converters” on page 340
“Making additions available through Web Services” on page 342
“Implementing Web Services” on page 343
“Invoking Web Services” on page 346
“Invoking Web Services using JAX-RPC” on page 346
“Invoking Web Services with atomic transactions” on page 348
“Invoking Web Services with WS-Security” on page 349
“Invoking Web Services with atomic transactions and WS-Security” on page 351
“Configuring Web Services security for WebSphere Application Server” on page
352

Understanding Web Services
InfoSphere MDM Server Web Services can be directly invoked by sending SOAP
requests over HTTP(S) to the application server on which the enterprise
application is deployed and running.
The structure of the SOAP requests and responses and that of the services
themselves is described in WSDL files. These WSDL files can be obtained from the
application server as soon as the enterprise application is deployed. WSDL files are
also available in the EAR file in the META-INF/wsdl directories of the Web services
EJB modules and in the samples package. These modules can be recognized by
their names, which have a WS suffix. The WSDL files are also available in the
sample package for convenience.
The WSDL files can be used to generate client code to access the Web Services
programmatically. Depending on the type of client code that is generated, the caller
may not even need to be aware of any SOAP or HTTP details; instead, it may only
have to deal with constructs that are specific to the platform and language that the
client code has been generated for.
© Copyright IBM Corp. 1996, 2009

323

Licensed Materials – Property of IBM

Business functionality is made available through 21 Web services. These services’
implementation is supported through eight EJB modules. All administrative
services are not available through the Web services. The partitioning of the Web
services in the EJB modules is shown in the diagram below:

The function on each Web service corresponds to a particular controller component
and a finder component. For example, the function of the PartyService Web
service matches directly the combined functions of TCRMCorePartyTxn and
TCRMCorePartyFinder.

Understanding WSDL file structures
InfoSphere MDM Server Web Services are described by a series of WSDL and XSD
files. The WSDL elements that describe the services are separated into various files
based on their level of abstraction. Data type definitions are separated from service
descriptions and placed into XSD files.
The files contain the following kinds of descriptions and definitions:

324

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Service.wsdl contains the service endpoint address for the service
named . The WSDL files obtained from the application server
reflect the actual endpoint address where the service is deployed.
v Binding.wsdl contains the bindings of the service port to a
particular messaging and transport protocol. For InfoSphere MDM Server, the
default bindings are SOAP and HTTP(S). Other bindings (such as SOAP over
JMS) use different file names. This file also describes the style and encoding of
the service (which, in the case of InfoSphere MDM Server, is document-literal
wrapped).
v Port.wsdl contains the descriptions for the service’s port in terms
of its operations and their corresponding input/output messages.
v Common.wsdl contains descriptions of Web Service elements that are common and
shared by multiple port descriptions,such as the base service fault.
v .xsd contains the Data Transfer Object (TO) type definitions that
are used in the description of the service’s operations and messages.
v Intf.xsd contains type definitions other than TOs, used in the
description of the service’s operations and messages.
v CommonIntf.xsd contains types that are commonly used by service interfaces,
such as the Control type).
v Common.xsd contains types that are commonly used by the other types that are
specific to particular services.
v xtensions.xsd used as an indirection mechanism to allow for schema definitions
from different, solution-specific, namespaces to be used
v .xsd (not delivered with the product) contains the type
definitions that extend the data used by InfoSphere MDM Server or custom
operations and messages. These are provided by solution implementations and
they extend existing InfoSphere MDM Server types.

WSDL file relationships
The diagram below shows the relationships between the various files used to
describe the Web Services.

Chapter 29. Using and configuring Web Services

325

Licensed Materials – Property of IBM

WCC.wsdll

PartyService.wsdll

BusinessService.wsdll

...

PartyBinding.wsdll

BusinessBinding.wsdll

...

PartyPort.wsdll

BusinessPort.wsdll

...

Extensions.xsd

Common.wsdll

Party.xsd

Business.xsd

Common.xsd

PartyExt.xsd

BusinessExt.xsd

The Extensions.xsd file as delivered contains no type definitions. InfoSphere MDM
Server solution implementations can modify this file to import their particular data
types (contained in XSD files). No type definitions should be placed directly inside
Extensions.xsd. The diagram above shows an example of a solution that extends
the data types used by both the Party and Business services.
InfoSphere MDM Server solution implementations must not modify any of the
WSDL and XSD files provided with the product, except for the Extensions.xsd file.

Understanding Web Services operations and data types
At the Web service operation level, there is typically a one-to-one equivalence
between web services operations and native InfoSphere MDM Server transactions.
The names of web services operations and their parameters match those of
InfoSphere MDM Server transactions. For more details on how web services relate
to transactions, see the web services section of the IBM InfoSphere Master Data
Management Server Transaction Reference Guide.
Web services data types are realized by both SOAP XML elements, in SOAP
requests and responses, and by Java objects.
The diagram below shows some of the basic types used to describe the web
services data types, the TransferObject and PersistableObject.

326

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

TransferObject
TransferObject is the base type of all the objects that are identifiable by
means of a string value (objectId) in a request or response.
PersistableObject
All of the types that carry persistent data are subtypes of
PersistableObject. Some of the features of PersistableObject are:
v Surrogate key to identify the entity and support the Pluggable Key
feature.
v List of null fields to support the Nullable Fields feature.
v Last update date information related to user, transaction and date/time.
v Historical information regarding changes made to the entity.
The idPK element of type SurrogateKey is used to identify a persistent
entity and also to provide support for the Pluggable Key feature. The idPK
element contains the following information:
v A numeric value that is the surrogate primary key of the entity.
v A boolean flag that indicates whether the key is system-generated or
provided by a third party system, also referred to as pluggable.

Chapter 29. Using and configuring Web Services

327

Licensed Materials – Property of IBM

For example, when used with a pluggable key, the idPK element of a
PersistableObject would be represented in a SOAP message as follows:
12345678

The nullFields element is a list of element names used to support the
Nullable Fields feature. It lists those elements in the PersistableObject
that must be nulled. It is considered an error if an element of a
PersistableObject is listed as a null field in nullFields and at the same
time appears in the PersistableObject.
For example, when used with a Person type to null the displayName,
alertIndicator, and lastStatementDate fields in an updateParty SOAP
message, it would be represented like this:

...

PersistableObjectWithTimeline
This is the base type for all types that carry persistent data and active
within a specific time interval, as indicated by the startDate and endDate.
Response
The output from a web service invocation is wrapped in a response data
type. As shown in the figure below, a response contains an instance of
control, and an instance of status. The response type is an abstract type.
Concrete types of response are defined depending on the actual data
content. For example a PersonResponse type is defined as a subtype of
response and contains one instance of person.

328

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Control
The Control data type encapsulates transaction context information. It
contains a set of built-in elements and can be extended to carry any
user-specific information that is required as part of the transaction context.
The Property data type can carry any name value pair. The predefined
names are enumerated in ControlNamesEnum, which can be extended with
user specific names.
The fragment below shows an example of an element of type Control with
built-in elements and generic properties:

12345678
cusadmin
100
...
2006-03-12T14:23:45Z
AB-2132-90

Status Either the response, or specific objects contained in the response can
contain application processing status information. This information is

Chapter 29. Using and configuring Web Services

329

Licensed Materials – Property of IBM

contained in the Status data type and it consists of a type code that
indicates the status, the component that produced the status and any
number of message instances.
Subtypes of TransferObject that have an associated status that is more
specific than the Status type, use a subtype of Status as their status field.
For example, the Party type has a status of type PartyStatus.
TypeCode
All type codes are represented as subtypes of the TypeCode type. Any type
code data type consists of a string value and a string code.

For example, the preferredLanguage element of the Party type is a type
code of the type Language, and would be represented in a SOAP message
as follows:
English

ProcessingException
System and application errors result in a SOAP response that contains a
ProcessingFault.

Party and Person
This is an example of how two of the web services data types are
described in the XSD files and implemented in Java as data transfer
objects.
Party is an abstract type and, therefore, no instances are possible. This is
different from the XML, where instances of its equivalent type
TCRMPartyBObj are possible.

330

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The Party type only contains data that is related to the party entity.
Information about processing of the party entity is separated into the status
object associated with the entity’s TransferObject base type.

Chapter 29. Using and configuring Web Services

331

Licensed Materials – Property of IBM

Person is a concrete type that is a subclass of Party. Subclassing is used in
web services in contrast with the XML, where subtypes are represented
using aggregation.
Each element contained by both Party and Person is of a specific type,
unlike their XML counterparts which are all of type string. The type of the
contained elements are either XML schema data types (such as xd:string,
xsd:unsignedInt, or xsd:boolean) or other types defined in the web
services description (such as a subtype of TypeCode, LastUpdate,
HistoryRecord, PartyIdentification, or PersonName).
Suspect
The Suspect type is aggregated by the Party type and on its turn contains a
collection of Party. The actual instances in this collection are of type
SuspectPerson or SuspectOrganization.

332

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

PartyLocation
PartyLocation is an abstract type that is used as the base type for both
PartyAddress and PartyContactMethod.

Chapter 29. Using and configuring Web Services

333

Licensed Materials – Property of IBM

EntityRole
EntityRole is an abstract type that is used as the base type for
PartyGroupingRole, PartyRelationshipRole and EntityHierarchyRole.

PartySearch
The PartySeach and PartySearchResult types are related as shown in the
diagram below. There are specific search types for person and organization
as there are specific result types. The result types PersonSearchResult and
OrganizationSearchResult contain the search criteria in the form of a
PersonSearch and OrganizationSearch respectively.

ContractSearch
There are also more specific types of search FSPersonSearch and
FSOrganizationSearch which are subtype of PersonSearch and

334

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

OrganizationSearch respectively. Each of these contains a ContractSearch.

SuspectPartySearch
The SuspectPartySearch type has two subtypes SuspectPersonSearch and
SuspectOrganizationSearch

Chapter 29. Using and configuring Web Services

335

Licensed Materials – Property of IBM

PrivPref
The PrivPref and EntityPrivPref and their concrete subtype are related as
shown in the diagram below.

336

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Understanding Web Services invocation
This section describes how the Web Services requests are serviced internally by the
controller components.
Some aspects of this processing are customizable to allow client extensions and
additions to the functionality provided by InfoSphere MDM Server.

1 addparty (SOAP request)
A client application submits a Web services SOAP request, either directly
as an HTTP(S) request or using a tool-generated client. The application
server JAX-RPC runtime deserializes the SOAP XML request into Java
objects and passes them to the appropriate Web services endpoint, which
then prepares a transaction request and invokes the Service Controller.
1.1 processRequest (transfer objects)
The Service Controller selects a request parser that can parse the incoming
requests containing transfer objects into a request containing business
objects. This is based on configuration from the properties files.
1.1.1 parseRequest (transfer objects)
The supplied parser transforms the Web services transfer objects into

Chapter 29. Using and configuring Web Services

337

Licensed Materials – Property of IBM

business objects. The parser provides hooks into the conversion process
that enable extensions to provide their own transfer object and business
object pairs.
1.1.3 addParty (business objects)
The appropriate controller processes the transaction.
1.1.5 constructResponse (business objects)
Similar to the parsing process but in the opposite direction, the result
business objects are converted into their equivalent transfer objects. This
enables the extensions to provide their own transfer object and business
object pairs.
2 SOAP response
The JAX-RPC runtime serializes the transfer objects into a SOAP XML
response and returns it to the client application.

Making data extensions available through Web Services
After developing a InfoSphere MDM Server extension, you can make it available
through Web services.
The task in this section outline the two main steps required to make a newly
developed extension available through InfoSphere MDM Server Web services.
See also:
“To make data extensions available through Web Services”

To make data extensions available through Web Services
1. Define the XML data types corresponding to the extensions developed.
2. Write the ’transfer object-to-business object’ converters.

Understanding data type definitions
The task in this section uses an example that assumes that the data extension,
called PersonExt, adds some fields to the Person InfoSphere MDM Server data
type, as shown in the following class diagram.

See the task in the following section to add the extension data types.
See also:

338

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

“To add extension data types”

To add extension data types
1. Change the Extensions.xsd file to import your XSD file that contains the type
definition.
2. Add an import element as follows:

3. The Extension.xsd that you must change is located in the META-INF/wsdl
directory of the web services EJB Module whose types you are extending. For
this example, the EJB module is contained in the PartyWSEJB.jar.
4. In the example in this task, the PartyExtensions.xsd file contains the actual
definition of the PersonExt type. The Extensions.xsd file only serves as an
indirection mechanism. The PersonExt type can be represented in the
PartyExtensions.xsd file as follows:

5. Use the WSDL2Java emitter to generate the corresponding Java class for any
XML schema data type that you have created. The diagram below shows the
PersonExt class generated for the PersonExt XML schema data type defined
above.

Chapter 29. Using and configuring Web Services

339

Licensed Materials – Property of IBM

Important: You must ensure that the WSDL2Java emitter does not generate code
that overrides the data types provided with InfoSphere MDM Server. One way
to ensure that is to provide the emitter with a class path that includes the
existing InfoSphere MDM Server transfer object Java classes.

Understanding business object converters
After defining the Web Services data types, and their corresponding Java transfer
objects have been generated, you must ensure that InfoSphere MDM Server can
convert back and forth between them and their equivalent InfoSphere MDM Server
extension business objects.
The task in this section uses the example of an extension business object called
PersonBObjExt.
See also:
“To extend business object converters”

To extend business object converters
1. To ensure that conversion between Java extension transfer objects and
InfoSphere MDM Server extension business objects works properly, you must
create a converter Java class called PersonBObjExtConverter that extends the
PersonBObjConverter class from the com.ibm.wcc.party.service.to.convert
package.

340

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

2. PersonBObjExtConverter only needs to implement the following four methods:
void copyToBusinessObjectExtension(IExtension bObjExt, TransferObject tObjExt)
void copyToTransferObjectExtension(TransferObject to, DWLControl dwlControl)
DWLCommon instantiateBusinessObject(TransferObject to, DWLControl dwlControl)
TransferObject instantiateTransferObject(DWLCommonbObj)

3. The copyTo* methods must copy each individual field from the business object
to the transfer object and back, according to their name.
4. The instantiate* methods must create instances of your extension’s business
object or transfer object class, also according to their name.
5. To enable InfoSphere MDM Server to pick up the appropriate converter for
your extension data types, the following configuration must be added to the
tcrm_extension.properties file:
services.endpoints.message.converter.com.company.solution.party.PersonBObjExt =
com.company.solution.to.convert.PersonExtBObjConverter
services.endpoints.message.converter.com.company.solution.to.PersonExt =
com.company.solution.to.convert.PersonExtBObjConverter

The general format of the converters configuration should be as follows:
services.endpoints.message.converter. =
services.endpoints.message.converter. =

Chapter 29. Using and configuring Web Services

341

Licensed Materials – Property of IBM

Making additions available through Web Services
Unlike the InfoSphere MDM Server Service Controller, which handles new
transactions based only on a configuration stored in a properties file, the Web
Services interface into InfoSphere MDM Server requires that all Web Services and
their operations and data types are described by WSDL files before they can be
used.
If you modified InfoSphere MDM Server to support new transactions, either
through additions or through new business proxies (see Chapter 2, “Customizing
InfoSphere MDM Server,” on page 17), and you want to make them available
through Web Services, you need to describe, implement and add your new Web
Services to the InfoSphere MDM Server enterprise application. InfoSphere MDM
Server provides supporting classes to help you implement Web Services as EJB
endpoints.
It is possible for a single Web Service that you have created to group more than
just one transaction. Typically, you should group all the transactions that you
support through a controller/finder pair in a single Web Service.
See also:
“Describing Web Service WSDL and XSD files”

Describing Web Service WSDL and XSD files
To describe your service you need to create a set of WSDL and XSD files.
You can describe the service in just one file, but to make it simpler you can follow
the approach taken in InfoSphere MDM Server and split the description across
multiple files. Splitting the description makes it easier to reuse it in other Web
services or with different bindings for the same web services (such as SOAP over
JMS).
For example, a Web service called AdditionServices would require the following
files:
v AdditionServices.wsdl – describes the address at which the service is available
and which is appropriate for the transport binding chosen.
v AdditionBinding.wsdl – describes the transport and messaging protocol bindings
for the service (HTTP and SOAP respectively).
v AdditionPort.wsdl – describes the interface of the service in terms of its
operations and messages.
v Addition.xsd – describes the data types used in the messages.
You can follow the pattern in the existing Web services WSDL and XSD files. For
each new transaction that you create, you must add the following:
v A Web service operation.
v One input, one output, and between zero and many fault messages.
v One part per message only (required when the service style and encoding are
document literal wrapped).
v One element per part. The types used to describe the element are defined in the
XSD files (either Additions.xsd or other XSD files).
v For the fault message, you can reuse the ProcessingFault element defined in
Common.wsdl.

342

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Implementing Web Services
Once you have your new Web Service and its data types described, you need to
create an implementation to support it.
InfoSphere MDM Server uses the EJB endpoint, which is recommended because it
provides a simpler threading model that, in turn, makes the implementation
simpler.
See also:
“To implement Web Services”

To implement Web Services
1. You can either write the implementation yourself or use a WSDL2Java emitter
to generate it. An example implementation is shown in the figure below.

2. To enable your Web Service to be invoked through HTTP(S):
a. Create a servlet mapping in the WebServicesRouter project.
b. Add a new servlet called AdditionPort.
c. Use the Web Service enabler class provided by the application server’s
JAX-RPC runtime.
For example, with WebSphere Application Server, the class is
com.ibm.ws.webservices.engine.transport.http.WebServicesServlet.
3. Start writing the implementation for your service endpoint EJB
AdditionServiceBean. Change this bean to extend the InfoSphere MDM Server
abstract class com.ibm.wcc.service.BaseServiceBean.
4. In your bean class, you will find methods that correspond to the operations
you defined in the WSDL file. Implement the methods as follows:

Chapter 29. Using and configuring Web Services

343

Licensed Materials – Property of IBM
public ResponseaddReminder(Control control, Reminder reminder)
throws com.ibm.wcc.to.ProcessingException {
return performServiceOperation(new Request("addReminder",
control, reminder));
}

5. Override the same method as in the previous step for the BaseServiceBean, as
shown:
protected HashMap instantiateWccTransactionContext(Control control,
String serviceName) {
HashMap context = new HashMap();
context.put(ReqRespTypeHelper.PARSER_STRING, "");
context.put(ReqRespTypeHelper.CONSTRUCTOR_STRING, "");
context.put(ReqRespTypeHelper.REQUEST_TYPE_STRING, "standard");
context.put(ReqRespTypeHelper.RESPONSE_TYPE_STRING, "standard");
context.put(ReqRespTypeHelper.OPERATION_TYPE_STRING, "All");
context.put(ReqRespTypeHelper.TARGET_APPLICATION_STRING, "tcrm");
return context;
}

In this method, you must provide values for the Control object, which maps
to the DWLControl object. These allow your web Service to invoke your
additions through the service controller, using the appropriate parser and
constructor.
6. Set the physical class for the parser and constructor.
The customized parser and constructor can be configured in the
DWLCommon_extension.properties file:
#################################
# webServices Parser and Constructor
#################################
Parser.tcrm.=com.company.
Constructor.tcrm.=com.company.

7. Implement your parser by extending abstract parser and implement method
as shown:
public class AdditionServiceRequestParser extends
com.ibm.wcc.service.to.convert.ServiceRequestParser {
private IDWLProperty properties = new TCRMProperties();
public AdditionServiceRequestParser() throws RequestParserException {
super();
}
/**
* This is a call back method to instantiate an instance of
* SimpleBObjConverter for the given parameter
*
* @param tObj an instance of Transfer Object
* @return an instance of SimpleBObjConverter
* @throws RequestParserException
* @see com.ibm.wcc.to.convert.ServiceRequestParser
*
#getSimpleBObjConverterInstance(com.ibm.wcc.to.TransferObject)
*/
protected SimpleBObjConverter getSimpleBObjConverterInstance(
TransferObject tObj) throws RequestParserException {
return ConversionUtil.instantiateSimpleBObjConverter(tObj, properties);
}
/**
* This is a call back method to instantiate an instance of
* WrapperBObjConverter for the given parameter
*
* @param tObjs an array of Transfer Object
* @return an instance of WrapperBObjConverter
* @throws RequestParserException
* @see com.ibm.wcc.to.convert.ServiceRequestParser
*
#getWrapperBObjConverterInstance(com.ibm.wcc.to.TransferObject[])
*/
protected WrapperBObjConverter getWrapperBObjConverterInstance(
TransferObject[] tObjs) throws RequestParserException {
if (tObjs != null && tObjs.length > 0) {
return ConversionUtil.instantiateWrapperBObjConverter(tObjs[0],
properties);
} else {
throw new RequestParserException(ResourceBundleHelper.resolve(

344

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
ResourceBundleNames.WEB_SERVICES_STRINGS, NO_DATA_IN_REQUEST_MSG));
}
}
}

8. Implement your constructor by extending abstract parser and implement
method as shown:
public class AdditionServiceResponseConstructor extends
com.ibm.wcc.service.to.convert.ServiceResponseConstructor {
public AdditionServiceResponseConstructor() {
super();
}
private IDWLProperty properties = new TCRMProperties();
/**
* This is a call back method to instantiate an instance of
* SimpleBObjConverter for the given parameter
*
* @param bObj an instance of business object
* @return an instance of SimpleBObjConverter
* @throws ResponseConstructorException
* @see com.ibm.wcc.to.convert.ServiceResponseConstructor
*
#getSimpleBObjConverterInstance(com.dwl.base.DWLCommon)
*/
protected SimpleBObjConverter getSimpleBObjConverterInstance(DWLCommon bObj)
throws ResponseConstructorException {
return ConversionUtil.instantiateSimpleBObjConverter(bObj, properties);
}
/**
* This is a call back method to instantiate an instance of
* WrapperBObjConverter for the given parameter
*
* @param bObj an instance of business object
* @return an instance of WrapperBObjConverter
* @throws ResponseConstructorException
* @see com.ibm.wcc.to.convert.ServiceResponseConstructor
*
#getWrapperBObjConverterInstance(com.dwl.base.DWLCommon)
*/
protected WrapperBObjConverter getWrapperBObjConverterInstance(DWLCommon bObj)
throws ResponseConstructorException {
return ConversionUtil.instantiateWrapperBObjConverter(bObj, properties);
}
/*
* (non-Javadoc)
*
* @see com.ibm.wcc.service.to.convert.ServiceResponseConstructor
*
#instantiateServiceResponseFactory()
*/
protected ServiceResponseFactory instantiateServiceResponseFactory()
throws ResponseConstructorException {
return AdditionServiceResponseFactory.getInstance();
}
}

9. Implement response factory by extending service response interface as shown:
public class AdditionServiceResponseFactory implements ServiceResponseFactory {
protected AdditionServiceResponseFactory() {
super();
}
/**
* @return the instance of PartyServiceResponseFactory
*/
public static ServiceResponseFactory getInstance() {
if (theInstance == null) {
theInstance = new AdditionServiceResponseFactory();
}
return theInstance;
}
/**
* create and populate the response instance
*
* @param transactionName the transaction name
* @param tos the transfer object array containing data
*/
public Response createResponseInstance(String transactionName,
TransferObject[] tos) throws ResponseConstructorException {
Response response = null;

Chapter 29. Using and configuring Web Services

345

Licensed Materials – Property of IBM
try {
response = new ReminderResponse();
if (tos != null && tos.length > 0) {
//assuming addReminder/updateReminder/getReminder returns a reminder
((ReminderResponse) response).setReminder((Reminder) tos[0]);
}
} catch (Exception e) {
if (e instanceof ResponseConstructorException) {
throw (ResponseConstructorException) e;
}
ResponseConstructorException ex = new ResponseConstructorException(
e.getLocalizedMessage());
ex.setCauseObject(e);
throw ex;
}
return response;
}
}

10. If your Web services extends an existing business objects or creates a new
business object, you must also implement the supporting converters to allow
the conversion of the types defined in the XSD into the extension business
objects and back. For more information on implementing the converters, see
“Making data extensions available through Web Services” on page 338

Invoking Web Services
There are four ways to invoke JAX-RPC-based Web Services depending on the
requirements of your implementation.
You can invoke JAX-RPC-based Web Services using one of the following four
methods:
v “To invoke Web Services using JAX-RPC” on page 347
v “To invoke Web Services with atomic transactions” on page 349
v “To invoke Web Services with WS-Security” on page 350
v “To invoke Web Services with atomic transactions and WS-Security” on page 352
Be aware that security and transactional capabilities add overhead to the
processing of Web services.

Invoking Web Services using JAX-RPC
You can invoke web services using Java API for XML-based remote procedure calls
from a web application. JAX-RPC simplifies the process of building web services
with familiar method-call paradigm to those programming on a Java platform.
WebSphere Application Server contains an implementation of JAX-RPC. You can
generate a Web services proxy from a WSDL file for the client using IBM JAX-RPC
runtime. On the server side, a Web services router is used to intercept the SOAP
calls.
The following figure shows a simple JAX-RPCC call.

346

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

See also:
“To invoke Web Services using JAX-RPC”

To invoke Web Services using JAX-RPC
1. Program the Web service client. In the example, the Web service client is
programmed to add a person with just a name, and to get the person with a
name. In the example, PartyServiceProxy is a generated proxy class.
v Setup Web Service Objects
protected Control getControl() {
......
//set control object
control.setRequestId(12345);
control.setRequesterName("cusadmin");
control.setRequesterLanguage(new Integer(100));
......
}
protected PersonName getName() {
......
NameUsageType nameType = new NameUsageType();
nameType.set_value("Legal");
name.setNameUsage(nameType);
......
}
protected Person getPerson() {
......
getPerson().setName(new PersonName[]{getName()});
......
}

Note: Control, PersonName and Person types are generated from the WSDL
file. RequestId can be set to any number. RequesterName is set to cusadmin
for default transaction authorization. RequesterLanguage is a mandatory
field and set to 100 for English. NameUsageType is hard coded to Legal for
simplicity. Name and Person are linked together.
v Invoke Web Service
public String doAddPerson() {
......
//set the server and port for endpoint of web service
getPartyServiceProxy().setEndpoint(getRequestScope().get("endPoint") +
"/PartyWS_HTTPRouter/services/PartyPort");
//invoke add person web service on proxy
PersonResponse personResponse = getPartyServiceProxy().addPerson(
getControl(), getPerson());
//echo the id for the person added in message
getFacesContext().addMessage("addPerson", new FacesMessage(
"Person added with IdPk: " + personResponse.getPerson().getIdPK().get_value()));
......
}
public String doGetPerson() {
......
//set the server and port for endpoint of web service
getPartyServiceProxy().setEndpoint(getRequestScope().get("endPoint") +

Chapter 29. Using and configuring Web Services

347

Licensed Materials – Property of IBM
"/PartyWS_HTTPRouter/services/PartyPort");
//invoke get person web service on proxy
PersonResponse personResponse = getPartyServiceProxy().getPerson(
getControl(), id.longValue(), 1);
//set page bean for display
setPersonName(personResponse.getPerson().getName(0));
......
}

2. Prepare InfoSphere MDM Server for none secured mode, and ensure that you
have disabled WebSphere Application Server Global Security.
3. Prepare InfoSphere MDM Server for none secured Web services:
v Disable security configurations in ibm-webservices-bnd.xmi and
ibm-webservices-ext.xmi for all xxxWSEJB.jar EJB modules under
META-INF folder.
v Comment all ... tagged content
in ibm-webservices-ext.xmi file
v Comment all of ...<
/securityRequestConsumerBindingConfig> tagged content in
ibm-webservices-bnd.xmi file.
Refer to “To enable Web Services security for WebSphere Application Server” on
page 353 for details.

Invoking Web Services with atomic transactions
The WebSphere Application Server JAX-RPC implementation supports Web
Services global transaction.
Global transaction information is added to the SOAP message header, and the
server must initiate SOAP calls back to the client for transaction coordination. The
figure shows a SOAP message call with Global Transaction information:

Enabling transaction context between Web Service calls:
WebSphere Application Server supports OASIS standard for Web Services Atomic
Transaction 1.0 (WS-AT 1.0). WS-AT supports global transactions through the
two-phased commit protocol. The transaction participants and resources are held
until confirmed during the second phase of the two-phased commit. It is used to
distribute an atomic transaction context between multiple application components
so that any resources used by those components is coordinated by WebSphere
Application Server (using XA) to an atomic outcome.

348

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The relation of WS-AT to web services is conceptually similar to a Java transaction
service and EJBs and Web modules. If the transaction is container managed, you
do not need any coding.
No changes to the Web service provider are required. All Web services providers
are EJB modules and already have a default container transaction type of Required,
so no changes are required. The providers interpret incoming Web services
requests with WS-AT transaction context and convert them into a JTA transaction
context.
You must enable transaction context on the Web service consumer side. The
process is different depending on whether the consumer is an EJB module or a
Web module.
The task in this section illustrates how to enable the transaction context between
Web service calls.
See also:
“To invoke Web Services with atomic transactions”

To invoke Web Services with atomic transactions
1. Double-click the deployment descriptor of one of the following:
v If the client is in an EJB Module, double-click the deployment descriptor of
the EJB module and click the EJB bean that contains the Web services client.
v If the client is in a Web module, double-click the deployment descriptor of
the Web module and click the servlet which contains the Web services client.
2. From WebSphere Extensions, under Global Transaction, click Send Web
Services Atomic Transaction on outbound requests. This ensures any
transaction context is propagated with the Web service requests issued from
this module. The JTA transaction context is converted to a WS-AT transaction
context.
3. Wrap the Web service call with a global transaction. This example shows two
addPerson transactions wrapped by UserTransaction within a Web module.
public String doAddPersons() {
......
InitialContext initCtx = new InitialContext();
UserTransaction userTran =
UserTransaction)initCtx.lookup("java:comp/UserTransaction");
userTran.begin ();
//add person 1
PersonResponse personResponse = getPartyServiceProxy().
addPerson(getControl(), getPerson1());
getFacesContext().addMessage("addPerson", new FacesMessage(
"Person1 added with IdPk: " + personResponse.getPerson().getIdPK().get_value()));
//add person 2
personResponse = getPartyServiceProxy().addPerson(getControl(), getPerson2());
getFacesContext().addMessage("addPerson", new FacesMessage(
"Person2 added with IdPk: " + personResponse.getPerson().getIdPK().get_value()));
userTran.commit();
......
}

Invoking Web Services with WS-Security
You can invoke Web Services using a secured JAX-RPC call from a web
application.
The default setting is to use UsernameToken for web service authentication. The
user name token is embedded in the SOAP message header and checked by the
Web service provider for authentication and authorization.
Chapter 29. Using and configuring Web Services

349

Licensed Materials – Property of IBM

The WebSphere Application Server JAX-RPC implementation supports
UsernameToken Profile from OASIS standard WS-Security 1.0. The figure shows a
secured SOAP message with UsernameToken:

See also:
“To invoke Web Services with WS-Security”

To invoke Web Services with WS-Security
1. Open the Web module deployment descriptor, click WS Extension → Request
Generator Configuration → Security Token, and click Add.
2. At Name, type WCCToken, and at Token type, select Username Token. The local
name field is automatically populated. Click OK to finish.
3. On the WS Binding tab click Security Request Generator Binding
Configuration → Token Generator → Add.
4. At Token generator name, type WCCTokenGenerator and at Security token,
select WCCToken. The remaining fields like Token generator class, Value type
and Local name are automatically populated.
5. At Callback handler, enter the custom call back handler you want to use. For
example:
com.your_company.callback.YourCompanyCallbackHandler

6. Click OK. This callback handler is created to pickup the username/password
user entered on UI.
Note: If the Web service client has a fixed identity, use
com.ibm.wsspi.wssecurity.auth.callback.NonPromptCallbackHandler, the callback
handler that comes with the JAX-RPC runtime, and enter your fixed identity
username and password. See the custom callback handler sample code at the
end of the procedure for more information.
7. Enable WebSphere Application Server Global Security. You may use Local OS as
the user registry while enabling security in the application server. By default,
there are two security roles: ServiceConsumer and ServiceProvider.
v The ServiceConsumer role maps to all authenticated users. This role is
associated with all entry point modules. All Web service modules are
considered as entry points. The Entry point module can accept outside calls.
When you send user tokens in a SOAP request to a Web services module, the
user must exist in the WebSphere Application Server user registry.
v The ServiceProvider role maps to one default user: mdm. This role is
associated with all modules that are not considered entry points. These
modules are not to be exposed to outside calls and are only called by entry

350

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

point modules, therefore the user mdm must not be exposed to the outside. If
it is exposed, a caller from the outside maybe able to directly call a non-entry
module using the mdm identity.
8. Ensure that the security configurations are enabled in ibm-webservices-bnd.xmi
and ibm-webservices-ext.xmi for all xxxWSEJB.jar ejb modules under
META-INF folder, by uncommenting all of the following:
v the ... tag content in
ibm-Webservices-ext.xmi file
v the ...<
/securityRequestConsumerBindingConfig> tag content in
ibm-Webservices-bnd.xmi file.
Refer to “To enable Web Services security for WebSphere Application Server”
on page 353 for more information.
The custom callback handler sample code is shown here:
import javax.security.auth.callback.CallbackHandler;
......
public class YourCompanyCallbackHandler implements CallbackHandler {
private String username;
private char[] password;
......
public void handle(Callback[] callbacks) throws IOException,
UnsupportedCallbackException {
int i = 0;
if(callbacks == null || (i = callbacks.length) == 0)
return;
username = getUserNameFromWebClient();
password = getPasswordFromWebClient();
for(int j = 0; j < i; j++)
{
Callback callback = callbacks[j];
if(callback instanceof NameCallback)
{
((NameCallback)callback).setName(username);
continue;
}
if(callback instanceof PasswordCallback)
{
((PasswordCallback)callback).setPassword(password);
continue;
}
}
}
}

Invoking Web Services with atomic transactions and WS-Security
You can invoke Web Services with both atomic transactions and WS-Security.
When the application server initiates transaction coordination SOAP calls, it always
uses the secured HTTPS channel. Using Web Services with atomic transactions and
WS-Security needs support for the HTTPS protocol for Web Services because global
transaction co-ordination SOAP calls use this protocol.
The user name token and transactional information are both embedded in SOAP
message header.

Chapter 29. Using and configuring Web Services

351

Licensed Materials – Property of IBM

The figure shows a SOAP message with Username Token and Global Transaction
information sent through HTTPS:

See also:
“To invoke Web Services with atomic transactions and WS-Security”

To invoke Web Services with atomic transactions and
WS-Security
1. Ensure that the Web service client is deployed on the server.
2. Enable HTTP SSL for your InfoSphere MDM Server Web Services client
application by navigating to Enterprise Applications →
[YourEnterpriseApplication] → Web module → [YourWebApplication].war →
Web Services: Client security bindings → HTTP SSL configuration and
selecting the checkbox next to HTTP SSL enabled under General Properties.
The two WebSphere Application Server instances must use the default setting
for SSL in order to recognize each other’s certificate. If they do not use the
default SSL setting, the client may have trouble identifying the server’s SSL
certificate. For more information, see the section on the Import Signer Certificate
in the WebSphere Application Server Information Center.

Configuring Web Services security for WebSphere Application Server
WebSphere Application Server security and Web Services security must both be
either enabled or disabled in order for Web Services transactions to run. You can
configure your Web Services security setting to match your application server
security setting.
During installation, the Web Services security is automatically configured to be the
same as the WebSphere Application Server security setting. If the application
server security is either enabled or disabled after installing InfoSphere MDM
Server, you must manually update the Web Services security settings
There are two files used by WebSphere Application Server for the Web Services
security configuration:
v ibm-webservices-ext.xmi
v ibm-webservices.bnd.xmi
These files are located in each xxxWSEJB project under the META-INF folder. There
are two additional sets of sample files in the META-INF folder, with the security

352

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

setting enabled and disabled. Use these files are a guide for configuring the
settings. When you are merging content with sample XM files, ensure that you do
overwrite your custom configurations.
See also:
“To enable Web Services security for WebSphere Application Server”
“To disable Web Services security for WebSphere Application Server”

To enable Web Services security for WebSphere Application
Server
To enable Web Services security, merge:
v ibm-webservices-ext.xmi with content from ibm-webservicesext.xmi.securityEnabled
v ibm-webservices-bnd.xmi with content from ibm-webservicesbnd.xmi.securityEnabled
Remember: Because WebLogic security is always enabled, it is not necessary to
perform these steps for WebLogic.

To disable Web Services security for WebSphere Application
Server
To disable Web services security, merge:
v ibm-webservices-ext.xmi with content from ibm-webservicesext.xmi.securityDisabled
v ibm-webservices-bnd.xmi with content from ibm-webservicesbnd.xmi.securityDisabled
Remember: Because WebLogic security is always enabled, it is not necessary to
perform these steps for WebLogic.

Chapter 29. Using and configuring Web Services

353

Licensed Materials – Property of IBM

354

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 30. Using the external Web Services Adapter
The InfoSphere MDM Server Web Services adapter provides a Web Services
interface to the InfoSphere MDM Server Service Controller.
Important: Please note as of InfoSphere MDM Server version 8.0, the external
Web Services adapter is no longer recommended and has been deprecated. The
recommended web services invocation should use the native web services.
In addition to the Web Services described in the previous chapter, which are
natively supported through the IBM InfoSphere Master Data Management Server
enterprise application, an external Web Services Adapter allows for InfoSphere
MDM Server XML requests and responses to be tunnelled through SOAP
messages.
InfoSphere MDM Server Web Services adapter provides a Web Services interface to
the InfoSphere MDM Server Service Controller. It is a protocol adapter that
converts a Web service SOAP request over HTTP or HTTPS into a Java RMI call to
DWLServiceController session EJB. It is packaged as a Web application and can be
deployed independently of the back end, IBM InfoSphere Master Data
Management Server. It can also be deployed together with the back end.

In this section, you will learn:
“Installing the Web Services Adapter”
“Configuring the Web Services Adapter” on page 356

Installing the Web Services Adapter
The InfoSphere MDM Server Web Services adapter is packaged as a J2EE web
application and it is not automatically installed when the back end is installed.
This application must be manually installed. The .war file used for its installation
is located at legacyAdapters/WebServicesAdapter/WCCWSAdapter.war
Install this web application using the installation tools available for the application
server, such as the Administration Console for WebSphere application server.
Note the values of web application’s context root and the server’s HTTP, or
HTTPS, port number. These are part of the end point used by the web services
clients to invoke this service.
Use the sample web services client shipped with the distribution to verify
installation or review the sample code. See the IBM InfoSphere Master Data
Management Server Developers Guide for more information.
© Copyright IBM Corp. 1996, 2009

355

Licensed Materials – Property of IBM

Configuring the Web Services Adapter
InfoSphere MDM Server Web Services adapter configuration is available in the
webservices.properties file, which is included as part of the web application. It is
available in the WEB-INF/classes folder inside the web application.
The following lists some of the key configuration items, along with their
description. Consult the properties file for more information.
#######################################################################
# Location of servers running WCC Back End, like WebSphere Customer Center
# ie: corbaloc:iiop:serverName:port
#
providerUrl=corbaloc:iiop::
#######################################################################
# Default WebSphere Customer Center Context
# If other WCC application is invoked, set the values appropriately.
#
targetApplication=tcrm
requestType=standard
parser=TCRMService
responseType=standard
constructor=TCRMService
operationType=All

See also:
“Web Services interface”
“Deprecated Web Services interface” on page 357

Web Services interface
WsDWLServiceControllerAdpater.wsdl describes the web service exposed by the
InfoSphere MDM Server Web Services adapter. This file is available in the web
application in the wsdl/com/dwl/base/webservices/.
The following shows an extract of the Javadoc from the web service interface.
/**
* This is the entry point for WCC enterprise web application.
*
* According to the parameter contained in context, different WCC applications would
* be invoked by RMI.
* For example, WebSphere Customer Center or WCC Admin Service etc.
*
*/
public class WsDWLServiceControllerAdapter {
/**
*
* The main entry point into the system through web service interface.
* Each call is a stateless call
*
* @param strRequest represents the request data to be processed.
*
For example, it can be the request XML.
*
* @param targetApplication target application to which this request should be
* sent to.
*
* @param requestType drives the selection of a request handler and parser
* factory.
*
A value of standard will select the standard request
*
handler.
*

356

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
* @param parser used to select the parser for this request.
*
A value of TCRMService will select the WCC XML parser.
*
* @param responseType used to select the constructor factory.
*
A value of standard will select the standard factory.
*
* @param constructor used to select the constructor to build the response.
*
A value of TCRMService will select the WCC XML response
*
constructor.
*
* @param operationType used to specify the operation to be executed for this
*
request by the standard request handler. The only value available
*
through the web service interface is ALL, which will
*
perform all operations.
*
* @return String response from WCC Application Back End
*
*/
public String process(String strRequest,
String targetApplication,
String requestType,
String parser,
String responseType,
String constructor,
String operationType) {
...
}
}

Deprecated Web Services interface
Previous versions of the InfoSphere MDM Server Web Services interface supported
a slightly different WSDL, called WsDWLServiceControllerProxy.wsdl, which was
deprecated as of WebSphere Customer Center v5.5. It is still available in the
DWLWSAdapter.war and is installed along with the latest web service. It is
recommended that any existing clients using this interface switch over to using the
new interface.
Following is a list of the services exposed in the deprecated interface and how to
accomplish the same using new interface.
v configureHandler—Sets the providerUrl and the jndiPrefix properties. These are
available in the webservice.properties file and the web service clients do not
need to set this configuration before sending the request.
v getConfiguration—Returns the values set by the configureHandler method.
Again there is no need for the web service client to know about the providerUrl
and jndiPrefix for the backend application, so it should not be used.
v testRequest—The new process service replaces this service and has the same
interface with the exception of the name.

Chapter 30. Using the external Web Services Adapter

357

Licensed Materials – Property of IBM

358

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 31. Customizing Event Manager
Event Manager is a component that detects events and activities. You can
customize it for your business needs.
The Evergreen application is an application used in conjunction with Event
Manager to ensure that InfoSphere MDM Server data is current. For information
about the Evergreen application, refer to “Managing the Evergreen application” on
page 569.
In this section, you will learn:
“Understanding Event Manager business rules”
“Understanding the Event Manager design overview” on page 360
“Understanding events detected by the passage of time” on page 362
“Understanding events triggered by a transaction” on page 363
“Understanding explicit events” on page 364
“Using Event Manager with InfoSphere MDM Server” on page 364
“Understanding the Event Manager data model” on page 365
“Setting up definition tables for Event Manager” on page 366
“Setting up business systems and business entities” on page 367
“Setting up event definitions and categories” on page 367
“Setting up business rules for the event definitions” on page 368
“Setting up the processing option for event detection” on page 370
“Maintaining operational data manually” on page 372
“Maintaining operational tables” on page 372
“Maintaining the PROCESSCONTROL table” on page 372
“Maintaining the PROCESSACTION table” on page 373
“Maintaining operational data using transactions” on page 374
“Writing business rules” on page 374
“Implementing rules using Java” on page 375
“Writing the business adapter” on page 376
“Calling Event Manager from the business system” on page 377
“Detecting events for all configured event categories” on page 378
“Detecting events for explicit event categories” on page 379
“Creating user explicit events” on page 379
“Starting time-based event detection” on page 380
“Configuring the EventDetectionScheduleController” on page 381
“Configuring the notification topic” on page 381

Understanding Event Manager business rules
Business rules are used to detect an event that occurs after the passage of time, or
when an event is the result of a transaction, unless the event is explicitly recorded
as a result of a customer interaction.

359

Licensed Materials – Property of IBM

Event Manager business rules are conditional; that is, they detect an event only
when certain conditions are satisfied. Consequently, you may have many rules for
a single business event. For example, a retirement event may be detected as a
result of multiple rules: the party has turned 65 and the party rolled over their
retirement savings plan to an retirement fund.
You can add, update, or end (cancel) the business rules at any time. The rules can
be implemented as Java classes or using any third party rules engine.

Understanding the Event Manager design overview
The InfoSphere MDM Server Event Manager consists of five major subsystems:
services layer, event detector message-driven bean (MDB) with process controller,
event analyst or detector, event persistence module, and notification module.
The following diagram describes these subsystems:

v Services layer—Provides a business interface to Event Manager users. This
interface consists of the ProcessController and EventService session beans. The
business system can call the ProcessController session bean to inform Event
Manager about a transaction performed against a particular business object. The
ProcessController bean then sends this business object for processing to the
event analyst or detector. This step is asynchronous, ensuring that the business
transaction is not delayed by event processing.

360

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v ProcessController bean with Event Detector MDB—Ensures that business
objects are sent to the event analyst or detector module for processing. The
EventDetectionsScheduleController invokes the ProcessController bean according
to the setting. The ProcessController bean checks for any business objects that
are due for processing within a certain time and sends them to the event analyst
or event detector.
v Event analyst or detector—Executes event rules to determine the list of the
current event occurrences and the list of the future potential event occurrences,
for a given business object.
v Event persistence module—Persists the information about events that have
taken place.
v Notification Module—Sends notifications to other business systems.

Chapter 31. Customizing Event Manager

361

Licensed Materials – Property of IBM

Understanding events detected by the passage of time
When using the time-based detection process, Event Manager selects all business
objects with a next process date that is set to the current date or earlier.
As part of processing the business object, Event Detector returns two items:
v A list of events that have occurred.s
v The date of the next closest possible event. This date is persisted and is called
the next process date.

Event Manager executes the business rules to determine the events have happened
and the ones that are pending. Events that are currently due are processed, and
events that are pending are used to determine the next process date. If there are no
events pending, a date in the future is selected, based on the system settings. This
date is called the event horizon. You can control how often the business rules are
re-evaluated by changing the value of the event horizon. The next process date is
stored in the PROCESSACTION table.
The PROCESSACTION table contains the records for business objects that Event
Manager monitors, by types of event categories. For example, for a business object,
there may be one PROCESSACTION record corresponding to the life events

362

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

category and another record corresponding to the monthly events category. Other
information about the business object, such as the unique identifier, is stored in the
PROCESSCONTROL table.
The EventDetectionScheduleController invokes the ProcessControllerInternal bean
to check if there are any business objects in the PROCESSACTION table that are
due for processing. The ProcessControllerInternal bean picks up all the records
from the PROCESSACTION table with a next process date of today or earlier and
a status of 3 (which indicates that the record is done), or status of 2 (which
indciates dead records that have passed certain time), for the type of event
category that the EventDetectionScheduleController is invoking. If the record has a
status of 2, it is considered to be in process, meaning some other thread is already
executing business rules for it. If the record has a status of 5, it is considered to be
excluded from processing.
The ProcessControllerInternal bean does not do actual event detection. Rather, it
places a task object into the JMS queue. The EventDetectorMDB (the
message-driven bean) picks up the tasks from the queue and starts processing.
Processing the task includes these actions:
v Calling the business system using an adapter to retrieve the most recent data on
the business object
v Invoking business rules to analyze the data
v Persisting occurred events
v Sending notification
v Resetting the next process date in the PROCESSACTION table.
The new next process date value depends on the result of the business rules. If the
rules detect that the business object will have a new event occurring in the near
future, one that occurs between now and event horizon, then the new next process
date is set to the date of the upcoming event. If multiple events are detected by the
rules as future pending events, the date with the nearest future event is selected. If
no new events are planned, next process date is set to the event horizon. This way,
the future events are never pre-scheduled; rather, the processing of all business
rules are rescheduled for the next process date, presuming the future event is
going to happen. If the rule is deleted or changed, you do not have to delete
pre-scheduled occurrences; that is, no additional maintenance actions are necessary.
If the rule has changed or a new rule is added, and there is a possibility that some
business objects should be processed sooner than scheduled, the next process date
should be reset to today’s date to trigger the processing of the newly changed rule.

Understanding events triggered by a transaction
When InfoSphere MDM Server performs a transaction that modifies data related to
the business object, it needs to inform Event Manager about the data change. Event
Manager re-executes all the business rules to see if there are new occurred or
pending events.
The business system can inform Event Manager about the data change by calling
the ProcessController bean. The ProcessController bean places the request in a JMS
queue and returns back to the caller. This way, the performance of original
business transaction is not significantly impacted by the overhead of calling Event
Manager.
The task, placed in the queue by the ProcessController bean, is processed in the
same fashion as scheduled processing. All business rules are executed and the next
Chapter 31. Customizing Event Manager

363

Licensed Materials – Property of IBM

process date is reset in the PROCESSACTION table.

Understanding explicit events
Event Manager can persist information about explicit events.
Explicit events are events that are considered important and need to be captured,
but cannot be derived from the business data or transaction data. For example, if
the client has won the lottery and informed their Client Service Representative
(CSR) about this event, the CSR can capture this information in Event Manager.

Using Event Manager with InfoSphere MDM Server
The Event Manager services layer consists of two InfoSphere MDM Server stateless
session beans: ProcessController bean and EventService bean.
The ProcessController bean provides operational interfaces for business systems to
call Event Manager at the end of business transactions. It also offers a local
interface to be used by the business system transaction when it is deployed
together with Event Manager to improve performance.
The EventService bean provides operational interfaces for customer service
representative front-end tools to persist explicit events.

364

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Event Manager queries the business system for business data prior to executing the
business rules. During the integration phase, the new business adapter class
implementing IEventBusinessAdapter interface needs to be written. The following
class diagram outlines this relationship:

Understanding the Event Manager data model
Event Manager data is managed by a set of database tables.
The following diagram shows the data model of Event Manager:

Chapter 31. Customizing Event Manager

365

Licensed Materials – Property of IBM

Notes:
v The Event Manager data model consists of three operational tables:
PROCESSCONTROL; PROCESSACTION; and EVENT. These tables hold data
pertaining to business objects and events that is added by Event Manager when
it detects the related event. The other tables are definition tables.
v Your integration team must set up proper data for these tables before using
Event Manager.

Setting up definition tables for Event Manager
Before using Event Manager, your integration team must set up the definition
tables in the Event Manager database. The tables describe the following
information:
v The business system with which Event Manager integrates.
v The types of business objects that Event Manager monitors.
v The business adapter used to retrieve information about a business object from
the business system.
v
v
v
v

The types of event definitions.
Grouping of event definitions.
Business rules to execute for the event definitions.
Processing options in Event Manager.

See also:

366

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Setting up business systems and business entities
You must determine which business system and which business entities (that is,
the types of business objects from that business system) for which Event Manager
should be detecting events.
For every business system integrated with Event Manager, there must be one
record in the CDDWLPRODUCTTP table. For each business entity in that business
system, there must be one record in the PRODENTITY table.
For information on how the business system calls Event Manager, see “Calling
Event Manager from the business system” on page 377.
See also:
“To set up a business system and business entity for Event Manager”

To set up a business system and business entity for Event
Manager
1. Add a record to the CDDWLPRODUCTTP table to register the business system.
2. Add a record to the PRODENTITY table for each business entity for which you
want Event Manager to detect events.

Setting up event definitions and categories
Every type of event that you want Event Manager to monitor is determined by an
event definition. For example, to monitor whether a business entity is turning 65
years old, you create an event definition (such as Turning65) in the
CDEVENTDEFTP table. Since you can monitor more than one type of event for the
same business entity, you can define other event definitions (such as Turning70,
RRSP, and CreateSuspects).
In theory, you can detect all types of events at the same time. In practice, however,
you can expect certain types of events to happen more frequently than others (for
example, turning 65 happens only once in a life time; creating suspects happens
every week). By grouping event definitions based on the frequency you expect the
events to occur, you can schedule event detection at different intervals.
Grouping of event definitions is set up using the CDEVENTCAT table. The event
horizon specifies how frequently, in number of days, that the event definitions
belonging to that event category is detected by default. For example, the following
records are provided in the sample data in the CDEVENTCAT and
CDEVENTDEFTP tables:

Chapter 31. Customizing Event Manager

367

Licensed Materials – Property of IBM

In the example data, the LifeEvents category groups seven event definitions (from
RRSP to LOB2), and the CreateSuspects category contains only one event definition
(CreateSuspects). The LifeEvents event horizon is 3650 days and the CreateSuspects
horizon is seven days.
When the LifeEvents category is run, all the business rules associated with the
event definitions, provided that the definition has not expired, belonging to that
category are executed to detect event occurrences. For more information on setting
up business rules, see “Setting up business rules for the event definitions.”
See also:
“To set up event definitions and categories for Event Manager”

To set up event definitions and categories for Event Manager
1. Add a record to the CDEVENTCAT table to register the name of the event
category, taking into account the frequency at which events are likely to
happen.
2. Define one or more event definitions in the CDEVENTDEFTP table for each
category defined above. Each event definition corresponds to the type of event
you want to detect.

Setting up business rules for the event definitions
Events are detected by executing business rules. For example, to detect whether an
entity is over 65 years old, a rule can compare the entity’s birth date with the
current date. If the difference is over 65 years, the Turning65 event has occurred.
Business rules can be implemented using Java or external rules engine. Use the
EVENTDEFEXTRULE, EXTRULE, EXTRULEIMPLEM, and JAVAIMPL tables to
associate business rules with event definitions. For example, the following records
in the EVENTDEFEXTRULE and EXTRULE tables provided in the sample data
associate business rules with event definitions:
v CreateSuspects
v LifeEvents

368

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Notice that although the LifeEvents category groups seven different event
definitions, one rule can be shared by one or more definitions. Therefore, this
subset of event definitions can be evaluated using one rule implementation. On the
other hand, different event definitions can use different business rules. For
example, record 5 uses a different rule than the rest of the event definitions in the
LifeEvents category.
Finally, you define the rules’ implementation in the EXTRULEIMPLEM and
JAVAIMPL tables, as shown in the sample data below:

Chapter 31. Customizing Event Manager

369

Licensed Materials – Property of IBM

In the EXTRULEIMPLEM table, you define whether the business rules are
implemented using Java by specifying EXT_RULE_TP_CODE = J. You then define
the name of the Java class in the JAVAIMPL table.
To determine how to implement business rules, see “Writing business rules” on
page 374.
See also:
“To define a business rule for an event definition for Event Manager”

To define a business rule for an event definition for Event
Manager
1. Add a record to the EVENTDEFEXTRULE and EXTRULE table to establish the
relationship between the event definition and the business rule definition.
2. Add a record in the EXTRULEIMPLEM table to indicate whether the rule is
implemented using a Java class or an external rules engine.
3. If the rule is implemented using a Java class, add a record to the JAVAIMPL
table, indicating the name of the Java class implementing the business rules.

Setting up the processing option for event detection
When the business system calls Event Manager to detect events, Event Manager
checks the PROCESSCONTROL and PROCESSACTION operational tables, calls the
business adapter to get the business object, executes the business rules, and finally
updates the EVENT table if the event is successfully detected.
The role of the PROCESSCONTROL table is to record the business object that is
passed to Event Manager by the business system. A record corresponding to the
business object is created once, when the business object is passed to Event
Manager for the first time. At the same time, Event Manager also determines
whether or not it needs to create any PROCESSACTION records. The role of the
PROCESSACTION table is to record what types of event categories Event Manager
has to monitor for the business object. Records in the PROCESSACTION tables are
created based on the definitions in the ENTITYEVENTCATOPT and
ENTITYEVENTCAT tables. Business adapter used to retrieve the business object is
defined in the ADAPTERDEF table.
For example, the following records are provided in the sample data in the
ENTITYEVENTCATOPT, ENTITYEVENTCAT and ADAPTERDEF tables:
v CONTACT Business entity
v CreateSuspects
v LifeEvents

370

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The ENTITYEVENTCATOPT table contains three processing options for creating
PROCESSACTION records. The Create_Detect option instructs Event Manager to
create a PROCESSACTION record for the business object and detect the event
immediately. The Create_NoDetect option instructs Event Manager to create a
PROCESSACTION record, but not detect the event at this time. This sets up the
PROCESSACTION record for the business object so that event detection can be
scheduled at a later time. To learn more about scheduling event detection, see
“Starting time-based event detection” on page 380.
The NoCreate_NoDetect option instructs Event Manager to bypass creating the
PROCESSACTION record and event detection. If you want to schedule event
detection for the business object in the future, you need to create the
PROCESSACTION record manually.
One of these three processing options must be used in the ENTITYEVENTCAT
record to indicate to Event Manager how PROCESSACTION record and event
detection are handled. In the above sample data, the record for the LifeEvents
event category contains an ENTEVENTCATOPT_ID of 2, which instructs Event
Manager to create the PROCESSACTION record and run the business rules for this
event category immediately. The record for the CreateSuspects event category
contains an ENTEVENTCATOPT_ID of 0, which instructs Event Manager to bypass
creating the PROCESSACTION record and event detection.
The ADAPTERDEF_ID in the ENTITYEVENTCAT record refers to the record
defined in the ADAPTERDEF table. The ADAPTERDEF record contains the class
name of the adapter implementation. Note that in the ENTITYEVENTCAT sample
data above, all four records refer to the CONTACT business entity
(PRODENTITY_ID = 10), but they can refer to different business adapter based on
the event category. To find out more information about business adapter, see
“Writing the business adapter” on page 376.
See also:

Chapter 31. Customizing Event Manager

371

Licensed Materials – Property of IBM

“To define the processing option for an event category forEvent Manager”

To define the processing option for an event category
forEvent Manager
1. Add a record to the ADAPTERDEF table to register the business adapter that
you want to use for retrieving business data from the business system.
2. Add a record to the ENTITYEVENTCAT table, indicating the business entity,
the adapter you want to use, and one of the three predefined
ENTITYEVENTCAT_ID values.

Maintaining operational data manually
You can maintain the PROCESSCONTROL and PROCESSACTION records using
SQL statements. This method is useful when you want to maintain a large volume
of records, such as during the initial loading of operational data.

Maintaining operational tables
Three operational tables hold the data pertaining to the business objects and their
occurred events as the events are being detected by Event Manager.
The role of these tables are as follows:
v PROCESSCONTROL—A record in this table holds the ID uniquely identifying
a business object in the business system.
v PROCESSACTION—A record in this table corresponds to an event category
that Event Manager monitors for the business object. For each event category to
be monitored, a separate record is required. This record also holds the next
process date, which is used by time-based event detection to determine when an
event has to be reevaluated.
v EVENT—A record in this table corresponds to an occurred event.
When InfoSphere MDM Server calls into Event Manager at the end of a
transaction, these records are created and updated automatically by Event Manager
on an ongoing basis. However, if you intend to roll out Event Manager to process
a predefined set of business objects, you may find it useful to manually add
records to these tables and schedule event detection on these objects.

Maintaining the PROCESSCONTROL table
The PROCESSCONTROL table contains a reference to each business object in
InfoSphere MDM Server. It has a foreign key relationship with PRODENTITY
table, which contains information about the business entity of that business object.
The PROCESSCONTROL table can be pre-populated with references to the
business objects within InfoSphere MDM Server during the integration phase. For
example, the PROCESSCONTROL table may be populated with the party’s
primary keys.
The following is some fictitious data populated in the PROCESSCONTROL table:

372

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

In the above sample data, the PROCESSCON_INST_PK column stores the party’s
primary keys. The NEXT_PROCESS_DT in the PROCESSCONTROL table contains
no processing and can be left as null.

Maintaining the PROCESSACTION table
After you populate the PROCESSCONTROL table, for each type of event category
you want to monitor for the business object, you need to create a
PROCESSACTION record. The PROCESSACTION table has a foreign key
relationship with the ENTITYEVENTCAT table, which refers to the event category
to be monitored, and a foreign key relationship with the PROCESSCONTROL
table, which refers to the business object.
During the lifetime of the system, new business entities can be added to the
business system. In this case, when the business system calls Event Manager at the
end of transaction, new or missing business object records are added to the
PROCESSACTION table prior to executing the rules. After the rules are run, the
NEXT_PROCESS_DT for the record is set to the appropriate value.
If processing of the record fails for any reason, the NEXT_PROCESS_DT is set to
today. This allows the same record to be picked up the next day by the
EventDetectionScheduleController again.
Business objects are processed individually. Once the EventDetector module
receives a record from the PROCESSACTION table, Event Manager updates the
EVENT_STATUS field in the PROCESSACTION record with a value of 2. This is
done to ensure that scheduled Event Manager processing does not select the same
record while it is already being processed by another thread. At the end of the
processing, the EVENT_STATUS field is re-set to a value of 3.
If you must exclude some of the business objects from processing for business
reasons, set the EVENT_STATUS field to 5. The EventDetectionScheduleController
does not pick up the records with this status, and if there is transaction-triggered
processing, the request is ignored.
The following is some example data populated in the PROCESSACTION table:
v Next process dates are staggered
v CreateSuspects
v LifeEvents

Chapter 31. Customizing Event Manager

373

Licensed Materials – Property of IBM

In the sample data, two PROCESSACTION records are created for each
PROCESSCONTROL record created in “Maintaining the PROCESSCONTROL
table” on page 372:
v One for the LifeEvents category
v One for the CreateSuspects category
This allows these two event categories to be scheduled for detection independently.

Maintaining operational data using transactions
You can use various transactions to maintain the PROCESSCONTROL and
PROCESSACTION records.
These transactions are as follows:
v addProcessControl
v addProcessAction
v updateProcessAction
v getProcessControl
v getProcessAction
v getAllProcessActions
See the IBM InfoSphere Master Data Management Server Transaction Reference Guide
for more information about these transactions.

Writing business rules
Business rules are responsible for detecting the occurrence of events and predicting
the time future events may occur. Event Manager uses the externalized rules
component to configure the business rules.
The externalized rules component offers the following features:
v Rules can be externalized into a rules engine.
v Different rules engine products can be accommodated.
v Different rules can be implemented in different rules engine products.

374

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Rules can be externalized as Java code.
v A rule can change implementation types (for example, rules engine
implementation to Java code implementation and vice versa), without affecting
the core product. In other words, a rule can have multiple implementations
v A rule can receive input data and can return data in the form of objects
Most events must be predefined in the CDEVENTDEFTP table, except for events
that are user explicit. When a business rule reports the occurrence of an event to
Event Manager, a new record is created in the event table with a reference to the
event definition. See “To set up event definitions and categories for Event
Manager” on page 368 for details on how to set up the CDEVENTDEFTP table.
There is no direct relationship between events and rules. Events are detected by
rules, and rules are executed because there are events defined in CDEVENTDEFTP
table. The choice of rules engine can determine how many rules are needed to
implement a single event. See “Setting up business rules for the event definitions”
on page 368 for information on how to associate business rules with event
definitions.
Note: Rules are configured in tables related to the externalized rules component.
Rules and event definitions are linked via EVENTDEFEXTRULE table, which
references both the CDEVENTDEFTP table and the EXTRULE table. This means
each event definition can have its own rule, if necessary. However, typically a
single Java business rule can handle multiple event definitions. Similarly, a single
rule set, configured as a single rule in the EXTRULE table, can handle all events
defined in the CDEVENTDEFTP table. In this case, you must specify the same rule
for all the event definitions it covers. Event Manager ensures the rule is executed
only once, even if it is registered for multiple event definitions.

Implementing rules using Java
To implement business rules as Java code, write the class that implements the
com.dwl.base.externalrule.Rule interface. Event Manager provides an abstract Java
class that already implements the rule interface; therefore, when writing Java
business rules for Event Manager, simply extend
com.dwl.commoncomponents.eventmanager.test.BaseRule class.
To implement a custom Java business rule, extend BaseRule class, providing
implementation for the following method:
public abstract void executeRules(EventTaskObject task)

Java business rules can obtain all necessary information from the EventTaskObject,
passed as an input parameter of the executeRules() method. EventTaskObject
contains information about the business entity itself, events that have already
occurred for this business entity and additional information such as today’s date,
event horizon, and others (see the figure below).
To obtain list of the occurred events, use the getOccurredEvents() method, which
returns a vector of EventObj objects. Each EventObj object contains information
such as the name of predefined events if the event is not user explicit, date when
the event occurred, and others.
To obtain the business data object or transaction object, use methods getDataObj()
and getTransactionObj(), respectively.

Chapter 31. Customizing Event Manager

375

Licensed Materials – Property of IBM

EventTaskObject can provide today’s date when getToday() method is called. Also,
to write the rules designed to determine future data of the event occurrence, it is
important to know how far in the future the rule is supposed to look. The
getToDate() method returns today’s date increased by the number of days specified
as the event horizon in the CDEVENTCAT table. For example, if today is May 10,
and the value of the EVENT_HORIZON field in CDEVENTCAT table is 365, the
getToDate() method returns the date of May 10 next year. This date can then be
used to determine the time of the occurrence of events in the future.
When current or future events are detected by the rule, it is important to
communicate that information to Event Manager. Rules must add the
newly-detected events to the list of the pending events on the EventTaskObject
using the addPendingEventObject(EventObj eventObject) method. If the event is a
current occurred event, then the creation date of the EventObj should be set to the
time this event is going to occur in the future. For tracking purposes, the events
created by rules should have the event trigger property set to EventTriggered. Use
the constant EventManagerConstants.TRIGGER_EVENT_TRIGGERED to set this
value.

Writing the business adapter
The business adapter implements the IEventBusinessAdapter interface.
This interface prescribes one method as follows.
public DataObjectCollection getDataObjects(Serializable transObj, String busObjKey,
String busEntity)

The method requires the following input parameters:
v Serializable transObj—Contains the business object passed to ProcessController
bean during the call from the business system. Typically, it contains the business
object participating in the business transaction or the transaction object itself. If
the Event Manager processing is not triggered by a transaction, this parameter is
empty.
v String busObjKey—Contains the primary key of the business object within the
business system. If processing is triggered by calling the ProcessController bean,
this value is set to the value passed into processTask() method. If the
EventDetectionScheduleController triggers the processing, this value is retrieved
from the PROCESSCON_INST_PK field in the PROCESSCONTROL table.
v String busEntity—Contains a logical name of the business object within
business system. If processing is triggered by calling the ProcessController bean,

376

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

this value is set to the value passed into processTask() method. If the
EventDetectionScheduleController triggers the processing, this value is retrieved
from the NAME field in the PRODENTITY table, by looking up the
PRODENTITY_ID field in the PROCESSCONTROL table.
This method must return the DataObjectCollection object or null. This return type
allows the adapter to return multiple business objects.
In the case, where the EventDetectionScheduleController triggered the processing,
the adapter typically returns only one object. The adapter retrieves the business
object from the business system, creates the new DataObjectCollection object, adds
one business object to the DataObjectCollection object and then returns it.
In the case where a transaction triggered the processing, the adapter can use the
information in the transObj, passed as an input parameter, to decide which type of
objects should be retrieved from the business system. Each object must be added as
EventDataObj to the DataObjectCollection with the appropriate busEntity and
busObjKey information. For example, if the business transaction is ContractUpdate,
the adapter may want to retrieve information for all the parties modified during
the transaction. Each party data object, together with the party primary key and
entity name, should be added as EventDataObj to DataObjectCollection and
returned to the caller. If the adapter is not retrieving any data object and simply
needs to pass transaction object transObj to the rule, it still should be added to
DataObjectCollection as EventDataObj. If the adapter returns with an empty
DataObjectCollection, Event Manager will not be able to proceed.
To add business object information to the DataObjectCollection, use the following
method:
public boolean add(Serializable busDataObj, String busEntity, String busObjKey)

Once the adapter is implemented, it needs to be registered with Event Manager in
the ADAPTERDEF table, which contains information about the adapter
implementation, such as vendor information and the fully qualified name of the
adapter class. The ID of the adapter should then be added to the
ENTITYEVENTCAT record as a foreign key to the entity event category that uses
this adapter. The value from the DWL_PROD_TP_CD field of the PRODENTITY
table, which corresponds to the PRODENTITY_ID of that entity event category,
should be used as the busSysID input parameter when calling the
ProcessController bean. To find out more about calling the ProcessController bean,
see “Calling Event Manager from the business system.”

Calling Event Manager from the business system
To notify Event Manager about business transactions, the business system can call
one of the processTask() methods of the ProcessController bean. The
ProcessController bean is a stateless session bean and is registered under the JNDI
name ProcessController.
Once the processTask() method is invoked, Event Manager places one or more
EventTaskObjects with all information from the input parameters in the JMS work
queue. After the task object is put in the work queue, the call to the processTask()
method returns to the business system. Asynchronously, the EventDetectorMDB
then picks up the task object from the queue, calls the business adapter to retrieve
that business object, and calls the EventDetectorHelperBean to detect the event.

Chapter 31. Customizing Event Manager

377

Licensed Materials – Property of IBM

Depending on which processTask() method to call, Event Manager either detects
events for all event categories configured in the ENTITYEVENTCAT table for the
business system or business entity combination, or detects events for event
categories that are explicitly passed to Event Manager

Detecting events for all configured event categories
To detect events for all the configured event categories for the business system or
business entity combination, use the following processTask() method.
Execute the processTask() method as follows:
void processTask(String busSysID, String busObjKey, Serializable transObj,
String busEntity)

Method processTask() requires the following as input parameters:
v String busSysID—Provides the value from the DWL_PROD_TP_CD field of the
record in CDDWLPRODTP table, containing the business system information.
This should also be the DWL_PROD_TP_CD field in the PRODENTITY record,
which corresponds to the business system/business entity combination.
v String busObjKey—Provides the actual primary key of the business object
within the business system.
This processTask() method uses the busSysID ad BusEntity values to look up the
PRODENTITY_ID from the PRODENTITY table. It then looks up the
ENTITYEVENTCAT table to find all the event categories that are configured for
the PRODENTITY_ID.
For example, the sample data provided for Event Manager contains this data:

If the busSysID 1 and busEntity CONTACT are passed into this processTask()
method as arguments (which yields the lookup of PRODENTITY_ID of 10), all four
event categories could be triggered for event detection. However, since the
ENTEVENTCATOPT_ID=2is for the first two event categories, only these two
categories are triggered for event detection. See “Setting up the processing option
for event detection” on page 370 for the use of the ENTEVENTCATOPT_ID.

378

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Depending on the implementation of the business adapter, some of the input
parameters in processTask() method may be optional. For example, if the transObj
input parameter has the primary key and entity name of the business object, then
the busObjKey and busEntity input parameters can be omitted. If the transObj
input parameter is not present, then values for the busObjKey and busEntity
parameter must be provided. See “Writing the business adapter” on page 376 for
more information.

Detecting events for explicit event categories
To detect events for event categories that you want to specify explicitly, use the
following processTask() method.
Execute the processTask() method as follows:
void processTask(EventTaskParameters eventTaskParameters)

The EventTaskParameters object allows you to specify one or more event
categories. The following code snippet shows how to construct a
EventTaskParameters object that can be used as argument to the processTask()
method:
...
// first argument for busSysID = 1
// transSerObj = transaction object
EventTaskParameters parameters =
new EventTaskParameters("1", null, null,
transSerObj);
// EventCategorySelection object associates
// business entity with one or many event categories
// busEntity = "CONTACT"
EventCategorySelection eventCatSelection =
new EventCategorySelection("CONTACT");
// associates "LifeEvents"
eventCatSelection.addCategoryType(new Long(1));
// associates "CreateSuspects"
eventCatSelection.addCategoryType(new Long(3));
parameters.addEventCategorySelection(eventCatSelection);
...

The code snippet above creates the parameters to detect only two types of event
categories: LifeEvents and CreateSuspects for the business system and business
entity combination 1 and CONTACT. Note that although two categories are
specified explicitly, Event Manager still looks up the ENTITYEVENTCAT table to
ensure that the event category is valid for the PRODENTITY_ID configured for the
business system/business entity combination, and to determine the
ENTITYEVENTCATOPT_ID configured. Since LifeEvents is the only event category
that has the ENTITYEVENTCATOPT_ID field set to 2, only LifeEvents is detected.

Creating user explicit events
To add a user explicit event, call the processTask() method of
ProcessControllerBean.
Execute the processTask() method of ProcessControllerBean as follows:
void processTask(String busSysID, String busObjKey, EventObj eventObj, String
busEntity)

Chapter 31. Customizing Event Manager

379

Licensed Materials – Property of IBM

This method takes the same input parameters as the processTask() method
described in “Detecting events for all configured event categories” on page 378,
except for EventObj eventObj, which provides the EventObj containing information
about the user explicit event.
You do not have to provide event definitions, as user-explicit events are not
predefined. If the user-explicit event is set to trigger a notification, set the
notification flag to true on the EventObj, using the method setDoNotification
(Boolean doNotification).

Starting time-based event detection
When the PROCESSCONTROL and PROCESSACTION tables are set up properly,
either automatically as a result of the business system calling into Event Manager
or by manually adding records to these tables. Events can be re-evaluated by
starting the EventDetectionScheduleController.
The EventDetectionScheduleController is a Java class. Its main() method opens a
socket on the server where it is run. After the socket is opened, you issue an
EventDetectionCommand to tell the EventDetectionScheduleController how to
interact with Event Manager on the server. You can issue an
EventDetectionCommand to do one of four things:
v Start processing an event category, specifying an event category ID
v Cancel processing an event category, specifying an event category ID
v Get status on the EventDetectionScheduleController (for example, which event
categories are currently being processed)
v Shut down the EventDetectionScheduleController
Using the EventDetectionScheduleController, you can detect events of different
categories concurrently
Five cripts are provided to process time-based event detection:
v startScheduleController.sh
v runEventDetection.sh
v cancelEventDetection.sh
v statusScheduleController.sh
v shutdownScheduleController.sh
Here is some example usages for the scripts:
v To begin processing events for LifeEvents and CreateSuspects categories, run the
following scripts:
– startScheduleController.sh
– runEventDetection.sh
– runEventDetection.sh
v To stop processing event for LifeEvents while continuing with other scheduled
event detections, run the script cancelEventDetection.sh.
v To stop processing all scheduled event detections and shut down the scheduler,
run the script shutdownScheduleController.sh.

380

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Configuring the EventDetectionScheduleController
The EventDetectionScheduleController class calls the ProcessControllerInternal
session bean. The location of the bean is configured in the
EventManagerClient.properties file in the property
ProcessControllerInternal.PROVIDER_URL.
After an event detection is started, the EventDetectionScheduleController keeps
sending requests to the application server to process due events. If the server is
restarted, the EventDetectionScheduleController must also be restarted. The
following properties can be changed in EventManagerClient.properties to fine tune
the behavior of the process capacity of the EventDetectionScheduleController:
v EventDetectionScheduleControllerHost—Indicates the host server on which
EventDetectionScheduleController runs. The EventDetectionCommand that you
invoke tries to communicate with the EventDetectionScheduleController on this
server.
v EventDetectionScheduleControllerPort—Specifies the port number where you
want the EventDetectionScheduleController to open a connection. The
EventDetectionScheduleController uses this port to listen for
EventDetectionCommand.
v EventDetectionJobDefaultCycle—Specifies the cycle (in milliseconds), or the
interval at which a job runs. Since you may run different jobs on the server,
consider running different jobs at different intervals, depending on the priority
of the job. In this case, override the default cycle by specifying a -cycle
argument when you run the runEventDetection.sh script.
v EventDetectionMaximumTasksInQueueOverride—Specifies an estimated
maximum number of tasks that can be put on the queue among all the jobs that
are scheduled to run on the server. If this value is omitted or is zero, the
max_messages_in_tasks_queue property in the EventManager.properties file on
the server is used.

Configuring the notification topic
Event Manager uses the notification component to send XML messages to the
topic, which is a publish-subscribe type of JMS destination. Notification is issued
for each event if that event’s definition is configured in the CDEVENTDEFTP table
with the ENABLE_NOTIFY field set to Y.
For the user explicit events, notification can be turned on or off for each event
individually.
The topic must be registered with the JMS provider and the topic name must be
configured in the database. To use the topic with Event Manager, set the topic
name in the /IBM/EventManager/Notification/topic configuration in
Configuration and Management.
Below is the sample of the XML notification sent for TCRMPartyBObj with primary
key 6500019390515 on the occurrence of a retirement event:

Retirement
2
TCRMPartyBObj
6500019390515

Chapter 31. Customizing Event Manager

381

Licensed Materials – Property of IBM
Retirement
TimeTriggered
2004-05-16 14:37:59.558

382

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 32. Setting and administering the security service
Access to InfoSphere MDM Server data and functionality is controlled both at the
application server level and at the application level.
The InfoSphere MDM Server Security Service refers to business transaction access
control. For data access control, see Chapter 33, “Controlling the visibility and
accessibility of data,” on page 391.

Application Server Security
At the application server level, InfoSphere MDM Server enterprise beans and web
services port components are configured for each method to only grant access to
users in particular roles. InfoSphere MDM Server relies on the application server to
perform user authentication. The identities being authenticated are those of the
systems consuming the functionality of InfoSphere MDM Server.
InfoSphere MDM Server defines two security roles: ServiceConsumer; and
ServiceProvider. All user identities that are authenticated by the application server
are placed in the ServiceConsumer role. The methods of the enterprise beans that
constitute entry points for other applications (the ServiceController bean, the
ProcessControlInternal bean and the web services beans) are configured to grant
access to the ServiceConsumer role. Also, these beans use the ServiceProvider role
as RunAs security role. All the other enterprise beans, which are not meant to be
accessed directly by other applications, have their methods configured.
The ServiceProvider RunAs security role must be bound at deployment time to an
actual user identity in the user registry used by the application server. By default,
InfoSphere MDM Server binds this role to the InfoSphere MDM Server user
identity. You can either create an InfoSphere MDM Server identity in you user
registry or bind the role to a different user identity. This identity should not be
used for any other purposes and should be reserved for the use of InfoSphere
MDM Server enterprise application.

Application Security
InfoSphere MDM Server relies on the application server to establish a trust
relationship with the systems consuming its functionality. Once the identity of the
outside system invoking a transaction has been authenticated by the application
server, it is implicitly trusted by the InfoSphere MDM Server application.
InfoSphere MDM Server requires that a user identity be passed in the requests in
one of the following forms within the Control object:
v RequesterName and UserRoles properties as clear text values
v Authentication assertion about the identity and its attributes (roles). By default
SAML 1.1 assertions are supported
In both these forms the user and role information is about the end-user on behalf
of which the request was made. This information is used by the InfoSphere MDM
Server application to make access policy decisions and to enforce them.
The security service provides a framework for externalizing access policy decisions.
The framework defines the interfaces that a transaction authorization provider
must implement to provide the InfoSphere MDM Server application with access
© Copyright IBM Corp. 1996, 2009

383

Licensed Materials – Property of IBM

policy decisions on business transactions. InfoSphere MDM Server comes with a
default transaction authorization provider which uses a relational database to store
information about security policy. In addition to that a transaction authorization
provide is provided that uses an LDAP directory to store security access policy
information.
The security service also provides a framework for formatting of the authentication
assertions. The framework defines the interface required to parse authentication
assertion included in the transaction requests. InfoSphere MDM Server comes with
a default authentication assertion parser that supports the use of SAML (Security
Assertion Markup Language).
In this section, you will learn:
“Configuring the security service”
“Understanding the Security Data Manager”
“Configuring the user management run time API” on page 385
“Understanding the runtime security service” on page 386
“Understanding the default transaction authorization provider” on page 387
“Configuring LDAP transaction authorization providers” on page 388
“Configuring a custom transaction authorization provider” on page 389
“Using a custom authentication assertions parser” on page 390

Configuring the security service
The security service provides various configuration options. The security service
framework options are defined in configurations with names beginning with
/IBM/DWLCommonServices/Security.
The default authentication assertion options are defined in configurations with
names beginning with /IBM/DWLCommonServices/Security/SAML.
See to the “Understanding configuration elements in the Configuration and
Management component” on page 419 topic for details about these configurations.
By default InfoSphere MDM Server does not validate the incoming SAML XML
with the corresponding XSD based on the configuration above. If the validation is
turned on, you must package the SAML1.1 XSD into InfoSphere MDM Server EAR
file. This XSD can be downloaded from the OASIS consortium web site. If you do
not include the SAML1.1 XSD, the transaction will fail. A log message warning
users of the missing XSD is also logged in the InfoSphere MDM Server log.
Additionally, transaction authorization provider-specific configuration may be
needed and is discussed in the section for the respective transaction authorization
providers.
For information on configuring web services security, see “To enable Web Services
security for WebSphere Application Server” on page 353

Understanding the Security Data Manager
The Security Service comes with a Security Data Manager to administer the
authorization data for the default transaction authorization provider. As mentioned
earlier, the default transaction authorization provider performs the authorization
check against a relational database, and the Security Data Manager provides

384

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

services to manage the data in these database tables. For more information on the
table structure, see “Understanding the default transaction authorization provider”
on page 387.
The Security Data Manager consists of a server-side component, which provides
the API for data management as well as a web-based administration GUI. Some of
the services provided by this manager include:
v Add or update a user profile
v Add or update a group profile
v Add a transaction authorization for a user
v Add a transaction authorization for a group
This interface should be used to add or update authorization data for all out of the
box as well as client specific extended transactions. These transactions must first be
registered in the CDBUSINESSTXNTP database table. Such extended transactions
must be given a primary key greater than 1,000,000. All values less than 1,000,000
are reserved for InfoSphere MDM Server provided transactions.
To retrieve authorization information from the transaction authorization provider
during run time, see “Configuring the user management run time API.”

Configuring the user management run time API
You can configure the user management run time API in order to retrieve
authorization information from the transaction authorization provider.
The user management run time API is responsible for obtaining the authorization
information during run time from transaction authorization provider. The API
provides a level of indirection between transaction authorization provider running
in InfoSphere MDM Server run time and consumers of user management
information, allowing clients to plug in alternative API implementations in order to
retrieve users and roles information from external transaction authorization
provider.
The UserManagementProvider interface defines the methods for obtaining users
and roles information, as shown in class diagram below.
This interface must be implemented by a concrete user management provider class
that is responsible for retrieving user and roles information in InfoSphere MDM
Server run time. The user management provider class must be registered with
InfoSphere MDM Server run time by providing a fully-classified class name as a
value for the Configuration Management property /IBM/DWLCommonServices/
UserManagement/user_management_provider_class_name.

Chapter 32. Setting and administering the security service

385

Licensed Materials – Property of IBM

InfoSphere MDM Server provides a default implementation class
(DefaultUserManagementProvider) to retrieve data from the default transaction
authorization provider, where authorization information is stored in relational
database, with the user represented by a record in USERPROFILE table and the
role represented by a record in GROUPPROFILE table:
v getRolesByUser—Returns the vector of the role names. The role name is a string
containing the value from GROUPPROFILE.group_name field.
v getUsersByRole—Returns the vector of the user names. The user name is a
string containing the value from the USERPROFILE.user_id field.
v isValidUser—Determines if the user is valid, based on whether the user name is
present in USERPROFILE.user_id field.
v isValidRole—Determines if the role is valid, based on whether the role name is
present in GROUPPROFILE.group_name field.
For more details on how to add or update user information for default
authentication provider, see “Understanding the Security Data Manager” on page
384.

Understanding the runtime security service
The InfoSphere MDM Server security service provides an interface for performing
runtime authorization checks. The Request/Response Framework uses this
interface to ensure that each incoming transaction is authorized before processing
the transaction. The process of the runtime security check is as follows:
1. An incoming request identifies the user, the user’s group name, or both,
representing the end user requesting the transaction. For example, for a
InfoSphere MDM Server XML transaction, the user and group information can
be passed in the DWLControl element of the incoming request. The following is
an excerpt of the DWLControl definition in the request XSD showing the
attributes relevant to security.

386

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

...

requesterName represents the user while userRole contains the group to which
the user belongs. Multiple roles can be passed for the given user and the
runtime check is performed for all roles.
The information about the end user’s identity and roles can be also passed in
as SAML 1.1 authentication assertions. The assertions are passed as unparsed
character data in the authData element of the DWLControl group.
2. In addition to the user and group information, the input request also contains
the name of the transaction to be executed. For the InfoSphere MDM Server
XML transaction, this is contained in the TCRMTxType element.

3. On receiving the request, the Request/Response Framework invokes the
security service to perform the authorization check, passing it the user, group
and transaction name information.
4. The security service invokes the currently configured transaction authorization
providers to check whether the user, one of the groups, or both, are authorized
to perform that transaction. If multiple transaction authorization providers are
configured, all of them are invoked.
5. If none of the transaction authorization providers respond with authorization,
Request/Response Framework returns with a security exception.
6. If at least one of the transaction authorization providers returns with
authorization, Request/Response Framework proceeds with the request
processing.
Transaction authorization providers make up the significant part of the runtime
security services. The following sections describe the two transaction authorization
providers that are included in the security service.

Understanding the default transaction authorization provider
The security service includes a default transaction authorization provider. This
provider performs transaction authorization against security data stored in a
relational database. The authorization data associates users and groups to the
transactions for which they are authorized.
The class name that implements this transaction authorization provides is
com.dwl.base.security.provider.DefaultTransactionAuthorizationProvider. In order
to use this provider, it should be configured in the configuration repository as
described above.
Following data model shows the table structure used for authorization.

Chapter 32. Setting and administering the security service

387

Licensed Materials – Property of IBM

The transaction authorization provider and the database are designed so that only
the authorization grants are considered. In other words, there is no explicit
authorization revoke. Instead, the absence of a user or group authorization for a
transaction implies that they don’t have access to execute the transaction. Once the
security is turned on, authorization data must be configured for the requests to
succeed in the authorization check.

Configuring LDAP transaction authorization providers
The LDAP transaction authorization provider implements the transaction
authorization check against an LDAP repository. It uses JNDI to connect to the
LDAP server and uses the LDAP search functionality to query the directory for a
relationship between the transaction and the group or user.
In other words, the LDAP transaction authorization provider is independent of the
LDAP server and the directory structure used to store the authorization data.
However, following constraints must be considered before using this provider for a
specific LDAP server:
v The LDAP server must be accessible using the JNDI interface
v The server must conform to LDAP v2 specifications or later, including the LDAP
search filter specifications
v The directory structure containing the group to transaction or user to transaction
association must be searchable using search filters. This search filter must result
in one or more records, only if the group or user is authorized for that
transaction. If the group or user is not authorized for that transaction, the search
filter must return 0 records
Given the generic nature of the LDAP transaction authorization provider’s
implementation, it is expected to work with any LDAP server, if the conditions
above are met. However, it has only been tested, and is only supported on:
v IBM Tivoli Directory Server 5.2
v Netscape Directory Server version 4.1

388

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

The LDAP transaction authorization provider does not provide any caching feature
for the authorized data. Also, the transaction authorization provider does not
provide any administration or management of the authorization data in the
directory server, as these functions are outside the scope of the provider.
See also:
“To configure the LDAP transaction authorization provider”

To configure the LDAP transaction authorization provider
1. Specify the LDAP transaction authorization provider as the runtime transaction
authorization provider in the Configuration and Management repository as
follows:
v /IBM/DWLCommonServices/Security/enabled = true
v /IBM/DWLCommonServices/Security/
transaction_authorization_provider_class_name_1=
com.dwl.base.security.provider.LdapTransactionAuthorizationProvider
2. Specify the following configurations to indicate the LDAP server and how the
LDAP directory tree is implemented:
v /IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/
jndiFactoryClass
v /IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/jndiProviderUrl
v /IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/base
v /IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/Filter/user
v /IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/Filter/group
Refer to “Understanding configuration elements in the Configuration and
Management component” on page 419 for details about these configurations.

Configuring a custom transaction authorization provider
Custom transaction authorization providers can be plugged into InfoSphere MDM
Server security service and used for runtime security authorization checks.
See also:
“To configure a custom transaction authorization provider”

To configure a custom transaction authorization provider
1. Write a transaction authorization provider class to implement the
AuthorizationProvider interface.
This interface is in the com.dwl.base.security.interface package inside the
DWLCommonServices. The class specification for this interface is:

Internally the class can implement the logic directly or by calling into other
third party transaction authorization providers such as SiteMinder, ClearTrust
and others. It should return true only if the user or the group is authorized for
the passed in resource and false otherwise.
Chapter 32. Setting and administering the security service

389

Licensed Materials – Property of IBM

2. Configure the new transaction authorization provider class by specifying its
name in the configuration repository as shown in the Security Configuration
section above.
3. Package the new class in a separate jar, and list this jar in the classpath section
of the DWLCommonServices jar’s manifest file-this makes the class available in
the classpath at runtime.

Using a custom authentication assertions parser
You can create a customized authentication assertions parser for InfoSphere MDM
Server to use in parsing the raw authentication assertions.
Authentication assertions can be passed into the InfoSphere MDM Server
application to assert the identity of the end user that initiated the business
transactions. The assertions must be passed as the authData element of the
DWLContol group within a request. The content of the authData element must not
be parsed by the request parser. Rather, it should be stored as is. The DWLControl
object uses configuration to determine the parser to use in parsing the raw
authentication assertions.

See also:
“To use a custom authentication assertion parser”

To use a custom authentication assertion parser
1. Create a class that implements the ISecurityData parser interface.
2. Configure the item /IBM/DWLCommonServices/Security/SAML/
security_data_parser in the configuration repository with the name of this class
3. Ensure that the authentication assertions are passed in the request in a form
that will not be parsed by the request parser. For example in an InfoSphere
MDM Server XML request, the content of the authData element is placed in a
CDATA section .
The XML response returns the same CDATA section in the response by setting
the Control property authData tag name as a value of the configuration element
/IBM/DWLCommonServices/XML/Character_only_tags.

390

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 33. Controlling the visibility and accessibility of data
You can control who sees what and who can add persistent data using data level
entitlements, set though the Rules of Visibility and access tokens.
Data level entitlements are rules that dictate whether or not a user can view or
persist certain sets of data. InfoSphere MDM Server defines two categories of Data
Level Entitlements:
v Rules of Visibility, which control the data that a user is allowed to view, based
on the defined rules and constraints
v Persistency entitlements, which control the data that a user is allowed to add or
update, based on the defined rules and constraints
This is sometimes referred to as ″row and column level security″ as both the
instance of data and the type of data is considered. An example of controlled
instance of data would be where one financial advisor user is not allowed to view
a specific party because that party is managed by a different financial advisor user.
An example of controlled type of data would be where a given user is not given
permission to view addresses and social security numbers for all parties.
InfoSphere MDM Server processes entitlements at two levels:
v At the database level, which is referred to as Accessibility. For Rules of Visibility,
this provides database-level filtering of data based on access tokens.
v In the data-level entitlements engine. For Rules of Visibility, this provides
post-inquiry filtering of data based on more complex rules and constraints; for
persistency entitlements this ensures that the user is entitled to make adds or
updates to that party, prior to invoking calls on the database.
These two levels, or mechanisms, should be considered together when deriving a
strategy around data level entitlements. For example, the Accessibility mechanism
can provide a coarse-grained filtering of data that a user has access to in a high
performing manner, followed by additional filtering by the Rules of Visibility
engine, which applies a more complex logic that is not suited or possible to contain
in database queries.
These mechanisms are described in:
v “Setting Rules of Visibility” on page 392
v “Protecting operational resources” on page 399
In this section, you will learn:
“Setting Rules of Visibility” on page 392
“Creating and refining a rule” on page 397
“Using the Date Arithmetic operand type” on page 398
“Understanding how database tables are affected by Rules of Visibility” on
page 398
“Sample: Using RoV rules” on page 398
“Protecting operational resources” on page 399

391

Licensed Materials – Property of IBM

Setting Rules of Visibility
In InfoSphere MDM Server, entitlements refer to users’ ability to see information
and perform tasks according to the constrains for the user and the group the user
belongs to. Setting the data level entitlements—which include both Data
Persistency entitlements and Rules of Visibility—are the main subjects of this
chapter.
Execution of the Rules of Visibility (RoV) engine and the Persistency Entitlements
engine is controlled through the Extension Handler component. Enabling and
disabling RoV or Persistency Entitlements requires activating or deactivating the
RoV and Persistency Entitlements extension sets—Rules #11 and #12 in the
EXTENSIONSET table. Furthermore, complex external constraint evaluation rules
may be defined as Java classes or Rule-sets extensions.
For more information about defining RoV, see IBM InfoSphere Master Data
Management Server System Management Guide.
See also:
“Understanding Data Persistency entitlements”
“Understanding Rules of Visibility permissions” on page 394
“Understanding Rules of Visibility data rules” on page 394
“Understanding the Data Entitlement object model” on page 395

Understanding Data Persistency entitlements
The module contains runtime engines that evaluate data level entitlements, and a
user interface and maintenance services that maintain entitlement rules that are
stored in the underlying database.
An Accessor, which may be a user or a user group, is entitled to take an Action,
for example adding, updating, or viewing, on Elements, for example, the party
address, conditional on a set of Constraints.
When you assign data entitlements, note the following points about accessors:
v Entitlements can only be assigned to user types Users and Usergroups
v User ID and user groups are only obtained from the DWLControl object. There
is no interface to third party applications to determine who the user is.
v Accessor profile data, for example the user’s line of business, are only obtained
from the DWLControl object. There is no interface to third party applications to
get user data.
″All Users″ is supported. Rules that are assigned apply to all users of the system.

392

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Extension Handler
Provides a means to extend the InfoSphere MDM Server product by using
an event-based model. The extension handler is configured to respond to
certain events, and then evaluate whether any extension sets need to be
invoked. An extension set can be either a rule set, such as a JRules ilr file,
or a Java class. The Extension Handler is used to plug in product modules
such as Rules of Visibility as well as plugging in client extensions-extended
elements, new client-defined extensions, and new client-defined
transactions.
With regard to data level entitlements, the Extension Handler:
v Invokes the RoV engine at the post of all inquiry and persistence
transactions
v Invokes the Persistency Entitlements engine at the pre of all persistency
transactions by entering the required data in the Extension Handler
tables to execute those engines under prescribed conditions.
RoV Engine
The responsibility of the RoV Engine is to, when given an object hierarchy,
determine which objects and attributes the user is entitled to view. It also
eliminates or filters the objects and attributes that the user is not entitled to
view.
The RoV Engine collaborates with:
v Accessor Factory to determine who the user is from the list of Accessors
v Entitlement Factory to obtain a list of entitlements for the Accessors
v Entitlement Component to evaluate constraints.
Persistency Entitlements Engine
The responsibilities of the Persistency Entitlements Engine is to, when
given an object hierarchy, determine which objects and attributes the user
is entitled to persist.
The Persistency Entitlements Engine collaborates with:
v Accessor Factory to figure out who the user is from the list of Accessors
v Entitlement Factory to obtain a list of entitlements for the Accessors
Chapter 33. Controlling the visibility and accessibility of data

393

Licensed Materials – Property of IBM

v Entitlement Component to evaluate constraints.
Accessor Factory
The responsibility of the Accessor Factory is to, when given the
DWLControl object, determine the user’s ID, user groups, party, and the
groups the party is in. The Accessor Factory reads user information from
the DWLControl object
Accessor Component
The responsibility of the Accessor Component is to provide details of a
given accessor, including the user profile details, agent hierarchy details
and other information.
Entitlement Factory
The responsibility of the Entitlement Factory is to, when given a list of
accessors and an element (object) provide a list of Entitlements.
Entitlement Component
The responsibility of the Entitlement Component is to:
v Evaluate entitlement constraints
v Provide details of elements within an entitlement.

Understanding Rules of Visibility permissions
Permissions include the following:
v When Rules of Visibility and Persistency Data-Level Entitlements is configured
On, the default is that users—or generally, an accessor—have no access unless
access is explicitly granted
v Permissions can only be granted, not restricted
v Users are entitled to take action on data if there is at least one entitlement rule
granting that access, where all the constraints within the rule pass. A union
approach is assumed, in other words, OR is assumed between entitlement rules.
An example of a union approach—a user who belongs to two user groups wants
to access specific data. One of the groups the user belongs to is not allowed to
see that data, the other group is allowed to see the data. Because the user
belongs to at least one group that is allowed to see the data, the user is allowed
to see the data.
v Given the above points, no conflict resolution is required

Understanding Rules of Visibility data rules
Within a transaction, if an accessor does not have access to a given object, then the
accessor does not have access to any of the object’s children—in other words, an
accessor has to be able to see or update a parent object in order to see or update
any child objects.
The runtime engines use code table values. The values for each code table are:

394

Table.Attribute

In Scope Values

Out Scope Values

Entitlement.accessor_key_tp_cd

User_id

Party_id

User_group_name

Party_group_id

Entitlement.accessor_tp_cd

User

Party

Usergroup

Partygroup

All Users

All Parties

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM
Table.Attribute

In Scope Values

Out Scope Values

DataAction.associated_data_tp_cd

Data_association

Object
Attribute

DataAction.data_action_tp_cd

View & Add
View & Update
View
Persist (Add/Update)
All

OperatorType.evaluation_tp_cd

Base_engine

EntitlementConstraint.operator_tp_cd

Equals

Java_plugin

Not equals
Less than
Less than or equal to
Greater than
Greater than or equal
to
Can change to
In set
EntitlementConstraint.constraint_tp_cd

EntitlementLevel

ObjectLevel

AttributeLevel (or
blank/null)
DataAction.permission_tp_cd

Grant

Restrict

EntitlementCondition.rhs_operand_tp_cd

Static Value(s)

Logical Expression

System Date

Accessor Data

DWLControl Element

Externally Obtained

Any

Object.Attribute
value

DateArithmetic

System Timestamp
System Time

Understanding the Data Entitlement object model
After you create a rule, you can add constraints to further refine the rule.
If there are multiple constraints in a single rule, every constraint must evaluate to
true in order for the accessor to be entitled to take action on the data contained in
the rule—″and″ is assumed between constraints on entitlement.

Chapter 33. Controlling the visibility and accessibility of data

395

Licensed Materials – Property of IBM

The object model above shows how the InfoSphere MDM Server business objects
are given additional data elements and behavior that are related to Data
Entitlement functionality.

This object model shows how the Entitlement Rules defined in the database are
represented in objects and their associations with the Entitlement Engine
processing components.

396

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Creating and refining a rule
After you create a rule, you can add constraints to further refine the rule.
If there are multiple constraints in a single rule, every constraint must evaluate to
true in order for the accessor to be entitled to take action on the data contained in
the rule—″and″ is assumed between constraints on entitlement.
When there is more than one constraint within an entitlement rule that involves
the same type of object, or class, then all constraints for a given object must pass.
For example, if ″a given user group can view contracts that are within their line of
business and have a current cash value of less than 1 million dollars″, then there
are two constraints on the contract object and both constraints must evaluate to
true for a given instance of a contract.
See also:
“Setting rule parameters or constraints”
“Implementing simple and complex constraint types”

Setting rule parameters or constraints
As described in IBM InfoSphere Master Data Management Server System Management
Guide, users define the structure of the constraint in terms of element, operator,
operand, and value that the constraint applies to.
A constraint is essentially a logical expression of the left-hand side element, the
operator, and the right-hand side operand type/value. For example:
Left side (element)

Operator

Right side (Operand
type/value)

Partyaddress.Undeliverable.ReasonCode

Equals

Static Value / 9

Address.AddressLastUpdateDate

Cannot change Any (value)/to

These expressions must evaluate to ″true″ to take effect.

Implementing simple and complex constraint types
Constraints may be simple or complex, depending on the left side of the
expression.
If it refers to an element found within a business object contained in the
transaction, and is thus directly available for evaluation, it is a simple constraint.
However, if the left-side data element not directly available, evaluating the
constraint is a much more complex process, involving additional database reads.
There are two kinds of complex constraints: attribute level, and entitlement level. An
attribute level complex constraint applies to a particular data element contained in
a business object within the transaction. An entitlement level complex constraint
applies to all areas the user is entitled to access.
Complex constraints are implemented by overriding the LHS value with the value
produced by the external Operand Builder from the InfoSphere MDM Server

Chapter 33. Controlling the visibility and accessibility of data

397

Licensed Materials – Property of IBM

Extension Framework Java classes or Rule-sets. The Operand Builders are custom
programs that have to be written in conjunction to the constraint definition. See the
OperandBuilder.ilr for an example.
Note: Do not change the DWLStatus.status value in OperandBuilder.

Using the Date Arithmetic operand type
The Date Arithmetic operand type can be used for evaluating the date element of a
data object against a predefined date arithmetic expression that is based on current
system date.
Valid expressions are: SystemDate; n Year; n Month; n Day; +; and-. The
expression must begin with SystemDate.
For example:
(LHS) ContractComponent.IssueDate > (RHS) SystemDate - 1 Year + 15 Days

Understanding how database tables are affected by Rules of Visibility
There are several database tables that are involved in the three aspects of RoV.
Rules Rules are updated using a combination of the ENTITLEMENT,
ENTITLEMENTCONTRAINT, CONSTRAINTPARAM and DATAACTION
tables.
Data Groups
Data Groups are set up in the DATAASSOCIATION,
ASSOCIATEDOBJECT, and ASSOCIATEDATTRIB tables.
User to Rule Associations
Users to Rule Associations are updated in the ACCESSORENTITILE table.

Sample: Using RoV rules
Below are some sample rules for RoV.
Rule

Data Action

Entitlement Conditions

User can update
party information
but is not allowed
to set the
undelivered
reason code to
9-harassment

Permission_tp_cd = grant

Attribute =
PartyAddress.undeliveredReasonType

Data_action_tp_cd = all
Element_group = data group
1, 2, ...

Operator_tp_cd = cannot change to
Rhs_operand_tp_cd = static values
Negate_result_ind = No
Parameter_value = 9 - harassment

All users are only
allowed to view
the city/state/zip
of foreign
addresses that
have not been
standardized

Permission_tp_cd = restrict
Data_action_tp_cd = view
Element_group = data group x
AccessorType = all users

Attribute =
Address.standardFormattingInd
Operator_tp_cd = Equals
Rhs_operand_tp_cd = static values
Negate_result_ind = No
Parameter_value = ″N″

398

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Protecting operational resources
InfoSphere MDM Server can be used to protect party and contract information by
defining access to that information.
In InfoSphere MDM Server, resources can be protected so that only users who have
authorization can operate on the resources. Resources can be any operational assets
in the application, such as files, database records, and so on. A resource is
protected by assigning it an access token value. A user, or the groups to which the
user belongs, may be associated with zero or many access token values. When the
user has an associated access token value that matches the access token value on
the resource, the user is authorized to operate on the resource.
For example, contracts on the system can be assigned different access token values
based on some criteria, such as the line of business to which the contracts belong.
If a financial advisor servicing a particular line of business searches on the
contracts on the system, the advisor can only view the contracts belonging to that
line of business.
Currently, resources that can be protected include CONTACT and CONTRACT
records in the database. In other words, InfoSphere MDM Server can be deployed
to protect party and contract information.
To enable protected resources, you must:
v Implement authorization for users and groups
v Understand how resources are operated on when this feature is enabled
v Customize access to protected resources, if you have created any extension for
InfoSphere MDM Server
See also:
“Enabling protected resources”
“Implementing authorization”
“Understanding operations on protected resources” on page 400
“Setting up access tokens for users and groups” on page 400
“Customizing access to protected resources” on page 403

Enabling protected resources
To enable protected resources, set the INACTIVE_IND value to N on records 119 and
120 in the EXTENSIONSET table. By default, the values are Y, which means this
feature is disabled.

Implementing authorization
Authorization is implemented using access tokens, which must be set.
A user, or the groups to which the user belongs to, can be associated with zero to
many access token values. The access token values are set on the DWLControl object
so that the values are accessible during the transaction.
InfoSphere MDM Server provides a data model to support a default access token
authorization.

Chapter 33. Controlling the visibility and accessibility of data

399

Licensed Materials – Property of IBM

The com.dwl.base.accessToken.DefaultAccessTokenAccessor class is used to
retrieve the collection of access tokens associated with the user and group. It then
sets this collection to the DWLControl object. The collection of access tokens can be
retrieved using the DWLControl.getAccessTokenCollection() method during the
transaction. The collection can be queried using the methods provided by the
com.dwl.base.accessToken.AccessTokenCollection class.

Implementing another access token accessor
You do not have to manage access tokens with the default data model. If you have
a different data model, or an external authorization system that you want to
integrate with InfoSphere MDM Server, you may want to use those instead of the
default data model.
To override the default access token accessor, set the CONFIGELEMENT record
/IBM/DWLCommonServices/AccessToken/AccessTokenAccessor/className to a value
that corresponds to another accessor class implementation. The accessor class must
implement the com.dwl.base.accessToken.AccessTokenAccessor interface.

Understanding operations on protected resources
Before you begin to define access for users, you must understand how users with
different levels of access will be able to work with protected resources.
Currently CONTACT and CONTRACT records can be protected. These two tables
contain an ACCESS_TOKEN_VALUE column.
If this column on a record contains null, that record is not protected. That is, any
user or group can operate on that record. If this column on a record contains a
value, that record is protected. Only users that are associated with an access token
value that matches the value in that column can operate on that record.
Default access token
The default access token allows a resource to be created and protected with
a specific access token value.
Global access token
The global access token gives a user authorization to any protected
resource, even if the user is not associated with an access token value that
matches the access token value assigned to the resource. For example, an
administrator can be associated with a global access token.

Setting up access tokens for users and groups
Setting up access tokens for users and groups requires planning based on business
needs.

400

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

For example, you can set up access tokens based on lines of business, by
department, or use other criteria. It is generally more manageable to set up access
tokens for groups, and then assign the group to different users.
The following tables show sample records that set up access tokens for users and
groups.
Table 35. Sample data for USERPROFILE table
USER_PROFILE_ID

USER_ID

GUEST

USER

ADMINISTRATOR

Table 36. Sample data for GROUPPROFILE table
GROUP_PROFILE_ID

GROUP_NAME

CORPORATE

INVESTMENT

Table 37. Sample data for ACCESSTOKEN table
ACCESS_TOKEN_ID

ACCESS_TOKEN_VALUE

GLOBAL_IND

1000

2000

3000

4000

Table 38. Sample data for USERACCESSTOKEN table
USER_ACCESS_TOKEN_ID

ACCESS_
TOKEN_ID

USER_PROFILE
_ID

DEFAULT_IND

Table 39. Sample data for GROUPACCESSTOKEN table
GROUP_ACCESS
_TOKEN_ID

ACCESS_TOKEN
_ID

GROUP_PROFILE
_ID

DEFAULT_IND

The collection of access tokens are based on the element, which is
the user’s name, and element, which are the groups the user belongs
to, in the element in the request.
Suppose the system contains 4 contracts as follows:
Table 40. Example access token values
CONTRACT_ID

...

ACCESS_TOKEN_VALUE

10000000
20000000

3000

30000000

4000
Chapter 33. Controlling the visibility and accessibility of data

401

Licensed Materials – Property of IBM
Table 40. Example access token values (continued)
CONTRACT_ID

...

40000000

ACCESS_TOKEN_VALUE
1000

The following examples illustrate how these 4 contracts can be operated on.
Example 1
Request:

GUEST
100

Associated access token values: None
Operations
v If this request is to add a contract, the contract is added with an
ACCESS_TOKEN_VALUE of null
v If this request is to update contract 20000000, this request is not allowed as this
contract has an access token value of 3000
v If this request is to search contracts, this request returns contract 10000000 as this
contract has an access token value of null
Example 2
Request:

USER
100

Associated access token values: 3000
Operations
v If this request is to add a contract, the contract is added with an
ACCESS_TOKEN_VALUE of null
v If this request is to update contract 20000000, this request is allowed as this
contract has an access token value of 3000
v If this request is to update contract 30000000, this request is not allowed as this
contract has an access token value of 4000
v If this request is to search contracts, this request returns contract 10000000 and
contract 20000000
Example 3
Request:

USER
100
INVESTMENT

Associated access token values: 3000, 4000 (default)

402

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Operations
v If this request is to add a contract, the contract is added with an
ACCESS_TOKEN_VALUE of 4000.
v If this request is to update contract 30000000, this request is allowed as this
contract has an access token value of 4000
v If this request is to update contract 40000000, this request is not allowed as this
contract has an access token value of 1000
v If this request is to search contracts, this request returns contract 10000000,
contract 20000000 and contract 30000000
Example 4
Request:

ADMINISTRATOR
100
CORPORATE

Associated access token values: 1000 (global), 2000
Operations
v If this request is to add a contract, the contract is added with an
ACCESS_TOKEN_VALUE of null
v If this request is to update contract 30000000, this request is allowed as this user
has a global access token
v If this request is to search contracts, this request returns all 4 contracts

Customizing access to protected resources
You can customize the access to protected resources using access tokens.
Currently, the CONTACT and CONTRACT tables are protected by assigning a
value in the ACCESS_TOKEN_VALUE column. When extending the BObjQuery class for
these two tables, append a specially marked SQL segment to search for possibly
zero to many access token values that are associated with the user. At run time,
InfoSphere MDM Server resolves the collection of access token values.
The specially-marked SQL segment is shown below.
For selecting from the CONTACT table:
<< AND (CONTACT.ACCESS_TOKEN_VALUE IS NULL OR CONTACT.ACCESS_TOKEN_VALUE IN ())>>

For selecting from the CONTRACT table:
<< AND (CONTRACT.ACCESS_TOKEN_VALUE IS NULL OR CONTRACT.ACCESS_TOKEN_VALUE IN ())>>

This segment should be appended to an SQL statement where selecting from the
CONTACT or CONTRACT table is required. For example:
SELECT CONTACT.CONT_ID AS CONTACT_CONT_ID, CONTACT.ACCE_COMP_TP_CD
AS ACCECOMPTPCD24, CONTACT.PREF_LANG_TP_CD AS PREFLANGTPCD24,
CONTACT.CREATED_DT AS CONTACT_CREATED_DT, CONTACT.SINCE_DT AS SINCE_DT,
CONTACT.LEFT_DT AS LEFT_DT, CONTACT.INACTIVATED_DT AS INACTIVATEDDT24,
CONTACT.CONTACT_NAME AS CONTACTNAME24, CONTACT.PERSON_ORG_CODE AS PERSONORGCODE24,
CONTACT.SOLICIT_IND AS SOLICITIND24, CONTACT.CONFIDENTIAL_IND AS CONFIDENTIALIND24,
CONTACT.CLIENT_IMP_TP_CD AS CLIENTIMPTPCD24, CONTACT.CLIENT_ST_TP_CD AS CLIENTSTTPCD24,
CONTACT.CLIENT_POTEN_TP_CD AS CLIENTPOTENTPCD24, CONTACT.RPTING_FREQ_TP_CD AS RPTINGFREQTPCD24,
CONTACT.LAST_STATEMENT_DT AS LASTSTATEMENTDT24, CONTACT.PROVIDED_BY_CONT AS PROVIDEDBYCONT24,
CONTACT.LAST_UPDATE_DT AS LASTUPDATEDT24, CONTACT.LAST_UPDATE_USER AS LASTUPDATEUSER24,
CONTACT.ALERT_IND AS CONTACT_ALERT_IND, CONTACT.LAST_UPDATE_TX_ID AS LASTUPDATETXID24,

Chapter 33. Controlling the visibility and accessibility of data

403

Licensed Materials – Property of IBM
DO_NOT_DELETE_IND DO_NOT_DELETE_IND, CONTACT.LAST_USED_DT AS LASTUSEDDT,
CONTACT.LAST_VERIFIED_DT AS LASTVERIFIEDDT, CONTACT.SOURCE_IDENT_TP_CD AS SOURCEIDENTTPCD,
CONTACT.DO_NOT_DELETE_IND DO_NOT_DELETE_IND, CONTACT.ACCESS_TOKEN_VALUE AS ACCESS_TOKEN_VALUE,
CONTACT.PENDING_CDC_IND AS PENDING_CDC_IND FROM CONTACT WHERE ( CONTACT.CONT_ID = ? )
<< AND (CONTACT.ACCESS_TOKEN_VALUE IS NULL OR CONTACT.ACCESS_TOKEN_VALUE IN ())>>

404

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Chapter 34. Using the Configuration and Management
components
The Configuration and Management components support the operational
configuration and management of applications. They enable administrative users to
deploy, fine-tune, and manage applications within their runtime environment.
The Configuration and Management components allow you to configure and
manage both standalone and enterprise applications. Currently, these components
are only available for InfoSphere MDM Server and InfoSphere MDM Server Event
Manager enterprise applications, not for the InfoSphere MDM Server Batch
Controller application.
For details on using the Management Agent and Management Console, see the
Using the Configuration and Management Components section of the IBM
InfoSphere Master Data Management Server System Management Guide. This guide also
includes a section with information about performing bootstrap configuration for
the Configuration and Management components.
In this section, you will learn:
“Understanding configuration”
“Learning the Configuration and Management architectural overview” on page
406
“Understanding the stand-alone enterprise application” on page 406
“Understanding J2EE clustered enterprise application” on page 407
“Understanding custom clustered enterprise application” on page 408
“Understanding configuration definitions and schemas” on page 409
“Understanding Configuration and Management database structure” on page
411
“Using the Application Configuration Client” on page 414
“Understanding the Configuration class” on page 414
“Understanding configuration methods” on page 415
“Understanding the ConfigContext class and public Node getConfigItemsMap()
method” on page 416
“Adding configuration nodes and items” on page 416
“Broadcasting configuation changes” on page 417
“Working with configuration data” on page 417
“Understanding configuration elements in the Configuration and Management
component” on page 419

Understanding configuration
To recognize the different sets of requirements that apply to application
configuration before and after the application has been deployed in the operational
environment, configuration is divided up into two categories: static and dynamic.
v Static—Usually new code or resources can be added as a result of changing
static configuration. Consequently, the application would have to be rebuilt,

405

Licensed Materials – Property of IBM

retested, and redeployed. Static configuration setting can be changed through the
Configuration and Management system, but changed values will only take effect
after you restart the application server.
v Dynamic—Configuration that controls the behavior of the application while
operational is considered to be dynamic. The application observes and reacts to
changes in its dynamic configuration without having to be rebuilt, retested, or
redeployed. Changes in dynamic configuration do not result in application
resources having to be added, changed, or removed.

Learning the Configuration and Management architectural overview
The focal point of the Configuration and Management components is the
Configuration and Management database that stores the application configuration.
Applications read their configuration from the Configuration and Management
database through the application configuration client. Administrators use the
Management Console to view and change the configuration stored in the
Configuration and Management database through the Management Agent.
There are three basic topologies that are relevant for the understanding of how the
Configuration and Management components interact. These topologies are based
on the types of managed applications:
v Stand-alone enterprise application
v J2EE clustered enterprise application
v Custom clustered enterprise application
In all of these topologies, the Configuration and Management database is available
either locally or remotely to both the Management Agent and the application. The
Management Console and the Management Agent are always located on the same
computer. The main differences between these topologies are found in the ways in
which the Management Agent communicates with the application to inform it
about changes to configuration.

Understanding the stand-alone enterprise application
In this topology, the Management Agent communicates with the management EJB
(MEJB) running on the same application server on which the application runs.
The Management Agent uses the management EJB to locate the JMX MBean of the
application and to invoke commands on it.

406

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Management
Console
RMI

Application Server
Application
Management RMI
IIOP
Agent

MEJB

Application

JDBC
JDBC

Configuration
Repository

When changes to the dynamic configuration settings are committed to the
Configuration and Management database, the Management Agent notifies the
application’s MBean about these changes so that the application dynamically
reloads the configuration.
In this configuration, the Management Agent and the Management Console are
located on the same computer as the application server.

Understanding J2EE clustered enterprise application
In this topology, the application is clustered using the clustering capabilities of the
J2EE application server. The Management Agent communicates with the
management EJB on the managing node of the application server; that is, the
deployment manager for WebSphere Application Server Network Deployment
Edition.
The Management Agent uses the management EJB to locate particular deployments
and instances of the application in the clustered environment or, more precisely,
the management beans that control these deployments and instances. This is
required so that the Management Agent can inform the application about
configuration changes.

Chapter 34. Using the Configuration and Management components

407

Licensed Materials – Property of IBM

Management
Console

RMI

Application Server
Application
Management
Agent

RMI
IIOP

MEJB

JMXMP

Application Server
(Managed Node)
JDBC

Application

JDBC

Configuration
Repository
Application
Application Server
(Managed Node)
In this configuration, the Management Agent and Management Console are located
on the same computer as the managing node of the application server, but not
necessarily the same computer as the application itself.
There are no additional administrative actions to be taken whenever the structure
of the cluster and the mapping of the application to the cluster changes. The
Management Agent automatically discovers the topology of the cluster through the
management EJB.

Understanding custom clustered enterprise application
In this topology, the application is clustered in custom ways. The enterprise
application is deployed multiple times and it does not appear as a clustered
application to the J2EE application server.
The Management Agent communicates with each of the management EJBs on each
of the application servers on which the clustered applications are deployed. The
Management Agent must be configured to know about each individual node in the
custom cluster so that it can inform each application instance about configuration
changes.

408

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

Management
Console

RMI

Application
Management
Agent

RMI/IIOP

Application
Server
MEJB
JDBC

Application

Configuration
Repository

JDBC

Application
Server
MEJB

Application

In this configuration, the Management Agent and Management Console are not
collocated on the same computer with any particular application Server.
When there is a change in the structure of the custom cluster, the bootstrap
configuration of the Management Agent needs to be updated to reflect the change
in structure. For details, see the Management Agent bootstrap configuration section
in the IBM InfoSphere Master Data Management Server System Management Guide.

Understanding configuration definitions and schemas
Configuration definitions are XML documents that contain all the configuration
items and their values, as defined during the development process.
Chapter 34. Using the Configuration and Management components

409

Licensed Materials – Property of IBM

These definitions are packaged in the application archive. They can be modified
during the application assembly phase and repackaged with the application. At
deployment, the configuration definitions are used to establish the initial
configuration in the configuration repository. They can also be used as the vehicle
for replicating existing configuration.
Configuration definitions can contain both static and dynamic configuration. For
an operational application, the Management Console allows administrators to
change both dynamic configuration items and static configuration items, but will
give warnings before changing static configuration items.
The configuration definition distributed with the application is considered to
contain the factory defaults for the configuration. Any changes to this
configuration can potentially be overwritten by upgrades to subsequent versions of
the application. If you want to change your configuration while retaining factory
defaults, you should do so from the Management Console after the application
(and its configuration) is deployed.
The configuration is structured hierarchically and is therefore well-suited to be
represented in an XML document. Configuration consists of nodes and items.
Nodes are containers for other nodes and items while items represent the actual
configurable values. In the XML document the nodes correspond to XML entities
while the items correspond to entity attributes.
The root node of the application XML document is the application name in which
any spaces have been replaced with hyphens (″-″). If the application consists of
modules (for example, an enterprise application that contains EJB and Web
modules), the root’s immediate child nodes correspond to those modules. If the
name of root node of a module’s XML documents are same, then all child nodes
are put under the same root node. The name of the root node of all modules is
IBM. The rest of the nodes are used to structure the configuration logically
according to the functional areas within the application or within each module.
The following is an example of application configuration XML:

410

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

When the application consists of modules, the final configuration definition is
compiled at deployment time by combining together all the configuration
definitions, the dwl-config.xml files, found inside the modules into a master
configuration definition.
The location of the configuration definitions in the packaged application depends
on the managed application type:
v J2SE Application—There is only one configuration definition per application.
The name of the XML document is dwl-config.xml and it can be found in the
META-INF directory of the application JAR.
v J2EE Application—There is one configuration definition document for each EJB
or Web module and one for the application. All configuration definitions are
contained in XML documents named dwl-config.xml that are located in the
META-INF directory of the EJB module JAR, Web module WAR, or enterprise
application EAR. At deployment time, all the configuration definitions of the EJB
and Web modules contained in an enterprise application are merged into the
configuration definition found in the enterprise application EAR file. Items in
the EAR’s configuration definition override items in the module-specific
definitions.
Each configuration definition has an XML schema associated with it. This schema
is called the configuration definition schema and it is contained in a file named
dwl-config.xsd that is packaged together with the corresponding configuration
definition document in the EJB, web or application archive. The application’s
schema references the EJB and Web modules schemas. The schema serves as the
metadata to validate the configuration. It can provide information about the
cardinalities of the configuration items relative to each other, types of data, and
possible values for enumerated items. Configuration definition schemas are
deployed in the Configuration and Management database at the same time that the
application configuration is deployed.
Configuration definition schemas of InfoSphere MDM Server modules use only
local element to avoid name conflict while merging modules’ configuration
schemas. Use the same method for configuring the definition schemas of client
modules. Similar to the way in which the configuration definitions of the modules
are compiled into a master configuration definition for the application, the
configuration definition schemas for the modules (dwl-config.xsd files) are
combined into a master configuration definition schema for the application.

Understanding Configuration and Management database structure
The application configuration is represented in two ways: as an XML hierarchical
structure; and as a flat map structure.
v XML hierarchical structure—Consists of nodes and items. Each node can
contain other nodes and items. Items contain the actual configuration values and
the default values. There is only one node that is the root of the configuration
tree. The XML hierarchical structure is used when you update a configuration
value, or add or delete a configuration node or item.
v Flat map structure—Consists of key value pairs, whose key is the canonical
name of a specific configuration setting, and whose value is the value of a
Chapter 34. Using the Configuration and Management components

411

Licensed Materials – Property of IBM

specific configuration setting. For performance reasons the map structure is used
when reading the configuration value, export configuration settings.
The Configuration and Management database uses a database to store both static
and dynamic configuration. Multiple applications can use the same database to
store their configurations.

v appsoftware entity—Represents a software application whose configuration has
been deployed. This entity contains configuration and management information
that is specific to a particular application version. The natural key for this entity
is the name and version pair.
– application_id—Specifies anumeric artificial key used to uniquely identify an
application. This is used instead of the composite natural key to help reduce
the size of the key.
– name—Specifies the name of the application. This name corresponds to the
application or J2EEApplication key properties found in the object name of the
application management bean.
– version—Specifies a string that represents the version of the application. The
format of this string is ##.##.##.### representing the major version, minor
version, fix pack and hot fix numbers.
– config_schema—Specifies an XML schema representing the configuration
definition schema used by this application version. This attribute is a CLOB.
– Config_XML—Specifies XML schema representing the configuration
definition used by this application version. This attribute is a CLOB.
– last_update_dt—Specifies the date and time of the last update operated on
this entity. If not provided, this attribute defaults to the date and time of the
access.
– last_update_user—Specifies the user account name of the user that initiated
the update.
v appdeployment entity—Corresponds to an installation (deployment) of the
application in the operational environment. Each deployment is uniquely
identified by its name across all applications of the same kind and version. The
deployment name and the application key form the natural key for this entity.
– deployment_id—Specifies an artificial numeric key used to uniquely identify
a deployment of a particular application version. This is used instead of the
composite natural key to help reduce the size of the key.

412

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

– name—Specifies the name of the deployment. This name must be unique
across all deployments of an application version. The name is also the natural
key of this entity.
– last_update_dt—Specifies the date and time of the last update operated on
this entity. If not provided, this attribute defaults to the date and time of the
access.
– last_update_user—Specifies the user account name of the user that initiated
the update.
v appinstance entity—Corresponds to a runtime instance of an application. It is
used to identify application instances that need to override configuration items.
If no application instance is defined for an application deployment, then all
instances of that deployment use exactly the same configuration.
– instance_id—Specifies aa artificial numeric key used to uniquely identify an
instance of a particular application version. This is used instead of the
composite natural key to help reduce the size of the key.
– name—Specifies the name of the instance. This name must be unique across
all instances of a deployment. The name is also the natural key of this entity.
– deployment_id—Specifies an artificial numeric key used to uniquely identify
a deployment of a particular application version. This is used instead of the
composite natural key to help reduce the size of the key.
– last_update_dt—Specifies the date and time of the last update operated on
this entity. If not provided, this attribute defaults to the date and time of the
access.
– last_update_user—Specifies the user account name of the user that initiated
the update.
v configelement entity—Corresponds to one configuration element. An element
can be either a node or an item. A node contains other elements. An item
contains a value. The natural key of this entity is name of the configuration
element.
– element_id—Specifies an artificial numeric key used to uniquely identify a
configuration element within a deployment or application instance. This is
used instead of the composite natural key to help reduce the size of the key.
– name—Specifies a hierarchical name that uniquely identifies a configuration
item within the scope of a deployment or application instance. This is also the
natural key of this entity.
– value—Specifies the currently-assigned value of the configuration item in its
string representation. If this field is null, then the value from the
value_default field is used. If this element is a node, the value is always null.
– value_default—Specifies the factory default value of the configuration item in
its string representation. If this element is a node, the value_default is always
null.
– deployment_id—Specifies an artificial numeric key used to uniquely identify
a deployment of a particular application version. This is used instead of the
composite natural key to help reduce the size of the key.
– instance_id—Specifies an artificial numeric key used to uniquely identify an
instance of a particular application version. This is used instead of the
composite natural key to help reduce the size of the key.
– last_update_dt—Specifies the date and time of the last update operated on
this entity. If not provided, this attribute defaults to the date and time of the
access.
– last_update_user—Specifies the user account name of the user that initiated
the update.
Chapter 34. Using the Configuration and Management components

413

Licensed Materials – Property of IBM

Using the Application Configuration Client
Applications can use the Application Configuration Client to access the
configuration at runtime. This client provides read-only access to the Configuration
and Management database using a configuration repository adapter. The adapter
itself is pluggable and can be replaced to access different types of configuration
repositories. InfoSphere MDM Server provides a database-based Configuration and
Management database and its corresponding repository adapter.
The Application Configuration Client provides programmatic read-only access to
the application’s configuration. The Configuration class and the ConfigContext
interface are the main elements of the Application Configuration Client:

Understanding the Configuration class
The Configuration class provides applications with read-only access to the
Configuration and Management database. The Configuration class is a singleton
whose sole instance can be obtained through the getConfiguration() method.
Attention: In J2EE applications, a singleton does not span multiple JVM
instances. Therefore, the semantics of the Configuration singleton are only
maintained while in the same JVM instance as the calling code.
You can browse the Configuration and Management database with the
Configuration object using one of two modes:
v Context-free access—Allows the calling code to see the latest values in the
Configuration and Management database. One effect of context-free access is
that multiple queries on a given configuration item can yield different values if

414

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

an administrator has changed that item outside of the application. This might be
an undesired effect (for example, when an application is processing a business
transaction that requires a consistent view of the configuration).
Context-based access—Ensures that, within the scope of an established context,
an application can query a configuration item any number of times and it will
still yield the same result, regardless of whether that item has been modified
outside of the application.
For context-based access, it must be noted that the context is valid only within
the process (JVM) in which it was created. If an application needs to ensure a
consistent view of the configuration across multiple processes, it must itself
ensure that the configuration is passed in remote calls from process to process.
Another option is the use of a distributed cache for the Configuration singleton.
In addition to providing access to the Configuration and Management database,
the Configuration class provides information about the application’s name and
version. These are retrieved from the manifest file in the application’s archive (JAR,
WAR, or EAR). The class that triggers the Configuration class to load must itself be
loaded from an archive. This archive must contain a manifest file
(META-INF/MANIFEST.MF) that, within its main attributes, contains two
attributes: Application-Name and Application-Version.

Understanding configuration methods
The Configuration and Management components support several configuration
methods.
v public synchronized static Configuration getConfiguration()—Provides the
caller with the sole instance of the Configuration singleton.
v public ConfigContext createContext()—Obtains a context to access the
Configuration and Management database. This context can then be used with
other methods that are capable of context-based access to the Configuration and
Management database.
v public Node getNode(String canonicalName)—Retrieves a configuration node
based on its canonical name, in a context-free manner.
A canonical node name consists of the names of all the node’s ancestors’ names
up to the root of the configuration tree, separated by the forward slash character
(/). The root is designated by a forward-slash character.
An example of a canonical node name is IBM/Party/Search.
v public Node getNode(String canonicalName, ConfigContext
context)—Retrieves a configuration node based on its canonical name, in a
context-based manner.
v public Item getConfigItem(String canonicalName)—Retrieves a configuration
item based on its canonical name, in a context-free manner.
A canonical item name consists of the names of all the node’s ancestors’ names
up to the root of the configuration tree, separated by the forward slash character
(/). The root is designated by a forward-slash character.
An example of a canonical item name is /IBM/Party/Search/maxSearches
Attention: Item getItem(String canonicalName) is deprecated
v public Item getItem(String canonicalName, ConfigContext context)—Retrieves
a configuration item based on its canonical name, in a context-based manner.
v public synchronized void refresh()—Triggers a refresh of the configuration to
ensure that the latest changes to the dynamic config settings made in the
Configuration and Management database are visible to the application.
Chapter 34. Using the Configuration and Management components

415

Licensed Materials – Property of IBM

The refresh operation only applies to context-free configuration. Context-based
configuration access is unaffected and the application continues to see the same
values for the configuration items as when the context was created.
When the refresh operation is invoked, the configuration may reload
immediately, but it is not guaranteed. The configuration is reloaded, at the latest,
at the time of the first access after a refresh operation was invoked. That means
that more changes can occur in the interval between when the refresh operation
was invoked and the first configuration access.
Applications should not rely on the timing of these operations to synchronize
themselves with changes in the Configuration and Management database.
Attention: getItem(String canonicalName, ConfigContext context) is
deprecated.
v public synchronized void refresh(Collection canonicalNodeNames)—Triggers a
refresh of the configuration. This is similar to refresh(), except that it refreshes
particular nodes that are passed as parameters to the call.
The refresh applies to the nodes passed as parameters and all their configuration
sub-trees.
v public static String getApplicationName()—Returns the name of the application
as recorded in the manifest of the application archive under the
Application-Name attribute.
v public static String getApplicationVersion()—Returns the version of the
application as recorded in the manifest of the application archive under the
Application-Version attribute.

Understanding the ConfigContext class and public Node
getConfigItemsMap() method
Be familiar with the class and method for the Configuration and Management
components. The method retrieves information from the context.
The ConfigContext class is used to establish a read-only configuration context in
which the configuration is guaranteed not to change for as long as the context is
maintained. This is useful for clients that need to ensure that all the code executing
under the same transaction will have a consistent view of the configuration,
independent of changes to the configuration external to the transaction.
Note: The context only applies within the same process (JVM) in which it was
created.
For transactions that execute across many processes, the client is responsible for
ensuring a consistent view of the configuration, possibly by passing those
configuration values through all the method calls in the transaction.
The public Node getConfigItemsMap() method retrieves the map of the
configuration corresponding to the context.

Adding configuration nodes and items
New configuration nodes and items can be added as part of the development
process. All configuration items can also be customized as part of the application
assembly process.
See also:

416

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

“To add configuration nodes and items”

To add configuration nodes and items
1. Add the new configuration nodes and items to the configuration definition,
which is located in the dwl-config.xml file.
If you are extending the base InfoSphere MDM Server product with your own
configuration definition, put this definition file in the META-INF directory of
the extension module’s JAR file.
2. Add the new configuration nodes and items to the configuration definition
schema, which is located in the dwl-config.xsd file.
If you are extending the base InfoSphere MDM Server product with your own
configuration definition schema, put this definition file in the META-INF
directory of the extension module’s JAR file.
When the system manager changes the value of the configuration setting
through Management Console, it validates the value against the configuration
schema. Therefore, put constraints on making changes to those values.

Broadcasting configuation changes
The JMX notification model is used to broadcast configuration data changes when
there is a refresh change to a dynamic configuration item. If the broadcast change
occurs before a refresh, put the change in preRefresh; if the broadcast change
occurs after the refresh, put the change in postRefresh.
See also:
“To broadcasting configuration data changes”

To broadcasting configuration data changes
1. Register JMX listeners to receive and handle configuration data change
notification. The name of JMX listener is configured in the bootstrap.properties
file.
Here is an example of how to update the bootstrap.properties file:
JMXListeners.className.1= com.dwl.management.config.client.mbean.listeners.LoggingChangeListenerMBean
JMXListeners.className.2=

2. Use the implementation of the LoggingChangeListenerMBean to dynamically
change logging level and file path setting.

Working with configuration data
The individual dwl-config.xml files at the module level are combined into a master
configuration definition file at deployment time. Similarly, the dwl-config.xsd files
are combined into a master configuration definition schema file. Once deployed,
use Management Console to change the value of any of the configuration elements.
This is described in the topic on “Understanding configuration definitions and
schemas” on page 409.
The following diagram shows the deployment for the base InfoSphere MDM
Server modules:

Chapter 34. Using the Configuration and Management components

417

Licensed Materials – Property of IBM

If you create your own module to extend InfoSphere MDM Server, including your
own dwl-config.xml and dwl-config.xsd files, deploy them so that they are
combined into the master configuration definition file and master configuration
definition schema file.
The following diagram shows an example of deployment with extensions:

InfoSphere MDM Server provides several options to deploy and remove the
configuration data. You can use the Management Console to perform any of these
options:
v Deploying the application configuration—Uses the EAR file as the input and
combines the dwl-config.xml and dwl-config.xsd in each of the modules found
in the EAR file. This option uses the default value for each of the configuration
element. Use this option if you want to load the entire master configuration
definition with the default values.
v Removing the application configuration—Removes the entire deployed master
configuration definition. Use this option if you want to remove the entire
deployment.
Note: Any value that you have specified for any configuration elements will be
lost.
v Partially deploy the application configuration—Uses a JAR file (that is, a
module) as the input and adds nodes to the deployed master configuration

418

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

definition based on the way the context is defined in the dwl-config.xml and
dwl-config.xsd in the JAR file. If you have specified any values for configuration
elements in any existing nodes, the values will not be affected. Use this option if
you want to add to the master configuration definition.
To use this option, you must also ensure that the META-INF/MANIFEST.MF
inside the JAR file contains the following entries:
Manifest-Version: 1.0
Created-By: MDM (IBM Corporation)
Application-Name:
Application-Version:

Note: You must restart the server to make this option take effect.
v Partial remove the application configuration—Uses the JAR file (that is, a
module) as the input and removes the configuration elements under the module
from the deployed master configuration definition. If you have specified any
values for configuration elements in the remaining nodes, the values will not be
affected. Use this option if you want to remove portion of the master
configuration definition.
To use this option, you must also ensure that the META-INF/MANIFEST.MF
inside the JAR file contains the following entries:
Manifest-Version: 1.0
Created-By: MDM (IBM Corporation)
Application-Name:
Application-Version:

Understanding configuration elements in the Configuration and
Management component
The Configuration and Management component manages several properties.

/IBM/BusinessServices/EntitySuspectProcessing/
collapsedEntitiesNumberLimit
v Description—Specifies the maximum number of A1 suspects returned by the
FindAllSuspectMatchRules external rule. If this value is 0, this rule returns all
A1 matches found.
v Default value—15
v Dynamic—true

/IBM/BusinessServices/EntitySuspectProcessing/
EntityLinkReasonType/collapse
v Description—Specifies the type code indicating that the entity is linked to
another entity because the entity was collapsed. This value should be one of the
LINK_REASON_TP_CD values in the CDLINKREASONTP table.
v Default value—1
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
EntityLinkReasonType/split
v Description—Specifies the type code indicating that the entity is linked to
another entity because the entity was split. This value should be one of the
LINK_REASON_TP_CD values in the CDLINKREASONTP table.
v Default value—2
v Dynamic—false
Chapter 34. Using the Configuration and Management components

419

Licensed Materials – Property of IBM

/IBM/BusinessServices/EntitySuspectProcessing/
InactiveReasonType/collapse
v Description—Specifies the type code indicating that the entity is inactive
because the entity was collapsed. This value should be one of the
INACT_REASON_TP_CD values in the CDINACTREASONTP table.
v Default value—1
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
InactiveReasonType/split
v Description—Specifies the type code indicating that the entity is inactive
because the entity was split. This value should be one of the
INACT_REASON_TP_CD values in the CDINACTREASONTP table.
v Default value—2
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
ProcessingDepth/LinkDepthNumberLimit
v Description—Specifies the maximum number of times to retrieve products
recursively in the getLinkedProducts transaction.
v Default value—15
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
SuspectReasonType/systemMarked
v Description—Specifies the type code indicating that the suspect is marked by
the system. This value should be one of the SUSP_SOURCE_TP_CD values in
the CDSUSPECTSOURCETP table.
v Default value—2
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
SuspectReasonType/userMarked
v Description—Specifies the type code indicating that the suspect is marked by a
user. This value should be one of the SUSP_SOURCE_TP_CDvalues in the
CDSUSPECTSOURCETP table.
v Default value—1
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
SuspectStatusType/criticalChangeResolved
v Description—Specifies the type code indicating that the suspect was
investigated, and the critical data change was resolved. This value should be one
of the SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP table.
v Default value—25
v Dynamic—false

420

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/BusinessServices/EntitySuspectProcessing/
SuspectStatusType/duplicateEntity
v Description—Specifies the type code indicating that the suspect was
investigated, and the entities are duplicates. This value should be one of the
SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP table.
v Default value—24
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
SuspectStatusType/duplicateEntityDoNotCollapse
v Description—Specifies the type code indicating that the suspect is under
investigation, the entities are suspect duplicates, and should not be collapsed.
This value should be one of the SUSP_ST_TP_CD values in the
CDSUSPECTSTATUSTP table.
v Default value—26
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
SuspectStatusType/notDuplicate
v Description—Specifies the type code indicating that the suspect was
investigated, and the entities are not duplicates. This value should be one of the
SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP table.
v Default value—23
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
SuspectStatusType/pending
v Description—Specifies the type code indicating that the suspect is under
investigation, and the critical data change for the entity is pending. This value
should be one of the SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP
table.
v Default value—22
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/
SuspectStatusType/suspectDuplicate
v Description—Specifies the type code indicating that the suspect is under
investigation, and the entity and the suspect are duplicates. This value should be
one of the SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP table.
v Default value—21
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/SuspectType/
closeMatch
v Description—Specifies the type code indicating the close match suspect. This
value should be one of the SUSPECT_TP_CD values in the CDSUSPECTTP table.
v Default value—12
v Dynamic—false

Chapter 34. Using the Configuration and Management components

421

Licensed Materials – Property of IBM

/IBM/BusinessServices/EntitySuspectProcessing/SuspectType/
exactMatch
v Description—The type code indicating the exact match suspect. This value
should be one of the SUSPECT_TP_CD values in the CDSUSPECTTP table.
v Default value—11
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/SuspectType/
notMatch
v Description—Specifies the type code indicating suspects do not match. This
value should be one of the SUSPECT_TP_CD values in the CDSUSPECTTP table.
v Default value—14
v Dynamic—false

/IBM/BusinessServices/EntitySuspectProcessing/SuspectType/
possibleMatch
v Description—The type code indicating the possible match suspect. This value
should be one of the SUSPECT_TP_CD values in the CDSUSPECTTP table.
v Default value—13
v Dynamic—false

/IBM/CoreUtilities/DateValidation/dateFormat
v Description—Specifies the format with which to represent a date in a date field.
A date field contains the year (YYYY), month (MM) and day (DD), which can be
represented in one of the following formats:
– 1 = YYYY-MM-DD
– 4 = YYYY-DD-MM
– 13 = MM-DD-YYYY
– 16 = DD-MM-YYYY
The separator between the year, month, and date is defined in the
/IBM/CoreUtilities/DateValidation/dateSeparator configuration element.
v Default value—1
v Dynamic—false

/IBM/CoreUtilities/DateValidation/dateSeparator
v Description—Specifies the separator used to separate the year, month, and day
in a date format. The separator can be one of the following characters:
– – /
– .
v Default value—A hyphen (-)
v Dynamic—false

/IBM/CoreUtilities/EventManager/busiEntities
v Description—Specifies the business entities that Event Manager monitors. This
value corresponds to a list of comma delimited GROUP_NAME values in the
V_GROUP table. By default, it is empty.
v Default value—A blank (that is, a blank value).
v Dynamic—false

422

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/CoreUtilities/EventManager/businessSystemId
v Description—Specifies the system that Event Manager monitors. This value
corresponds to a DWL_PROD_TP_CD value in the CDDWLPRODUCTTP table.
v Default value—1
v Dynamic—false

/IBM/CoreUtilities/EventManager/EventCategoryForBusiEntities
v Description—Species the event categories for the business entities that Event
Manager monitors. This value corresponds to a list of comma delimited
EVENT_CAT_CD values in the CDEVENTCAT table. By default, it is empty.
v Default value—A blank (that is, a blank value).
v Dynamic—false

/IBM/CoreUtilities/KeyGeneration/instancePKIdentifier
v Description—Specifies a numeric value that can be appended to each generated
ID. This provides a way to generate IDs for database clustering and replication.
To enable this feature, each instance of this configuration element should have a
unique numeric value.
v Default value—A blank (that is, a blank value).
v Dynamic—false

/IBM/CoreUtilities/Response/OrderSort/enabled
This configuration element is not supported.

/IBM/CoreUtilities/SynchronizeTransactionTime/enabled
v Description—Determines whether all sub-transactions in a transaction use the
same transaction time. This configuration element only applies to entity beans.
v Default value—false
v Dynamic—false

/IBM/DWLAdminServices/InternalValidation/enabled
v Description—Determines whether or not internal date values in
DWLAdminService requests are validated.
v Default value—true
v Dynamic—false

/IBM/DWLAdminServices/Response/dtd
v Description—Specifies the schema against which DWLAdminService responses
are validated.
v Default value—DWLAdminResponse.xsd
v Dynamic—false

Chapter 34. Using the Configuration and Management components

423

Licensed Materials – Property of IBM

/IBM/DWLAdminServices/Response/xsd
v Description—Specifies the schema against which DWLAdminService responses
are validated.
v Default value—DWLAdminResponse.xsd
v Dynamic—false

/IBM/DWLBusinessServices/Category/Search/maxResults
v Description—Specifies the maximum number of records returned from a
searchCategory and searchCategoryHierarchy transaction.
v Default value—100
v Dynamic—true

/IBM/DWLBusinessServices/Task/priorityCatType
v Description—Specifies the type code indicating the priority category type that is
used in Task Management. This value should be one of the
PRIORITY_CAT_TP_CD values in the CDPRIORITYTP table.
v Default value—1
v Dynamic—true

/IBM/DWLBusinessServices/Task/Search/maxResults
v Description—Specifies the maximum number of records returned from a
searchTask transaction.
v Default value—100
v Dynamic—true

/IBM/DWLBusinessServices/Task/Search/sortOrder
v Description—Specifies a comma delimited string listing the attributes in the
TaskSearchResultBObj object, in the order in which the TaskSearchResultBObj
records are returned in a searchTask transaction.
v Default value—DueDate, Priority, CreationDate
v Dynamic—true

/IBM/DWLBusinessServices/WorkbasketEntity/Search/maxResults
v Description—Specifies the maximum number of WorkbasketEntityBObj records
in each TaskBObj object that is returned as part of each TaskSearchResultBObj
record in a searchTask transaction.
v Default value—100
v Dynamic—true

/IBM/DWLCommonServices/AccessToken/AccessTokenAccessor/
className
v Description—Specifies the class used to retrieve the collection of access tokens
associated with users and groups. The class must implement the
com.dwl.base.accessToken.AccessTokenAccessor interface.
v Default value—com.dwl.base.accessToken.DefaultAccessTokenAccessor
v Dynamic—true

424

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/BaseTableExtension/
updateCheckIgnoreList
v Description—Specifies a comma delimited string of fully-qualified entity object
names that ignore the last update date check. If you add an entity object name
in this configuration element, that entity object can be updated even if the last
update date of the entity object does not match the last update date of the
record in the database.
This configuration element is useful if you use base table extensions, and you
use an entity bean to update an entity object in which the extended entity object
does not have logic to handle the last update date being modified by the base
object.
v Default value—A blank (that is a blank value)
v Dynamic—true

/IBM/DWLCommonServices/ConcurrentExecution/
defaultWaitTimeout
v Description—Specifies the time, in milliseconds, that a concurrent execution
waits until all work items are completed. Set a value to avoid waiting
indefinitely in case of an issue such as a deadlock.
v Default value—3600000
v Dynamic—false

/IBM/DWLCommonServices/ConcurrentExecution/enabled
v Description—Determines whether concurrent execution infrastructure is
enabled. The product provides several several components that can be executed
concurrently when this configuration element is enabled. Examples of these
components are as follows:
– Searching for party addresses under a parent object
– Searching for party identification under a parent object
– Transactions that are supported by the federated deployment framework
v Default value—false
v Dynamic—false

/IBM/DWLCommonServices/ConcurrentExecution/Cache/
purgeFrequency
v Description—Specifies the time interval, in milliseconds, between two
consecutive cache purges.
v Default value—604800000
v Dynamic—false

/IBM/DWLCommonServices/ConcurrentExecution/Cache/
timeToLive
v Description—Specifies the time, in milliseconds, after which a cached work item
is removed from the cache.
v Default value—604800000
v Dynamic—false

/IBM/DWLCommonServices/DataBase/OS
v Description—Specifies the operating system of the database server.
v Default value—This value is set upon installation of the operating system.
Chapter 34. Using the Configuration and Management components

425

Licensed Materials – Property of IBM

v Dynamic—false

/IBM/DWLCommonServices/DataBase/type
v Description—Specifies the supported database product name. Supported
databases are DB2 and Oracle.
v Default value—This value is set upon installation of the database.
v Dynamic—false

/IBM/DWLCommonServices/DataBase/
TimeStampPrecisionIndicator/enabled
v Description—Determines whether the nanosecond part of a timestamp is set to
0 to match the database timestamp precision.
v Default value—false
v Dynamic—false

/IBM/DWLCommonServices/DateValidation/dateFormat
v Description—Specifies the format with which to represent a date in a date field.
A date field contains the year (YYYY), month (MM) and day (DD), which can be
represented in one of the following formats:
– 1 = YYYY-MM-DD
– 4 = YYYY-DD-MM
– 13 = MM-DD-YYYY
– 16 = DD-MM-YYYY
The separator between the year, month, and date is defined in the
/IBM/DWLCommonServices/DateValidation/dateSeparator configuration
element.
v Default value—1
v Dynamic—false

/IBM/DWLCommonServices/DateValidation/dateSeparator
v Description—Specifies the separator used to separate the year, month, and day
in a date format. The separator can be one of the following characters:
– – /
– .
v Default value—A hyphen (-)
v Dynamic—false

/IBM/DWLCommonServices/EntitySpecUse/SpecCascadeType
v Description—Specifies the spec cascade type code value used in
EntitySpecUseBObj to indicate whether the EntitySpecUseBObj can be inherited
by the descendents of the category. It is used in recursive SQL scripts to return
the EntitySpecUseBObj objects from ancestors.
v Default value—1
v Dynamic—false

/IBM/DWLCommonServices/EntitySpecUse/CategoryHierarchy/
RecursiveSQL/Limit
v Description—Specifies the recursion limit used in recursive SQL scripts. Some
database provider allows recursive SQL scripts to execute infinitely. This value

426

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

provides the maximum number of recursion that a recursive SQL is allowed to
execute. If an SQL recurs above this value, an exception is thrown.
For example, recursive SQL scripts are used to retrieve EntitySpecUseBObj
objects inherited from ancestor category nodes.
v Default value—20
v Dynamic—false

/IBM/DWLCommonServices/ExtensionFramework/enabled
v Description—Determines whether the extension framework is enabled.
v Default value—true
v Dynamic—true

/IBM/DWLCommonServices/ExternalRule/Ilog/AutoReload/
enabled
v Description—Determines whether the rule set manager is aware of any ILR
modification at runtime and consequently reloads and re-parses the ILR files.
v Default value—true
v Dynamic—false

/IBM/DWLCommonServices/ExternalRule/Ilog/IncludeAllJars/
enabled
v Description—Determines whether the jrulesall.jar is available at runtime.
v Default value—true
v Dynamic—false

/IBM/DWLCommonServices/FastTrack/constructor
v Description—Specifies the value corresponding to the Constructor value of the
context argument for the DWLServiceController class.
v Default value—TCRMService
v Dynamic—false

/IBM/DWLCommonServices/FastTrack/targetApplication
v Description—Specifies the value corresponding to the TargetApplication value
of the context argument for the DWLServiceController class.
v Default value—tcrm
v Dynamic—false

/IBM/DWLCommonServices/FastTrack/Request/encoding
v Description—Specifies the encoding of the request message. Before sending
String request as byte stream, MDM Query Connect converts the String to bytes
using this encoding.
v Default value—UTF-16BE
v Dynamic—false

/IBM/DWLCommonServices/FastTrack/Response/encoding
v Description—Specifies the encoding of the response message.
v Default value—UTF-16BE
v Dynamic—false

Chapter 34. Using the Configuration and Management components

427

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/FastTrack/Response/
maxMessageChunk
v Description—Specifies the maximum size of the response message in bytes. The
recommended value for CICS® is 24576. The theoretical upper limit is 32K. To be
safe, this value should not exceed 24KB.
The recommended value for MQ is 4000000.
v Default value—500000
v Dynamic—false

/IBM/DWLCommonServices/FastTrack/Response/type
v Description—Specifies the value corresponding to the ResponseType value of
the context argument for the DWLServiceController class.
v Default value—standard
v Dynamic—false

/IBM/DWLCommonServices/FastTrack/Response/Size/enabled
v Description—Determines whether the response is split into smaller chunks of
data. Each chunk of data has a 12 character header containing the following
information:
– First character is an end of message indicator. If it is N, more message chunks
will follow; if it is Y, it is the last chunk.
– Next three characters contain the chunk order number (for example, 001)
– Next eight characters contain the message size in bytes (for example, 00005000
if the message size is 5000 bytes).
v Default value—true
v Dynamic—false

/IBM/DWLCommonServices/FastTrack/SetJmsMessageId/enabled
v Description—Determines whether the response message ID is set to the value of
request message ID.
v Default value—true
v Dynamic—false

/IBM/DWLCommonServices/IDGeneration/AlphaIDGenerator/
className
v Description—Specifies the class of an ID generator that generates an alpha ID.
v Default value—com.dwl.base.util.AlphaIDGenerator
v Dynamic—true

/IBM/DWLCommonServices/IDGeneration/
AlphaNumericIDGenerator/className
v Description—Specifies the class of an ID generator that generates an
alphanumeric ID.
v Default value—com.dwl.base.util.AlphaNumericIDGenerator
v Dynamic—true

/IBM/DWLCommonServices/IDGeneration/NumericIDGenerator/
className
v Description—Specifies the class of an ID generator that generates a numeric ID.
v Default value—com.dwl.base.util.NumericIDGenerator

428

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Dynamic—true

/IBM/DWLCommonServices/IDGeneration/
NumericStringIDGenerator/className
v Description—Specifies the class of an ID generator that generates a numeric
string ID.
v Default value—com.dwl.base.util.NumericStringIDGenerator
v Dynamic—true

/IBM/DWLCommonServices/InternalValidation/enabled
v Description—Determines whether internal validation is enabled.
v Default value—true
v Dynamic—true

/IBM/DWLCommonServices/Jndi/contextFactory
v Description—Specifies the JNDI context factory class. If this value is not
specified, the JNDI context factory class provided by the application server is
used.
v Default value—A blank (that is, a blank value).
v Dynamic—false

/IBM/DWLCommonServices/KeyGeneration/instancePKIdentifier
v Description—Specifies a numeric value that can be appended to each generated
ID. This provides a way to generate IDs for the purpose of database clustering
and replication. To enable this, each instance of this configuration element
should have a unique numeric value.
v Default value—A blank (that is, a blank value).
v Dynamic—false

/IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/
base
v Description—Specifies the base object at which to start the search. This
configuration element only applies if the value of the /IBM/
DWLCommonServices/Security/
transaction_authorization_provider_class_name_1 configuration element is
com.dwl.base.security.provider.LdapTransactionAuthorizationProvider.
v Default value—Airius.com
v Dynamic—false

/IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/
jndiFactoryClass
v Description—Specifies the JNDI factory class to look up the LDAP server. This
configuration element only applies if the value of the /IBM/
DWLCommonServices/Security/
transaction_authorization_provider_class_name_1 configuration element is
com.dwl.base.security.provider.LdapTransactionAuthorizationProvider.
v Default value—com.sun.jndi.ldap.LdapCtxFactory
v Dynamic—false

Chapter 34. Using the Configuration and Management components

429

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/
jndiProviderUrl
v Description—Specifies the URL pointing to the LDAP server. This configuration
element only applies if the value of the /IBM/DWLCommonServices/Security/
transaction_authorization_provider_class_name_1 configuration element is
com.dwl.base.security.provider.LdapTransactionAuthorizationProvider.
v Default value—ldap://localhost
v Dynamic—false

/IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/
Filter/group
v Description—Specifies the search filter to apply to an LDAP server to search for
transactions authorized for the group (user role). This configuration element
only applies if the value of the /IBM/DWLCommonServices/Security/
transaction_authorization_provider_class_name_1 configuration element is
com.dwl.base.security.provider.LdapTransactionAuthorizationProvider.
v Default value—(&(objectClass=groupofuniquenames)(cn=
%t)(uniquemember=cn=%g,*))
v Dynamic—false

/IBM/DWLCommonServices/LdapSecurityProvider/LdapSearch/
Filter/user
v Description—Specifies the search filter to apply to an LDAP server to search for
transactions authorized for the user. This configuration element only applies if
the value of the /IBM/DWLCommonServices/Security/
transaction_authorization_provider_class_name_1 configuration element is
com.dwl.base.security.provider.LdapTransactionAuthorizationProvider.
v Default value—(&(objectClass=groupofuniquenames)(cn=
%t)(uniquemember=uid=%u,*))
v Dynamic—false

/IBM/DWLCommonServices/Locale/languageId
v Description—Specifies the default language ID for the application. This
language ID is used to look up code table values.
v Default value—100
v Dynamic—false

/IBM/DWLCommonServices/Logging/configurationOverride
v Description—Overrides the logging level and logging file at the application
level.
For example, to override these values if you use Log4J.properties, specify:
log4j.appender.file.File=/MDM.log\nlog4j.logger.com=WARN, file
Likewise, to override these values if you use JDKLog.properties, specify
java.util.logging.FileHandler.pattern=$a_valid_path/MDM.log\
ncom.level=WARNING, file
v Default value—A blank (that is, a blank value).
v Dynamic—true

430

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/MultiTimeZoneDeployment/
defaultTimeZone
v Description—Specifies the default time zone to use to convert date values from
common time zone (UTC) format if no requesterTimeZone is specified in a
request.
v Default value—A blank (that is, a blank value).
v Dynamic—false

/IBM/DWLCommonServices/MultiTimeZoneDeployment/enabled
v Description—Determines whether multi-timezone deployment is enabled. When
multi-timezone deployment is enabled, date values will be stored in the database
using common time zone (UTC) format.
v Default value—false
v Dynamic—false

/IBM/DWLCommonServices/NLS/system_Default_Data_Locale
v Description—Specifies the default locale used for spec values NLS objects.
v Default value—en
v Dynamic—false

/IBM/DWLCommonServices/Notifications/defaultLanguage
v Description—Specifies the language ID used in notification. For example, this
language ID is used to look up code table values in a particular language if code
tables are used in the notification message. The language ID corresponds to the
LANG_TP_CD value in the CDLANGTP table.
v Default value—100
v Dynamic—true

/IBM/DWLCommonServices/Notifications/enabled
v Description—Determines whether notification is enabled at the application level.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/Notifications/ExplicitCommit/enabled
v Description—Controls how notifications are sent to multiple topics in a
single-phase commit (XA disabled) and two-phase commit (XA enabled). If the
transaction is XA enabled, set this value to false. If the transaction is XA
disabled, set this value to true so that a notification can be sent to more than one
topic.
v Default value—false
v Dynamic—false

/IBM/DWLCommonServices/Notifications/
NotificationManagerThrowException/enabled
v Description—Determines whether the Notification component throws exceptions
if errors occur upon initializing the component. Typically, such errors occur if the
notification metadata is not configured correctly.
v Default value—false
v Dynamic—false

Chapter 34. Using the Configuration and Management components

431

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/PerformanceTracking/enabled
v Description—Determines whether performance tracking is enabled.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/level
v Description—Specifies the level of performance statistics to track.
v Default value—0
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ARM40TransactionFactory/className
v Description—Specifies the class used to enable ARM 4.0 performance tracking
on the application. The class must implement the
org.opengroup.arm40.transaction.ArmTransactionFactory interface. If this value
is set to None, the performance tracking will use the logging component and the
performance statistics will be logged to a file.
v Default value—None
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ComponentLayer/enabled
v Description—Determines whether performance tracking is enabled at the
component level.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ComponentLayerExtension/enabled
v Description—Determines whether performance tracking is enabled at the
component level extension.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ComponentLayerPrePost/enabled
v Description—Determines whether performance tracking is enabled at the
component level pre or post processing.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ControllerLayer/enabled
v Description—Determines whether performance tracking is enabled at the
controller level.
v Default value—false
v Dynamic—true

432

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/PerformanceTracking/
ControllerLayerExtension/enabled
v Description—Determines whether performance tracking is enabled at the
controller level extension.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ControllerLayerPrePost/enabled
v Description—Determines whether performance tracking is enabled at the
controller level pre/post processing.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
DatabaseDetails/enabled
v Description—Determines whether performance tracking is enabled at the
database connection level.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
DatabaseQuery/enabled
v Description—Determines whether performance tracking is enabled at the
database query.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/ExecuteTx/
enabled
v Description—Determines whether performance tracking is enabled at the
business proxy.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ExternalBusinessRules/enabled
v Description—Determines whether performance tracking is enabled at the
external business rule component.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ExternalValidation/enabled
v Description—Determines whether performance tracking is enabled at the
external validation component.
v Default value—false
v Dynamic—true

Chapter 34. Using the Configuration and Management components

433

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/PerformanceTracking/
InternalValidation/enabled
v Description—Determines whether performance tracking is enabled at the
internal validation component.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/Notification/
enabled
v Description—Determines whether performance tracking is enabled at the
notification component.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/PartyMatcher/
enabled
v Description—Determines whether performance tracking is enabled at the party
matching component.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
RequestHandler/enabled
v Description—Determines whether performance tracking is enabled at the
request handler.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/RequestParser/
enabled
v Description—Determines whether performance tracking is enabled at the
request parser.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ResponseConstructor/enabled
v Description—Determines whether performance tracking is enabled at the
response constructor.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
SecurityAuthorization/enabled
v Description—Determines whether performance tracking is enabled at the
security authorization component.
v Default value—false
v Dynamic—true

434

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/PerformanceTracking/
Standardization/enabled
v Description—Determines whether performance tracking is enabled at the
standardization component.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
SuspectProcessing/enabled
v Description—Determines whether performance tracking is enabled at the
suspect processing.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
ThirdPartyExtension/enabled
v Description—Determines whether performance tracking is enabled at the third
party extension.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PerformanceTracking/
TransactionManager/enabled
v Description—Determines whether performance tracking is enabled at the
business transaction manager.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/PhoneticSearch/extensionElementId
v Description—Specifies the extensionElementId parameter used by the
PhoneticKeyManager class to obtain specified PhoneticKeyGenerator
implementation.
v Default value—SoundexExtension
v Dynamic—true

/IBM/DWLCommonServices/PhoneticSearch/extensionId
v Description—Specifies the extensionId parameter used by the
PhoneticKeyManager class to get specified PhoneticKeyGenerator
implementation.
v Default value—com.ibm.imc.phonetics.PhoneticKeyProviders
v Dynamic—true

/IBM/DWLCommonServices/RedundantUpdate/enabled
v Description—Determines whether allowing redundant update is enabled. If this
value is set to false, redundant update is not allowed. If the business object to
be updated contains the same values as the values on the system, an error
message is thrown.
If this value is true, redundant update is allowed. If the business object to be
updated contains the same values as the values on the system, the values are
updated on the system.
v Default value—false
Chapter 34. Using the Configuration and Management components

435

Licensed Materials – Property of IBM

v Dynamic—true

/IBM/DWLCommonServices/Report/Broadcaster/enabled
v Description—Determines whether service activity monitoring is enabled. If it is
enabled, JMX notification is issued for each transaction.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/Report/Listener/enabled
v Description—Determines whether transaction activity data is logged in a log
file. This configuration element is applicable only if service activity monitoring is
enabled.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/Response/UseMetadataOrder/enabled
This configuration element is not supported.

/IBM/DWLCommonServices/Runtime/application
v Description—Specifies the run time of the InfoSphere MDM Server instance.
Possible values are WCC and FastTrack.
v Default value—WCC
v Dynamic—false

/IBM/DWLCommonServices/Search/caseSensitive
v Description—Determines whether searches are case sensitive. When searches are
not case sensitive, additional table columns and indexes will be used to store
case insensitive values.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/Security/enabled
v Description—Determines whether security is enabled.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/Security/
number_of_transaction_authorization_providers
v Description—Specifies the number of transaction authorization providers.
v Default value—1
v Dynamic—true

/IBM/DWLCommonServices/Security/SAML/
SAML_userRoles_Attribute_AttributeName
v Description—Specifies the element in the SAML input indicating the userRoles
attribute name.
v Default value—urn:wcc:dir:attribute-def:userRoles
v Dynamic—true

436

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/Security/SAML/
SAML_userRoles_Attribute_AttributeNamespace
v Description—Specifies the element in the SAML input indicating the userRoles
attribute namespace.
v Default value—urn:wcc:attributeNamespace:uri
v Dynamic—true

/IBM/DWLCommonServices/Security/SAML/security_data_parser
v Description—Specifies the class of a customized authentication assertions parser.
The assertions must be passed as the element of the DWLContol
group within a request. The class must implement the
com.dwl.base.ISecurityDataParser interface.
v Default value—com.dwl.base.SAML11Parser
v Dynamic—true

/IBM/DWLCommonServices/Security/SAML/
SAML_XML_Validation/enabled
v Description—Determines whether the SAML XML is validated.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/Security/
transaction_authorization_provider_class_name_1
v Description—Specifies the class of the transaction authorization provider. The
class must implement the com.dwl.base.security.AuthorizationProvider interface.
v Default
value—com.dwl.base.security.provider.DefaultTransactionAuthorizationProvider
v Dynamic—true

/IBM/DWLCommonServices/SpecValueSearch/DefaultStatus
v Description—Spcecifies the initial index status of searchable spec attribute.
v Default value—1
v Dynamic—true

/IBM/DWLCommonServices/SpecValueSearch/IndexTable/
MaintainValues/enabled
v Description—Determines whether index value maintenance is enabled.
v Default value—true
v Dynamic—true

/IBM/DWLCommonServices/SpecValueSearch/IndexTable/
ScheduleSpecValueIndexProcess/ImpactedSpecValueSize/
medium
v Description—Determines spec value indexing strategy based on impacted spec
value size.
v Default value—10000
v Dynamic—true

Chapter 34. Using the Configuration and Management components

437

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/SpecValueSearch/IndexTable/
ScheduleSpecValueIndexProcess/ImpactedSpecValueSize/small
v Description—Determines spec value indexing strategy based on impacted spec
value size.
v Default value—500
v Dynamic—true

/IBM/DWLCommonServices/SpecValueSearch/
MaxDecimalFractionDigitsSize
v Description—Specifies the scaled value size of the DECIMAL_VALUE column in
the PRODUCTVALINDEX table. If the scaled value size of a searchable attribute
of decimal data type is greater than that of the column, the value will not to be
stored in system.
v Default value—19
v Dynamic—true

/IBM/DWLCommonServices/SpecValueSearch/
MaxDecimalTotalDigitsSize
v Description—Specifies the non-scaled value size of the DECIMAL_VALUE
column in the PRODUCTVALINDEX table. If the non-scaled value size of a
searchable attribute of decimal data type is greater than that of the column, the
value will not to be stored in system.
v Default value—31
v Dynamic—true

/IBM/DWLCommonServices/SpecValueSearch/
MaxLongTotalDigitsSize
v Description—Specifies the scaled value size of the LONG_VALUE column in the
PRODUCTVALINDEX table. If the scaled value size of a searchable attribute of
long data type is greater than that of the column, the searchable attribute value
will not to be stored in system.
v Default value—19
v Dynamic—true

/IBM/DWLCommonServices/SpecValueSearch/MaxStringValueSize
v Description—Specifies the size of the STRING_VALUE column in the
PRODUCTVALINDEX table. If the size of a searchable attribute of string data
type is greater than that of the column, the searchable attribute value will be
truncated to be stored in system.
v Default value—255
v Dynamic—true

/IBM/DWLCommonServices/SpecValueSearch/Recursive/enabled
v Description—Determines whether recursive SQL is used internally to search for
spec values.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/Standardization/enabled
v Description—Determines whether standardization is enabled.
v Default value—false

438

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Dynamic—true

/IBM/DWLCommonServices/Standardization/
StandardizationManager/className
v Description—Specifies the fully qualified name of the standardization manager
class. This class gets the standardizers from the metadata based on business
objects passed in and invokes the corresponding standardizers.
v Default
value—com.ibm.mdm.common.standardization.DefaultStandardizationManager
v Dynamic—true

/IBM/DWLCommonServices/SynchronizeTransactionTime/enabled
v Description—Determines whether the timestamps of the transaction and all its
sub-transactions are synchronized.
v Default value—false
v Dynamic—false

/IBM/DWLCommonServices/TAIL/enabled
v Description—Determines whether TAIL is enabled.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/TAIL/maxRecords
v Description—Specifies the maximum number of records returned from a
getTAIL transaction.
v Default value—100
v Dynamic—true

/IBM/DWLCommonServices/TAIL/Asynchronous/enabled
v Description—Determines whether TAIL is logged asynchronously from the
transaction context of an InfoSphere MDM Server transaction.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/TAIL/
LogNegativeCompositeTransaction/enabled
v Description—Determines whether TAIL is logged for negative transactions.
v Default value—false
v Dynamic—true

/IBM/DWLCommonServices/TAIL/RedundantUpdate/enabled
v Description—Determines whether TAIL is logged for update transactions that
contain redundant update data.
v Default value—false
v Dynamic—true

Chapter 34. Using the Configuration and Management components

439

Licensed Materials – Property of IBM

/IBM/DWLCommonServices/UserManagement/
user_management_provider_class_name
v Description—Specifies the class of user management provider used. The class
must implement the com.ibm.mdm.usermanagement.AuthorizationProvider
interface.
v Default
value—com.ibm.mdm.usermanagement.DefaultUserManagementProvider
v Dynamic—false

/IBM/DWLCommonServices/Validation/BusinessKeyValidation/
ExcludeList/groupNames
v Description—Specifies acomma delimited string listing the group names for
which validation using the business key validator class is disabled.
v Default value—ContractRoleLocationPrivPref, Address, ContactMethod,
FinancialProfile, IncomeSource, OrganizationName, PartyAddressPrivPref,
PartyContactMethodPrivPref, PartyLobRelationship, PartyLocationPrivPref,
PartyPrivPref, PartyAddressPrivPref, PartyContactMethodPrivPref,
AccessDateValue, AdminContEquiv, EntityInstancePrivPref,
ProductSpecValueBObj
v Dynamic—true

/IBM/DWLCommonServices/Validation/BusinessKeyValidation/
Validator/className
v Description—The fully qualified name of the generic business key validator
class.
v Default value—com.ibm.mdm.common.validator.MDMBusinessKeyValidator
v Dynamic—false

/IBM/DWLCommonServices/Validation/External/enabled
v Description—Determines whether external validation is enabled.
v Default value—true
v Dynamic—true

/IBM/DWLCommonServices/XML/Character_only_tags
v Description—Specifies a comma delimited string indicating the XML elements
whose values are enclosed by a CDATA XML element in an XML response.
v Default value—authData
v Dynamic—true

/IBM/DWLCommonServices/XML/useValidatingParser
v Description—Determines whether XML request is validated against its
corresponding XML schema.
v Default value—true
v Dynamic—true

/IBM/DWLCommonServices/XmlRequestParse/UseGrammaPool/
enabled
v Description—Determines whether grammar-pooling is enabled for the XML
request parser.
v Default value—true
v Dynamic—false

440

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/EventManager/Integration/WebSphereMQ/MQEnvironment/
channel
v Description—Specifies the channel used for connection to the WebSphere MQ
queue manager.
This configuration element only applies if you use the
com.dwl.commoncomponents.eventmanager.integration.MQQueueExplorer class
for the /IBM/EventManager/QueueExplorer/className configuration element.
This configuration element should match the queue manager channel as defined
on the application server.
v Default value—yourMQChannel
v Dynamic—true

/IBM/EventManager/Integration/WebSphereMQ/MQEnvironment/
hostName
v Description—Specifies the host name on which the WebSphere MQ queue
manager.
This configuration element only applies if you use the
com.dwl.commoncomponents.eventmanager.integration.MQQueueExplorer class
for the /IBM/EventManager/QueueExplorer/className configuration element.
This configuration element should match the queue manager host name as
defined on the application server.
v Default value—yourMQHostName
v Dynamic—true

/IBM/EventManager/Integration/WebSphereMQ/MQEnvironment/
port
v Description—Specifies the TCP/IP port number used for connection to the
WebSphere MQ queue manager.
This configuration element only applies if you use the
com.dwl.commoncomponents.eventmanager.integration.MQQueueExplorer class
for the /IBM/EventManager/QueueExplorer/className configuration element.
This configuration element should match the queue manager TCP/IP port as
defined on the application server.
v Default value—yourMQListeningPort
v Dynamic—true

/IBM/EventManager/Integration/WebSphereMQ/MQQueue/name
v Description—Specifies the name of the WebSphere MQ queue.
This configuration element only applies if you use the
com.dwl.commoncomponents.eventmanager.integration.MQQueueExplorer class
for the /IBM/EventManager/QueueExplorer/className configuration element.
This configuration element should match the queue name as defined on the
application server.
v Default value—yourMQQueueName
v Dynamic—true

/IBM/EventManager/Integration/WebSphereMQ/MQQueueManager/
name
v Description—Specifies the name of the WebSphere MQ queue manager.
This configuration element only applies if you use the
com.dwl.commoncomponents.eventmanager.integration.MQQueueExplorer class
Chapter 34. Using the Configuration and Management components

441

Licensed Materials – Property of IBM

for the /IBM/EventManager/QueueExplorer/className configuration element.
This configuration element should match the queue manager name as defined
on the application server.
v Default value—yourMQQueueManagerName
v Dynamic—true

/IBM/EventManager/MemoryCache/timeToLive
v Description—Specifies the time, in milliseconds, for which Event Manager
database configurations are cached. After this time expires, the database
configurations are reloaded. If this value is 0, the configurations are kept in
cache until the server is stopped.
v Default value—200000
v Dynamic—false

/IBM/EventManager/MessageSender/queue
v Description—Specifies the resource environment reference name defined in the
deployment descriptor corresponding to the queue used by Event Manager.
v Default value—jms/EMQueue
v Dynamic—false

/IBM/EventManager/MessageSender/queueConnectionFactory
v Description—Specifies the resource reference name defined in the deployment
descriptor corresponding to the queue connection factory used by Event
Manager.
v Default value—jms/EMQCF
v Dynamic—false

/IBM/EventManager/MessagesInQueue/max
v Description—Specifies the maximum number of PROCESSACTION records to
select to create tasks per cycle in time-based event detection. The configuration
element only applies if you use the
com.dwl.commoncomponents.eventmanager.client.ProcessControllerProxy class
to start time-based event detection.
v Default value—500
v Dynamic—false

/IBM/EventManager/Notification/topic
v Description—Specifies the resource environment reference name defined in the
deployment descriptor corresponding to the topic to which Event Manager
notifications are posted. If you want to route notifications to another topic, you
can set the new topic name in this configuration element, add the new resource
environment reference name in the deployment descriptor, and configure the
new topic in the InfoSphere MDM Server notification data model.
v Default value—jms/EMTopic
v Dynamic—false

/IBM/EventManager/ProcessTime/max
v Description—Specifies the maximum processing time, in milliseconds, that a
task can stay in progress. Event Manager uses this time to retry a task that has
been in progress for too long. Event Manager creates tasks using the following
criteria:

442

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

– It tries to select PROCESSACTION records that have the EVENT_STATUS
with a value of 3 and changes the value to 2, marking them in progress. It
then creates tasks based on these records.
– If no PROCESSACTION records with a status of 3 exist, it tries to select
records that have a value of 2 only if their LAST_UPDATE_DT value is earlier
than the current time minus the maximum processing time. In this case, Event
Manager retries these tasks that were previously marked as in progress but
did not finish processing.
v Default value—3600000
v Dynamic—false

/IBM/EventManager/QueueExplorer/className
v Description—Specifies the class used to query the queue used by Event
Manager. This class must implement the
com.dwl.commoncomponents.eventmanager.IQueueExplorer interface.
In time-based event detection that is started the
com.dwl.commoncomponents.eventmanager.client.EventDetectionScheduleController
class, the class in this configuration element queries the depth of the queue in
order to estimate a desirable number of tasks to put on the queue per cycle in
the event detection.
Two implementation classes are provided:
– com.dwl.commoncomponents.eventmanager.DefaultQueueExplorer
– com.dwl.commoncomponents.eventmanager.integration.MQQueueExplorer
The DefaultQueueExplorer class used JMS API to implement the interface. The
MQQueueExplorer class uses WebSphere MQ API to implement the interface.
v Default
value—com.dwl.commoncomponents.eventmanager.DefaultQueueExplorer
v Dynamic—true

/IBM/FinancialServices/Contract/Search/maxResults
v Description—Specifies the maximum number of records returned from a
searchContract transaction.
v Default value—100
v Dynamic—true

/IBM/FinancialServices/Contract/ContractPartyRole/
partyInquiryLevel
v Description—Specifies the party inquiry level used in the addContractPartyRole
and updateContractPartyRole transactions. The inquiry level determines whether
the TCRMPartyBObj object will be returned in these transactions, and what
kinds of children objects will be returned under the TCRMPartyBObj object.
v Default value—4
v Dynamic—true

/IBM/FinancialServices/ExtendedAdminContractIdSearch/enabled
v Description—Determines whether the AdminContractIdFieldType and
AdminContractId attributes in a TCRMPartialSysAdminKeyBObj object provided
in a searchContract transaction are taken in account as search criteria. When this
configuration element is set to true, and a TCRMPartialSysAdminKeyBObj
object is included in the TCRMContractSearchBObj object in the request, the

Chapter 34. Using the Configuration and Management components

443

Licensed Materials – Property of IBM

AdminContractIdFieldType and AdminContractId attributes provided in the
TCRMPartialSysAdminKeyBObj are used to search for any matched records in
the NATIVEKEY table.
v Default value—false
v Dynamic—false

/IBM/MessagingAdapter/Exeption/xmlTagName
v Description—Specifies the element tag to use to wrap an exception message in
order to ensure a well-formed XML.
v Default value—DWLMessagingAdapterException
v Dynamic—false

/IBM/MessagingAdapter/Exeption/CommitOnSendFail/enabled
v Description—Determines whether the transaction is committed if the response
fails to be sent to the response queue.
v Default value—true
v Dynamic—false

/IBM/MessagingAdapter/Exeption/JmsMsgToOutboundQueue/
enabled
v Description—Determines whether exceptions raised by the application are sent
to the outbound queue as JMS TextMessage.
v Default value—false
v Dynamic—false

/IBM/MessagingAdapter/Exeption/NonXmlToOutboundQueue/
enabled
v Description—Determines if any exceptions are sent to the outbound queue as
JMS TextMessage. To ensure the exception is formatted as a well-formed XML,
the exception message is wrapped in an element tag specified by the
/IBM/MessagingAdapter/Exeption/xmlTagName configuration element.
v Default value—false
v Dynamic—false

/IBM/MessagingAdapter/JMSQueue/activeQueueGroup
v Description—Specifies a group of outbound queues. This configuration element
is not currently supported.
v Default value—DWLCustomerQueue1
v Dynamic—false

/IBM/MessagingAdapter/JMSQueue/JMSMessageHeaderCopy/
enabled
v Description—Determines whether the JMS Message Header from the inbound
message is copied to the outbound message.
v Default value—true
v Dynamic—true

/IBM/MessagingAdapter/JMSQueue/JMSMessageMsgIdToCorrId/
enabled
v Description—Determines whether the JMS MessageId from the inbound
message is mapped to the JMS CorrelationId of the outbound message.

444

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Default value—false
v Dynamic—false

/IBM/MessagingAdapter/JMSQueue/SendResponseToOUTBOUND/
enabled
v Description—Determines whether the response is sent to an outbound queue.
v Default value—true
v Dynamic—false

/IBM/MessagingAdapter/Request/encoding
v Description—Specifies the encoding to use to encode the request if the JMS
request is a ByteMessage.
v Default value—UTF-16BE
v Dynamic—false

/IBM/MessagingAdapter/RequestHeader/constructor
v Description—Specifies the value corresponding to the Constructor value of the
context argument for the DWLServiceController class.
v Default value—TCRMService
v Dynamic—false

/IBM/MessagingAdapter/RequestHeader/operationType
v Description—Specifies the value corresponding to the OperationType value of
the context argument for the DWLServiceController class.
v Default value—All
v Dynamic—false

/IBM/MessagingAdapter/RequestHeader/parser
v Description—Specifies the value corresponding to the Parser value of the
context argument for the DWLServiceController class.
v Default value—TCRMService
v Dynamic—false

/IBM/MessagingAdapter/RequestHeader/requestType
v Description—Specifies the value corresponding to the RequestType value of the
context argument for the DWLServiceController class.
v Default value—standard
v Dynamic—false

/IBM/MessagingAdapter/RequestHeader/responseType
v Description—Specifies the value corresponding to the ResponseType value of
the context argument for the DWLServiceController class
v Default value—standard
v Dynamic—false

/IBM/MessagingAdapter/RequestHeader/targetApplication
v Description—Specifies the value corresponding to the TargetApplication value
of the context argument for the DWLServiceController class.
v Default value—tcrm
v Dynamic—false
Chapter 34. Using the Configuration and Management components

445

Licensed Materials – Property of IBM

/IBM/MessagingAdapter/Response/encoding
v Description—Specifies the encoding to use to encode the response if the JMS
response is a ByteMessage.
v Default value—UTF-16BE
v Dynamic—false

/IBM/Party/AbiliTecLink/addressUsageType1
v Description—Specifies the type code indicating an address that is used to
generate an AbiliTec Address. This value should be one of the
ADDR_USAGE_TP_CD values in the CDADDRUSAGETP table.
v Default value—1
v Dynamic—false

/IBM/Party/AbiliTecLink/IdType
v Description—Specifies the type code indicating an AbiliTecLink ID. This value
should be one of the ID_TP_CD values in the CDIDTP table.
v Default value—11
v Dynamic—false

/IBM/Party/AbiliTecLink/orgNameUsageType1
v Description—Specifies the type code indicating an organization name that is
used to generate an AbiliTec commercial name. This value should be one of the
NAME_USAGE_TP_CD values in the CDNAMEUSAGETP table.
v Default value—1
v Dynamic—false

/IBM/Party/AbiliTecLink/personNameUsageType1
v Description—Specifies the type code indicating a person name that is used to
generate an AbiliTec consumer name. This value should be one of the
NAME_USAGE_TP_CD values in the CDNAMEUSAGETP table.
v Default value—1
v Dynamic—false

/IBM/Party/Acxiom/AbiliTecPersonRequestURL
v Description—Specifies the person link of the Acxiom server.
v Default value—https://idtest.acxiom.com/abilitec-consumer/1.0
v Dynamic—false

/IBM/Party/Acxiom/AbiliTecOrganizationRequestURL
v Description—Specifies the organization link of the Acxiom server.
v Default value—https://idtest.acxiom.com/abilitec-business/1.0
v Dynamic—false

/IBM/Party/Acxiom/AbiliTecRequestURL
v Description—Specifies the URL of the Acxiom server.
v Default value—https://interactivetest.acxiom.com/httpgateway
v Dynamic—false

446

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/Party/Acxiom/abiliTecSupportedCountries
v Description—Specifies the country supported by Acxiom. Currently, only USA is
supported. The configuration element value is the country type code for USA in
the application. This value should be one of the COUNTRY_TP_CD values in
the CDCOUNTRYTP table.
v Default value—185
v Dynamic—false

/IBM/Party/Acxiom/applicationId
v Description—Specifies the Acxiom application ID.
v Default value—test
v Dynamic—false

/IBM/Party/Acxiom/password
v Description—Specifies the Acxiom user password.
v Default value—A blank (that is, a blank value).
v Dynamic—false

/IBM/Party/Acxiom/userId
v Description—Specifies the Acxiom user ID.
v Default value—A blank (that is, a blank value).
v Dynamic—false

/IBM/Party/Acxiom/Return_Derived_Link/enabled
v Description—Determines whether Acxiom returns a derived link when no
maintained link is found.
v Default value—true
v Dynamic—false

/IBM/Party/CollapseMutipleParties/collapsedPartiesNumberLimit
v Description—Used by the default external rule FindAllSuspectMatchRules to
specify the maximum number of A1 matches found. If this value is 0, this rule
returns all A1 matches found.
v Default value—0
v Dynamic—true

/IBM/Party/CollapseMutipleParties/InactiveReasonType/collapse
v Description—Specifies the type code indicating that the party is inactive because
the party was collapsed. This value should be one of the
INACT_REASON_TP_CD values in the CDINACTREASONTP table.
v Default value—2
v Dynamic—false

/IBM/Party/CollapseMutipleParties/InactiveReasonType/split
v Description—Specifies the type code indicating that the party is inactive because
the party was split. This value should be one of the INACT_REASON_TP_CD
values in the CDINACTREASONTP table.
v Default value—4
v Dynamic—false

Chapter 34. Using the Configuration and Management components

447

Licensed Materials – Property of IBM

/IBM/Party/CollapseMutipleParties/PartyLinkReasonType/collapse
v Description—Specifies the type code indicating that the party is linked to
another party because the party was collapsed. This value should be one of the
LINK_REASON_TP_CD values in the CDLINKREASONTP table.
v Default value—1
v Dynamic—false

/IBM/Party/CollapseMutipleParties/PartyLinkReasonType/split
v Description—Specifies the type code indicating that the party is linked to
another party because the party was split. This value should be one of the
LINK_REASON_TP_CD values in the CDLINKREASONTP table.
v Default value—2
v Dynamic—false

/IBM/Party/ContactMethod/PhoneCategoryType
v Description—Specifies the type code indicating the contact method category
type for the party phone number details. This value is used by the phone
number normalization rule and should be one of the CONT_METH_CAT_CD
values in the CDCONTMETHCAT table.
v Default value—1
v Dynamic—false

/IBM/Party/CriticalDataChangeProcessing/enabled
v Description—Determines whether critical data change processing is enabled.
v Default value—false
v Dynamic—true

/IBM/Party/DUNSNumber/ConfidenceCode/Threshold
v Description—Used by the default external rule DnBMatchConfidenceRule to
specify the threshold for the confidence code.
v Default value—7
v Dynamic—true

/IBM/Party/ExcludePartyNameStandardization/enabled
v Description—Determines whether name standardization is excluded.
v Default value—false
v Dynamic—false

/IBM/Party/IdentifierGeneration/Factory/className
v Description—Specifies the factory class name of the ID generator.
v Default value—com.dwl.tcrm.utilities.MDMPartyIdentifierFactory
v Dynamic—true

/IBM/Party/IdentifierGeneration/Validation/enabled
v Description—Determines whether generated IDs require validation.
v Default value—false
v Dynamic—false

448

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/Party/IdentifierGeneration/Validator/className
v Description—Specifies the class to validate generated IDs.
v Default value—com.dwl.tcrm.utilities.MDMPartyIdentifierValidator
v Dynamic—true

/IBM/Party/InternalValidation/lastUpdateUserType
v Description—If this configuration element value is userpartyid, the system treats
the requesterName value in the DWLControl object as a party ID and validates
that the party ID exists.
v Default value—userid
v Dynamic—false

/IBM/Party/LocationNormalization/enabled
v Description—Determines whether location normalization is enabled. For
example, address line 1 is normalized into street number, street name, and street
type.
v Default value—false
v Dynamic—false

/IBM/Party/PartyMatch/PartyIdentification/organizationTax
v Description—Specifies the type code indicating an organization’s corporate tax
identification number. This value should be one of the ID_TP_CD values in the
CDIDTP table.
v Default value—2
v Dynamic—false

/IBM/Party/PartyMatch/PartyIdentification/personSin
v Description—Specifies the type code indicating a person’s social insurance
number (SIN). This value should be one of the ID_TP_CD values in the CDIDTP
table.
v Default value—10
v Dynamic—false

/IBM/Party/PartyMatch/PartyIdentification/personTax
v Description—Specifies the type code indicating a person’s social security
number (SSN). This value should be one of the ID_TP_CD values in the CDIDTP
table.
v Default value—1
v Dynamic—false

/IBM/Party/PhoneticSearch/threshHold
v Description—Specifies the number of exact matches returned by a search
transaction that is sufficient to warrant not adding phonetic search results to the
result set.
v Default value—0
v Dynamic—true

/IBM/Party/PhoneticSearch/AddressSearch/enabled
v Description—Determines whether phonetic search on address is enabled.
v Default value—false
Chapter 34. Using the Configuration and Management components

449

Licensed Materials – Property of IBM

v Dynamic—true

/IBM/Party/PhoneticSearch/AddressSearch/maxLength
v Description—Specifies the maximum length of the phonetic keys generated for
an address.
v Default value—4
v Dynamic—true

/IBM/Party/PhoneticSearch/HierarchyOrganizationSearch/enabled
v Description—Determines whether phonetic search on organization name is
enabled on the searchNodeInOrganizationHierarchy transaction.
v Default value—false
v Dynamic—true

/IBM/Party/PhoneticSearch/HierarchyPersonSearch/enabled
v Description—Determines whether phonetic search on person name is enabled
on the searchNodeInPersonHierarchy transaction.
v Default value—false
v Dynamic—true

/IBM/Party/PhoneticSearch/OrganizationNameSearch/enabled
v Description—Determines whether phonetic search on organization name is
enabled.
v Default value—false
v Dynamic—true

/IBM/Party/PhoneticSearch/OrganizationNameSearch/maxLength
v Description—Specifies the maximum length of the phonetic keys generated for
an organization name.
v Default value—4
v Dynamic—true

/IBM/Party/PhoneticSearch/PersonNameSearch/enabled
v Description—Determines whether phonetic search on person name is enabled.
v Default value—false
v Dynamic—true

/IBM/Party/PhoneticSearch/PersonNameSearch/maxLength
v Description—Specifies the maximum length of the phonetic keys generated for a
person name.
v Default value—4
v Dynamic—true

/IBM/Party/PrivacyPreference/
ValidateProductEntityWithProductDomain/enabled
v Description—Determines whether to use the product domain to validate a
product that is associated with a TCRMEntityInstancePrivPrefBObj object. If this
value is set to false, the product is validated against the CDPRODTP code table.
Otherwise, the product is validated using the data model in the product domain.
v Default value—false

450

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Dynamic—false

/IBM/Party/Search/maxResults
v Description—Specifies the maximum number of records returned from a
searchParty, searchPerson, or searchOrganization transaction.
v Default value—100
v Dynamic—true

/IBM/Party/Search/ReturnValue/organizationAddressUsageType
v Description—Specifies the organization address usage type to return in the
response as part of the search summary. This value should be one of the
ADDR_USAGE_TP_CD values in the CDADDRUSAGETP table.
v Default value—3
v Dynamic—false

/IBM/Party/Search/ReturnValue/organizationIdentificationType
v Description—Specifies the organization identification type to return in the
response as part of the search summary. This value should be one of the
ID_TP_CD values in the CDIDTP table.
v Default value—2
v Dynamic—false

/IBM/Party/Search/ReturnValue/organizationNameUsageType
v Description—Specifies the organization name usage type to return in the
response as part of the search summary. This value should be one of the
NAME_USAGE_TP_CD values in the CDNAMEUSAGETP table.
v Default value—1
v Dynamic—false

/IBM/Party/Search/ReturnValue/personAddressUsageType
v Description—Specifies the person address usage type to return in the response
as part of the search summary. This value should be one of the
ADDR_USAGE_TP_CD values in the CDADDRUSAGETP table.
v Default value—1
v Dynamic—false

/IBM/Party/Search/ReturnValue/personIdentificationType
v Description—Specifies the person identification type to return in the response as
part of the search summary. This value should be one of the ID_TP_CD values
in the CDIDTP table.
v Default value—1
v Dynamic—false

/IBM/Party/Search/ReturnValue/personNameUsageType
v Description—Specifies the person name usage type to return in the response as
part of the search summary. This value should be one of the
NAME_USAGE_TP_CD values in the CDNAMEUSAGETP table.
v Default value—1
v Dynamic—false

Chapter 34. Using the Configuration and Management components

451

Licensed Materials – Property of IBM

/IBM/Party/Standardizer/Address/className
v Description—Specifies the address standardizer class.
v Default value—com.dwl.tcrm.coreParty.component.TCRMAddressStandardizer
v Dynamic—true

/IBM/Party/Standardizer/Name/className
v Description—Specifies the name standardizer class.
v Default value—com.dwl.tcrm.coreParty.component.TCRMPartyStandardizer
v Dynamic—true

/IBM/Party/SummaryIndicator/enabled
v Description—Determines whether the Summary Data Indicator feature is
enabled.
v Default value—off
v Dynamic—false

/IBM/Party/SuspectProcessing/enabled
v Description—Determines whether Suspect Processing is enabled.
v Default value—true
v Dynamic—true

/IBM/Party/SuspectProcessing/AddParty/returnSuspect
v Description—Controls how A2 suspects are returned in an addParty transaction.
This configuration element is used in conjunction with the
element of an addParty transaction. If the
element is set to No on the request and this
configuration element is enabled, and if A2 parties are found and no A1 parties,
then the A2 parties are returned in the response and no new party is added. The
transaction is essentially halted.
v Default value—true
v Dynamic—true

/IBM/Party/SuspectProcessing/PersistDuplicateParties/enabled
v Description—Determines whether a duplicate A1 party is persisted based on
some predefined criteria.
v Default value—false
v Dynamic—true

/IBM/Party/SuspectProcessing/SuspectReasonType/
systemMarked
v Description—Specifies the type code indicating that the suspect is marked by
the system. This value should be one of the SUSP_SOURCE_TP_CD values in
the CDSUSPECTSOURCETP table.
v Default value—2
v Dynamic—false

/IBM/Party/SuspectProcessing/SuspectReasonType/userMarked
v Description—Specifies the type code indicating that the suspect is marked by a
user. This value should be one of the SUSP_SOURCE_TP_CD values in the
CDSUSPECTSOURCETP table.

452

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Default value—1
v Dynamic—false

/IBM/Party/SuspectProcessing/SuspectStatusType/
criticalChangeResolved
v Description—Specifies the type code indicating that the suspect was
investigated, and the critical data change was resolved. This value should be one
of the SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP table.
v Default value—5
v Dynamic—false

/IBM/Party/SuspectProcessing/SuspectStatusType/duplicateParty
v Description—Specifies the type code indicating that the suspect was
investigated, and the parties are duplicates. This value should be one of the
SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP table.
v Default value—4
v Dynamic—false

/IBM/Party/SuspectProcessing/SuspectStatusType/
duplicatePartyDoNotCollapse
v Description—Specifies the type code indicating that the suspect is under
investigation, the parties are suspect duplicates, and should not be collapsed.
This value should be one of the SUSP_ST_TP_CD values in the
CDSUSPECTSTATUSTP table.
v Default value—6
v Dynamic—false

/IBM/Party/SuspectProcessing/SuspectStatusType/notDuplicate
v Description—Specifies the type code indicating that the suspect was
investigated, and the parties are not duplicates. This value should be one of the
SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP table.
v Default value—3
v Dynamic—false

/IBM/Party/SuspectProcessing/SuspectStatusType/pending
v Description—Specifies the type code indicating that the suspect is under
investigation, and the critical data change for the party is pending. This value
should be one of the SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP
table.
v Default value—2
v Dynamic—false

/IBM/Party/SuspectProcessing/SuspectStatusType/
suspectDuplicate
v Description—Specifies the type code indicating that the suspect is under
investigation, and the party and the suspect are duplicates. This value should be
one of the SUSP_ST_TP_CD values in the CDSUSPECTSTATUSTP table.
v Default value—1
v Dynamic—false

Chapter 34. Using the Configuration and Management components

453

Licensed Materials – Property of IBM

/IBM/Product/ProductStructureStrategy/Variant
v Description—Specifies the rule ID of the configured VariantStrategy product
structure strategy.
v Default value—A blank (that is, a blank value).
v Dynamic—false

/IBM/Product/ProductSuspectProcessing/ProcessingDepth/
categoryInquiryLevel
v Description—Specifies the product category inquiry level used in the
collapseMultipleProducts and splitProduct transactions.
v Default value—1
v Dynamic—false

/IBM/Product/ProductSuspectProcessing/ProcessingDepth/
productInquiryLevel
v Description—Specifies the product inquiry level used in the
collapseMultipleProducts and splitProduct transactions.
v Default value—4
v Dynamic—false

/IBM/Product/ProductSuspectProcessing/ProcessingDepth/
relatedProductInquiryLevel
v Description—Specifies the related product inquiry level used in the
collapseMultipleProducts and splitProduct transactions.
v Default value—1
v Dynamic—false

/IBM/Product/Search/MaxReturn
v Description—Specifies the maximum number of records returned from a
searchProductInstance transaction.
v Default value—100
v Dynamic—true

/IBM/Product/SpecValueSearch/CaseSensitive/enabled
v Description—Determines whether case sensitive search for string value is
enabled.
v Default value—false
v Dynamic—true

/IBM/Product/SpecValueSearch/MaxSpecValueSearchBObjs
v Description—Specifies the maximum number of spec value search business
objects in the searchProductInstance transaction.
v Default value—5
v Dynamic—false

/IBM/Product/SpecValueSearch/
MaxSpecValueSearchCriteriaBObjs
v Description—Specifies the maximum number of spec value search criteria
business objects in the searchProductInstance transaction.
v Default value—20

454

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Dynamic—false

/IBM/Product/SpecValueSearch/SpecValueSearchSQL/className
v Description—Specifies the class to construct search SQL snippet.
v Default value—defaulted
v Dynamic—true

/IBM/Product/SuspectSearch/maxResults
v Description—Specifies the maximum number of records returned from a
searchProductSuspect transaction
v Default value—100
v Dynamic—true

/IBM/ProductServices/RevisionHistory/DateRange/maxYears
v Description—Specifies the maximum number of years to limit the date range
that can be used in the getRevisionHistory transaction.
v Default value—1
v Dynamic—false

/IBM/ThirdPartyAdapters/Address/Formatter
v Description—Specifies a pattern that is used to format address information. The
pattern must adhere to the vendor’s address standardization specifications.
v Default
value—AddressLineOne=DelDesignator+DelId+StreetNumber+PreDirectional+
StreetName+StreetSuffix+PostDirectional;AddressLineTwo=BoxDesignator+BoxId
+StnInfo+StnId;AddressLineThree=BuildingName+Region+DelInfo
v Dynamic—true

/IBM/ThirdPartyAdapters/EAS/addressUsageTypeMap
v Description—Specifies the mapping between the InfoSphere MDM Server
CDADDRUSAGETP code table values and the EAS ADDR_TYPE values.
The InfoSphere MDM Server CDADDRUSAGETP code table values are as
follows:
–
–
–
–
–
–
–

1
2
3
4
5
6
7

Primary residence
Other residence
Business
Mailing
Summer residence
Temporary residence
Secondary residence

The EAS ADDR_TYPE values are as follows:
– H - Home Address
– B - Business Address
– O - Other Address
The ADDR_TYPE values are the same for both IBM DB2 Relationship Resolution
and IBM DB2 Anonymous Resolution Anonymizer.
v Default value—(1-H),(2-O),(3-B),(4-O),(5-O),(6-O),(7-O)
v Dynamic—false

Chapter 34. Using the Configuration and Management components

455

Licensed Materials – Property of IBM

/IBM/ThirdPartyAdapters/EAS/chargeCardTypeMap
v Description—Specifies the mapping between the InfoSphere MDM Server
CDCHARGECARDTP code table values and the EAS NUM_TYPE or
ATTR_TYPE values, depending on the concrete EAS integration.
The InfoSphere MDM Server CDCHARGECARDTP code table values are as
follows:
– 1 - Visa
– 2 - Mastercard
– 3 - American Express®
– 4 - Diner’s Club
For IBM DB2 Relationship Resolution, the NUM_TYPE value is CC - Credit
Card Number.
For IBM DB2 Anonymous Resolution Anonymizer, the ATTR_TYPE value is CC Credit Card Number.
v Default value—(1-CC),(2-CC),(3-CC)
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/contactMethodTypeMap
v Description—Specifies the mapping between the InfoSphere MDM Server
CDCONTMETHTP code table values and the EAS NUM_TYPE, ADDR_TYPE, or
ATTR_TYPE values, depending on the concrete EAS integration.
The InfoSphere MDM Server CDCONTMETHTP code table values are as
follows:
– 1 - Home telephone
– 2 - Business telephone
– 3 - Facsimile
– 4 - Pager
– 5 - Cellular
– 6 - Business e-mail
– 7 - Personal e-mail
– 8 - Mobile telephone
For IBM DB2 Relationship Resolution, the NUM_TYPE value is PH - Phone
The ADDR_TYPE values are as follows:
– H - Home address
– B - Business address
– O - Other address
For IBM DB2 Anonymous Resolution Anonymizer, the NUM_TYPE value is:
PHONE - Phone Number.
The ATTR_TYPE value is:EMAIL - e-mail
v Default value—(1-PH),(2-PH),(3-PH),(4-PH),(5-PH),(6-B),(7-H),(8-PH)
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/correctionAction
v Description—Specifies the action for before image in an update transaction.
Valid values are as follows:
– D - Delete
– F - Forced hard-delete
– N - Do not delete

456

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Default value—D
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/dsrcCode
v Description—Specifies the unique data source code that EAS uses to identify
InfoSphere MDM Server.
v Default value—
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/exclusiveSourceSystem
v Description—Specifies a comma delimited string listing the client system IDs
that are feeder systems to InfoSphere MDM Server and feeder systems to EAS at
the same time.
v Default value—
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/idStatusTypeMap
v Description—Specifies the mapping between the InfoSphere MDM Server
CDIDSTATUSTP code table values and the EAS NUM_STAT values.
The InfoSphere MDM Server CDIDSTATUSTP code table values are as follows:
– 1 - Applied for identification
– 2 - Active
– 3 - Inactive
– 4 - Expired
– 5 - Certified
– 6 - Temporary residence
– 7 - Not certified
The EAS NUM_STAT values are as follows:
– V - Valid
– I - Invalid
– U - Unknown
The NUM_STAT values only applies to IBM DB2 Relationship Resolution.
v Default value—(1-I),(2-V),(3-I),(4-I),(5-V),(6-I)
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/idTypeMap
v Description—Specifies the mapping between the InfoSphere MDM Server
CDIDTP code table values and the EAS NUM_TYPE values, depending on the
concrete EAS integration.
The InfoSphere MDM Server CDIDTP code table values are as follows:
– 1 - Social security number
– 2 - Corporate tax identification
– 3 - Driver’s license
– 4 - Birth certificate
– 5 - Mother’s maiden name
– 6 - Tax identification number
– 7 - Tax registration number
– 8 - Passport Nnumber
Chapter 34. Using the Configuration and Management components

457

Licensed Materials – Property of IBM

– 9 - Health Card
– 10 - Social insurance number
– 11 - ABILITECLINK
For IBM DB2 Relationship Resolution, the NUM_TYPE values are as follows:
– DL - Driver’s license
– PP - Passport number
– SSN - Social security number
For IBM DB2 Anonymous Resolution Anonymizer, the NUM_TYPE values are as
follows:
– DL - Driver’s license
– SSN - Social security number
v Default value—(1-SSN),(3-DL), (8-PP)
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/nameUsageTypeMap
v Description—Specifies the mapping between the InfoSphere MDM Server
CDNAMEUSAGETP code table values and the EAS NAME_TYPE values.
The InfoSphere MDM Server CDNAMEUSAGETP code table values are as
follows:
– 1 - Legal
– 2 - Business
– 3 - Nickname
– 4 - Also known as
– 5 - Maiden
– 6 - Alias
– 7 - Preferred
– 8 - Previous
The EAS NAME_TYPE values are as follows:
– M - Main name
– A - Also known as
The NAME_TYPE values are the same for both IBM DB2 Relationship
Resolution and IBM DB2 Anonymous Resolution Anonymizer.
v Default value—(1-M),(2-M),(3-A),(4-A),(5-A),(6-A),(7-A),(8-A)
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/queue
v Description—Specifies the queue defined for the JMS provider, which is used
when InfoSphere MDM Server sends UMF message to EAS.
v Default value—jms/EASQueue
v Dynamic—false

/IBM/ThirdPartyAdapters/EAS/queueConnectionFactory
v Description—Specifies the queue connection factory defined for the JMS
provider, which is used when InfoSphere MDM Server sends UMF message to
EAS.
v Default value—jms/EASQCF
v Dynamic—false

458

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

/IBM/ThirdPartyAdapters/EAS/resolutionType
v Description—Specifies the concrete EAS integration. Valid values are as follows:
– NONE - No EAS integration with InfoSphere MDM Server
– RR - InfoSphere MDM Server is integrated with a IBM DB2 Relationship
Resolution instance
– AR - InfoSphere MDM Server is integrated with a IBM DB2 Anonymous
Resolution Anonymizer
v Default value—NONE
v Dynamic—false

/IBM/ThirdPartyAdapters/IIS/defaultCountry
v Description—Specifies the type code indicating that default country when a
country is not provided in the data. This value should be one of the
COUNTRY_TP_CD values in the CDCOUNTRYTP table. This configuration
element is used by integration with the IIS Server.
v Default value—185
v Dynamic—false

/IBM/ThirdPartyAdapters/IIS/initialContextFactory
v Description—Specifies the JNDI context factory class used to look up the IIS
Server. This configuration element is used by integration with the IIS Server.
v Default value—com.ibm.websphere.naming.WsnInitialContextFactory
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/providerURL
v Description—Specifies the URL pointing to the IIS server. This configuration
element is used by integration with the IIS Server.
v Default value—iiop://iishost:2809
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/operationName
v Description—Specifies the method on the IBM WebSphere DataStage® service
that the adapter class calls in matching organizations. This configuration element
is used by integration with the IIS Server.
v Default value—match
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/Converter/
className
v Description—Specifies the class used to convert the data between the InfoSphere
MDM Server data format and the IBM InfoSphere DataStage data format used in
matching organizations. This configuration element is used by integration with
the IIS Server.
v Default value—
com.ibm.mdm.thirdparty.integration.iis8.converter.
MatchOrganizationInfoServerConverter
v Dynamic—true

Chapter 34. Using the Configuration and Management components

459

Licensed Materials – Property of IBM

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/DesiredTypes/
addressUsage
v Description—Specifies the address usage type of an organization to consider
when matching organizations. This configuration element is used by integration
with the IIS Server.
v Default value—An asterisk (*).
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/DesiredTypes/
identification
v Description—Specifies the identification type of an organization to consider
when matching organizations. This configuration element is used by integration
with the IIS Server.
v Default value—2
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/DesiredTypes/
nameUsage
v Description—Specifies the name usage type of an organization to consider when
matching organizations. This configuration element is used by integration with
the IIS Server.
v Default value—An asterisk (*).
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/Input/dataType
v Description—Specifies the name of the IBM WebSphere DataStage input data
class used in matching organizations. This configuration element is used by
integration with the IIS Server.
v Default value—MatchInput
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/Output/dataType
v Description—Specifies the name of the IBM WebSphere DataStage output data
class used in matching organizations. This configuration element is used by
integration with the IIS Server.
v Default value—MatchOutput
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/Service/
basicPackageName
v Description—Specifies the basic package name of the remote home interface of
the IBM WebSphere DataStage service that the adapter class uses in matching
organizations. This configuration element is used by integration with the IIS
Server.
v Default value—com.ibm.isd.MDMQS.MDMQSService
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/Service/jndi
v Description—Specifies the remote JNDI name of the IBM WebSphere DataStage
service that the adapter class uses in matching organizations. This configuration
element is used by integration with the IIS Server.

460

InfoSphere MDM Server v9.0: Developers Guide

Licensed Materials – Property of IBM

v Default value—ejb/MDMQS/MDMQSService
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchOrganization/Service/name
v Description—Specifies the name of the remote home interface of the IBM
WebSphere DataStage service that the adapter class uses in matching
organizations. This configuration element is used by integration with the IIS
Server.
v Default value—MDMQSService
v Dynamic—true

/IBM/ThirdPartyAdapters/IIS/MatchPerson/operationName
v Description—Specifies the method on the IBM WebSphere DataStage service
that the adapter class calls in matching persons. This configuration element is
used by integr