ObjectStackObjectStack

Dashboard Metadata

Build analytics dashboards with chart widgets, global filters, and auto-refresh

Dashboard Metadata

A Dashboard defines an analytics page with chart widgets, key metrics, and data visualizations. Dashboards support configurable layouts, global date filters, and auto-refresh.

Basic Structure

const salesDashboard = {
  name: 'sales_overview',
  label: 'Sales Overview',
  description: 'Key sales metrics and pipeline analysis',
  refreshInterval: 300,     // Refresh every 5 minutes

  dateRange: {
    field: 'close_date',
    defaultRange: 'this_quarter',
    allowCustomRange: true,
  },

  widgets: [
    {
      title: 'Total Revenue',
      type: 'metric',
      object: 'opportunity',
      valueField: 'amount',
      aggregate: 'sum',
      layout: { x: 0, y: 0, w: 3, h: 2 },
    },
    {
      title: 'Pipeline by Stage',
      type: 'bar',
      object: 'opportunity',
      categoryField: 'stage',
      valueField: 'amount',
      aggregate: 'sum',
      layout: { x: 3, y: 0, w: 6, h: 4 },
    },
    {
      title: 'Win Rate',
      type: 'pie',
      object: 'opportunity',
      categoryField: 'status',
      valueField: 'id',
      aggregate: 'count',
      layout: { x: 9, y: 0, w: 3, h: 4 },
    },
  ],
};

Dashboard Properties

PropertyTypeRequiredDescription
namestring✅Machine name (snake_case)
labelstring✅Display label
descriptionstringoptionalDashboard description
widgetsDashboardWidget[]✅Chart and metric widgets
refreshIntervalnumberoptionalAuto-refresh interval (seconds)
dateRangeobjectoptionalGlobal date range filter
globalFiltersGlobalFilter[]optionalGlobal filter controls

Widgets

Each widget defines a data visualization:

{
  title: 'Monthly Revenue',
  type: 'line',
  object: 'invoice',
  categoryField: 'invoice_date',
  valueField: 'total',
  aggregate: 'sum',
  filter: { field: 'status', operator: 'eq', value: 'paid' },
  layout: { x: 0, y: 0, w: 6, h: 4 },
}

Widget Properties

PropertyTypeRequiredDescription
titlestring✅Widget display title
typeChartType✅Visualization type (see below)
objectstring✅Source object name
categoryFieldstringoptionalField for categories/X-axis
valueFieldstringoptionalField for values/Y-axis
aggregateenumoptionalAggregation function
filterFilterConditionoptionalData filter criteria
layoutobject✅Grid position and size
chartConfigobjectoptionalAdvanced chart configuration
optionsobjectoptionalAdditional display options
responsiveobjectoptionalResponsive behavior

Chart Types

TypeDescriptionBest For
metricSingle number KPIRevenue, count, percentage
barBar chart (vertical/horizontal)Category comparison
lineLine chartTrends over time
piePie/donut chartDistribution
areaArea chartVolume over time
scatterScatter plotCorrelation
radarRadar chartMulti-dimensional comparison
funnelFunnel chartConversion stages
gaugeGauge/speedometerProgress toward goal
heatmapHeat mapDensity visualization
treemapTree mapHierarchical proportions
tableData table widgetDetailed records

Aggregation Functions

FunctionDescription
countCount records
sumSum values
avgAverage values
minMinimum value
maxMaximum value

Widget Layout

Widgets are positioned on a 12-column grid:

layout: {
  x: 0,    // Column position (0-11)
  y: 0,    // Row position
  w: 6,    // Width in columns (1-12)
  h: 4,    // Height in rows
}

Date Range

Configure a global time filter that applies to all widgets:

dateRange: {
  field: 'created_at',
  defaultRange: 'this_month',
  allowCustomRange: true,
}

Preset Ranges

RangeDescription
todayCurrent day
yesterdayPrevious day
this_weekCurrent week
last_weekPrevious week
this_monthCurrent month
last_monthPrevious month
this_quarterCurrent quarter
last_quarterPrevious quarter
this_yearCurrent year
last_yearPrevious year
last_7_daysRolling 7 days
last_30_daysRolling 30 days
last_90_daysRolling 90 days
customUser-defined range

Global Filters

Add interactive filter controls that apply to all widgets:

globalFilters: [
  { field: 'region', label: 'Region', type: 'select' },
  { field: 'owner', label: 'Sales Rep', type: 'lookup' },
]

Complete Example

const projectDashboard = {
  name: 'project_overview',
  label: 'Project Overview',
  description: 'Real-time project health metrics',
  refreshInterval: 60,

  dateRange: {
    field: 'created_at',
    defaultRange: 'this_month',
    allowCustomRange: true,
  },

  globalFilters: [
    { field: 'project', label: 'Project', type: 'lookup' },
    { field: 'assignee', label: 'Team Member', type: 'lookup' },
  ],

  widgets: [
    {
      title: 'Open Tasks',
      type: 'metric',
      object: 'project_task',
      valueField: 'id',
      aggregate: 'count',
      filter: { field: 'status', operator: 'neq', value: 'done' },
      layout: { x: 0, y: 0, w: 3, h: 2 },
    },
    {
      title: 'Completed This Week',
      type: 'metric',
      object: 'project_task',
      valueField: 'id',
      aggregate: 'count',
      filter: { field: 'status', operator: 'eq', value: 'done' },
      layout: { x: 3, y: 0, w: 3, h: 2 },
    },
    {
      title: 'Tasks by Status',
      type: 'pie',
      object: 'project_task',
      categoryField: 'status',
      valueField: 'id',
      aggregate: 'count',
      layout: { x: 6, y: 0, w: 3, h: 4 },
    },
    {
      title: 'Tasks by Priority',
      type: 'bar',
      object: 'project_task',
      categoryField: 'priority',
      valueField: 'id',
      aggregate: 'count',
      layout: { x: 9, y: 0, w: 3, h: 4 },
    },
    {
      title: 'Completion Trend',
      type: 'line',
      object: 'project_task',
      categoryField: 'completed_at',
      valueField: 'id',
      aggregate: 'count',
      layout: { x: 0, y: 4, w: 12, h: 4 },
    },
  ],
};

On this page

Dashboard MetadataBasic StructureDashboard PropertiesWidgetsWidget PropertiesChart TypesAggregation FunctionsWidget LayoutDate RangePreset RangesGlobal FiltersComplete ExampleRelated