Reports
Built-in and custom report templates, the Report Builder, widgets, brand templates, scheduled delivery, and Community Reports.
Reports
On the Reports page at /reports you build, schedule and distribute reports about the fleet, from a device inventory to a patch-compliance summary or a custom SQL breakdown of job outcomes. The page also hosts the community report templates and the brand templates that give generated PDFs a consistent look.

11.1 The tabs
The page is organised into five tabs, selected across the top:
Templates: the library of report templates, both built-in and user-created. This is where you pick a template to generate, edit, share, or duplicate.Community: read-only report templates curated by NetLock (see 11.9).Generated: the list of already-produced reports, with filenames, timestamps, the template they came from, and download links for the output files.Schedules: the list of recurring report runs. Each row is a schedule attached to a template.Brands: brand templates that drive the cover page, colours, logo, and PDF footer of generated reports.
Everything starts from a template: you generate or schedule reports from it, attach a brand to it, and share it.
11.2 Templates
The Templates tab lists every report template you have access to. Two categories share the tab:
- Built-in templates ship with the product and are flagged with a
Built-inchip. AShow Built-incheckbox in the toolbar shows or hides them, so the list can be narrowed to your own templates. - Custom templates are created from the Templates tab's
Createaction, or by duplicating an existing template. They can be shared with other users via the Share Template dialog. A community template becomes a custom template when you copy it from theCommunitytab (see 11.9).
Each template has an Author, a creation date, a description, and a list of widgets that define what the generated report contains. Templates are edited in the Report Builder (covered next).
Template actions
Row actions on a template include:
- Generate: open the Generate Report dialog for a one-off run (see 11.6).
- Edit: open the template in the Report Builder.
- Duplicate: create a copy in your library, useful for editing a built-in without modifying the original.
- Delete: remove the template. Built-in templates cannot be deleted.
- Share: open the Share Template dialog to grant access to other users.
Recurring runs are created with New Schedule in the toolbar.
11.3 The Report Builder
The Report Builder at /reports/builder (and /reports/builder/{id} when editing an existing template) is where a template is authored. A template is a sequence of widgets; the Builder is the editor for that sequence.

