Binding Chart Data — Chart Controls

The Binding Object

For array-based charts (bar, line, area, pie, scatter, histogram, heatmap), the binding is specified under settings.binding:

{
  "settings": {
    "binding": {
      "source": "$context",   // or "$json"
      "path": "analytics.pageViews"
    }
  }
}

For scalar gauges (gauge-radial, gauge-linear), the binding is specified under settings.value:

{
  "settings": {
    "value": {
      "source": "$context",
      "path": "kpi.npsScore"
    }
  }
}

Source: $context vs $json

Source	Where data lives	When to use
`$context`	The form's execution context — populated from `initialValues`, workflow node outputs, or real-time SignalR pushes	Dashboard forms, live KPI screens, data loaded via the form's `onLoad` action
`$json`	The form's editable field values (what the user is filling in)	Rarely used for charts — only if a user-entered field drives a chart (e.g., a forecast model)

Path Syntax

The path uses dot-notation to navigate nested objects:

// Flat path
"path": "monthlyRevenue"
// → context.monthlyRevenue

// Nested object
"path": "analytics.pageViews"
// → context.analytics.pageViews

// Array index (rare — usually you bind to the whole array)
"path": "departments[2].metrics"
// → context.departments[2].metrics

Loading Data into the Context

The most common pattern is a form action that calls an API on form load and stores the response in the context. Configure this via the form's actions array:

// Form-level actions configuration
{
  "actions": [
    {
      "id": "load-analytics",
      "type": "apiCall",
      "trigger": "onLoad",
      "settings": {
        "url": "/api/analytics/dashboard",
        "method": "GET",
        "storeResultIn": "context.analytics"
      }
    }
  ]
}

// Once the action completes, context.analytics contains the API response.
// Charts bound to "analytics.pageViews", "analytics.revenue", etc. render immediately.

Static Data (Design and Testing)

During form design and testing, bind charts to static data embedded in the form schema's initialValues:

{
  "initialValues": {
    "analytics": {
      "pageViews": [
        { "label": "Jan", "value": 12400 },
        { "label": "Feb", "value": 15200 },
        { "label": "Mar", "value": 13800 }
      ],
      "conversionRate": 3.7
    }
  }
}

Reactive Updates via SignalR

Charts update reactively whenever their bound path changes in the context. This includes real-time pushes from a workflow SignalR stream. A workflow execution node can push updated chart data without the user refreshing the page:

// Workflow node pushes updated KPI data via SignalR context update:
// The node output includes: { "context.kpi": { "npsScore": 78, "slaPercent": 96.4 } }
//
// All gauges and charts bound to context.kpi.* re-render immediately.
// No additional configuration needed in the form schema.

Expected Data Shapes per Chart Type

Chart Type	Data Shape
chart-bar (single)	`[{ label: string, value: number }]`
chart-bar (multi-series)	`[{ [labelKey]: string, [seriesKey]: number, ... }]`
chart-line (single)	`[{ label: string, value: number }]`
chart-line (multi-series)	`[{ [labelKey]: string, [seriesKey]: number, ... }]`
chart-area	Same as chart-line
chart-pie	`[{ label: string, value: number }]`
chart-scatter (standard)	`[{ x: number, y: number, label?: string }]`
chart-scatter (bubble)	`[{ x: number, y: number, size: number, label?: string }]`
chart-histogram (raw)	`[{ value: number }]` or `number[]`
chart-histogram (bucketed)	`[{ label: string, value: number }]`
chart-heatmap	`[{ row: string, col: string, value: number }]`
gauge-radial / gauge-linear	Single `number` (scalar, not array)

Troubleshooting Empty Charts

Symptom	Likely Cause	Fix
Chart renders but is blank	Path resolves to `null` or `undefined`	Check the `path` matches the actual context key; inspect context in the browser console
Chart renders blank on first load	API action hasn't completed yet	Add a loading state or use a skeleton placeholder until `onLoad` action completes
Chart shows "No data"	Data is an empty array `[]`	Check your API returns rows; add `emptyMessage` setting for clarity
Wrong values displayed	Wrong key names in data vs `labelKey`/`seriesKey` settings	Ensure `labelKey` and series `key` values match the actual property names in data objects
Gauge shows 0 despite data	`value` binding resolves to string instead of number	Ensure the API returns numeric values; cast on server or use a transform

Design Pattern: Dashboard Form The canonical pattern for a chart-heavy dashboard is: (1) Create a form in view or admin mode. (2) Add an onLoad API action that fetches all KPI data and stores it in context. (3) Bind all charts to paths within that context object. (4) Use modeVisibilitySettings to hide charts in edit mode if the form also collects data.

← Linear Gauge