Troubleshooting Heretto

Important: This topic is (mostly?) obsolete. Most of these tips apply to the old publishing system.

Here are some tips for troubleshooting problems in Heretto.

Finding bad cross references

Sometimes Heretto reports a document as having one or more bad cross references. If you cannot find them in the WYSIWYG editor, switch to source (XML) and search for 'BAD-REF'. When you find it in an <xref>, delete everything in the <xref> except for the href attribute.

For example change this:

<xref jcm-link-man:resource-uuid="3e795e90-0684-11e6-82ef-bc764e109cbd" <?BAD-REF doc-bad?/><? ... ?> href="#topic-9228/section-ID">

To this:

<xref href="#topic-9228/section-ID">

Save the document and easyDITA will correct and fill-in the proper uuid.

Fixing FileNotFoundException build error

This is how you fix a build the FileNotFoundException and it includes a reference to keydef.xml. The message appears as an error when you build (Publish) a map.

Error example

The message above gives a clue as to where the problem will be found: in the Social folder.

Important: This error is almost always the result of a map that has a chunk="to-content" attribute, and a subtopic that has a <keyword> in it. (This is a bugi in the Open Toolkit library.) You can always fix the problem by eitehr removing all keywords in the sub topic, or removing the chunk attribute.

The easiest way to fix this is to locate and remove the chunk="to-content" attribute in the DITA map.

Alternatively, remove the <keyword> elements from the subtopic, which in the example above is "configuring_google_promote.dita".

If you are having a hard time locating the problem:

  1. Download the build to your computer, unzip the bundle, and open the log.txt file in a text editor.

  2. Search the log file and look for "FileNotFoundException".

  3. When you find it, look at the line above the line that contains the error and identify the parent DITA file. This example tells you, "The problem is in a child topic of the Google_promote(.dita) file"

  4. Locate the DITA map or book-map that contains that file, and edit the map's XML. Then remove the chunk="to-content" attribute, and save the map.

Finding bad keywords

A keyword like [Medallia, Inc.] references one of our global variables. Usually, when everything is set up correctly, you can see the value of the variable. When the reference is incorrect, you see the Key ref value instead, like this [Voci]. In the easyDITA editor, this paragraph looks like this:

As you can see, capitalization matters. These can be tricky to identify.

The log.txt file — created when you build (publish) the job — does call them out, but as INFO not ERROR or WARNING. To find them, search the log file for "Unable to find key definition" or "href may be used as fallback".

You can then open the document and correct the error.

Fixing 'type NMTOKEN must be a name token.' error

This happens when there is a malformed <keyword>. The error gives no clue to that effect; it looks like this:
[gen-list] [DOTJ013E][ERROR] Failed to parse the referenced file &apos;/opt/publishing-processors/temp_publish_store/pub-349163208/db/organizations/medallia/repositories/master/content/documents/Help/OrgMgmt/Organization_management.dita&apos;. The XML parser reported the following error:  [gen-list] Organization_management.dita Line 2:Attribute value &quot;&quot; of type NMTOKEN must be a name token.    [chunk] [DOTX008E][ERROR] File &apos;/opt/publishing-processors/medallia/dita-open-toolkits/DITA-OT1.8.5_full_easy_install_bin/temp/temp20190206205531582/Help/OrgMgmt/Organization_management.dita&apos; does not exist or cannot be loaded.
The important part is:
[gen-list] Organization_management.dita Line 2:Attribute value &quot;&quot; of type NMTOKEN must be a name token.
This happens because either of these definitions:

<title id="">
<keyword id="" />
<keyword keyref="platform"/>

In the first and second, id= is blank. You cannot have a blank ID. (In the easyDITA Attributes editor, you need to click the Trashcan icon; do not just delete the contents of the field.)

In the last example, the keyref value is "platform", but the actual keyref is "Platform". Keyrefs are case-sensitive. The correct use is
<keyword keyref="Platform"/>