GraphQL-Endpunkt — Einrichtung und Betrieb

Gen. 24 Core & Enterprise

1. Übersicht

Die microtech Software stellt GraphQL-Endpunkte automatisch bereit. Sobald Sie GraphQL für einen Mandanten aktivieren, erkennt der Datenserver die Änderung und stellt den zugehörigen Endpunkt unter einer festen, stabilen URL zur Verfügung. Eine manuelle Einrichtung von Automatisierungsdiensten ist dafür nicht erforderlich.

Jeder Mandant erhält seinen eigenen Endpunkt mit einer vorhersagbaren URL-Struktur. Eine zentrale Statusübersicht zeigt den aktuellen Zustand aller Endpunkte.

1.1. Was ändert sich gegenüber der manuellen Einrichtung?

	Manuell (Automatisierungsdienst)	Automatisch
Einrichtung	Aufgaben-Dienst anlegen und konfigurieren	Kennzeichen pro Mandant aktivieren
URL	Enthält eine GUID als Kennung	Feste, vorhersagbare Struktur pro Mandant
Verwaltung	Manuell starten und stoppen	Automatisch durch den Datenserver
Statusübersicht	Ereignis-Protokoll pro Dienst	Zentrale Statusseite für alle Mandanten

Info

Bestehende, manuell eingerichtete Automatisierungsdienste des Typs "GraphQL-Server" bleiben unverändert funktionsfähig. Sie können beide Varianten parallel betreiben.

2. Einrichtung

2.1. Voraussetzungen

Für den automatischen GraphQL-Endpunkt gelten dieselben Voraussetzungen wie für die manuelle Einrichtung:

• microtech Software mit GraphQL-Lizenz (Gen. 24 Enterprise oder Partner-App-Lizenz)

• HTTP/2 im Datenserver eingerichtet und aktiviert

• Gültiges SSL-Zertifikat in der microtech Serverkonfiguration (BpConfig.exe) hinterlegt

Zusätzlich muss mindestens ein Benutzer mit aktiviertem GraphQL-Zugangskennzeichen vorhanden sein.

Info

Weitere Informationen zur HTTP/2-Einrichtung finden Sie in der microtech Hilfe: Serverkonfiguration - Register: HTTP/2.

Weitere Informationen zu HTTPS und Domain-Anforderungen finden Sie auf der Seite OAuth 2.0 API-Dokumentation im Bereich "HTTPS und Domain-Anforderungen"

2.2. GraphQL pro Mandant aktivieren

Die Aktivierung erfolgt über Registerkarte: DATEI - INFORMATIONEN - AKTUELLE FIRMA / FILIALE / MANDANT - Schaltfläche: MANDANT BEARBEITEN - Register: WEITERE ANGABEN - Abschnitt: VORGABEN / EINSTELLUNGEN. Aktivieren Sie dort das Kennzeichen "GraphQL aktiviert".

Nach der Aktivierung erkennt der Datenserver die Änderung innerhalb weniger Sekunden und startet den zugehörigen GraphQL-Endpunkt automatisch. Den Status können Sie über die Statusübersicht (siehe Abschnitt 4) oder im Ereignis-Protokoll verfolgen.

Beachten Sie

Das Kennzeichen ist nur sichtbar, wenn eine GraphQL-Lizenz vorhanden ist.

3. URL-Struktur

3.1. Basis-URL

Jeder automatische Endpunkt ist unter einer festen URL erreichbar:

https://<server.domain>/microtech/erp/mand/<MandNr>/

Der Bestandteil erp ist der Servername der Standard-Releaseversion. Spezialversionen, die parallel installiert werden können, verwenden einen abweichenden Servernamen:

Version	Servername
Release	erp
Beta	erpb
Schulung	erps

Die exakte URL eines gestarteten Endpunkts wird im Ereignis-Protokoll angezeigt.

Info

Das Ereignis-Protokoll erreichen Sie in der microtech Software unter Registerkarte: DATEI - INFORMATIONEN - GLOBALE DATEN - Ereignis-Protokoll.

