Informations sur les Panneaux

Accéder à la Configuration des Panneaux du Tableau de Bord

Visualisez et créez des panneaux de visualisation dans les tableaux de bord, y compris leur mise en page, positionnement et paramètres de configuration.

Obtenir les Panneaux du Tableau de Bord

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

Récupère tous les panneaux de visualisation configurés dans un tableau de bord, y compris les types de panneaux, les positions, dimensions et paramètres de configuration.

Paramètres de Chemin

Paramètre	Type	Obligatoire	Description
tenantId	GUID	Oui	L'identifiant du locataire
projectId	GUID	Oui	L'identifiant du projet
dashboardId	GUID	Oui	L'identifiant du tableau de bord

Réponse (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\"}"
    }
  ]
}

Champs de Réponse

Champ	Type	Description
dashboardId	GUID	Le tableau de bord contenant ces panneaux
panels	tableau	Liste des objets panneau

Champs de l'Objet Panneau

Champ	Type	Description
panelId	GUID	Identifiant unique du panneau
name	string	Titre d'affichage du panneau
panelType	string	Type de visualisation (voir la section Types de Panneaux)
position	string	Position dans la grille au format "Row: X, Col: Y"
width	entier	Largeur du panneau en unités de grille
height	entier	Hauteur du panneau en unités de grille
configuration	string	Chaîne JSON contenant les paramètres spécifiques au panneau

Réponses d'Erreur

Non Trouvé (404) :

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

Créer un Panneau de Tableau de Bord

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

Crée un nouveau panneau de visualisation dans un tableau de bord. L'API crée automatiquement le bloc sélecteur approprié en fonction du type de panneau et des paramètres fournis.

Paramètres de Chemin

Paramètre	Type	Obligatoire	Description
tenantId	GUID	Oui	L'identifiant du locataire
projectId	GUID	Oui	L'identifiant du projet
dashboardId	GUID	Oui	L'identifiant du tableau de bord

Corps de la Requête

{
  "title": "string (requis)",
  "description": "string (optionnel)",
  "panelType": "string (requis)",
  "blockId": "GUID (requis pour les panneaux de données)",
  "row": "integer (requis, base 0)",
  "column": "integer (requis, base 0)",
  "width": "integer (requis, 1-12)",
  "height": "integer (requis, 1-20)",
  "settings": "string (optionnel, JSON pour la configuration du sélecteur)"
}

Champs du Corps de Requête

Champ	Type	Obligatoire	Description
title	string	Oui	Titre d'affichage du panneau
description	string	Non	Description optionnelle
panelType	string	Oui	Nom de la classe du type de panneau (voir section Types de Panneaux)
blockId	GUID	Oui*	ID du bloc calculateur à afficher (*non requis pour DashboardPanelDashboardNote)
row	integer	Oui	Position en ligne (base 0)
column	integer	Oui	Position en colonne (base 0)
width	integer	Oui	Largeur du panneau en unités de grille (1-12)
height	integer	Oui	Hauteur du panneau en unités de grille (1-20)
settings	string	Non	Chaîne JSON avec la configuration du sélecteur

Réponse (201 Créé)

{
  "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"
}

Note : Le blockId dans la réponse est l’ID du bloc SELECTOR, et non pas l’ID original du bloc calculateur. L'API crée automatiquement un bloc sélecteur qui enveloppe le calculateur.

Réponses d'Erreur

Mauvaise Requête (400) - Bloc Manquant :

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

Mauvaise Requête (400) - Type de Panneau Invalide :

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

Mauvaise Requête (400) - Bloc Non Trouvé :

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

Types de Panneaux

Les tableaux de bord mindzieStudio supportent les types de panneaux suivants :

Classe de Type de Panneau	Sélecteur Créé	Description
DashboardPanelCalculator	SelectorFullCalculator	Sortie complète du calculateur (cartes de processus, tendances, graphiques)
DashboardPanelSingleValue	SelectorSingleValueFromLabel	Valeur unique / carte KPI
DashboardPanelHorizontalBarChart	SelectorMultiColumns	Diagramme à barres horizontales, listes classées
DashboardPanelDataTable	SelectorFullCalculator	Affichage sous forme de tableau de données
DashboardPanelProcessMap	SelectorFullCalculator	Visualisation carte de processus
DashboardPanelDashboardNote	(aucun)	Panneau texte/note (pas de blockId requis)
DashboardPanelRecommendationSentence	(aucun)	Affichage de recommandations IA

Paramètres des Panneaux par Type

DashboardPanelSingleValue (Cartes KPI)

Quand panelType est DashboardPanelSingleValue, les paramètres configurent comment extraire une valeur unique à partir de la sortie d’un calculateur :

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

