Complete documentation of return codes

Idea created by Michael_Lowry on Apr 13, 2018
    Under review
    Score5
    • Michael_Lowry
    • Carsten_Schmitz
    • Vlad_N
    • DaliborSefcik607509
    • TimSchmelzer602739
    Automation Engine functions initiated via user interface actions, scripting statements, or API calls usually result in a return code and/or message. Often, these are not completely described in the pertinent documentation pages. For example, documentation page of the :DEACTIVATE_UC_OBJECT scripting statement lists just seven (7) different possible return codes:
    • 12204 - The task (RunID) cannot be deactivated. You cannot deactivate objects of a workflow.
    • 12205 - The task RunID) cannot be deactivated because some of its subtasks are still active.
    • 12206 - The status definition is not numerical.
    • 12207 - The status definition is not in an ascending order (from-to).
    • 12208 - The status definition is syntactically incorrect.
    • 12209 - Cannot find the status definition: The object has not been deactivated automatically.
    • 12210 - The status definition is not numerical. The object has not been deactivated automatically.
    However, this documentation page omits at least five (5) other possible return codes for this statement:
    • 11010 - Cannot find Workflow '&01' for deactivation.
    • 11028 - It is not possible to deactivate group '&01' because it is not active.
    • 11161 - Cannot deactivate task with RunID '&01', invalid status for deactivation.
    • 11163 - Cannot deactivate task with RunID '&01', this task is not active anymore.
    • 11164 - Cannot deactivate task with RunID '&01', a task within a Workflow cannot be deactivated
    Although these messages documented in the general Messages documentation, they are not documented on the documentation page for the :DEACTIVATE_UC_OBJECT scripting statement or the DeactivateTask Java API class. When developers are designing the error handling portions of programs that interact with the Automation Engine, the lack of a complete list of return codes for each AE function makes this job more difficult, time-consuming, and error-prone.

    For each Automation Engine function, there should be a complete list of the possible return codes, plus a description of each one. These return codes should appear in the documentation of the relevant user interface elements, scripting statements, and API calls. If you want to document them only in one place, I suggest documenting them in the page of the corresponding AE scripting statement, where partial lists of return codes can already be found. Then a link to this page can be included in the documentation pages for the corresponding UI functions and API classes.