White Paper

Extending IBM InfoSphere Master Data Management Server
using the MDM Workbench

Tony Garrard (garrard@uk.ibm.com) and Matt Lovett (mlovett@uk.ibm.com)
All Rights Reserved
Version 2.0
Copyright International Business Machines Corporation 2009, 2010
Page 1 of 35
Contents
Trademarks ...........................................................................................................................3
Introduction...........................................................................................................................3
Prerequisites......................................................................................................................3
Additional References.......................................................................................................4
Setting up the Development Environment............................................................................4
Preparing to run the Setup Wizard....................................................................................4
Running the Setup Wizard ................................................................................................4
WebSphere Configuration ................................................................................................7
MDM Configuration and Deployment..............................................................................8
Database Information........................................................................................................9
Resolving problems that occur during setup and configuration .....................................10
Setup Wizard Task Descriptions.........................................................................................10
Importing the MDM Resources ......................................................................................10
Modify the Web Service Configuration..........................................................................11
Configuring the WebSphere Application Server ............................................................11
Creating the database ......................................................................................................12
Deploying the MDM EAR..............................................................................................13
Deploying the MDM Configuration ...............................................................................13
Verifying the Install ........................................................................................................13
Restoring the setup tool ..................................................................................................14
Creating a new Hub Module ...............................................................................................14
Creating an Addition.......................................................................................................16
Code Generation .............................................................................................................19
Merging CustomerResources..........................................................................................20
Configuring the domain ..................................................................................................21
Adding an Entity Extension ................................................................................................21
Sharing the code..................................................................................................................25
Sharing the workspace ....................................................................................................25
Sharing the model ...........................................................................................................27
Testing the Extensions ........................................................................................................27
Testing the addition using Web Services........................................................................28
Testing the addition using the service controller bean....................................................30
Appendix A: Web Services Test sample code....................................................................31
Appendix B: Service controller sample code......................................................................33
Page 2 of 35
Trademarks
IBM, DB2, InfoSphere, Rational and WebSphere are trademarks of International
Business Machines Corporation in the United States, other countries, or both.
EJB, Java, Java Naming and Directory Interface, JDBC, J2EE, and all Java-based
trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries,
or both.
Other company, product, or service names may be trademarks or service marks of others.
Introduction
The IBM InfoSphere Master Data Management (MDM) Server 9 provides a solution for
managing enterprise data.
The framework provides a comprehensive data model and associated business services
that can be extended to create a customized solution tailored to your business.
This article provides guidance on how these extensions are developed using the MDM
Workbench supplied with the MDM Server product. The following topics are discussed
with the use of examples to help you get started:
Setting up your development environment

Adding new entities to the data model
Customizing entities within the data model
The use of code control systems to manage generated artifacts
Methods for testing
The majority of this whitepaper is also applicable to the IBM InfoSphere Master
Information Hub (MIH). The MIH workbench provides similar capabilities to the MDM
Workbench, allowing the user to add new entities to the application.
Prerequisites
IBM Rational Application Developer for WebSphere Software (RAD) 7.5.4

or IBM Rational Software Architect (RSA) 7.5.4 installed (without the Web
Service feature pack as it is incompatible with the MDM Workbench)
The MDM Workbench 9.0.0.2 installed on RSA/RAD
The WebSphere 7.0.0.5 test environment installed on RSA/RAD
DB2 9.5 fixpack 4 installed onto the same machine as the RSA/RAD tooling
Access to the MDM900_WAS_AIX.tar.gz file supplied with the MDM Server
distribution media
MDM Server version 9 can be deployed onto either WebSphere Application Server 6.1 or
7.0.0.5. Throughout this article version 7.0.0.5 will be used. The versions and fixpack
Page 3 of 35
levels of the pre-requisite software are important and are documented in the MDM
Workbench infoCenter.
Additional References
To complement the information provided in this document, additional information can be
found from the following sources:
The MDM Workbench developerWorks homepage
http://www.ibm.com/developerworks/spaces/mdmworkbench
MDM Workbench developerWorks forum
http://jtlog.wordpress.com/2009/02/11/mdm-workbench-developerworks-forum
Setting up the Development Environment

Before you can develop extensions to the MDM platform it is necessary to prepare the
RSA workspace by running a setup wizard. This section outlines the recommended setup
procedure. More information on the individual tasks within the wizard can be found later
in this article.
Preparing to run the Setup Wizard

Prior to running the setup wizard, the workspace preferences must be configured as
follows.
Enable J2EE developer capability in RSA
1. Click Window > Preferences to open the Preferences dialog.
2. Click General > Capabilities.
3. Confirm the J2EE Developer capability is enabled.
Select the WebSphere 7 JRE as the default
1. Click Window > Preferences to open the Preferences dialog.
2. Click Java > Installed JREs.
3. Confirm the WebSphere Application Server v7.0 JRE is selected.
The WebSphere 7 JRE will not be available unless you have installed the WebSphere
Application Server 7 Test Environment. This feature is required before running the setup
wizard.
Running the Setup Wizard

