AddOn/Calender_Office365_User/Fehlzeitenimport/readme.md aktualisiert

AddOn/Calender_Office365_User/Fehlzeitenimport/readme.md

@@ -1,71 +1,108 @@
-## Kalenderfehlzeiten aus der ZeusX Zeiterfassung übernehmen
+# Kalenderfehlzeiten aus der ZeusX-Zeiterfassung übernehmen
 
-Die Zeiterfassungssoftware ZeusX bitet eine WebAPI Schnittstelle an.
+Die Zeiterfassungssoftware **ZeusX** bietet eine WebAPI-Schnittstelle zur automatisierten Datenabfrage, z. B. für Kalenderfehlzeiten.
+
+---
 
 ## Voraussetzungen
 
 - PHP 7.x oder höher  
-- cURL-Erweiterung
+- cURL-Erweiterung für PHP  
-- REST WebAPI Client für die Einrichtung
+- REST WebAPI Client zur Einrichtung  
-- Webserver mit HTTPS-Unterstützung beim ZeusX 
+- Webserver mit HTTPS-Unterstützung (für die ZeusX-Weboberfläche)  
-- Softwarelizenz für den Export von Kalenderfehlzeiten über WebAPI
+- Lizenz zur Nutzung der WebAPI für den Export von Kalenderfehlzeiten  
 
-## Installation
+---
 
-1. **Export in der Zeiterfassungssoftware anlegen**
+## Installation & Einrichtung
-   - Einrichtung >> Modelle >> Datenaustausch >> Exportdefinition >> [+]Neu
-   - Export-Layout hochladen
 
-2. **(De)Aktievierung der zusätzlichen Zeitstempelverschlüsselung bei jedem Webrequest**
+### 1. Export in der ZeusX-Software anlegen
-   - Als Systemadministrator anmelden
-   - Einrichtung >> Personen
-   - Zum Systemsart (01.01.2000) springen
-   - Systemeinstellungen >> API Web-Service >> Datenschutzeinstellung: Auf zusätzliche Client Autorisierung wird verzichtet
-   - Erstellung des (Bearer) Token über `https://<ZeusX WebUI URL>/Environment/Account/Token.aspx` mit dem Schnittstelle `webapi` und dem ZeusX Login
 
-3. **Abfrage testen**
+- Navigiere zu:  
-   - Abfrage aller Exporte aus der Zeiterfassungssoftware ZeusX mit einem GET Request:
+  `Einrichtung → Modelle → Datenaustausch → Exportdefinition → [+] Neu`
-   ``` 
+- Lade dort das gewünschte Export-Layout hoch.
+
+---
+
+### 2. (De)Aktivierung der zusätzlichen Zeitstempelverschlüsselung
+
+- Als **Systemadministrator** in der ZeusX-Weboberfläche anmelden  
+- Navigiere zu:  
+  `Einrichtung → Personen → (Datum 01.01.2000 auswählen)`  
+  `Systemeinstellungen → API Web-Service → Datenschutzeinstellung`
+- Stelle sicher, dass **„Auf zusätzliche Client-Autorisierung wird verzichtet“** aktiviert ist.
+- Erstelle ein Bearer-Token unter:  
+  `https://<ZeusX-WebUI-URL>/Environment/Account/Token.aspx`  
+
+  Mit folgenden Angaben:
+  - **Schnittstelle:** `webapi`  
+  - **Login:** Dein ZeusX-Benutzerkonto
+
+---
+
+## API-Anfragen
+
+### 3. Verfügbare Exporte abfragen
+
+```bash
 curl --request GET \
      --url https://<Server-URL>/<API-Site>/api/export/ \
      --header 'authorization: <Token>'
 ```
-   Hier wird dann ein JSON zurückgegeben mit einer Liste aller in der Zeiterfassungssoftware ZeusX definierten Exportdefinitionen
-   Zur Abfrage wird die ObjektId aus dem JSON benötigt.
 
-   - Abfrage aller Organisationseinhgeiten bzw. Abteilungen per GET Request, die ine der Zeiterfassungssoftware ZeusX angelegt sind:
+> Gibt eine JSON-Liste aller in ZeusX definierten **Exportdefinitionen** zurück.  
-   ``` 
+> Die jeweilige **`ObjectId`** wird für spätere Anfragen benötigt.
+
+---
+
+### 4. Organisationseinheiten abfragen
+
+```bash
 curl --request GET \
      --url https://<Server-URL>/<API-Site>/api/organization/ \
      --header 'authorization: <Token>'
 ```
-   Hier wird wieder die ObjektId aus dem zurück gegebenen JSON der jeweiligen OE benötigt.
 
-   - Beantragung der Erstellung und zusammenfügen der Daten aus der Zeiterfassungssoftware+ ZeusX per POST Request:
+> Liefert alle in ZeusX angelegten **Organisationseinheiten** (Abteilungen) mit zugehörigen `ObjectId`s.
-   ``` 
+
+---
+
+### 5. Export beantragen
+
+```bash
 curl --request POST \
      --url https://<Server-URL>/<API-Site>/api/export \
      --header 'authorization: <Token>' \
      --header 'content-type: application/json' \
      --data '{
-         "ExportDefinition":"<ObjektId vom ersten Request>",
+       "ExportDefinition": "<ObjectId aus Schritt 3>",
-         "organizationUnit":"<ObjektId vom zweiten Request>",
+       "organizationUnit": "<ObjectId aus Schritt 4>",
-         "DateFrom":"<Startdatum der Exportwerte im Format dd.mm.yyyy>",
+       "DateFrom": "01.01.2024",
-         "DateUntil":"<Enddatum der Exportwerte im Format dd.mm.yyyy>"
+       "DateUntil": "31.01.2024"
      }'
 ```
-   Hier wird ein reiner Text zurück gegeben mit einer GUID die für die Abfrage der Daten notwendig ist.
 
-   - Abfrage der Exportdaten die beantragt worden sind per GET Request:
+> Gibt eine GUID zurück, die zur Abfrage der generierten Daten verwendet wird.
-   ``` 
+
+---
+
+### 6. Exportdaten abrufen
+
+```bash
 curl --request GET \
-       --url https://<Server-URL>/<API-Site>/api/export/<GUID Rückgabewert aus der Beantragung der Daten> \
+     --url https://<Server-URL>/<API-Site>/api/export/<GUID> \
      --header 'authorization: <Token>'
 ```
-   Hier kann die Antwort entweder die zu erwartenden Daten sein, oder folgendses JSON, was dann bedeutet das die Erstellung der Daten aktuell noch andauert:
+
-   ``` 
+> **Mögliche Antworten:**
-   {
+
+- **Daten liegen vor:**  
+  Die Antwort enthält die exportierten Daten.
+
+- **Export läuft noch:**  
+  Rückgabe folgender JSON-Statusmeldung: 
+  `{
   "Result": "JobPending",
   "Message": ""
 }
-   ``` 
+`