JBoss.orgCommunity Documentation

Dashbuilder Documentation

If you want to build the project and execute a quick demo, please, proceed as indicated:

  1. Prerequisites:

    This guide assumes you have Java JDK 1.6 (set as JAVA_HOME), a Git client and Maven 3.0.5+ (set as MAVEN_HOME) in your system. The java and mvn commands must be added to the executable path as well.

  2. Download the project from the GitHub server:

    git clone https://github.com/droolsjbpm/dashboard-builder.git
  3. Open a terminal window, go to the scripts directory and type the following command:

    ./buildandrun.sh h2

    This command compiles, builds and runs the application. This procedure will take a few minutes (but only for the first time) because of the Maven build process needs to download a lot of third-party libraries.

  4. Once the application is started, open a browser and type the following URL:


    The login screen will appear. Login as user root and password root. You'll gain access to the default workspace, called Showcase, which contains several sample dashboards as well as some administrative tools.

    The following users are available by default:

    • root/root: to sign-in as the superuser. It's granted with administrative permissions.

    • demo/demo: to sign-in as an end user. It has only read only permissions.

    You'll need to sing-in as superuser in order to be able to create and modify dashboards.

The purpose of this chapter is NOT to provide a full detailed explanation of the tooling, but to guide you through the key steps to get your first dashboards created. The following section will provide basic information about how to configure the system to retrieve information from existing databases or files, create new indicators and manage different dashboards.

For this guide, it's assumed the simple installation has been done, with the standard set of examples and user and role configuration. It's important to notice this configuration MUST NOT be used in production, since it provides default security credentials.


Please, read the previous chapters to figure out how to get the application up and running

The procedure to create a brand new dashboard is pretty simple as we will see in the following sections. That procedure is composed of 3 main stages:

  1. Get the data we want to manipulate.

  2. Create key performance indicators on top of such data.

  3. Create a new dashboard and drag&drop the new KPIs on it.

The first thing to do, after you have accessed the web application, is to create a data provider. On the left menu, go to 'Administration > Data providers' and once there, select the option 'Create new data provider'.

The purpose of data providers is to gather information from any system, either a database, a file or any other, and transform it to the internal in-memory representation for building dashboards. As you may guess there exists different data sources and therefore different ways to retrieve as we're going to see next.

Click on 'Create new data provider'. The following fields will be shown in the form, with some sensible defaults:

Once you have filled all the fields, click on 'Try', to check that everything works properly. The application will give you a message 'Correct data set ...' and we continue by pressing 'Save'.

Next, a screen is shown with all the fields found after parsing the file, giving us the option to change the name of each field. For numeric fields it gives us the option to specify if we want numeric values to be treated as labels by the dashboard engine. This is something really useful when dealing with numbers which actually behave as labels, f.i: the numeric reference code of a product item.

After this last step, you can save and finish the creation of your new data provider.

The previous sections showed how data could be loaded from plain text like CSV files or query from a database connection. When data is small enough, Dashbuilder can handle pretty well the small data sets in memory as far as it doesn't exceed the 2MB size limit. However, must of the time, our data sets are bigger and we can't upload all the data for Dashbuilder to handle it by its own. Is in these cases where database backed queries can help us to implement nice drill down reports and charts without preloading all the data.

Imagine a database containing two tables:

Now, let's take as an example a very simple example of a stock exchange dashboard which is fed from the two tables above. The dashboard displays some indicators about several companies from several countries selling their shares at a given price on every day closing date. The dashboard displays 4 KPIs as you can see in the following screenshot:

All the indicators are displaying data coming from the two database tables defined above.

  • Bar chart - Average price per company

  • Area chart - Sales price evolution

  • Pie chart - Companies per country

  • Table report - Stock prices at closing date

What we're going to start discussing next is the two strategies we can use for building a dashboard. This is an important aspect to consider, specially if we're facing big data scenarios.

The native approach consists in having a data provider for every indicator in the dashboard instead of loading an handling all the data set in memory. Every KPI is told what data has to display. Every time the user filters on the dashboard, the SQLs are parsed, injected with the filter values and re-executed. No data is hold in memory, the dashboard is always asking the DB for the data.

