Insights: Reporting and Dashboards

Build your own reports and dashboards on top of your Rossum data — ask a question in plain English.

What Insights is

Insights is Rossum’s self-service reporting module. It sits on top of a reporting database that mirrors your document data, and it lets you answer questions about your operation — automation rate, throughput, corrections, how long your team spends on each queue.

You reach it from the top navigation:

• Insights — the central hub for accessing, analysing and managing your reporting data. Everything you or Rossum creates lives here.

• Statistics — the built-in, fixed usage dashboard. Unlike Insights, it cannot be customised.

There are three ways to get a report in Insights, and most customers use all three:

• Rossum standard dashboards — pre-built templates that Rossum can set up in your organisation.

• Conversational Insights Assistant — describe what you want in English and Insights builds the report for you.

• Create a custom dashboard from your own reports, with filters shared across every card.

NOTE

Insights is built on Metabase. Wherever this article stops short of a deep-dive, the Metabase documentation linked at the end of this article applies directly to what you see in Rossum.

Who can see what

Access to Insights is granted at organisation level. Every user with the Admin or Manager role can open every report, dashboard and collection in Insights.

IMPORTANT

Insights does not currently respect queue-level access. A Manager who is restricted to two queues in Queue Settings will still see data from all queues inside Insights.

Annotators and other roles have no access to Insights.

What data is available, and how fresh it is

Synchronisation schedule

The reporting database is refreshed once a day, overnight:

NOTE

If you need live numbers for today, use Statistics and its filters instead. Insights is for trends, not for live queue monitoring.

⚠️ Reporting window

By default the reporting database holds a rolling 30-day window that ends yesterday. Anything older than that drops out of Insights automatically, even if the document itself is still in Rossum. Retention is calculated from the Received at date on the document.

You can see the exact window your organisation currently has on the Rossum: all — Timespan available for Insights card of the 1: Rossum: Overview dashboard, which reports a Data starts and a Data ends date. You can also just ask the assistant what the oldest received document is.

Retention

• The retention window is counted from the day a document is received — not from the day it was exported or last touched.

• Retention can be extended up to 365 days on request. Contact your Rossum representative or Rossum Support to arrange it.

Choosing the right timestamp

Several lifecycle timestamps are available, and picking the right one is most of what makes a card mean what you intended.

A useful pattern: a document with confirmed_at set but exported_at empty is stuck after confirmation.

Rossum standard dashboards

Rossum maintains a small set of template dashboards that cover the questions almost every customer asks. You can request that Rossum sets them up in your organisation, build your own from scratch, or start from a template and adapt it.

Both dashboards ship with two filters at the top — a date filter on Received or Exported date (defaulting to Previous 3 months) and a multi-select Queue(s) filter — so you can narrow the whole dashboard in one action.

TIP

Duplicate a standard dashboard before you change it. That way you keep a clean reference copy, and a later template update from Rossum will not overwrite your work.

Creating a report with Conversational Insights

The quickest way into Insights is to describe the report you want in plain English. The assistant turns your sentence into a query, picks a sensible visualisation, and shows you the result.

How to create a report

1. Go to Insights.

2. Click Create Report.

3. Type your question in English — for example, “Automation rate by queue”.

4. Review the result. If it is close but not right, refine it (see Adjusting a report below).

5. Save the report, and choose the collection it should live in.

TIP

Open Configure manually on any assistant-built report to see exactly how it is configured and what data goes into it. It is the fastest way to learn the query editor, and the fastest way to check that the report means what its title claims.

Writing a prompt

The assistant works best when your question names three things: the measure, the breakdown, and the timeframe.

• Measure — what is being counted or summed. “Number of documents”, “automation rate”, “active time spent”.

• Breakdown — how to split it. “by queue”, “by vendor”, “by status”, “by month”.

• Timeframe — “last 30 days”, “previous 3 months”, “by due date month”.

Ask one question per report.

Common use cases

These queries work well in almost any Rossum environment. Use them as starting points.

Adjusting a report

A report from the assistant is a normal Rossum report — nothing about it is locked. You have three levels of control:

In the query editor you build the query in stages, in this order: pick data → join data → custom columns → filter → summarise and group → sort → row limit. Anything the assistant produced can be edited at any stage.

Creating a dashboard

A dashboard is a saved layout of reports that share a set of filters. Use one whenever a single number is not the answer — an operations review, a monthly business review, a queue health check.

