Dieser Artikel enthält alle notwendigen Informationen für Personio-Kunden, die am Beta-Test der neuen API für benutzerdefinierte Berichte teilnehmen. Vielen Dank für Ihre Teilnahme an diesem Beta-Test.
Ablauf des Beta-Tests
Der geplante zeitliche Ablauf des Beta-Tests sieht so aus:
|
Zeit |
Beschreibung |
|
KW 34 |
Beginn der Beta-Phase: Die u.g. Funktionalitäten werden in Ihrem Personio-Konto freigeschaltet. |
|
KW 38 |
Global Release: Die unten aufgeführten Funktionalitäten sind für alle Kunden verfügbar. |
Umfang des Beta-Tests
Folgende Funktionen sind in der aktuellen Beta-Phase verfügbar:
- Endpunkt zum Abruf einer Liste vorhandener benutzerdefinierter Berichte:
Dieser Endpunkt stellt Ihnen Metadaten zu vorhandenen benutzerdefinierten Berichten in Ihrem Personio-Konto zur Verfügung, z.B. Berichtsname, Berichtstyp, Berichtsdatum/Zeitraum. - Endpunkt zum Abruf einer Liste von Spalten-/Attributdefinitionen:
Dieser Endpunkt liefert Attributnamen und -Übersetzungen der verfügbaren Spalten. Er ist besonders wichtig, wenn Sie einen Bericht mit benutzerdefinierten Attributen oder Abwesenheitsdaten erhalten, da Sie die IDs der Attribute der Übersetzung zuordnen müssen. - Endpunkt zum Abruf von Berichtsdaten eines vorhandenen benutzerdefinierten Berichts:
Dieser Endpunkt stellt Ihnen die Daten in einem vorhandenen benutzerdefinierten Bericht im JSON-Format zur Verfügung.
Um den Endpunkt Benutzerdefinierte Berichte nutzen zu können, generieren Sie Zugriffsdaten oder aktivieren Sie den Endpunkt Lesen für ein vorhandenes Paar Zugriffsdaten. Ein Write Endpunkt ist derzeit nicht implementiert.
Hinweis
Wenn der Read-Endpunkt aktiviert ist, können alle vorhandenen Berichte abgerufen werden. Außerdem bleibt der Bereich Lesbare Mitarbeiterattribute für die Mitarbeiterdaten-API für den Endpunkt Benutzerdefinierte Berichte unberücksichtigt. Alle Attribute, die einem benutzerdefinierten Bericht hinzugefügt wurden, können über den Endpunkt abgerufen werden, wenn er für die entsprechenden Zugriffsdaten aktiviert ist, unabhängig davon, ob das Attribut auf der Whitelist steht oder nicht.
API-Zugriff und Autorisierung
Ausführliche Informationen zum allgemeinen Zugriff und zur Autorisierung finden Sie im Personio Developer Hub.
Endpunkte für Benutzerdefinierte Berichte
Um die Endpunkte Benutzerdefinierte Berichte nutzen zu können, müssen Sie API-Zugriffsdaten generieren (client_id und client_secret). Führen Sie dazu die folgenden Schritte aus:
- Wählen Sie die Option Neue Zugriffsdaten generieren.
- Aktivieren Sie die Option Lesen für Benutzerdefinierte Berichte. Sie können auch den Read-Endpunkt Benutzerdefinierte Berichte für ein bereits vorhandenes Paar Zugriffsdaten aktivieren.
Die API für benutzerdefinierte Berichte ermöglicht es Ihnen, alle Zeilen und Felder eines benutzerdefinierten Berichts für die weitere Analyse oder Verwendung im JSON-Format abzurufen. Die API lässt es derzeit nicht zu, vorhandene Berichte zu erstellen oder zu aktualisieren.
Ein gängiger Anwendungsfall für die API für benutzerdefinierte Berichte ist der Export von Daten aus einem benutzerdefinierten Bericht in Personio in andere Systeme, z. B. ein BI-Tool oder ein Data Warehouse.
Beachten Sie bei der Verwendung der API für benutzerdefinierte Berichte bitte die folgenden Punkte:
Große Datensätze oder lange Zeiträume
Bei Berichten, die eine große Anzahl von Mitarbeitern enthalten oder sich über lange Zeiträume erstrecken, wird empfohlen, zunächst den Endpunkt GetReports abzufragen, um den Zeitstempel data_refreshed_at für den betreffenden Bericht abzurufen. Dies muss geschehen, bevor der Inhalt des Berichts mithilfe des Endpunkts GetReportData abgerufen wird, um sicherzustellen, dass seit der letzten Datenaktualisierung ein ausreichender Zeitraum verstrichen ist.
Benutzerdefinierte Attribute
Benutzerdefinierte Mitarbeiterattribute haben eine Attributs-ID, die mit dem Präfix dynamic_ beginnt, das beim Abrufen von Berichtsinhalten über den Endpunkt GetReportData bereitgestellt wird. Um den lesbaren Namen des Attributs abzurufen, muss zuerst der Endpunkt GetColumns verwendet werden, der es ermöglicht, die Attributs-ID mit ihrem lesbaren Namen in Bezug zu setzen. Namen für andere Sprachen können abgerufen werden, indem Sie ?locale=<2-stelliger Sprachen-Code> an den Endpunkt GetColumns anhängen, z. B. .../columns? locale=DE.
Endpunkt GetReports
HTTP-Methode – GET
https://api.personio.de/v1/company/custom-reports/reportsDieser Endpunkt dient dazu, die Liste der vorhandenen benutzerdefinierten Berichte in Ihrem Konto abzurufen. Bitte beachten Sie, dass Sie nur Berichte abrufen können, die bereits in der Personio-Anwendung erstellt wurden.
Beispiel für eine Response{
"success": true,
"metadata": {
"total_elements": 92,
"current_page": 1,
"total_pages": 1
},
"offset": 0,
"limit": 0,
"data": [
{
"type": "Bericht",
"attributes": {
"id": "9f1edbf3-f68e-4f13-83e3-9b1400bacw313",
"name": "Testbericht",
"description": "Das ist eine Beschreibung",
"author_first_name": "Robert",
"author_last_name": "Wilson",
"type": "point_in_time",
"status": "UP_TO_DATE",
"start_date": "2022-07-13",
"end_date": "2022-07-13",
"created_at": "2022-07-11T12:39:05Z",
"updated_at": "2022-07-12T09:45:13Z",
"data_refreshed_at": "2022-07-12T09:45:13Z",
"columns": [
"first_name",
"last_name",
"position",
"team_id",
"department_id",
"fix_salary",
"dynamic_1945114"
],
"filters": [
{
"column": "subcompany_id",
"comparison": "neq",
"value": "7996"
},
{
"column": "subcompany_id",
"comparison": "neq",
"value": "21963"
},
],
"period_type": "heute",
"items": null
}
}
]
}Endpunkt GetColumns
HTTP-Methode – GET
https://api.personio.de/v1/company/custom-reports/columns?locale=de
Dieser Endpunkt dient dazu, eine Liste aller verfügbaren Spalten abzurufen, damit Nutzer die column_id der für Menschen lesbaren Übersetzung zuordnen können.
Beispiel für eine Response{
"success": true,
"metadata": {
"total_elements": 232,
"current_page": 1,
"total_pages": 1
},
"offset": 0,
"limit": 0,
"data": [
{
"type": "Column",
"attributes": {
"id": "id",
"human_readable": "ID",
"data_type": "INTEGER"
}
},
{
"type": "Column",
"attributes": {
"id": "first_name",
"human_readable": "First name",
"data_type": "TEXT"
}
},
{
"type": "Column",
"attributes": {
"id": "last_name",
"human_readable": "Last name",
"data_type": "TEXT"
}
},
{
"type": "Column",
"attributes": {
"id": "email",
"human_readable": "Email",
"data_type": "TEXT"
}
},
{
"type": "Column",
"attributes": {
"id": "dynamic_47589",
"human_readable": "Birthday",
"data_type": "DATE"
}
}
]
}Tipp
Der/die data_type(n) für die Spalte des Endpunkts Benutzerdefinierte Berichte kann/können sich von den data_typen im Mitarbeiter-Endpunkt unterscheiden, damit für Berichtszwecke umfangreichere Daten verfügbar gemacht werden können.
Endpunkt GetReportDataHTTP-Methode – GET
https://api.personio.de/v1/company/custom-reports/reports/{report_id}Dieser Endpunkt dient dazu, die Daten eines vorhandenen benutzerdefinierten Berichts aus Ihrem Konto abzurufen.
Beispiel für eine Response{
"success": true,
"metadata": {
"total_elements": 114,
"current_page": 1,
"total_pages": 1
},
"offset": 0,
"limit": 0,
"data": [
{
"type": "Report",
"attributes": {
"id": "9f1edbf3-f65e-4f13-83e9-9b1400bace13",
"name": "Report Name",
"description": "This is a description",
"author_first_name": "Robert",
"author_last_name": "Wilson",
"type": "point_in_time",
"status": "UP_TO_DATE",
"start_date": "2022-07-12",
"end_date": "2022-07-12",
"created_at": "2022-07-11T12:39:05Z",
"updated_at": "2022-07-12T09:45:13Z",
"data_refreshed_at": "2022-07-12T09:45:13Z",
"columns": [
"first_name",
"last_name",
"position",
"team_id",
"department_id",
"fix_salary",
"dynamic_1945114"
],
"filters": [],
"period_type": "today",
"items": [
{
"employee_id": 1314107,
"attributes": [
{
"attribute_id": "first_name",
"data_type": "TEXT",
"value": "Adella Lena"
},
{
"attribute_id": "last_name",
"data_type": "TEXT",
"value": "Broose-Maier"
},
{
"attribute_id": "position",
"data_type": "TEXT",
"value": "Director Engineering"
},
{
"attribute_id": "team_id",
"data_type": "ENTITY",
"entity_id": "64728",
"value": "Executive Team"
},
{
"attribute_id": "department_id",
"data_type": "ENTITY",
"entity_id": "412781",
"value": "Product & Engineering"
},
{
"attribute_id": "fix_salary",
"data_type": "SALARY",
"amount": "100000.00",
"currency_symbol": "$"
},
{
"attribute_id": "fix_salary_interval",
"data_type": "TEXT",
"value": "yearly"
},
{
"attribute_id": "dynamic_1945114",
"data_type": "OPTION",
"value": "Festanstellung/Permanent position"
}
]
},
{
"employee_id": 2610586,
"attributes": [
{
"attribute_id": "first_name",
"data_type": "TEXT",
"value": "Joline"
},
{
"attribute_id": "last_name",
"data_type": "TEXT",
"value": "Sicha"
},
{
"attribute_id": "position",
"data_type": "TEXT",
"value": "Engineering Manager"
},
{
"attribute_id": "team_id",
"data_type": "ENTITY",
"entity_id": "64938",
"value": "A Team"
},
{
"attribute_id": "department_id",
"data_type": "ENTITY",
"entity_id": "346001",
"value": "Research & Development"
},
{
"attribute_id": "fix_salary",
"data_type": "SALARY",
"amount": "70000.00",
"currency_symbol": "$"
},
{
"attribute_id": "fix_salary_interval",
"data_type": "TEXT",
"value": "yearly"
},
{
"attribute_id": "dynamic_1945114",
"data_type": "OPTION",
"value": "Festanstellung/Permanent position"
}
]
}
]
}
}
]
}Hinweis
Für den Berichtstyp Historische Daten wird die Ausgabe historischer Werte nur mit der employee_id abgeglichen. Vor- und Nachnamen werden nicht ausgegeben. Um die employee_id einem Namen zuordnen zu können, kann der Mitarbeiter-Endpunkt abgerufen werden.Tipp
Weitere Details finden Sie im Dokument openapi.yaml im Download-Beriech dieses Artikels.Feedback
Als Beta-Kunde haben Sie die Möglichkeit, die Peer-Review-Erfahrung für die API für benutzerdefinierte Berichte aktiv mitzugestalten. Die Funktion, die Sie testen, ist noch in einem frühen Entwicklungsstadium. Wir würden gerne hören, was Sie von ihr halten. Je früher wir Ihr Feedback erhalten, desto besser, da wir Ihren Input dann analysieren und für künftige Verbesserungen berücksichtigen können.
Bitte füllen Sie dieses Formular aus, um uns Ihr Feedback mitzuteilen:
Hinweis
Jeder Beta-Tester muss während der Testphase mindestens einmal anhand des folgenden Formulars Feedback abgeben.