SINCE VERSION 7.0

What is the Reporting Framework?

PIPEFORCE comes with a reporting framework you can integrate into your applications or use them to build your own developer or admin reports.

Such reports can be used to give insights into your data for you and your users.

Similar to the forms framework, reports can be created using the low code. This means no in-depth developer knowledge is required.

However, in order to create reports with this reporting framework, it is important that you're familiar with the concept of Automation Pipeline and Commands. If not, please follow the link to read more about it and then come back to this guide.

Each report always consists of two main components:

• One or more pipelines, providing the reporting data.

• A chart in order to visualize the reporting data.

Available Charts​

To visualize the data of a report, PIPEFORCE uses the library Chart.js. This library provides many different types of charts. You can find live examples on the Chart.js website: https://www.chartjs.org/docs/latest/samples.

Here are some examples of such charts that can be used inside PIPEFORCE:

​

Open

Vertical Bar Chart​

Open

Stacked Bar Chart​

​

​

Creating a static chart​

Each app can have multiple reports, each report is visualized by one chart. In order to create such a report chart, you have to create a new property of mime type application/json inside this path:

Replace io.pipeforce.myapp by the name of the app you would like to place the report within and myreport by the name of your report.

The report configuration has this main format:

Except title and description, this configuration is a 100% Chart.js configuration file meaning, you can use the full power of this library here. See here for a full reference about the configuration options.

The main sections are:

• title - Is the title to be displayed for the report.

• description - Is the description of the report.

• type - The type of the chart to be displayed. Please refer to the Chart.js sample documentation and select the key of the chart you would like to display and replace CHART_TYPE by this key. Example keys are: line, bar, radar, doughnut, bubble and many more.

• data - Defines the data to be consumed by this chart. How this data structure looks like depends on the selected chart. Refer to the Chart.js documentation for the selected chart about it.

• options - This section defines configuration options for the selected chart.

There are also other configuration elements possible. Please have a look into the Chart.js documentation for a full reference.

Here is a full working chart configuration with static data:

Create a new report using the wizard in the apps section which will contain a JSON like the example above.

Go to the app and open the report.

You should then see a static chart example which looks similar to this:

Creating a dynamic chart​

In the previous chapter you have seen how to create a chart with static data. In this section you will learn how to make this report dynamic by loading dynamic data coming from a pipeline.

Its important to understand the concept, that all dynamic data for a chart is provided by a pipeline. Therefore, lets first create a simple pipeline which returns the data section for the chart:

As you can see, this pipeline simply returns the data part of the chart configuration also as static array. But since you're already familiar with the concept of commands and pipelines you can probably imagine the power of this: You can now call any appropriate command in order to load data from somewhere, for example from a SQL database, from a REST endpoint or any other data source, convert it into the data structure required by your chart and return it finally in the body.

Let's create a new pipeline using the wizard and save this pipeline under the app path where you have stored the reporting configuration before, for example: global/app/io.pipeforce.myapp/pipeline/piechartdata.

The last step is to link your chart configuration with your pipeline. To do so, replace your origin data section of your chart configuration:

by this new section:

As you can see, the static array [20, 40, 20, 10, 10] was replaced by an URI string, pointing to your pipeline: $uri:pipeline:global/app/io.pipeforce.myapp/pipeline/piechartdata.

The next time you reload your chart, it will load the data now from the pipeline. And since it is loaded from a pipeline, the data can be collected, transformed, enriched or prepared in any way the pipeline framework supports before they will be send to the chart.

This approach can also be used for the labels element to provide dynamic labels.

Caching report data​

Sometimes collecting and preparing the data for a report can be a long running task which takes a lot of time and processing power. In this situations you should consider to cache your reporting data.

To do so, you can use the pipeline commands cache.get and cache.put. Let's see the pipeline from the previous chapters extended by these caching commands:

As you can see, the command cache.get at the beginning of the pipeline first looks up an entry in the cache under key report:piechart. In case such an entry exists, the pipeline will exit, and the cache entry will be returned immediately.

Otherwise the pipeline will be executed, the report data generated and stored in the body.

Finally this data from the body will be put into the cache using the key report:piechart. The data will be kept for 30 minutes.

In case this pipeline will be run within the next 30 minutes, the data is returned from the cache.

Configuration Attributes

The Report Config is the main configuration file for a report. Here you can define the title, description, charts of the report and from where the report data should be loaded from.

In order to create a new report and show it as a new entry in your apps tiles listing, you have to add the report config as a new property to this path in the property store:

Whereas <reportname> is a lower-case and unique name for the report in a format supported by the property path.

The content type of the report config property must be application/json; type=report.

You can also create it in the web ui in section LOW CODE -> Properties using the Report wizard.

The most basic structure of this JSON document must be like this:

title

The title defines the title of the report to be displayed in the web ui and in other locations.

This can be a static text or an i18n uri like $uri:i18n:myTitle for example. See: Internationalization (i18n)

description

The description is optional and describes the intention of the report.

This can be a static text or an i18n uri like $uri:i18n:myDescription for example. See: Internationalization (i18n)

icon

Each report can have an individual icon. This value must be a code name from the Google Material Icons as listed here: https://fonts.google.com/icons

This value is optional. If not given, the default icon is shown.

color

The color of the report icon. If not specified, the secondary color is used, which depends on the style settings. By default this is a blue color like this:

The color value can be a hexadecimal value, like this:
"color": "#FFA500"

Or it can be a constant selected from the Colors palette.

For example you could use the color palette constant “green” like this:
"color": "green"

Another example:

"color": "red-8"

hidden

This optional attribute defines whether the report should be shown as tile inside the app ("hidden": false) or not ("hidden": true).

The list can be still loaded by its URL if required.

If this attribute is missing, "hidden": false is used as a default.

type

The type of the chart to be displayed. Please refer to the Chart.js sample documentation and select the key of the chart you would like to display. Example keys are: line, bar, radar, doughnut, bubble and many more.

data

Defines the data to be consumed by this chart. How this data structure looks like depends on the selected chart. Refer to the Chart.js documentation for the selected chart about it.

This data can be a static JSON embedded here, or a PIPEFORCE URI pointing to a pipeline or property as the data source.

options

This section defines configuration options for the selected chart as documented in Chart.js.