Panelinformationen

Zugriff auf Dashboard-Panel-Konfigurationen

Anzeigen und Erstellen von Visualisierungs-Panels in Dashboards einschließlich deren Layout, Positionierung und Konfigurationseinstellungen.

Dashboard-Panels abrufen

GET /api/{tenantId}/{projectId}/dashboard/{dashboardId}/panels

Ruft alle in einem Dashboard konfigurierten Visualisierungs-Panels ab, einschließlich Paneltypen, Positionen, Abmessungen und Konfigurationseinstellungen.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
tenantId	GUID	Ja	Die Mandanten-ID
projectId	GUID	Ja	Die Projekt-ID
dashboardId	GUID	Ja	Die Dashboard-ID

Antwort (200 OK)

{
  "dashboardId": "880e8400-e29b-41d4-a716-446655440000",
  "panels": [
    {
      "panelId": "990e8400-e29b-41d4-a716-446655440000",
      "name": "Process Flow Chart",
      "panelType": "DashboardPanelProcessMap",
      "position": "Row: 1, Col: 1",
      "width": 6,
      "height": 4,
      "configuration": "{\"dataSource\": \"MainProcess\", \"visualization\": \"flow\"}"
    },
    {
      "panelId": "aa0e8400-e29b-41d4-a716-446655440000",
      "name": "KPI Summary",
      "panelType": "DashboardPanelSingleValue",
      "position": "Row: 1, Col: 7",
      "width": 3,
      "height": 2,
      "configuration": "{\"metric\": \"avgCycleTime\", \"format\": \"duration\"}"
    }
  ]
}

Antwortfelder

Feld	Typ	Beschreibung
dashboardId	GUID	Das Dashboard, das diese Panels enthält
panels	Array	Liste der Panel-Objekte

Felder des Panel-Objekts

Feld	Typ	Beschreibung
panelId	GUID	Eindeutige Kennung des Panels
name	String	Anzeigetitel des Panels
panelType	String	Visualisierungstyp (siehe Abschnitt Panel-Typen)
position	String	Rasterposition als "Row: X, Col: Y"
width	Integer	Breite des Panels in Rastereinheiten
height	Integer	Höhe des Panels in Rastereinheiten
configuration	String	JSON-String mit panel-spezifischen Einstellungen

Fehlermeldungen

Nicht gefunden (404):

{
  "Error": "Dashboard not found",
  "DashboardId": "880e8400-e29b-41d4-a716-446655440000"
}

Dashboard-Panel erstellen

POST /api/{tenantId}/{projectId}/dashboard/{dashboardId}/panel

Erstellt ein neues Visualisierungs-Panel in einem Dashboard. Die API erstellt automatisch den passenden Selector-Block basierend auf dem Paneltyp und den angegebenen Einstellungen.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
tenantId	GUID	Ja	Die Mandanten-ID
projectId	GUID	Ja	Die Projekt-ID
dashboardId	GUID	Ja	Die Dashboard-ID

Anfragetext

{
  "title": "string (erforderlich)",
  "description": "string (optional)",
  "panelType": "string (erforderlich)",
  "blockId": "GUID (erforderlich für Datenpanels)",
  "row": "integer (erforderlich, 0-basiert)",
  "column": "integer (erforderlich, 0-basiert)",
  "width": "integer (erforderlich, 1-12)",
  "height": "integer (erforderlich, 1-20)",
  "settings": "string (optional, JSON für Selector-Konfiguration)"
}

Felder im Anfragetext

Feld	Typ	Erforderlich	Beschreibung
title	String	Ja	Anzeigetitel des Panels
description	String	Nein	Optionale Beschreibung
panelType	String	Ja	Klassenname des Panel-Typs (siehe Abschnitt Panel-Typen)
blockId	GUID	Ja*	ID des Calculator-Blocks, der angezeigt wird (*bei DashboardPanelDashboardNote nicht erforderlich)
row	Integer	Ja	Zeilenposition (0-basiert)
column	Integer	Ja	Spaltenposition (0-basiert)
width	Integer	Ja	Breite des Panels in Rastereinheiten (1-12)
height	Integer	Ja	Höhe des Panels in Rastereinheiten (1-20)
settings	String	Nein	JSON-String mit Selector-Konfiguration

