OMNISRV-Gazette _{(est. 2026)}
Server Betriebsdokumentation™

Eine ältere Version des Dokuments wurde geladen! Beim Speichern wird eine neue Version des Dokuments mit diesem Inhalt erstellt.

====== Einleitung ======

<WRAP info round 80% justify>
===== Worum geht es? =====

Kundinnen und Kunden können über <wrap em>eTermin</wrap> selbstständig eine Beratung buchen. 
Rund um diese Buchung werden bereits verschiedene Abläufe automatisch angestoßen – 
beispielsweise die Terminbestätigung, die Eintragung in den Kalender der Beraterin 
oder gegebenenfalls die Bereitstellung weiterer Unterlagen.

Das <wrap em>//Projekt: eTermin//</wrap> erweitert diesen bestehenden Ablauf um eine automatische 
Datenübergabe an <wrap em>Professional Works (PW)</wrap>.

Die bei einer Buchung erfassten Kundendaten werden dazu automatisch an unsere 
Datenschnittstelle übermittelt, geprüft und für Professional Works aufbereitet. 
Anschließend wird geprüft, ob die Kundin oder der Kunde dort bereits vorhanden ist.

Bestehende Daten werden dabei **nicht blind überschrieben**. Fehlende geeignete 
Informationen können ergänzt werden; ist noch kein passender Datensatz vorhanden, 
wird ein neuer Interessent angelegt.
</WRAP>

<WRAP tip round 80% justify>
===== Der Ablauf in drei Teilen =====

**Teil 1 – Kunde bucht**\\
Was passiert, wenn eine Kundin oder ein Kunde über eTermin eine Beratung bucht?

**Teil 2 – Verarbeiten der Buchung**\\
Wie werden die übermittelten Buchungsdaten geprüft und für Professional Works vorbereitet?

**Teil 3 – Datenübergabe an PW**\\
Wie wird geprüft, ob die Person bereits vorhanden ist, und was geschieht anschließend?
</WRAP>

----

====== Teil 1: Kunde bucht ======

<WRAP tip round 80% justify>
===== Was passiert nach einer Buchung? =====

Eine Kundin oder ein Kunde bucht über **eTermin** eine Beratung. Nach erfolgreicher
Buchung veranlasst eTermin automatisch verschiedene weitere Prozesse.

Die folgende Darstellung zeigt die wichtigsten Abläufe. Für unser Projekt verfolgen
wir anschließend den Weg der **Buchungsdaten an unsere Datenschnittstelle** weiter.
</WRAP>

<mermaid>
flowchart TD
 A["👤 Kunde / Kundin"] -->|bucht eine Beratung| B["📱 / 💻 eTermin-Buchungsseite"]
 B --> C["☁️ Buchung erfolgreich eTermin veranlasst nun folgende Prozesse:"]

C --> D["✉️ Bestätigung per E-Mail"]
 C --> E["📄 ggfs. Formulare zusenden"]
 C --> F["📅 Termin im Outlook-Kalender der Beraterin eintragen"]
 C --> G["💳 ggf. Zahlung via PayPal"]
 C --> H["📦 Buchungsdaten an unsere Datenschnittstelle (Webhook)"]

H --> I["➡️ Weiter mit Teil 2 Verarbeiten der Buchung"]
</mermaid>

<WRAP info round 80% justify>
<wrap em>Was bedeutet „Webhook“?</wrap>

Ein Webhook ist vereinfacht gesagt ein **digitaler Datenbote**. Sobald eine neue
Buchung erfolgt, übermittelt eTermin die dafür vorgesehenen Buchungsdaten automatisch
an unsere Datenschnittstelle. Niemand muss die Daten dort manuell abholen oder übertragen.

Die anderen dargestellten Vorgänge – beispielsweise Terminbestätigung, Kalendereintrag
oder gegebenenfalls die Zahlung – werden von **eTermin bzw. den dort angebundenen
Diensten** veranlasst. Unser Projekt verfolgt ab hier den Weg der Buchungsdaten weiter.
</WRAP>

{{ :projekte:etermin:teil-1-comic.png?direct&400 |}}
----

====== Teil 2: Verarbeiten der Buchung ======

<WRAP tip round 80% justify>
===== Was passiert mit den Buchungsdaten? =====

Die von **eTermin** übermittelten Buchungsdaten treffen an unserer Datenschnittstelle ein.
Bevor Daten an Professional Works weitergegeben werden, wird zunächst geprüft, ob sie
grundsätzlich verwendbar sind.

