0
# Dashboard Management
1

2
Visual dashboard creation, widget management, and sharing capabilities. Dashboards provide web-based visualization and control interfaces for IoT things and their properties.
3

4
## Capabilities
5

6
### Core Dashboard Operations
7

8
Primary dashboard management functionality for creating and managing visual interfaces.
9

10
```javascript { .api }
11
class DashboardsV2Api {
12
  /**
13
   * Create a new dashboard
14
   * @param dashboardv2 - Dashboard configuration including widgets and layout
15
   * @param opts - Optional parameters including organization ID
16
   * @returns Promise<ArduinoDashboardv2> - Created dashboard object
17
   */
18
  dashboardsV2Create(dashboardv2: Dashboardv2, opts?: any): Promise<ArduinoDashboardv2>;
19

20
  /**
21
   * List all dashboards accessible to the authenticated user
22
   * @param opts - Optional parameters including organization ID and pagination
23
   * @returns Promise<ArduinoDashboardv2[]> - Array of dashboard objects
24
   */
25
  dashboardsV2List(opts?: any): Promise<ArduinoDashboardv2[]>;
26

27
  /**
28
   * Get detailed information about a specific dashboard
29
   * @param id - Dashboard ID
30
   * @param opts - Optional parameters including organization ID
31
   * @returns Promise<ArduinoDashboardv2> - Dashboard object with full details
32
   */
33
  dashboardsV2Show(id: string, opts?: any): Promise<ArduinoDashboardv2>;
34

35
  /**
36
   * Update dashboard configuration and layout
37
   * @param id - Dashboard ID
38
   * @param dashboardv2 - Updated dashboard configuration
39
   * @param opts - Optional parameters including organization ID
40
   * @returns Promise<ArduinoDashboardv2> - Updated dashboard object
41
   */
42
  dashboardsV2Update(id: string, dashboardv2: Dashboardv2, opts?: any): Promise<ArduinoDashboardv2>;
43

44
  /**
45
   * Partial update of dashboard properties
46
   * @param id - Dashboard ID
47
   * @param dashboardv2 - Partial dashboard configuration updates
48
   * @param opts - Optional parameters including organization ID
49
   * @returns Promise<ArduinoDashboardv2> - Updated dashboard object
50
   */
51
  dashboardsV2Patch(id: string, dashboardv2: Dashboardv2, opts?: any): Promise<ArduinoDashboardv2>;
52

53
  /**
54
   * Delete a dashboard permanently
55
   * @param id - Dashboard ID
56
   * @param opts - Optional parameters including organization ID
57
   * @returns Promise<void>
58
   */
59
  dashboardsV2Delete(id: string, opts?: any): Promise<void>;
60

61
  /**
62
   * Clone an existing dashboard
63
   * @param id - Dashboard ID to clone
64
   * @param clone - Clone configuration including new name and options
65
   * @param opts - Optional parameters including organization ID
66
   * @returns Promise<ArduinoDashboardv2> - Cloned dashboard object
67
   */
68
  dashboardsV2Clone(id: string, clone: Clone, opts?: any): Promise<ArduinoDashboardv2>;
69

70
  /**
71
   * Get dashboard as a template for replication
72
   * @param id - Dashboard ID
73
   * @param opts - Optional parameters including organization ID
74
   * @returns Promise<ArduinoDashboardv2template> - Dashboard template
75
   */
76
  dashboardsV2Template(id: string, opts?: any): Promise<ArduinoDashboardv2template>;
77
}
78
```
79

80
### Widget Management
81

82
Link widgets to thing properties and variables for real-time data display and control.
83

84
```javascript { .api }
85
class DashboardsV2Api {
86
  /**
87
   * Link a widget to thing properties or variables
88
   * @param id - Dashboard ID
89
   * @param widgetId - Widget ID within the dashboard
90
   * @param widgetlink - Widget link configuration specifying data sources
91
   * @param opts - Optional parameters including organization ID
92
   * @returns Promise<ArduinoWidgetv2> - Updated widget configuration
93
   */
94
  dashboardsV2Link(id: string, widgetId: string, widgetlink: Widgetlink, opts?: any): Promise<ArduinoWidgetv2>;
95
}
96
```
97

98
### Dashboard Sharing
99

100
Share dashboards with other users and manage access permissions.
101