To run the setup wizard:
Page 4 of 35
Click File > New > Other. The New wizard opens.
On the Select a wizard page select InfoSphere Master Information Hub >
Development and Test Environment.
Click Next.
You will then see a dialog detailing all the tasks that can be run.
Figure 1: The Development and Test Environment wizard
Figure1.PNG
Each setup task is explained in more detail later in this document.
If the wizard has been run previously, the Restore the Development Environment Setup
Tool task should be run on its own prior to running any other task. This ensures that no
Page 5 of 35
residual information from a previous run has been left within the tool configuration, and
clears the saved information from the following pages of the wizard.
While it is possible to run all of the setup tasks in one step, it is recommended to run the
first 5 tasks, up to Create an Application Database. Then verify that your workspace
security settings match those of the application server (see this section). Once this is
complete then re-launch the setup wizard and invert the selection to choose the remaining
8 tasks.
It is important to note that running the wizard turns off the workspace Build
Automatically option. If you wish to re-enable automatic builds then select Build
Automatically from the Project menu.
When working through the wizard the following additional dialogs will be displayed to
input the required information. Some of the tasks do not require all of this information so
some dialogs may be omitted.
Page 6 of 35
WebSphere Configuration
Figure 2: WebSphere Configuration
Figure2.PNG
For the WebSphere Configuration:
1. Choose the WebSphere version. For this article we are using version 7.0. Selecting
the WebSphere version will automatically configure the WebSphere home.
2. Select the required profile from the Profile Name drop-down box. If you have
not yet created a WebSphere Application Server profile, use the Create Profile
button to launch the Profile Management Tool. Selecting a profile will fill in the
correct values for the bootstrap port, node name, and cell name.
3. In Backup profile at specify the directory where the profile backup will be
placed.
4. In Application distribution file specify the location of the MDM Distribution
file.
5. In Unpack distribution to specify where the distribution will be unpacked.
Page 7 of 35
MDM Configuration and Deployment

Figure 3: Application Configuration and Deployment
Figure3.PNG
For the Application Configuration and Deployment:
1. Click the Detect host name button to add in your machines host name, or type
localhost.
2. The Deployment name is defaulted to MDMServer.
3. In the Temporary output folder specify the folder or pathname where the MDM
EAR from your workspace will be exported to.
Page 8 of 35
Database Information
Figure 4: Database Information
Figure4.PNG
For the database information panel:
1. Check that the Database home is set to the correct location. This should be
$DB2_INSTALL_LOC/java
2. Specify the username and password for the user that will create the database
3. Specify the name of the database.
Before you can continue from the database information panel you must click the Test
Connection button. This will validate the database settings and once the settings have
been successfully checked, the Next and Finish buttons will be enabled.
Once all the required information has been specified, clicking the Finish button will
execute the selected setup tasks.
Page 9 of 35
Resolving problems that occur during setup and configuration

If you are having issues with the development setup, you will need to examine the logs to
determine where the error occurred.
Logging of the tasks is done in several areas:
c:\test\ DevEnvSetup.log logs the actions of the wizard (the directory must exist
for this log to appear).
$WORKSPACE\.metadata\.plugins\com.ibm.mdm.config.external.automation\
automationLog.log logs the output of the tasks.
Database logs are found within the database scripts in the MDMDatabase project.
For each set of scripts you will find a localrun folder that contains the output.
$WORKSPACE\CustomerResources\logs will contain the logs generated by the
server. You may need to refresh the project in the workspace before you can see
the log files. ManagementAgent.log and ManagmentConsole.log will show the
activity of the Deploy Configuration task. The location of these log files is
configured in the CustomerResources/properties/Log4J.properties file.
Setup Wizard Task Descriptions

The following sections give more details and explanations for each of the tasks available
in the Development and Test Environment wizard.
Importing the MDM Resources

Tasks Involved:
Import Application Projects into Workspace

Customize Configuration Files
Task Details:
These tasks are responsible for setting up the workspace within RSA/RAD.
The task Import Application Projects into Workspace performs several actions:
1.
2.
3.
4.
Extracts the MDM application and resources into the specified unpack location.
Imports the MDM EAR and the EAR manifest file into the workspace.
Updates the classpath settings for the MDM projects.
Imports the database scripts (from the MDM/database folder within the unpacked
location) into a project called MDMDatabase.
5. Creates a CustomerResources project and unzips the properties.jar and
DWLSchemas.jar into this project.
6. Imports the ManagementAgent and ManagementConsole (from the MDM folder
within the unpacked location) into the workspace.
Page 10 of 35
The task Customize Configuration files modifies property files in the

CustomerResources, ManagementAgent and ManagementConsole to match the
configuration details that were specified in the wizard. It also sets the database
configuration found in the dwl-config.xml file within the DWLCommonServicesEJB
project.
Modify the Web Service Configuration

Note that the wizard does not configure the MDM Web services to match the security
attributes of your app server. The default is security enabled. If this does not match the
security settings of your app server then you must reconfigure Web services. In each of
the WSEJB projects, there are 2 files found in the folder ejbModule/META-INF
ibm-webservices-bnd.xmi
ibm-webservices-ext.xmi
Within the same folder there are example files with the suffix
SecurityEnabled/SecurityDisabled. You will need to copy the contents of the files that
match your WAS security setting into the above two files.
Configuring the WebSphere Application Server

Tasks Involved:
Backup WebSphere profile

Configure WebSphere profile
Task Details:
There are two tasks associated with configuring the application server:
The Backup WebSphere Profile task will backup the profile to the directory specified in
the wizard.
The Configure WebSphere Profile task creates all the required application server
resources, including Message Queues and JDBC Connections. It also sets the server
classpath to include resources held in the CustomerResources project. This enables
developers to configure the MDM Server directly within the CustomerResources folder
without having to repackage the configuration into the appropriate jars held in the EAR.
The classpath setting can be checked using the WAS admin console.
1. Select your server from Servers / Application Servers.
2. From Server Infrastructure, expand Java and Process Management.
3. Choose Process Definition, and from Additional Properties select Java Virtual
Machine.
4. From General Properties confirm the classpath settings that point to the resources.
Page 11 of 35
Figure 5: Verifying the WAS classpath
Figure5.PNG
To validate that the task has completed successfully, use the WAS Admin console and
check that the jdbc/DWLConfig Data source has been created. This task must complete
successfully or deploying the MDM EAR to WAS will fail.
Creating the database