Antwort (201 Created)

{
  "panelId": "5b54172c-b15c-4dd9-bab6-6cfceb7389df",
  "title": "My KPI Panel",
  "dashboardPanelClassName": "DashboardPanelSingleValue",
  "row": 0,
  "column": 0,
  "width": 2,
  "height": 1,
  "blockId": "db0dd1b9-63b5-4754-92b1-2764f4a3fb68"
}

Hinweis: Die blockId in der Antwort ist die SELECTOR-Block-ID, nicht die ursprüngliche Calculator-Block-ID. Die API erstellt automatisch einen Selector-Block, der den Calculator kapselt.

Fehlermeldungen

Bad Request (400) - Fehlender Block:

{
  "Error": "VALIDATION_ERROR",
  "Message": "BlockId is required for panel type 'DashboardPanelSingleValue'"
}

Bad Request (400) - Ungültiger Panel-Typ:

{
  "Error": "VALIDATION_ERROR",
  "Message": "Invalid panel type 'InvalidType'. Valid types: DashboardPanelSingleValue, DashboardPanelCalculator, ..."
}

Bad Request (400) - Block nicht gefunden:

{
  "Error": "VALIDATION_ERROR",
  "Message": "Block 'guid' does not exist"
}

Panel-Typen

mindzieStudio-Dashboards unterstützen folgende Panel-Typen:

Panel-Typ-Klasse	Erstellter Selector	Beschreibung
DashboardPanelCalculator	SelectorFullCalculator	Vollständige Calculator-Ausgabe (Prozesskarten, Trends, Diagramme)
DashboardPanelSingleValue	SelectorSingleValueFromLabel	Einzelwert / KPI-Karte
DashboardPanelHorizontalBarChart	SelectorMultiColumns	Horizontaler Balkendiagramm, Ranglisten
DashboardPanelDataTable	SelectorFullCalculator	Datentabellenanzeige
DashboardPanelProcessMap	SelectorFullCalculator	Prozesskarten-Visualisierung
DashboardPanelDashboardNote	(keiner)	Text-/Notiz-Panel (kein blockId erforderlich)
DashboardPanelRecommendationSentence	(keiner)	KI-Empfehlungsanzeige

Panel-Einstellungen pro Typ

DashboardPanelSingleValue (KPI-Karten)

Wenn panelType DashboardPanelSingleValue ist, konfigurieren die Einstellungen, wie ein einzelner Wert aus der Ausgabe eines Calculators extrahiert wird:

{
  "tableIndex": 0,
  "labelColumnName": "Name",
  "labelName": "Total Case Count",
  "valueColumnName": "Value",
  "formatText": "N0"
}

Einstellung	Typ	Beschreibung
tableIndex	Integer	Welche Ausgabetabelle verwendet wird (gewöhnlich 0)
labelColumnName	String	Spalte mit Labels (gewöhnlich "Name")
labelName	String	Das zu findende Label (z.B. "Total Case Count")
valueColumnName	String	Spalte mit Wert (gewöhnlich "Value")
formatText	String	.NET-Formatstring (z.B. N0, F2, P0)

Am besten geeignet für: CalculatorDataInformation, CalculatorOverview

DashboardPanelHorizontalBarChart (Balkendiagramme)

Wenn panelType DashboardPanelHorizontalBarChart ist, muss columnNames in den Einstellungen enthalten sein, um SelectorMultiColumns auszulösen:

{
  "tableIndex": 0,
  "columnNames": ["ActivityName", "Count"],
  "sortColumnName": "Count",
  "sortAscending": false,
  "maxRows": 10
}

Einstellung	Typ	Beschreibung
tableIndex	Integer	Welche Ausgabetabelle verwendet wird
columnNames	Array	Spalten, die im Diagramm enthalten sein sollen (MÜSSEN mit Calculator-Ausgabe übereinstimmen)
sortColumnName	String	Nach welcher Spalte sortiert wird
sortAscending	Boolean	Sortierrichtung
maxRows	Integer	Maximale anzuzeigende Zeilen

