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.
Möchtest du die Urlaubsverwaltung ohne eine langwierige Registrierung ausprobieren?
Dann steige über unsere Landingpage direkt in das Demo-System ein.
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.
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
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.
Die Anwendung steht als
zur Verfügung.
- 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.yaml, 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.jarFalls 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.
Alle Informationen zum Betrieb mit unserem Docker Image sind im Ordner .example zu finden.
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 * * *
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.
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: $PASSWORTWenn Sie die Urlaubsverwaltung das erste Mal starten, werden automatisch alle Datenbanktabellen angelegt.
Um den E-Mail-Server zu konfigurieren, müssen folgende Konfigurationen vorgenommen werden.
uv:
mail:
from: absender@example.org
fromDisplayName: Urlaubsverwaltung
replyTo: no-reply@example.org
replyToDisplayName: Urlaubsverwaltung
application-url: https://example.org
spring:
mail:
host: $HOST
port: $PORT
username: $USERNAME
password: $PASSWORTAlle weiteren spring.mail.* Konfigurationen können in der Spring Dokumentation
eingesehen werden.
Personen werden nicht mehr automatisch in die Urlaubsverwaltung synchronisiert, sondern nur noch beim Login der jeweiligen Person in der Urlaubsverwaltung angelegt.
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: TRACEsowie eine Logdatei
logging.file.name: logs/urlaubsverwaltung.loggeschrieben wird.
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. |
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)
messagesstandardmäßige application messages properties - (required)
launchpad-corelaunchpad message properties
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:
Um die Anwendung möglichst schnell lokal ausprobieren zu können, bietet es sich an die Datenbank via Docker Compose zu starten:
docker-compose upund die Anwendung mit dem Profil demodata zu starten:
java -jar -Dspring.profiles.active=demodata urlaubsverwaltung.jarAuf 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 |
|---|---|---|
| user@urlaubsverwaltung.cloud | secret | User |
| departmentHead@urlaubsverwaltung.cloud | secret | User & Abteilungsleiter |
| secondStageAuthority@urlaubsverwaltung.cloud | secret | User & Freigabe-Verantwortlicher |
| boss@urlaubsverwaltung.cloud | secret | User & Chef |
| office@urlaubsverwaltung.cloud | secret | User & Office |
| admin@urlaubsverwaltung.cloud | 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.yaml
auf false gesetzt werden.
Folgende Systeme sind erreichbar unter localhost
| Service | Port |
|---|---|
| Urlaubsverwaltung | 8080 |
| Mailhog | 8025 |
| Mailhog SMTP | 1025 |
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.
Ohne GitHub Account
https://github.com/urlaubsverwaltung/urlaubsverwaltung.gitmit GitHub Account
git clone git@github.com:urlaubsverwaltung/urlaubsverwaltung.gitZum 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.
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"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.
Die 'User Experience' einiger Seiten wird zur Laufzeit mit JavaScript weiter verbessert.
Assets sind in <root>/src/main/javascript zu finden
bundlessind in den HTML-Seiten zu integrierencomponentssind einzelne Komponenten zur Wiederverwendung wie z. B. der datepickerjsbeinhaltet seitenspezifische Dingelibsind 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
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'Wir nutzen das großartige Lucide Icon Set. Vielen Dank!
Die Urlaubsverwaltung verfügt über eine API, die unter http://localhost:8080/api erreichbar ist.
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.
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));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.
Unsere Playwright UI Tests erzeugen bei Fehlschlag zwei Artefakte:
- Video
- Trace Report
Die Artefakte sind im target Verzeichnis zu finden.
Videos sind zur schnellen Analyse nützlich, da sie z. B. direkt im Browser angeschaut werden können.
Wenn das Video nicht ausreicht, kann der Trace Report zur detaillierten Analyse genutzt werden.
Hierzu das zip entweder auf https://trace.playwright.dev hochladen oder die lokale laufende progressive Webapp
bei sich selbst starten mit z. B. maven:
./mvnw exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.classpathScope="test" -D exec.args="show-trace target/FAILED-test.zip"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