Custom error handling in DocFusion helps to control how generation-time errors for templates are handled. Error messages can be accessed in the generation logs, or directly in generated documents, for further insight and associated stack-traces.
There are two levels of error handling available in DocFusion:
- (Level 0, Default) HaltOnAnyError: The lowest level of error handling. Stops execution on any encountered error.
- (Level 1) HaltOnCriticalError: The most flexible option attempts to generate the document by allowing as many errors as possible.
Custom error levels can be set for business units, individual templates, and as request parameters to API requests. There's an order of precedence that applies but, in each case, the error level setting adjusts the tolerance when encountering errors during document generation. When left unset, a fallback is in place.
When error messages are related to smart parts or adornments, they can be viewed directly in the generated document. The error messages are marked in red to easily identify them. Their location is also relative to the position of the smart part or adornment to provide a clearer indication as to the source of the generation failure.
Custom error levels can be set in Workbench or Template Designer, depending on whether you want to apply it globally, across all templates in a business unit, or an individual template basis. (See Related Guides for instructions.)
Defaults
DocFusion defaults to HaltOnAnyError unless you change the custom error level. The default setting applies globally to all templates in a business unit, and to smart parts and adornments.
The error level setting on the business unit serves as the fallback for all templates.
Templates created with Template Designer or Workbench (version 2023.3.27 or later) will automatically have HaltOnAnyError enabled.
Existing templates that were created with prior versions of Template Designer or Workbench MUST have the error level setting enabled for error handling on adornments to be applied.
Smart Parts & Adornments
Binding evaluations have been applied to the following smart parts:
- DataFields,
- Optionals,
- Optional Columns,
- Charts,
- and Repeaters.
Each of these smart parts generate error messages and, if the error level is set to HaltOnAnyError, generation will terminate and return with failure. When the error level is set to HaltOnCriticalError, the most lenient error level, the generation engine will attempt to continue with document generation despite errors.
For adornments to register errors, you must opt-in on the template settings dialog.
Order of Precedence
To cater for both the ability to override error level settings and ensure that there are fallbacks, the following order of precedence applies:
- Business Unit: Applies globally to all templates in the business unit, and serves as the default. When unset, the HaltOnAnyError error level setting applies.
- Template Configuration: Overrides the business unit setting and applies to individual templates. Falls-back to the business unit setting if unset.
- Request Parameter: Highest order of precedence that overrides all other settings on business unit and template levels. Falls back to template configuration, or business unit setting (the default).
Related Guides
- Setting custom error handling globally, for all templates in a business unit
- Setting error handling for specific templates
- Set error handling using request parameters to API calls