-
Extending IBM InfoSphere Master Data Management Server
using the MDM Workbench Tony Garrard ([email protected]) and
Matt Lovett ([email protected]) 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
Copyright International Business Machines Corporation 2009, 2010
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
Copyright International Business Machines Corporation 2009, 2010
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:
Copyright International Business Machines Corporation 2009, 2010
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
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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. Extracts the MDM application and resources into the specified
unpack location. 2. Imports the MDM EAR and the EAR manifest file
into the workspace. 3. Updates the classpath settings for the MDM
projects. 4. 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.
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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
Copyright International Business Machines Corporation 2009, 2010
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).
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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:
Copyright International Business Machines Corporation 2009, 2010
Page 16 of 35
-
Table 1: Contents of the Reminder addition Name Type Description
ReminderpkId Long The primary key of the new
table / addition. (In the model editor, check that the primary
key option is selected.)
priorityTpCd Type Code A type code reference to the PriorityType
code table (located in the DWLBusinessServices module, underneath
the Task folder).
remindPartyId Reference Reference to the Party entity (located
in the Party module). This is the association between the Reminder
and the Party that should be reminded.
remindRecordedBy String The name of the user that recorded the
reminder.
remindDtm TimeStamp The date on which the reminder is to
happen.
remindDesc String The description of the reminder.
recordedDtm TimeStamp 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.
Copyright International Business Machines Corporation 2009, 2010
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
Copyright International Business Machines Corporation 2009, 2010
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
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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:
Copyright International Business Machines Corporation 2009, 2010
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');
Copyright International Business Machines Corporation 2009, 2010
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 Files Comment MDM META-INF/application.xml
.project
.settings/org.eclipse.wst.common.component
Updated when new modules are added to the MDM application
DWLCommonServicesEJB ejbModule/META-INF/ejb-jar.xml Updated
Copyright International Business Machines Corporation 2009, 2010
Page 25 of 35
-
ejbModule/META-INF/ibm-ejb-jar-bnd.xmi when a new controller EJB
is added
X_EJB ejbModule/META-INF/MANIFEST.MF Updated to add dependency
to extension modules
X_WS build/mapping.properties build/was_jaxrpc_tdjava.properties
build/wsgen.xml
Used for code generation, no need to save in source code
repository
X_WS .classpath Updated to adjust the classpath for the
module
X_WS src/*ext/to Java classes Generated classes for Web
services
X_WS src/*_Helper, _Deser, _Ser Java classes Web services
deployment code that does not need to be saved in the source code
repository
X_WS_HTTPRouter WebContent/WEB-INF/wsdl/Extensions.xsd
WebContent/WEB-INF/wsdl/*Ext.xsd
Web service schema files for data extensions
X_WSEJB ejbModule/META-INF/MANIFEST.MF Updated to add dependency
to extension WS modules
X_WSEJB ejbModule/META-INF/*mapping.xml Web service type mapping
files updated to include data extension
Copyright International Business Machines Corporation 2009, 2010
Page 26 of 35
-
type mappings
X_WSEJB ejbModule/META-INF/wsdl/Extensions.xsd
ejbModule/META-INF/wsdl/*Ext.xsd
Web service schema files for data extensions
X_WSEJB mdmgen_backups 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:
Copyright International Business Machines Corporation 2009, 2010
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/WEB-INF/wsdl/ExampleModuleService.wsdl)
4. Verify the client type is Java proxy, and continue with the
wizard.
Copyright International Business Machines Corporation 2009, 2010
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.
Copyright International Business Machines Corporation 2009, 2010
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 (application-client.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.
Copyright International Business Machines Corporation 2009, 2010
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
com.ibm.xmlns.prod.websphere.wcc.common.intf.schema.Control; import
com.ibm.xmlns.prod.websphere.wcc.party.intf.schema.PersonSearchResultsResponse;
import com.ibm.xmlns.prod.websphere.wcc.party.schema.PersonSearch;
import
com.ibm.xmlns.prod.websphere.wcc.party.schema.PersonSearchResult;
Copyright International Business Machines Corporation 2009, 2010
Page 31 of 35
-
import
com.ibm.xmlns.prod.websphere.wcc.party.service.PartyService; import
com.ibm.xmlns.prod.websphere.wcc.party.service.PartyService_Service;
import
com.ibm.mdm.examples.examplemodule.intf.schema.ReminderResponse;
import com.ibm.mdm.examples.examplemodule.schema.PriorityType;
import com.ibm.mdm.examples.examplemodule.schema.Reminder; import
com.ibm.mdm.examples.examplemodule.service.ExampleModuleService;
import
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
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);
Copyright International Business Machines Corporation 2009, 2010
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
java.io.StringReader; import java.text.DateFormat; import
java.text.SimpleDateFormat; import java.util.Calendar; import
java.util.Date; import java.util.HashMap; import
java.util.TimeZone; import java.util.Vector; import
javax.naming.InitialContext; import
javax.xml.parsers.DocumentBuilder; import
javax.xml.parsers.DocumentBuilderFactory; import
javax.xml.xpath.XPath; import javax.xml.xpath.XPathConstants;
import javax.xml.xpath.XPathFactory; import org.w3c.dom.Document;
import org.w3c.dom.Node; import org.xml.sax.InputSource; import
com.dwl.base.error.DWLError; import com.dwl.base.error.DWLStatus;
import com.dwl.base.exception.DWLResponseException; import
com.dwl.base.requestHandler.beans.DWLServiceController; import
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();
Copyright International Business Machines Corporation 2009, 2010
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 = "" + "" + "" +
"101" + "" + "cusadmin" + "100" + "" + "" + "" + "searchPerson" +
"TCRMPersonSearchBObj" + "" + "" + "%" + "0" + "ACTIVE" + "" + "" +
"" + ""; 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 = "" + ""
+ "" + "101" +
Copyright International Business Machines Corporation 2009, 2010
Page 34 of 35
-
"" + "cusadmin" + "100" + "" + "" + "" + "addReminder" +
"ReminderBObj" + "" + "" + "2" + "" + partyId + "" + "" + partyName
+ "" + "" + reminderString + "" + "Test reminder" + "" + now + "" +
"" + "" + "" + ""; 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 errors = status.getDwlErrorGroup();
for(DWLError error : errors) {
System.out.println(error.getDetail());
System.out.println(error.getErrorMessage()); } } } } } }
Copyright International Business Machines Corporation 2009, 2010
Page 35 of 35
TrademarksIntroductionPrerequisitesAdditional References
Setting up the Development EnvironmentPreparing to run the Setup
WizardRunning the Setup WizardFigure 1: The Development and Test
Environment wizard
WebSphere ConfigurationFigure 2: WebSphere Configuration
MDM Configuration and DeploymentFigure 3: Application
Configuration and Deployment
Database InformationFigure 4: Database Information
Resolving problems that occur during setup and configuration
Setup Wizard Task DescriptionsImporting the MDM ResourcesModify
the Web Service ConfigurationConfiguring the WebSphere Application
ServerFigure 5: Verifying the WAS classpath
Creating the databaseDeploying the MDM EARDeploying the MDM
ConfigurationVerifying the InstallRestoring the setup tool
Creating a new Hub ModuleFigure 6: Hub Module Project
WizardFigure 7: Code generation options within the application
mod
Creating an AdditionTable 1: Contents of the Reminder
additionFigure 8: The model editor showing the new Reminder
entityFigure 9: The complete module model
Code GenerationMerging CustomerResourcesConfiguring the
domain
Adding an Entity ExtensionFigure 10: Creating a hub module
project to contain the exteFigure 11: Setting the 'Start Id' for
the new hub moduleFigure 12: The ExtendedPerson entity
extensionExample 1: Incomplete SQL statementExample 2: Complete SQL
statement
Sharing the codeSharing the workspaceTable 2: Workspace files
that will be modified when extendin
Sharing the model
Testing the ExtensionsTesting the addition using Web
ServicesFigure 13: Creating a Web service client
Testing the addition using the service controller beanFigure 14:
An RSA run configuration to run the XML test
Appendix A: Web Services Test sample codeExample 3: Web service
test code
Appendix B: Service controller sample codeExample 4: Service
controller test code