Paramètre	Type	Description
tableIndex	entier	Indice de la table de sortie à utiliser (habituellement 0)
labelColumnName	string	Colonne contenant les labels (généralement "Name")
labelName	string	Label à rechercher (ex. "Total Case Count")
valueColumnName	string	Colonne contenant la valeur (habituellement "Value")
formatText	string	Chaîne de format .NET (N0, F2, P0, etc.)

Usage recommandé avec : CalculatorDataInformation, CalculatorOverview

DashboardPanelHorizontalBarChart (Graphiques à Barres Horizontales)

Quand panelType est DashboardPanelHorizontalBarChart, incluez columnNames dans les paramètres pour activer SelectorMultiColumns :

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

Paramètre	Type	Description
tableIndex	entier	Indice de la table de sortie à utiliser
columnNames	tableau	Colonnes à inclure dans le graphique (DOIVENT correspondre à la sortie du calculateur)
sortColumnName	string	Colonne pour le tri
sortAscending	booléen	Sens du tri
maxRows	entier	Nombre maximum de lignes à afficher

IMPORTANT : Les noms de colonnes doivent correspondre exactement aux colonnes de sortie du calculateur. Par exemple, CalculatorActivityFrequency utilise le nom de la colonne d’activité du dataset (ex. "ActivityName") et non un générique "Activity".

Usage recommandé avec : CalculatorActivityFrequency, CalculatorResourceFrequency

DashboardPanelCalculator (Visualisations Complètes)

Pour la sortie complète du calculateur (cartes processus, tendances), aucun paramètre particulier n’est requis :

{}

Ou omettez complètement le paramètre settings.

Architecture des Panneaux

Les panneaux de tableau de bord ne se connectent pas directement aux blocs calculateur. Ils utilisent une architecture en trois couches :

Panel.InputBlockId -> Bloc Sélecteur -> Bloc Calculateur (via parent_id)

Pourquoi des Sélecteurs ? Les blocs sélecteurs définissent COMMENT afficher la sortie du calculateur :

• SelectorFullCalculator : Affiche la sortie complète avec les paramètres de visualisation
• SelectorSingleValueFromLabel : Extrait une valeur unique par recherche de label
• SelectorMultiColumns : Extrait des colonnes spécifiques avec tri/limitation

L'API crée automatiquement le bloc sélecteur approprié lors de la création d’un panneau pointant vers un calculateur.

Système de Mise en Page des Panneaux

Les panneaux du tableau de bord utilisent un système de mise en page basé sur une grille :

• Unités de Grille : Système à 12 colonnes
• Position : Coordonnées ligne et colonne (base 0)
• Taille : Largeur (1-12 colonnes), Hauteur (1-20 lignes)
• Responsive : Mise à l’échelle automatique selon la taille de l’écran

Exemples d'Implémentation

Obtenir les Panneaux du Tableau de Bord

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"

Créer un Panneau KPI (Valeur Unique)

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\"}"
  }'

Créer un Graphique à Barres Horizontales

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}"
  }'

Créer un Panneau Calculateur Complet

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}`);
  }
}

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

// Usage - Créer un panneau KPI
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(`Created panel: ${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):
    """Récupère tous les panneaux dans un tableau de bord."""
    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 not found')
    else:
        raise Exception(f'Failed to get panels: {response.status_code}')


def create_dashboard_panel(dashboard_id, panel_data, token):
    """Crée un nouveau panneau dans un tableau de bord."""
    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'Failed to create panel: {response.status_code}'))


# Usage - Obtenir les panneaux
panels = get_dashboard_panels('dashboard-guid', 'your-auth-token')
print(f"Dashboard: {panels['dashboardId']}")
print(f"Nombre de panneaux : {len(panels['panels'])}")

# Usage - Créer un panneau KPI
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"Created panel: {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} not found");
        }

        throw new Exception($"Failed to get panels: {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($"Failed to create panel: {errorJson}");
    }
}

// Usage
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");

// Obtenir les panneaux
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})");
}

// Créer un panneau KPI
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($"Created panel: {newPanel.PanelId}");

Notes Importantes

Capacités de l'API

• Accès Lecture : Utilisez le endpoint GET pour récupérer la configuration des panneaux
• Accès Création : Utilisez le endpoint POST pour créer de nouveaux panneaux avec création automatique du bloc sélecteur
• Accès Modification : La modification des panneaux se fait actuellement via l’interface mindzieStudio
• Accès Suppression : La suppression des panneaux se fait actuellement via l’interface mindzieStudio

Analyse de la Configuration

Le champ configuration contient une chaîne JSON qu’il faut analyser pour accéder aux paramètres.

Système de Mise en Page

Les positions des panneaux utilisent un système grille ligne/colonne avec des tailles flexibles. Les valeurs de ligne et colonne sont à base 0 lors de la création des panneaux.