Benutzerdefinierte Widgets

Custom Widgets sind ab SKOOR 10.0.0 verfügbar.

Custom Widgets erweitern das SKOOR-Visualisierungsökosystem, indem sie es Entwicklern ermöglichen, maßgeschneiderte, interaktive UI-Komponenten zu erstellen, die sicher innerhalb von SKOOR Dashboards ausgeführt werden. Sie verbinden die Flexibilität moderner Web-Frameworks (wie React oder Vue oder reines Vanilla JS) und moderner Build-Tools (wie Vite oder Webpack) mit den kontrollierten Datenpipelines und strengen Sicherheitsstandards von SKOOR.

Schnellstartanleitung

Für die Verwendung von Custom Widgets benötigen Sie Zugangsdaten für die SKOOR Registry. Wenden Sie sich an support@skoor.com, um diese anzufordern.

Verwenden Sie das Paket @skoor/create-custom-widget, um ein neues SKOOR-Custom-Widget-Projekt mit der empfohlenen Struktur und den erforderlichen Abhängigkeiten zu erstellen.

  1. Paketseite öffnen: https://www.npmjs.com/package/@skoor/create-custom-widget

  2. Widget-Projekt initialisieren: Folgen Sie den Anweisungen des Pakets, um einen neuen Custom-Widget-Workspace zu erstellen.

  3. Erstellen, testen und veröffentlichen: Implementieren Sie das Widget, validieren Sie es lokal und veröffentlichen Sie es anschließend in der SKOOR Package Registry unter dem zugewiesenen Customer Scope.

Funktionsweise von Custom Widgets

skoor-custom-widget-architecture.svg

Custom Widgets arbeiten als isolierte, eigenständige Pakete, die über die zentrale SKOOR Package Registry (registry.skoor.com) verteilt und verwaltet werden.

  • Einstiegspunkt (main): Jedes Widget-Paket definiert eine HTML-Datei als main-Einstiegspunkt in der package.json. Alle erforderlichen statischen Assets (Skripte, Styles, Bilder) werden direkt aus der Registry geladen.

  • Isolierte Ausführung: Widgets werden innerhalb von IFRAMEs ausgeführt, die durch eine dedizierte Origin und eine restriktive Content Security Policy (CSP) isoliert sind. Dies gewährleistet Mandantentrennung, Sicherheit und eine strikte Abgrenzung.

  • Erstellungsmethoden: Custom Widgets können entweder manuell von Entwicklern mit einem beliebigen modernen lokalen Entwicklungs-Workflow (z. B. Vite, Webpack oder Vanilla JS) erstellt oder mithilfe von KI generiert werden, um schnell funktionale Dashboards und Komponenten aufzusetzen.

Paketstruktur & Datenabfragen

Um vollständig portabel und versionskontrolliert zu bleiben, bündeln Custom Widgets ihre erforderlichen Datendefinitionen direkt im Paket unter dem Konfigurationsblock skoor:

  • Gebündelte Abfragen: Pakete enthalten ihre erforderlichen Datenbankabfragen unter der Eigenschaft skoor.dataQueryPackage, die auf eine exportierte Abfrage-JSON-Datei verweist. Verwenden Sie das Export-Tool des SKOOR MCP Servers, um eine dedizierte Abfragegruppe zu exportieren; der Export enthält automatisch alle erforderlichen Abhängigkeiten.

  • Die Dashboard Bridge (@skoor/dashboard-bridge): Widgets kommunizieren mit der SKOOR-Kernplattform ausschließlich über die offizielle Bibliothek @skoor/dashboard-bridge. Diese Bridge abstrahiert die asynchrone Kommunikation (über postMessage und Penpal) und ermöglicht es Widgets:

    • Daten dynamisch über dataQuerySelect(...) oder dataSourceSelect(...) abzurufen.

    • Globale Dashboard-Filter auszulesen und zu aktualisieren (getFilters(), setFilters(...)).

    • Host-Styling, Theme-Variablen, Schriftfamilien und Inhaltshöhen automatisch über setup() zu synchronisieren.

Beispiel für eine package.json-Konfiguration eines Custom Widgets (veröffentlicht unter einem Customer Scope, z. B. @customer-scope/custom-metric-widget):

{
  "name": "@customer-scope/custom-metric-widget",
  "version": "1.0.0",
  "main": "dist/index.html",
  "skoor": {
    "dataQueryPackage": "./data/data-queries.json"
  }
}

Entwicklung, MCP-Server-Integration & Veröffentlichung