Tasks Involved:
Create an Application Database
Task Details:
The Create an Application Database task will create the required DB2 database. The
database created using the task will have full Compound Triggers with Delete (more about
this on creating the new MDM Module). It will also have data set to the insurance
industry. This may not match the choices you make when installing MDM Server, but is
adequate for a development and test environment.
To use Oracle as your database, you should refer to the Tech note Setting up the MDM
Server development environment with WebSphere Application Server and an Oracle
database from the IBM support website.
Page 12 of 35
To check that the application server can connect to the database, use the WAS admin
console to test the connection (via Resources/JDBC/Data sources).
Deploying the MDM EAR

Tasks Involved:
Clean workspace
Prepare for deployment
Build workspace
Export Application EAR
Deploy Application to WebSphere Profile
Task Details:
These tasks build an EAR file for the application, and then deploy the EAR onto
WebSphere Application Server. An alternative to running these tasks is to manually run
Project > Clean from the build menu and then hot-deploy the EAR to the WAS server. To
hot-deploy the EAR ensure that your server is show in the Servers view, and then right
click the server and use Add and Remove Projects to add the MDM EAR project.
If you have run the wizard, but would prefer to use the hot-deploy functionality, you must
remember to remove the deployed application from the server (using the WAS admin
console) before hot-deploying the MDM EAR project.
Deploying the MDM Configuration

Tasks Involved:
Deploy Configuration
Task Details:
The task Deploy Configuration runs the management agent and console to deploy the
configuration held in the exported EAR. This means that even if you have hot-deployed
the MDM application, you will have to run the Export Application EAR for this task to
successfully complete.
To check that the task completed successfully, view the APPSOFTWARE and
CONFIGELEMENT tables within the database.
Verifying the Install

Tasks Involved:
Import Installation Verification project

Validate Installation
Page 13 of 35
Task Details:
These tasks import and run the Install VerificationTest. To determine whether the tests
have successfully completed, you will need to examine the response files found in
InstallVerification/xml/response. Each response file should have SUCCESS as the
Result Code. You will need to refresh the Install Verification project before the response
files are visible in the workspace.
Restoring the setup tool

Tasks Involved:
Restore the Development Environment Setup Tool
Task Details:
As previously mentioned, this task cleans up the configuration within the tool, as well as
the saved responses to the pages within the wizard. This task should be run before setting
up each new development environment.
Creating a new Hub Module

The MDM server configuration may be extended in a number of different ways, from the
development of entirely new entities to just adding behavioral modifications to existing
entities.
The MDM server is composed of Hub Modules. MDM provides the following default
modules: BusinessServices, DWLBusinessServices, FinancialServices, Party and Product.
For each of these modules, there exists a reference model that can be found in
$Module/src/reference.mdmxmi which you can open to view the Transactions, Business
Objects and Codetables available.
In order to create any server modifications, a new hub module project must be created.
This will contain an empty model (module.mdmxmi) that data and behavioral
modifications can be added to. The MDM Workbench includes a wizard for creating
module projects (New > Other > InfoSphere Master Information Hub > Hub Module
Project).
Page 14 of 35
Figure 6: Hub Module Project Wizard
Figure6.PNG
The following fields are required:
Project name the name of the new hub module project
Base Java package name Java classes generated for this hub module project will
be defined in sub-packages within the specified package name
Service namespace URI The URI that will be used to invoke the Web services
EAR project name Select the MDM EAR project
The first time that a Hub Module Project is created the application level configuration
must also be supplied:
Hub base name the name of the new application
Database schema name the name of the database schema
Within the new Module Project the following files are created: the module.mdmxmi
model file, mdmgen.xml (an ANT build script used to generate the code) and
mdmgen.properties that defines additional properties that can be specified for the ANT
script.
Page 15 of 35
Additionally, if an application.mdmxmi file does not already exist, it is created in the

application EAR project. This file defines code generation options that apply to all the
new modules in the workspace.
Figure 7: Code generation options within the application module
Figure7.PNG
The application module contains the hub base name, as well as the schema name,
databases and history triggers to be generated. It is important to match the schema name
and triggers to those that will be used for the real application.
Creating an Addition
Data Additions and Data Extensions can be added to the model in one of two ways:
By running a wizard (New> Other>Data Addition/Data Extension)

By using the Hub Module editor
For example, the Reminder addition, which will be used to add reminder notes for users, is
required to have the following attributes:
Page 16 of 35
Table 1: Contents of the Reminder addition

Name
ReminderpkId
Type
Long
priorityTpCd
Type Code
remindPartyId
Reference
remindRecordedBy
String
remindDtm
TimeStamp
remindDesc
String
recordedDtm
TimeStamp
Description
The primary key of the new
table / addition. (In the
model editor, check that the
primary key option is
selected.)
A type code reference to the
PriorityType code table
(located in the
DWLBusinessServices
module, underneath the
Task folder).
Reference to the Party entity
(located in the Party
module). This is the
association between the
Reminder and the Party that
should be reminded.
The name of the user that
recorded the reminder.
The date on which the
reminder is to happen.
The description of the
reminder.
The date on which the
reminder was recorded.
In this example, the Hub Module editor is used to create the Reminder addition.
1. Open the ExampleModule/module.mdmxmi file (it automatically opens in the Hub
Module editor).
2. Select the Model tab.
3. Within the Contents tree on the left hand pane, right click on the ExampleModule
folder and choose New > Entity.
4. In the right hand pane, enter Reminder as the entity name.
The Hub Module editor will display the new entity, along with additional standard
content, including a primary key attribute, an error reason, and add, update and get record
transactions.
Page 17 of 35
Figure 8: The model editor showing the new Reminder entity
Figure8.PNG
Next, use the model editor to create the remaining content underneath the Reminder entity.
For each, right click the entity and choose New > Attribute (or Reference, or Type Code),
and then configure the name and type.
By default any new addition (Entity) will have add, update and get record transactions
created. The add and update transactions are mandatory and cannot be deleted, however
the user can specify as many Get Record transactions as they require. The Get Record
transaction provides a parameter list which can be modified to include any of the attributes
available to the entity. For this example the default getReminder transaction is replaced
with two new Get Record transactions. Again, use the Hub Module model editor to make
the changes.
Modify the getRecord transaction to get the reminder associated with a specific
ReminderpkId primary key:
1. Select the getReminder transaction and rename the record to
getReminderByReminderId.
2. Verify that the Query Parameters list only contains ReminderpkId and the option
Multiple Records Returned remains unchecked.
Add a transaction to get all reminders associated with a specific person
Page 18 of 35
1. Right click Reminder and choose New > Get Record.