WICHTIG: Spaltennamen müssen exakt mit den Ausgabespalten des Calculators übereinstimmen. Zum Beispiel verwendet CalculatorActivityFrequency den Spaltennamen der Aktivität aus dem Dataset (z.B. "ActivityName"), nicht einen generischen "Activity".

Am besten geeignet für: CalculatorActivityFrequency, CalculatorResourceFrequency

DashboardPanelCalculator (Vollständige Visualisierungen)

Für die vollständige Calculator-Ausgabe (Prozesskarten, Trends) sind keine speziellen Einstellungen erforderlich:

{}

Oder die Einstellungen können ganz weggelassen werden.

Panel-Architektur

Dashboard-Panels sind nicht direkt mit Calculator-Blöcken verbunden. Stattdessen verwenden sie eine dreistufige Architektur:

Panel.InputBlockId -> Selector Block -> Calculator Block (via parent_id)

Warum Selector? Selector-Blöcke definieren, WIE die Calculator-Ausgabe dargestellt wird:

• SelectorFullCalculator: Vollständige Ausgabe mit Visualisierungseinstellungen anzeigen
• SelectorSingleValueFromLabel: Einzelnen Wert per Label-Lookup extrahieren
• SelectorMultiColumns: Bestimmte Spalten mit Sortierung/Begrenzung extrahieren

Die API erstellt automatisch den passenden Selector-Block, wenn ein Panel auf einen Calculator verweist.

Panel-Layout-System

Dashboard-Panels verwenden ein rasterbasiertes Layout-System:

• Rastereinheiten: 12-Spalten-Raster
• Position: Zeilen- und Spaltenkoordinaten (0-basiert)
• Größe: Breite (1-12 Spalten), Höhe (1-20 Zeilen)
• Responsiv: Automatische Skalierung auf verschiedenen Bildschirmgrößen

Implementierungsbeispiele

Dashboard-Panels abrufen

cURL

curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/dashboard/880e8400-e29b-41d4-a716-446655440000/panels" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

KPI-Panel erstellen (Einzelwert)

curl -X POST "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/dashboard/{dashboardId}/panel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Total Cases",
    "panelType": "DashboardPanelSingleValue",
    "blockId": "calculator-data-information-guid",
    "row": 0,
    "column": 0,
    "width": 2,
    "height": 1,
    "settings": "{\"tableIndex\":0,\"labelColumnName\":\"Name\",\"labelName\":\"Total Case Count\",\"valueColumnName\":\"Value\",\"formatText\":\"N0\"}"
  }'

Horizontales Balkendiagramm erstellen

curl -X POST "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/dashboard/{dashboardId}/panel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Activity Distribution",
    "panelType": "DashboardPanelHorizontalBarChart",
    "blockId": "calculator-activity-frequency-guid",
    "row": 1,
    "column": 0,
    "width": 6,
    "height": 3,
    "settings": "{\"tableIndex\":0,\"columnNames\":[\"ActivityName\",\"Count\"],\"sortColumnName\":\"Count\",\"sortAscending\":false,\"maxRows\":10}"
  }'

Volles Calculator-Panel erstellen

curl -X POST "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/dashboard/{dashboardId}/panel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Case Count",
    "panelType": "DashboardPanelCalculator",
    "blockId": "calculator-case-count-guid",
    "row": 0,
    "column": 2,
    "width": 2,
    "height": 1
  }'

JavaScript/Node.js

const TENANT_ID = '12345678-1234-1234-1234-123456789012';
const PROJECT_ID = '87654321-4321-4321-4321-210987654321';
const BASE_URL = 'https://your-mindzie-instance.com';