Anschließend wird geprüft, ob alle von **Professional Works (PW)** benötigten Angaben
vorhanden sind. Nur wenn dies erforderlich ist, werden festgelegte technische
Standardwerte ergänzt. Danach werden die Daten für die Übergabe an PW aufbereitet.
</WRAP>

<mermaid>
flowchart TD
 A["📦 Buchungsdaten aus Teil 1 kommen an"] --> B["🔍 Grundprüfung der Daten"]

B --> C{"Sind die Daten verwendbar?"}

C -- NEIN --> D["🛑 Nicht weiter verarbeiten"]
 D -.-> E["✉️ Optional: Benachrichtigung an Admin"]

C -- JA --> F{"Sind alle für PW benötigten Angaben vorhanden?"}

F -- JA --> H["🧹 Daten für PW aufbereiten"]

F -- NEIN --> G["🧩 Fehlende technisch notwendige Angaben mit festgelegten Standardwerten ergänzen z. B. Geburtsdatum → 01.01.1901"]

G --> H

H --> I["🔍 Abschlussprüfung"]
 I --> J["📦✓ Datenpaket für PW bereit"]

J --> K["➡️ Weiter mit Teil 3 Datenübergabe an PW"]
</mermaid>

<WRAP info round 80% justify>
**Warum werden manchmal Standardwerte ergänzt?**

Professional Works verlangt für die Anlage eines Datensatzes bestimmte Pflichtangaben.
Diese müssen jedoch bei einer Buchung über eTermin nicht in jedem Fall vorliegen.

Ein Beispiel ist das **Geburtsdatum**. Wurde bei der Buchung kein Geburtsdatum erfasst,
wird für die technische Übergabe der festgelegte Standardwert **01.01.1901** eingesetzt.

Dieser Wert bedeutet ausdrücklich **nicht**, dass die Kundin oder der Kunde tatsächlich
am 01.01.1901 geboren wurde. Er dient ausschließlich als technischer Platzhalter, damit
der Datensatz von Professional Works verarbeitet werden kann.

Fehlerhafte oder grundsätzlich nicht verwendbare Buchungsdaten werden dagegen
**nicht passend gemacht und nicht an PW weitergegeben**. Optional kann in diesem Fall
eine Benachrichtigung an den Administrator erfolgen.
</WRAP>

----

====== Teil 3: Datenübergabe an PW ======

<WRAP tip round 80% justify>
===== Was passiert bei der Übergabe an Professional Works? =====

Das in Teil 2 geprüfte und aufbereitete Datenpaket kann nun an **Professional Works (PW)**
übergeben werden. Bevor dort ein neuer Interessent angelegt wird, erfolgt zunächst eine
**Doublettenprüfung**.

Damit soll verhindert werden, dass eine bereits in Professional Works vorhandene Person
versehentlich ein zweites Mal angelegt wird. Abhängig vom Ergebnis dieser Prüfung wird
entweder ein neuer Interessent angelegt oder ein bereits vorhandener Datensatz geprüft
und gegebenenfalls sinnvoll ergänzt.
</WRAP>

<mermaid>
flowchart TD
 A["📦✓ Aufbereitetes Datenpaket aus Teil 2"] --> B["📨 Daten an Professional Works übergeben"]

B --> C["🔍 Doublettenprüfung"]
 C --> D{"Ist die Person bereits in PW vorhanden?"}

D -- NEIN --> E["👤 Neuen Interessenten in PW anlegen"]
 E --> F["✅ Verarbeitung abgeschlossen"]

D -- JA --> G["👤 Vorhandenen Datensatz prüfen"]
 G --> H["🔍 Übermittelte und vorhandene Angaben vergleichen"]

H --> I{"Können die neuen Angaben den vorhandenen Datensatz sinnvoll ergänzen?"}

I -- JA --> J["✓ Fehlende Angaben ergänzen"]
 I -- NEIN --> K["🛑 Vorhandene bzw. abweichende Angaben nicht blind überschreiben"]

J --> L["✉️ Optional: Benachrichtigung an Admin"]
 K --> L

L --> M["✅ Verarbeitung abgeschlossen"]
</mermaid>

<WRAP info round 80% justify>
**Warum ist die Doublettenprüfung so wichtig?**

Eine Kundin oder ein Kunde kann bereits in **Professional Works** vorhanden sein – zum
Beispiel aufgrund eines früheren Kontakts oder eines bereits bestehenden Vorgangs.
Deshalb wird nicht automatisch bei jeder eTermin-Buchung ein neuer Interessent angelegt.

