...

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.

...

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

...

• 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:

​

...

​

...

​

...

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:

global/app/io.pipeforce.myapp/report/myreport

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.

...

{
  "title": "Pie chart example",
  "description": "My first PIPEFORCE report",
  "type": "pie",
  "data":  {
    "labels": ["Red", "Orange", "Yellow", "Green", "Blue"],
    "datasets": [
      {
        "data": [20, 40, 20, 10, 10],
        "backgroundColor": ["#4dc9f6", "#f67019", "#f53794", "#537bc4", "#acc236"]
      }
    ]
  },
  "options": {
    "responsive": true,
    "plugins": {
      "legend": {
        "position": "top"
      },
      "title": {
        "display": true,
        "text": "Pie Chart"
      }
    }
  }
}

Create a new property using the property editor, for example under global/app/myapp/report/piechart:

...

Copy the configuration from above as content to this property and save it. Then go to All Apps -> myapp -> Pie chart example. 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.

...

pipeline:
  - set.body:
      value: [2050, 40, 20, 10, 1050]

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:

...

  "data":  {
    "labels": ["Red", "Orange", "Yellow", "Green", "Blue"],
    "datasets": [
      {
        "data": "$uri:pipeline:pipeline.start?key=global/app/io.pipeforce.myapp/pipeline/piechartdata",
        "backgroundColor": ["#4dc9f6", "#f67019", "#f53794", "#537bc4", "#acc236"]
      }
    ]
  },

As you can see, the static array [20, 40, 20, 10, 10] was replaced by a an URI string, pointing to your pipeline: $uri:pipeline:pipeline.start?key=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.

...

pipeline:

  - cache.get:
      key: "report:piechart"
      exit: true

  - set.body:
      value: [20, 40, 20, 10, 10]

  - cache.put:
      timeToLive: 30
      key: "report:piechart"
      value: "#${body}"

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.

...

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:

global/app/<appname>/report/<reportname>

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 of your report",
  "description": "Description of your report",
  "type": "CHART_TYPE",
  "data" : {...},
  "options": {...}
}

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.