DATAZONE Connect

DATAZONE Connect ist ein generischer Script-Runner fuer Integrationen mit Drittsystemen. Er laeuft als eigener Docker-Container und stellt eine REST-API bereit, ueber die Scripts mit Variablen ausgefuehrt werden koennen.

Konzept

Connect verfolgt einen Scripts-first-Ansatz: Jede Integration (Nuclos, Teams, Slack, Zammad, etc.) ist ein einfaches Shell-Script mit standardisierten Metadaten. Das bedeutet maximale Flexibilitaet bei minimalem Aufwand.

Architektur

DATAZONE Control                    DATAZONE Connect
+------------------+               +------------------+
| Playbook         |  Webhook-Step | Flask API (5002) |
|   Step 1: Script |  ----------> | /api/scripts/run |
|   Step 2: Task   |               |                  |
|   Step 3: Webhook| ------------> | /scripts/         |
+------------------+               |   nuclos.sh      |
                                   |   teams.sh       |
                                   |   slack.sh        |
                                   +------------------+

Wie es funktioniert

1. Scripts werden im Ordner connect/scripts/ abgelegt
2. Connect liest automatisch die Metadaten aus den Script-Headern (@name, @description, @var)
3. Variablen werden als Umgebungsvariablen an die Scripts uebergeben
4. Zugangsdaten (Passwoerter, API-Keys) kommen aus den Container-Umgebungsvariablen, nicht aus den Scripts
5. Scripts geben strukturierte Ergebnisse ueber die Konvention #RESULT:{json} zurueck

REST-API

Health-Check

GET /api/health

Gibt den Status des Containers und die Anzahl verfuegbarer Scripts zurueck.

Scripts auflisten

GET /api/scripts

Gibt eine Liste aller verfuegbaren Scripts mit Metadaten zurueck:

[
  {
    "name": "Nuclos Billing",
    "filename": "nuclos-billing.sh",
    "description": "Erstellt Taetigkeitsnachweis mit Position in Nuclos.",
    "vars": [
      {"name": "CUSTOMER_NUMBER", "required": true, "description": "Kundennummer (z.B. K-10001)"},
      {"name": "CUSTOMER_NAME", "required": true, "description": "Kundenname"},
      {"name": "TASK", "required": true, "description": "Beschreibung der Taetigkeit"}
    ]
  }
]

Script ausfuehren

POST /api/scripts/run
Content-Type: application/json

{
  "script": "nuclos-billing.sh",
  "vars": {
    "CUSTOMER_NUMBER": "K-10001",
    "CUSTOMER_NAME": "Bell & Schmidt",
    "TASK": "OPNsense Firmware Update"
  }
}

Synchrone Ausfuehrung (Standard): Wartet auf das Ergebnis und gibt es direkt zurueck.

Asynchrone Ausfuehrung: Mit ?async=true wird ein Job erstellt, dessen Status abgefragt werden kann:

POST /api/scripts/run?async=true
→ {"job_id": "abc123", "status": "running"}

GET /api/jobs/abc123
→ {"status": "completed", "exit_code": 0, "result": {...}}

Eingehende Webhooks

POST /api/webhooks/incoming/{name}

Empfaengt externe Webhook-Aufrufe (z.B. von Zammad, GitLab, etc.) und fuehrt das zugehoerige Script aus. Der Webhook-Body wird als WEBHOOK_BODY-Umgebungsvariable uebergeben.

Ausfuehrungslog

GET /api/logs
GET /api/logs?limit=10

Gibt die letzten Script-Ausfuehrungen mit Status und Ergebnis zurueck.

Scripts erstellen

Metadaten-Format

Jedes Script beginnt mit einem standardisierten Header:

#!/bin/bash
###############################################################################
# @name Mein Script
# @description Kurze Beschreibung was das Script macht.
#
# @var PFLICHT_VAR     required  Beschreibung der Pflicht-Variable
# @var OPTIONAL_VAR    optional  Beschreibung der optionalen Variable
###############################################################################

Feld	Pflicht	Beschreibung
@name	Ja	Anzeigename des Scripts
@description	Ja	Kurzbeschreibung
@var	Nein	Variable mit Name, required/optional und Beschreibung

Strukturierte Rueckgabe

Scripts koennen ein JSON-Ergebnis ueber die Konvention #RESULT:{json} zurueckgeben:

echo "#RESULT:{\"success\":true,\"id\":42,\"message\":\"Erstellt\"}"

Connect parst die letzte Zeile die mit #RESULT: beginnt und gibt das JSON als result-Feld in der API-Antwort zurueck.

Zugangsdaten

Zugangsdaten werden niemals direkt in Scripts gespeichert. Stattdessen werden sie als Container-Umgebungsvariablen konfiguriert:

# Im Script: Umgebungsvariable nutzen
NUCLOS_PASS="${NUCLOS_PASS:?NUCLOS_PASS nicht gesetzt}"