Wird kein passender vorhandener Datensatz gefunden, kann ein **neuer Interessent**
angelegt werden.

Ist die Person bereits vorhanden, werden die übermittelten Angaben mit dem bestehenden
Datensatz verglichen. Fehlende Informationen können sinnvoll ergänzt werden.
**Bereits vorhandene oder abweichende Angaben werden jedoch nicht blind überschrieben.**

Damit bleibt Professional Works im Zweifelsfall die maßgebliche Datenquelle. Eine
Benachrichtigung an den Administrator kann zusätzlich vorgesehen werden, beispielsweise
wenn bei der Verarbeitung eine manuelle Prüfung sinnvoll erscheint.
</WRAP>

----

====== Die Nerd-Variante ======

<WRAP important round 80% justify>
===== Und was passiert wirklich unter der Motorhaube? =====

Die ersten drei Teile dieser Dokumentation beschreiben den Ablauf bewusst aus Sicht
der Anwenderinnen und Anwender. Für das Verständnis des Geschäftsprozesses spielen
Server, Webhooks, APIs oder Datenformate schließlich keine Rolle.

Ab hier verlassen wir die Komfortzone. :-)

Die folgenden Abschnitte beschreiben die **technische Umsetzung des Projekts eTermin**:
wie die von eTermin übermittelten Daten entgegengenommen und verarbeitet werden,
wie die Kommunikation mit **Professional Works (PW)** erfolgt und welche technischen
Mechanismen für Prüfung, Protokollierung und Fehlerbehandlung eingesetzt werden.

Dieser Bereich richtet sich insbesondere an **Administratoren, Entwickler und betreuende
IT-Dienstleister**. Er soll ermöglichen, die Funktionsweise der Automatisierung
nachzuvollziehen, Fehler systematisch einzugrenzen und das System bei Bedarf
weiterzuentwickeln.
</WRAP>

<WRAP info round 80% justify>
===== Die technische Dokumentation ist aufgeteilt in =====

**Technische Dokumentation**\\
Aufbau und Zusammenspiel der beteiligten Komponenten – vom eTermin-Webhook über die
Verarbeitung der Buchungsdaten bis zur Kommunikation mit Professional Works.

**Betrieb & Fehlersuche**\\
Was im laufenden Betrieb zu beachten ist, wo Protokolle zu finden sind und wie bei
Störungen oder fehlerhaften Übertragungen vorgegangen wird.

**Schnittstellen / API**\\
Technische Referenz der verwendeten Schnittstellen, Datenformate und relevanten
Funktionen von eTermin und Professional Works.
</WRAP>

----

====== Technische Dokumentation ======

<WRAP tip round 80% justify>
===== Wie arbeiten die beteiligten Systeme zusammen? =====

Technisch besteht die Automatisierung aus drei beteiligten Bereichen:
**eTermin** liefert die Daten einer neuen Buchung, unsere **Datenschnittstelle**
nimmt diese entgegen und verarbeitet sie, und **Professional Works (PW)**
übernimmt anschließend die geprüften und aufbereiteten Kundendaten.

Die Kommunikation erfolgt dabei automatisch über definierte Schnittstellen.
Die folgende Übersicht zeigt zunächst nur das grundsätzliche Zusammenspiel.
Die einzelnen Verarbeitungsschritte und Schnittstellen werden anschließend
genauer dokumentiert.
</WRAP>

<mermaid>
flowchart LR
 A["📅 eTermin Buchung wird abgeschlossen"] -->|"Webhook Buchungsdaten"| B["⚙️ Unsere Datenschnittstelle Daten empfangen prüfen aufbereiten"]

B -->|"API-Anfrage"| C["🗄️ Professional Works Doublettenprüfung Kundendaten"]

C -->|"API-Antwort"| B

B -->|"API-Anfrage anlegen / ergänzen"| C

C -->|"API-Antwort Ergebnis"| B

B --> D["📝 Protokollierung Ergebnis / Fehler"]
</mermaid>

<WRAP info round 80% justify>
===== Zwei unterschiedliche Schnittstellen =====

Obwohl der gesamte Vorgang automatisch abläuft, werden technisch zwei unterschiedliche
Kommunikationswege verwendet.

**eTermin → unsere Datenschnittstelle**\\
eTermin stößt die Verarbeitung an. Nach einer Buchung werden die vorgesehenen
Buchungsdaten automatisch an unsere Datenschnittstelle gesendet. Technisch erfolgt
dies über einen **Webhook**.

