---
title: "Creating and designing a report"
slug: "creating-and-designing-a-report"
updated: 2026-11-06T10:44:05Z
published: 2026-11-06T10:44:05Z
canonical: "docs.xtremepush.com/creating-and-designing-a-report"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating and designing a report

Start a new report and design it with an Xpert in the design workspace, then save it as a version.

You design a report by chatting with an Xpert. The Xpert writes the queries, lays out the page and checks its own work while you watch a live preview. Nothing reaches anyone until you save a version.

## Before you begin

The report needs an Xtremepush instance with Intelligence data or synced campaigns. If it has neither, the workspace asks you to **Choose an instance**.

## Start a new report in Analyse

1. Click **Analyse** in the sidebar, then **Reports**.
2. Click **New report**.
3. Choose how to start:

| Option | What happens |
| --- | --- |
| **Start from a template** | Pick one of the **Starter templates**. The Xpert maps the template's datasets to your data, then shows you the page. |
| **Describe it** | Write what the report should answer. The Xpert reads this before it designs anything. |
| **Copy an existing report** | Search for a published report and copy it. The copy starts from its published design, with no editions. |
| **From a conversation** | Choose one of your Assistant conversations. The Xpert drafts the report from the questions you asked and the queries it ran, and names it after the conversation. |
4. Optionally, enter a **Name** and **What should it answer?**. A template report is named after its template unless you change it, and a report from a conversation is named after the conversation. For **Describe it**, enter both.
5. Click **Create from template** or **Create and design**.

The design workspace opens. For a template or a conversation, the Xpert starts drafting straight away.

> [!NOTE]
> You can also start a report from the Assistant or from an HTML artefact. See [Using reports with the Assistant, Flows and tickets](/documentation/docs/using-reports-with-the-assistant-flows-and-tickets).

## Design the report with the Xpert

To open the workspace for an existing report, click **Design** on the report's page, or **Continue designing** if a draft is already open. The subtitle shows where you are, for example *Draft v3 · v2 is live*.

The workspace has three areas: the chat, the preview and a panel of tabs. On a phone, these become one row of tabs: **Chat**, **Preview**, **Sources**, **Delivery**, **Code** and, once a version is published, **Compare**.

1. In the chat, tell the Xpert what the report should show, for example *Add weekly sends by channel as a bar chart*. Ask for one change at a time.
2. Check the **Preview**. To preview another recent period, choose it in the period list beside the preview. A preview can cover up to 31 days. This changes only what you are looking at; each run of the report always covers its own period. If the preview is empty, the period may have no data yet: choose a period you know has data.
3. To check the page in dark mode, click **Dark**.
4. Keep asking until the page is right. The Xpert tests each query before it uses it and tells you what it changed. It also checks how the page looks in light and dark mode and fixes what it finds before it replies. If it could not fix something, the reply says so.

A design request can take a few minutes. You can leave the page and come back; the reply waits for you. If a reply does not arrive, click **Ask again**.

> [!TIP]
> Ask for comparisons, not wider queries
> 
> To show a change over time, ask for a comparison with the previous period, or the last few periods, rather than a query over a longer date range. Each edition then reports on its own period and stays the same size.

The page's commentary comes from narrative sections that the Xpert writes for each take. Each template starts with its own, such as *Three things to know* or *Verdict*. Ask the Xpert to add, remove or change them.

### Sources tab

**Sources** lists the report's datasets and, under **Narrative**, its narrative sections. Each dataset shows its title, its source (**Intelligence query** or **Xtremepush campaigns**), any comparison, and how it did in the last preview:

| Badge | Meaning |
| --- | --- |
| **OK** | The query returned rows. |
| **Empty** | The query ran but found no rows for that period. This is not an error. |
| **Truncated** | More rows matched than the dataset keeps. Ask the Xpert to aggregate the data. |
| **Error** | The query failed. Expand the dataset to see why. |
| **Deferred** | The preview ran out of time for this dataset. It runs in full when the report runs. |
| **Missing** | The dataset returned no result. |
| **Not mapped** | A template dataset that is not yet connected to your data. You cannot save a version until every dataset is mapped. |

To change a dataset's SQL yourself:

1. Expand the dataset and edit the SQL.
2. Click **Test the edit** to run it for the preview period. Testing saves nothing.
3. Click **Save**.

Report queries are read-only and can only be `SELECT` queries. To change an Xtremepush campaigns dataset, ask the Xpert.

To change a narrative section's instructions, click **Edit instructions**, make your change and click **Save**. If the Xpert changes the same item while you are editing, click **Save mine over the latest** to keep your version, or **Revert** to see the latest.

### Delivery tab

**Delivery** sets what a take's email and Slack message lead with. Who the report goes to is set on the report's page. See [Delivering and sharing a report](/documentation/docs/delivering-and-sharing-a-report).

- **Headline numbers**: up to six, for example Sends, Open rate, Click rate, Conversions or Revenue. For each number, set:
  - **Label**, **Dataset** and **Column**.
  - **Combine rows**: `sum`, `avg`, `min`, `max`, `first`, `last` or `count`.
  - **Format**, and **Currency** for a currency format.
  - **Change**: **vs the previous period** or **none**.
  - **Good when**: **it goes up** or **it goes down**.
- **Hero chart**: one chart for the email. Choose a chart **Recipe** and its **Dataset**, or **No chart**. Slack messages never carry a chart.
- **Summary**: the commentary the email and Slack lead with, chosen from the report's narrative sections. With no headline numbers and no chart, the message carries the summary alone.

Click **Add a number** to add a headline number, and **Up**, **Down** or **Remove** to reorder or delete one. Click **Preview email** to see the message with the latest take's commentary, or sample text before the first take.

### Code tab

**Code** shows the page template, written in Jinja. If you would rather not edit this yourself you can ask the Xpert in the chat to change the page instead. The template is read-only until you click **Edit**. Click **Validate** to check your change, then **Save**. You cannot save a template with an error; click an issue to jump to its line.

### Compare tab

Once a report has a published version, **Compare** shows the published version and your draft side by side over the preview period, with a list of what changed. If you change the draft or the period, click **Refresh**.

## Save a version

Your changes stay in the draft until you save. Until then, the published version keeps running, and readers see takes written by it.

1. Click **Save as v1** (or the next version number) at the top of the workspace.
2. In **What changed**, describe the change, for example *Adds weekly sends by channel*. The Xpert suggests a note you can edit.
3. For the first version, choose the **Xpert who writes each take**. Later saves ask for this only if the report has no Xpert.
4. For the first version, set the **Schedule**: how often it **Runs** (**Daily**, **Weekly** or **Monthly**), **At** what time, and **On** which weekday for a weekly report or which **Day** (1 to 28) for a monthly one. To run the report only by hand, leave it on **Not scheduled**. Later saves do not show the schedule, so set it carefully: you cannot change it after the first version. A private report is never scheduled, and the dialog says so instead.
5. Click **Save as v1** (or whatever the next version number is).

Schedule times use your browser's timezone, which the dialog shows, for example *Times are in Europe/London*. The schedule starts once the version is saved.

XpertOS checks every dataset and the page before it publishes the version. This can take a minute. If a dataset fails or the page has an error, the dialog lists what to fix. If the check could not run, click **Try again**.

| Schedule | Each take covers |
| --- | --- |
| **Daily** | The previous day |
| **Weekly** | The previous week (Monday to Sunday) |
| **Monthly** | The previous month |

To throw away a draft and go back to the published version, click **Discard**. A report that has never been published keeps its first draft.

## Check figures that are not live

Every figure on a report normally comes from your data. Sometimes a page needs a figure that no query can give yet, such as a target agreed in a meeting. The Xpert can then type the figure in and mark it as not live. It does the same when it converts an HTML artefact and cannot link a figure to your data.

On the page, a figure that is not live has a dashed underline and a **static** badge. Hover over it to see why it was typed in. In the PDF, it has a † mark instead of the badge, with a note at the foot of the page.

When you save a version, the dialog shows how many figures are not live. Hover over the count to see each figure and why it was typed in. You can still save. These figures stay exactly as typed in every take, so check that they are still correct before you save. When the data exists, ask the Xpert to replace them with figures from a query.