Stammdaten¶

Abruf von Mitarbeiter-Stammdaten¶

Erfahren Sie hier, wie Stammdaten von in Planerio angelegten Mitarbeitern automatisiert oder manuell abgerufen werden kann. Im Abschnitt Konfiguration haben Sie sogenannte „Schichtgruppen-Token“ als Zugänge zu den Daten in Planerio erstellt, diese werden nun benötigt. Die URL zum Datenabruf lautet:

https://<host>/integrations/tokenapi/v2/aaa-bbb-ccc/employees

Anstelle von aaa-bbb-ccc ist das entsprechende Schichtgruppen-Token einzusetzen. Weiterhin ist es möglich, den Datenabruf wie folgt zu parametrisieren. Der erste Parameter muss dabei mit einem ? eingeleitet werden, alle folgenden mit einem &.

Folgende Daten sind in der Antwort enthalten (jeweils pro Mitarbeiter):

Import von Mitarbeiter-Stammdaten¶

Die Schnittstelle zum Benutzerdatenimport ermöglicht es, Mitarbeiterstammdaten aus Drittsystemen nach Planerio zu übertragen.

Konfiguration¶

Die Konfiguration der Schnittstelle muss durch Planerio vorgenommen werden. Bitte wenden Sie sich für weitere Informationen an Ihren Account Manager.

Wichtig ist, dass in Planerio unter Admin -> Abteilung max. 1 Abteilung angelegt ist. Andernfalls funktioniert die initiale, einmalige Zuordnungen zu den Schichtgruppen nicht.

Datenfluss¶

Es bestehen drei Möglichkeiten zur Übertragung von Mitarbeiterstammdaten aus Drittsystemen nach Planerio:

• Push-basiert. Hierbei übermittelt das Drittsystem einzelne oder mehrere Mitarbeiterdatensätze mittels HTTPS. Dies ermöglicht eine Synchronisation in Echtzeit.
• Pull-basiert. Hierbei ruft Planerio in regelmäßigen Intervallen Mitarbeiterdatensätze aus dem Drittsystem über eine HTTPS-Schnittstelle ab.
• Pull-basiert im Batch-Modus. Hierbei ruft Planerio in regelmäßigen Intervallen (meistens 1/Tag) die Mitarbeiterdatensätze für alle Mitarbeiter aus dem Drittsystem ab. Die Übertragung erfolgt hier in der Regel über SFTP mit CSV-Dateien o.ä.

In allen drei Fällen wird das Drittsystem zum „Master“, also zum primären System der konfigurierten Felder. Die Felder können anschließend in Planerio nicht mehr modifiziert werden.

Datenstruktur¶

Die aktuelle technische Beschreibung der Datenstruktur können Sie jederzeit über folgenden Link abrufen:

https://schemas.planerio-ops.de/MasterDataSource/UserImportSchema/index.html

Das zugrunde liegende JSON-Schema können Sie hier herunterladen:

https://schemas.planerio-ops.de/MasterDataSource/UserImportSchema/schema.zip

Weitere Informationen zu verfügbaren Feldern¶

Bitte entnehmen Sie die aktuelle Feldliste inklusive Typen, Formaten und der Angabe, ob ein Feld optional ist, dem oben stehenden Link. Unten finden Sie weitere Informationen zu ausgewählten Feldern.

Basis-Informationen¶

Beispiel-Struktur für vacationBudgetOverride:

[
  {
    "year": 2023,
    "days": 26.5,
    "expiryDate": null,
    "updatedAt": "2023-03-13T17:17:17+01:00"
  }
]

Beispiel-Struktur für workSchedule:

[
  {
    "validFrom": "2013-07-01",
    "weeklyDays": 4,
    "weeklyHours": 32,
    "jobTitle": "MTRA",
    "customPayrollFields": {
      "accountingSubUnit": "Accounting Sub Unit",
      "contractNumber": "Contract Number",
      "individualTenantNumber": "Individual Number"
    }
  }
]