**Unsere Datenschnittstelle ↔ Professional Works**\\
Die Kommunikation mit Professional Works erfolgt dagegen über dessen **API**.
Unsere Datenschnittstelle stellt dort gezielt Anfragen – beispielsweise zur Prüfung
vorhandener Kundendaten oder zum Anlegen bzw. Ergänzen eines Datensatzes – und
verarbeitet anschließend die jeweilige Antwort von PW.

Damit übernimmt unsere Datenschnittstelle die Rolle des Vermittlers zwischen beiden
Systemen.

<wrap em>eTermin und Professional Works kommunizieren für diesen Prozess nicht
direkt miteinander.\\ 
Es braucht einen Zwischenstopp zwecks Plausibilitätsprüfung, Zuweisung zu den richtigen Datenfeldern und Prüfung der Professional Works Mindestanforderungen.</wrap>
</WRAP>

<WRAP todo>\\ 
<wrap em>Die einzelnen Scripte für Webhook und Datenanpassung folgen.</wrap>
</WRAP>

----

====== Betrieb & Fehlersuche ======

<WRAP tip round 80% justify>
===== Was passiert, wenn etwas nicht funktioniert? =====

Die Datenübertragung zwischen eTermin und Professional Works läuft im Normalbetrieb
**vollständig automatisch**. Ein manueller Eingriff ist daher grundsätzlich nicht
erforderlich.

Trotzdem muss jederzeit nachvollziehbar bleiben, ob eine Buchung erfolgreich verarbeitet
wurde oder an welcher Stelle die Verarbeitung abgebrochen ist.

Deshalb werden die wesentlichen Verarbeitungsschritte und deren Ergebnis
**protokolliert**. Tritt ein Fehler auf, darf daraus insbesondere kein unkontrollierter
oder unvollständiger Datensatz in Professional Works entstehen.

Je nach Art des Fehlers kann zusätzlich eine **Benachrichtigung an den Administrator**
erfolgen.
</WRAP>

<mermaid>
flowchart TD
 A["📦 Neue Buchungsdaten"] --> B["⚙️ Automatische Verarbeitung"]

B --> C{"Verarbeitung erfolgreich?"}

C -->|"JA"| D["✅ Vorgang erfolgreich abgeschlossen"]
 D --> E["📝 Ergebnis protokollieren"]

C -->|"NEIN"| F["🛑 Verarbeitung abbrechen"]
 F --> G["📝 Fehler und Ursache protokollieren"]
 G -.-> H["✉️ Optional: Administrator benachrichtigen"]
</mermaid>

<WRAP important round 80% justify>
===== Grundsatz bei Fehlern =====

**Ein Fehler darf nicht durch Raten „repariert“ werden.**

Kann ein Datensatz nicht eindeutig oder sicher verarbeitet werden, wird die automatische
Verarbeitung an der betreffenden Stelle beendet. Der Fehler wird protokolliert und kann
anschließend gezielt geprüft werden.

Insbesondere werden bei Fehlern **keine widersprüchlichen Angaben in Professional Works
blind überschrieben** und keine technisch zweifelhaften Daten erzeugt, nur damit der
Vorgang formal als erfolgreich abgeschlossen werden kann.

Damit gilt auch im automatisierten Betrieb:

<wrap em>Im Zweifel kontrolliert abbrechen und nachvollziehbar protokollieren statt falsche Daten zu erzeugen.</wrap>
</WRAP>

<WRAP info round 80% justify>
===== Wo finde ich die technischen Informationen? =====

Die konkreten Informationen für den Betrieb werden an dieser Stelle ergänzt, sobald
die technische Umsetzung abgeschlossen ist. Dazu gehören insbesondere:

* Speicherort und Aufbau der Protokolle
  * mögliche Fehlerzustände und deren Bedeutung
  * Benachrichtigungen an den Administrator
  * Prüfung des Betriebszustands
  * Vorgehen bei fehlgeschlagenen Übertragungen
  * Wiederholung bzw. erneute Verarbeitung eines Vorgangs

Diese Angaben werden aus der **tatsächlich eingesetzten Implementierung** dokumentiert
und nicht vorab angenommen.
</WRAP>

----

====== Schnittstellen / API ======

<WRAP tip round 80% justify>
===== Über welche Schnittstellen kommunizieren die Systeme? =====

Für die automatische Verarbeitung einer eTermin-Buchung werden zwei technisch
unterschiedliche Schnittstellen und Kommunikationswege verwendet.

