Zum Hauptinhalt springen

Externe Datenbank

Zeiterfassung schreibt jedes Stempelereignis unmittelbar als einzelnen Datensatz in eine von Ihnen bereitgestellte SQL-Datenbank. Drittsysteme — Lohnbuchhaltung, HR-Software oder BI-Werkzeuge — lesen diese Tabelle direkt per SQL, ohne Umweg über das Modul. Der Vertrag dieser Schnittstelle ist das nachfolgend dokumentierte Tabellenschema.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen​

  • Typ: SQL-Datenbank — das Modul schreibt, Drittsysteme lesen
  • Unterstützte Datenbanksysteme: PostgreSQL, MySQL, Microsoft SQL Server, Derby
  • Konfiguration: Moduloberfläche, Karte Datenbank-Einstellungen — Felder Datenbanktyp, Host, Datenbankname, Benutzername, Passwort und Optionen (optionale Parameter, die zu Verbindungsbeginn an den Datenbankserver übergeben werden). Die Schaltfläche Verbindung testen prüft die Angaben; das Passwort legt das Modul verschlüsselt ab.
  • Tabelle: genau eine Tabelle mit frei wählbarem Namen. Das Modul normalisiert den Namen auf Kleinbuchstaben und entfernt alle Zeichen außer Buchstaben, Ziffern und Unterstrich.
  • Zugriff für Drittsysteme: direkte SQL-Verbindung mit eigenen Zugangsdaten an dieselbe Datenbank. Das Modul stellt keinen eigenen Abfrage-Endpunkt bereit; lesende Zugriffe erfordern keine Modullizenz.
  • Netzzugriff: Für Installationen ohne direkte Verbindung zum Datenbankserver (z. B. STARFACE Cloud) bietet die Moduloberfläche zusätzlich eine SSH-Tunnel-Konfiguration.

Alternativ zur eigenen Datenbank trägt die Schaltfläche STARFACE Datenbank die interne PostgreSQL-Datenbank der Anlage ein (localhost, Datenbank asterisk). Empfohlen ist eine eigene Datenbank: Bei Anlagen-Updates hat das Modul keine Kontrolle über die interne Datenbank. Legen Sie in jedem Fall regelmäßige Backups der Tabelle an.

Schreibverhalten​