Create the dashboard

1. Go to Insights.

2. Open the arrow next to Create Report and choose Create Dashboard.

3. Give the dashboard a name and a short description. The description is what colleagues read first — say what decisions the dashboard supports.

4. Choose the collection it belongs to, then confirm.

TIP

Use Create Collection to group dashboards and reports by team or topic before you have many of them. Collections are much harder to introduce once fifty reports already exist in one flat list.

Add reports to the dashboard

1. Open the dashboard and click the pencil icon to enter edit mode.

2. Click the + icon to add a card. You can add an existing saved report, or create a new one directly on the dashboard.

3. Add heading and text cards to break the dashboard into sections. The standard Overview dashboard uses this pattern — “Pending Documents”, “Automation” — and it makes a long dashboard readable.

4. Drag cards to reposition them; drag the handle at the bottom-right corner of a card to resize it. Cards snap to a grid and reflow automatically.

5. Click Save.

Use dashboard tabs when a dashboard covers more than one audience — for example an “Operations” tab and a “Finance” tab — rather than letting a single tab grow to twenty cards.

NOTE

Where a filter lives determines what it can reach. A filter placed on the dashboard itself can be connected to cards on all tabs. A filter placed on a heading card or a question card can only reach cards on its own tab.

Adding a filter to a dashboard

Add and connect a filter

1. Open the dashboard and click the pencil icon to enter edit mode.

2. Click the filter icon where you want the filter to appear.

3. Choose the filter or parameter type.

TIP

If you need to filter on annotation fields, queue, or document metadata, pick Text or Category. That covers almost every filter you will build in Rossum.

4. Connect the filter to each card. Under each card, open Column to filter on and select the column the filter should apply to. This step is the one people skip, and it is the reason filters appear to “do nothing”.

5. Configure the settings in the sidebar: the Label shown to users, the Filter operator, a Default value, whether people pick from a dropdown list, a search box or an input box, and whether they can select multiple values or a single value.

6. Click Save.

Things to know

• Unconnected cards ignore the filter. A dashboard where three of five cards respond to the date filter is worse than one with no filter at all, because the numbers no longer agree with each other. Connect every card, or move the unconnected ones off the dashboard.

• If a filter is not connected to any card on the current tab, it is hidden rather than shown as broken.

• When you select a column, Insights offers to connect the same filter to every other card that has that column — accept it, then check each card.

• The column path can differ from card to card. On the Overview dashboard the same Queue(s) filter connects to Document.Queue Name on some cards and Summaries.Queue Name on others, because those cards are built on different data. This is why each card has to be checked individually.

• A card can only be connected to a column its query can reach. If the card is built on document only and you want to filter by vendor, you must first bring the field table into the card’s query. See Example 3.

• Set a default value on your date filter. Without one, every card runs against the full reporting window on every page load, which is slower and rarely what anyone wants. The standard dashboards default to Previous 3 months.

Linked filters

A linked filter narrows the options offered by a second filter — pick a workspace and the queue list shows only that workspace’s queues.

1. Enter edit mode, then click the gear icon on the filter you want to narrow (the child filter).

2. Open the Linked filters tab and select the parent filter.

3. Click Save.

NOTE

The child filter must be an ID, location, or text/category filter. Both columns must either sit in the same table or be connected by a defined relationship between their tables. Queue and workspace both sit on document, so they qualify.

When a filter does not work

Understanding the table structure (and when you need to join)

This is the single concept that decides whether Insights feels easy or frustrating. The reporting database is not one wide spreadsheet. It is a set of related tables, and each table holds only its own attributes.

The six tables

Two describe documents and people; four describe extracted fields.

Fixed means every organisation has the same columns. Schema-shaped means the columns are generated from that customer’s own document schema, so they differ between customers.

How the tables join

Everything joins on annotation_id — shown in the query editor as Annotation ID — and document is the hub.

Two consequences are worth committing to memory:

• There is no queue or workspace table. queue_name, queue_id, workspace_name and workspace_id live directly on document, so grouping or filtering by queue never needs a join. This is why the Queue(s) filter on the standard dashboards just works.

• Field data reaches document columns for free. Because field_metadata.annotation_id points at the document, a card built on field_metadata can still group by queue_name or filter on received_at — the query builder resolves it through that link. This is how “Hours spend per Queue” is built from per-field time.