The SQL data providers are the following:

As you can see every KPI is delegating the filter & group by operations to the database. The filter magic happens thanks to the {sql_condition} statements. Every time a filter occurs in the UI the dashbuilder core gets all the SQL data providers referenced by the KPIs and it parses/injects into those SQLs the current filter selections made by the user. The signature of the sql_condition clause is the following:

      {sql_condition, [optional | required], [db column], [filter property]}




When designing a dashboard never forget of thinking thoroughly about the origin, type and the volume of the data we want to display in order to go for the right strategy.

Once the necessary data providers have been created, you can continue by adding a new Key Performance Indicator to an existing page. All dashboards are created by adding indicators and other types of panels to pages. A dashboard is a page with a mixture of different kind of panels placed into it. The following screenshot shows an example of a Sales Dashboard:

Pages can be created from scratch, or duplicating an existing one. Both options are explained in the following sections. Meanwhile we will assume the page already exists and we only want to add an indicator.

Indicators are a special type of panels, which are the widgets that can be placed within the page. To add a panel or indicator just click on the toolbar icon 'Add panel to the current page':

This will make a popup be shown with all the available panels:

To add a new 'Key Performance Indicator', click onDashboard > Key Perfomance Indicator. Drag the 'Create panel' option and drop it into any of the page regions. You will see that they are being highlighted while you move the mouse over them, then simply drop the panel.

Once dropped, the first step is to select the Data Provider you need to use, as configured before, to feed the charts and reports with data. Select any of the data providers and then you can start creating a new indicator.

Now, you must see the chart edition panel. It's an intuitive environment which helps you configure different type of charts and reports...

  • Domain (X Axis): The data column that is taken as the X axis. In this example, we choose the property 'Country'.

  • Range (Y Axis): Information to be grouped and aggregated for every domain interval. For example: 'Amount'.

  • Renderer: The rendering library to use. Each one provides different features and visualization style. By default 'NVD3'.

  • Sort intervals by: It's how the domain values can be sorted, for example, according to its range value.

  • Sort order: It can be ascending or descending.

To finish the panel edition just close the panel edition window. If you want to get back again, just click on the right upper corner of the panel area and select the 'Edit content' menu option.

The system provides you with 3 types of chart displayers: bar, pie and line, and a special table displayer very useful to create tabular reports. The system also comes with 2 rendering engines: NVD3 (pure HTML5/SVG technology) and a Flash based one, Open Flash Chart 2. Each renderer has its own available features, so depending on the type of chart and renderer choosen you can end up with some display features enabled or disabled depending the case. For instance, the 'Paint area' feature is not available for OFC2 line charts.

A dashboard is basically a page with some KPIs placed on it (plus some other additional widgets as we will see later on). There are two different ways of creating a page:

Starting as a blank page:

Duplicating an existing page:

You will find these icons at the top of the page, in the administration bar:

To create a new page, click on the 'Create new page' icon:

A form will be shown to fill in some parameters:

  • Page title.

  • Parent page: Pages are organized in a hierarchical way. This is the parent page.

  • Skin: This will select and specific look'n'feel and CSS stylesheet for this page. You can leave the default value.

  • Envelope: Defines which kind of HTML template will be placed around the page layout.

  • Region layout: This is the template, that is, how regions are organized to place the panels inside the page. We can choose any of the installed types, for example, "Demo - Default template with sliding".

Most of these properties will be discussed in the chapter about 'Customing look'n'feel'. After creating the page, you might realize the page is still not accessible from the left menu but you can see it in the combo list in the administration toolbar:

If you want this page to be shown in the left menu, you can click on 'Edit content' and then add the newly created page to the list of options displayed in the menu.

Repeat until the page has all the content and panels required. After dropping the panels into the right regions and configuring them, you might be able to create dashboards that look like the following one:

As you can see, a dashboard is usually composed by one or more instances of the following panel types:

  • Dashboard > Key Performance Indicator

  • Dashboard > Filter & Drill-down

  • Navigation > Tree menu

  • Navigation > Language menu

  • Navigation > Logout panel

