Debugging Reports

Overview

Finding and resolving issues in a report template can be difficult. The following are tools that can help find and resolve any issues you may encounter.

JSONata Query Exerciser

JSONata queries can be difficult to debug in a report template. It is much easier to use an external tool that will allow you to modify your query and see the data output in real-time. There are two recommended tools for doing this. First, there is a JSONata Exerciser that allows you to run queries against your data and get instant results. There is a similar tool in the Report Web Editor. This tool has the added benefit of allowing you to insert your queries directly into your report templates after testing the results.

Using one of the tools above will help you write queries that are known to produce the desired JSON data output for your report template.

Layout Debugger

Each component in a report may optionally include a DebugOptions element. Setting this on a component provides for a few useful features to aid in debugging layout issues.

The image below shows a report with a single Text component with the Debug option enabled:

DebugOptions Schema

key	type	required	description
enabled	boolean	optional	Turns on debugging for the component.
highlightColor	string	optional	Sets the color to use for highlighting the component. Can be any well-know color name (e.g. "red", "blue", "orange", etc.).
name	string	optional	Renders a name next to the component. Helpful for identifying a component while debugging.
breakpoint	boolean	optional	Sets breakpoint in the debugger

Component Debugging

Sometimes it is helpful to step-through code when rendering a specific component in a report. It is possible to set a breakpoint in your report template. This is done by setting the breakpoint option in the component's debug settings as shown below:

{
    "type": "Text",
    "text": "Let's debug this component!",
    "debug": {
        "breakpoint": true
    }
}

With the breakpoint enabled and a debugger attached when rendering the report, the debugger will stop as soon as the component begins the rendering process. This can be helpful when trying to debug layout, conditionals, queries, etc.

Layout Exceptions

It is possible to generate a report template that is impossible to render. This will result in a Layout Exception that can sometimes be hard to track down. When you encounter such an exception, the best method of finding the issue is to look for layoutOptions that could result in ambiguous layout or a layout that is impossible to fit on a page. For example, the following component will result in a Layout Exception:

{
    "type": "Text",
    "text": "Layout exceptions are no fun.",
    "style": {
        "layoutOptions": {
            "width": 1000
        }
    }
}

The cause of the Layout Exception for the component above is simple to detect. A page in a report is not wide enough to accommodate 1,000 pixels, so the report is impossible to render.

Another example of a component that would result in a Layout Exception:

{
    "type": "Row",
    "style": {
        "layoutOptions": {
            "height": 200
        }
    },
    "components": [
        {
            "component": {
                "type": "Text",
                "text": "Layout exceptions are no fun.",
                "style": {
                    "layoutOptions": {
                        "height": 250
                    }
                }
            }
        }        
    ]
}

In this example, a child component has set a layout height of 250 that will not fit in its parent component because it has a height of 200. Adjusting either value so that the parent component can accommodate the child will resolve the issue.