Um Custom Widgets effizient zu entwickeln und zu veröffentlichen, können Sie Ihre KI-Programmierassistenten über den integrierten Model Context Protocol (MCP) Server direkt mit Ihrer SKOOR-Instanz verbinden.

Verwendung des SKOOR MCP Servers (Abrufen, Erstellen, Aktualisieren, Exportieren)

Der SKOOR MCP Server ermöglicht es externen LLM-Clients (wie Cursor oder Cline), Tabellen- und Datenabfragedefinitionen direkt aus Ihrer SKOOR-Instanz abzurufen, zu erstellen, zu bearbeiten und zu exportieren:

  • Abrufen: Abfragen von Datenbankschemas, Tabellenstrukturen und bestehenden Datenabfragedefinitionen, um verfügbare Datenmodelle zu verstehen.

  • Erstellen: Automatisches Generieren neuer Datenabfragen und Strukturieren von Widget-Definitionen auf Basis Ihrer genauen Vorgaben.

  • Aktualisieren / Bearbeiten: Iteratives Verfeinern von Abfragen, Anpassen von Aggregationen oder Ändern von Parametern direkt in Ihrer Entwicklungsumgebung mit vollständiger Schemavalidierung.

  • Exportieren: Exportieren von Datenabfragepaketen in das JSON-Format mithilfe des Export-Tools des MCP Servers. Legen Sie widgetspezifische Abfragen in einer dedizierten Gruppe ab und exportieren Sie diese Gruppe; der Export schließt automatisch die erforderlichen Abhängigkeiten ein.

Konfigurieren Sie Ihren MCP-Client (z. B. in Ihren Projekt- oder globalen Einstellungen) mithilfe der folgenden HTTP-Konfigurationsvorlage:

{
  "servers": {
    "skoor-mcp": {
      "type": "http",
      "url": "https://<your-skoor-instance>/skoor-webservice/mcp",
      "headers": {
        "Authorization": "Basic <your-base64-encoded-credentials>"
      }
    }
  },
  "inputs": []
}

Einrichtung der Registry & Veröffentlichung

  1. Registry konfigurieren: Erstellen Sie eine Datei .npmrc im Stammverzeichnis Ihres Projekts mit dem privaten SKOOR-Registry-Endpunkt:

    registry=https://registry.skoor.com
  2. Authentifizieren: Melden Sie sich mit den von SKOOR bereitgestellten Zugangsdaten bei der Registry an:

    npm login --registry=https://registry.skoor.com
  3. Customer Scopes: Pakete müssen immer in Ihrem zugewiesenen Customer Scope (z. B. @customer-scope/my-widget) veröffentlicht werden.

Sicherheit, Netzwerkbeschränkungen & CSP

Um die Datensouveränität des Unternehmens zu schützen und einen unbefugten Datenabfluss an Drittanbieter zu verhindern, wendet SKOOR strenge Sicherheitsrichtlinien auf Custom Widgets an:

  • Standardmäßige Isolation: Externe Netzwerkkommunikation aus einem Widget heraus ist standardmäßig streng untersagt und wird über eine restriktive Content Security Policy (CSP) blockiert.

  • CSP-Ausnahmen: Wenn ein Widget ausdrücklich eine Kommunikation mit externen Endpunkten erfordert (z. B. öffentliche APIs oder Drittanbieter-Repositories), können Ausnahmen im Abschnitt skoor.csp der Datei package.json deklariert werden:

{
  "skoor": {
    "csp": {
      "connect-src": [
        "https://api.external-service.com"
      ]
    }
  }
}
  • Bestätigung durch Benutzer: Wenn ein Widget über seine CSP-Konfiguration zusätzliche Netzwerk-Origins anfordert, zeigt die Plattform Administratoren oder Benutzern einen Bestätigungsdialog an, um den ausgehenden Datenzugriff ausdrücklich zu autorisieren.

Lebenszyklus: Installation und Dashboard-Bereitstellung

Die Bereitstellung und Nutzung eines Custom Widgets folgt einem klaren administrativen und betrieblichen Lebenszyklus:

  1. Veröffentlichung: Entwickler erstellen das versionierte Paket und veröffentlichen es in der privaten SKOOR Package Registry (registry.skoor.com).

  2. Installation: Administratoren navigieren zu den SKOOR Settings, öffnen den Verwaltungsbereich für Custom Widgets und installieren das gewünschte Paket aus der privaten Registry.

  3. Dashboard-Integration: Nach der Installation steht das Custom Widget im WYSIWYG Dashboard Builder zur Verfügung. Dort können Benutzer es auf Dashboards platzieren, seine Ansichtsparameter konfigurieren und es mit globalen Dashboard-Filtern verknüpfen.