async function getDashboardPanels(dashboardId, token) {
  const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/dashboard/${dashboardId}/panels`;

  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });

  if (response.ok) {
    return await response.json();
  } else if (response.status === 404) {
    throw new Error('Dashboard not found');
  } else {
    throw new Error(`Failed to get panels: ${response.status}`);
  }
}

async function createDashboardPanel(dashboardId, panelData, token) {
  const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/dashboard/${dashboardId}/panel`;

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(panelData)
  });

  if (response.ok) {
    return await response.json();
  } else {
    const error = await response.json();
    throw new Error(error.Message || `Failed to create panel: ${response.status}`);
  }
}

// Verwendung - Panels abrufen
const panels = await getDashboardPanels('dashboard-guid', 'your-auth-token');
console.log(`Dashboard: ${panels.dashboardId}`);
console.log(`Panels: ${panels.panels.length}`);

// Verwendung - KPI-Panel erstellen
const newPanel = await createDashboardPanel('dashboard-guid', {
  title: 'Total Cases',
  panelType: 'DashboardPanelSingleValue',
  blockId: 'calculator-data-information-guid',
  row: 0,
  column: 0,
  width: 2,
  height: 1,
  settings: JSON.stringify({
    tableIndex: 0,
    labelColumnName: 'Name',
    labelName: 'Total Case Count',
    valueColumnName: 'Value',
    formatText: 'N0'
  })
}, 'your-auth-token');

console.log(`Panel erstellt: ${newPanel.panelId}`);

Python

import requests
import json

TENANT_ID = '12345678-1234-1234-1234-123456789012'
PROJECT_ID = '87654321-4321-4321-4321-210987654321'
BASE_URL = 'https://your-mindzie-instance.com'

def get_dashboard_panels(dashboard_id, token):
    """Alle Panels in einem Dashboard abrufen."""
    url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/dashboard/{dashboard_id}/panels'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }

    response = requests.get(url, headers=headers)

    if response.ok:
        return response.json()
    elif response.status_code == 404:
        raise Exception('Dashboard nicht gefunden')
    else:
        raise Exception(f'Panels konnten nicht abgerufen werden: {response.status_code}')


def create_dashboard_panel(dashboard_id, panel_data, token):
    """Neues Panel in einem Dashboard erstellen."""
    url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/dashboard/{dashboard_id}/panel'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }

    response = requests.post(url, headers=headers, json=panel_data)

    if response.ok:
        return response.json()
    else:
        error = response.json()
        raise Exception(error.get('Message', f'Panel konnte nicht erstellt werden: {response.status_code}'))


# Verwendung - Panels abrufen
panels = get_dashboard_panels('dashboard-guid', 'your-auth-token')
print(f"Dashboard: {panels['dashboardId']}")
print(f"Anzahl Panels: {len(panels['panels'])}")

# Verwendung - KPI-Panel erstellen
settings = {
    'tableIndex': 0,
    'labelColumnName': 'Name',
    'labelName': 'Total Case Count',
    'valueColumnName': 'Value',
    'formatText': 'N0'
}

new_panel = create_dashboard_panel('dashboard-guid', {
    'title': 'Total Cases',
    'panelType': 'DashboardPanelSingleValue',
    'blockId': 'calculator-data-information-guid',
    'row': 0,
    'column': 0,
    'width': 2,
    'height': 1,
    'settings': json.dumps(settings)
}, 'your-auth-token')

print(f"Panel erstellt: {new_panel['panelId']}")

C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class DashboardPanelsResponse
{
    public Guid DashboardId { get; set; }
    public List<PanelInfo> Panels { get; set; }
}

public class PanelInfo
{
    public Guid PanelId { get; set; }
    public string Name { get; set; }
    public string PanelType { get; set; }
    public string Position { get; set; }
    public int Width { get; set; }
    public int Height { get; set; }
    public string Configuration { get; set; }
}

public class CreatePanelRequest
{
    public string Title { get; set; }
    public string Description { get; set; }
    public string PanelType { get; set; }
    public Guid BlockId { get; set; }
    public int Row { get; set; }
    public int Column { get; set; }
    public int Width { get; set; }
    public int Height { get; set; }
    public string Settings { get; set; }
}

