Notes from a small field

If you have set up an MDM Server development environment, you should have noticed that you have actually already run some MDM transactions. The Validate MDM Installation step in the MDM Development and Test Environment (DEST) wizard runs an addContract and two addPerson transactions to verify everything is configured and working. In addition to the first two options, you can actually use the DEST wizard to run your own transactions. Here’s how.

Option 3: InstallVerification Project

This is probably the simplest of all the options for testing an MDM transaction. The Validate MDM Installation step of the DEST wizard will run any transactions in the xml folder of the InstallVerification project. The results are placed in the xml/response folder in the same project but you will need to refresh the contents of the project to see the new files. Follow these steps for an easy way to try out this option:

• Copy one of the existing files in the xml folder of the InstallVerification project and give it a new name, e.g. testTCRMaddperson.xml
• Edit the new file and change some of the values. I changed the address, identification number and name for example
• Start the DEST wizard, select just the Validate MDM Installation step, click next, then finish
• Right click on the InstallVerification project and select Refresh
• Open the appropriate response file in the xml/response folder, for example ResponsetestTCRMaddPerson.xml, and check the results

Tip: don’t forget that DEST runs all the transactions in the xml folder so you may wish to clear it out now and then.

After setting up an MDM Server development environment you will probably want to start running transactions sooner or later to test things out. Having recently needed to do just that and, by coincidence, following a question about the subject, here are a couple of simple options to get started quickly:

Option 1: Web Service Adapter Sample Client

Using the web service adapter sample client lets you submit MDM XML transactions from a simple web page. The web service adapter is a legacy part of the product which simply wraps up traditional MDM transaction requests in a web service request but it’s ideal for running quick tests.

The developer environment set up process leaves an unpacked set of MDM files behind, including WCCWSAdapter.war and WCCWSAdapterSampleClient.war files. For example on my machine, the files are in C:\MDM\UNPACK\WCC\legacyAdapters\WebServicesAdapter. (You set the location to unpack the files in to on the set up wizard, which you can re-run if you cleaned up afterwards.)

I imported the war files into my workspace, configured the webservices.properties settings in WCCWSAdapter/WebContent/WEB-INF/classes and deployed everything with the MDM EAR.

Once deployed, you can open the following URL to submit transactions:

http://localhost:9080/WCCWSAdapterSampleClient/sample/WsDWLServiceControllerAdapterProxy/TestClient.jsp

Set the end point to http://localhost:9080/WCCWSAdapter/services/WsDWLServiceControllerAdapter before submitting the first request.

Option 2: Test with Web Services Explorer

In RSA you can right click on any .wsdl file and select ‘Web Services > Test with Web Services Explorer’, which includes the .wsdl files in the MDM *WSEJB projects.

Before testing the MDM web services you’ll need to modify some .xmi files since, by default, security for the test environment server will be off, but the web services will be configured for security being on. For example, if you want to run Party web services, look in the PartyWSEJB/ejbModule/META-INF/ directory. You should see ibm-webservices-bnd.xmi and ibm-webservices-ext.xmi files, plus *_SecurityDisabled.xmi and *_SecurityEnabled.xmi versions of the same files. Copy the *_SecurityDisabled.xmi versions over the the plain *.xmi files and redeploy the MDM application.

Finally, open your chosen .wsdl file and set the end point to the test server. For example I opened PartyWSEJB/ejbModule/META-INF/wsdl/PartyService.wsdl and set the PartyPort address to http://localhost:9080/PartyWS_HTTPRouter/services/PartyPort

Then you’re ready to right click on the .wsdl file and select ‘Web Services > Test with Web Services Explorer’.

Those aren’t the only ways to run MDM transactions, but I’ve found them really useful for quick and dirty tests. For a more in depth look at using the web services interface, check out the Configure and invoke Web services for WebSphere Customer Center developerWorks tutorial. I hope to cover more options in the furtue, for example using the messaging adapter, but in the mean time I’d be very interested to hear of any other articles out there for submitting requests.

Update: see also Option 3 for using the InstallVerification project to run transactions (27 August 2008)

There is now an MDM Workbench white paper which covers development environment set up, and continues with the subsequent tasks required for a complete MDM Server extension.

So you’ve got your brand new Master Data Management Server and you want to get down to doing some development on it. Here are the steps I use to get up and running. (I’ll update them if I discover any other useful tips, or glaring errors!)

You will need:

• Prereq software installed*
• MDMWorkbench.zip and MDM80_WAS_AIX.tar.gz files from MDM Server

* Make sure you do not have the WebSphere Application Server feature pack for web services installed in RSA. If you do have the feature pack installed, you will need to use the IBM Installation Manager to uninstall the whole WebSphere Application Server version 6.1 runtime, not just the feature pack, and reinstall the runtime without the feature pack selected. The DB2 prereq (DB2 Enterprise Edition 9.1 fixpack 3a) is also very important. See below for log locations if the MDM database is not created properly.

