16.3.0 Error Handling and Verify Reference
This article will outline the features of Error Handling and Verify, describe how to implement and use them in AutoTag, how to interpret issue output in AutoTag, and how to use these features in the Windward Engines. This article assumes you have a working knowledge of AutoTag and one of the Windward Engines.
What are Error Handling and Verify?
Error Handling and Verify are a data validation and an issue identification tool included in AutoTag and the Windward Java, .NET, and RESTful Engines. Together, Verify and Error Handling provide the user with a list of issues the Windward engine encounters in their template without halting report generation, and still delivering a final report. Error Handling and Verify handle two different realms of issues, and can be enabled and disabled independently in the engines, but share an interface in AutoTag.
Error Handling Issues
Error Handling must be enabled on a per tag bases and can catch a variety of different exceptions that normally would halt report generation, as well as verify the existence of a node or value being queried by your tag’s select. Each of the Error Handling issues listed below can be enabled individually for any eligible tag type. Error Handling can be applied to each of the following tag types: Out, Import, Set, ForEach, Query, If, Switch, Case, Link, Bookmark, and DrillDown.
Type issues can occur when a tag has a specified data type different than the data type of the data returned by the select statement. These issues if uncaught by Error Handling would normally throw an exception that halts report generation.
Formatting issues can occur when a tag has a specified format but the data returned by the select is not in the correct form to be applied to the specified format. These issues if uncaught by Error Handling would normally throw an exception that halts report generation.
A bad select can occur when a select fails to find valid data in the data source. These can occur for several reasons, one example being a nonexistent node alias being used in a select statement. These issues if uncaught by Error Handling would normally throw an exception that halts report generation.
Node Does Not Exist
Node does not exist issues are reported when a node is queried and the alias does not exist in the data source. These issues if uncaught by Error Handling would normally return an empty value that may be output to the final report without an explanation for the missing data.
Node Is Null
Node is Null issues are reported when a select returns an empty or NULL value. These issues if uncaught by Error Handling would normally return an empty value that may be output to the final report without an explanation for the missing data.
Verification issues do not need to be enabled for individual tags, but rather report issues in a template that may affect the quality of the report as a whole. The different Verification issues are listed below:
Unused Data Source
Occurs when a data source is connected to the template but not used.
Undefined Data Source
Occurs when a tag uses a data source that is not connected or a tag is not connected to any data source.
Elements generating off page
Occurs when an element generated during report generation is off the visible page.
Some tags become “invisible” during editing. While the tag is not visible in the template (there is no visible text representation or nickname), it’s signature still exists (click ALT+F9 to reveal all tag signatures) and it will output during report generation. Verify will report an issue for any invisible tags in the template.
Adding Error Handling to Your Template
In a AutoTag template, open the Tag Editor for a tag eligible for Error Handling. You can achieve this by double clicking the eligible tag.
In the Tag Editor navigate to Properties > Advanced. Select the error-handling box, and click the three dots that appear on the right side of the Properties window.
In the window that appears, you will see the six different Error Handling options you can enable for a tag. The first five Error Handling options correspond to different Error Handling issues, for example: The “Ignore type error” option checks for type issues. Select each of the first five Error Handling options you would like to check by clicking the box next to the option and click “OK” when you are finished. You’re probably wondering what the “Treat warning as error” option does; don’t worry, we’ll get to that later!
Click the “Save Tag” button in the Tag Editor to save your changes. You now have Error Handling set for one of the tags in your template! Follow along bellow to learn how to view instances of Error Handling in your template.
The “Treat warning as error” option
All Error Handling issues will appear as “warnings” unless the “Treat warning as error” option is selected for the tag, in which case the issue will appear as an “error”. Out of the box, “warnings” and “errors” are identical except for the different signatures in the error stream. What this option does is enables users who embed Windward into their applications to automatically handle issues of different severities. If Error Handling catches an issue in an important tag, choosing to report the issue as “Error” vs “Warning” allows that issue to be prioritized on a different level.
Running Error Handling and Verify in AutoTag
In AutoTag, Error Handling and Verify must be run together. While the two are referred to only as “Verify” in AutoTag, “Verify” does report both Verification issues and Error Handling issues that occur in the template. The first way to run Error Handling and Verify in AutoTag is by clicking the “Verify” button that appears next to the “Output” button under the AutoTag ribbon.
The second way to run “Verify” is when you generate a report. To run “Verify” on report generation, open the AutoTag Manager ribbon and click the options button. In the Options window that opens, check off the “Verify On Report Generation” option to enable Verify running at report generation. Now when you click the “Output” button to produce a report, “Verify” will be run as the report generates. This will not noticeably affect the time it takes to generate your report, but will notify you if there are issues in your template. Running a report with “Verify On Report Generation” enabled will allow your report to output even if exceptions are encountered in tags with the appropriate Error Handling settings enabled. The Error Handling settings on tags in your template will only catch errors during output if the “Verify On Report Generation” setting is enabled.
Error Handling and Verify Results in AutoTag
All issues found by Error Handling and Verify in AutoTag are displayed in the “AutoTag Verify” window. There are six different sections that appear in the window: one for each of the five different types of Error Handling issues, and one for Verification issues. The “AutoTag Verify” window only appears when Verify is run and there are issues in the template. The window shows whether the issue is a warning or an error, the nickname of the tag that caused the issue, the exception title, and the full text of the tag.