2. Rename the record to getReminderByPartyId.
3. Modify the Query Parameters so that the list only contains the remindPartyId
parameter and verify the option Multiple Records Returned is checked.
If required, users can add extra transactions:
Txn transaction transactions which use a Business Object as a parameter
Inquiry transaction transactions which use MDM Simple types (String, Long,
Timestamp, BigDecimal or Short) as parameters
The model should now look like the following figure:
Figure 9: The complete module model
Figure9.PNG
Code Generation
When the model is complete you can use the 'Generate Code' action to create the addition.
This process will create several new projects in the workspace:
ExampleModuleEJB - the controllers EJB session bean

ExampleModuleWS - the Web service implementation
ExampleModuleWSEJB the Web service EJB session bean
Page 19 of 35
ExampleModuleWS_HTTPRouter - the WSDL and XSD files for the Web

services
The ANT script that runs the codegen will also incorporate these projects into the
application EAR and ensure that classpaths are modified so that all projects compile
cleanly.
Unless the Web services need to be customized (which is unlikely), all modifications to
the code are performed in the ExampleModule. The Reminder Business Object (BObj) can
be found in the component sub-package whilst the data access classes can be found in
the entityObject sub-package.
By selecting the ExampleModule project and opening the Tasks view, all the
MDM_TODO markers can be viewed. These markers show where customizations can be
performed e.g. customized validation logic; as well as tasks that have to be performed in
order to complete the implementation.
Merging CustomerResources
Additional files are created in the resources folder within the hub module project. There
are two different types of generated resources: database scripts, and snippets for inclusion
into the CustomerResources project.
The database scripts are generated for each of the database systems that are selected in the
application.mdmxmi file. Review each file for MDM_TODO statements. For the
Reminder example, provided that the application.mdmxmi specifies the correct database
schema name, the files should be complete. Each script includes a comment that explains
which order the scripts should be run in, and how to run them using the DB2 tools.
Another method is to use RSAs built-in Data Connectivity tools to run the specified SQL.
To do this open the SQL files in the default SQL editor, and then right click and select
Run SQL.
The snippets within the resources folder need to be merged into the Customer Resources
project. In each case, the filename tells you which file within the Customer Resources
should be updated.
The properties files are easy to merge; you simply copy the contents into the
corresponding file. It is good practice to surround the changes with a comment, so that
other team members will be able to understand which changes have come from which
module.
The XSD files are a little more difficult to merge. In each case you need to copy the
snippet into the correct target file. Once all the snippets are copied, select the request and
response schemas for your hub (ExampleHubRequest.xsd and ExampleHubResponse.xsd
for this example), and use RSA to validate the files. If there are any validation errors then
you must resolve the errors before deploying the modified application.
Page 20 of 35
For this example, you will find that the ReminderLastUpdateDate and
ReminderLastUpdateUser elements defined by the new snippets clash with the existing
definitions of those elements in some of the existing schemas. Simply commenting out
these two definitions within the ExampleHubRequest.xsd and ExampleHubResponse.xsd
should resolve the problems. Re-run the validation to check that all of the problems are
now resolved.
Configuring the domain

Within the resources folder, there is a domainConfig directory. This contains two sets of
resources: scripts to configure the database and a dwl-config.xml file. You should run the
database script that matches your database, and then copy the dwl-config.xml file into the
XMLServicesEJB\ejbModule\META-INF directory.
Adding an Entity Extension

You can place as many additions or extensions as you need within a hub module project.
However, to show the difference in code generation between the two, a new hub module
project will be used. If multiple teams are working on the solution, splitting the
functionality into multiple modules can enable the different development teams to work in
parallel.
Page 21 of 35
Figure 10: Creating a hub module project to contain the extension
Figure10.PNG
When you have created the new hub module you must remember to modify the Start Id for
the metadata (as found on the Hub Module Overview page). This will ensure that database
metadata does not conflict with that defined in the previous module. In this example we
have set the start id to 1010000, so that the range of ids that will be used does not overlap
with the ExampleModule.
Page 22 of 35
Figure 11: Setting the 'Start Id' for the new hub module
Figure10.PNG
The new entity extension will be called ExtendedPerson and will extend the Person
Business Object. Rather than adding a new table to the database you may choose to extend
the existing table. Using the hub module editor you can create the new entity extension
and then add attributes to it.
In this case, a RiskScore (String) and a RiskRecordedDt (Timestamp) are being added.
When complete, the model should look like the following:
Page 23 of 35
Figure 12: The ExtendedPerson entity extension
Figure12.PNG
Selecting the ExtendedPerson entity extension in the hub module editor shows two
additional options:
Add fields to base table Use this option if you want the extra fields to be added
directly to the base entities database table rather than creating an additional
database table.
Override base query Use this option to provide generated code to customize
the SQL called by the entity.
Generation of this model will produce just one additional project ExampleExtModuleWS.
The other projects that were created in the addition are not required as no additional
transactions have been defined. If build automatically has been turned off, you must
remember to rebuild the workspace. Additionally, in the database metadata scripts, you
should examine the MDM_TODO markers and complete the SQL statements. For
example:
Example 1: Incomplete SQL statement