The document table

One row per document. Every metric that is not about individual fields comes from here.

Identity and placement

Automation and effort

Actors

One user id per lifecycle event, all pointing at user.user_id:

created_by_user_id     confirmed_by_user_id     exported_by_user_id

rejected_by_user_id    deleted_by_user_id       purged_by_user_id

In the query editor and in filter dropdowns these appear as named relationship groups — “Modified by User”, “Purged by User” and so on — each offering the same set of user columns (see Figure 11). The exact set of relationships your organisation has is whatever the picker shows.

IMPORTANT

Pick the actor that matches the question. “Who did this work” is confirmed_by_user_id. created_by_user_id is whoever imported the document, which in many setups is an integration account or a different person entirely.

The user table

The filter picker also offers First Name, Last Name and Email alongside Username, so you can label a filter with whichever reads best for your team.

The field_metadata table

One row per field instance on a document — a long, narrow table. This is the only place with per-field time and correction data, and it is the table to prefer for anything about corrections, per-field effort or confidence.

Standard patterns

• Rank fields by cost — sum time_spent_overall_s, group by schema_id, sort descending, limit 15. This is what the shipped Most corrected fields card does — note that it ranks by time, not by correction frequency.

• Rank fields by error rate — count rows where is_corrected is true, grouped by schema_id. A different question, and usually the more actionable one.

• Corrections per document — count corrected rows per annotation_id, then group by that count to get a distribution. Two steps; save the first as its own question.

Two ways to bring a related table in

IMPORTANT

You cannot filter, group or display an attribute of a related table until that table is part of your query. A query built on document alone knows confirmed_by_user_id but not the person’s name, and knows nothing at all about extracted values.

1. Linked columns (preferred)

Where a relationship between two tables is already defined, the related table’s columns are offered to you without any manual work. In the query editor they appear grouped under the relationship’s name, and in the chart they are labelled with the path — which is what you see on the Overview dashboard, where the x-axis of “Hours spend per Queue” reads:

Annotation → Queue Name

In a custom expression, reference such a column with the table prefix:

[Queue.Name]

Always check for a linked column first. It is less work and less error-prone than a manual join.

2. An explicit join

When no linked column exists, add the table yourself:

1. In the query editor, click Join data.

2. Pick the table (or a saved report) you want to join. It must be in the same database — which everything in Insights is.

3. Choose the matching key column on each side. For anything document-related this is Annotation ID on both sides.

4. Choose the join type. Left join is almost always what you want for reporting: it keeps every document, and leaves the joined values empty where there is no match. An inner join silently drops documents that have no match, which quietly understates your volumes.

5. Click Columns and select only the columns you actually need, to keep the result readable.

TIP

If a total looks too low after you add a join, the join type is the first thing to check. Switch inner to left and compare the row counts.

Filter Examples

Three situations, in increasing order of difficulty: filtering on a column the table already has, joining to bring in a person’s name, and joining to bring in an extracted value. Work through all three and the rest of Insights follows the same pattern.

Example 1 — Filter a dashboard by queue (no join needed)

You have a dashboard of volume and automation cards, and you want a single control at the top that narrows every card to a chosen set of queues. This is the Queue(s) filter on the standard 1: Rossum: Overview dashboard.

This example needs no join, because queue_name is a column on document.

Steps

1. Open the dashboard and click the pencil icon to enter edit mode.

2. Click the filter icon in the dashboard header — not on an individual card. Only a filter placed here can reach cards on every tab.

3. Choose Text or Category as the filter type, and Is as the operator.

4. Under the first card, open Column to filter on and select the queue name column.

5. Insights offers to connect the same filter to every other card that has that column. Accept the offer, then check each card individually. Any card still showing “Select…” is not connected and will silently ignore the filter.

6. Set Label to Queue(s). This is only the display name — it does not change behaviour.

7. Set How should people filter on this column? to Dropdown list, so users pick from the real queue names instead of typing them and mistyping them.

8. Set People can pick to Multiple values, so a user can compare two queues side by side.

9. Leave Default value empty if the dashboard should open on all queues. Set it if most readers only ever care about one.

10. Click Save, then select a queue and confirm that every card changes.

TIP

A card built on field_metadata can be connected to this same filter, because field_metadata reaches document.queue_name through annotation_id. That is how “Hours spend per Queue” — a per-field measure — responds to a queue filter.