102
```javascript { .api }
103
class DashboardsV2Api {
104
  /**
105
   * Share a dashboard with another user
106
   * @param id - Dashboard ID
107
   * @param dashboardshare - Sharing configuration including user ID and permissions
108
   * @param opts - Optional parameters including organization ID
109
   * @returns Promise<void>
110
   */
111
  dashboardsV2Share(id: string, dashboardshare: Dashboardshare, opts?: any): Promise<void>;
112

113
  /**
114
   * List all shares for a dashboard
115
   * @param id - Dashboard ID
116
   * @param opts - Optional parameters including organization ID
117
   * @returns Promise<ArduinoDashboardshare[]> - Array of share configurations
118
   */
119
  dashboardsV2ListShares(id: string, opts?: any): Promise<ArduinoDashboardshare[]>;
120

121
  /**
122
   * Remove dashboard sharing for a specific user
123
   * @param id - Dashboard ID
124
   * @param userId - User ID to remove sharing for
125
   * @param opts - Optional parameters including organization ID
126
   * @returns Promise<void>
127
   */
128
  dashboardsV2DeleteShare(id: string, userId: string, opts?: any): Promise<void>;
129

130
  /**
131
   * Request access to a shared dashboard
132
   * @param id - Dashboard ID
133
   * @param sharerequest - Access request with message and permissions requested
134
   * @param opts - Optional parameters including organization ID
135
   * @returns Promise<void>
136
   */
137
  dashboardsV2RequestAccess(id: string, sharerequest: Sharerequest, opts?: any): Promise<void>;
138
}
139
```
140

141
## Data Models
142

143
```javascript { .api }
144
interface ArduinoDashboardv2 {
145
  createdAt?: Date;
146
  href?: string;
147
  id?: string;
148
  name?: string;
149
  organizationId?: string;
150
  owner?: ArduinoDashboardowner;
151
  sharedWith?: ArduinoDashboardshare[];
152
  updatedAt?: Date;
153
  userId?: string;
154
  widgets?: ArduinoWidgetv2[];
155
}
156

157
interface Dashboardv2 {
158
  name: string;
159
  widgets?: ArduinoWidgetv2[];
160
}
161

162
interface ArduinoWidgetv2 {
163
  height?: number;
164
  id?: string;
165
  name?: string;
166
  options?: any;
167
  type?: string;
168
  variables?: ArduinoLinkedvariable[];
169
  width?: number;
170
  x?: number;
171
  xMobile?: number;
172
  y?: number;
173
  yMobile?: number;
174
}
175

176
interface Widgetlink {
177
  variables?: ArduinoLinkedvariable[];
178
}
179

180
interface ArduinoLinkedvariable {
181
  id?: string;
182
  lastValue?: any;
183
  lastValueUpdatedAt?: Date;
184
  name?: string;
185
  permission?: string;
186
  thingId?: string;
187
  type?: string;
188
  variableName?: string;
189
}
190

191
interface Dashboardshare {
192
  message?: string;
193
  userId: string;
194
}
195

196
interface ArduinoDashboardshare {
197
  createdAt?: Date;
198
  id?: string;
199
  message?: string;
200
  sharedBy?: string;
201
  userId?: string;
202
}
203

204
interface Sharerequest {
205
  message?: string;
206
}
207

208
interface Clone {
209
  includeWidgets?: boolean;
210
  name: string;
211
}
212

213
interface ArduinoDashboardowner {
214
  email?: string;
215
  id?: string;
216
  username?: string;
217
}
218

219
interface ArduinoDashboardv2template {
220
  name?: string;
221
  organizationId?: string;
222
  widgets?: ArduinoWidgetv2template[];
223
}
224

225
interface ArduinoWidgetv2template {
226
  height?: number;
227
  name?: string;
228
  options?: any;
229
  type?: string;
230
  variables?: ArduinoLinkedvariableTemplate[];
231
  width?: number;
232
  x?: number;
233
  y?: number;
234
}
235

236
interface ArduinoLinkedvariableTemplate {
237
  name?: string;
238
  permission?: string;
239
  type?: string;
240
  variableName?: string;
241
}
242
```
243

244
**Comprehensive Dashboard Management Example:**
245

