A Report runs a query on a schedule and turns the results into a file, which is then delivered to the people or the FeedFeed
A Feed is a means of organising and categorising data in Stroom. A Feed contains multiple Streams of data that have been ingested into Stroom or output by a Pipeline. Typically a Feed will contain Streams of data that are all from one system and have a common data format.
Click to see more details... 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.
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.
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.
1 - Report Settings
The file type a report produces, whether empty reports are sent, and AI summaries.
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.
Comma Separated Values is a file format with typically one record per line and fields delimited by a ,. Fields may be optionally enclosed with double quotes, though there is no fixed standard for CSV data, particularly when it comes to escaping of double quotes and/or commas.
Click to see more details...
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 is a simple markup language for creating rich formatted text using a text editor. Due to the simplicity of the Markdown it is still very readable in its raw form that contains the markup. Markdown is used in Stroom on the Documentation tab of each Document type and in the DocumentationDocument type.
Click to see more details...
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.
A Feed is a means of organising and categorising data in Stroom. A Feed contains multiple Streams of data that have been ingested into Stroom or output by a Pipeline. Typically a Feed will contain Streams of data that are all from one system and have a common data format.
Click to see more details... that errors occurring during execution are written to. Use Set Default to use the feed configured for the system.
Delivering a report by email or to a feed, and the template context available to report emails.
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.
A Stream notification writes the report into a FeedFeed
A Feed is a means of organising and categorising data in Stroom. A Feed contains multiple Streams of data that have been ingested into Stroom or output by a Pipeline. Typically a Feed will contain Streams of data that are all from one system and have a common data format.
Click to see more details... 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 MetadataMetadata
Metadata refers to the data that describes the Stream data. It is sometimes referred to as just Meta.
Click to see more details....
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.