There are a couple of new questions on the MDM Workbench FAQ which I think it's worth drawing attention to. Making sure you use short and simple install and workbench directory names from the start can save a few headaches later in the set-up process.

On the subject of the FAQ, don't forget that anyone in the MDM Developers group can edit it, so if you have any other tips to share, please do.

What directory names should I use to avoid problems?

There are a number of issues that you may encounter related to the
directories used to install software, as well as your workspace
location. For example:

Long path names

Directory names which contain special characters, such as the $ symbol
This can be a particular issue on Windows 7 where the default install location may include '(86)'

To avoid these problems, you should use short, simple, directory names. For example:

C:\IBM\SDP

C:\IBM\MDMWorkspace

Why does testing the database connection cause an error?

You may see the following error when using the "Test Connection" button:

Input Error

... db2ValidateDBName.log (The system cannot find the file specified).

This problem can occur for a couple of reasons: either the RSA
install directory contains special characters (see details above) or the system path environment variable has exceeded the Windows limit.
If the directory name is not the problem, check whether 'db2' can be
found on the path using the Windows Command Prompt. You will see the
following message if the DB2 path entries are not being picked up
correctly:

'db2' is not recognized as an internal or external command,operable program or batch file.

You can work round the Windows environment variable limit by moving
the DB2 path entries to the front of the system path before re-starting
RSA and trying the setup again.

Before using MDM web services in a development environment you need to disable web service security. This is because the web services are configured with security enabled by default, while the test server has security turned off. You can disable web service security manually by modifying relevant ibm-webservices-ext.xmi files, as described on the MDM Workbench FAQ, however a colleague recently sent me a really useful Ant target to automate the process. It's obviously important to enable security again before deploying an MDM application in a production environment, so I've included a target to reverse the process as well:

<fail unless="workspace.root.available"> Directory '${workspace.root}' does not exist. Run Ant build using the provided launch configuration, or make sure the 'workspace.root' property is set to the workspace location. </fail> </target>

You can run this build using the Run As > Ant Build... context menu option in the workbench. You need to provide the path to your workspace using the workspace.root property, and there is a ${workspace_loc} variable provided by the launch configuration which you can use, as shown below.

I've uploaded the example build.xml file and an associated launch configuration to developerWorks. These should work if you import them in to the CustomerResources project in your workspace. Make sure the Ant build file is called build.xml, then right click on the DisableSecurity.launch file and select Run As > DisableSecurity from the context menu. You should see the build results in the Console view, showing which files were modified if all goes well.

Thanks to Pramod for adding details about disabling web service security to the FAQ, and thanks to Barry and Tony for the original build script.

The second is the new Wiki that the FAQ is on! I hope the FAQ is just the first of many more pages on the MDM Developers Wiki.

You can see the current FAQ below and, if there's anything missing, it's easy to add more: anyone in the MDM Developers group can edit the Wiki. I plan to post excerpts from the FAQ here as it gets updated, to make it easier to find via search engines, and hopefully to provide a nicer way to subscribe to updates.

Platform support and prerequisite software

Can I run MDM Workbench on Linux ?

MDM Workbench is only supported on Windows currently. You may be
able to install MDM Workbench on RSA on Linux, and parts of the tool
would probably work fine, but the Development and Test Environment
wizard will not work.

The Development and Test Environment wizard (often called DEST) is
used to install MDM Server on the RSA WebSphere test server, create a
database and set up your workspace ready for development. MDM Server is
not supported on Windows as a production environment so there is no
Windows version of MDM Server. The Websphere AIX version of MDM Server
can be installed on Windows using DEST.

Can I run MDM Workbench on Windows 7 ?

We have not tested MDM Workbench on Windows 7. However we are not
aware of any problems with MDM Workbench 9.0.x on Windows 7 (with
WebSphere 7 and DB2). MDM Workbench 8.5 requires RSA 7.0 which is not
supported on Windows 7. WAS 6.1 test server is also not supported on
Windows 7.

