generate report

Generates a report based on a report template. The report is generated by creating a “Report generation” task in the task manager, which generates the report asynchronously. Once the report is generated, its ID is added to the message metadata under the reports key, and the message is routed to either the Success connection (if the report was successfully generated) or the Failure connection (if an error occurs during generation).

Report template required: Before using this node, ensure that a report template has been created in ThingsBoard. The report template defines the structure and content of the generated report.

Configuration

The node supports two operating modes for obtaining report configuration:

1. Report config from message - The node extracts all report settings from the incoming message data. This mode is useful when report parameters are determined dynamically.

2. Report config from node settings - The node uses report settings specified directly in its configuration form. This mode is suitable when generating reports with static, predefined parameters.

The operating mode is controlled by the Use report config from message checkbox.

Configuration fields

When Use report config from message is disabled, the following configuration fields become available:

General report settings

• Report template (required) - The report template to use for generating the report. Select from available report templates in your tenant. When Use report config from message is enabled, this value is read from the reportTemplateId field in the incoming message data.

• User (required) - The user whose credentials will be used to generate the report. This determines access permissions and data visibility during report generation. When Use report config from message is enabled, this value is read from the userId field in the incoming message data.

• Timezone (required) - The timezone in which the report will be generated (e.g., “America/New_York”). This affects how timestamps and time-based data are displayed in the report. When Use report config from message is enabled, this value is read from the timezone field in the incoming message data.

Recipients

• Notification targets - Set of notification targets to notify when the report is generated. Leave empty if no notifications should be sent. When Use report config from message is enabled, this value is read from the targets field (array of UUIDs) in the incoming message data.

• Notification template - The notification template to use for sending notifications about the generated report. Only applicable when notification targets are specified. When Use report config from message is enabled, this value is read from the notificationTemplateId field in the incoming message data.

JSON Schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TbGenerateReportV2NodeConfiguration",
  "type": "object",
  "properties": {
    "useConfigFromMessage": {
      "type": "boolean",
      "description": "Whether to read report configuration from the incoming message.",
      "default": false
    },
    "config": {
      "type": "object",
      "description": "Report configuration (used when 'useConfigFromMessage' is false).",
      "properties": {
        "reportTemplateId": {
          "type": "object",
          "description": "Report template identifier.",
          "properties": {
            "entityType": {
              "type": "string",
              "const": "REPORT_TEMPLATE"
            },
            "id": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "entityType",
            "id"
          ]
        },
        "userId": {
          "type": "object",
          "description": "User identifier.",
          "properties": {
            "entityType": {
              "type": "string",
              "const": "USER"
            },
            "id": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "entityType",
            "id"
          ]
        },
        "timezone": {
          "type": "string",
          "description": "Timezone for report generation.",
          "example": "Europe/Kiev"
        },
        "targets": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Set of notification target UUIDs."
        },
        "notificationTemplateId": {
          "type": "object",
          "description": "Notification template identifier.",
          "properties": {
            "entityType": {
              "type": "string",
              "const": "NOTIFICATION_TEMPLATE"
            },
            "id": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "entityType",
            "id"
          ]
        }
      },
      "required": [
        "reportTemplateId",
        "userId",
        "timezone"
      ]
    }
  },
  "additionalProperties": false
}

Message processing algorithm

1. The node determines the report configuration source:
   • If Use report config from message is enabled, extracts the report configuration from the incoming message data
   • Otherwise, uses the report configuration specified in the node settings

2. The node creates a report generation task using the configuration from step 1.

3. The report generation task is submitted to the task manager for asynchronous processing.

4. When the report generation completes, the generated report ID is added to the message metadata:
   • The generated report ID is added to the reports metadata field
5. The updated message is forwarded via the appropriate connection:
   • Success if the report was successfully generated
   • Failure if an error occurred during report generation

Output connections

• Success
  • The report was successfully generated. The outgoing message includes the generated report ID in the reports metadata field.
• Failure
  • An error occurred during report generation, such as:
    • Invalid or missing report configuration
    • Report template not found
    • User not found
    • Failed to generate the report
    • Failed to submit task to the task manager

Examples

Example 1 — Generate report using node settings

Incoming message

Any message.

Node configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "useConfigFromMessage": false,
  "config": {
    "reportTemplateId": {
      "entityType": "REPORT_TEMPLATE",
      "id": "31815190-a35d-11f0-84cf-d3d34cbac472"
    },
    "userId": {
      "entityType": "USER",
      "id": "f5e2b870-a2d7-11f0-b6e3-69416924d372"
    },
    "timezone": "America/New_York",
    "targets": [
      "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4"
    ],
    "notificationTemplateId": {
      "entityType": "NOTIFICATION_TEMPLATE",
      "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
    }
  }
}

Outgoing message

A message that is a complete copy of the incoming message, with the generated report ID added to the reports metadata field:

1
2
3
{
  "reports": "7f8e9d0c-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
}

Routed via the Success connection.

Result

A report generation task is created and processed asynchronously. Once complete, the generated report ID is added to the message metadata, and notifications are sent to the configured targets.

Example 2 — Generate report using message configuration

Incoming message

1
2
3
4
5
6
7
8
9
10
11
{
  "reportTemplateId": {
    "entityType": "REPORT_TEMPLATE",
    "id": "42916201-b46e-22g1-95dg-e4e45dcbd583"
  },
  "userId": {
    "entityType": "USER",
    "id": "06f3c981-b3e8-22g1-c7f4-7a527835e483"
  },
  "timezone": "America/New_York"
}

Node configuration

1
2
3
4
{
  "useConfigFromMessage": true,
  "config": null
}

Outgoing message

A message that is a complete copy of the incoming message, with the report job ID added to the reports metadata field:

1
2
3
{
  "reports": "8g9f0e1d-2b3c-4d5e-6f7a-8b9c0d1e2f3a"
}

Routed via the Success connection.

Result

A report generation job is created using the configuration provided in the message data. The report will be generated asynchronously without sending any notifications (since no targets were specified).