Auslöser der Zeiterfassung ist die Gruppenanmeldung: Meldet sich ein Benutzer an der konfigurierten Zeiterfassungsgruppe an oder ab (Funktionstaste „Gruppe An-/Abmelden", STARFACE App, Teams-Integration oder User-Frontend des Moduls), fügt das Modul genau einen neuen Datensatz ein (INSERT). Optional stempelt das Modul ausgestempelte Gruppenmitglieder bei einem ausgehenden Telefongespräch automatisch ein. Bestehende Zeilen werden vom Modul weder geändert noch gelöscht; ohne gültige Modullizenz werden keine Stempelereignisse geschrieben.

Die Tabelle erstellen Sie einmalig über die Moduloberfläche. Das Modul setzt dabei die folgende DDL ab (Tabellenname beispielhaft zeiterfassung; existiert bereits eine Tabelle dieses Namens, schlägt die Erstellung fehl):

CREATE TABLE zeiterfassung (timestamp TEXT, status TEXT, accountid INTEGER, name TEXT)

Primärschlüssel, Indizes oder Constraints legt das Modul nicht an; die generischen Typangaben bildet das jeweilige Datenbanksystem auf seine nativen Typen ab.

Ausfallsicherheit: Ist die Datenbank beim Stempeln nicht erreichbar, puffert das Modul den Eintrag im Modulspeicher und versucht alle 5 Minuten, gepufferte Einträge nachzutragen — es gehen keine Stempelereignisse verloren. Nachgetragene Einträge behalten ihren ursprünglichen Zeitstempel, erscheinen aber erst verzögert in der Tabelle. Die physische Zeilenreihenfolge ist daher nicht zwingend chronologisch: Sortieren Sie Abfragen stets über ORDER BY timestamp, und verlassen Sie sich bei inkrementellen Abgleichen nicht allein auf den höchsten bereits gelesenen Zeitstempel.

Über die Moduloberfläche lässt sich zusätzlich ein Backup der Tabelle erstellen und wiederherstellen (Dateiendung .zebak, ein modulinternes, komprimiertes JSON-Format; die Wiederherstellung ersetzt den Tabelleninhalt vollständig).

Schema​

Alle Stempeldaten liegen in der einen konfigurierten Tabelle (im Folgenden beispielhaft zeiterfassung):

SpalteTypBedeutung
timestampTEXTZeitpunkt des Stempelereignisses als ISO-8601-Zeichenkette in lokaler Anlagenzeit, sekundengenau, ohne Zeitzonenangabe — z. B. 2026-08-04T07:32:10. Lexikografische Sortierung entspricht der zeitlichen Reihenfolge.
statusTEXTin = eingestempelt, out = ausgestempelt
accountidINTEGERAccount-ID des Benutzers auf der STARFACE — der stabile Schlüssel für die Benutzerzuordnung
nameTEXTName des Benutzers zum Stempelzeitpunkt im Format „Nachname, Vorname" (denormalisierte Momentaufnahme)

Hinweise für auswertende Systeme:

  • Die im Modul gepflegten Personalnummern (Eigene IDs) werden nicht in die Datenbank geschrieben; sie fließen erst beim Datei-Export ein (siehe Exportformate).
  • name dient der Lesbarkeit; maßgeblich für Auswertungen ist accountid, da sich Benutzernamen ändern können.
  • Arbeitszeiten sind nicht vorberechnet gespeichert — die Tabelle enthält ausschließlich die rohen Ereignisse. Dauern berechnen Sie durch Paarung aufeinanderfolgender in-/out-Ereignisse je Benutzer (oder Sie verwenden die Zeiterfassungs-Exporte des Moduls).

Beispiele​

Alle Stempelereignisse eines Monats, chronologisch (das Zeitraumfilter-Muster LIKE auf der ISO-Zeichenkette verwendet das Modul selbst und funktioniert auf allen unterstützten Datenbanksystemen):

SELECT timestamp, status, accountid, name
  FROM zeiterfassung
 WHERE timestamp LIKE '2026-07-%'
 ORDER BY timestamp;

Alle Ereignisse eines einzelnen Benutzers:

SELECT timestamp, status
  FROM zeiterfassung
 WHERE accountid = 101
 ORDER BY timestamp;

Aktuell eingestempelte Benutzer (jeweils letzter Status je Account):

SELECT t.accountid, t.name, t.timestamp AS eingestempelt_seit
  FROM zeiterfassung t
  JOIN (SELECT accountid, MAX(timestamp) AS ts
          FROM zeiterfassung
         GROUP BY accountid) letzter
    ON letzter.accountid = t.accountid
   AND letzter.ts = t.timestamp
 WHERE t.status = 'in';

Beispieldatensätze:

timestampstatusaccountidname
2026-07-01T07:58:23in101Mustermann, Max
2026-07-01T12:02:41out101Mustermann, Max
2026-07-01T12:31:07in101Mustermann, Max
2026-07-01T16:45:12out101Mustermann, Max
Anwendungsbeispiel

Eine Anwesenheitsübersicht im Intranet fragt zyklisch den letzten Status je Benutzer ab (Abfrage oben) und zeigt live, wer gerade eingestempelt ist — ganz ohne Modul-Oberfläche.

Versionierung & Kompatibilität​

Tabellenaufbau, Spaltennamen und die Wertemenge von status (in/out) sind der stabile Vertrag dieser Schnittstelle; dokumentierter Stand ist Modulversion 26.4.1. Eine separate Schemaversion in der Datenbank existiert nicht — maßgeblich ist die installierte Modulversion. Schemaänderungen werden in den Release Notes der jeweiligen Modulversion dokumentiert. Bauen Sie Auswertungen auf Spaltennamen auf (explizite Spaltenliste statt SELECT *), damit spätere Erweiterungen bestehende Abfragen nicht beeinflussen.

Inhaltsverzeichnis