Beispiel:

https://erp.firma.internal/microtech/erp/mand/01/

3.2. Endpunkte

Unter der Basis-URL stehen folgende Endpunkte zur Verfügung:

Endpunkt	Beschreibung
/graphql/v1	GraphQL-API für Datenzugriff
/login	Browser-Login (Benutzername/Passwort oder Windows SSO)
/logout	Beendet Browser-Session
/authorize	Startet OAuth 2.0-Flow
/token	Tauscht Codes gegen Tokens, erneuert Tokens
/revoke	Widerruft Tokens

Alle Endpunkte erfordern eine Authentifizierung über OAuth 2.0 (Bearer Token) oder Browser-Session. Eine detaillierte Beschreibung der Authentifizierungsmethoden und HTTP-Parameter finden Sie in der OAuth 2.0 API-Dokumentation.

Gen. 24 Enterprise

3.3. Interaktive Oberfläche

Wird die Basis-URL in einem Browser aufgerufen, erscheint eine Übersichtsseite mit Anmeldestatus und einem Link zur GraphQL-API. Nach erfolgreicher Anmeldung steht unter /graphql/v1 die interaktive GraphQL-Oberfläche (Apollo Sandbox) zur Verfügung, über die Abfragen direkt im Browser getestet werden können.

Beachten Sie

Die interaktive Oberfläche ist derzeit nur in der Enterprise-Edition verfügbar.

Gen. 24 Core & Enterprise

4. Statusübersicht

4.1. HTML-Statusseite

Die zentrale Statusseite ist ohne Authentifizierung unter folgender URL erreichbar:

https://<server.domain>/microtech/erp/mand/

Sie zeigt eine Übersicht aller Mandanten und deren aktuellem Status:

Status	JSON-Wert	Farbe	Bedeutung
Aktiv	running	grün	Endpunkt ist aktiv und erreichbar
Wird initialisiert	initializing	blau	Endpunkt wurde gestartet und meldet sich beim Datenserver an
Gestartet, warte auf Rückmeldung	spawned	blau	Prozess wurde gestartet, erste Rückmeldung steht aus
Start vorgemerkt	start_queued	gelb	Endpunkt ist zum Start vorgemerkt
Blockiert	blocked	orange	Endpunkt kann nicht gestartet werden (z. B. Mandant in Konvertierung)
Stop angefordert	stop_requested	orange	Endpunkt wurde zum Stoppen aufgefordert
Wird gestoppt	stopping	rot	Endpunkt wird gerade beendet
Gestoppt	stopped	grau	Endpunkt wurde gestoppt
Inaktiv	disabled	grau	GraphQL ist für diesen Mandanten nicht aktiviert

Bei laufenden Endpunkten enthält die Statusseite einen direkten Link zum jeweiligen Mandanten-Endpunkt.

