Skip to content

comsysto/urlaubsverwaltung

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Urlaubsverwaltung Build Coverage Docker Pulls Crowdin

Die Urlaubsverwaltung ist eine Web-Anwendung, um Abwesenheiten elektronisch verwalten zu können.

Anhand von Urlaubsanträgen kann ein Mitarbeiter eine Anfrage stellen, die von den jeweils berechtigten Personen genehmigt, abgelehnt oder storniert werden kann. Jeder Mitarbeiter kann seine Überstunden pflegen, um immer den Überblick zu behalten und falls doch mal eine Person ausfallen sollte, so kann die Krankmeldung direkt gepflegt werden.

Wenn du mehr Informationen und Bilder über dieses Projekt sehen möchtest dann schaue auf unserer Landingpage vorbei.

Version 4.x
Diese Readme bezieht sich auf die 5er-Version der Urlaubsverwaltung. Wenn du Informationen zu der 4er-Version erhalten möchtest, dann findest du diese im v4.x Branch.

Demo-System

Möchtest du die Urlaubsverwaltung ohne eine langwierige Registrierung ausprobieren?
Dann steige über unsere Landingpage direkt in das Demo-System ein.

FAQ

Für Fragen, die bei der Benutzung der Urlaubsverwaltung aufkommen, gibt es ein Hilfe.
Sollte dieser Fragenkatalog nicht weiterhelfen, kannst du gerne ein neue Q&A erstellen.

🎉 Version 5.x

Die Version 5.0.0 der Urlaubsverwaltung ist verfügbar!

Wir haben größere Anpassungen an der Datenbank und den Security-Providern vorgenommen, sowie die Weichen für die weitere Entwicklung der Urlaubsverwaltung stellen. Daher gibt es für den ein oder anderen nicht nur gute Nachrichten.

  • Keine Unterstützung für MariaDB und MySQL. Wir wechseln komplett auf PostgreSQL. Einen Migrationspfad ist bereits im Migration-Guide-v5 vorhanden.
  • Wir haben die security provider LDAP und Active Directory entfernt und unterstützen dafür OIDC noch stärker.

Alle Informationen zum Migrieren von 4.72.1 auf 5.0.0 findet ihr im Migration-Guide-v5

Berechtigungen

In der Urlaubsverwaltung gibt es aktuell folgende Arten von Berechtigungen:

  • inaktiv: hat keinen Zugang mehr zur Urlaubsverwaltung (Daten des Benutzers bleiben zur Archivierung bestehen)
  • User: darf Urlaub für sich selbst beantragen
  • Abteilungsleiter: darf Urlaubsanträge für die Benutzer seiner Abteilungen einsehen, genehmigen und ablehnen
  • Freigabe-Verantwortlicher: ist bei der zweistufigen Genehmigung von Anträgen verantwortlich für die endgültige Freigabe
  • Chef: darf Urlaubsanträge aller Benutzer einsehen, genehmigen und ablehnen
  • Office: darf Einstellungen zur Anwendung vornehmen, Mitarbeiter verwalten, Urlaub für Mitarbeiter beantragen/stornieren und Krankmeldungen pflegen

Eine aktive Person kann eine oder mehrere Rollen innehaben.


Betrieb

Voraussetzungen

Download

Die Anwendung steht als

zur Verfügung.

Installation .jar Variante

  • Konfiguration Datenbank
  • Konfiguration Security Provider
  • Lege ein Verzeichnis für die Urlaubsverwaltung an (z.B. /opt/urlaubsverwaltung). Kopiere die .jar-Datei dorthin.
  • Erstelle in dem Verzeichnis eine Konfigurationsdatei namens application.properties, welche die Konfiguration für die Urlaubsverwaltung enthält und die Standardwerte überschreibt. Die vollständigen Konfigurationsoptionen sind unter Konfiguration dokumentiert.

Nach der Konfiguration lässt sich die Urlaubsverwaltung starten.

java -jar urlaubsverwaltung.jar

Falls es Probleme beim Starten der Anwendung gibt, ist es hilfreich das Logging der Anwendung zu konfigurieren, damit erhält man mehr Informationen über den Fehlerzustand.

Docker Variante

Alle Informationen zum Betrieb mit unserem Docker Image sind im Ordner .example zu finden.

Konfiguration

