OCT Gateway Personio | Help Center

Diese Anleitung beschreibt die Einrichtung des OCT Gateway Personio - dieses überträgt Daten aus der Personio API in die staging Schicht einer OCT Datenbank.

1. Klassifikation

Merkmal	Klassifikation
Quelldatentyp	API
Steuerungsstruktur	Auswahl der abzurufenden Tabellen aus Personio über Aktivierung der Endpunkte in der config.json Datei Eingrenzung des Datenabrufs durch Definition von Start- und Enddatum in der config.json Datei
Validierungsoberfläche	Tabellenstatistik, Views zur Prüfung der abgerufenen Daten
unterstützte OCT Versionen	5.11, 5.12, 2026.02
Installation	manuell
Programmierpattern	Loop over Tables (Tabellen sind in der Konfiguration aktiviert und werden dynamisch verarbeitet)
Tabellengruppe	staging.tPERSONIO_*
Öffentlicher Testdatenbestand	keiner bekannt
Inhalte der API	nachzulesen unter https://developer.personio.de/reference/ (Link führt zu externer Seite)

2. Funktionalität

Das Gateway spiegelt die ausgewählten Tabellenstrukturen und Daten 1:1 aus der Personio API in die staging Schicht einer OCT Datenbank.
Die Personio API liefert viele JSON-Objekte. Diese werden vom Gateway nicht weiter aufgelöst, sondern 1:1 in die Staging Tabellen geschrieben. Beispiel: Spalte “amount” mit Inhalt: {'currency': ‘EUR’, ‘value’: 0.0}.
Die OCT Datenbank stellt eine Validierungsoberfläche für diese Daten bereit.

3. Systemvoraussetzungen

3.1. Systemvoraussetzungen Personio API

Einrichtung der API Zugangsdaten in Personio: https://developer.personio.de/docs/getting-started-with-the-personio-api (Anleitung auf personio.de)
Das Gateway benötigt die Client-ID und das Client-Secret mit den passenden Zugriffsrechten auf die benötigten API-Endpunkte aus Schritt 1.

3.2. Systemvoraussetzungen OCT

OCT Applikation 5.11 oder höher - je nach Einrichtungsvariante lokal oder in der Azure Cloud
Eine OCT Datenbank, die als Zieldatenbank on-premises oder in einer Cloudumgebung erreichbar sein muss.

4. Technische Einrichtung

4.1. Variante Cloud - Einrichtung des Gateways mit OCT in der Saxess-Cloud

4.1.1. Zusätzliche Voraussetzungen:

Azure Storage Account mit Kontoname und Access Key

4.1.2. Installationsanleitung:

