Introducing Dashbuilder Runtime

Business Process monitoring via dashboards and reports is a crucial part of a successful business automation deployment. In Business Central (BC), it is possible to monitor the execution of processes and human tasks using dashboards.

Under the hood, every dashboard living in BC is actually built with a tool called Dashbuilder. It allows users to author pages and add reporting elements to it, making it possible to create dashboards in a user-friendly way. Until recently dashboards could only run inside BC. Now, we are happy to introduce Dashbuilder Runtime, which makes it possible to run BC dashboards in a separate web application.

Dashbuilder Runtime

On Business Central release 7.42.0, we introduced a new standalone application called Dashbuilder Runtime. This new feature is a lightweight application able to run dashboards created on Business Central in a containerized fashion, allowing us to cover a lot of business automation use cases.

Exporting Dashboards from Business Central

Dashboards can be exported in Business Central by accessing Admin -> Dashbuilder Data Transfer feature in Business Central.

Exported dashboards have three components:

• Datasets: Data from different sources (CSV, SQL, Kie Server…) that can be reused in pages;
• Pages: User built pages with layout components containing visual components that may be using a dataset;
• Navigation: Navigation between pages that is used in the Business Central menu.

With Gradual Export you can select which pages and datasets will be in the exported ZIP. If you select no page or select a page without selecting a dataset that it uses then you won’t be able to download the export.

The dataset may have dependencies and it must be configured according to the dataset type:

• CSV: The CSV files are exported along with the ZIP and imported seamlessly in Runtime;
• SQL: For SQL datasets you just need to make sure that the target dataset is configured in the server where Runtime is running;
• Kie Server: In Business Central Kie Server datasets uses the same service used when managing Kie Server instances. In Runtime, the configuration is different and we will cover it in the next section.

The navigation between pages respects the same configuration in Business Central, which means that if page 1 is in group group1 and page 2 is in group2, then the same group will be imported and remain as the navigation in Runtime. A page not added in navigation will be added to a group called “Dashboards”.

Kie Server Datasets on Dashbuilder Runtime

Kie Server uses BC as a controller: when BC is used as a controller, Kie Server container creation will be done in BC. The same happens for datasets, Kie Server configuration is called template and we can refer to a template to create datasets or install containers.

If other services need to retrieve Kie Server information then it should use the Kie Server REST API and that’s what Runtime does, it accesses the Kie Server REST API to run queries from datasets.

When a Kie Server dataset is created in Business Central the server template information is provided and it is used by Runtime to look for the Kie Server information:

dashbuilder.kieserver.serverTemplate.{SERVER_TEMPLATE}.location

dashbuilder.kieserver.serverTemplate.{SERVER_TEMPLATE}.user

dashbuilder.kieserver.serverTemplate.{SERVER_TEMPLATE}.password

dashbuilder.kieserver.serverTemplate.{SERVER_TEMPLATE}.token

It is also possible to setup Kie Server per dataset:

dashbuilder.kieserver.dataset.{DATA_SET_NAME}.location

dashbuilder.kieserver.dataset.{DATA_SET_NAME}.user

dashbuilder.kieserver.dataset.{DATA_SET_NAME}.password

dashbuilder.kieserver.dataset.{DATA_SET_NAME}.token

Notice that token authentication is not used if credentials are provided

One may also want to run the dashboard against another Kie Server installation. Let’s say that datasets were created on a Kie Server in DEV environment, it means that the datasets queries were created on the DEV Kie Server. When the dashboards are exported go, let’s say, to PROD, with another Kie Server, the queries created in DEV won’t be available, so an error will be thrown. In such cases it is possible to port queries from a dataset to another Kie Server by using the replace query boolean property. It can also be set by dataset or by server template:

dashbuilder.kieserver.serverTemplate.{SERVER_TEMPLATE}.replace_query

Or

dashbuilder.kieserver.dataset.{DATA_SET_NAME}.replace_query

It needs to be set only one time so Runtime creates the queries. Once the queries are created you can remove this system property.

Installation

Dashbuilder Runtime is a Java web application and it is distributed in the form of a WAR and it can be deployed in a Wildfly 18 installation.

An easy way to deploy is by dropping the WAR (dashbuilder-runtime.war) in {WILDFLY_HOME}/standalone/deployments. By default it uses the root web context (“/”) and the other security domain, making it protected by default.

Dashbuilder Runtime login screen

Create a user with an admin role to login, it can be created using the add-user.sh utility:

Dashbuilder Runtime configuration

Dashbuilder Runtime can be customized using system properties and in this section we some general system properties.

Dashboards Path

When a dashboard is uploaded it is stored in the filesystem. The path where it will be stored is controlled by the system property “dashbuilder.import.base.dir”, which by default points to dir /tmp/dashbuilder

In fact, this system property is the root path for any dashboard model. For example, if there are multiple files on this path, the file can be imported by accessing Dashbuilder Runtime and passing a query parameter import with the name of the file that should be loaded, for example: runtime_host?import=sales_dashboard will attempt to load the file /tmp/dashbuilder/sales_dashboard.zip

Static Dashboard

If one wants the runtime instance to load a specific dashboard then one just needs to use the system property dashbuilder.runtime.import. Just set this property pointing to a local file path and it will be loaded during Runtime startup.

Controlling upload size

Application servers usually control POST requests size, but is also possible to control the size of uploaded dashboards using the system property dashbuilder.runtime.upload.size. The size should be in KB and by default the value is 96kb, meaning that if someone tries to upload a file bigger than 96kb then an error will be displayed and the dashboard won’t be installed.

Loading external dashboards

Dashboard is in a public accessible URL that can be accessed by Dashbuilder Runtime. Just pass the URL using the import query parameter, for example, runtime_host?import=http://filesHost/sales_dashboard.zip. For security reasons this option is disabled by default and it is possible to enable it by setting the system property “dashbuilder.runtime.allowExternal” as true.

Conclusion

In this article, we introduced Dashbuilder Runtime. In the next posts we will cover more features such as Multi Dashboards and Embedding pages.