Understanding changedItem in Dashboard Designer

Overview

The changedItem object is a critical event payload in Dashboard Designer, used to handle data updates and user interactions dynamically. It serves as a bridge between backend data and frontend components, enabling developers to create dashboards that respond intelligently to changes in data or user actions.

changedItem is accessible in both:

• Connection Scripts (to handle dataset-level data loads), and

• Component Scripts (to handle user-driven interactions like clicks or selections).

This guide explains the structure, usage, and best practices for implementing changedItem in both contexts.

Using changedItem in Connections

Purpose

When used within connection scripts, the changedItem payload provides direct access to the data records retrieved from the connected data source. This enables real-time updates of dashboard components (such as labels, KPIs, and charts) based on the latest data.

Structure

changedItem.attributes.data

• Returns an array of objects, each representing a record retrieved from the data source.

• The data array can be iterated or accessed directly using index notation (e.g., data[0].field_name).

Example: Updating a Label Based on Connection Data

var len = changedItem.attributes.data.length;

if (len > 0) {
    sdk.setValue('label13', changedItem.attributes.data[0].total_transactions);
} else {
    sdk.setValue('label13', 0);
}

Explanation:

• changedItem.attributes.data.length — Checks how many records were returned from the data source.

• data[0].total_transactions — Accesses the value of the field total_transactions in the first record.

• sdk.setValue() — Dynamically updates the label component (label13) with the retrieved value.

• The else condition ensures that a fallback value (0) is displayed if the dataset is empty.

• Use Case: Ideal for KPIs and Labels that display summary metrics like total sales, transaction counts, or revenue.

Using changedItem in Components

Purpose

Within component scripts, changedItem captures user-driven events such as clicks, selections, or drill-down interactions. This allows dashboards to respond dynamically — for example, by filtering other charts, highlighting selections, or updating global variables.

Common Properties

Property	Description
changedItem.attributes.Value	Returns the value clicked or selected on a single-value component (e.g., Pie Chart slice, Bar, or Point).
changedItem.attributes.event_order	Returns the field name associated with the clicked data point (used in multi-value components).
changedItem.attributes.drillComponent.drillColor	Returns the color of the clicked slice or chart element. Useful for maintaining consistent visual context during drill-downs.

Example: Capturing User Clicks in a Chart

// Update a global variable with the clicked event name
sdk.updateGlobalVariable('label39', {
    'Value': changedItem.attributes.event_name
}, false);

Explanation:

• changedItem.attributes.event_name — Retrieves the name of the clicked chart event.

• sdk.updateGlobalVariable() — Updates a global variable (label39) with the captured value.

• The global variable can then be used by other components (e.g., charts, filters) to maintain a consistent drill-down context.

• The false parameter ensures that the update does not trigger an immediate reload.

• Use Case: Useful for drill-down navigation, cross-component filtering, or context sharing between multiple charts and dashboards.

3. Best Practices

Follow these guidelines to ensure reliable and efficient use of changedItem :

Guideline	Recommendation
Check for Data Availability	Always verify changedItem.attributes.data.length > 0 before accessing records. Prevents runtime errors when datasets are empty.
Graceful Handling	Use else conditions to handle cases where data is missing or invalid.
Drill-Down Context	Capture both the clicked value and color (drillColor) to maintain visual and logical context during drill-down operations.
Global Variable Sharing	Use sdk.updateGlobalVariable() to store clicked values for reuse in other dashboard components.
Avoid Hardcoded References	Use parameterized references or global variables instead of static component IDs for scalability.

Example Use Cases

Example 1 – Update a Label Using Connection Data

var len = changedItem.attributes.data.length;

if (len > 0) {
    sdk.setValue('label10', changedItem.attributes.data[0].total_sales);
} else {
    sdk.setValue('label10', 0);
}

• Result: Updates label10 with the total_sales field value from the first record retrieved by the connection.

Example 2 – Capture Click Event and Trigger Data Reload

// Capture the clicked value
var category = changedItem.attributes.Value;

// Set context for dependent charts
sdk.setContext('selected_category', category);

// Reload dependent datasets
sdk.reload(['C_2', 'C_3']);

• Result: Clicking on a chart element triggers the reloading of all dependent data services that filter based on the selected category.

Example 3 – Store Drill-Down Selection as a Global Variable

sdk.updateGlobalVariable('selectedBrand', {
    'Value': changedItem.attributes.Value,
    'Color': changedItem.attributes.drillComponent.drillColor
}, false);

• Result: Stores both the clicked brand name and its color, allowing other charts to align their visuals during drill-down or context-based filtering.

Summary

The changedItem object is a powerful event handler that enables dynamic, data-driven interactivity in Dashboard Designer. It seamlessly connects backend data events and user interactions, allowing dashboards to respond in real-time to:

• Data updates from connections.

• Clicks or selections on charts and components.

• Drill-down or contextual filtering actions.

By understanding and implementing changedItem in both connection scripts and component scripts, developers can build highly interactive, responsive, and intelligent dashboards on the BDB Platform.

Quick Reference

Context	Key Property	Purpose
Connection	changedItem.attributes.data	Access data records returned from a data source.
Component	changedItem.attributes.Value	Retrieve the user-clicked value on a chart or component.
Component	changedItem.attributes.drillComponent.drillColor	Capture the color of the clicked chart element.
Any	sdk.updateGlobalVariable()	Store and share event data between dashboard components.