manifest.json

Die manifest.json ist die einzige Konfigurationsdatei eines Plugins. Sie deklariert Metadaten, Queries, Parameter und Berechtigungen.

Entwickler-Handbuch · Plugin-Authoring

Pflichtfelder

jsonmanifest.json

{
  "id": "sellx.artikel-kpi",
  "name": "Artikel-KPI",
  "version": "1.0.0",
  "category": "report",
  "requiresDbRole": "read",
  "queries": [
    {
      "id": "top-articles",
      "name": "Top 10 Artikel",
      "description": "Verkaufte Menge und Umsatz der 10 meistverkauften Artikel",
      "file": "sql/top-articles.sql",
      "parameters": []
    }
  ]
}

Feld	Typ	Beschreibung
`id`	string	Eindeutige Plugin-ID, reverse-DNS-Notation (`sellx.<hersteller>.<name>`)
`name`	string	Anzeigename im Hub
`version`	string	semver, `MAJOR.MINOR.PATCH`
`category`	enum	`report` oder `automation`
`requiresDbRole`	enum	`read`, `write`, oder `owner`
`queries`	array	Liste der Query-Definitionen

Optionale Felder

jsonmanifest.json

{
  "...": "...Pflichtfelder oben...",
  "description": "Zeigt verkaufte Top-Artikel mit Umsatz-Vergleich",
  "author": {
    "name": "sellx GmbH",
    "email": "plugins@sellx.de",
    "url": "https://sellx.de/plugins/artikel-kpi"
  },
  "icon": "icon.png",
  "license": "proprietary",
  "minHubVersion": "0.5.0",
  "tags": ["umsatz", "verkauf", "kpi"]
}

Feld	Typ	Beschreibung
`description`	string	Kurzbeschreibung, max. 500 Zeichen
`author`	object	Name, Email, URL des Plugin-Herstellers
`icon`	string	Pfad zur Icon-Datei (relativ zum ZIP-Root)
`license`	string	z.B. `proprietary`, `MIT`, `GPL-3.0`
`minHubVersion`	string	Niedrigste Hub-Version, die das Plugin unterstützt
`tags`	string[]	Such-Tags für den Plugin-Store

Query-Definition

jsonmanifest.json

{
  "id": "sales-by-period",
  "name": "Umsatz nach Zeitraum",
  "description": "Summierter Umsatz gruppiert nach Monat",
  "file": "sql/sales-by-period.sql",
  "parameters": [
    {
      "name": "fromDate",
      "type": "date",
      "label": "Von",
      "required": true,
      "default": "2026-01-01"
    },
    {
      "name": "toDate",
      "type": "date",
      "label": "Bis",
      "required": true
    },
    {
      "name": "minAmount",
      "type": "number",
      "label": "Min. Umsatz (€)",
      "required": false,
      "min": 0,
      "max": 1000000
    }
  ]
}

Feld	Typ	Beschreibung
`id`	string	Query-ID, eindeutig im Plugin, Dateiname muss `sql/<id>.sql` sein
`name`	string	Anzeigename im Tab
`description`	string	Tooltip im Workspace
`file`	string	Pfad zur SQL-Datei relativ zum ZIP-Root
`parameters`	array	Liste der Parameter (UI-Eingabefelder)

Parameter-Typen

Typ	UI-Element	JSON-Wert	Validation
`string`	Text-Input	`"Hallo"`	`minLength`, `maxLength`
`number`	Number-Input	`42.5`	`min`, `max`, `step`
`date`	Date-Picker	`"2026-06-30"`	`min`, `max`
`bool`	Checkbox	`true`/`false`	—
`article`	Artikel-Suche	`12345` (Artikel-ID)	Auto-Complete gegen `tArtikel`
`customer`	Kunden-Suche	`67890` (Kunden-ID)	Auto-Complete gegen `tKunde`

Beispiel: Alle Parameter-Typen

jsonparameters.json

"parameters": [
  { "name": "title", "type": "string", "label": "Titel", "required": true, "minLength": 3, "maxLength": 50 },
  { "name": "limit", "type": "number", "label": "Anzahl", "required": true, "min": 1, "max": 100, "default": 10 },
  { "name": "since", "type": "date", "label": "Seit", "required": true, "default": "2026-01-01" },
  { "name": "active", "type": "bool", "label": "Nur aktive", "required": false, "default": true },
  { "name": "article", "type": "article", "label": "Artikel", "required": false },
  { "name": "customer", "type": "customer", "label": "Kunde", "required": false }
]

DB-Rollen

Wert	Bedeutung	Typische Plugins
`read`	`db_datareader` reicht	Reports, KPIs, Suchen
`write`	`db_datawriter` nötig	Automationen, Backfills
`owner`	`db_owner` nötig	Schema-Änderungen (selten)

Bei der Installation prüft der Sidecar, ob die Hub-DB-Rolle ≥ requiresDbRole ist. Sonst: DB_ROLE_MISMATCH.

Kategorien

Wert	Bedeutung
`report`	Read-only-Queries, zeigt Ergebnisse in DataTable
`automation`	Hintergrund-Tasks, schreiben in die DB (geplant)

Beispiel: Minimales Manifest

jsonmanifest.json

{
  "id": "example.hello-world",
  "name": "Hello World",
  "version": "1.0.0",
  "category": "report",
  "requiresDbRole": "read",
  "queries": [
    {
      "id": "count",
      "name": "Anzahl Artikel",
      "file": "sql/count.sql",
      "parameters": []
    }
  ]
}

sqlsql/count.sql

SELECT COUNT(*) AS ArtikelAnzahl FROM tArtikel