Editing report templates
Prerequisites
- Create a report template
- Access to the Settings App
Editing reports
- open the Settings app.
- click on the "Report templates " entry in the navigation menu.
- select the report template you want to edit from the list. The following operations are now available to you:
| Operation | Description |
|---|---|
| The details of the report template can be called up and edited. | |
| Archive | Report templates that are no longer required can be archived. |
Details of the report template
Click on the icon to display the details of the report template.
General information
After creating the report template, you can make further settings, including name and location.
| Keyword | Description | Example |
|---|---|---|
Name |
A simple text field for entering the name of the report template. | Weekly report |
Location |
A search field for entering the location. | Heidelberg |
Configuration
This section describes the various configuration options for reports. You can define the time and time span for data collection, determine the retention period for reports and define or overwrite user-defined variables for report creation.
Time and time span
The time period of the data for the report is determined from the properties 'Time point' and 'Time period', whereby 'Time point' represents the end of the time period from which the selected 'Time period' is subtracted.
Example
An example is used to illustrate the function of the settings 'Time point' and 'Time span'.
| keyword | value | description |
|---|---|---|
Time |
00:00:00 | The start time of the report. |
Time span |
1 day | The time span that a report generated from this template covers retrospectively from the start time. |
The 'Time' setting defines the start time of the report. In our example, a report generated from this template starts at 00:00:00.
The 'Time span' setting determines how far back a report generated from this template collects data. In this case, a report generated from this template collects data for a period of one day.
Based on these settings, a generated report from this template is generated on 13.01.2023 at 00:00:00 and covers the period from 12.01.2023 at 00:00:00 to 13.01.2023 at 00:00:00.
Storage
The 'Retention' setting determines how long individual reports are retained. Once the set retention period has expired, a report generated from this template cannot be requested again and all download links lose their validity.
Report variables
Under the Variables tab in the configuration settings of the report, the user can define layout variables for report creation, overwrite panel-specific variables or add their own variables.
A list of the available report variables can be found here.
Creating and overwriting report variables
After selecting the "Edit" option, you can define specific report variables by clicking on "Add new variable". There are two types of variables that you can create:
| Variable type | Description |
|---|---|
| Layout variables | Variables of this type only apply to the m2v app. |
| Parameters (panel-specific variables) | Variables of this type automatically overwrite variables of the same name in the Grafana dashboard. |
In the report settings, you can overwrite all variables defined in Grafana regardless of their type. This makes it possible, for example, to adjust the aggregation period, the aggregation function or other variables used for different purposes without having to create a new dashboard.
Please note that these overrides only apply to the creation of the respective report and have no effect on the display of the dashboard or other reports based on the dashboard.
Example
Suppose you want to change the aggregation function to average and group the data over a period of five minutes. In this case, you would need to add two new variables and select the type 'parameter' for both.
The name of the variable determines the Grafana variable to be overwritten, in this case aggrFunction and selectedInterval. The value of aggrFunction is set to mean and the value of selectedInterval is set to 5m.
Variable configuration:
| type | variable | value |
|---|---|---|
Parameters |
aggrFunction | mean |
Parameters |
selectedInterval | 5m |
After you have clicked on "Save", the new report can be generated. You can view the result here.
Prioritization of report variables
Note
For technical reasons, a new temporary dashboard must be created for an overwritten variable. This dashboard is deleted again after successful report generation.
Report variables are always prioritized as follows during report creation:
| Priority | Source | Description |
|---|---|---|
| 1 | Report settings | Variables that are defined here have the highest priority. |
| 2 | Grafana | Variables defined in Grafana have the second highest priority. |
| 3 | Default values | If no variables have been defined in the report settings or in Grafana, the default values are used. |
This means that the variables defined in the report settings have a higher priority than the variables defined in Grafana and the default values.
Task planning
Here the user can plan when a report generated from this template should be created.
By default, reports are generated every day at 00:00 (12:00 AM). The setting Disabled in the drop-down menu deactivates the automatic generation of the report.
Example
The configuration for a report that is only generated every Monday (weekly) at 00:00 (12:00 AM) looks like this:
Cron syntax
The cron syntax is used to define schedules for the repeated creation of reports. A typical cron schedule consists of five fields separated by spaces.
| Field | Description | Possible values |
|---|---|---|
| minutes | Specifies the minute at which the command is to be executed. | 0-59 |
| Hours | Specifies the hour at which the command is to be executed. | |
| Day-of-month | Specifies the day of the month on which the command is to be executed. | |
| Month | Specifies the month in which the command is to be executed. | 1-12 or Jan, Feb, Mar, etc. |
| Day of week | Specifies the day of the week on which the command is to be executed. | 0-7 (0 and 7 stand for Sunday) or Sun, Mon, Tue, etc. |
Our implementation also uses a sixth digit at the beginning for the seconds.
The fields can be defined in different ways:
- A single number: The command is only executed at this specific time.
- Multiple numbers separated by commas: The command is executed at the specified times.
- A range of numbers separated by a hyphen: The command is executed at all times within this range.
- The asterisk (*) as a placeholder: It stands for every possible number and means that the command is executed at every minute/hour/day/month/day of the week.
Example
m2v cron syntax:
seconds minutes hours day-of-month month day-of-week
Suppose you want to create a report every day at 6 am. The cron time specification for this would be
0 0 6 * * *.
0stands for the second in which the command is to be executed (at the beginning of each minute).0stands for the minute in which the command is to be executed6stands for the hour in which the command is to be executed (6 a.m.).- The first
*stands for the day of the month and means that the command will be executed on every day of the month. - The second
*stands for the month and means that the command will be executed every month. - The third
*stands for the day of the week and means that the command is executed on every day of the week.
Overall, this cron time specification therefore means that the command is executed every day at 6 am.
For visual support when creating cron times, you can use Crontab Guru. Please note that Crontab Guru does not support seconds.
Archive
You can archive the selected report by clicking on . Please note that you must first confirm this action.