Wird die URL eines nicht laufenden Mandanten-Endpunkts aufgerufen (z. B. https://.../mand/01/), zeigt die Statusseite eine kontextbezogene Meldung mit dem aktuellen Status und dem Grund an.

4.2. JSON-API

Dieselbe URL liefert bei Anfragen mit Accept: application/json eine maschinenlesbare Statusübersicht:

GET /microtech/erp/mand/ HTTP/1.1
Accept: application/json

Antwort:

{
  "globalReason": null,
  "globalSeverity": null,
  "relays": [
    {
      "mandNr": "01",
      "status": "running",
      "skipReason": null,
      "skipDetail": null
    },
    {
      "mandNr": "02",
      "status": "disabled",
      "skipReason": null,
      "skipDetail": null
    }
  ]
}

Feld	Beschreibung
globalReason	Maschinenlesbarer Grund als Enum-Wert (z. B. "maintenance_mode", "config_disabled"), oder null
globalSeverity	Schweregrad des globalen Grundes: "info", "warning", "error", oder null
relays[].mandNr	Mandantennummer
relays[].status	Status (siehe Statustabelle oben)
relays[].skipReason	Maschinenlesbarer Grund als Enum-Wert (z. B. "version_mismatch", "conversion_pending"), oder null
relays[].skipDetail	Ergänzende Details zum Skip-Grund (z. B. Versionsnummern), oder null

Mögliche globalReason-Werte:

Wert	Schweregrad	Bedeutung
not_activated	info	GraphQL-Relays warten auf HTTP-Transport
server_starting	info	Datenbank-Server wird gestartet
server_shutting_down	info	Datenbank-Server wird heruntergefahren
http_transport_inactive	warning	HTTP-Transport nicht aktiv
server_state_transition	info	Datenbank-Server-Statustransition aktiv
server_not_started	warning	Datenbank-Server nicht gestartet
maintenance_mode	info	Datenbank-Server im Wartungsmodus
config_disabled	info	GraphQL-Relay in Konfiguration deaktiviert
license_insufficient	error	GraphQL-Modul nicht lizenziert
max_instances_zero	info	MaxInstances=0 in Konfiguration
no_graphql_users	info	Keine Benutzer mit GraphQL-Zugang konfiguriert
global_data_not_readable	error	Globale Daten nicht lesbar

Mögliche skipReason-Werte:

Wert	Bedeutung	skipDetail
conversion_pending	Konvertierung ausstehend	KonvKz=N
data_restore_pending	Datenrücksicherung ausstehend	—
initialization_pending	Erstinitialisierung ausstehend	—
reconciliation_pending	Tabellenabgleich ausstehend	—
never_opened	Mandant wurde noch nicht geöffnet	—
version_mismatch	Versionsunterschied	Mandant: X, Server: Y
version_not_readable	Versionsinformation nicht lesbar	Fehlermeldung
global_maintenance_pending	Globale Wartung ausstehend	—

Der Status einzelner Mandanten ist ebenfalls als JSON abrufbar:

GET /microtech/erp/mand/01/ HTTP/1.1
Accept: application/json

Antwort (Endpunkt läuft):

{
  "mandNr": "01",
  "available": true,
  "status": "running",
  "skipReason": null,
  "skipDetail": null,
  "error": null,
  "globalReason": null,
  "globalSeverity": null
}

Beachten Sie

Diese Antwort wird vom laufenden Relay-Prozess selbst geliefert. Ist der Endpunkt nicht erreichbar, antwortet stattdessen die Statusseite des Datenservers:

Antwort (Endpunkt nicht verfügbar):

{
  "mandNr": "01",
  "available": false,
  "status": "blocked",
  "skipReason": "conversion_pending",
  "skipDetail": "KonvKz=3",
  "error": null,
  "globalReason": null,
  "globalSeverity": null
}

Feld	Beschreibung
available	true wenn der Endpunkt aktiv und erreichbar ist
status	Aktueller Status (siehe Statuswerte oben)
skipReason	Maschinenlesbarer Grund als Enum-Wert, oder null
skipDetail	Ergänzende Details zum Skip-Grund, oder null
error	Fehlermeldung bei internen Problemen, sonst null

GraphQL-Endpunkt nicht erreichbar:

Wird ein GraphQL-Endpunkt direkt angefragt (z. B. GET /microtech/erp/mand/01/graphql/v1 mit Accept: application/json), liefert die Statusseite eine GraphQL-spec-konforme Fehlerantwort:

{
  "data": null,
  "errors": [
    {
      "message": "GraphQL-Relay für Mandant 01 nicht verfügbar",
      "extensions": {
        "code": "RELAY_UNAVAILABLE",
        "status": "blocked",
        "skipReason": "conversion_pending",
        "skipDetail": "KonvKz=3"
      }
    }
  ]
}

GraphQL-Clients können diese Antwort wie eine reguläre GraphQL-Fehlerantwort verarbeiten. Der extensions.code-Wert RELAY_UNAVAILABLE unterscheidet sie von Fehlern des laufenden GraphQL-Endpunkts.

5. Betrieb

5.1. Automatisches Starten und Stoppen

Der Datenserver überprüft regelmäßig, welche Mandanten einen GraphQL-Endpunkt benötigen. Endpunkte werden automatisch gestartet, wenn:

• Das Kennzeichen "GraphQL aktiviert" für den Mandanten gesetzt ist

• Der Mandant sich in einem startbaren Zustand befindet (z. B. keine laufende Konvertierung, keine Datenrücksicherung, passende Versionsnummer, ...)

• Mindestens ein Benutzer mit GraphQL-Zugang existiert

Der Datenserver stoppt Endpunkte automatisch, sobald eine dieser Bedingungen nicht mehr erfüllt ist, beim Herunterfahren des Datenservers oder bei Aktivierung des Wartungsmodus.

5.2. Dynamische Executor-Verwaltung

Jeder GraphQL-Relay verwaltet für jeden Benutzer mit GraphQL-Zugangskennzeichen einen eigenen Pool von GraphQL-Executor-Instanzen. Die Pools passen sich automatisch an die tatsächliche Last an:

• Bedarfsgesteuerter Start: Beim Start des Relay wird pro Benutzer zunächst nur eine Executor-Instanz erzeugt. Weitere Instanzen werden erst bei Bedarf gestartet, wenn eingehende Anfragen dies erfordern.

• Proaktive Bereitstellung: Sobald die letzte verfügbare Instanz eines Pools vergeben wird, startet der Pool vorsorglich eine neue Instanz, damit die nächste Anfrage nicht auf einen Kaltstart warten muss.

• Automatischer Abbau: Executor-Instanzen, die länger als 10 Minuten nicht verwendet wurden, werden schrittweise abgebaut. Dabei bleibt pro Pool immer mindestens eine warme Instanz erhalten, um Latenz bei der nächsten Anfrage zu vermeiden.

• Dynamische Skalierung: Der Datenserver kann die maximale Instanzanzahl (MaxInstances) im laufenden Betrieb ändern. Der Relay übernimmt den neuen Wert beim nächsten Heartbeat und propagiert ihn an alle Benutzer-Pools. Bei einer Erhöhung werden zusätzliche Instanzen bei Bedarf gestartet; bei einer Verringerung werden überzählige Instanzen beim nächsten Freiwerden oder Idle-Abbau entfernt.

5.3. Ereignis-Protokoll

Das Ereignis-Protokoll erfasst alle relevanten Ereignisse der automatischen Endpunkte. Sie können über folgende Kategorien gezielt filtern:

Gruppe	Beschreibung
GraphQL-Relay	Ereignisse des Endpunkt-Prozesses (Start, Stopp, Fehler)
GraphQL-Executor	Ereignisse der Executor-Instanzen, die Anfragen verarbeiten

Info

Das Ereignis-Protokoll erreichen Sie in der microtech Software unter Registerkarte: DATEI - INFORMATIONEN - GLOBALE DATEN - Ereignis-Protokoll.

5.4. Bestehende Automatisierungsdienste

Die automatische Bereitstellung beeinflusst manuell eingerichtete Automatisierungsdienste des Typs "GraphQL-Server" nicht. Sie können beide Varianten parallel betreiben.

Beachten Sie

Bei manuell eingerichteten Diensten wird weiterhin eine GUID-basierte URL verwendet. Der Zugriff erfordert in beiden Varianten eine Authentifizierung per OAuth 2.0 oder Browser-Session. Für neue Integrationen empfehlen wir die automatischen Endpunkte mit fester URL-Struktur.

6. Erweiterte Konfiguration

Über die Konfigurationsdatei des Datenservers (BpServer.ini) steuern Sie unter dem Abschnitt [GraphQLRelay] das Verhalten der automatischen Bereitstellung. Der Datenserver erkennt Änderungen im laufenden Betrieb — ein Neustart ist nicht erforderlich.

Parameter	Standard	Beschreibung
Disabled	False	Deaktiviert die automatische Bereitstellung vollständig
MaxInstances	10	Maximale Anzahl der Executor-Instanzen pro Endpunkt