Set Analytics Page Definition

Set a page's whole draft in one call: the fastest way to build a page, and the one to use from an agent. Send the page settings, variables, tabs and panels as Get Analytics Page Definition answers them. Name a panel or tab the page has by its id; give a new one a ref of your own and name it by that ref anywhere in the body: a click's panelId, a container's items, a panel's tabId. A panel left out is deleted; settings, variables and tabs left out stay as they are. Within a panel only what differs from the draft is written: a field you send replaces it, except the maps format, links and style and each settings block, which merge over what is stored; send a key as null to remove it. A tab left out is deleted, and a panel you keep must name a tab you keep in tabId; tabs null turns tabs off and keeps every panel. Data sources are not part of a page: make them with Create Analytics Data Source first and name them in each panel's dataSources. Every problem is answered at once, each with its JSON Pointer, before anything is written. The whole change is one undo step (Undo Analytics Page reverses it). Send the revision you last read in If-Match. The answer is the definition as written, with the id each ref got. Viewers see the change once the page is published.

PUT

Path

Path parameters

stringrequired

The page id, from List Analytics Pages.

Headers

Optional headers

stringrequired

Required. The revision you last read: the revision from its read (Get Workflow Definition for a workflow, Get Analytics Page Definition for an Analytics page, Get Analytics Data Source Table for a fixed source's table), or meta.revision from your last change to it. The ETag header of either answer is the same value, ready to send back. The change applies only if nobody changed it since: otherwise it answers 412 with the current revision in error.details.revision. Send it as a strong entity tag ("r_..."): a weak one (W/"...") never matches and answers 412. Without it the request answers 428.

string

Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. Here a key acts in another organization only as one of its members: with "Use this key across all of your organizations" on, in an organization its creator belongs to with a role. Child organizations and MindCloud staff access do not reach this endpoint. Every response's X-Company-Id header names the organization it acted in. See Organizations.

Body

Arguments

object

The page settings; only those that differ are written.

The page settings, as Update Analytics Page takes them. Left out, they stay as they are; a setting left out of page stays too.

namestring
The page title.
descriptionstring
The line under the title, or null when it has none.
iconstring
An icon id from the app icon catalog, or null when it has none.
iconColorstring
An icon color from the app palette, or null when it has none.
fullWidthboolean
Whether the page spans the whole window.
showPanelSourcesboolean
Whether each panel shows its data sources' app icons.
themeIdstring
A theme id from List Analytics Themes, or null to follow the folder or company default.
styleobject
Style overrides on top of the theme, by option key, such as { "seriesColors": [...] }. Each option sent replaces that option, null clears one, and style null clears every override. Values are checked against the theme's option registry.
isPausedboolean
true stops the page's data from refreshing; false resumes it (a folder above it can still keep it paused).

array

Every page variable, in page order.

Every variable (filter) the page should have, in page order, as Set Analytics Page Variables takes them. Left out, they stay as they are.

array

Every tab, in order, or null for none.

Every tab the page should have, in order, or null for no tabs. Left out, they stay as they are. A tab left out is deleted with the panels on it.

idstring
An existing tab id, from Get Analytics Page Definition, to keep that tab.
refstring
Your own name for a new item, used in place of its id anywhere in this body. The answer maps each ref to the id it got.
namestringrequired
The tab name.

array of objectrequired

Every panel the page should have. A new one has a ref; an existing one its id.

Every panel the page should have, at most 100. A panel left out is deleted.

idstring
An existing panel id on this page, from Get Analytics Page Definition, to keep and change that panel.
refstring
Your own name for a new item, used in place of its id anywhere in this body. The answer maps each ref to the id it got.
namestring
The panel's title. Setting it turns off automatic renaming for this panel.
descriptionstring
The line under the title when the panel opens as a full-page drill-down view. An empty string clears it.
placementstring
page puts the panel on the grid; drill takes it off the grid, to open when another panel drills into it.
- page
- drill
dataSourcesarray of objects
Every data source feeding the panel, in order. Replaces the list.
- dataSourceIdstringrequired
  The data source, from List Analytics Data Sources.
- aliasstring
  The name the query and transform code use for the source's rows. Made from the source's name when left out.
- querystring
  DuckDB SQL over the source's rows, with the alias as the table name: filter, group, sort and limit here. An empty string shows every row.
- followPageDateboolean
  false keeps the page's date filter off this source (an all-time figure).
transformCodestring
JavaScript function body receiving each source as a named input ({ alias }) and returning the rows to show. Use it only for what SQL cannot do. Saving it runs it; read the result with Get Analytics Panel Output. An empty string removes it.
displayTypestring
How the panel draws its rows. One of: table, bar, line, combo, pareto, bump, scatter, bubble, quadrant, pie, treemap, heatmap, pivot, cohort, statusgrid, activity, funnel, waterfall, sankey, chord, statetimeline, timeline, stat, trend, progress, gauge, bullet, report, document, workbook, html, map, region, tabs, group.
- table
- bar
- line
- combo
- pareto
- bump
- scatter
- bubble
- quadrant
- pie
- treemap
- heatmap
- pivot
- cohort
- statusgrid
- activity
- funnel
- waterfall
- sankey
- chord
- statetimeline
- timeline
- stat
- trend
- progress
- gauge
- bullet
- report
- document
- workbook
- html
- map
- region
- tabs
- group
columnsarray of objects
Table panels: the columns shown, in order. Replaces the list; an empty list lets the panel pick its columns from the rows. Null clears them.
- keystringrequired
  The row key to show (dot paths allowed). A button column takes an identifier you choose, which names its click event "button:<key>".
- typestring
  How the value is formatted: string, number, percent, ratio, currency, duration, rank, boolean, date, object, list, html, button.
  - string
  - number
  - percent
  - ratio
  - currency
  - duration
  - rank
  - boolean
  - date
  - object
  - list
  - html
  - button
- labelstring
  Button columns: the text on the button.
- tooltipstring
  Button columns: one sentence shown on hover.
- widthnumber or string
  The width in pixels, 64-800. An empty string returns it to the width of its content.
formatobject
How each column's values are formatted, keyed by column: { "<column>": { "type": "currency" } }. Merged over what is stored; null for a column takes its format off. Null clears every format.
linksobject
Table panels: the link each cell of a column opens, keyed by column. Merged over what is stored; null for a column takes its link off. Null clears every link.
styleobject
The color of each series or category, keyed by its name. Merged over what is stored; null for a name takes its color off. Null clears every color.
settingsobject
The settings of the panel's display type, keyed by block (annotations, tooltip, chart, bump, scatter, pie, treemap, cellGrid, statusGrid, activity, funnel, waterfall, sankey, chord, statetimeline, stat, trend, target, report, document, workbook, html, map, region, tabs, group), as Get Analytics Panel answers them. A block is refused on a type that does not draw it.
- annotationsobject
  The annotations settings. A block you send is merged over the stored one: send only the fields you change.
- tooltipobject
  The tooltip settings. A block you send is merged over the stored one: send only the fields you change.
- chartobject
  The chart settings. A block you send is merged over the stored one: send only the fields you change.
- bumpobject
  The bump settings. A block you send is merged over the stored one: send only the fields you change.
- scatterobject
  The scatter settings. A block you send is merged over the stored one: send only the fields you change.
- pieobject
  The pie settings. A block you send is merged over the stored one: send only the fields you change.
- treemapobject
  The treemap settings. A block you send is merged over the stored one: send only the fields you change.
- cellGridobject
  The cellGrid settings. A block you send is merged over the stored one: send only the fields you change.
- statusGridobject
  The statusGrid settings. A block you send is merged over the stored one: send only the fields you change.
- activityobject
  The activity settings. A block you send is merged over the stored one: send only the fields you change.
- funnelobject
  The funnel settings. A block you send is merged over the stored one: send only the fields you change.
- waterfallobject
  The waterfall settings. A block you send is merged over the stored one: send only the fields you change.
- sankeyobject
  The sankey settings. A block you send is merged over the stored one: send only the fields you change.
- chordobject
  The chord settings. A block you send is merged over the stored one: send only the fields you change.
- statetimelineobject
  The statetimeline settings. A block you send is merged over the stored one: send only the fields you change.
- statobject
  The stat settings. A block you send is merged over the stored one: send only the fields you change.
- trendobject
  The trend settings. A block you send is merged over the stored one: send only the fields you change.
- targetobject
  The target settings. A block you send is merged over the stored one: send only the fields you change.
- reportobject
  The report settings. A block you send is merged over the stored one: send only the fields you change.
- documentobject
  The document settings. A block you send is merged over the stored one: send only the fields you change.
- workbookobject
  The workbook settings. A block you send is merged over the stored one: send only the fields you change.
- htmlobject
  The html settings. A block you send is merged over the stored one: send only the fields you change.
- mapobject
  The map settings. A block you send is merged over the stored one: send only the fields you change.
- regionobject
  The region settings. A block you send is merged over the stored one: send only the fields you change.
- tabsobject
  The tabs settings. A block you send is merged over the stored one: send only the fields you change. { items: [panel ids], ... } replaces the child list; null releases every child back to the grid.
- groupobject
  The group settings. A block you send is merged over the stored one: send only the fields you change. { items: [panel ids], ... } replaces the child list; null releases every child back to the grid.
onobject
What clicking the panel's items does, keyed by event: rowClick, valueClick and the other events the display type fires, or "button:<column key>" for a button column. Replaces every wiring; null clears them all.
interactionobject
Stat panels: make the tile a control that flips a toggle page variable. null makes it a normal panel again.
- togglesstringrequired
  The toggle page variable the tile flips.
paramsobject
Drill-down panels: labels for the $params the source SQL reads, keyed by param. Replaces them; null clears them.
displayCodestring
Advanced display: JavaScript function body that returns the display settings from the page variables. It is run when you save. An empty string goes back to the static settings and keeps the code.
aiSnippetsCodestring
Report panels: JavaScript function body returning { KEY: { prompt, additionalContext } } for the {{KEY}} tokens the transform writes. An empty string removes it.
layoutobject
The panel's place on the grid. Null on a drill-down or a panel inside a container, which take none; null on a grid panel keeps its place.
- xnumberrequired
  Leftmost column, 0-11.
- ynumberrequired
  Top row, from 0.
- wnumberrequired
  Width in columns, 1-12.
- hnumber
  Height in rows; null or left out keeps the panel as tall as what it shows.
heightModestring
auto takes a fixed height off, so the panel is as tall as what it shows.
- auto
tabIdstring
The tab the panel sits on: a tab id, or a tab ref from tabs. Required on a new grid panel when the page has tabs; null keeps an existing panel on its tab.

array of string

Every receipt a 409 ANALYTICS_EMBED_CONFIRMATION_REQUIRED answered for this body.

Only after a 409 ANALYTICS_EMBED_CONFIRMATION_REQUIRED for this body: every confirmationReceipt such answers gave, confirming the changes to the published embeds they list. A body that deletes several embedded panels or tabs collects one receipt per deletion.

string

Ignored; send the revision in If-Match.

Ignored, so a definition read can be sent back as it is. Send the revision in If-Match.

Response fields

pageobject

The page settings, as Update Analytics Page takes them.

namestring
The page title.
descriptionstring
The line under the title, or null.
iconstring
The page icon id, or null.
iconColorstring
The page icon color, or null.
fullWidthboolean
Whether the page spans the whole window.
showPanelSourcesboolean
Whether each panel shows its data sources' app icons.
themeIdstring
The page theme, from List Analytics Themes, or null when it follows its folder or the company default.
styleobject
Style overrides on top of the theme, by option key, or null.
isPausedboolean
Whether the page's own data refreshes are paused.

variablesarray of objects

The page variables (its filters), in page order, as Set Analytics Page Variables takes them.

namestring
The variable name. Queries read it as $<name>.
typestring
What it holds.
- dateRangeA date window.
- selectOne value, or several with multiple, from a list of choices.
- searchFree text a viewer types.
- toggleAn on or off switch.
controlstring
chip shows a picker on the page; none has no picker.
- chip
- none
labelstring
The picker label.
defaultobject
What the page opens with: a date preset or range, all or a choice value, or true or false for a toggle.
multipleboolean
A select that takes several choices.
labeledBystring
A select set by a row click: the clicked row field that names the value.
optionsobject
A select: where its choices come from, as dataSourceId with query or valueField and labelField, or typed values.
presetsarray
A dateRange: its preset menu, in order.
showCalendarboolean
A dateRange: false allows presets only.
timeGranularityboolean
A dateRange: custom ranges carry times.

tabsarray of objects

The page tabs, in order, or null when the page has none.

idstring
The tab id.
namestring
The tab name.

panelsarray of objects

Every panel in the draft, in the shape Update Analytics Panel takes, with its grid place and tab.

idstring
The panel id.
namestring
The panel's title, shown in its card header.
descriptionstring
The line under the title when the panel opens as a full-page drill-down view.
placementstring
Where the panel shows.
- pageOn the page grid.
- drillOff the grid: it opens when a click on another panel drills into it, narrowed by the clicked row.
displayTypestring
How the panel draws its rows. One of: table, bar, line, combo, pareto, bump, scatter, bubble, quadrant, pie, treemap, heatmap, pivot, cohort, statusgrid, activity, funnel, waterfall, sankey, chord, statetimeline, timeline, stat, trend, progress, gauge, bullet, report, document, workbook, html, map, region, tabs, group.
- tableDraws a table panel.
- barDraws a bar panel.
- lineDraws a line panel.
- comboDraws a combo panel.
- paretoDraws a pareto panel.
- bumpDraws a bump panel.
- scatterDraws a scatter panel.
- bubbleDraws a bubble panel.
- quadrantDraws a quadrant panel.
- pieDraws a pie panel.
- treemapDraws a treemap panel.
- heatmapDraws a heatmap panel.
- pivotDraws a pivot panel.
- cohortDraws a cohort panel.
- statusgridDraws a statusgrid panel.
- activityDraws a activity panel.
- funnelDraws a funnel panel.
- waterfallDraws a waterfall panel.
- sankeyDraws a sankey panel.
- chordDraws a chord panel.
- statetimelineDraws a statetimeline panel.
- timelineDraws a timeline panel.
- statDraws a stat panel.
- trendDraws a trend panel.
- progressDraws a progress panel.
- gaugeDraws a gauge panel.
- bulletDraws a bullet panel.
- reportDraws a report panel.
- documentDraws a document panel.
- workbookDraws a workbook panel.
- htmlDraws a html panel.
- mapDraws a map panel.
- regionDraws a region panel.
- tabsDraws a tabs panel.
- groupDraws a group panel.
dataSourcesarray
The data sources feeding the panel, in order.
- dataSourceIdstring
  The data source, from List Analytics Data Sources.
- aliasstring
  The name the source's query and the transform code use for its rows.
- querystring
  DuckDB SQL over this source's rows, with the alias as the table name. Empty when the panel shows every row as stored.
- followPageDateboolean
  Whether the page's date filter narrows this source. False for an all-time figure on a date-filtered page.
transformCodestring
JavaScript function body that receives each source as a named input and returns the rows to show. Empty when the source queries return the rows directly.
columnsarray
Table panels: the columns shown, in order. Null when the panel picks its columns from the rows.
- keystring
  The row key the column shows (dot paths allowed). For a button column, the identifier that names its click event.
- typestring
  How the value is formatted and aligned. Absent for plain text.
  - stringFormats the value as string.
  - numberFormats the value as number.
  - percentFormats the value as percent.
  - ratioFormats the value as ratio.
  - currencyFormats the value as currency.
  - durationFormats the value as duration.
  - rankFormats the value as rank.
  - booleanFormats the value as boolean.
  - dateFormats the value as date.
  - objectFormats the value as object.
  - listFormats the value as list.
  - htmlFormats the value as html.
  - buttonFormats the value as button.
- labelstring
  Button columns: the text on the button.
- tooltipstring
  Button columns: the sentence shown on hover.
- widthnumber
  The column width in pixels for everyone. Absent when the column is as wide as its content.
formatobject
How each column's values are formatted, keyed by column, for any display type: { "<column>": { "type": "currency", ... } }. Null when none is set.
linksobject
Table panels: the link each cell of a column opens, keyed by column. Null when none is set.
styleobject
The color of each series or category, keyed by its name. Null when none is set.
settingsobject
The settings of the panel's display type, keyed by block: annotations, tooltip, chart, bump, scatter, pie, treemap, cellGrid, statusGrid, activity, funnel, waterfall, sankey, chord, statetimeline, stat, trend, target, report, document, workbook, html, map, region, tabs, group. Only the blocks the panel stores are present.
onobject
What clicking the panel's items does, keyed by event (rowClick, valueClick, "button:<column key>" ...): { "rowClick": { "action": "navigatePage", "pageId": "..." } }. Empty when nothing is wired.
interactionobject
Stat panels: the toggle page variable a click on the tile flips. Null for a normal panel.
- togglesstring
  The toggle page variable.
paramsobject
Drill-down panels: the human label of each $param its SQL reads, keyed by param: { "userId": { "label": "User", "labeledBy": "userName" } }. Null when none is declared.
displayCodestring
JavaScript function body that returns the display settings from the page variables. Kept, but unused, while displayMode is basic.
aiSnippetsCodestring
Report panels: JavaScript function body returning the AI-written sections of the report. Empty when it has none.
layoutobject
The panel's place on the page grid. Null when it was never placed (it then flows full width in creation order), and for a drill-down or a panel inside a container.
- xnumber
  Leftmost column on the 12-column grid, 0-11.
- ynumber
  Top row, from 0.
- wnumber
  Width in columns, 1-12.
- hnumber
  Height in rows (one row is about 48px). Null when the panel is as tall as what it shows.
tabIdstring
The page tab the panel sits on, from Get Analytics Page. Null on a page without tabs, and for a drill-down or a panel inside a container.

revisionstring

The draft revision: send it in If-Match to Set Analytics Page Definition. It changes whenever anything in this definition does.

refsobject

The id each new panel and tab got, by its ref.

panelsobject
{ <ref>: <panel id> } for each new panel.
tabsobject
{ <ref>: <tab id> } for each new tab.