The 'Filter & Drill-down' panel allows for the quick definition of dynamic forms that will allow us to navigate troughout the data displayed by the dashboard. Once an instance of the 'Filter & Drill-down' panel is dropped on the oage we just have to select the 'Edit content' option from the panel menu. After that, a popup window similar to the following will be displayed:

This is a filter configuration panel where we can set the filter behaviour. Let's focus first on the middle bottom part of the screen: the Data provider's property table, which lists the properties of ALL the data providers referred by the KPIs on the page. For example, if we are building a sales dashboard and all its KPIs are built on top of the same data provider called 'Sales dasboard demo' then the system lists all the data properties of the 'Sales dashboard demo ' provider. Hence, only the properties we select as 'Visible' will be part of the filter form. Aditionally, we can enable the drill-down feature for each property. If enabled then the system will redirect to the target page when the property is selected on the filter form. Below is an screenshot of the filter panel of the 'Sales dashboard demo'.

As you can see the form is composed by all the visible properties selected. For each property the system reads its configuration by asking the underlying data provider. For label type properties a drop-down list is displayed, containing as options all the disctinct values of the data provider's column. When the user submits a change on the filter form then the following operations are carried out by the dashboard visualization engine:

  1. It reads the data sets for the target data providers. A data provider is in the target set if it contains the selected filter property.

  2. It applies a filtering algorithm in memory on the target data.

  3. If drill-down is enabled for the selected property then the target page is set as current and the steps #1 and #2 are repeated again.

  4. Finally, after filtering, all the sensible KPIs are updated in order to display the filtered data. By sensible, we mean a KPI which is displaying data that is being filtered.

Let's see next how to define custom authorization policies to grant/deny access to a workspaces, pages or panels instances per role.

To wrap up, it's worth to mention that thanks to the permission system we can build a workspace structure with several pages, menus and panels and start defining what pages and panels within a page will be visible for each role. We can also define special kind of users and give them restricted access to certain tooling features or even restricted access to a page subset. The chances here are infinite.

There exist three types of graphic resources.

You can handle all these components from the administration console, under the node 'Graphic resources' and create/modify them in order to fully customize the look and feel of your dashboards.

Each graphic resource is packaged in a file. Zip file which content varies depending on the type of component. Nonetheless, the structure of the management screen is the same regardless of the type of the resource being handled. As we can see on the screen, the upload form is composed by two fields:

  • ID: a unique identifier. If you just want to update existing resource you just have to copy its id.

  • Zip file: file coming from the user local file system containing the definition of the component and its resources.

Each zip comes with a definition file which name varies depending on the type:envelope.properties, skin.properties or layout.properties. This property file have two distinct parts:

  • Name of the item in different languages, to which is added a line in the following format:

    name.<idiom abbreviation(es, en, ca)> = Name of the resource in that language

  • List of static resources associated with the component:

    resource.<resource_id>= Path relative to the zip file.

The easiest way to create a brand new skin, envelope or page layout is to download an existing one, unzip/modify it and finally upload the new zip as a new resource. The management of graphic resources can be carried out by a graphical designer who shall not require the presence of a technician to do their job.

Despite Dashbuilder is an standalone dashboard composition tooling, integration with external systems might be required. For instance:

  • Imagine a third-party web app which relies on Dashbuilder to provide the monitoring capabilities. The web app requires to embed a chart into one of its pages. This would be an example of content syndication.

  • Imagine also another application which want to push/pull data from Dashbuilder. A SAP system, for instance, which want to push a new purchase order to an specific Dashbuilder data provider, or a external alert management system which requires to evaluate the current value for a given KPI.

These and many others are examples of integration uses cases. This chapter walks through the different mechanisms that Dashbuilder provides in that direction.

Dashbuilder provides the ability to embed dashboard charts into your own web app via a lightweight easy to use JavaScript API. Once a dashboard is built, it's possible to pick up any KPI and paste it into any web application.

