OCT-Datenintegration
OCT-Datenintegration
Breadcrumbs

Installationsanleitung gateway.personio

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. Systemvoraussetzungen

1.1. Systemvoraussetzungen Personio API

  • Einrichtung einer API-Integration in Personio um die API-Zugangsdaten zu erhalten (Anleitung: Einrichtung der API-Zugangsdaten in Personio )

  • Das Gateway benötigt die Client-ID und das Client-Secret mit den passenden Zugriffsrechten auf die benötigten API-Endpunkte aus Schritt 1.

1.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.

2. Technische Einrichtung

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

2.1.1. Zusätzliche Voraussetzungen:

  • Azure Storage Account mit Kontoname und Zugriffsschlüssel (Access Key)

2.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 Releaseordner “Gateway_Personio_v1.1.2” 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

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.1.2/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

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

3.2.1. Zusätzliche Voraussetzungen:

3.2.2. Installationsanleitung:

Schritt A

Datei entpacken

  • den Releaseordner “Gateway_Personio_v1.1.2.zip” aus dem internen Bereich herunterladen, und nach C:\ProgramData\Saxess Software\ entpacken

Schritt B

Pythonpakete installieren

  • im Ordner Gateway_Personio_v.1.1.2 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.1.2/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.1.2” 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

4. Konfigurationsoptionen in der config.json Datei

4.1. Auswahl der abzurufenden Tabellen über Aktivierung der API - Endpunkte

Folgende Personio API V1 Endpunkte können im Bereich “api_endpunkte” aktiviert werden. Die Inhalte der Endpunkte lassen sich im Detail im Personio Developer Hub nachlesen.

Folgende Personio API v2 Endpunkte können unter “api_endpunkte” eingetragen werden. Die Inhalte lassen sich im Detail im Personio Developer Hub nachlesen.

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

4.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"
}

4.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.