My output failed! Where do I start?

When output fails for a map, there can be several causes:

  • a problem with the Output Generator
  • a problem with the output type (OT plugin) you are using
  • a problem with your content

The output failure could be limited to one of these categories or it could be a combination of categories.

Follow this troubleshooting process to narrow down the cause of the output failure. It can be time-consuming but it is the same process that IXIASOFT Support follows when diagnosing output problems. By following this process internally, you might find the solution more quickly than IXIASOFT Support because you do not need to exchange files and details of the problem.

This troubleshooting process applies to a complete build failure...no output at all. If you get output but it's formatted strangely, that is almost definitely an issue with your custom plugin. The IXIASOFT CCMS has no effect whatsoever on output formatting. The CCMS merely stores your content, and passes it to the Output Generator, which in turn passes it to the Open Toolkit. The Open Toolkit plugin you are using is completely responsible for formatting the output.

Test One (Initial Failure): Try to output your map using your custom output type. Was it successful?

  • Yes: You're all set!
  • No: There is a problem with the Output Generator, your custom plugin, or your content. Go to Test Two.

Test Two (OutGen, plugin, or content?): Try to output your map using an equivalent generic output type (dita2pdf, dita2xhtml, etc.). Was it successful?

  • Yes: The Output Generator is working correctly but there is most likely a problem with your custom OT plugin or your content. Go to Test Three.
  • No: There is most likely a problem with the Output Generator or your content. Go to Test Four.

Test Three (Plugin or content): Try to output a different map using your custom output type. Was it successful?

Test Four (OutGen or content?): Try to output a different map using an equivalent generic output type (dita2pdf, dita2xhtml, etc.). Was it successful?

Troubleshooting Your Content

IXIASOFT recommends that you keep a "benchmark" map in your content store--one that you know builds successfully using your custom OT plugins and that you never change. (Ideally, it should not share content with other maps so that again--it never changes.) When output for a production map fails, you can use the benchmark map for comparison. If the benchmark map output succeeds under the same conditions that the production map fails under, you can be pretty sure that the problem lies in the content or structure of the production map. The benchmark map should be robust enough to be a meaningful test and should include the DITA features that you regularly use.

If you create smaller maps and combine them into larger maps, you have a troubleshooting advantage. For example, say a build for BookmapA fails. BookmapA references 10 smaller maps as chapters. You can try building each of the 10 chapter maps individually until you find the specific map that is causing the problem. If that chapter map in turn references several sub-maps, again--you can build each of the sub-maps individually until you find the one that is causing the problem. If each individual map referenced by BookmapA builds successfully, you know the problem must be in BookmapA itself--perhaps its structure is incorrect or some piece of metadata is not being used correctly by your plugin.

If you don't create smaller sub-maps but instead work with very large "flat" maps (maps that reference only topics, not any sub-maps), troubleshooting is going to be more tedious for you.

Once you have narrowed the problem to a specific map, you can begin finding the specific topic or topics that are causing the problem. This can also be a tedious process. Here is an illustration of a simple process-of-elimination.

1 You've gone through the other troubleshooting steps and have determined that the problem is in fact with your map. The build fails on the complete map.
2 You comment out topics 6-10 in the map. The build still fails, suggesting the problem is with topics 1-5.
3 You comment out topics 1-5 in the map. The build succeeds, confirming the problem is with topics 1-5.
4 You narrow the scope and comment out only topics 1-3 in the map. The build succeeds, confirming the problem is with topics 1-3.
5 You narrow the scope further and comment out only topics 1-2 in the map. The build succeeds, confirming either topic 1 or topic 2 is the problem.
6 You comment out only topic 1 in the map. The build fails, suggesting that topic 2 is the problem.
7 You comment out only topic 2 in the map. The build succeeds, confirming that topic 2 is the problem.

Obviously, process-of-eliminations can be much more complex than this example. You might have a number of topics that are problematic, scattered throughout the map. In such cases, you might have to begin by commenting out all topics and re-introducing them one at a time until you identify them all. For this reason, using several smaller maps rather than one large map--as mentioned above--can make your troubleshooting process much simpler.

Troubleshooting the Output Generator

Some potential issues with the Output Generator include:

  • The Output Generator service has stopped
  • There is some connection problem within your network
  • You are not connected to the correct instance of the Output Generator
  • You are using an incompatible Java version
  • Your custom DTD plugin is not installed in the OT within the Output Generator so it does not recognize your content
  • You have not properly integrated your custom plugins into the OT within the Output Generator
  • There are errors in one or more of your Output Generator configuration files (such as outputtypes.xml, preprocessors.xml, conductor_client.xml, etc.)

Check each of these items. You might need the help of your IT group if you don't have direct access to the Output Generator machine.

If none of the above checks resolves the problem, contact IXIASOFT Support.

Troubleshooting an Open Toolkit plugin

Troubleshooting plugins can be complex, because the problem could lie in so many different areas. The problem could be as simple as a typo somewhere in a template (a missing bracket, parenthesis, comma, closing tag, etc.), or it could be an issue of compatibility between your plugin and the version of the OT you are using, or it could be any number of other things.

If you aren't familiar with plugin troubleshooting, or the original creator of the plugin is not available to help, contact IXIASOFT Support for assistance.