public class CreatePanelResponse
{
    public Guid PanelId { get; set; }
    public string Title { get; set; }
    public string DashboardPanelClassName { get; set; }
    public int Row { get; set; }
    public int Column { get; set; }
    public int Width { get; set; }
    public int Height { get; set; }
    public Guid BlockId { get; set; }
}

public class DashboardPanelClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly Guid _tenantId;
    private readonly Guid _projectId;
    private readonly JsonSerializerOptions _jsonOptions;

    public DashboardPanelClient(string baseUrl, Guid tenantId, Guid projectId, string accessToken)
    {
        _baseUrl = baseUrl;
        _tenantId = tenantId;
        _projectId = projectId;
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Authorization =
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
        _jsonOptions = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };
    }

    public async Task<DashboardPanelsResponse> GetDashboardPanelsAsync(Guid dashboardId)
    {
        var url = $"{_baseUrl}/api/{_tenantId}/{_projectId}/dashboard/{dashboardId}/panels";
        var response = await _httpClient.GetAsync(url);

        if (response.IsSuccessStatusCode)
        {
            var json = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<DashboardPanelsResponse>(json, _jsonOptions);
        }
        else if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
        {
            throw new Exception($"Dashboard {dashboardId} nicht gefunden");
        }

        throw new Exception($"Panels konnten nicht abgerufen werden: {response.StatusCode}");
    }

    public async Task<CreatePanelResponse> CreatePanelAsync(Guid dashboardId, CreatePanelRequest request)
    {
        var url = $"{_baseUrl}/api/{_tenantId}/{_projectId}/dashboard/{dashboardId}/panel";
        var json = JsonSerializer.Serialize(request, _jsonOptions);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await _httpClient.PostAsync(url, content);

        if (response.IsSuccessStatusCode)
        {
            var responseJson = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<CreatePanelResponse>(responseJson, _jsonOptions);
        }

        var errorJson = await response.Content.ReadAsStringAsync();
        throw new Exception($"Panel konnte nicht erstellt werden: {errorJson}");
    }
}

// Verwendung
var client = new DashboardPanelClient(
    "https://your-mindzie-instance.com",
    Guid.Parse("12345678-1234-1234-1234-123456789012"),
    Guid.Parse("87654321-4321-4321-4321-210987654321"),
    "your-access-token");

// Panels abrufen
var panels = await client.GetDashboardPanelsAsync(Guid.Parse("dashboard-guid"));
Console.WriteLine($"Dashboard: {panels.DashboardId}");
foreach (var panel in panels.Panels)
{
    Console.WriteLine($"- {panel.Name} ({panel.PanelType})");
}

// KPI-Panel erstellen
var newPanel = await client.CreatePanelAsync(Guid.Parse("dashboard-guid"), new CreatePanelRequest
{
    Title = "Total Cases",
    PanelType = "DashboardPanelSingleValue",
    BlockId = Guid.Parse("calculator-data-information-guid"),
    Row = 0,
    Column = 0,
    Width = 2,
    Height = 1,
    Settings = JsonSerializer.Serialize(new
    {
        tableIndex = 0,
        labelColumnName = "Name",
        labelName = "Total Case Count",
        valueColumnName = "Value",
        formatText = "N0"
    })
});

Console.WriteLine($"Panel erstellt: {newPanel.PanelId}");

Wichtige Hinweise

API-Funktionalitäten

• Lesezugriff: Verwenden Sie den GET-Endpunkt, um Panel-Konfigurationen abzurufen
• Erstellen: Verwenden Sie den POST-Endpunkt, um neue Panels mit automatischer Selector-Block-Erstellung anzulegen
• Ändern: Die Bearbeitung von Panels erfolgt aktuell über die mindzieStudio-Benutzeroberfläche
• Löschen: Das Löschen von Panels erfolgt aktuell über die mindzieStudio-Benutzeroberfläche

Konfigurationsparsing

Das Feld configuration enthält einen JSON-String, der zum Zugriff auf die Einstellungen geparst werden muss.

Layout-System

Panel-Positionen verwenden ein Zeilen/Spalten-Rastersystem mit flexibler Größe. Zeilen- und Spaltenwerte sind beim Erstellen von Panels 0-basiert.