Troubleshooting
Problems generally fall into a handful of classes that are discussed in some detail below.
Note: IBM Support does not support DCM, though they will accept a PMR if a problem exists with an underlying SOMA request made by DCM, provided the request is correctly formed.
These types of issues are reflected in complaints about failing to find some Ant-related or Xalan jar file. Check over the Quick Start page to be certain that you've covered all the bases and run the initial test.
Is what you are trying to accomplish correctly specified, or does this represent a bug in DCM or DataPower? The first thing to determine is whether the same operation works when done through the DP browser interface. For example, if an import operation is failing then do that import manually to verify that it works.
Many of the DCM operations correspond one-to-one with operations that can be done manually. Some operations, though, such as the *-from-def operations, do multiple SOMA operations under the covers.
(One of the things that you may discover during this process is that you are trying to use a SOMA enhancement that is not yet supported by DCM. There is a long-term project under way to avoid any of these issues but it is not yet in place.)
The properties defined for each operation are critical since DCM is basically a big Ant build file. The dumpinput="true" property is useful for determining whether the properties being used by DCM are what you think that they are. You define properties at a high level (e.g. the command line or property files) and those properties percolate downward through Ant, XSLT, and Java. The dumpinput="true" property causes the innermost Java code, where the SOMA calls are made, to print out the (potentially modified) properties.
There is a dumpoutput="true" property that exposes the SOMA requests and responses by printing them to the console, usually, but it has been superceded by a better mechanism.
The optional capture.soma.dir="..." property causes the underlying Java code to write each SOMA request and response to files in the specified directory. The requests can be replayed using a tool such as curl and they can be validated against xml-mgmt.wsdl if you have a tool capable of doing that. The responses may reveal something about the reason for failure.
The most common failure response is "Authentication failure" which may be related to the userid/password that you specified. If you aren't certain that the supplied userid/password has the required permissions to do that operation then try using admin/xxx to see whether that resolves the problem. If you are certain that the userid/password has sufficient permission then this response often indicates that the target domain doesn't exist.
Other failures, such as the failure to delete a domain because a user is currently logged into it, are more obvious.
DCM, for all its capabilities, is a fairly shallow piece of code. Each operation in deploy.ant.xml invokes one or more macrodefs in dcm-taskdefs.ant.xml which in turn invoke stylesheets and Java code to generate one or more SOMA requests, and to process DataPower's responses to those requests. Adding <echo> elements to Ant scripting, <xsl:message> elements to stylesheets, and System.out.println() to .java files is pretty simple. The build files and Java code are all pretty straightforward while the stylesheets can be a little more daunting. Don't hesitate to ask for a little help if you end up working through the stylesheets at some point.
DCM bugs do show up now and then and there has been one instance where DataPower was not correctly handling a SOMA request (that led to a PMR).
Ant offers two arguments to help debug the tool, the Version and Debug flags. These two flags, when set on the command, can provide some in depth error reporting about the runtime logic. This is recommended if you are interested in the DCM DCM xml code. As this testing can be done relatively easily through a terminal, it has not been added to the plug-in.