Preparation:

The first part of this preparation covers clearing up from previous attempts to set up an MDM development environment, which you can skip if you are using a machine for the first time.

• Drop any existing MDM database using the DB2 Control Center
• Delete all WebSphere profiles using manageProfiles -deleteAll in <SDP70_INSTALL>\runtimes\base_v61\bin
• Delete directories left behind by the profile delete, by default in <SDP70_INSTALL>\runtimes\base_v61\profiles
• Use the following command to create a new WebSphere profile, replacing <PLACEHOLDERS> with the correct values for your system (I use localhost for <HOSTNAME> and you can find out your <MACHINE_NAME> by running echo %COMPUTERNAME% in a Command Prompt window):

manageProfiles -create -winserviceCheck false -omitAction defaultAppDeployAndConfig -templatePath "<SDP70_INSTALL>\runtimes\base_v61\profileTemplates\default" -profilePath "<SDP70_INSTALL>\runtimes\base_v61\profiles\MdmDev01" -nodeName <MACHINE_NAME>Node01 -cellName <MACHINE_NAME>Node01Cell -enableAdminSecurity false -profileName MdmDev01 -hostName <HOSTNAME> -isDeveloperServer

• Start RSA and create a new workspace with a short path length, for example, C:\ibm\mdm. This is important because long path lengths can cause problems when importing EAR files in to RSA
• (If you are not prompted to choose a workspace location when starting RSA, use the File > Switch Workspace… menu option after RSA has started.)
• Open the ‘J2EE’ perspective and enable J2EE capability if prompted
• Open the ‘Servers’ view
• If the server is not already shown, right click in the ‘Servers’ view, choose New > Server, and enter details for the WebSphere 6.1 server1 created with the profile earlier
• Right click the server and choose Open
• In the ‘Publishing’ settings, select the ‘Run server with resources on Server’
• Open the Window menu and choose Preferences… Set the default JRE for new Java projects to ‘WebSphere v6.1 JRE’ on the Java/Installed JREs page.
• Install the MDM Workbench if you have not already done so.

Using the Developer Environment Setup Tool (DEST):

To open the DEST wizard open the File menu and choose New > Other… then filter for ‘MDM’ and pick ‘MDM Development and Test Environment’

When using the DEST wizard, double check all the values it asks for. The defaults may not be correct for your system and the values are not validated. For example, if the database home is wrong or does not exist, you will only find out when errors occur later.

• Start the DEST wizard and run the last step (‘Restore the MDM Development Environment Setup Tool’) on its own. This is not strictly necessary, especially if you haven’t run the wizard before, but best to be on the safe side!
• Start the DEST wizard again and run the first 5 steps (up to and including ‘Create an MDM Server Database’)
• Fill in all the requested values to match your system, including the name of the profile you created earlier. Note: the ‘MDM distribution file’ it asks for is the ‘MDM80_WAS_AIX.tar.gz’ file
• When the tasks have been completed, test the data sources that have been configured using the WebSphere administrative console**
• Close the administration console and restart the server (this is required to complete SIB configuration)
• Start the DEST Wizard again and run the remaining steps up to and including ‘Validate MDM Installation’
• When the tasks have finished, refresh the ‘xml’ folder in the ‘InstallVerification’ project and check the responses from MDM.

If the responses look good, you’re ready to start using the MDM development tools! That’s something for another post though.

** To check the data source settings:

• Right click the server in the ‘Servers’ view and choose ‘Run administrative console’
• Open Resources > JDBC > Data sources in the navigation pane
• Check the driver type is set to ‘4′ (not ‘,4′) in the DWLConfig, DWLCustomer and EventManager data sources
• Use the ‘Test Connection’ option to double check all is well

Where to look if things go wrong:

As well as the usual WebSphere logs, you can find MDM specific logs in <RSA_WORKSPACE_LOCATION>\logs, i.e. under the same directory as all the projects in your workbench.

Logs from the ‘Create an MDM Server Database’ step can be found under the MDMDatabase project in the RSA workspace . Look for the CM and CUST directories under WCC/DB2/Standard/ddl (you may need to refresh before the log files appear in the workspace).

Another good thing to check is the CONFIGELEMENT table; if it does not contain any data, the ‘Deploy MDM Server Configuration to WebSphere Profile’ step failed. Check the ManagementAgent.log and ManagementConsole.log files in <RSA_WORKSPACE_LOCATION>\logs.

Update: If you want to try running some MDM transactions after setting up the development environment, here’s how. (14 July 2008)

Update: Added hints for <MACHINE_NAME> and <HOSTNAME> placeholders. (22 August 2008)

Update: Added link to new white paper. (27 May 2009)