However, if you’re considering upgrading from an earlier version of WebWorks Publisher to the latest ePublisher platform release (currently version 9.2.2 build #10315), you should be aware of a significant change in the way that TopicAlias markers are handled.

In WWP6, the contents of TopicAlias markers were treated as numeric MapIDs, and WWP autogenerated text aliases based on the text of the heading in which the TopicAlias marker was inserted.

For example, if you inserted 1002 in a TopicAlias marker, WWP6 would generate a mapping entry as follows:

   #define Heading_Text1002  1002 /* Heading Text */

Now in WWeP 9, the contents of TopicAlias markers are instead treated as text aliases, and WWeP instead generates its own map IDs based on the sequence in which TopicAlias markers appear in source files.

In WWeP, the example above is now output as follows:

   #define 1002 10000010 /* Heading Text */

The old approach in WWP6 meant that the map IDs received from application developers could be inserted in TopicAlias markers in a one-time effort, and these IDs were honored regardless of topic order or heading text. If either of these changed from one release to another, WWP handled all necessary changes with no manual rework, as text aliases were created and associated with the proper files automatically.

According to Quadralay, the change was intended to resolve “confusion” regarding the use of TopicAlias markers, since under the new scheme, these markers are indeed treated as text aliases.

However, for users migrating legacy projects from older WWP versions in which TopicAlias markers contained numeric IDs, the distinct disadvantage to this method is that changes to topic order now affect the autogenerated IDs, which requires manual changes to either application source code or manual editing of custom map files.

Workaround: If your fileset contains only a small number of TopicAlias markers, your best bet is probably to bite the bullet and replace the numeric IDs in the TopicAlias markers in FrameMaker with the alias strings from the header file supplied by your application developers (something like IDH_DLG_DIALOGNAME).

Quadralay support has since confirmed this defect, which they describe as follows:

If your AutoMap job does not complete successfully, and it returns errors in the log regarding failed communication with FrameMaker, it’s possible that it was not able to run the job from the Windows scheduler (even if you are running it manually) due to invalid credentials.

That is, when you set up a job, you must provide a valid user name and password to schedule the conversion. If a job is executed, and it can’ t log in correctly, it may report errors in communicating with FrameMaker (because it can’t even communicate effectively with the system). To resolve the issue, right-click on the the job in the AutoMap interface and choose Schedule Job. If you’d like to schedule it for automated conversion, do so in the Windows task scheduler dialog that appears. Otherwise, just click OK. You’ll be prompted for a user name and password. Enter the correct credentials, click OK, and then run the job as usual.

Attempting to Start FrameMaker communication...
Error communicating with Adobe FrameMaker.

These messages suggest that AutoMap can’t find FrameMaker (or vice versa), and if that’s the case, Quadralay offers a few suggestions in a TechNote.

But today I found out (the hard way) that these errors may in fact have nothing to do with the connection between AutoMap and FrameMaker…

…Instead, they may actually be caused by bad settings in the job schedule. These faulty settings apparently prevent the job from running—even manually via the Run command.

When the job is set up, if the job schedule was not defined (for example, if you canceled out of the task schedule dialog for waj <jobname>), the properties for the job (XP Control Panel > Scheduled Tasks) reveal that the task is set to run as NT AUTHORITY\SYSTEM.

Changing this via the Schedule Job command in the context menu to use a proper user name & password allows the task to run properly.

It would be nice if the log file would contain some sort of error message that points the user in the right direction in these cases, instead of sending us down the dead end road with Error communicating with Adobe FrameMaker.

Update:  I’ve pointed this out to the support people at Quadralay, who have since confirmed the defect.