# GraphQL-Endpunkt — Einrichtung und Betrieb

<span class="custom-button red-button">Gen. 24 Core & Enterprise</span>

**Ab Build 7145**

## 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 "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 "Info"

    Weitere Informationen zur HTTP/2-Einrichtung finden Sie in der microtech Hilfe: [Serverkonfiguration - Register: HTTP/2](../04_moduluebergreifend/programmeinrichtung%20und%20konfiguration/serverkonfiguration/glserverkonfigurationhttp2.md).
    
    Weitere Informationen zu HTTPS und Domain-Anforderungen finden Sie auf der Seite **[OAuth 2.0 API-Dokumentation im Bereich "HTTPS und Domain-Anforderungen"](./oauthapidoku.md#15-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"**.

![GraphQL für Mandant aktivieren](https://assets.hilfe.microtech.de/bilder/18_graphql/graphqlendpunkteinrichten_1.png)

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.

!!! warning "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 "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](./oauthapidoku.md).

<span class="custom-button red-button">Gen. 24 Enterprise</span>

### 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.

!!! warning "Beachten Sie"

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

<span class="custom-button red-button">Gen. 24 Core & Enterprise</span>

## 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:**
```json
{
  "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):**
```json
{
  "mandNr": "01",
  "available": true,
  "status": "running",
  "skipReason": null,
  "skipDetail": null,
  "error": null,
  "globalReason": null,
  "globalSeverity": null
}
```

!!! warning "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):**
```json
{
  "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:

```json
{
  "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 |

![Ereingnis-Protokoll relevante Ereignisse anzeigen](https://assets.hilfe.microtech.de/bilder/18_graphql/graphqlendpunkteinrichten_2.png)

!!! info "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.

!!! warning "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 |