Generating code

Why is there a problem setting the runtime for new projects?

To generate web services the workbench requires the Tools for WebSphere Application Server, version 6.1
feature to be installed in RAD/RSA. You must have version 6.1 of the
server development tools installed, even if your target runtime is
WebSphere Application Server 7, otherwise the following error will occur
when generating code:

com.ibm.mdm.tools.models.core.codegen.CodeGenException: Failed to set runtime for new projects: no runtime is associated with the EAR

Errors when running transactions on MDM Server

If you see this error in the WebSphere log when running transactions
on MDM Server 8.5, then you have installed the WebSphere 6.1 Web
Services Feature Pack. This feature pack is not compatible with MDM
Server 8.5.

In a development environment, the feature pack is installed as an
optional feature in Installation Manager. Use Installation Manager to
uninstall the WebSphere 6.1 test server, then re-install without the Web
Services Feature Pack.

Exception_TopologySession_ApplicationNotFound

If you see this error in the WebSphere log when running transactions
on MDM Server, then the server is unable to load configuration
settings. The server configuration is stored in the database tables
configelement, appsoftware, appdeployment, and appinstance.

First check if the table configelement is empty: if it is, then you
need to deploy the server configuration. In a development environment,
run the Development and Test Environment wizard task "Deploy
configuration to WebSphere profile".

If this does not work, then use the WebSphere admin console to check
that the server data sources are defined. If the data sources are not
defined, then run the Development and Test Environment wizard task
"Configure WebSphere profile". If the data sources are defined, test the
connections and address any problems before proceeding.

If there is content in the configelement table, then check the
workspace file CustomerResources/properties/config/bootstrap.properties.
The property application.manifest.location should be set to the path to
the MDM application MANIFEST.MF file, in your workspace. The property
deployment.name must match the value in the database table
appdeployment.

Common causes of problems

WebSphere application server classpath

In a development environment, the server properties and XSD files
are loaded from the CustomerResources project in your workspace. To
arrange this, the Development and Test Environment wizard adds the
CustomerResources folders to the WebSphere server classpath. If the
classpath is pointing to the wrong locations, the server will behave
strangely (the exact symptoms will depend on your circumstances).

This can commonly occur if you have tried to copy, move or rename
your workspace on the file system or have set up a new development
environment re-using an existing WebSphere profile.

To check the server classpath, start the WebSphere admin console.
Select the server. On the right hand side of the page, expand Java and
Process Management and select Process Definition. Select Java Virtual
Machine. You can view and edit the classpath definition in this panel.

To avoid this problem arising: do not copy, move or rename a
workspace on your file system and when setting up a development
environment, create a new WebSphere profile and make it the default
profile.

Testing the database connection in the Development and Test Environment wizard can cause Rational Software Architect to stop responding. This is occurs when one of the scripts running under the covers picks up the wrong find command. The problem is typically because something like MKS Toolkit is installed, which includes its own version of the find command. You may not have installed MKS Toolkit manually, for example DataStage Designer installs MKS Toolkit automatically. The simplest way to check if this is the case, is to run the find command directly and check the output. You can use the start > Run... menu option to open a Command Prompt; type cmd in the Open box and press OK. You should see the following output when you run the find command:

If you see a different response, the Development and Test Environment wizard will fail when you try to test the database connection. To get round this problem you should modify the PATH environment variable so that the folder containing the default Windows find command is before any others. The article, "How To Manage Environment Variables in Windows XP" describes how to modify environment variables on Windows XP. The correct find command is in the same folder as cmd.exe, which you used above. This folder will already be in the PATH, but you need to move it to the beginning so that is checked before any of the other folders. This change will cause problems for any software relying on the the PATH to locate the alternative find command, so I recommend taking a copy of the PATH setting before you change it, then restoring the original settings after you have successfully set up your development environment.