Stammdaten¶

Abruf von Mitarbeiter-Stammdaten¶

Über diesen Endpunkt können Sie die Stammdaten der in Planerio angelegten Mitarbeiter automatisiert oder manuell abrufen. Dafür benötigen Sie ein im Abschnitt Konfiguration erstelltes Schichtgruppen-Token. Die URL zum Datenabruf lautet:

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

Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token. Sie können den Datenabruf mit den folgenden Query-Parametern konfigurieren. Leiten Sie den ersten Parameter mit ? und alle weiteren Parameter mit & ein.

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.

In Planerio darf unter Admin → Abteilung höchstens eine Abteilung angelegt sein. Andernfalls funktioniert die einmalige initiale Zuordnung zu den Schichtgruppen nicht.

Datenfluss¶

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

• Push-basiert: Das Drittsystem übermittelt einzelne oder mehrere Mitarbeiterdatensätze per HTTPS. Dies ermöglicht eine Synchronisation in Echtzeit.
• Pull-basiert: Planerio ruft Mitarbeiterdatensätze in regelmäßigen Intervallen über eine HTTPS-Schnittstelle aus dem Drittsystem ab.
• Pull-basiert im Batch-Modus: Planerio ruft in regelmäßigen Intervallen, meist einmal täglich, die Datensätze aller Mitarbeiter aus dem Drittsystem ab. Die Übertragung erfolgt in der Regel per SFTP, beispielsweise mit CSV-Dateien.

In allen drei Fällen ist das Drittsystem das führende System („Master“) für die konfigurierten Felder. Diese Felder können anschließend nicht mehr in Planerio geändert 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.

Basisinformationen¶

Beispiel-Struktur für vacationBudgetOverride:

[
  {
    "year": 2023,
    "budgetDays": 26.5,
    "expiryDate": null
  }
]

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 Benutzern aus dem Drittsystem zu 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 aus derselben Quelle (sofern angegeben; siehe oben)
• Suche nach Benutzername
• Suche nach E-Mail-Adresse

Für die Schritte 2 und 3 gilt: Im „globalen Modus“ sucht Planerio accountübergreifend. Im Normalfall beschränkt sich die Suche auf denselben Account. Der globale Modus betrifft ausschließlich Installationen, die das Feld planerioAccountId und den unter Verfügbare Accounts für Import abrufen beschriebenen Endpunkt availableAccounts verwenden.

Push-Datenfluss – Authentifizierung¶

Sie benötigen ein technisches Login aus Benutzername und Passwort sowie den zuvor ermittelten Wert für <host>. Mit diesen Zugangsdaten können Sie wie in der allgemeinen Dokumentation beschrieben ein Session-Token abrufen.

Push-Datenfluss – Endpunkte¶

Benutzer importieren (anlegen und aktualisieren)¶

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

HTTP-Status-Code im Erfolgsfall: 204

Aufbau des Requests: gemäß dem oben verlinkten UserContainerDTO-Schema.

Verfügbare Accounts für Import abrufen¶

Dieser Endpunkt ist nur relevant, wenn Sie mehrere getrennte Kunden-Accounts in Planerio mit Daten versorgen möchten. Stimmen Sie die Verwendung bitte mit Ihrem Account- oder Projektmanager ab.

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"
  }
]

Mit der id aus dieser Antwort können Sie anschließend beim Push über den PUT-Endpunkt import/user im Feld planerioAccountId festlegen, welchem Account neue Benutzer zugeordnet werden.

Urlaubsbudgetkonfigurationen¶

Bevor Sie eine vacationBudgetConfigurationId für einen Mitarbeiter verwenden können, müssen Sie die zugehörige Urlaubsbudgetkonfiguration in Planerio speichern. Senden Sie dazu einen HTTPS-Request an den folgenden Endpunkt:

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

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

Der Endpunkt führt ein Upsert aus: Er erstellt eine neue Konfiguration oder aktualisiert eine vorhandene Konfiguration. Das Feld budgetId dient dabei als eindeutiger Bezeichner.

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 gegebenenfalls beauftragt werden. Die im Abschnitt Datenstruktur beschriebenen Datenstrukturen und Felder definieren auch für Pull-Datenflüsse den aktuell unterstützten Umfang der Schnittstelle.