Each widget is backed by a data source: a SQL query that produces the rows the widget shows. The Builder offers two modes for authoring that query: the Visual Query Builder and direct SQL. Both need SQL access (see below); the statements of the built-in templates run without it.
Visual Query Builder
The Visual Query Builder is the default mode. It shows the query as a set of form controls:
Table: the table to select from. The list contains exactly the tables the MySQL user for SQL access can read.Columns: the columns to include in the result, from the columns that user can read.Fn: aggregate function applied to a column. The supported aggregates areCOUNT,SUM,AVG,MIN,MAX, andDISTINCT.Joins: a list of joins, each with a join type, a right-hand table, and anONcondition.Where: the filter conditions, composed withAND/ORlogic. Supported operators:=,!=,<,>,<=,>=,LIKE,IN,IS NULL,IS NOT NULL.Logic: per-clause grouping between conditions.Op,Value: the operator and right-hand side for each condition.- Order-by and limit controls complete the query.
Filter by the report's tenants: on for a new query. The Builder adds the tenant condition for the base table:t0.tenant_id IN (@tenant_id)for a table with atenant_idcolumn,t0.device_id IN (SELECT id FROM devices WHERE tenant_id IN (@tenant_id))for a table with adevice_idcolumn, and the same throughaccess_keyfor a table with anaccess_keycolumn. The condition stands first in its own parentheses; your own conditions follow in theirs. A table without any of these columns cannot be filtered by tenant, and the editor says so. On older widgets the switch is off; turn it on to filter them by tenant.
The resulting SQL is composed by the Builder and stored on the widget.
SQL access and direct SQL
Own SQL (the SQL typed into the widget's SQL field and the SQL the Visual Query Builder generates, including the SQL of text parameters) runs only over a dedicated MySQL user that the administrator creates and enters under Settings → SQL access (/settings/sql-access). The grants of that user are the boundary of what such SQL can read. Setting it up is described in Set up SQL access for reports, dashboards and custom fields. On cloud instances SQL access is not available.
With SQL access configured, the Widget Editor offers the Visual Query Builder and the SQL field to every user who may create or edit the template (reports_create / reports_edit). In the SQL field you type the query directly, for queries the visual builder cannot express. On save, each own statement is checked with EXPLAIN over the report user: syntax, tables and columns it may read. When MySQL refuses the statement, its message is shown and the template is not saved. Queries run in a read-only transaction with a limit of 10 seconds per statement; user variables such as @rownum := @rownum + 1 are allowed.
The built-in templates and unchanged copies of them, imported ones included, run without SQL access. A changed or new statement needs SQL access, and so does a copy whose built-in statement an update has changed.
Without SQL access:
- own widgets show
SQL access not configuredinstead of data (in generated output[SQL access not configured]); - the Widget Editor shows a notice with a link to
Settings → SQL accessand offers neither the Visual Query Builder, the SQL field nor the AI SQL Assistant; - saving or importing a template that contains own SQL is refused.
The AI SQL Assistant button drafts a query from a natural-language description. The AI only writes into the editor; you still review and run the query yourself.
Placeholders. A query, including the SQL of a text parameter, may use these placeholders:
@date_fromand@date_toare bound as parameters to the date range the report runs for.IN (@tenant_id)is replaced, when the report runs, by the list of tenant ids the report is generated for, for exampleWHERE d.tenant_id IN (@tenant_id). Only this exact text is replaced:IN(@tenant_id),in (@tenant_id)or= @tenant_idstay as they are. For tables without a tenant column, filter through the devices of the tenants, for examplee.device_id IN (SELECT id FROM devices WHERE tenant_id IN (@tenant_id))ora.access_key IN (SELECT access_key FROM devices WHERE tenant_id IN (@tenant_id)). A widget whose SQL does not carry the placeholder in this form is left out of reports for selected tenants (see 11.10); the Widget Editor and saving point this out and offer the correction.@scope_unassignedis replaced by1=1in a report over all tenants and by1=0in a report for selected tenants. It is for rows that belong to no tenant, for example audit entries with an empty tenant:((@scope_unassigned AND tenant_name = '') OR tenant_name IN (SELECT name FROM tenants WHERE id IN (@tenant_id))). The built-in audit reports use it.@patch_scopeis replaced the same way by the scored predicate of the compliance scope ofPatch Management → Settings(see 7.4): sources, update types, severities, approval state, grace period and the exclusion of Defender security intelligence updates, evaluated at the time the report runs. It expects the update catalogdevices_available_updatesto be joined with the aliasdauand stands where a condition stands, for example... WHERE du.status = 'Available' AND @patch_scope. The built-in patch reports use it, so their compliance figures match the patch management page andGET /v1/patch-compliance. A query that carries@patch_scopewithout thedaualias fails with an unknown-column error; the placeholder is case-sensitive.
For the EXPLAIN check on save, IN (@tenant_id) stands in as IN (0), @patch_scope and @scope_unassigned as 1=1, and @date_from / @date_to are bound.
Both modes store their output in the same widget field, so a template can mix widgets authored in either mode.
Tip: Start in the Visual Query Builder. Switch to direct SQL only for what the visual builder cannot do, such as window functions, user variables or custom field values. A Visual Query Builder query is easier to read, review and hand over.
11.4 Widgets
A report is a sequence of widgets. Each widget is one of four types:
- Metric: a single number with a label. Use for headline figures: total devices, open incidents, unpatched criticals.
- Chart: a plotted series. Bar, line, and pie presentations are available depending on the widget configuration.
- Table: a tabular display of the rows the data source returns. The usual choice for inventory-style reports.
- Text: static markdown content, rendered in place. Use for narrative explanations, section headers within a report, or preamble paragraphs. The text can carry
{{tenant_name}},{{tenant_company}},{{date_from}}and{{date_to}}(see 11.10) and the{{key}}of its text parameters; a text parameter with one of these keys keeps its own value.

The Widget Editor
Each widget is authored and edited in the Widget Editor dialog. The dialog is divided between the widget's data source (handled via either the Visual Query Builder or direct SQL, as described in 11.3) and its presentation, with the controls for the chosen widget type (axes, colours, column order, label text). The data source controls are shared across all widget types except Text, which is purely markdown and has no query.
11.5 Brand templates
Brand templates at the Brands tab define how a generated report looks, independent of what it contains. A brand wraps the content of any template with a cover page and footer consistent with a specific customer, MSP unit, or product line.

The Brand Template dialog accepts:
- Company info: company name, address, contact details.
- Colours: primary and secondary colours used on the cover page and in section headers.
- Logo: the image shown on the cover page and (scaled) in the footer.
- Header text: the text line at the top of each generated page.
- Footer text: the text line at the bottom of each page.
- Custom fields: a list of key-value pairs rendered as cosmetic footer entries on the PDF cover page.
- Show custom fields in footer: a switch that controls whether those custom fields are rendered.
Custom Fields in reports
Important: The Report Builder does not offer Custom Fields as a data source, and the Visual Query Builder has no dropdown for them. In Reports, Custom Fields appear in one place only: as cosmetic key-value pairs on brand template footers.
To show Custom Field data in the body of a report, for example a table of devices and their
Asset Tagcustom field, write direct SQL against the underlying tables. This needs SQL access (see 11.3).
A brand template is attached to a report template via the Report Builder. One brand can back many templates; a template with no brand uses the default styling.
11.6 Scheduled delivery
The Schedules tab lists scheduled runs; each row attaches a template to a cadence and a distribution method. Schedules are created from the Schedule dialog.

Frequency
The frequency selector offers:
HourlyDailyWeekly, with a day-of-week picker (Sunday through Saturday).Monthly, with a day-of-month picker (1 through 28).Quarterly, with a day-of-month picker.Annually, with a day-of-month picker.
Day-of-month goes up to 28, so scheduled runs fire in every month. A "last day of month" option is not available.
Time
Time is expressed as Hour (0–23) and Minute (0–59), evaluated in the server's configured time zone.
Date range
The Date range selector controls the window of data the generated report covers:
Auto (based on frequency): schedules only; the window follows the schedule's frequency.Last 24 HoursLast 7 DaysLast 30 DaysLast QuarterLast Year
Output format
The Export format control selects how the generated report is rendered:
PDF: paginated with the brand template applied.HTML: single-file HTML, handy for embedding in a customer portal or emailing inline.CSV: raw row data; suitable for further processing.JSON: structured form; suitable for downstream automation.
Distribution
Scheduled runs deliver through one of two channels:
- Email: the schedule carries a
Recipientsfield (comma-separated addresses), aSubject, and aBody. The rendered report is attached to the message.Send to the report contacts of the tenantalso sends each report made for one tenant to the report contacts of that tenant (see 11.10), in a mail of its own. - Webhook: the schedule carries a
URL, an HTTPMethod(GET,POST,PUT,DELETE,PATCH),Request Headersas JSON,Request Bodyas JSON, and anAttach Filetoggle. WhenAttach Fileis on, the rendered report is sent as a multipart attachment; when off, only the request body is sent. A schedule that produces one report per tenant calls the webhook once per report.
Subject, body and the webhook request body can use {{tenant_name}}, {{tenant_company}}, {{date_from}} and {{date_to}}; in the webhook body the values are escaped for a JSON string.
The distribution is set per schedule, so the same template can back one email schedule and one webhook schedule.
Tenants
A schedule runs over All tenants (including new ones) or over selected tenants, as one combined report or as one report per tenant (see 11.10).
Status of a run
While a run produces its reports, the schedule shows running. The next run is set when a run starts. A server that stops in the middle of a run therefore does not start the same run again and sends no report twice. After the next start, such a run shows failed with a note, and the reports it had not produced yet are missing for that period. When some reports of a run fail and others succeed, the status is failed with n of m tenants failed and their names.
11.7 Output formats
Whether triggered from the Generate Report dialog or from a schedule, the output format is selected at run time:
| Format | Use |
|---|---|
PDF | Human-readable report with the brand template applied. The default for customer-facing output. |
HTML | Single-file HTML; renders in any browser and embeds in email bodies. |
CSV | Raw row data from each table widget. Strips charts and formatting. |
JSON | Structured representation of the report's data. Intended for downstream automation. |
PDF honours the brand template attached to the source template; the other formats ignore it.
11.8 Generating a report on demand
The Generate action on any template opens the Generate Report dialog for a one-off run.

Fields:
Template: pre-filled from the row you clicked.All tenants/Tenants: the tenants the report covers; all tenants by default (see 11.10).Reports: with several tenants,One report per tenant(the default) orOne combined report.Format:PDF,HTML,CSV, orJSON.Date range: the same options as scheduled delivery.Email: optional; if filled, the generated file is emailed to that address. Leave it blank to only produce the file (it appears on theGeneratedtab). WithAlso send to the report contacts of the tenant, a report made for one tenant also goes to that tenant's report contacts. Every recipient gets a mail of its own.
11.9 Community Reports
The Community tab of the Reports page lists report templates curated by NetLock. They are read-only. Each row offers two actions:
- Generate: make a report from the community template directly.
- Copy to my templates: create a custom template from it.
Copied templates are normal custom templates that you can edit, schedule and delete. Report templates cannot be published to the community from the console.
11.10 Reports per customer
A report can be made for one customer (tenant), for several, or for all tenants, on demand and on a schedule.
Choosing the tenants. The Generate Report dialog, the Schedule dialog and the preview of the Report Builder offer All tenants and the tenants that exist. With several tenants, One report per tenant makes a separate report for each of them; One combined report makes one report over all of them. On demand, one report per tenant is limited to 25 reports per run and the files are downloaded as one ZIP file. A schedule over All tenants (including new ones) with one report per tenant also covers tenants created after the schedule was saved. Tenants being deleted are left out.
What the customer sees. A report for one tenant names it on the cover page and in the PDF header as Customer: Company (Name) (the company only when it is set), and in the HTML, CSV and JSON output. The file name is <template>_<tenant>_<date>_<time>.<extension>. A report over all tenants names no customer.
Widgets that do not filter by tenant. A report for selected tenants (anything other than all tenants) leaves out every widget whose SQL does not carry IN (@tenant_id) exactly (see 11.3), so it never shows data of other customers. The Templates tab marks such templates with Partly tenant-filtered, the Generate and Schedule dialogs name the widgets before the report is made, and after an on-demand run the dialog lists what was left out. In a report over all tenants every widget runs.
Templates that describe the whole instance. A template marked Whole instance (for example Policy Assignment Overview, which lists every policy) is generated over all tenants only, as one combined report. Copies of it are treated the same way.
Built-in templates. The built-in templates filter by tenant. Update Approval Status Report counts the updates pending on the authorized devices of the report's tenants (each update once, however many devices it is pending on), also in reports over all tenants. The audit reports (Admin Activity Audit, Configuration Change Audit, Device Authorization Audit, the change history of Policy Assignment Overview) include entries without a tenant (logins, settings changes) only in reports over all tenants. The failed logins of Remote Access Audit are left out of reports for selected tenants.
Report contacts. Each tenant can carry a list of report contacts in its tenant settings (Chapter 4.3). A schedule with Send to the report contacts of the tenant sends every report made for exactly one tenant to that tenant's report contacts, in a mail of its own, so they do not see the other recipients. Combined reports over several tenants are not sent to report contacts. Addresses in Recipients (for example your own team) receive every report.
Text variables. Text widgets, mail subject and body and the webhook body can use {{tenant_name}} (the tenant's name; All tenants over all tenants; the names when a report covers several tenants), {{tenant_company}}, {{date_from}} and {{date_to}} (yyyy-MM-dd).
Generated tab. The Tenants column shows the tenants each report covers (All tenants, a tenant, or the first tenant and +n); a tenant deleted since appears as Deleted tenant #id. The tenant filter in the toolbar shows the reports of a tenant, including reports over all tenants. Reports made for one tenant only are deleted together with that tenant; a deleted tenant is removed from the selection of a schedule, and the schedule is switched off when no tenant is left.
Accounts with access to some tenants. An account without access to all tenants (Chapter 14.5) chooses among its own tenants; All tenants is not offered, and all of its tenants are selected at the start. Generated reports and schedules that cover other tenants, or all tenants, are shown with a lock; the account cannot download, change or delete them. A schedule reports on no more than the tenants of the account that created it, at the time of each run; a schedule whose creator was deleted, or has none of its tenants, does not run.
Tip: One report per tenant multiplies the work of a run by the number of tenants. Schedule large per-tenant runs outside working hours.
11.11 Dialogs
The Reports page and its Builder share a set of dialogs:
| Dialog | Purpose |
|---|---|
| Generate Report | Run a template once, with tenants, format and date range. |
| Schedule | Create or edit a recurring run with tenants and distribution settings. |
| Widget Editor | Add or edit a single widget (metric, chart, table, or text). |
| Share Template | Grant other users access to a template. |
| Brand Template | Create or edit a brand (cover, colours, logo, footer). |
| Import Template | Import a template from a JSON file. |
| Delete Confirm | Confirm deletion of a template, schedule, or brand. |
Permissions
| Flag | Gates |
|---|---|
reports_enabled | Opening the Reports page. |
reports_create | Creating a template. |
reports_edit | Editing a template. |
reports_delete | Deleting a template. |
reports_generate | Running the Generate Report dialog, including the choice of tenants. |
reports_schedules | Creating or managing schedules, including their tenants. |
reports_brand_templates | Managing brand templates. |
Own SQL and the Visual Query Builder additionally need SQL access, configured under Settings → SQL access by an account with settings_sql_access (see 11.3).
See Appendix X.2 for the full permission catalogue.
Related chapters
- Chapter 8.4 — Custom Fields covers where Custom Fields live in the product and how to read their values via SQL when you need them inside a report body.
- Chapter 12 — Events & Audit is the source for generating event-oriented reports.
- Part III — How-To Guides includes a step-by-step for running a compliance report and scheduling email delivery.
- Set up SQL access for reports, dashboards and custom fields covers the MySQL user that own SQL runs over.