Zuordnung von Nutzern aus dem Drittsystem und Planerio¶

Beim Import wird anhand folgender Kriterien in dieser Reihenfolge versucht, einen existierenden Mitarbeiter in Planerio zu finden. Gibt es einen Treffer, wird der Mitarbeiter anhand der Daten aus dem Import aktualisiert. Andernfalls wird ein neuer Mitarbeiter angelegt.

• uniqueId (sofern angegeben, siehe oben) aus derselben Quelle
• Suche nach Benutzername
• Suche nach E-Mail-Adresse

Für Schritte 2+3: Falls der „globale Modus“ aktiv ist wird über alle Accounts hinweg gesucht. Andernfalls (der Normalfall) nur innerhalb desselben Accounts. Der „globale Modus“ bezieht sich NUR auf Installationen, in denen das Feld „planerioAccountId“ und der unter Verfügbare Accounts für Import abrufen beschriebene „availableAccounts“-Endpunkt genutzt wird.

Push-Datenfluss – Authentifizierung¶

Als Grundvoraussetzung benötigen Sie ein technisches Login, bestehend aus Benutzername und Passwort, sowie den ermittelten Platzhalter <host>. Mit diesen technischen Zugangsdaten können Sie ein Session Token abrufen, wie in der generellen Dokumentation beschrieben.

Push-Datenfluss – Endpunkte¶

Benutzer importieren (anlegen + aktualisieren)¶

PUT https://<host>/integrations/v1/import/user
X-Planerio-API-Gateway-Auth: SESSIONTOKEN

Status-Code im Erfolgsfall: 204

Request-Aufbau: gemäß UserContainerDTO-Schema (siehe oben).

Verfügbare Accounts für Import abrufen¶

Dieser Endpunkt ist nur relevant, falls Sie mehrere getrennte Kunden-Accounts in Planerio mit Daten versorgen möchten. Bitte halten Sie hierzu Rücksprache mit unserem Account- oder Projekt-Manager.

GET https://<host>/integrations/v1/import/availableAccounts
X-Planerio-API-Gateway-Auth: SESSIONTOKEN

Beispiel-Antwort:

[
  {
    "id": "DUMMY-0001",
    "description": "Ärzte"
  },
  {
    "id": "DUMMY-0007",
    "description": "Verwaltung"
  }
]

Die id aus dieser Antwort kann anschließend beim Push (PUT import/user-Endpunkt) im Feld planerioAccountId genutzt werden, um neu importierte Benutzer einem gewünschten Account zuzuordnen.

Urlaubsbudgetkonfigurationen¶

Um die vacationBudgetConfigurationId für einen Mitarbeiter verwenden zu können, müssen wir zuvor die Urlaubsbudgetkonfiguration in Planerio gespeichert haben, bevor sie verwendet werden kann. Sie kann über eine HTTPS-Anfrage an den Planerio-Server gespeichert werden.

PUT https://<host>/integrations/tokenapi/v2/{token}/absences/vacation-budget-configuration

{
  "budgetId": "unique-sap-identifier",
  "budgetName": "Planerio München 28 Tage",
  "budget": 28
}

Es handelt sich um ein „Upsert“, sodass es mit demselben Endpunkt erstellt oder aktualisiert werden kann. Die Aktualisierung wird mit dem Feld budgetId identifiziert.

Pull-Datenflüsse¶

Wie oben beschrieben, besteht auch die Möglichkeit, Mitarbeiterstammdaten zeitgesteuert nach Planerio zu importieren. Es werden dabei folgende Übertragungswege unterstützt:

HTTPS, FTPS, SFTP, S3

Unterstützte Formate sind:

JSON, CSV, XML

Weitere Übertragungswege und Formate können ggf. beauftragt werden. Die in Abschnitt Datenstruktur aufgeführten Datenstrukturen und -Felder definieren auch hier den aktuell implementierten Umfang der Schnittstelle.