From c18fbf180652a3363542ef9cc7d1b01c395382eb Mon Sep 17 00:00:00 2001 From: "olaf.braun" Date: Wed, 25 Jun 2025 21:21:13 +0200 Subject: [PATCH] AddOn/Calender_Office365_User/Fehlzeitenimport/readme.md aktualisiert --- .../Fehlzeitenimport/readme.md | 157 +++++++++++------- 1 file changed, 97 insertions(+), 60 deletions(-) diff --git a/AddOn/Calender_Office365_User/Fehlzeitenimport/readme.md b/AddOn/Calender_Office365_User/Fehlzeitenimport/readme.md index 67f28967..9134dcf6 100644 --- a/AddOn/Calender_Office365_User/Fehlzeitenimport/readme.md +++ b/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 -- REST WebAPI Client für die Einrichtung -- Webserver mit HTTPS-Unterstützung beim ZeusX -- Softwarelizenz für den Export von Kalenderfehlzeiten über WebAPI +- PHP 7.x oder höher +- cURL-Erweiterung für PHP +- REST WebAPI Client zur Einrichtung +- Webserver mit HTTPS-Unterstützung (für die ZeusX-Weboberfläche) +- Lizenz zur Nutzung der WebAPI für den Export von Kalenderfehlzeiten -## Installation +--- -1. **Export in der Zeiterfassungssoftware anlegen** - - Einrichtung >> Modelle >> Datenaustausch >> Exportdefinition >> [+]Neu - - Export-Layout hochladen +## Installation & Einrichtung -2. **(De)Aktievierung der zusätzlichen Zeitstempelverschlüsselung bei jedem Webrequest** - - 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:///Environment/Account/Token.aspx` mit dem Schnittstelle `webapi` und dem ZeusX Login +### 1. Export in der ZeusX-Software anlegen -3. **Abfrage testen** - - Abfrage aller Exporte aus der Zeiterfassungssoftware ZeusX mit einem GET Request: - ``` - curl --request GET \ - --url https:////api/export/ \ - --header 'authorization: ' - ``` - 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. +- Navigiere zu: + `Einrichtung → Modelle → Datenaustausch → Exportdefinition → [+] Neu` +- Lade dort das gewünschte Export-Layout hoch. - - Abfrage aller Organisationseinhgeiten bzw. Abteilungen per GET Request, die ine der Zeiterfassungssoftware ZeusX angelegt sind: - ``` - curl --request GET \ - --url https:////api/organization/ \ - --header 'authorization: ' - ``` - 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: - ``` - curl --request POST \ - --url https:////api/export \ - --header 'authorization: ' \ - --header 'content-type: application/json' \ - --data '{ - "ExportDefinition":"", - "organizationUnit":"", - "DateFrom":"", - "DateUntil":"" - }' - ``` - Hier wird ein reiner Text zurück gegeben mit einer GUID die für die Abfrage der Daten notwendig ist. +### 2. (De)Aktivierung der zusätzlichen Zeitstempelverschlüsselung - - Abfrage der Exportdaten die beantragt worden sind per GET Request: - ``` - curl --request GET \ - --url https:////api/export/ \ - --header 'authorization: ' - ``` - Hier kann die Antwort entweder die zu erwartenden Daten sein, oder folgendses JSON, was dann bedeutet das die Erstellung der Daten aktuell noch andauert: - ``` - { - "Result":"JobPending", - "Message":"" - } - ``` +- 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:///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:////api/export/ \ + --header 'authorization: ' +``` + +> 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:////api/organization/ \ + --header 'authorization: ' +``` + +> Liefert alle in ZeusX angelegten **Organisationseinheiten** (Abteilungen) mit zugehörigen `ObjectId`s. + +--- + +### 5. Export beantragen + +```bash +curl --request POST \ + --url https:////api/export \ + --header 'authorization: ' \ + --header 'content-type: application/json' \ + --data '{ + "ExportDefinition": "", + "organizationUnit": "", + "DateFrom": "01.01.2024", + "DateUntil": "31.01.2024" + }' +``` + +> Gibt eine GUID zurück, die zur Abfrage der generierten Daten verwendet wird. + +--- + +### 6. Exportdaten abrufen + +```bash +curl --request GET \ + --url https:////api/export/ \ + --header 'authorization: ' +``` + +> **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": "" +} +` \ No newline at end of file