INSERT INTO DB2ADMIN.CDDWLCOLUMNTP (DWLCOLUMN_TP_CD, DWLTABLE_TP_CD, COLUMN_NAME,
EXPIRY_DT, LAST_UPDATE_DT, DESCRIPTION, LOCALE_SENSITIVE)
VALUES (1010025, -- MDM_TODO: Replace with the DWLTABLE_TP_CD of the existing database
table, 'riskscore', null, CURRENT TIMESTAMP, null, 'N');
Page 24 of 35
In this MDM_TODO, find the appropriate DWLTABLE_TP_CD of Person. The entry

can be found in CDDWLTABLETP and the value should be equal to 308 so that the
INSERT SQL statement now becomes:
Example 2: Complete SQL statement

INSERT INTO DB2ADMIN.CDDWLCOLUMNTP (DWLCOLUMN_TP_CD, DWLTABLE_TP_CD, COLUMN_NAME,
EXPIRY_DT, LAST_UPDATE_DT, DESCRIPTION, LOCALE_SENSITIVE)
VALUES (1010025, 308, 'riskscore', null, CURRENT TIMESTAMP, null, 'N');
Some of the remaining MDM_TODO markers need to be replaced with the

DWLTABLE_TP_CD of the matching history table. In this case that is H_PERSON and
the value from CDDWLTABLETP is 257.
Sharing the code

For any non-trivial project the next logical step is to save the artifacts into a source control
system (SCS) both to ensure that the code is not lost, and to enable other team members
to continue development in parallel.
There is more than one way to share the application code, and the approach used needs to
be tailored to the team and the development/build environment required.
Sharing the workspace

One option is to add the entire workspace to the SCS. This means that all resources in the
workspace are available to the developer and the build process should be very simple.
However, there are several problems with this approach.
The workspace is large. Typically a workspace will contain more than 30,000 files
and occupy around 500MB of disk space.
Some SCSs require artifacts to be checked out prior to them being modified. With
that in mind, the table below shows the artifacts that may be modified and need to
be checked out when creating extensions to the MDM Server
Table 2: Workspace files that will be modified when extending MDM

