Turn a dashboard into an app
Open a workbook and switch to Dashboard builder. In the workbook menu, select App mode. Cube replaces the dashboard with a starter app that you can edit, and the Dashboard builder tab reads App builder. To go back to a standard dashboard, select App mode again. The tab reads Dashboard builder again. Cube keeps the standard dashboard’s draft while the workbook is in app mode, so switching back restores it.Build the app with the agent
Describe the app you want in the agent chat. Include the business question, the data you want to show, and how people should interact with it. For example:Build a revenue performance app with headline metrics, a monthly trend chart, and a searchable status filter. Use the company’s brand colors.The agent starts from the layout that your prompt describes:
- A dashboard with filters on top — the default when you name no layout.
- A dashboard with filters on the left — for example, “with the filters in a column on the left”. On a narrow screen, the filters move above the content.
- A story — for example, “tell the story of Q3 sales”. The headline and its key numbers come first, then one section for each finding: a short text, a chart, and a takeaway. A menu at the top stays in view while you scroll and jumps to each section.
- Slides — for example, “present the Q3 review as slides”. A title slide and an overview of up to four key numbers come first, then one finding per slide: a chart, a table, or a list, with a one-line narration under it. The agent keeps a deck to about eight slides. See Present a slide deck.
How the agent picks charts
The agent picks each chart from the question it answers and the shape of the report’s data:- Change over time gets a line or an area chart. A bar chart over time keeps the periods in date order instead of sorting them by value.
- A ranking or a comparison gets a bar chart sorted by value. Long labels or more than 12 categories get horizontal bars. With more than 30 categories, the agent shows the top ones or a table.
- Part of a whole gets a donut chart only when one count or sum is split into 2 to 6 parts with no negative values. To compare shares across a second category or over time, the agent uses a 100% stacked bar.
- One number gets a KPI card. Two related measures get a scatter chart, or a combo chart when their units differ.
Periods that are still running
When the agent sets a relative date range on a report, such as the last 30 days, it ends the range at today, unlike the date range picker presets above. It shows rows dated after today only when they belong in the app, for example a forecast. Line, area, and bar charts mark the period that holds today, such as the current month, because its numbers are not final:- A line or an area chart draws the last segment dashed, into a hollow point.
- A bar chart draws the bar hatched.
- The tooltip adds (to date) to the period, for example Nov 2026 (to date).
Show data on a map
Apps have two map components:RegionMapshades countries or US states by a value, for example revenue by country.PointMapdraws one point per row at its latitude and longitude, for example stores sized by their orders.
Regions and projections
Theregions prop picks the shapes:
world(the default) draws the countries of the world at a 1:110m scale. Small countries, such as Singapore and Malta, are not on this map.us-statesdraws the 50 US states and the District of Columbia, with Alaska and Hawaii in insets. US territories, such as Puerto Rico and Guam, are not on this map.
projection prop picks how the world is drawn:
flat(the default) draws a flat map. It leaves out Antarctica.globedraws a globe that viewers turn by dragging it. It opens on the center of the data, weighted by value, and never turns by itself, so a download always shows that view. To open it elsewhere, passcenteras[longitude, latitude].
projection.
Match regions
RegionMap reads the region from regionField. A country matches by its
English name, its ISO 3166 alpha-2, alpha-3, or numeric code, or a common name,
such as USA, UK, or South Korea. A US state matches by its name or its
postal code, such as CA. Case, accents, and punctuation don’t matter.
Rows for the same region are added up. Shades run from a faint to a full tint
of one color. A region without a row is hatched, so it doesn’t read as a small
value.
A value that matches no region is not drawn. The app logs it once in the
Console, for example:
PointMap leaves out rows with a latitude outside -90 to 90 or a longitude
outside -180 to 180, and, on a map of US states, rows outside the states. It
logs them once, too. On a globe, points on the far side are hidden until a
viewer turns it.
Props
Both components takedata and columns, like the app’s other charts. With
columns, field titles and value formats come from the report.
Maps don’t zoom or pan, don’t react to clicks, and can’t draw custom GeoJSON
shapes or map tiles.
Present a slide deck
A slide deck shows one slide at a time in a 16:9 frame. Under the slide, the deck shows the slide number, a dot for each slide, and arrow buttons. Click a dot to go to its slide. To move between slides with the keyboard, click the app first, then press:- →, Page Down, or Space for the next slide.
- ←, Page Up, or Shift+Space for the previous slide.
- Home or End for the first or last slide.
Preview and edit the code
The app editor has two modes:- Preview shows the running app. Use it as your viewers will.
- Code shows the app’s Files and a code editor. Select a file to edit it.
- Click Run to save all changed files and reload the app with them. Until the new version is ready, the preview shows the previous one, dimmed.
- Click Discard to drop your unsaved changes.
If you leave the workbook before you click Run, your unsaved changes are lost.
Edit text in the preview
To fix a title or a caption, click it in Preview and type. Press Enter, or click elsewhere, to save it. Press Esc to cancel. Cube writes the new text into the app’s code and reloads the app. Each saved edit is one Undo step. While you’re typing in a title or a caption, ⌘Z or Ctrl+Z undoes your typing instead. When you point at text you can edit, it gets a dashed outline. You can’t edit this way:- Buttons, tabs, links, and other controls. Clicking them works as usual.
- Text that comes from your data, or that appears in more than one place in the app.
- Text that the app doesn’t show yet, such as an empty subtitle or note. Add it in Code or ask the agent.
Add reports that the app doesn’t use
When the workbook has reports that the app doesn’t show, the editor toolbar shows how many, for example 2 reports not used. Click it to see the list. To have the agent add them, click Add in chat. Cube opens the agent chat and adds the reports, with their IDs, to the message box. Review the message, then send it. The list leaves out reports that an app can’t read: reports from Source SQL tabs, reports with no query yet, and Python reports that haven’t run. If the app’s code gets the list of reports at run time, withuseReports() or cube.getReports(),
instead of naming the reports it reads, it can show any of them. The editor
doesn’t show the note for such an app.
Find and fix problems
When the app reports errors or warnings, the editor toolbar shows their count. Click the count (Show problems) to open the code and the Problems panel under the code editor. The panel also opens by itself when the first problem appears. The panel has two tabs:- Problems lists the app’s errors and warnings, resources that the sandbox blocked, and an app that rendered nothing. When Cube can find the file and line of a problem, the row shows them. Click the row to open the file at that line. A blocked resource has a hint, for example “Apps can’t load files from the internet”. See Governed data access for how to include such files in the app. In Files, each file that has a problem shows an error mark.
- Console shows what the app writes to the browser console.
Publish the app
Click Publish to publish the app, the same way you publish a dashboard. Cube refuses to publish an app that has no entry file or whose entry file is empty. Viewers see the published app read-only. It uses the report definitions from the version you published, and Cube runs these reports for each viewer. Viewers cannot open the app’s code. The app follows the viewer’s light or dark theme and locale. Apps use your account’s app theme for colors and fonts, and the account’s default chart palette for charts, so they match your brand without code changes. New apps also show the theme’s logo.Download and schedule the app
Download a published app as a PNG or PDF file from the Download button, the same way you download a dashboard. The file shows the whole app, not only the part that fits on the screen. The app’s Download settings dialog has no Layout row: apps don’t offer a print version. You need the Download data permission, and the button is hidden when an admin turns off the data download controls. Refreshes, dashboard deliveries, and alerts work for apps the same way as for dashboards. They run the reports of the published version, and their notifications attach the whole app as a PNG or PDF file. The PDF depends on the app’s layout:- A dashboard or a story is one tall page.
- A slide deck has one page per slide. If the PDF shows only the deck’s first slide, ask the agent to update the app’s slide deck component.
useCapture() from app/_cube.js.
It returns true while Cube renders the app for a file and false otherwise.
In a PDF, each element with the data-app-page attribute starts a new page.
Governed data access
An app reads only the results of reports in its own workbook. Cube runs those reports with the viewer’s permissions and passes the results to the app. The app does not receive credentials for your data source or Cube APIs, and it cannot query your warehouse directly. Apps run in a sandbox, isolated from the Cube interface:- An app cannot make network requests, so it cannot call external APIs or send data out of Cube.
- An app cannot load external scripts, stylesheets, images, or fonts. Put
everything the app needs in its files. Images and fonts can be embedded as
data:URLs. - An app cannot read Cube cookies, storage, or the page around it.
Apps in embedded analytics
A published app renders in signed and private embeds the same way as on its published page. Embed the dashboard as you would any other dashboard. The app runs in the same sandbox, isolated from the embedding page. The app is treated like a standard dashboard:- It reads only the reports pinned by the published version.
- Cube runs those reports with the viewer’s permissions and, in signed embeds, the embed user’s user attributes, so two viewers can see different numbers in the same app.
- The page receives
cube:event:dashboard-loadedonce the app has loaded, or once it shows an error. The event does not say which. cube:action:refreshmakes the app read its reports again.cube:action:set-filterfilters the app’s reports, and so do filter parameters in the embed URL. Cube applies each filter to every report that the app reads, so the app needs no code for it. A report that cannot take a filter fails to load instead of showing unfiltered numbers: for example, a report on a view that does not have the filter’s dimension, or a Python report, which the app reads from its last run. A filter that Cube cannot read makes every report fail to load: its value is not valid JSON, its name is not in theview.dimensionform, itstypeis unknown, or it has novaluewhere itstypeneeds one.
useHostFilters(). It comes from
app/_cube.js, the module that Cube provides to every app for reading data:
f_orders.status={"value":"completed"} becomes
{ member: "orders.status", type: "equals", value: "completed" }. The array is
empty when the page sets no filters. A component that calls it re-renders when
the page sends new filters.
To let viewers present a slide deck full screen, the
iframe’s allow attribute must include fullscreen, as in
allow="microphone; fullscreen". The host page’s Permissions-Policy header,
and any parent iframe, must allow fullscreen too. If any of them doesn’t, the
deck shows no Full screen button.
When an app fails
- The app couldn’t start — Cube could not save your changes or open a session for the app. Click Try again.
- The app didn’t load — the app did not finish loading within 15 seconds. Click Try again.
- Dashboard apps aren’t available here — apps are not set up for this environment. Contact your administrator.
- This app hit an error — the app’s code threw an error while it ran. The message shows the error. Fix the code, or ask the agent to fix it, and click Run.
- Couldn’t load the app’s source — Cube could not fetch the app’s files, so the editor did not open. Click Reload to try again.
- The app rendered nothing — the app started without errors but put nothing on the page. See Find and fix problems.
Preview limitations
During preview:- Workbooks with an app cannot be promoted to another deployment.
- A PDF of a slide deck holds about 18 slides. Later slides are cut off.
- An app takes today’s date from the time zone of the viewer’s device, not from the time zone of the query. Close to midnight, a viewer far from that time zone can see the current period end a day early or late.
- Dashboard filter widgets and other controls do not apply to an
app. Build the controls into the app instead, or filter it from the embedding
page with
cube:action:set-filter. - An app cannot read reports from Source SQL tabs.
- Apps can read workbook report results but cannot write data back to a source.
- Available components and APIs may change as the feature develops.