<wrap em>eTermin → unsere Datenschnittstelle</wrap>\\
eTermin stößt die Verarbeitung über einen **Webhook** an. Nach Abschluss einer
Buchung sendet eTermin die vorgesehenen Buchungsdaten selbstständig an eine
dafür bereitgestellte Adresse unserer Datenschnittstelle.

Die Buchungsdaten werden dabei als **JSON-Datenblock** übertragen. Dieser enthält
die von eTermin bereitgestellten Informationen zur Buchung und zur betreffenden
Person.

<wrap em>Unsere Datenschnittstelle ↔ Professional Works</wrap>\\
Die weitere Kommunikation erfolgt über die **API von Professional Works**.
Unsere Datenschnittstelle übernimmt hierbei die aktive Rolle und stellt gezielte
HTTP-Anfragen an PW.

Je nach benötigter Aktion werden insbesondere **GET-Anfragen** zum Abrufen bzw.
Prüfen vorhandener Informationen und **POST-Anfragen** zur Übergabe neuer Daten
bzw. zum Auslösen entsprechender Aktionen verwendet. Die Antworten von
Professional Works werden anschließend von unserer Datenschnittstelle ausgewertet.

<wrap em>Der Zwischenstopp auf unserer Datenschnittstelle ist deshalb technisch notwendig:</wrap>\\
Der von eTermin gelieferte JSON-Datenblock kann nicht einfach unverändert an
Professional Works weitergereicht werden. Die enthaltenen Daten müssen geprüft,
den entsprechenden PW-Datenfeldern zugeordnet und bei Bedarf um technisch
erforderliche Angaben ergänzt werden. Anschließend erzeugt unsere
Datenschnittstelle daraus die jeweils benötigten HTTP-Anfragen an die
Professional-Works-API.

Unsere Datenschnittstelle übernimmt damit nicht nur den Transport, sondern die
**Übersetzung und kontrollierte Vermittlung zwischen zwei unterschiedlichen
Schnittstellen**.
</WRAP>

<mermaid>
flowchart LR
 ET["📅 eTermin Buchung abgeschlossen"]

HOOK["⚙️ Unsere Datenschnittstelle Webhook empfangen"]

PROC["🔎 Verarbeitung prüfen zuordnen aufbereiten"]

PW["🗄️ Professional Works API"]

ET -->|"Webhook Buchungsdaten"| HOOK
 HOOK --> PROC

PROC -->|"API-Anfrage"| PW
 PW -->|"API-Antwort"| PROC
</mermaid>

<WRAP info round 80% justify>
===== Webhook und API – der entscheidende Unterschied =====

**Webhook**\\
Beim Webhook beginnt das sendende System die Kommunikation. eTermin meldet
unserer Datenschnittstelle sinngemäß:

//„Es ist etwas passiert – hier sind die Daten dazu.“//

Unsere Datenschnittstelle muss eTermin daher nicht ständig nach neuen Buchungen
fragen.

**API**\\
Bei der Kommunikation mit Professional Works beginnt dagegen unsere
Datenschnittstelle die jeweilige Aktion. Sie fragt beispielsweise sinngemäß:

//„Existiert diese Person bereits?“//\\
//„Lege diesen Interessenten an.“//\\
//„Ergänze diese zulässigen Angaben.“//

Professional Works verarbeitet die Anfrage und liefert eine Antwort zurück.

<wrap em>Webhook = eTermin meldet ein Ereignis. API = unsere Datenschnittstelle führt gezielte Aktionen mit Professional Works aus.</wrap>
</WRAP>

<WRAP important round 80% justify>
===== Technische Referenz =====

Die konkreten technischen Angaben werden mit der tatsächlich eingesetzten
Implementierung dokumentiert. Dazu gehören insbesondere:

* verwendete URLs bzw. Endpunkte
  * HTTP-Methoden und erwartete Statuscodes
  * Authentifizierung
  * übertragene Datenfelder und Datenformate
  * Zuordnung eTermin-Felder → interne Verarbeitung → PW-Felder
  * Pflichtfelder und verwendete technische Standardwerte
  * Doublettenprüfung
  * Fehlerantworten und deren Behandlung
  * Versionsstand der verwendeten Schnittstellen

Diese Angaben werden **nicht aus Annahmen vorab erzeugt**, sondern aus den
tatsächlich eingesetzten Webhook- und API-Implementierungen übernommen.
</WRAP>

----

Zusammenfassung