Server
Project
MDM
Files
META-INF/application.xml
.project
.settings/org.eclipse.wst.common.component
DWLCommonServicesEJB ejbModule/META-INF/ejb-jar.xml
Comment
Updated
when new
modules are
added to the
MDM
application
Updated
Page 25 of 35
ejbModule/META-INF/ibm-ejb-jar-bnd.xmi
X_EJB
X_WS
X_WS
X_WS
X_WS
X_WS_HTTPRouter
X_WSEJB
X_WSEJB
when a new
controller
EJB is added
ejbModule/META-INF/MANIFEST.MF
Updated to
add
dependency
to extension
modules
build/mapping.properties
Used for
build/was_jaxrpc_tdjava.properties
code
build/wsgen.xml
generation,
no need to
save in
source code
repository
.classpath
Updated to
adjust the
classpath for
the module
src/*ext/to Java classes
Generated
classes for
Web services
src/*_Helper, _Deser, _Ser Java classes
Web services
deployment
code that
does not
need to be
saved in the
source code
repository
WebContent/WEB-INF/wsdl/Extensions.xsd Web service
WebContent/WEB-INF/wsdl/*Ext.xsd
schema files
for data
extensions
ejbModule/META-INF/MANIFEST.MF
Updated to
add
dependency
to extension
WS modules
ejbModule/META-INF/*mapping.xml
Web service
type
mapping
files updated
to include
data
extension
Page 26 of 35
X_WSEJB
ejbModule/META-INF/wsdl/Extensions.xsd
ejbModule/META-INF/wsdl/*Ext.xsd
X_WSEJB
mdmgen_backups
type
mappings
Web service
schema files
for data
extensions
Mapping
files are
copied here
by and used
by the code
generator
Note: X signifies the MDM Project that is going to be extended e.g. Party
Sharing the model

Another approach, which should provide more flexibility, is to share only the new hub
module projects and the CustomerResources project. With this approach the process for
setting up a new workspace is reasonably straightforward:
1. Use the wizard to import the application EAR.
2. Extract the hub module projects and CustomerResources from the repository.
3. Run the code generation for each hub module project.
The final step will create the module EJB and Web services projects, and include them all
into the application EAR project. If some of the non-shared code needs to be modified
then the team should either decide to share that project as well, or put a process in place to
ensure that the team members stay in sync with one another.
A case in point is the application.mdmxmi file, which is contained within the MDM
EAR project. Sharing this project would require sharing a lot of additional files and yet
this file only contains a handful of settings which are unlikely to change. It is probably
impractical to put a complex process in place for this simple file, so team members should
probably just agree on common settings, and document them. However, if a build process
is required, then it may be worth considering creating a build project and checking in any
modified files. They can then be copied over to the required destination when required.
Similarly, care must also be taken on sharing the CustomerResources as the Development
and Test Environment wizard introduces workspace location specific values. These are in
bootstrap.properties and Log4j.properties. The property application.manifest.location in
bootstrap can simply be commented out, but the other properties, namely log file locations
may need modification or common setting guidelines.
Testing the Extensions

Before testing the new extensions verify:
Page 27 of 35
1. The CustomerResources have been updated with the resources from the module
project
2. The updated application EAR has been deployed to the test server
3. That the database has been updated with the additional SQL scripts
If you are not extending Person, Organization or Contract, it is a good idea to re-run the
Install Verification test. This will validate that the server is operating normally, and help
diagnose any problems with the merged CustomerResources.
There are several ways to connect to the MDM Server, and many ways to structure the
code that makes these calls. Here we describe two simple ways to call the server one
using Web Services and another sending XML messages to the service controller bean.
These tests could be extended to build a comprehensive test suite for the extensions, and
in a development environment, this suite should be executed and extended as each
customization is built.
These testing methods are suitable for building automated test suites. A more interactive
approach, where a graphical user interface is created to view and update the contents of
the MDM Server, is often useful. The User Interface Generator (included in the MDM
Workbench) could be used to rapidly build such tools.
Testing the addition using Web Services

It is possible to test the Web service without writing any code at all. RSA includes the
Web Services Explorer, which can be used to connect to any Web service. To use this,
right click on the WSDL file for the service that you want to test, and choose Web
Services > Test with Web Services Explorer. This can be used to invoke the methods on
the service, but filling in the request can be complicated, so this approach is best used as a
quick check to make sure that the service is up and running.
More advanced tests can be written by creating a Java client for the Web service, and then
using the client interfaces to call the MDM Server. Again, the RSA documentation
contains information about building Web Service Clients, but one approach is to:
1. Create a new Java project for your test code.
2. With the new project selected, choose File > New > Other... > Web Services >
Web Service Client.
3. Use the Browse button to choose the WSDL file that describes your service (in this
case ExampleModuleWS_HTTPRouter/WebContent/WEBINF/wsdl/ExampleModuleService.wsdl)
4. Verify the client type is Java proxy, and continue with the wizard.
Page 28 of 35
Figure 13: Creating a Web service client
Figure13.PNG
When the wizard completes, Java code will have been generated to enable you to call the
Web service. If you need to call more than one Web service (to call both the Party Web
service as well as the new addition, for example) then generate Web service client code for
each service in turn. The Party WSDL is located at
PartyWS_HTTPRouter/WebContent/WEB-INF/wsdl/PartyService.wsdl. While generating
the second Web service you may need to give RSA permission to overwrite some of the
generated files.
The example in Appendix A uses both the Party and ExampleModule Web services. It
calls into the Party Web service to find the ID of a party, and then creates a reminder for
that ID. If your MDM system does not contain any Party instances then you will need to
create instances before the search will return any results.
As with any Web service, if your services are not located at the URL contained in the
service definition then you will have to adapt the sample code to include the correct
service URL when using the locator class to create the service port object.
Page 29 of 35
Testing the addition using the service controller bean

This method of testing passes XML messages to the MDM Server by using the service
controller bean that is contained within the MDM Server. This test example runs as a Java
EE application client and uses JNDI to locate the controller bean.
To setup a new Java EE application client project, use the wizards in RSA. For this
example we created a new application client project and added it to a new EAR file.
In order to call the service controller, the EAR file needs to include the MDM Server
client jar and the application client needs to include a reference to the controller bean.
To import the MDM Client JAR perform the following steps:
1. Start the J2EE utility jar import. Choose File > Import > Java EE > J2EE Utility
Jar.
2. Check that you are adding the JAR file to the correct EAR, and select the option to
copy the utility jar into the EAR.
3. Click Next.
4. Browse to a directory that contains MDMClient.jar. One such directory is the lib
directory within the InstallVerification project. Choose MDMClient.jar
5. Click Finish.
One way to set up the EJB reference to the controller is to define it in the Deployment
Descriptor and the WebSphere Bindings deployment descriptor. If your application project
does not include these files then right click the project and use the Java EE context menu
to generate them.
1. Open the deployment descriptor for the application client project (applicationclient.xml).
2. Switch to the Design tab, and click Add..., then choose EJB reference and click
OK.
3. In the Details section, enter a name, such as ejb/MDMController, set the type to
Session, and set the home interface to
com.dwl.base.requestHandler.beans.DWLServiceControllerHome
4. Open the WebSphere bindings descriptor (ibm-application-bnd.xml).
5. Switch to the Design tab and click Add, then choose EJB reference and click
OK.
6. Enter the same name (ejb/MDMController), and set the binding name to
com/dwl/base/requestHandler/beans/DWLServiceController
7. Save and close both editors.
The example code in Appendix B shows how to perform the same simple test by passing
XML messages to the service controller. To run the test, set up a new RSA configuration
for running a WebSphere v7 application client, and tick the box to enable the client to
connect to the server.
Page 30 of 35
Figure 14: An RSA run configuration to run the XML test
Figure14.PNG
Appendix A: Web Services Test sample code

The following example demonstrates how to test the Reminder addition using Web
services.
Example 3: Web service test code

package test;
import java.util.Calendar;
import java.util.GregorianCalendar;
import java.util.List;
import javax.xml.datatype.DatatypeFactory;
import
import
import
import
com.ibm.xmlns.prod.websphere.wcc.common.intf.schema.Control;
com.ibm.xmlns.prod.websphere.wcc.party.intf.schema.PersonSearchResultsResponse;
com.ibm.xmlns.prod.websphere.wcc.party.schema.PersonSearch;
com.ibm.xmlns.prod.websphere.wcc.party.schema.PersonSearchResult;
Page 31 of 35
import
import
import
import
import
import
import
com.ibm.xmlns.prod.websphere.wcc.party.service.PartyService;
com.ibm.xmlns.prod.websphere.wcc.party.service.PartyService_Service;
com.ibm.mdm.examples.examplemodule.intf.schema.ReminderResponse;
com.ibm.mdm.examples.examplemodule.schema.PriorityType;
com.ibm.mdm.examples.examplemodule.schema.Reminder;
com.ibm.mdm.examples.examplemodule.service.ExampleModuleService;
com.ibm.mdm.examples.examplemodule.service.ExampleModuleService_Service;
public class SimpleAddReminder {

public static void main(String[] args) {
try {
// Search for all active people in the MDM Server
PersonSearch search = new PersonSearch();
search.setLastName("%");
search.setInquiryLevel(0);
search.setPartyFilter("ACTIVE");
// Find the Party web service and call it
PartyService_Service partyLocator = new PartyService_Service();
PartyService partyService = partyLocator.getPartyPort();
DatatypeFactory factory = DatatypeFactory.newInstance();
Control control = new Control();
control.setRequestId(101);
control.setRequesterName("cusadmin");
control.setRequesterLanguage(100);
PersonSearchResultsResponse searchResponse =
partyService.searchPerson(control, search);
String statusValue =
searchResponse.getStatus().getProcessingStatus().getValue();
System.out.println("Searched for people with response status: " +
statusValue);
// Find the first person in the result set
List<PersonSearchResult> results =
searchResponse.getSearchResult();
PersonSearchResult person = results.get(0);
// Create the reminder
Reminder reminder = new Reminder();
reminder.setRemindPartyId(person.getMatchedFields().getPartyId());
reminder.setRemindRecordedBy(person.getGivenNameOne() + " " +
person.getLastName());
reminder.setRemindDesc("A test reminder");
GregorianCalendar currentTime = (GregorianCalendar)
GregorianCalendar.getInstance();
reminder.setRecordedDtm(
factory.newXMLGregorianCalendar(currentTime));
// Set the prioriry
PriorityType priority = new PriorityType();
priority.setCode("2");
reminder.setPriorityTpCd(priority);
// Set the reminder for this time tomorrow
GregorianCalendar reminderTime = (GregorianCalendar)
Calendar.getInstance();
reminderTime.add(Calendar.DAY_OF_WEEK, 1);
reminder.setRemindDtm(
factory.newXMLGregorianCalendar(reminderTime));
// Find the web service for the addition and call it
ExampleModuleService_Service exampleLocator =
new ExampleModuleService_Service();
ExampleModuleService exampleService =
exampleLocator.getExampleModulePort();
control = new Control();
control.setRequestId(101);
Page 32 of 35
control.setRequesterName("cusadmin");
control.setRequesterLanguage(100);
ReminderResponse response =
exampleService.addReminder(control, reminder);
statusValue =
response.getStatus().getProcessingStatus().getValue();
System.out.println("Added reminder with response status: " +
statusValue);
} catch(Exception e) {
System.out.println("Caught exception");
e.printStackTrace(System.out);
}
}
}
Appendix B: Service controller sample code

The following example demonstrates how to test the Reminder addition using calls to the
service controller bean.
Example 4: Service controller test code

import
import
import
import
import
import
import
import
java.io.StringReader;
java.text.DateFormat;
java.text.SimpleDateFormat;
java.util.Calendar;
java.util.Date;
java.util.HashMap;
java.util.TimeZone;
java.util.Vector;
import
import
import
import
import
import
javax.naming.InitialContext;
javax.xml.parsers.DocumentBuilder;
javax.xml.parsers.DocumentBuilderFactory;
javax.xml.xpath.XPath;
javax.xml.xpath.XPathConstants;
javax.xml.xpath.XPathFactory;
import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.xml.sax.InputSource;
import
import
import
import
import
com.dwl.base.error.DWLError;
com.dwl.base.error.DWLStatus;
com.dwl.base.exception.DWLResponseException;
com.dwl.base.requestHandler.beans.DWLServiceController;
com.dwl.base.requestHandler.beans.DWLServiceControllerHome;
public class Main {

public static void main(String[] args) {
try {
InitialContext ic = new InitialContext();
Object homeStub = ic.lookup("java:comp/env/ejb/MDMController");
DWLServiceControllerHome home = (DWLServiceControllerHome)
javax.rmi.PortableRemoteObject.narrow(homeStub,
DWLServiceControllerHome.class);
DWLServiceController mdm = home.create();
String xmlResponse;
HashMap context = new HashMap();
Page 33 of 35
XPathFactory factory = XPathFactory.newInstance();

XPath xpath = factory.newXPath();
// Prepare an XML request that will search for people in the
// MDM Server
String searchPersonXML =
"<?xml version=\"1.0\"?>" +
"<TCRMService
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:noNamespaceSchemaLocation='ExampleHubRequest.xsd'>" +
"<RequestControl>" +
"<requestID>101</requestID>" +
"<DWLControl>" +
"<requesterName>cusadmin</requesterName>" +
"<requesterLanguage>100</requesterLanguage>" +
"</DWLControl>" +
"</RequestControl>" +
"<TCRMTx>" +
"<TCRMTxType>searchPerson</TCRMTxType>" +
"<TCRMTxObject>TCRMPersonSearchBObj</TCRMTxObject>" +
"<TCRMObject>" +
"<TCRMPersonSearchBObj>" +
"<LastName>%</LastName>" +
"<InquiryLevel>0</InquiryLevel>" +
"<PartyFilter>ACTIVE</PartyFilter>" +
"</TCRMPersonSearchBObj>" +
"</TCRMObject>" +
"</TCRMTx>" +
"</TCRMService>";
System.out.println("Sending xml:\n" + searchPersonXML);
xmlResponse = (String) mdm.processRequest(context,
searchPersonXML);
System.out.println("Response xml:\n" + xmlResponse);
// Find the id and name of the first person in the result
DocumentBuilderFactory builderFactory =
DocumentBuilderFactory.newInstance();
builderFactory.setNamespaceAware(true);
DocumentBuilder builder = builderFactory.newDocumentBuilder();
InputSource input = new InputSource(
new StringReader(xmlResponse));
Document domResponse = builder.parse(input);
String partyPath =
"/TCRMService/TxResponse/ResponseObject"+
"/TCRMPersonSearchResultBObj";
Node party = (Node) xpath.evaluate(partyPath, domResponse,
XPathConstants.NODE);
String partyId = xpath.evaluate("PartyId", party);
String partyName =
xpath.evaluate("GivenNameOne", party) + " " +
xpath.evaluate("LastName", party);
// Prepare an XML request to create a new reminder
Calendar reminderTime = Calendar.getInstance();
reminderTime.add(Calendar.DAY_OF_WEEK, 1);
DateFormat format =
new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
format.setTimeZone(TimeZone.getTimeZone("GMT"));
String now = format.format(new Date());
String reminderString =
format.format(reminderTime.getTime());
String reminderXML =
"<?xml version='1.0'?>" +
"<TCRMService
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:noNamespaceSchemaLocation='ExampleHubRequest.xsd'>" +
"<RequestControl>" +
"<requestID>101</requestID>" +
Page 34 of 35
"<DWLControl>" +
"<requesterName>cusadmin</requesterName>" +
"<requesterLanguage>100</requesterLanguage>" +
"</DWLControl>" +
"</RequestControl>" +
"<TCRMTx>" +
"<TCRMTxType>addReminder</TCRMTxType>" +
"<TCRMTxObject>ReminderBObj</TCRMTxObject>" +
"<TCRMObject>" +
"<ReminderBObj>" +
"<PriorityTpCdType>2</PriorityTpCdType>" +
"<RemindPartyId>" +
partyId +
"</RemindPartyId>" +
"<RemindRecordedBy>" +
partyName +
"</RemindRecordedBy>" +
"<RemindDtm>" +
reminderString +
"</RemindDtm>" +
"<RemindDesc>Test reminder</RemindDesc>" +
"<RecordedDtm>" + now + "</RecordedDtm>" +
"</ReminderBObj>" +
"</TCRMObject>" +
"</TCRMTx>" +
"</TCRMService>";
System.out.println("Sending xml:\n" + reminderXML);
xmlResponse = (String) mdm.processRequest(context, reminderXML);
System.out.println("Response xml:\n" + xmlResponse);
} catch(Exception e) {
System.out.println("Caught exception");
e.printStackTrace(System.out);
if(e instanceof DWLResponseException) {
DWLResponseException dwl = (DWLResponseException) e;
DWLStatus status = dwl.getStatus();
if(status != null) {
Vector<DWLError> errors = status.getDwlErrorGroup();
for(DWLError error : errors) {
System.out.println(error.getDetail());
System.out.println(error.getErrorMessage());
}
}
}
}
}
}
Page 35 of 35

White Paper

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

White Paper

Încărcat de

Drepturi de autor:

Formate disponibile

Extending IBM InfoSphere Master Data Management Server

using the MDM Workbench

Copyright International Business Machines Corporation 2009, 2010

Copyright International Business Machines Corporation 2009, 2010

Setting up your development environment

IBM Rational Application Developer for WebSphere Software (RAD) 7.5.4

Setting up the Development Environment

Preparing to run the Setup Wizard

Running the Setup Wizard

Copyright International Business Machines Corporation 2009, 2010

Figure 1: The Development and Test Environment wizard

Copyright International Business Machines Corporation 2009, 2010

Copyright International Business Machines Corporation 2009, 2010

MDM Configuration and Deployment

Copyright International Business Machines Corporation 2009, 2010

Resolving problems that occur during setup and configuration

Setup Wizard Task Descriptions

Importing the MDM Resources

Import Application Projects into Workspace

Copyright International Business Machines Corporation 2009, 2010

The task Customize Configuration files modifies property files in the

Modify the Web Service Configuration

Configuring the WebSphere Application Server

Backup WebSphere profile

Copyright International Business Machines Corporation 2009, 2010

Figure 5: Verifying the WAS classpath

Creating the database

Create an Application Database

Copyright International Business Machines Corporation 2009, 2010

Deploying the MDM EAR

Deploying the MDM Configuration

Verifying the Install

Import Installation Verification project

Copyright International Business Machines Corporation 2009, 2010

Restoring the setup tool

Restore the Development Environment Setup Tool

Creating a new Hub Module

Copyright International Business Machines Corporation 2009, 2010

Figure 6: Hub Module Project Wizard

Additionally, if an application.mdmxmi file does not already exist, it is created in the

Figure 7: Code generation options within the application module

By running a wizard (New> Other>Data Addition/Data Extension)

Copyright International Business Machines Corporation 2009, 2010

Table 1: Contents of the Reminder addition

Copyright International Business Machines Corporation 2009, 2010

Figure 8: The model editor showing the new Reminder entity

Copyright International Business Machines Corporation 2009, 2010

1. Right click Reminder and choose New > Get Record.

Figure 9: The complete module model

ExampleModuleEJB - the controllers EJB session bean

Copyright International Business Machines Corporation 2009, 2010

ExampleModuleWS_HTTPRouter - the WSDL and XSD files for the Web

Copyright International Business Machines Corporation 2009, 2010

Configuring the domain

Adding an Entity Extension

Copyright International Business Machines Corporation 2009, 2010

Figure 10: Creating a hub module project to contain the extension

Copyright International Business Machines Corporation 2009, 2010

Copyright International Business Machines Corporation 2009, 2010

Figure 12: The ExtendedPerson entity extension

Example 1: Incomplete SQL statement

Copyright International Business Machines Corporation 2009, 2010

In this MDM_TODO, find the appropriate DWLTABLE_TP_CD of Person. The entry

Example 2: Complete SQL statement