Schritt A im Microsoft Azure Storage Explorer oder Azure Portal im Azure Storage Account	eine Dateifreigabe “python” (Name kann auch frei vergeben werden) mit einem Ordner “scripts” (Name ist verpflichtend) anlegen den Releasordner “Gateway_Personio_v1.0.4” aus dem internen Bereich herunterladen und den Inhalt in den Ordner “scripts” kopieren im Ordner “config” in der Datei “config.json” die Zugangsdaten (api_client_id, api_client_secret) für die API, abzurufende Tabellen (in der Liste “api_endpunkte') aktivieren (1= aktiv, 0 =inaktiv) und die Zieldatenbankdaten einfügen, optional Start-und Enddatum
Schritt B in der OCT-Oberfläche im Bereich Datenflüsse	In OCT im Bereich Datenflüsse → Datenquellen einen Azure Storage vom Typ File-Storage als Datenquelle anlegen (Link zum Handbuch: https://help.onecooltool.de/oct-handbuch/v2026.02/3-2-1-6-azure-storage), Name und AccessKey sowie den File-Share Namen eintragen
Schritt C im SQL Server Management Studio	die Datenbankobjekte durch Ausführen des SQL-Scripts “SETUP_STAGING_PERSONIO.sql” aus dem Ordner “Gateway_Personio_v1.0.4/setup” in die OCT-Datenbank einspielen.
Schritt D in der OCT-Oberfläche im Bereich Datenflüsse	Prozesspipelines die Pipeline “GWPER - Datenabruf aus Personio API” öffnen Steps: “Powershell - Datenabruf aus Personio API” und “Python - Datenabruf aus Personio API” löschen oder deaktivieren im Step: “Container - Datenabruf aus Personio API” die Azure Datenquelle einstellen, unter Startbefehl config anpassen falls der Name der config.json angepasst wurde Pipeline ausführen Datenvalidierung in OCT über die Factory Validierung Gateways (VGW), Productline Validierung Gateway Personio (GWPER) durchführen

4.2. Variante On-Premises - Einrichtung des Gateways mit OCT auf einem Server

4.2.1. Zusätzliche Voraussetzungen:

eine lokale Python Installation Eine lokale Python Umgebung einrichten

4.2.2. Installationsanleitung:

Schritt A Datei entpacken	den Releasordner “Gateway_Personio_v1.0.4.zip” aus dem internen Bereich herunterladen, und nach C:\ProgramData\Saxess Software\ entpacken
Schritt B Pythonpakete installieren	im Ordner Gateway_Personio_v.1.0.4 die Datei “install_libraries_(als_Admin_ausführen).bat” mit Rechtsklick als Admin ausführen
Schritt C im SQL Server Management Studio	die Datenbankobjekte durch Ausführen des SQL-Scripts “SETUP_STAGING_PERSONIO.sql” aus dem Ordner “Gateway_Personio_v1.0.4/setup” in die OCT-Datenbank einspielen im Ordner “config” in der Datei “config.json” die Zugangsdaten (api_client_id, api_client_secret) für die API, abzurufende Tabellen (in der Liste “api_endpunkte') aktivieren (1= aktiv, 0 =inaktiv) und die Zieldatenbankdaten einfügen, optional Start-und Enddatum
Schritt D (optional): testweise Direktausführung	Python Script main.py in einem Terminal ausführen (python main.py --config=config.json), alternativ test_datenabruf.bat im Ordner “Gateway_Personio_v.1.0.4” starten
Schritt E in der OCT-Oberfläche im Bereich Datenflüsse	Prozesspipelines die Pipeline “GWPER - Datenabruf aus Personio API” öffnen Steps: “Container - Datenabruf aus Personio API” deaktivieren oder löschen nur für OCT-Version 5.11: den Step “Python - Datenabruf aus Personio API” löschen oder deaktivieren für OCT Versionen ab 5.12: den Step “Powershell - Datenabruf aus Personio API” löschen oder deaktivieren Pipeline ausführen
Schritt F Datenvalidierung	Datenvalidierung in OCT über die Factory Validierung Gateways (VGW), Productline Validierung Gateway Personio (GWPER) durchführen

5. Konfiguration der config.json Datei

5.1. Auswahl der abzurufenden Tabellen über Eintragung der API - Endpunkte

Folgende Personio API V1 Endpunkte können unter “api_endpunkte” eingetragen werden:
"v1/company/employees"
, "v1/company/employees/attributes"
, "v1/company/attendances/projects"
, "v1/company/attendances"
, "v1/company/time-offs"
, "v1/company/time-off-types"
, "v1/company/absence-periods"
, "v1/company/attendances/projects"
, "v1/company/document-categories"
, "v1/company/custom-reports/reports"

Folgende Personio API v2 Endpunkte können unter “api_endpunkte” eingetragen werden:

"v2/persons"
, "v2/persons/{person_id}/employments"
, "v2/absence-periods"
, "v2/absence-periods/{id}/breakdowns"
, "v2/absence-types"
, "v2/attendance-periods"
, "v2/compensations"
, "v2/compensations/types"
, "v2/legal-entities"
, "v2/org-units"
, "v2/cost-centers"

Das Feld “api_url” bitte nicht ändern, api_v1_batch_size hat ein Maximum von 200 und sollte auch nicht geändert werden.

5.2. Zeitliche Eingrenzung des Datenabrufs

Der Datenabruf kann über die Parameter „api_start_date“ und „api_end_date“ eingegrenzt werden. Die Datumsangaben erfolgen im Format „yyyy-mm-dd“. Dies gilt für alle Endpunkte mit Ausnahme von „v2/compensations“.
Für den Endpunkt „v2/compensations“ sind stattdessen die Parameter „api_payroll_start_date“ und „api_payroll_end_date“ zu verwenden, ebenfalls im Format „yyyy-mm-dd“. Dabei ist zu beachten, dass die Differenz zwischen beiden Datumswerten maximal einen Monat betragen darf.
Sind beide Felder „api_payroll_start_date“ und „api_payroll_end_date“ leer („“), werden automatisch die Daten des aktuellen Monats abgerufen.
Sollen sämtliche verfügbaren Daten abgerufen werden, sind die entsprechenden Datumsfelder leer zu lassen („“).

Beispielkonfiguration die alle Daten seit dem 1. Mai 2025 abruft, sowie die Compensations die seit Juni 2025 aktiv waren:

Die folgende Beispiel-Konfiguration ruft alle Daten seit dem 1. Mai 2025 sowie alle Compensations ab, die seit Juni 2025 aktiv waren:

{
  "api_start_date": "2025-05-01",
  "api_end_date": "",
  "api_payroll_start_date": "2025-06-01",
  "api_payroll_end_date": "2025-06-30"

5.3. Output

"csv_out_aktiv" : 1
"db_output_aktiv": 1

Legt fest, ob die abgerufenen Daten in die Zieldatenbank geschrieben oder als CSV-Datei auf der Festplatte bzw. in einem Azure File Share gespeichert werden.

1 = aktiviert
0 = deaktiviert

Beide Optionen können gleichzeitig aktiviert werden.