¶ Reports
This page describes how to use the reporting engine within the IoT Bridge to visualize and organize data within the IoT Bridge. Reporting is a powerful tool within the IoT Bridge to collect data from devices and provide simple, yet effective dashboards showing the health of your devices.
¶ Reports for device management
Here are some ideas for information you may wish to collect in reports.
- Network signal and connectivity data, for example the network, RSSI, BER, and other related information.
- Device firmware/software versions
- Battery voltage/percentage
- Operating environment (temperature, etc)
¶ What is a report?
A report is a living list of entries that have one or more fields that contain values that can be either a string, number, or timestamp. A report can have one or more aggregations to analyze and roll up data from fields to provide a visual representation of the data.
¶ Entries
Report entries are the rows in a report, typically each row will represent a device. Entries are visible on the Report details view.
¶ Fields
Fields represent the columns of data associated with each Entry (row). Only the latest value for each field is stored in the report, publishing the Field multiple times for the same Entry will overwrite previous values.
¶ Aggregations
Aggregations are summaries of the Field data from Entries. There are two main aggregation types available: terms and range. Aggregations can optionally by pivoted on string Fields providing another dimension to the report.
¶ Pivoting aggregations
Assume that we have a report with temperature and customer fields on each entry. Performing a simple range aggregation on the temperature field, it would provide an aggregation like this:
If we add a pivot on the customer field, the aggregation will now look like:
As you can see, it is quick and easy to build out useful and complex reports related to your devices in the field.
¶ Report dialog
The report dialog allows you to create and edit reports by managing the fields and aggregations
¶ Main dialog
- Report name: The report name, this is purely informational.
- Report key: The key for the report, this is used by triggers that want to publish data to reports using
report.publish(). - Tags: Key/value pairs to help organize reports.
- Fields: At the top level, you can add multiple fields, each field will show as a tab on the right side of the dialog.
- Add field: Adds a new field.
- Delete field: Removes the currently selected field.
- Name: The name of the field, this is used during presentation.
- Key: the key for the field, this is used when publishing from triggers.
- Data type: The data type for the field. Possible values are
number,string, andtimestamp. - Aggregations: Aggregations are associated with a particular field. See below
- Add aggregation (+ icon): Adds a new aggregation to the field.
- Edit aggregation: Edit an aggregation.
- Delete aggregation: Remove an aggregation from the field.
¶ Aggregation dialog
- Name: Name for the aggregation, this is used as the title of the graph.
- Pivot on field: Aggregations can be pivoted on another field, the field must have a type of
string. - Aggregation type: There are two types of aggregation,
rangewhich creates buckets to count entries based on anumberfield andtermsto count entries based on uniquestringfields. - Ranges: If the Aggregation type is
rangethen you must specify the range buckets for the aggregation.- Add range (+ icon): Adds a new range, the
fromandtovalue are evaluated inclusive of thefromvalue and exclusive of thetovalue. Ranges can overlap, and you may omit thefromor theto, but not both. - Edit range: Edit a range entry.
- Delete range: Remove a range entry.
- Add range (+ icon): Adds a new range, the
¶ Using reports in triggers
Reports get their data from triggers invoking the report.publish() function.
// publish fields 'temperature' and 'humidity' for the device
report.publish('env_report', event.endpoint.key, event.ts, { values: { temperature: 26.5, humidity: 53}})
// publish fields and set the name for the entry in the report
report.publish('env_report', event.endpoint.key, event.ts, { name: 'my device', values: { temperature: 26.5, humidity: 53}})
// publish location with entry
report.publish('env_report', event.endpoint.key, event.ts, { location: {lat: -45.23, lon: 80.123}, values: { temperature: 26.5, humidity: 53}})
¶ Trigger Actions
¶ report.publish(reportKey, key, ts, data)
Create or update an entry. data supports name, location, and a values object. Only the latest value for each field is retained.
¶ report.clone(oldKey, newKey, newName)
Clone a report definition to a new key and name. Entries are not copied.
¶ report.entryDelete(reportKey, key)
Delete one report entry.
¶ report.findEntry(reportKey, entryKey)
Return one entry and its report definition:
{
"entry": {},
"report": {}
}
¶ report.listEntries(reportKey, query[, sort][, limit])
Return {entries: [], report: {}}. query uses the platform query-string syntax, sort defaults to -ts, and limit defaults to 100 with a maximum of 200.
var result = report.listEntries('env_report', 'values.customer==acme', '-ts', 50)
¶ report.reset(key)
Delete all entries for the report while retaining its definition.
¶ Trigger Events
¶ report-operation
Generated when a user invokes a configured report operation other than the built-in setValue operation.
- reportKey: Report key.
- operationKey: Selected operation key.
- operationInputs: Values entered for the operation.
- entry: Selected report entry, including
name,key, andts.
¶ What's coming in the future for reports?
- More graph types (pie, map, etc)
- Geospatial reports
- Exporting reports as CSV and PDF
¶ Billable events
The following events are considered billable:
- Calls to
report.publish()