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 |
Erfahren Sie hier, wie sie in Planerio gepflegten Schichtpläne automatisiert abrufen können. 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>/planerio/planning/shifts/api/external/aaa-bbb-ccc/shifts
Anstelle von aaa-bbb-ccc ist das entsprechende Schichtgruppen-Token einzusetzen. Weiterhin ist es nötig, den Datenabruf wie folgt zu parametrisieren. Hängen Sie folgende Parameter an. Der erste Parameter muss dabei mit einem ? eingeleitet werden, alle folgenden mit einem & (vgl. Beispiel weiter unten).
| Parameter | Beschreibung |
|---|---|
| startDate=2020-07-01 | Dieser Parameter definiert den Beginn des Zeitraums, für den die Schichten abgerufen werden sollen. Das Datum muss dabei im Format YYYY-MM-DD, also z.B. 2020-12-31 für den 31. Dezember 2020, angegeben werden. Das Jahr muss im Bereich 2000-2099 liegen. |
| endDate=2020-08-01 | Dieser Parameter definiert das Ende des Zeitraums, für den Schichten abgerufen werden sollen. |
| format=xls | Dieser Parameter legt das Format der exportieren Daten fest. Verfügbar sind: xls (Excel-Datei), csv (Textdatei) und json (Standard). |
Optional stehen weiterhin folgende Parameter zur Verfügung:
| Parameter | Beschreibung |
|---|---|
| updatedAfter=2020-07-01 | Mit diesem Parameter können die Schichten auf solche eingeschränkt werden, die sich nach einem Stichtag geändert haben. Dies ist nützlich für Differenzbetrachtungen. Das Datum ist als YYYY-MM-DD zu formatieren. |
| includeEditing=1 | Standardmäßig werden nur Schichten aus veröffentlichten Schichtplänen abgerufen. Mit diesem Parameter können Sie auch Schichten aus Plänen, die sich noch im Status Entwurf befinden, einschließen. |
| includeDeleted=1 | Gelöschte Schichten werden standardmäßig nicht zurückgegeben. Falls Sie diese benötigen, können Sie sie über den angegebenen Parameter in das Ergebnis einschließen. |
| returnShiftComments=1 | Falls Sie an den Freitext-Kommentaren zu Schichten interessiert sind, setzen Sie diesen Parameter. Dies kann die Datenmenge erhöhen und die Antwortzeit des Endpunktes negativ beeinträchtigen. |
| sortResult=1 | Standardmäßig wird das Ergebnis nicht sortiert. Mit diesem Parameter ist es möglich, eine Sortierung gemäß folgender Priorisierung zu erzwingen: Schichtgruppe, Nachname, Vorname, Startzeit, Endzeit, letzte Änderung |
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 | (nur wenn Parameter includeDeleted gesetzt) Falls Schicht gelöscht, Zeitpunkt der Löschung im Format YYYY-MM-DD HH:MM:SS |
| is_virtual | Hat den Wert 1 falls es sich um eine sog. virtuelle Schicht handelt |
| flag_color | Benutzerdefinierter Namen für die 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 | Falls der Mitarbeiter über einen Import (vgl. separate Doku „Schnittstelle_Mitarbeiterdatenimport“) angelegt wurde, ist hier die uniqueId zur Identifizierung des MA im externen System enthalten. |
| is_external_user | true/false – ob das Freitextfeld „externer Mitarbeiter“ genutzt wird. Hat nichts mit user_external_id zu tun! |
| external_user_name | Falls das Freitextfeld „externer Mitarbeiter“ genutzt wird, ist der entsprechende Name hier enhalten. Hat nichts mit user_external_id zu tun! |
| 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 | (nur wenn Parameter returnShiftComments gesetzt) - Kommentar(e) zu dieser Schicht |
| location_id | Eindeutiger Bezeichner des Standortes des Arbeitsplatzes dieser Schicht |
| location_name | Benutzerdefinierter Namen des Standortes des Arbeitsplatzes dieser Schicht |
| tags | Tags/Kennzeichen. Diese kommen aktuell vom Arbeitsplatz dieser Schicht, sofern vorhanden. Mehrere sind durch , 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 |
Erfahren Sie hier, wie der aktuelle Personalbedarf aus den Schichtkarten 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>/planerio/planning/planning-configuration/api/external/aaa-bbb-ccc/shiftCards
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 &.
| Parameter | Beschreibung |
|---|---|
| startDate=2024-12-31 | Dieser Parameter filtert die Schichtkarten aus, die am angegebenen Datum nicht mehr gültig waren. Maßgeblich sind hier die (optionalen) Felder valid_from und valid_to der jeweiligen Schichtkarte. Beispiel: Eine Schichtkarte ohne das Feld valid_to aber mit dem Feld valid_from = 2024-12-31 ist ab dem 31.12.2024 unbegrenzt gültig, und ist somit für den beispielhaften Parameter in der Serverantwort enthalten. |
| endDate=2025-02-29 | Dieser Parameter filtert die Schichtkarten aus, die am angegebenen Datum noch nicht gültig waren. |
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 | (innerhalb workplace): eindeutige ID des Arbeitsplatzes |
| name | (innerhalb workplace): Name des Arbeitsplatzes |
| location | Name des Standortes |
| shift_group | Schichtgruppe |
| internal_id | (innerhalb shift_group): eindeutige ID der Schichtgruppe |
| name | (innerhalb shift_group): Name der Schichtgruppe |
| 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 | Regelung für Feiertage: NOT_ON_PUBLIC_HOLIDAYS/ IGNORE_PUBLIC_HOLIDAYS/ADDITIONAL_ON_PUBLIC_HOLIDAYS / 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/ON_CALL |
| automatically_planned | Wird die Schicht/werden die Schichten automatisch geplant? true/false |
| shift_end_day | Tag an dem die Schicht endet: SAME_DAY/ONE_DAY_AFTER/TWO_DAYS_AFTER |
| shift_details | Liste der n Schichten zur Schichtkarte (n>=1), mit Angaben zu jeder Schicht |
Aus 1 Schichtkarte werden je 1 oder mehrere (bis zu 10) Schichten erzeugt, an jeweils gleichem Datum und Uhrzeit. Detailinformationen zu jeder dieser Schichten sind in den Elementen innerhalb der Liste shift_details beschrieben. Die Objekte in dieser Liste haben die folgenden Felder:
| Feldname | Beschreibung |
|---|---|
| assignment_priority | Format VERY_HIGH/HIGH/NORMAL/LOW/VERY_LOW |
| preplanned_employee | Vorgeplanter Mitarbeiter |
| uuid | (innerhalb preplanned_employee): Planerio-systemweit eindeutige ID des vorgeplanten Mitarbeiters; entspricht employee_uuid in anderen Schnittstellen. |
| last_name | (innerhalb preplanned_employee): Nachname des vorgeplanten Mitarbeiters |
| first_name | (innerhalb preplanned_employee): Vorname des vorgeplanten Mitarbeiters |
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 |
Erfahren Sie hier, wie der aktuelle Personalstand 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.
️ Diese Funktion darf ausschließlich in Kombination mit dem Abruf des Personalbedarfs (vorheriger Abschnitt) genutzt werden. Um reine Mitarbeiterstammdaten abzurufen, nutzen Sie bitte nur den in Abschnitt 2.5.1 beschriebenen Endpunkt.
Die URL zum Datenabruf lautet:
https://<host>/integrations/tokenapi/v2/aaa-bbb-ccc/resourcePlanning/staff
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 &.
| Parameter | Beschreibung |
|---|---|
| format=xls | Dieser Parameter legt das Format der exportieren Daten fest. 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 | (Benutzte) Qualifikationen, durch ; 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 |