Die Anwendung besitzt im Verzeichnis src/main/resources eine Konfigurationsdatei. Diese beinhaltet gewisse Grundeinstellungen und Standardwerte. Diese allein reichen für die Produktivnahme der Anwendung allerdings nicht aus. Spezifische Konfigurationen wie z.B. die Datenbank Einstellungen und Security Provider müssen in einer eigenen Konfigurationsdatei hinterlegt werden.

Welche Möglichkeiten es bei Spring Boot gibt, damit die eigene Konfigurationsdatei genutzt wird, kann in der 'External Config' Reference nachgelesen werden.

Nachstehend alle spezifischen Konfigurationsmöglichkeiten der Urlaubsverwaltung mit ihren Standartwerten.

uv:

  mail:
    from: ''
    fromDisplayName: Urlaubsverwaltung
    replyTo: ''
    replyToDisplayName: Urlaubsverwaltung
    application-url: ''

  development:
    demodata:
      create: 'false'
      additional-active-user: '0'
      additional-inactive-user: '0'

  calendar:
    organizer: ''
    refresh-interval: P1D

  security:
    oidc:
      claim-mappers:
        group-claim:
          enabled: 'false'
          claim-name: groups
        resource-access-claim:
          enabled: 'false'
          resource-app: urlaubsverwaltung
        role-prefix: urlaubsverwaltung_
      post-logout-redirect-uri: '{baseUrl}'

  application:
    upcoming-holiday-replacement-notification:
      cron: 0 0 7 * * *
    reminder-notification:
      cron: 0 0 7 * * *
    upcoming-notification:
      cron: 0 0 7 * * *

  account:
    update:
      cron: 0 0 5 1 1 *

  sick-note:
    end-of-pay-notification:
      cron: 0 0 6 * * *

Security Provider konfigurieren

Siehe die Spring Boot oAuth2 konfiguration und für die Konfiguration des Resource Servers via JWT z.B.

Zudem kann das Verhalten der Urlaubsverwaltung anhand von uv.security.oidc beeinflusst werden.

Es wird erwartet, dass der OIDC Provider im Access Token folgende Attribute enthält: given_name, family_name, email. Der client registration muss deshalb mit den Scopes openid,profile und email konfiguriert werden.

Der erste Benutzer, welcher sich erfolgreich bei der Urlaubsverwaltung anmeldet, wird mit der Rolle Office angelegt. Dies ermöglicht Benutzer- und Rechteverwaltung und das Pflegen der Einstellungen innerhalb der Anwendung.

Datenbank konfigurieren

Die Anwendung verwendet zur Speicherung der Daten ein PostgreSQL-Datenbankmanagementsystem. Erstelle in deinem PostgreSQL-Datenbankmanagementsystem eine Datenbank sowie einen Benutzer mit Zugriffsrechten für diese Datenbank und konfiguriere diese

spring:
  datasource:
    url: jdbc:postgresql://$HOST:$PORT/$NAME_DER_DATENBANK
    username: $BENUTZER
    password: $PASSWORT

Wenn Sie die Urlaubsverwaltung das erste Mal starten, werden automatisch alle Datenbanktabellen angelegt.

E-Mail-Server konfigurieren

Um den E-Mail-Server zu konfigurieren, müssen folgende Konfigurationen vorgenommen werden.

uv:
  mail:
    from: [email protected]
    fromDisplayName: Urlaubsverwaltung
    replyTo: [email protected]
    replyToDisplayName: Urlaubsverwaltung
    application-url: https://example.org
spring:
  mail:
    host: $HOST
    port: $PORT
    username: $USERNAME
    password: $PASSWORT

Alle weiteren spring.mail.* Konfigurationen können in der Spring Dokumentation eingesehen werden.

Benutzer-Synchronisation konfigurieren

Personen werden nicht mehr automatisch in die Urlaubsverwaltung synchronisiert, sondern nur noch beim Login der jeweiligen Person in der Urlaubsverwaltung angelegt.

Logging konfigurieren

Sollten beim Starten der Anwendung Probleme auftreten, lässt sich in der Konfigurationsdatei eine ausführliche Debug-Ausgabe konfigurieren, indem das logging.level.* pro Paket konfiguriert wird,

logging:
  level:
    org.springframework.security: TRACE
    org.synyx.urlaubsverwaltung: TRACE