246
```javascript
247
import ArduinoIotClient from '@arduino/arduino-iot-client';
248

249
const dashboardsApi = new ArduinoIotClient.DashboardsV2Api();
250

251
async function createCompleteDashboard(thingId, properties) {
252
  try {
253
    // Create a dashboard with multiple widget types
254
    const dashboard = await dashboardsApi.dashboardsV2Create({
255
      name: "Environmental Monitoring Dashboard",
256
      widgets: [
257
        // Temperature gauge widget
258
        {
259
          id: "temp-gauge",
260
          name: "Temperature",
261
          type: "gauge",
262
          x: 0,
263
          y: 0,
264
          width: 4,
265
          height: 4,
266
          xMobile: 0,
267
          yMobile: 0,
268
          options: {
269
            minValue: -10,
270
            maxValue: 40,
271
            unit: "°C",
272
            showValue: true
273
          }
274
        },
275
        // Humidity percentage widget
276
        {
277
          id: "humidity-percent",
278
          name: "Humidity Level",
279
          type: "percentage",
280
          x: 4,
281
          y: 0,
282
          width: 4,
283
          height: 4,
284
          xMobile: 0,
285
          yMobile: 4,
286
          options: {
287
            unit: "%",
288
            showValue: true
289
          }
290
        },
291
        // LED control switch
292
        {
293
          id: "led-switch",
294
          name: "Status LED",
295
          type: "switch",
296
          x: 8,
297
          y: 0,
298
          width: 4,
299
          height: 2,
300
          xMobile: 0,
301
          yMobile: 8,
302
          options: {
303
            onLabel: "ON",
304
            offLabel: "OFF"
305
          }
306
        },
307
        // Fan speed slider
308
        {
309
          id: "fan-slider",
310
          name: "Fan Speed",
311
          type: "slider",
312
          x: 8,
313
          y: 2,
314
          width: 4,
315
          height: 2,
316
          xMobile: 0,
317
          yMobile: 10,
318
          options: {
319
            minValue: 0,
320
            maxValue: 100,
321
            unit: "%",
322
            step: 5
323
          }
324
        },
325
        // Time series chart
326
        {
327
          id: "temp-chart",
328
          name: "Temperature History",
329
          type: "chart",
330
          x: 0,
331
          y: 4,
332
          width: 12,
333
          height: 4,
334
          xMobile: 0,
335
          yMobile: 12,
336
          options: {
337
            chartType: "line",
338
            timeWindow: "24h",
339
            yAxisLabel: "Temperature (°C)",
340
            showLegend: true
341
          }
342
        }
343
      ]
344
    });
345

346
    console.log('Created dashboard:', dashboard.id);
347

348
    // Link widgets to thing properties
349
    const [tempProp, humidityProp, , ledProp, fanProp] = properties;
350

351
    // Link temperature gauge
352
    await dashboardsApi.dashboardsV2Link(dashboard.id, "temp-gauge", {
353
      variables: [{
354
        id: tempProp.id,
355
        thingId: thingId,
356
        name: tempProp.name,
357
        type: tempProp.type,
358
        variableName: tempProp.variableName,
359
        permission: tempProp.permission
360
      }]
361
    });
362

363
    // Link humidity widget
364
    await dashboardsApi.dashboardsV2Link(dashboard.id, "humidity-percent", {
365
      variables: [{
366
        id: humidityProp.id,
367
        thingId: thingId,
368
        name: humidityProp.name,
369
        type: humidityProp.type,
370
        variableName: humidityProp.variableName,
371
        permission: humidityProp.permission
372
      }]
373
    });
374

375
    // Link LED control
376
    await dashboardsApi.dashboardsV2Link(dashboard.id, "led-switch", {
377
      variables: [{
378
        id: ledProp.id,
379
        thingId: thingId,
380
        name: ledProp.name,
381
        type: ledProp.type,
382
        variableName: ledProp.variableName,
383
        permission: ledProp.permission
384
      }]
385
    });
386

387
    // Link fan speed control
388
    await dashboardsApi.dashboardsV2Link(dashboard.id, "fan-slider", {
389
      variables: [{
390
        id: fanProp.id,
391
        thingId: thingId,
392
        name: fanProp.name,
393
        type: fanProp.type,
394
        variableName: fanProp.variableName,
395
        permission: fanProp.permission
396
      }]
397
    });
398

399
    // Link temperature chart (same as gauge but different visualization)
400
    await dashboardsApi.dashboardsV2Link(dashboard.id, "temp-chart", {
401
      variables: [{
402
        id: tempProp.id,
403
        thingId: thingId,
404
        name: tempProp.name,
405
        type: tempProp.type,
406
        variableName: tempProp.variableName,
407
        permission: tempProp.permission
408
      }]
409
    });
410

411
    console.log('All widgets linked to properties');
412
    return dashboard;
413

414
  } catch (error) {
415
    console.error('Failed to create dashboard:', error);
416
    throw error;
417
  }
418
}
419

420
// Dashboard sharing and collaboration
421
async function shareDashboard(dashboardId, collaborators) {
422
  try {
423
    // Share with multiple users
424
    for (const collaborator of collaborators) {
425
      await dashboardsApi.dashboardsV2Share(dashboardId, {
426
        userId: collaborator.userId,
427
        message: `Sharing environmental dashboard with ${collaborator.name}`
428
      });
429

430
      console.log(`Shared dashboard with ${collaborator.name}`);
431
    }
432

433
    // List all shares to verify
434
    const shares = await dashboardsApi.dashboardsV2ListShares(dashboardId);
435
    console.log(`Dashboard is shared with ${shares.length} users`);
436

437
    return shares;
438

439
  } catch (error) {
440
    console.error('Failed to share dashboard:', error);
441
    throw error;
442
  }
443
}
444

445
// Dashboard management and maintenance
446
async function manageDashboards() {
447
  try {
448
    // List all dashboards
449
    const allDashboards = await dashboardsApi.dashboardsV2List();
450
    console.log(`Total dashboards: ${allDashboards.length}`);
451

452
    for (const dashboard of allDashboards) {
453
      console.log(`Dashboard: ${dashboard.name} (${dashboard.widgets?.length || 0} widgets)`);
454

455
      // Get detailed dashboard info
456
      const details = await dashboardsApi.dashboardsV2Show(dashboard.id);
457

458
      // Check if dashboard has shares
459
      const shares = await dashboardsApi.dashboardsV2ListShares(dashboard.id);
460
      if (shares.length > 0) {
461
        console.log(`  - Shared with ${shares.length} users`);
462
      }
463

464
      // Example: Clone important dashboards for backup
465
      if (dashboard.name.includes('Production')) {
466
        const backup = await dashboardsApi.dashboardsV2Clone(dashboard.id, {
467
          name: `${dashboard.name} - Backup`,
468
          includeWidgets: true
469
        });
470
        console.log(`  - Created backup: ${backup.id}`);
471
      }
472
    }
473

474
  } catch (error) {
475
    console.error('Dashboard management error:', error);
476
  }
477
}
478

479
// Advanced dashboard patterns
480
async function createDashboardTemplate(templateName, widgetConfigs) {
481
  try {
482
    // Create a template dashboard without data links
483
    const template = await dashboardsApi.dashboardsV2Create({
484
      name: templateName,
485
      widgets: widgetConfigs.map((config, index) => ({
486
        id: `widget-${index}`,
487
        name: config.name,
488
        type: config.type,
489
        x: config.x || 0,
490
        y: config.y || 0,
491
        width: config.width || 4,
492
        height: config.height || 4,
493
        options: config.options || {}
494
      }))
495
    });
496

497
    // Get template for future replication
498
    const templateObj = await dashboardsApi.dashboardsV2Template(template.id);
499

500
    console.log(`Created dashboard template: ${templateName}`);
501
    return { dashboard: template, template: templateObj };
502

503
  } catch (error) {
504
    console.error('Failed to create dashboard template:', error);
505
    throw error;
506
  }
507
}
508

509
// Usage example with error handling
510
async function dashboardManagementDemo(thingId, properties) {
511
  try {
512
    // Create complete dashboard
513
    const dashboard = await createCompleteDashboard(thingId, properties);
514

515
    // Share with collaborators
516
    await shareDashboard(dashboard.id, [
517
      { userId: 'user-1', name: 'John Doe' },
518
      { userId: 'user-2', name: 'Jane Smith' }
519
    ]);
520

521
    // Update dashboard layout
522
    await dashboardsApi.dashboardsV2Patch(dashboard.id, {
523
      name: "Environmental Monitoring Dashboard - Updated"
524
    });
525

526
    // Create template for future use
527
    await createDashboardTemplate('Environmental Template', [
528
      {
529
        name: 'Temperature',
530
        type: 'gauge',
531
        x: 0, y: 0, width: 4, height: 4,
532
        options: { minValue: -10, maxValue: 40, unit: '°C' }
533
      },
534
      {
535
        name: 'Humidity',
536
        type: 'percentage',
537
        x: 4, y: 0, width: 4, height: 4,
538
        options: { unit: '%' }
539
      }
540
    ]);
541

542
    // Perform dashboard maintenance
543
    await manageDashboards();
544

545
    console.log('Dashboard management demo completed successfully');
546

547
  } catch (error) {
548
    if (error.status === 400) {
549
      console.error('Bad request - check dashboard configuration');
550
    } else if (error.status === 403) {
551
      console.error('Forbidden - check dashboard permissions');
552
    } else if (error.status === 404) {
553
      console.error('Dashboard not found');
554
    } else {
555
      console.error('Dashboard management error:', error.detail || error.message);
556
    }
557
  }
558
}
559
```