Synapcus Developers (EN)
Synapcus Developers (EN)
Breadcrumbs

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:

<https://server/synapcus.nsf/<xpage>>/rest/api

Ein REST-Aufruf enthält mindestens:

fct=<function>

Parameter werden kommasepariert mit params übertragen:

...?fct=<function>&params=<arg1>,<arg2>,...

Beispiel für einen historischen Report:

<https://server/synapcus.nsf/xrCmpCtrl.xsp/rest/api?fct=getHistoryMoss&params=lastyear>

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: <API_KEY>

Beispiel:

Bash
curl \\
  -H "Accept: application/vnd.collection+json" \\
  -H "x-api-key: <API_KEY>" \\
  "<https://server/synapcus.nsf/xrCmpCtrl.xsp/rest/api?fct=getHistoryMoss&params=lastyear>"

Wenn der vorgeschaltete Gateway das Authorization-Schema verwendet:

Authorization: Bearer <API_KEY>

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&params=thisyear
...?fct=getHistoryTims&params=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 TIM-Reports

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.