0
# Superset UI Legacy Plugin Chart Event Flow
1

2
The @superset-ui/legacy-plugin-chart-event-flow package provides an Event Flow chart plugin for Apache Superset. It visualizes and compares the lengths of time different activities take in a shared timeline view, enabling users to understand temporal relationships and duration patterns across multiple events or processes.
3

4
## Package Information
5

6
- **Package Name**: @superset-ui/legacy-plugin-chart-event-flow  
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @superset-ui/legacy-plugin-chart-event-flow`
10

11
## Dependencies
12

13
- **@data-ui/event-flow**: "^0.0.84" - Core event flow visualization library
14
- **prop-types**: "^15.6.2" - Runtime type checking
15

16
### Peer Dependencies
17
- **react**: "^15 || ^16" - React framework
18
- **@superset-ui/chart-controls**: "*" - Superset chart control components
19
- **@superset-ui/core**: "*" - Core Superset functionality
20

21
## Core Imports
22

23
```typescript
24
import EventFlowChartPlugin from "@superset-ui/legacy-plugin-chart-event-flow";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const EventFlowChartPlugin = require("@superset-ui/legacy-plugin-chart-event-flow");
31
```
32

33
## Basic Usage
34

35
```typescript
36
import EventFlowChartPlugin from "@superset-ui/legacy-plugin-chart-event-flow";
37

38
// Register the plugin with Superset
39
new EventFlowChartPlugin().configure({ key: "event-flow" }).register();
40
```
41

42
Then use it via SuperChart:
43

44
```typescript
45
import { SuperChart } from "@superset-ui/core";
46

47
<SuperChart
48
  chartType="event-flow"
49
  width={600}
50
  height={600}
51
  formData={{
52
    // Required properties
53
    allColumnsX: "event_name", 
54
    entity: "user_id",
55
    minLeafNodeEventCount: 1,
56
    // Optional properties (available through control panel)
57
    orderByEntity: true,
58
    rowLimit: 1000,
59
    adhocFilters: [],
60
    allColumns: ["metadata_field"],
61
  }}
62
  queriesData={[{
63
    data: [
64
      { user_id: "123", event_name: "login", __timestamp: 1640995200000 },
65
      { user_id: "123", event_name: "click", __timestamp: 1640995260000 },
66
      // ... more event data
67
    ],
68
  }]}
69
/>
70
```
71

72
## Architecture
73

74
The plugin follows Superset's ChartPlugin architecture with several key components:
75

76
- **ChartPlugin Class**: Main plugin class that extends Superset's ChartPlugin base class
77
- **Chart Component**: React component (EventFlow) that renders the actual visualization using @data-ui/event-flow
78
- **Transform Props**: Data transformation function that converts Superset's format to the chart component's expected format
79
- **Control Panel**: Configuration UI that defines the form controls for chart settings
80
- **Lazy Loading**: Chart component and transform function are loaded on-demand for performance
81

82
## Capabilities
83

84
### Chart Plugin Registration
85

86
Main plugin class for registering the Event Flow chart with Superset.
87

88
```typescript { .api }
89
/**
90
 * Event Flow Chart Plugin for Apache Superset
91
 * Extends ChartPlugin to provide Event Flow visualization capabilities
92
 */
93
export default class EventFlowChartPlugin extends ChartPlugin {
94
  constructor();
95
}
96
```
97

98
The plugin is configured with:
99
- `loadChart`: Lazy-loaded EventFlow component
100
- `loadTransformProps`: Lazy-loaded data transformation function  
101
- `metadata`: Chart metadata including name, description, and settings
102
- `controlPanel`: Form control configuration
103

104
### Event Flow Component
105

106
React component that renders the Event Flow visualization.
107

108
```typescript { .api }
109
/**
110
 * Props interface for the EventFlow component
111
 */
112
interface EventFlowProps {
113
  /** Chart data as an array of time series records */
114
  data: TimeseriesDataRecord[];
115
  /** Chart height in pixels */
116
  height: number;
117
  /** Chart width in pixels */
118
  width: number;
119
  /** Initial minimum event count filter for leaf nodes */
120
  initialMinEventCount: number;
121
}
122

123
/**
124
 * Event Flow chart component that renders timeline visualization
125
 * @param data - Chart data as an array of time series records
126
 * @param initialMinEventCount - Initial minimum event count filter for leaf nodes
127
 * @param height - Chart height in pixels (default: 400)
128
 * @param width - Chart width in pixels (default: 400)
129
 * @returns React component rendering the event flow chart
130
 */
131
export default function EventFlow({
132
  data,
133
  initialMinEventCount,
134
  height = 400,
135
  width = 400,
136
}: EventFlowProps): JSX.Element;
137
```
138

139
### Data Transformation
140

141
Function that transforms Superset chart properties into EventFlow component props.
142

143
```typescript { .api }
144
/**
145
 * Form data interface for Event Flow chart configuration
146
 * Core properties used by transformProps: allColumnsX, entity, minLeafNodeEventCount
147
 * Additional properties available through Superset's control panel
148
 */