Example 2 — List confirmed documents and filter by the annotator (join to user)

You want a list of confirmed documents and a dashboard filter that narrows it to a chosen person — “show me everything Jana confirmed last month”. The person’s name is not on the document, so the user table has to be part of the query.

document stores confirmed_by_user_id — a number. The name lives in user.username. This is exactly what the shipped Rossum: Annotators: Individual Documents card does.

Step 1 — Build the report

1. Go to Insights, click Create Report, then choose Configure manually.

2. In Data, select document.

3. Add a Filter — status is confirmed.

4. Check for a linked column first. User columns are usually already offered, grouped under the relationship that reaches them (“Modified by User”, “Confirmed by User”). If yours are, you do not need a join — skip to step 6.

5. Otherwise click Join data, pick user, and set the condition to document.confirmed_by_user_id = user.user_id, with the join type left as Left join.

6. Under Columns, keep only what the reader needs. The shipped card shows annotation_id, status, queue_name, workspace_name, confirmed_at, original_file_name and active_time_spent.

7. Add username — this is the column the filter will use.

8. Sort by confirmed_at, descending, then save the report into a collection.

IMPORTANT

Keep the join as Left join. An inner join drops every document with no matching user, including everything that was fully automated — so your list would quietly exclude your best-performing documents.

Step 2 — Add the Annotator filter

1. Add the report as a card on a dashboard, or create a dashboard for it.

2. Enter edit mode and click the filter icon in the dashboard header.

3. Choose Text or Category.

4. Under the card, open Column to filter on and select username from the user group — not confirmed_by_user_id, or the dropdown will show numbers.

5. Set Label to Annotator, set it to Dropdown list, and allow Multiple values.

6. Click Save, then select a person and confirm the list shortens.

Watch out for

• A suspiciously short user list. If you filtered the user table on is_active = true, remove that condition — the flag is sparsely populated.

• Blank names. With a left join, automated documents show an empty user. That is correct, and it is useful: filter for empty to get a clean list of your fully automated documents.

• People who have left. They still appear in historical rows. Leave them in the dropdown, or your historical totals stop reconciling.

• The right actor. confirmed_by_user_id is “who did the work”. created_by_user_id is whoever imported the document, often an integration account.

• Per-field questions need a different table. “Which fields did Jana change?” is not answerable from document — that is field_metadata (is_corrected by schema_id).

Example 3 — Break down document distribution by vendor (join to field)

You want your existing Document Distribution by Queue and Status report split by vendor, and a Vendor filter on the dashboard. This is the hardest of the three, and the reason is worth understanding before the steps.

Why this one needs a join

• Document is one row per document, and it carries only lifecycle facts — status, queue, workspace, timestamps, automation, time spent. It holds no extracted values whatsoever. There is nothing on it that could answer “by vendor”.

• The vendor’s name is an extracted value, and extracted values live in field, keyed by the same annotation_id.

• Until field is part of the query, the query builder has no column named after your vendor field — so it cannot offer it as a grouping, and a dashboard filter has nothing to connect to. Joining on annotation_id is what makes the two tables a single result set; after that the vendor column behaves like any other column on the card.

IMPORTANT

field is schema-shaped, so the vendor column is called whatever your schema calls it — vendor_name in one organisation, payee_company_name in another, sometimes sender_name. Open the table in the data picker and read the real name before you build.

Step 1 — Add the join

1. Open the report and choose Configure manually to reach Advanced configuration.

2. In Data, confirm the table is Document.

3. Click Join data.

4. Pick Field as the table to join.

5. Set the condition to Document.Annotation ID = Field.Annotation ID. Leave the join type as a left join so documents with no extracted vendor still appear.

6. You do not have to display any Field column. Joining alone makes the vendor column available to groupings and to dashboard filters. The shipped Document Distribution card does exactly this.

7. If you want the breakdown inside the chart rather than only as a filter, add the vendor column as a third grouping in Summarize.

8. Click Visualize, then save.

Step 2 — Add the Vendor filter

1. On the dashboard, enter edit mode and click the filter icon in the header.

2. Choose Text or Category.

3. Under the card, open Column to filter on and pick the vendor column — it now appears under the Field group.

4. Set Label to Vendor, Dropdown list, Multiple values.

5. Click Save and confirm the chart responds.

Watch out for

