Stroom – report

Docs: Report Settings

Wed, 02 Sep 2026 00:00:00 +0000

The Settings tab controls what kind of file the report produces and what goes in it, and holds the feed that execution errors are written to.

An Analytic Rule has a Settings tab of its own, holding what the rule declares about itself. A report has none of those settings, because it delivers a file rather than detections.

File Type

Field	Description
File Type	The format of the file the report produces.

Four formats are available.

Format	Notes
CSV	Comma delimited. For something else to read.
TSV	Tab delimited. For something else to read.
Excel	Includes an additional Info sheet recording the report name, description, and execution times.
Markdown	For a person to read.

Choose Excel or Markdown where a person will read the report, and CSV or TSV where something else will consume it. The Excel Info sheet is worth knowing about, because it is where the recipient can see which period the report actually covers.

Send Empty Reports

Field	Description
Send Empty Reports	Whether a report whose query returned no rows is still delivered.

There is a real choice here. Delivering empty reports means the recipient knows the report ran and there was nothing to say, rather than being left to wonder whether it failed. Suppressing them avoids a stream of empty files for a report that is usually quiet.

Only emptiness suppresses delivery. A report that returned rows is always delivered however this is set, and a report that is suppressed is still recorded in the execution history as having run.

Note

The default is to deliver empty reports.

AI Summary

A report can ask a model to summarise the data it produced and deliver that summary with the report.

Field	Description
AI Summary	Whether to ask a model to summarise the report’s data.
AI Summary Model	The model to ask. Where this is not set, the model configured for Ask Stroom AI is used.
AI Summary Prompt	What to ask about the data. Where this is not set, a default prompt asks for a short summary of what the data shows and anything worth attention.

Where the summary ends up depends on the file type, since CSV and TSV cannot carry prose without breaking them for whatever reads them.

File Type	Where the summary goes
Excel	An AI Summary sheet.
Markdown	An AI Summary section after the table.
CSV, TSV	A separate Markdown file delivered alongside the report.

The summary is also available to email templates as aiSummary and is recorded as a ReportAiSummary entry in the stream meta where the report is delivered to a feed.

Note

The report is what the recipient is waiting for, so a model that is unavailable, slow or misconfigured costs the summary and nothing else. The failure is logged and the report is delivered without a summary.

Warning

AI summaries are a preview feature and are subject to breaking changes in future releases. Using a model requires the Use permission on the model document rather than the ability to read it.

Feed for Errors

Field	Description
Feed For Errors	The Feed that errors occurring during execution are written to. Use Set Default to use the feed configured for the system.

Docs: Report Delivery

Wed, 02 Sep 2026 00:00:00 +0000

The Notifications tab of a Report works in the same way as it does for an Analytic Rule, with the same two destination types and the same limit settings. The difference is what gets delivered. A rule delivers a detection, whereas a report delivers the file it produced.

A report can have several notifications, so the same report can be emailed to a distribution list and written to a feed for retention at the same time.

Email Delivery

The report is sent as an attachment, with the subject and body rendered from the notification’s templates.

Where the report is a CSV or TSV and an AI summary was produced, the summary is attached as a second file rather than being packed into an archive, so the recipient does not have to unpack anything.

The file name is derived from the report name and the effective execution time, so a recipient who keeps several editions can tell them apart.

Template Context

Report email templates use the same Jinja syntax as rule detection templates but have a completely different set of variables available, because a report is not a detection.

Variable	Description
`reportName`	The name of the Report .
`description`	The content of the report’s Documentation tab.
`executionTime`	The wall clock time at which the report ran.
`effectiveExecutionTime`	The point in time the report covers.
`rowCount`	The number of rows in the report.
`fileType`	The format of the attached file.
`fileName`	The name of the attached file.
`aiSummary`	The AI summary, or an empty string where there is none.

aiSummary is always present so that a template using it renders whether or not a summary was produced.

Note

None of the detection variables, such as detectTime, headline or values, are available to a report template. A template written for an Analytic Rule will not work on a Report.

Feed Delivery

A Stream notification writes the report into a Feed as a stream of type Report.

The stream carries the report file itself, unchanged, so anything already reading those streams is unaffected by settings such as the AI summary. The following entries are written to the stream Metadata .

Meta Key	Description
`ReportName`	The name of the report.
`ReportDescription`	The content of the report’s Documentation tab.
`ExecutionTime`	The wall clock time at which the report ran.
`EffectiveExecutionTime`	The point in time the report covers.
`ReportAiSummary`	The AI summary, where one was produced.

Writing reports to a feed is how you retain a record of what was reported and when, independently of whoever received the email.

Note

Use Source Feed If Possible has no effect on a Report, as it only applies to streaming Analytic Rules. Reports are always written to the Destination Feed.

Limiting