# In docker-compose.yml: Variable definieren
# environment:
#   - NUCLOS_PASS=${NUCLOS_PASS:-}

# In .env: Wert setzen
# NUCLOS_PASS=geheim123

Mitgelieferte Scripts

Nuclos Billing

Datei: nuclos-billing.sh

Erstellt automatisch einen Taetigkeitsnachweis mit Position im Nuclos ERP:

Variable	Pflicht	Beschreibung
CUSTOMER_NUMBER	Ja	Kundennummer (z.B. K-10001)
CUSTOMER_NAME	Ja	Kundenname
TASK	Ja	Beschreibung der Taetigkeit
DURATION_HOURS	Nein	Dauer in Stunden (Standard: 0.5)
HOSTNAME	Nein	Hostname des betroffenen Systems
MODULE	Nein	Modultyp (opnsense, linux, etc.)

Dynamischer Projekt-Lookup: Das Script sucht automatisch das passende Nuclos-Projekt anhand der Kundennummer. Wird kein Projekt gefunden, wird auf das Default-Projekt (DATAZONE) gebucht und der Kundenname im Belegtext vorangestellt.

Umgebungsvariablen (in .env setzen):

Variable	Beschreibung
NUCLOS_URL	Nuclos Server URL (z.B. https://nuclos.example.de)
NUCLOS_USER	Nuclos Benutzername
NUCLOS_PASS	Nuclos Passwort
NUCLOS_ORGANISATION	Nuclos Organisation
NUCLOS_MITARBEITER	Mitarbeiter-ID fuer die Zeitbuchung
NUCLOS_DEFAULT_PROJEKT	Fallback-Projektname (Standard: DATAZONE)

Teams Notification

Datei: teams-notify.sh

Sendet eine Nachricht an einen Microsoft Teams Webhook:

Variable	Pflicht	Beschreibung
MESSAGE	Ja	Nachricht (Text)
TITLE	Nein	Titel der Nachricht (Standard: DATAZONE Connect)
COLOR	Nein	Farbe als Hex-Wert (Standard: 0076D7)

Umgebungsvariable: TEAMS_WEBHOOK_URL muss in .env gesetzt sein.

Integration mit Playbooks

Connect wird ueber den Webhook-Step-Typ in Playbooks angebunden. Damit koennen Integrationen direkt in Wartungs-Workflows eingebunden werden.

Beispiel: Wartung mit Nuclos-Buchung

Step	Typ	Aktion	Bei Fehler
1	VM Snapshot	Snapshot erstellen	stop
2	Task	PVE_UPDATE	continue
3	Online pruefen	Warten bis online	stop
4	Webhook	Nuclos Billing (30 Min buchen)	continue
5	Webhook	Teams Benachrichtigung	continue

Beispiel: Webhook-Step Konfiguration

Fuer den Webhook-Step im Playbook:

Feld	Wert
URL	http://datazone-connect:5002/api/scripts/run
Methode	POST
Body	{"script":"nuclos-billing.sh","vars":{"CUSTOMER_NUMBER":"{customer_number}","CUSTOMER_NAME":"{customer_name}","TASK":"Wartung {hostname}","MODULE":"{module}"}}
Headers	Content-Type: application/json

Die Platzhalter {customer_number}, {customer_name}, {hostname} und {module} werden automatisch mit den Daten des aktuellen Hosts ersetzt.

Docker-Konfiguration

Connect laeuft als eigener Container im Docker-Netzwerk:

connect:
  build: ./connect
  container_name: datazone-connect
  environment:
    - CONNECT_TOKEN=${CONNECT_TOKEN:-}
    - NUCLOS_URL=${NUCLOS_URL:-}
    - NUCLOS_USER=${NUCLOS_USER:-}
    - NUCLOS_PASS=${NUCLOS_PASS:-}
    - NUCLOS_ORGANISATION=${NUCLOS_ORGANISATION:-}
    - NUCLOS_MITARBEITER=${NUCLOS_MITARBEITER:-}
    - NUCLOS_DEFAULT_PROJEKT=${NUCLOS_DEFAULT_PROJEKT:-DATAZONE}
    - TEAMS_WEBHOOK_URL=${TEAMS_WEBHOOK_URL:-}
  volumes:
    - ./connect/scripts:/scripts:ro
  networks:
    - datazone-net
  restart: unless-stopped

Eigene Scripts

Eigene Scripts einfach in den Ordner connect/scripts/ legen. Der Container bindet diesen Ordner als Read-Only-Volume ein. Nach dem Hinzufuegen neuer Scripts ist kein Neustart noetig — sie werden beim naechsten API-Aufruf automatisch erkannt.

Sicherheit

Connect ist nur im Docker-Netzwerk erreichbar und von aussen nicht zugaenglich. Fuer zusaetzliche Absicherung kann ein CONNECT_TOKEN konfiguriert werden.