• Counts can inflate. The join onto field is not guaranteed one-to-one. Count distinct annotation_id rather than counting rows.

• Left join, not inner. Documents where no vendor was extracted show a blank vendor. With an inner join they vanish, and a “distribution” that silently loses its failures is worse than no chart.

• Blank is a finding. Filter the vendor column for empty and you have a list of documents where vendor extraction failed — often more actionable than the distribution itself.

Linking straight to a document from a report

A report that lists problem documents is only half useful if the reader then has to search for each one by hand. Because a Rossum document URL is built from annotation_id, you can turn any report row into a clickable link.

The URL pattern

https://<your-organisation>.rossum.app/document/<annotation_id>

Option A — build the link as a custom column

1. In the query editor, add a Custom column.

2. Choose Custom Expression and concatenate the base URL with the id:

concat("https://<your-organisation>.rossum.app/document/", [annotation_id])

3. Name the column — for example Document link — and click Done.

NOTE

annotation_id is an integer, so wrap it if the concatenation is rejected — for example concat("…/document/", [annotation_id] + "").

Option B — format an existing column as a link

1. Display the report as a table.

2. Click the annotation_id column heading and choose Formatting.

3. Set Display as to Link.

4. Set the link URL to the pattern below, and optionally set friendlier link text than the raw id.

https://<your-organisation>.rossum.app/document/{{annotation_id}}

TIP

Option B keeps the underlying data clean — the report still contains an integer, not a string — so it is the better choice when the same report is also exported for analysis. Option A survives export as a usable URL, which is the better choice when the report is emailed as a spreadsheet.

Working with time values

Time in Insights is stored in seconds. This catches everyone out at least once, because a number like 37,384 looks like a document count rather than just over ten hours.

For a quick conversion, add a custom column with a plain division and format it to one or two decimal places. Do it before summarising, so the axis label reads in the unit you charted — this is how “Most corrected fields” ends up with a “Minutes spent” axis rather than raw seconds:

[working_seconds] / 60

Other reporting conventions

• Use median, not average, for durations. A document left open over lunch wrecks an average; the median ignores it.

• Build percentages as conditional count ÷ total count × 100. This is how the shipped automation-rate card does it — (Sum of Case ÷ Count) × 100 — and it shows the numerator and denominator alongside the rate.

• Name every measure explicitly. An unnamed sum arrives on the chart as “Sum of Hours” instead of “Hours”.

• Check status casing before hard-coding it. Statuses are lower-case in the instances observed, but a card comparing against 'exported' returns nothing where the value is 'Exported'.

Exporting a report

Any report or dashboard card can be downloaded. Hover the card, open the three-dot menu and choose the download option, or use the download button on an open report. Available formats are CSV, XLSX, JSON, and PNG for charts; a whole dashboard can be exported as PDF.

You can download either formatted results — which keep the formatting you applied in Insights, including the duration and link formatting described above — or unformatted raw values.

Row limits

IMPORTANT

An export that hits the row limit is truncated silently — you get a valid file with missing rows and no warning. Before you rely on an export for reconciliation, compare its row count against the row count shown in the report itself.

TIP

Raising the limit is rarely the right fix. If you are exporting hundreds of thousands of rows, aggregate in Insights first — the answer you want is almost always a summary, and a summarised export is faster, smaller and easier to check.

What is not in Insights

Insights exposes exactly six tables. If something is not a column on one of them, it is not in the reporting database — there is no hidden table to join to, and no assistant prompt that will surface it.

IMPORTANT

The two most frequently missed: labels and comments. Neither is stored in the reporting database, so you cannot report on them, group by them, or use them as a dashboard filter.

NOTE

A card can also be structurally correct and still come back empty because the underlying column is not populated — no due date extracted, nothing exported yet, no field time recorded on fully automated documents. That is a data-coverage question rather than a missing-table one, but it looks identical on screen. Check the column has values before assuming the query is wrong.

Further reading

Insights is built on Metabase, so the Metabase documentation applies directly to the query editor, the visualisation settings and the expression language.

• Visualising results - metabase.com/docs/latest/questions/visualizations/visualizing-results

• The query editor - metabase.com/docs/latest/questions/query-builder/editor

• Custom expressions - metabase.com/docs/latest/questions/query-builder/expressions

• Joining data - metabase.com/docs/latest/questions/query-builder/join

• Dashboard filters - metabase.com/docs/latest/dashboards/filters