149
interface EventFlowFormData {
150
  /** Column name for event names (required) */
151
  allColumnsX: string;
152
  /** Column name for entity identifier (e.g., user ID) (required) */
153
  entity: string;
154
  /** Minimum event count for leaf nodes to be initially visible (required) */
155
  minLeafNodeEventCount: number;
156
  /** Whether to order results by entity ID (optional, available in control panel) */
157
  orderByEntity?: boolean;
158
  /** Maximum number of events to return (optional, standard Superset control) */
159
  rowLimit?: number;
160
  /** Adhoc filter configurations (optional, standard Superset control) */
161
  adhocFilters?: any[];
162
  /** Additional metadata columns (optional, available in control panel) */
163
  allColumns?: string[];
164
}
165

166
/**
167
 * Extended chart props interface including Event Flow specific form data
168
 */
169
interface EventFlowChartProps extends ChartProps {
170
  formData: EventFlowFormData;
171
  queriesData: {
172
    data: TimeseriesDataRecord[];
173
  }[];
174
}
175

176
/**
177
 * Transforms Superset chart properties into EventFlow component props
178
 * @param chartProps - Superset chart properties including form data and query results
179
 * @returns Props object for EventFlow component or null data object if no data
180
 */
181
export default function transformProps(chartProps: ChartProps): {
182
  data: TimeseriesDataRecord[] | null;
183
  height: number;
184
  width: number;
185
  initialMinEventCount?: number;
186
};
187
```
188

189
### Control Panel Configuration
190

191
Configuration object that defines the form controls available in Superset's chart configuration UI.
192

193
```typescript { .api }
194
/**
195
 * Control panel configuration for Event Flow chart
196
 * Defines the form controls and sections available in Superset's chart builder
197
 */
198
declare const controlPanel: ControlPanelConfig;
199
```
200

201
The control panel includes sections for:
202
- **Legacy Regular Time**: Standard time-based controls
203
- **Event Definition**: Entity ID and event name column selection  
204
- **Query**: Filter controls including adhoc filters and row limits
205
- **Additional Metadata**: Optional metadata column selection
206

207
Key form controls:
208
- `entity`: Entity ID column (e.g., user ID)
209
- `all_columns_x`: Event name column selection
210
- `min_leaf_node_event_count`: Minimum leaf node event count (1-10)
211
- `order_by_entity`: Checkbox to ensure proper entity ordering
212
- `row_limit`: Maximum number of events to return
213
- `all_columns`: Multi-select for additional metadata columns
214

215
## Types
216

217
```typescript { .api }
218
/**
219
 * Time series data record structure expected by the chart
220
 */
221
interface TimeseriesDataRecord {
222
  /** Timestamp of the event (required for temporal positioning) */
223
  __timestamp: number;
224
  /** Additional data fields as key-value pairs */
225
  [key: string]: any;
226
}
227

228
/**
229
 * Chart metadata configuration
230
 */
231
interface ChartMetadata {
232
  category: string;
233
  credits: string[];
234
  description: string; 
235
  name: string;
236
  tags: string[];
237
  thumbnail: string;
238
  useLegacyApi: boolean;
239
}
240

241
/**
242
 * Superset chart properties base interface
243
 */
244
interface ChartProps {
245
  formData: any;
246
  queriesData: any[];
247
  width: number;
248
  height: number;
249
}
250

251
/**
252
 * Control panel configuration structure
253
 */
254
interface ControlPanelConfig {
255
  controlPanelSections: any[];
256
  controlOverrides: any;
257
}
258
```
259

260
## Exported Interfaces
261

262
The package exports the following TypeScript interfaces for advanced usage:
263

264
```typescript { .api }
265
/**
266
 * Props interface for the EventFlow component
267
 */
268
export interface EventFlowProps {
269
  data: TimeseriesDataRecord[];
270
  height: number;
271
  width: number;
272
  initialMinEventCount: number;
273
}
274

275
/**
276
 * Form data interface for Event Flow chart configuration
277
 * Core properties used by transformProps: allColumnsX, entity, minLeafNodeEventCount
278
 * Additional properties available through Superset's control panel
279
 */
280
export interface EventFlowFormData {
281
  allColumnsX: string;
282
  entity: string;
283
  minLeafNodeEventCount: number;
284
  orderByEntity?: boolean;
285
  rowLimit?: number;
286
  adhocFilters?: any[];
287
  allColumns?: string[];
288
}
289

290
/**
291
 * Extended chart props interface including Event Flow specific form data
292
 */
293
export interface EventFlowChartProps extends ChartProps {
294
  formData: EventFlowFormData;
295
  queriesData: {
296
    data: TimeseriesDataRecord[];
297
  }[];
298
}
299
```
300

301
## Error Handling
302

303
The EventFlow component handles cases where no data is available by displaying a "Sorry, there appears to be no data" message. The transformProps function returns a null data object when no valid data is present, which the component handles gracefully.
304

305
For malformed data, the @data-ui/event-flow library's `cleanEvents` function is used to sanitize and validate the data structure before rendering.