--- language: "en" --- # HR Reports API ## Zweck Die HR Reports API stellt HR- und Beschäftigungsdaten für bestehende Reports und Power BI bereit. Sie verwendet die vorhandenen Synapcus-Felder und die bestehende REST-Konvention. Die Dokumentation unterscheidet zwei Reporttypen: * Snapshot- beziehungsweise Actual-Reports: aktueller Datenstand oder ausgewähltes Jahr * History-Reports: historische Zeitreihen über mehrere Monate oder Jahre Beide Reporttypen sollen in Power BI gemeinsam verwendet werden können. Snapshot-Daten beschreiben den aktuellen Stand; History-Daten beschreiben die Entwicklung im Zeitverlauf. ## Allgemeine URL Generisches Synapcus-Schema: >/rest/api Ein REST-Aufruf enthält mindestens: fct= Parameter werden kommasepariert mit params übertragen: ...?fct=¶ms=,,... Beispiel für einen historischen Report: Die tatsächliche Umgebung ersetzt server durch den HTTPS-Host. Die Datenbank bleibt im Schema synapcus.nsf; weitere Datenbank- oder Pfadvarianten sind deploymentspezifisch. Der REST-Dispatcher ruft die angegebene Server-Side-Funktion dynamisch auf. Die params-Werte werden vor dem Aufruf in Kleinbuchstaben umgewandelt. ## Authentifizierung Der API-Key wird nicht als URL-Parameter übertragen. Aktuelle Synforge-Konvention: Accept: application/vnd.collection+json x-api-key: Beispiel: Bash curl \\ -H "Accept: application/vnd.collection+json" \\ -H "x-api-key: " \\ "" Wenn der vorgeschaltete Gateway das Authorization-Schema verwendet: Authorization: Bearer Es ist nur das im jeweiligen Gateway konfigurierte Schema zu verwenden. Der API-Key gehört nicht in Query-String, Log-Ausgabe, M-Code oder Power-BI-Dateien. Die Prüfung kann über Gateway, Reverse Proxy, Domino-Authentifizierung oder ACL erfolgen. Die Report-Funktion muss die Gateway-Authentifizierung nicht selbst implementieren. ## Reporttypen ### Snapshot- und Actual-Reports Snapshot-Reports liefern den Datenstand zum Zeitpunkt des Abrufs oder für einen ausgewählten aktuellen Jahreskontext. Sie eignen sich für: * aktuellen Mitarbeiterstand * aktuelle FTE-Struktur * aktuelle Funktionen und Organisationszuordnung * aktuelle Listen für HR-Reports * Jahresdaten im bestehenden Actual-Kontext Ein bestehender Aufruf ist: QEECompanyCtrl.getActualYearSheetsJSON Dieser wird beispielsweise aus xpHumRes_EmploymentsByName.xsp verwendet. Der Aufruf ist ein Actual-/Snapshot-Report und ersetzt keine historische Monatsreihe. ### History-Reports History-Reports liefern mehrere zeitlich sortierte Zeilen. Die öffentlichen History-Aufrufe sind: fct=getHistoryMoss fct=getHistoryTims `fct` bestimmt die historische Quelle. Deshalb beginnt `params` direkt mit dem Zeitraum; `form=mos` oder `form=tim` wird im Standardaufruf nicht wiederholt: ...?fct=getHistoryMoss¶ms=thisyear ...?fct=getHistoryTims¶ms=thisyear Die erste Datenbasis sind MOS-Monatsblätter. Die MOS-Zeilen werden historisch mit einer kontrollierten Auswahl aus EMP, PER und optional YES angereichert. TIM-Zeilen erhalten ebenfalls nur die für den Report freigegebenen TIM-, PER- und EMP-Felder. History-Reports eignen sich für: * Mitarbeiterstand und FTE-Entwicklung * Soll-, Ist-, Kapazitäts- und Überstundenverläufe * Eintritts- und Austrittsereignisse * historische Team- und Bereichszuordnung * Teilzeit-/Vollzeitentwicklung * Power-BI-Zeitreihen Die vollständige Spezifikation steht auf der Unterseite: [Historisierte MOS-Reports](historisierte-hr-reports-moss.md) [Historisierte TIM-Reports](historisierte-hr-reports-tims.md) ## Gemeinsame Request-Regeln * Die Funktionsauswahl erfolgt über fct. * Funktionsargumente werden in params übergeben. * params ist kommasepariert. * Werte in params dürfen selbst keine unescaped Kommata enthalten. * Der Dispatcher normalisiert params auf Kleinbuchstaben. * UNIDs werden case-insensitiv verarbeitet. * Named Arguments sind bei komplexeren Aufrufen vorzuziehen. * Fachliche Feldnamen bleiben die vorhandenen Synapcus-Namen. * Ein API-Key wird nie in params übertragen. ## Response-Grundformat Der Standard ist: Content-Type: application/vnd.collection+json JSON { "collection": { "version": "1.0", "queries": [], "links": [], "items": [ { "data": [ { "nm": "field_name", "vl": "field_value" } ] } ] } } Bedeutung: * collection.items enthält die Ergebniszeilen. * items\[n\] ist eine fachliche Datenzeile. * data enthält die Felder der Zeile. * nm ist der exakte Synapcus-Feldname. * vl ist der Feldwert. * Die Feldreihenfolge ist nicht relevant. * Leere Werte können als "" geliefert werden. * Explizite Nullwerte können als "0" geliefert werden. Clients dürfen nicht von einer festen Feldreihenfolge ausgehen. Für Power BI wird die Collection-Struktur in eine tabellarische Form transformiert. Optional kann der allgemeine Dispatcher mit responce=dttb eine flache DataTables-Struktur liefern. Der Parametername responce entspricht der bestehenden Implementierung. Der Parameter items wird vom allgemeinen Dispatcher entgegengenommen. Er ist für getHistoryMoss und getHistoryTims keine Feldprojektion; die Feldverträge sind serverseitig explizit definiert. ## Feldkonvention Die API verwendet die vorhandene Form-Präfix-Konvention: mos_* emp_* per_* yes_* Beispiele: mos_ist_hrs emp_brutto_percent per_name yes_emp_unid Synthetische Felder verwenden dieselbe fachliche Namenslogik: emp_fte_percent mos_soll_hrs_fte mos_ist_hrs_percent emp_entry Es werden keine fachlich unabhängigen Ersatznamen wie employeeId, departmentId oder actualHours eingeführt. ## Datenqualität und Aggregation * Snapshot-Daten und History-Daten dürfen nicht ohne Zeitkontext vermischt werden. * History-Zeilen besitzen ihren eigenen MOS-Zeitbezug. * Historische Organisationsfelder sind gegenüber aktuellen Stammdaten vorrangig, wenn eine Zeitreihenanalyse erfolgt. * Bei Mitarbeiterzählungen sind eindeutige Personen oder Beschäftigungen zu berücksichtigen. * Jahreswerte dürfen nicht über wiederholte Monatszeilen summiert werden. * YES-Werte müssen vor einer Aggregation nach Beschäftigung und Jahr dedupliziert werden. * Leere Werte sind fehlende Werte und nicht automatisch Null. * 0 und "0" sind beim Import fachlich gleichwertig zu behandeln. * Originalwerte und synthetische Vergleichswerte sind getrennt zu visualisieren. ## Power-BI-Nutzung ### Snapshot-Modell Snapshot-Reports können als aktueller Stammdaten- oder Jahresstand verwendet werden. Typische Visualisierungen: * aktuelle Anzahl Mitarbeitende * aktuelle FTE * aktuelle Verteilung nach Funktion * aktuelle Verteilung nach Standort oder OU * aktuelle Beschäftigungsstruktur ### History-Modell History-Reports werden über Jahr und Monat analysiert. Typische Visualisierungen: * Linienverlauf pro Monat * Entwicklung nach OU1, OU2 und OU3 * Mitarbeiter- und FTE-Vergleich * Soll-/Ist-/Kapazitätsverlauf * Eintritte und Austritte je Monat Die synthetischen \*_fte-Felder sind auf 100-%-FTE normierte Vergleichswerte. Sie ersetzen nicht die tatsächlichen Originalstunden. ## Fachliche Abdeckung Die Kombination aus Snapshot- und History-Reports unterstützt unter anderem: * aktuellen Mitarbeiterstand * Mitarbeiterstand im Zeitverlauf * aktuelle und historische FTE * Entwicklung von Teilzeit und Vollzeit * Entwicklung von Funktionen * Entwicklung je Standort, Team oder Bereich * Soll-, Ist-, Kapazitäts- und Überstundenverläufe * Eintritts- und Austrittsentwicklung * historische Organisationswechsel * EMP- und PER-basierte Strukturmerkmale Der aktuelle HR-Reports-Umfang liefert keine detaillierten Tages- oder Kontierungsdaten.