# Report Widget

A KPI card for dashboards. Each Report Widget shows one big value (today's sales, open orders, queue depth — whatever your data source returns) along with an icon, title, optional subtitle, and an up/down/flat trend indicator. Drop several of them across the top of a dashboard for the classic at-a-glance metric strip.

The value is data-driven — connect a NetSuite saved search or SuiteQL query and the widget pulls the first row's chosen field at render time.

## Available in

* Dashboard modules
* Reports modules
* Page modules

## When to use

* Across the top of a dashboard for headline metrics — *Today's Sales*, *Open Orders*, *Pending Approvals*, *Inventory Value*.
* A page header tile that surfaces one number prominently.
* An operations dashboard where each tile maps to one KPI.

For a multi-row tabular report, use **Transaction List** (Transactions Advanced) instead — Report Widget is for *one* number, not a table. For visual time-series charts, use **Chart Widget**.

## Settings

The block opens a configuration modal that handles all of its setup:

| Setting              | Description                                                                                                                                                                                                                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**            | The label shown above the big value (e.g. *Today's Sales*).                                                                                                                                                                                                                                    |
| **Value**            | The default static value shown when no data source is connected, or as a fallback.                                                                                                                                                                                                             |
| **Value Format**     | How the value renders: *Currency*, *Number*, *Date*, *Text*, or *Auto* (the widget guesses based on the value).                                                                                                                                                                                |
| **Icon**             | Icon shown beside the title. Pick from the standard icon set.                                                                                                                                                                                                                                  |
| **Icon Color**       | The icon's tint colour.                                                                                                                                                                                                                                                                        |
| **Subtitle**         | Supporting text below the value (e.g. *vs. yesterday*, *as of 3:00 PM*).                                                                                                                                                                                                                       |
| **Subtitle Color**   | *Auto* (uses Change Direction's colour), *neutral*, *positive* (green), *negative* (red), *info* (blue).                                                                                                                                                                                       |
| **Change Direction** | Trend arrow shown alongside the subtitle: *up*, *down*, or *none*.                                                                                                                                                                                                                             |
| **Change Text**      | Supporting text shown next to the trend arrow (e.g. *+12%*). Falls back to Subtitle if not set.                                                                                                                                                                                                |
| **Data Source**      | The query that produces the value. Two modes: *Saved Search* (NetSuite saved search ID) or *SuiteQL* (custom query). The widget reads the first row's configured value field.                                                                                                                  |
| **Action Column**    | When the widget is in table mode, adds an **Actions** column to each row. Choose the action type: open a record details panel, open the record in NetSuite, or show both. Set the column label, the ID field used to identify each row's record, the record type, and an optional URL pattern. |

## How it works

1. The widget renders the configured icon + title.
2. If a data source is configured, the widget runs the query (saved search or SuiteQL) and reads the first row.
3. The configured **Value Field** from that row becomes the big value, formatted per *Value Format*.
4. SuiteQL queries can reference the current user — `{employeeId}` and `{locationId}` are substituted automatically.
5. If no data source is configured, the widget renders the static **Value**.
6. Subtitle + change direction + trend arrow render below the value to provide context.

## Examples

**Today's sales tile.** Title: *Today's Sales*. Icon: dollar. Value Format: Currency. Data Source: a SuiteQL query summing today's invoices. Subtitle: *vs. yesterday*, Change Direction: up, Change Text: *+12%*.

**Open orders count.** Title: *Open Orders*. Icon: cart. Value Format: Number. Data Source: a saved search counting orders with status = pending. Subtitle: *Awaiting fulfillment*.

**Queue depth.** Title: *Queue*. Icon: package. Value Format: Number. Data Source: a SuiteQL count of pending BRM queue records. Pair with **BRM Queue Widget** below for at-a-glance + drilldown.

## Common issues

* **Value shows the static fallback** — the data source returned zero rows, or the configured value field doesn't exist in the result. Verify the saved search returns at least one row and the field name matches a column.
* **Wrong format** — set Value Format explicitly. *Auto* picks the first format that parses; for ambiguous cases (e.g. a number that should be a date), set the format manually.
* **Trend arrow doesn't appear** — Change Direction is set to *none*. Set it to *up* or *down* and add Change Text to make the indicator visible.

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Chart Widget</strong></td><td>Multi-value chart for trends and breakdowns.</td><td><a href="/pages/ime7EJ2FV2DEBCAva0gy">/pages/ime7EJ2FV2DEBCAva0gy</a></td></tr><tr><td><strong>BRM Queue Widget</strong></td><td>Compact queue-state widget for ops dashboards.</td><td><a href="/pages/AxMkKZjs0t9TwA6lNB2H">/pages/AxMkKZjs0t9TwA6lNB2H</a></td></tr><tr><td><strong>Transaction List</strong></td><td>For a tabular list of transactions (the role this doc previously described).</td><td><a href="/pages/0HBWjwooyav8Uibdnaus">/pages/0HBWjwooyav8Uibdnaus</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.in8sync.com/client-admin-guide/active-workflows/getting-started/report-components/report-widget.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.