sowie eine Logdatei

logging.file.name: logs/urlaubsverwaltung.log

geschrieben wird.

Info-Banner

Es kann ein Info-Banner konfiguriert werden, um z. B. Wartungsarbeiten anzukündigen. Der Banner ist dann ganz oben zu sehen.

uv.info-banner.enabled=true
uv.info-banner.text.de=Wartungsarbeiten ab Freitag 14:00. Es kann zu Beeinträchtigungen kommen.
Property Type Description
uv.info-banner.enabled Boolean (default) false, true zum aktivieren des Banners
uv.info-banner.text.de String Text des Info-Banners für das Deutsche Locale.

Launchpad

Es kann ein Launchpad konfiguriert werden, welches einen Absprung zu anderen Anwendungen ermöglicht.

launchpad:
  name-default-locale: de
  apps[1]:
    icon: ''
    name:
      de: Anwendung 2
      en: App 2
    url: https://example-2.org
  apps[0]:
    icon: ''
    name:
      en: App 1
      de: Anwendung 1
    url: https://example.org
Property Type Description
launchpad.name-default-locale Locale Standard Name der Anwendung wenn für ein Locale keine Übersetzung gefunden wird.
launchpad.apps[x].url String URL der Anwendung.
launchpad.apps[x].name.[locale] String Name der Anwendung für ein Locale.
launchpad.apps[x].icon String URL eines Bildes oder ein base64 encodiertes Bild. Wird in das <img src="" /> Attribut geschrieben.
Das Bild sollte optimalerweise ein Quadrat sein.

Das Launchpad hat eigene Übersetzungen. Spring muss entsprechend konfiguriert werden, damit die messages.properties gefunden wird:

spring.messages.basename: messages,launchpad-core
  • (required) messages standardmäßige application messages properties
  • (required) launchpad-core launchpad message properties

Anwendung als Service

Da die Anwendung auf Spring Boot basiert, lässt sie sich sehr komfortabel als Service installieren. Wie genau dies funktioniert, kann den entsprechenden Kapiteln der Spring Boot Dokumentation entnommen werden:


Demodaten-Modus

Starten der Anwendung im Demodaten-Modus

Um die Anwendung möglichst schnell lokal ausprobieren zu können, bietet es sich an die Datenbank via Docker Compose zu starten:

docker-compose up

und die Anwendung mit dem Profil demodata zu starten:

java -jar -Dspring.profiles.active=demodata urlaubsverwaltung.jar

Auf diese Weise wird die Anwendung mit einer PostgreSQL-Datenbankmanagementsystem gestartet und Demodaten generiert.

Die Demodaten enthalten folgende Benutzer, ein Passwort wird nicht benötigt:

Benutzername Passwort Rolle
[email protected] secret User
[email protected] secret User & Abteilungsleiter
[email protected] secret User & Freigabe-Verantwortlicher
[email protected] secret User & Chef
[email protected] secret User & Office
[email protected] secret User & Admin

Möchte man, dass beim Starten der Anwendung keine Demodaten generiert werden, muss die Konfiguration

uv.development.demodata.create

in den application-demodata.properties auf false gesetzt werden.

Aufrufen der Anwendung

Folgende Systeme sind erreichbar unter localhost

Service Port
Urlaubsverwaltung 8080
Mailhog 8025
Mailhog SMTP 1025

Entwicklung

Wenn du uns bei der Entwicklung der Urlaubsverwaltung unterstützen möchtest, dann schau dir die Contributing to Urlaubsverwaltung Referenz und die folgenden Abschnitte an. Bei Fragen kannst du gerne ein neue Q&A erstellen.

Voraussetzungen

Repository clonen

Ohne GitHub Account

https://github.com/urlaubsverwaltung/urlaubsverwaltung.git

mit GitHub Account

git clone [email protected]:urlaubsverwaltung/urlaubsverwaltung.git

git hooks (optional)

Zum Automatisieren verschiedener Dinge bietet dir das Projekt git hooks an. Diese kannst du mit folgendem Befehl installieren:

git config core.hooksPath '.githooks'

Die Git-Hooks sind im .githooks Verzeichnis zu finden.

Anwendung starten