The following HTML sample page shows how to achieve so.

        <title>Dashbuilder Javascript API</title>
        <script src="http://localhost:8080/dashbuilder/js-api/dashbuilder-1.0.0.js"></script>
        <style type="text/css">
          .code {
            background-color: rgb(248, 248, 248);
            border-color: rgb(221, 221, 221);
            border-radius: 3px;
            border-style: solid;
            box-sizing: border-box;
            color: rgb(51, 51, 51);
            font-weight: normal;
      <body onload="embedCharts();">
        <h1>How to embed KPIs in your own application</h1>
        This is a very simple layout that demonstrates how charts can be embedded with the following Javascript code:
        <span class="code">dashbuilder_embed_chart('chart1', 'http://localhost:8080/dashbuilder', 'kpi_30011353503663716', 600, 350);</span>

        <!-- Very simple layout with charts -->
        <table border="0" cellpadding="5" >
            <td id="chart1"></td>
            <td id="chart2"></td>
            <td id="chart3"></td>
            <td id="chart4"></td>
        <!-- End of charts -->

        Click <a href="#" onclick="embedCharts(); return false;">here</a> to reset the current filter criteria.

        <script type="text/javascript">
          function embedCharts() {
            var dashbuilderUrl = 'http://localhost:8080/dashbuilder';
            dashbuilder_embed_chart('chart1', dashbuilderUrl, 'kpi_30301353506280659', 600, 350);
            dashbuilder_embed_chart('chart2', dashbuilderUrl, 'kpi_30041353504912610', 600, 350);
            dashbuilder_embed_chart('chart3', dashbuilderUrl, 'kpi_30441353507392054', 600, 350);
            dashbuilder_embed_chart('chart4', dashbuilderUrl, 'kpi_30251353675275870', 600, 350);
And this is how the HTML looks after being processed by the browser:

As you can see in the source code of the example, all the KPIs are embedded using the following API call:

    dashbuilder_embed_chart(chartId, dashbuilderUrl, kpiId, width, height);
  • chartId: It's the id of the HTML element where the KPI will be inserted.

  • dashbuilderUrl: The fully qualified URL of the Dashbuilder app.

  • kpiId: The identifier of the KPI (provided by the Dashbuilder app). It can be obtained by editing the KPI panel from the Dashbuilder UI. Just go to the dashboard where the KPI is placed, edit the panel (admin rights required) and copy & paste the KPI id (see the image below).

  • width/height: The total size of the display area used to render the KPI.

Dashbuilder provides import and export functionality in order to move application assets between environments.

These assets can be:

  • Workspaces: By exporting and importing workspaces you can move your set of pages with a given look and feel between installations.

  • Key performance indicators and data providers:: By exporting and importing KPIs you can move your indicators and its data providers between installations.

  • Data sources: By exporting and importing data sources you can move your external connection configurations between installations.

In general, asset exportation must be done using the Web User Interface. There exist a panel for exporting each type of asset.

On the other hand, asset importation can be done in two ways:

  • Using the Web User Interface.

    There exist panels for importing each type of asset.

  • Using the Deployment Scanner.

    It allows to place your exported assets in a given folder inside the web application. Once application is starting, it scans the deployment folder and import the assets found.

    Using the Deployment Scanner allows for the automatic deployment of assets on application start up time and does not requires the user intervention either.

    It's important to note that assets are imported only at deploy time, not during application runtime.

The following sections describe how to perform import and export for each kind of asset.

Workspace import & export allows you to move one or more workspaces to other JBoss Dashbuilder installations.

The import & export of a given workspace implies moving:

In order to export a workspace there exist a panel named Export workspaces.

It lists all the existing workspaces in the application and allows to export one or more workspace definitions in a single XML file. Note that for versions previous to 6.2.0 the workspaces were exported in ZIP format.

In order to import a workspace you can do it in two ways:

Workspace import & export allows you to move your KPI and its data providers to other JBoss Dashbuilder installations.

The import & export of a given KPI implies moving:

In order to export a KPI there exist a panel named Export dashboards.

It lists all the existing KPI in the application and allows you to export one or more KPI definitions in a single XML file.

In order to import a KPI you can do it in two ways:

Data source import export allows you to import one or more data source connection definitions into a JBoss Dashbuilder installation.

Data source exportation is not supported yet, there is no panel for exporting them.

In order to import a data source you can do it in two ways: