Validate Analytics Page Definition

Check a body for Set Analytics Page Definition without saving anything. It answers every problem Set would refuse, each with its JSON Pointer. Unlike Validate Workflow Definition it answers no definition or refs: a new panel gets its id only when it is written, so Set Analytics Page Definition answers both. A click or container naming a panel the body creates is checked for its event and target here, and in full when it is written.

POST

Path

Path parameters

stringrequired

The page id, from List Analytics Pages.

Headers

Optional headers

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

validboolean

True when Set Analytics Page Definition would accept this body against the draft as it is now.

revisionstring

The draft revision it was checked against.

issuesarray of objects

Every problem with the body, each with its JSON Pointer.

pathstring
A JSON Pointer to the problem in the body.
codestring
What is wrong, such as UNKNOWN_PANEL, DUPLICATE_REF or INVALID_ARGS.
messagestring
What is wrong and how to fix it.