Dashboard Utility Overview

In BBj 15.0 and higher, access to full functionality of this feature requires an active Software Asset Management (SAM) subscription. See Benefits of ‘Software Asset Management” Feature Line.


In BBj 14.0 and higher, the Dashboard Utility facilitates the visualization of data via dashboard widgets that may contain all kinds of information based on

  • Bar, stacked bar, and stacked percentage bar charts
  • Pie and ring charts
  • Line, XY, and area charts
  • Grids
  • JasperReports
  • HTML text and websites
  • Images

Feature List

Enhancements added in BBj 19.0 and higher:

  • Adds the ability to define your own popup menus for a dashboard widget which can replace the default right-click and/or Options popup menus.
  • Adds the ability to access a DashboardWidget's WidgetControl from any DashboardWidgetEvent.  Now the developer has access to both the data and UI classes for the DashboardWidget on which the event occurred.
  • Adds the ability to control whether a dashboard program should stop execution after encountering an error filling a widget via the FillErrorAction field variable on a Dashboard, DashboardCategory, or Widget.  You can set a Dashboard, DashboardCategory, or individual widget to ignore errors, warn the user of errors, or stop execution on errors.  The default behavior as of 18.20 is to ignore errors and continue execution.  In this case, all errors will be logged and widgets will show as much information as is available.  When possible, the widgets will also display an error indicator and a description of the error that occurred.
  • Adds the ability to set  a custom image or text to display over a widget that experiences an error via the setFillErrorDisplayImage() and setFillErrorDisplayText() methods.
  • Adds a JasperViewerWidget constructor and DashboardCategory::addJasperViewerDashboardWidget() method that takes a report file, connection string, and report parameters to create an auto-fillable/refreshable JasperViewerWidget.
  • Adds the ability to create a JasperViewerWidget based on a BBJasperView which won't take up valuable space for the tool bar and status bar.
  • Adds the ability to force whether the JasperViewerWidget should show a tool bar or not via the setHasToolBar() and getHasToolBar() methods.
  • Adds getFitType() and setFitType() methods to the JasperViewerWidget.
  • Adds a getView() method to the JasperViewerWidget which returns the underlying BBJasperView, regardless of whether a BBJasperViewerControl is used.

Enhancements added in BBj 18.0 and higher

Enhancements added in BBj 17.0 and higher

Enhancements added in BBj 16.0 and higher

Enhancements added in BBj 15.0 and higher

Dashboard Utility Performance

Virtually all performance issues for the Dashboard Utility are related to aggregating data for the widgets.  By way of example, executing a slow SQL statement or filling a very large report widget can slow down the initial display of the entire dashboard.  The Dashboard Utility offers a way to analyze widget performance via a debug timing mode that outputs Dashboard Widget query timing to the  BBjServices Debug.log.<timestamp> log file in the <BBjHome>/log directory.  See this Bugzilla entry for details regarding how to enable logging and to download a sample program that analyzes the results and presents the data in a sortable grid.

Dashboard Utility Errors

When the Dashboard Utility experiences or throws a runtime error it will typically be in one of the following categories:

  • Error 256: An invalid parameter, such as an event type, was specified for callback. Attempting to add a non-unique object such as a DashboardCategory, DashboardWidget, DashboardWidgetFilter, or DashboardWidgetLink.

  • Error 300: An error occurred when filling a widget with data, e.g. an SQL error occurred when trying to build the record set for the widget.  These errors are logged in the BBjServices Debug.log.<timestamp> log file in the <BBjHome>/log directory.  The log file entry contains a timestamp, error number, line number on which the error occurred, the error message, and information about the widget including its name and title..

  • Error 305: An error occurred when setting a widget's column width percentages.

  • Error 310: An error occurred when trying locate a custom font for the widget.

  • Error 313: An error occurred in one of the ChartWidget's color utility methods.

  • Error 320: An error occurred loading an image. This may occur when loading an ImageWidget, or when loading an image via the setFillErrorDisplayImage() or setChartEmptyDisplayImage() methods.

  • Error 330: An error occurred locating a specified file, such as the report file specified in the JasperViewerWidget's constructor

To see the Dashboard Utility in action

  • From a browser, click on one of the Dashboard Demos from the BBx BUI Showcase page (no installation of BBj required)
  • After downloading and installing a packaged version of BBj that includes the Demos, run the <bbjhome>/utils/dashboard/demoDashboardBUISetup.bbj program and choose the (R)un option to launch a BUI program that demonstrates many of the Dashboard's capabilities

Furthermore, the Dashboard Utility facilitates the ability to embed dashboard widgets in an existing BBj, Visual PRO/5, or PRO/5 application.


 For complete Dashboard Utility documentation, including dashboard widgets, click here.  

Example Dashboard

See Also

The complete Dashboard Utility reference documentation

Dashboard Types

Dashboard Charts and Datasets

Dashboard Chart Customization

Dashboard Utility on the IDE Wiki


Copyright BASIS International Ltd. BBj®, Visual PRO/5®, PRO/5®, and BBx® are registered trademarks.