White Paper

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


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


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:


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


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.


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.


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.


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.


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.


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.


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.


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


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).


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.


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:


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.


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


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


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.


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.


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.


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:


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');


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


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


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:


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.


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.


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.


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;


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);


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();


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" +


"" + "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()); } } } } } }


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

Documents

White Paper