Planung¶
Abruf von Schichten¶
| Information | Wert |
|---|---|
| Verfügbar in Planerio-Versionen | 1.5 / 2.0 |
| Verfügbar über Technisches Login | ja |
| Verfügbar über Browser | nein |
| Endpunkt-Pfad | /planerio/planning/shifts/api/external/aaa-bbb-ccc/shifts |
Über diesen Endpunkt können Sie in Planerio gepflegte Schichtpläne automatisiert abrufen. Dafür benötigen Sie ein im Abschnitt Konfiguration erstelltes Schichtgruppen-Token. Die URL zum Datenabruf lautet:
https://<host>/planerio/planning/shifts/api/external/aaa-bbb-ccc/shifts
Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token und hängen Sie die folgenden Query-Parameter an. Leiten Sie den ersten Parameter mit ? und alle weiteren Parameter mit & ein (siehe Beispiel unten).
| Parameter | Beschreibung |
|---|---|
| startDate=2020-07-01 | Beginn des Zeitraums, für den Schichten abgerufen werden. Geben Sie das Datum im Format YYYY-MM-DD an, z. B. 2020-12-31 für den 31. Dezember 2020. Das Jahr muss zwischen 2000 und 2099 liegen. |
| endDate=2020-08-01 | Ende des Zeitraums, für den Schichten abgerufen werden. |
| format=xls | Format der exportierten Daten. Verfügbar sind xls (Excel-Datei), csv (Textdatei) und json (Standard). |
Zusätzlich stehen folgende optionale Parameter zur Verfügung:
| Parameter | Beschreibung |
|---|---|
| updatedAfter=2020-07-01 | Beschränkt das Ergebnis auf Schichten, die nach einem Stichtag geändert wurden. Dies eignet sich für differenzielle Synchronisierungen. Geben Sie das Datum im Format YYYY-MM-DD an. |
| includeEditing=1 | Schließt Schichten aus Schichtplänen mit dem Status „Entwurf“ ein. Standardmäßig werden nur Schichten aus veröffentlichten Plänen zurückgegeben. |
| includeDeleted=1 | Schließt gelöschte Schichten ein. Standardmäßig werden sie nicht zurückgegeben. |
| returnShiftComments=1 | Schließt Freitextkommentare zu Schichten ein. Dies kann die Datenmenge erhöhen und die Antwortzeit verlängern. |
| sortResults=1 | Sortiert das Ergebnis in dieser Reihenfolge: Schichtgruppe, Nachname, Vorname, Startzeit, Endzeit, letzte Änderung. Standardmäßig ist das Ergebnis unsortiert. |
Folgende Daten sind in der Antwort enthalten (jeweils ein Datensatz/Zeile pro Schicht):
| Feldname | Beschreibung |
|---|---|
| shift_id | Eindeutiger Bezeichner für diese Schicht |
| shift_start_date_time | Startzeit der Schicht im Format YYYY-MM-DD HH:MM:SS |
| shift_end_date_time | Endzeit der Schicht im Format YYYY-MM-DD HH:MM:SS |
| shift_updated_at | Letzte Änderung an dieser Schicht im Format YYYY-MM-DD HH:MM:SS |
| shift_deleted_at | Zeitpunkt der Löschung im Format YYYY-MM-DD HH:MM:SS (nur wenn includeDeleted gesetzt und die Schicht gelöscht ist) |
| is_virtual | 1, wenn es sich um eine virtuelle Schicht handelt |
| flag_color | Benutzerdefinierter Name der Farbe dieser Schicht |
| user_lastname | Nachname des zugewiesenen Mitarbeiters |
| user_firstname | Vorname des zugewiesenen Mitarbeiters |
| user_title | Titel oder akademischer Grad des eingeteilten Mitarbeiters |
| user_cost_center | Kostenstelle des zugewiesenen Mitarbeiters |
| user_personnel_number | Personalnummer des zugewiesenen Mitarbeiters |
| employee_uuid | Planerio-systemweit eindeutige ID des eingeteilten Mitarbeiters |
| user_external_id | Wurde der Mitarbeiter über einen Import angelegt, enthält dieses Feld die uniqueId, die ihn im externen System identifiziert. |
| is_external_user | true oder false: Gibt an, ob das Freitextfeld „Externer Mitarbeiter“ verwendet wird. Das Feld steht nicht in Zusammenhang mit user_external_id. |
| external_user_name | Name aus dem Freitextfeld „Externer Mitarbeiter“, sofern verwendet. Das Feld steht nicht in Zusammenhang mit user_external_id. |
| shift_group_id | Eindeutiger Bezeichner der Schichtgruppe dieser Schicht |
| shift_group_name | Name der Schichtgruppe dieser Schicht |
| workplace_id | Eindeutiger Bezeichner des Arbeitsplatzes dieser Schicht |
| workplace_description | Name des Arbeitsplatzes dieser Schicht |
| workplace_cost_center | Kostenstelle des Arbeitsplatzes dieser Schicht |
| shift_comment | Kommentare zu dieser Schicht (nur wenn returnShiftComments gesetzt ist) |
| location_id | Eindeutiger Bezeichner des Standortes des Arbeitsplatzes dieser Schicht |
| location_name | Benutzerdefinierter Name des Standorts des Arbeitsplatzes dieser Schicht |
| tags | Tags beziehungsweise Kennzeichen des Arbeitsplatzes, sofern vorhanden. Mehrere Werte sind durch Kommas getrennt. |
Abruf des aktuellen Personalbedarfs¶
| Information | Wert |
|---|---|
| Verfügbar in Planerio-Versionen | 1.5 / 2.0 |
| Verfügbar über Technisches Login | ja |
| Verfügbar über Browser | nein |
| Endpunkt-Pfad | /planerio/planning/planning-configuration/api/external/aaa-bbb-ccc/shiftCards |
Über diesen Endpunkt können Sie den in Schichtkarten definierten Personalbedarf automatisiert oder manuell abrufen. Dafür benötigen Sie ein im Abschnitt Konfiguration erstelltes Schichtgruppen-Token. Die URL zum Datenabruf lautet:
https://<host>/planerio/planning/planning-configuration/api/external/aaa-bbb-ccc/shiftCards
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.
| Parameter | Beschreibung |
|---|---|
| startDate=2024-12-31 | Schließt Schichtkarten aus, deren Gültigkeit vor dem angegebenen Datum endete. Maßgeblich sind die optionalen Felder valid_from und valid_to. Beispiel: Eine Schichtkarte mit valid_from=2024-12-31 und ohne valid_to gilt ab dem 31. Dezember 2024 unbefristet und ist daher in der Antwort enthalten. |
| endDate=2025-02-28 | Schließt Schichtkarten aus, deren Gültigkeit erst nach dem angegebenen Datum beginnt. |
Die Daten werden im JSON-Format zurückgegeben. Folgende Daten sind enthalten (jeweils pro Schichtkarte):
| Feldname | Beschreibung |
|---|---|
| uuid | Eindeutige ID der Schichtkarte |
| company | Firmenname |
| workplace | Arbeitsplatz |
| id | Eindeutige ID des Arbeitsplatzes (innerhalb von workplace) |
| name | Name des Arbeitsplatzes (innerhalb von workplace) |
| location | Name des Standortes |
| shift_group | Schichtgruppe |
| internal_id | Eindeutige ID der Schichtgruppe (innerhalb von shift_group) |
| name | Name der Schichtgruppe (innerhalb von shift_group) |
| valid_from | Beginn der Gültigkeit (YYYY-MM-DD) |
| valid_to | Ende der Gültigkeit (YYYY-MM-DD) |
| qualifications | Liste der erforderlichen Qualifikationen |
| days_of_week | Liste der Wochentage: Mon, Tue, Wed, Thu, Fri, Sat, Sun |
| public_holiday_policy | Feiertagsregelung: NOT_ON_PUBLIC_HOLIDAYS, IGNORE_PUBLIC_HOLIDAYS, ADDITIONAL_ON_PUBLIC_HOLIDAYS oder ONLY_ON_PUBLIC_HOLIDAYS |
| week_cycle | Länge des Wochenzyklus |
| time_begin | Format HH:MM |
| time_end | Format HH:MM |
| shift_type | Typ der Schicht: NORMAL, VIRTUAL oder ON_CALL |
| automatically_planned | true oder false: Gibt an, ob die Schichten automatisch geplant werden. |
| shift_end_day | Tag, an dem die Schicht endet: SAME_DAY, ONE_DAY_AFTER oder TWO_DAYS_AFTER |
| shift_details | Liste der Schichten dieser Schichtkarte (n >= 1) mit Angaben zu jeder Schicht |
Aus einer Schichtkarte werden eine bis zehn Schichten mit jeweils gleichem Datum und gleicher Uhrzeit erzeugt. Die Liste shift_details enthält die Detailinformationen zu diesen Schichten. Jedes Objekt in der Liste hat die folgenden Felder:
| Feldname | Beschreibung |
|---|---|
| assignment_priority | Priorität: VERY_HIGH, HIGH, NORMAL, LOW oder VERY_LOW |
| preplanned_employee | Vorgeplanter Mitarbeiter |
| uuid | Planerio-systemweit eindeutige ID des vorgeplanten Mitarbeiters (innerhalb von preplanned_employee); entspricht employee_uuid in anderen Schnittstellen |
| last_name | Nachname des vorgeplanten Mitarbeiters (innerhalb von preplanned_employee) |
| first_name | Vorname des vorgeplanten Mitarbeiters (innerhalb von preplanned_employee) |
Abruf des aktuellen Personalangebotes¶
| Information | Wert |
|---|---|
| Verfügbar in Planerio-Versionen | 1.5 / 2.0 |
| Verfügbar über Technisches Login | ja |
| Verfügbar über Browser | ja |
| Endpunkt-Pfad | /integrations/tokenapi/v2/aaa-bbb-ccc/resourcePlanning/staff |
Über diesen Endpunkt können Sie das aktuelle Personalangebot automatisiert oder manuell abrufen. Dafür benötigen Sie ein im Abschnitt Konfiguration erstelltes Schichtgruppen-Token.
Verwenden Sie diesen Endpunkt ausschließlich zusammen mit dem im vorherigen Abschnitt beschriebenen Abruf des Personalbedarfs. Verwenden Sie für reine Mitarbeiterstammdaten den Endpunkt „Abruf von Mitarbeiter-Stammdaten“.
Die URL zum Datenabruf lautet:
https://<host>/integrations/tokenapi/v2/aaa-bbb-ccc/resourcePlanning/staff
Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token. Sie können den Datenabruf mit dem folgenden Query-Parameter konfigurieren. Leiten Sie den ersten Parameter mit ? ein.
| Parameter | Beschreibung |
|---|---|
| format=xls | Format der exportierten Daten. Verfügbar sind xls (Excel-Datei), csv (Textdatei) und json (Standard). |
Folgende Daten sind enthalten (jeweils pro Mitarbeiter):
| Feldname | Beschreibung |
|---|---|
| company | Firmenname |
| last_name | Nachname |
| first_name | Vorname |
| personnel_number | Personalnummer |
| shift_group | Name der primären Schichtgruppe |
| qualifications | Verwendete Qualifikationen, durch Semikolons getrennt |
| weekly_hours | Wochenstunden (sofern gepflegt) |
| weekly_days | Arbeitstage pro Woche (sofern gepflegt) |
| hours_(mon|tue|wed|thu|fri|sat|sun) | Arbeitsstunden pro Wochentag (sofern fix) |
| entry_date | Eintrittsdatum im Format YYYY-MM-DD; 2000-01-01, falls nicht gepflegt |
| exit_date | Austrittsdatum (sofern gepflegt) |
| employee_uuid | Planerio-systemweit eindeutige ID des Mitarbeiters |
| tenant_number | Mandantennummer des Mitarbeiters (sofern vorhanden) |
| display_name | Anzeigename des Mitarbeiters |
| occupational_category | Berufsgruppe des Mitarbeiters |
| ~~vacation_days_yearly~~ | Nicht verwenden. Das Feld enthält keine verwertbaren Werte und wird entfernt. |