New

Improve Release Candidate transition control on DITA-OT/Ant processing

There are cases a "Release Candidate" state transition is blocked but there is no indication of why this is so in the Publish report.  Related Knowledge Base is KB0026023.  That is confusing behavior, because:

  1. That KB seems to be assuming different concept on "fatal error" than Ant.  In case of Ant, the errors from Ant subtasks are assumed as real fatal error unless Ant failonerror property is set to "true".  That will allow Ant/DITA-OT developers to take try-catch-style processing.  However, KB is probably assuming some certain types of Ant subtask errors are necessarily assumed as fatal error not trusting DITA-OT exit code.
  2. When the case occurred, both ishrunditaot.ps1 script and Ant (of DITA-OT processing) returns exit code '0', that means success (no fatal error).  Therefore, event log states "Success".  However, "Release Candidate" state transition is still blocked by the reason that the KB states.  It appears that ISHRUNDITAOTWITHCOPYIMAGES plugin implemented event logging than what KB assumes right about fatal error processing.
  3. Also, when the case occurred, DITA-OT log is not always with such fatal error message that KB states.  Nobody knows which the exact warning/error messages of DITA-OT log relate to the KB. However, it is not fatal error for DITA-OT/Ant, so that DITA-OT processing does not terminate with that.  So, it takes a lot to identify which of DITA-OT processing messages in the log are related to the KB.

It seems the KB is taking radical approach about error processing than Ant and DITA-OT developer think of.  Actually, there was a case DITA-OT generated expected output, but the state transition was blocked.  So, I feel the position stated by the KB might not be well reasonable, and I wish it stops doing that.  However, if what stated by KB is really needed by some reason, I suggest improving the event log processing by:

  • Stating "Warning" instead of "Success" when it encounters the case "Release Candidate" state transition will be blocked
  • In the event action message, state the exact error that ISHRUNDITAOTWITHCOPYIMAGES plugin assumes fatal but ishrunditaot.ps1 script and Ant don't, maybe pinpointing the error message in DITA-OT log
Masayuki Yamane
Parents

  • There are various Tridion Docs versions in use by various customers, and they in turn decided their DITA-OT version themselves. Both give a matrix of behaviors – as both received updates over time.

    So, let me first clarify some things about the publish on a out-of-the-box Tridion Docs 15.0. The publish consists out of 2 steps:

    1. exporting the necessary objects conditionally filtered to the file system
    2. converting those files into an output - for instance a PDF - using for instance DITA-OT and some extra processing

    The first step is totally controlled by the Tridion Docs PUBLISH background task. Any issue while exporting objects, is collected into the publish report. Are there objects missing? Are there links missing? Are the objects not released?
    The second step is the combination of all publish post processing plugins. Although there are a lot of out-of-the-box plugins, this step is a lot less controlled. So it is not possible to collect any issues of the second part into the publish report.

    Of course, we try to log in the event log that there is or might be an issue with the execution or output of all out-of-the-box plugins.
    So, although DITA-OT is mainly black box, the out-of-the-box plugin running DITA-OT tries to indicate that there is probably something wrong by checking...

    1. the exit code...if the exit code is not 0, an exception is thrown and the publish will fail
    2. the DITA-OT log file where over time we added checks for the following phrases:
      1. If the DITA-OT log file contains 'BUILD FAILED', an exception is thrown and the publish will fail
      2. If the DITA-OT log file contains 'FATAL ERROR', the publish will continue but the publication will not be a release candidate
      3. If the DITA-OT log file contains 'XML document structures must start and end within the same entity', the publish will continue but the publication will not be a release candidate

    However, you are right the event detail is not indicating clearly what the problem is, because the event detail has status "Success" and the description says that DITA-OT finished successfully.

    • SHELL command finished successfully. See eventdata for more details.
    • The DITA-OT logfile is available here for more details.

    For the next release which is Tridion Docs 15.3 we will ensure that the status is always "Warning" if we encounter one of the above phrases and we will adapt the description to contain the phrase we found. So the descriptions will become something like:

    • SHELL command finished with warnings. 'FATAL ERROR' found in the DITA-OT log file. See eventdata for more details.
    • DITA-OT finished with 'FATAL ERROR' in the log file. See attached DITA-OT log file for more details.
Comment

  • There are various Tridion Docs versions in use by various customers, and they in turn decided their DITA-OT version themselves. Both give a matrix of behaviors – as both received updates over time.

    So, let me first clarify some things about the publish on a out-of-the-box Tridion Docs 15.0. The publish consists out of 2 steps:

    1. exporting the necessary objects conditionally filtered to the file system
    2. converting those files into an output - for instance a PDF - using for instance DITA-OT and some extra processing

    The first step is totally controlled by the Tridion Docs PUBLISH background task. Any issue while exporting objects, is collected into the publish report. Are there objects missing? Are there links missing? Are the objects not released?
    The second step is the combination of all publish post processing plugins. Although there are a lot of out-of-the-box plugins, this step is a lot less controlled. So it is not possible to collect any issues of the second part into the publish report.

    Of course, we try to log in the event log that there is or might be an issue with the execution or output of all out-of-the-box plugins.
    So, although DITA-OT is mainly black box, the out-of-the-box plugin running DITA-OT tries to indicate that there is probably something wrong by checking...

    1. the exit code...if the exit code is not 0, an exception is thrown and the publish will fail
    2. the DITA-OT log file where over time we added checks for the following phrases:
      1. If the DITA-OT log file contains 'BUILD FAILED', an exception is thrown and the publish will fail
      2. If the DITA-OT log file contains 'FATAL ERROR', the publish will continue but the publication will not be a release candidate
      3. If the DITA-OT log file contains 'XML document structures must start and end within the same entity', the publish will continue but the publication will not be a release candidate

    However, you are right the event detail is not indicating clearly what the problem is, because the event detail has status "Success" and the description says that DITA-OT finished successfully.

    • SHELL command finished successfully. See eventdata for more details.
    • The DITA-OT logfile is available here for more details.

    For the next release which is Tridion Docs 15.3 we will ensure that the status is always "Warning" if we encounter one of the above phrases and we will adapt the description to contain the phrase we found. So the descriptions will become something like:

    • SHELL command finished with warnings. 'FATAL ERROR' found in the DITA-OT log file. See eventdata for more details.
    • DITA-OT finished with 'FATAL ERROR' in the log file. See attached DITA-OT log file for more details.
Children
No Data