Die Urlaubsverwaltung ist eine Spring Boot Anwendung und kann mit dem Maven Plugin gestartet werden. Alle Abhängigkeiten, wie die Datenbank oder der Mail-Server werden automatisch gestartet. Es bietet sich an, die Anwendung mit dem Profil demodata zu starten, um Testdaten generieren zu lassen:

./mvnw clean spring-boot:run -Dspring-boot.run.jvmArguments="-Dspring.profiles.active=demodata"

bzw. für Windows Benutzer über:

./mvnw.cmd clean spring-boot:run -Dspring-boot.run.jvmArguments="-Dspring.profiles.active=demodata"

Anwendung nutzen

Im Browser lässt sich die Anwendung dann über http://localhost:8080/ ansteuern.

Mit dem demodata Profil wird eine PostgreSQL-Datenbank verwendet und es werden Demodaten angelegt, d.h. Benutzer, Urlaubsanträge und Krankmeldungen. Daher kann man sich in der Weboberfläche nun mit verschiedenen Demodaten-Benutzer anmelden.

Frontend Entwicklung

Die 'User Experience' einiger Seiten wird zur Laufzeit mit JavaScript weiter verbessert.

Assets sind in <root>/src/main/javascript zu finden

  • bundles sind in den HTML-Seiten zu integrieren
  • components sind einzelne Komponenten zur Wiederverwendung wie z. B. der datepicker
  • js beinhaltet seitenspezifische Dinge
  • lib sind third-party Bibliotheken

Der Frontend Build ist in Maven integriert. Isoliert können die Assets aber auch auf der Kommandozeile gebaut werden.

  • npm run build
    • baut optimierte, minifizierte Assets
    • Info: der Dateiname beinhaltet einen Hash welcher eindeutig zum Inhalt des Assets passt
  • npm run build:dev
    • baut nicht minifizierte Assets
  • npm run build:watch
    • baut automatisch nach dem Editieren von JavaScript / CSS Dateien neue Assets

Long term caching von Assets

Startet man den Maven Build oder baut man die Assets mit dem NPM Task npm run build wird eine JSON Datei assets-manifest.json angelegt. Das Manifest beschreibt ein Mapping der bundles zum generierten Dateinamen inklusive Hash. Dieser gemappte Dateiname muss in den Html-Seiten integriert werden. Damit das nicht bei jeder Änderung manuell gemacht werden muss, kann der Dateiname mit Hilfe der Taglib AssetsHashResolverTag.java zur Kompilierungszeit automatisiert werden.

<script defer asset:src="npm.jquery.js"></script>

Während der Weiterentwicklung ist es sinnvoll das Caching zu deaktivieren. Wird das demodata Profil verwendet muss nichts weiter getan werden. Verwendest du das Profil nicht, kannst du das Caching mit folgenden application Properties deaktivieren:

spring:
  web:
    resources:
      chain:
        cache: 'false'
        strategy:
          content:
            enabled: 'false'
        cache:
          cachecontrol:
            max-age: '0'

Icons

Wir nutzen das großartige Lucide Icon Set. Vielen Dank! ♥️

API

Die Urlaubsverwaltung verfügt über eine API, die unter http://localhost:8080/api erreichbar ist.

UI Tests mit Playwright

Im test ui Package befinden sich UI Tests. Diese testen einige End to End Anwendungsfälle wie z. B. in den Einstellungen etwas aktivieren/deaktivieren und dessen Auswirkungen.

Als Testrunner und auch Assertion Lib wird Playwright-Java verwendet.
Details siehe Playwright for Java Getting Started.

Headless Browser

Die Tests laufen standardmäßig ohne sichtbaren Browser (headless). Das kann im PageParameterResolver mit BrowserType.LaunchOptions entsprechend konfiguriert werden.

final Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(false));

Debugging

Playwright bietet einen eigenen Inspector an. Siehe Playwright Debugging Tests für weitere Informationen.

Um diesen zu nutzen, muss beim Starten des Tests die Umgebungsvariable PWDEBUG=1 gesetzt werden.

Release

GitHub action

Go to the GitHub action with the name release trigger.

  • Click on "Run workflow"
  • Add the "Milestone ID" (see in the uri of a milestone)
  • Add "Release version"
  • Add "Next version"
  • Run the workflow

Releases

No releases published

Packages

No packages published

Languages

  • Java 83.5%
  • HTML 10.8%
  • JavaScript 4.4%
  • CSS 1.3%