The Limit Notifications, Maximum Notifications and Resume Notifications After settings behave exactly as they do for an Analytic Rule.

They are far less likely to matter for a report, because a report produces one file per run rather than one notification per matching row.

Docs: Reports

Wed, 02 Sep 2026 00:00:00 +0000

A Report runs a query on a schedule and turns the results into a file, which is then delivered to the people or the Feed you nominate.

Where an Analytic Rule turns each row of its query into a separate detection, a Report turns the whole result table into a single document. Use a Report when somebody wants a periodic summary of what the data shows, and an Analytic Rule when somebody needs telling about individual things as they are found.

How a Report Relates to an Analytic Rule

Reports and Analytic Rules are built on the same machinery and share most of their configuration. Anything documented for Analytic Rules applies to Reports unless stated otherwise here.

Tab	Difference from an Analytic Rule
Query	The same, except that the table preferences you set also shape the file produced, see Query.
Settings	Reports only, see Report Settings.
Notifications	The same destinations, but they deliver a file rather than a detection, see Delivery.
Execution	Identical, see Execution.
Documentation	Included in the report’s Excel info sheet and available to email templates.

The Processing Type on a Report’s Execution tab offers only Scheduled Query. Reports are always run on a schedule, so there is no streaming or table builder equivalent. They also have no Duplicate Management tab, because a report is a periodic summary and is expected to repeat.

The Query

The Query tab works as it does on an Analytic Rule, with one important difference.

The table preferences you set by interacting with the results, such as hidden columns, value formats and sort order, are stored on the report and applied when the report is generated. What you see in the results table while developing the query is therefore what the recipient will get.

Relative date expressions resolve against the report’s effective execution time rather than the current clock time, which is what allows a report for last month to be produced correctly today.

Jobs

Reports are run by the Reports job, which is disabled by default. A report will not run until that job has been enabled in

The job controls how often Stroom looks for report schedules that are due, not how often a report is produced.

Configuration

Reports use the same stroom.analytics configuration as Analytic Rules, including the SMTP settings that email delivery depends on, see Email Setup.

The defaults offered in the UI for the processing node, error feed and destination feed come from stroom.ui.reportUiDefaultConfig rather than from the equivalent analytics property.

Docs: Email Setup

Wed, 02 Sep 2026 00:00:00 +0000

Stroom sends email for two things, Analytic Rule notifications and Report delivery. Neither will work until an SMTP server has been configured.

This step is only needed if you intend to use email notifications. An installation whose rules only write detections to a Feed does not need it.

Note

There is no email configuration in the user interface. It is set in config.yml and applies to the whole installation, so rule authors cannot configure it themselves.

Configuration

Email is configured under the appConfig.analytics.emailConfig branch.

appConfig:
  analytics:
    emailConfig:
      fromAddress: "noreply@stroom"
      fromName: "Stroom Analytics"
      smtp:
        host: "localhost"
        port: 2525
        transport: "plain"
        username: null
        password: null

Property	Description
`fromAddress`	The address that Stroom sends from, and that replies will go to.
`fromName`	The display name shown against the from address.
`host`	The Fully Qualified Domain Name (FQDN) of the SMTP server.
`port`	The port of the SMTP server.
`transport`	How Stroom talks to the SMTP server, see below.
`username`	The user to authenticate as, or `null` for an unauthenticated server.
`password`	The password to authenticate with, or `null` for an unauthenticated server.

The from address and name are set here rather than on each rule, so every email Stroom sends comes from the same place. It is worth choosing an address that is monitored, or one that makes clear that replies will not be read.

Transport

Value	Meaning
`plain`	Plain SMTP with no transport security. This is the default.
`TLS`	SMTP over TLS.
`SSL`	SMTP over TLS. Treated identically to `TLS`.

Warning

Any value other than TLS or SSL is treated as plain, including a misspelling. A typo here will silently send mail unencrypted rather than failing, so it is worth confirming the setting took effect by checking the traffic or the mail server's logs.

Testing

The quickest way to confirm the configuration works is from a rule rather than from the server.

Open or create an Analytic Rule .
On the Notifications tab, add a notification with a Destination Type of Email and put your own address in the To field.
Click Send Test Email.

This sends an example detection through the whole path, so a message arriving proves the SMTP settings, the from address and the templates all work.

Where it fails, the error is reported in the user interface. Errors from real rule executions go to the rule’s error feed instead.

Stroom – report

Docs: Report Settings

File Type

Send Empty Reports

Note

AI Summary

Note

Warning

See Also

Feed for Errors

See Also

Docs: Report Delivery

Email Delivery

Template Context

Note

See Also

Feed Delivery

Note

Limiting

See Also

Docs: Reports

How a Report Relates to an Analytic Rule

The Query

See Also

Jobs

See Also

Configuration

Docs: Email Setup

Note

Configuration

Transport

Warning

Testing

See Also