State graph

Category: Control

Version: 1.0

Last Updated: February 24, 2026

Author: Any2Info

---

Description

The Stategraph control visualizes state-based timelines on a dashboard using a linked Dataclip as its data source.

The control renders horizontally stacked state segments across a time-based X-axis. Each segment represents a specific state during a defined time span. The Y-axis represents distinct items (YItems), where each item contains a sequence of non-overlapping state segments.

This control is designed for visualizing lifecycle transitions, operational states, and time-bound progressions.

---

Data Model

Each row in the linked Dataclip represents a single state interval.

Expected structure example:

YItems	StateStart	StateEnd	StateLabel	StateColor

Multiple rows per YItem are expected. Each YItem results in a distinct horizontal line composed of sequential state segments.

Segments must not overlap for the same YItem. Each timespan represents exactly one state.

---

Required Mappings

All mappings listed below are mandatory.

Mapping	Required	Description
YItems	Yes	Determines the items displayed on the Y-axis. Each distinct value results in a separate horizontal line in the graph.
StateStart	Yes	Defines the start datetime of the state segment.
StateEnd	Yes	Defines the end datetime of the state segment. Together with StateStart, determines the duration of the segment.
StateLabel	Yes	Defines the textual value representing the state shown within the segment.
StateColor	Yes	Defines the visual color of the state segment.

Correct behavior depends heavily on proper field typing and clean time interval logic in the Dataclip.

---

Rendering Behavior

• The X-axis represents time.

• The Y-axis represents distinct YItems.

• Each YItem renders as a sequence of horizontally stacked segments.

• Segments are generated based on distinct YItem values encountered in the dataset.

• Segments for the same YItem must not overlap.

• Each segment represents exactly one state during a specific time span.

If overlapping segments exist for the same YItem, rendering behavior is undefined and may result in visual inconsistencies.

---

Interaction

Hover Tooltip

Each segment provides a hover tooltip.

The tooltip displays contextual information derived from the mapped fields, typically including:

• YItem

• StateLabel

• StateStart

• StateEnd

This enables precise inspection of state durations without cluttering the visual layout.

Zooming

Basic graph zoom functionality is supported.

Users can zoom into a specific time range on the X-axis to inspect shorter intervals in greater detail. Zooming affects only the visible time window and does not modify the underlying dataset.

---

Supported Events

onUpdate

Trigger condition: The onUpdate event is triggered when the graph updates its data.

This occurs when:

• The control performs its initial data load.

• A linked value changes, causing the Dataclip to refresh.

• The underlying dataset is re-evaluated.

This event can be used to:

• Trigger dependent dashboard logic

• Synchronize other controls

• Execute follow-up actions after data refresh

---

Usage

Use the Stategraph control when visualizing:

• Machine or production states (Running, Idle, Error)

• Order lifecycle progression

• Case or workflow transitions

• SLA tracking

• Resource availability timelines

The control is particularly suited for scenarios where:

• State transitions occur over time

• Duration is a key dimension

• Sequential state progression must be visually clear

---

Data Requirements & Constraints

• StateStart and StateEnd must be valid datetime values.

• StateStart must be earlier than StateEnd.

• Segments for the same YItem must not overlap.

• All required mappings must be configured.

• Missing mappings prevent correct rendering.

Data preparation and validation at the Dataclip level are essential.

---

Tips & Best Practices

• Pre-sort data by YItems and StateStart for consistent rendering.

• Validate that no overlapping intervals exist per YItem before binding.

• Use consistent StateColor values for identical states across YItems.

• Limit the number of YItems to maintain dashboard readability.

• Use zoom functionality for detailed time analysis.

• Leverage onUpdate when synchronization with other dashboard components is required.

---

Errors & Troubleshooting

Issue	Possible Cause	Solution
Segments overlap visually	Overlapping StateStart/StateEnd values for same YItem	Validate dataset to ensure non-overlapping intervals
Graph not rendering	Missing required mapping	Verify all five required mappings are configured
Incorrect durations	Invalid datetime format	Validate Dataclip field types
Graph not refreshing as expected	Linked value not triggering update	Verify data binding and event configuration

---

Changelog

Version	Date	Change
1.0	February 24, 2026	Initial documentation version added.