- Demo System
- Blog Posts
- FAQ
- Berechtigungen
- REST-Schnittstelle
- Installation
- Systemvoraussetzungen
- Download
- Starten der Anwendung
- Aufrufen der Anwendung
- Anwendung als Service
- Konfigurationsdatei
- Datenbank
- Produktives Starten der Anwendung
- Authentifizierung
- LDAP
- Active Directory
- Synchronisation der User-Datenbank
- Synchronisation mit Kalender
- Konfiguration Microsoft Exchange
- Konfiguration Google Calendar
- Entwicklung
- Changelog
- Technologien
- Lizenz
Die Urlaubsverwaltung ist eine Web-Anwendung, die es ermöglicht, Urlaubsanträge von Mitarbeitern elektronisch zu verwalten. Mitarbeiter stellen Urlaubsanträge, die von den jeweils Berechtigten genehmigt oder abgelehnt werden. Die Anwendung bietet eine Übersicht über die bestehenden Urlaubsanträge und ermöglicht außerdem Überblick und Pflege von Urlaubsanspruch und Anzahl verbleibender Urlaubstage der Mitarbeiter. Zusätzlich können Krankmeldungen erfasst und überblickt werden.
Zum Ausprobieren der Anwendung gibt es ein Demo System mit Testbenutzern für die unterschiedlichen Rollen:
| Rolle | Benutzername | Passwort | Vorname, Nachname |
|---|---|---|---|
| Office | test | secret | Marlene Muster |
| Chef | testBoss | secret | Max Muster |
| Freigabe Verantwortlicher | testManager | secret | Peter Huber |
| Abteilungsleiter | testHead | secret | Thorsten Krüger |
| Benutzer | testUser | secret | Klaus Müller |
| Admin | admin | secret | Senor Operation |
Weitere Informationen zur Geschichte und Entwicklung der Urlaubsverwaltung findet man im synyx Blog:
Für Fragen, die bei der Benutzung der Urlaubsverwaltung aufkommen können, gibt es ein FAQ. Der Fragenkatalog erhebt keinen Anspruch auf Vollständigkeit und befindet sich im ständigen Wachstum und in Veränderung.
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
- Admin: Keine fachliche Rolle sondern nur für den Zugriff von Management Schnittstellen (Spring Boot Actuator).
Eine aktive Person kann eine oder mehrere Rollen innehaben.
Die Urlaubsverwaltung besitzt einen sich selbst beschreibende REST-Schnittstelle.
Diese kann mit über /api/ aufgerufen werden, z.Bsp. hier: https://urlaubsverwaltung.herokuapp.com/api/
Um eine aktuelle Version der Urlaubsverwaltung zu installieren, bitte die folgende Anleitung befolgen.
Falls noch eine ältere Version (< 2.12.0) der Urlaubsverwaltung verwendet hier, können Details zur Installation und Konfiguration hier nachgelesen werden.
Zusätzlich wird die Urlaubsverwaltung auch als Docker Image synxy/urlaubsverwaltung bereitgestellt. Beispiele zu diesem Deployment gibt es hier.
- JDK 8
- MySQL Datenbank
Die Anwendung steht auf Github bereits als deploybare WAR-Datei zum Download zur Verfügung. Einfach die WAR-Datei der aktuellsten Version hier downloaden. Auch wenn der Download eine WAR-Datei ist, kann sie wie die bisherige JAR-Datei verwendet werden, da die WAR-Datei einen Tomcat bundled.
Damit man die Anwendung möglichst schnell ausprobieren kann, bietet es sich an die Anwendung im Entwicklungsmodus zu starten:
java -jar -Dspring.profiles.active=dev urlaubsverwaltung.warAuf diese Weise wird die Anwendung mit einer In-Memory-Datenbank und Testdaten gestartet. Man kann sich mit den gleichen Benutzerdaten wie beim Demo System anmelden.
Die Anwendung ist nun erreichbar unter
<servername>:8080/
Da die Anwendung auf Spring Boot basiert, lässt sie sich sehr komfortabel als Service installieren. Wie genau dies funktioniert, kann den entsprechenden Kapiteln in der Spring Boot Dokumentation nachgelesen werden:
Die Anwendung besitzt im Verzeichnis src/main/resources eine application.properties Datei zur Konfiguration.
Diese beinhaltet gewisse Grundeinstellungen und Standardwerte. Diese allein reichen für die Produktivnahme der
Anwendung allerdings noch nicht aus. Spezifische Konfigurationen wie z.B. die Datenbank Einstellungen müssen durch eine
eigene Properties-Datei hinterlegt werden. Welche Konfigurationen überschrieben werden können/müssen, kann in einer beispielhaften
Konfigurationsdatei
eingesehen werden. Diese Datei kann einfach als Grundlage genommen werden, um eine eigene application.properties zu
erstellen, die die Standardwerte überschreibt.
Welche Möglichkeiten es bei Spring Boot gibt, damit die eigene Konfigurationsdatei genutzt wird, kann hier nachgelesen werden.
Einfachste Möglichkeit:
Man kann in dem Verzeichnis, in dem man die Anwendung startet eine Datei namens application.properties mit eigener
Konfiguration hinterlegen. Die dort konfigurierten Properties überschreiben dann die Standardwerte.
Die in der Konfigurationsdatei konfigurierte Datenbank muss existieren.
Wenn eine eigene Konfigurationsdatei hinterlegt ist, darf die Anwendung natürlich nicht mehr im Entwicklungsmodus
gestartet werden, d.h. die Anwendung muss ohne -Dspring.profiles.active=dev gestartet werden:
java -jar urlaubsverwaltung.warDie Anwendung verfügt über drei verschiedene Authentifizierungsmöglichkeiten:
default- für lokalen Entwicklungsmodus
ldap- Authentifizierung via LDAP
- Es müssen die LDAP URL, die LDAP Base und LDAP User DN Patterns konfiguriert sein, damit eine Authentifizierung via LDAP möglich ist.
activeDirectory- Authentifizierung via Active Directory
- Es müssen die Active Directory Domain und LDAP URL konfiguriert sein, damit eine Authentifizierung via Active Directory möglich ist.
Der erste Benutzer, der sich erfolgreich im System einloggt, wird in der Urlaubsverwaltung mit der Rolle Office angelegt. Dies ermöglicht Benutzer- und Rechteverwaltung innerhalb der Anwendung und das Pflegen der Einstellungen für die Anwendung.
Um LDAP zur Authentifizierung zu nutzen, muss die Property auth in der eigenen Konfigurationsdatei auf ldap gesetzt
werden:
auth=ldap
Um Active Directory zur Authentifizierung zu nutzen, muss die Property auth in der eigenen Konfigurationsdatei auf
activeDirectory gesetzt werden:
auth=activeDirectory
Ab Version 2.14 werden die LDAP/AD-Benutzer nicht mehr automatisch in die Urlaubsverwaltung synchronisiert, sondern nur noch beim Login des jeweiligen Users in die Datenbank übertragen.
Man kann die automatische Synchronisation aller Benutzer aktivieren indem man in der Konfiguration das Property uv.security.ldap.sync bzw. uv.security.activeDirectory.sync auf true gesetzt wird:
uv.security.ldap.sync=truebzw.
uv.security.activeDirectory.sync=true
Die Urlaubsverwaltung bietet die Möglichkeit alle Urlaube und Krankheitstage mit einem Kalender zu synchronisieren. Dafür werden Microsoft Exchange bzw. Office 356 und Google Calendar unterstützt.
Anhand der zu konfigurierenden Email-Adresse wird per Autodiscovery die dazugehörige Exchange Server Adresse ermittelt, welche für die synchronisation verwendet wird. Wichtig ist, dass der gewünschte Kalender bereits zuvor angelegt wurde.
Die Anbindung von Google Calendar basiert auf einem OAuth 2.0 Handshake. Sobald alle Konfigurationsfelder wie unten beschrieben für die Synchronisation mit Google Calendar befüllt sind, kann mit dem Button "Zugriff erlauben..." der OAuth 2.0 Handshake durchgeführt werden. Sofern dieser Schritt erfolgreich war und die Synchronisation eingerichtet ist, steht neben dem Button "Verbindung zum Google-Kalender ist hergestellt."
Um einen solchen OAuth 2.0 Handshake durchführen zu können ist es zunächst notwendig die Urlaubsverwaltung als Anwendung bei Google bekannt zu machen. Dies geschieht über APIs und Services. Hier muss zunächst ein Projekt angelegt werden. Sobald das geschehen ist kann die Calendar API aktiviert werden. Nach der Aktivierung müssen außerdem OAuth 2.0 Client Zugangsdaten erzeugt werden. Es müssen außerdem die Autorisierte Weiterleitungs-URIs mit dem Wert gefüllt werden der in den Einstellungen unter Weiterleitungs-URL angezeigt wird. Direkt nach der Erstellung werden Client Id und Client Secret angezeigt. Diese müssen dann in den Einstellungen der Urlaubsverwaltung entsprechend hinterlegt werden.
Eine weitere notwendige Information ist die Kalender ID welche später zur Synchronisation verwendet wird. Es kann dafür entweder ein bestehender Kalender verwendet werden oder ein neuer Kalender angelegt werden. In Google Calendar kann man dann in den Kalendereinstellungen die Kalendar ID finden. Diese muss ebenfalls in der Urlaubsverwaltung gepflegt werden.
Damit der OAuth 2.0 Handshake durchgeführt werden kann, ist es notwendig die die Weiterleitungs-URL bei der Konfiguration der Webanwendung bei Google anzugeben. Diese ist abhängig von der Installation und wird in den Einstellungen des Google Kalenders angezeigt, z.B. http://localhost:8080/web/google-api-handshake für ein Testsystem. Sie ist nur für die initiale Freigabe des Kalenders nötig.
Im Folgenden werden die durchzuführenden Schritte beschrieben, wenn man an der Urlaubsverwaltung entwickeln möchte.
git clone [email protected]:synyx/urlaubsverwaltung.gitFür ein Release wird das maven-release-plugin verwendet. Zum sorgenfreien Release Erstellung kann folgendes Script verwendet werden.
export RELEASE_VERSION=0.10.0
export NEW_VERSION=0.11.0-SNAPSHOT
./release.sh
git fetchDie Urlaubsverwaltung ist eine Spring Boot Anwendung und kann mit dem Maven Plugin gestartet werden:
./mvnw clean spring-boot:runbzw. für Windows Benutzer über:
./mvnw.cmd clean spring-boot:run./mvnw clean spring-boot:run -Drun.profiles=mariadbEinzelne Parameter lassen sich mit -D<parameterName>=<parameterWert> überschreiben.
Im Browser lässt sich die Anwendung dann über http://localhost:8080/ ansteuern.
Ohne weitere Anpassung der Standardkonfiguration wird eine H2-Datenbank verwendet und es werden Testdaten angelegt, d.h. Benutzer, Urlaubsanträge und Krankmeldungen. Daher kann man sich in der Weboberfläche nun mit verschiedenen Testbenutzern anmelden:
testUser/secret: Benutzer mit der RolleUsertestBoss/secret: Benutzer mit der RolleBosstestHead/secret: Benutzer mit der RolleDepartmentHeadtestManager/secret: Benutzer mit der RolleSecondStageAuthoritytest/secret: Benutzer mit der RolleOffice
Die User Experience einiger Seiten wird zur Laufzeit mit JavaScript weiter verbessert.
Assets sind in <root>/src/main/webapp zu finden
bundlessind in den JSPs 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
npm run build:dev- baut nicht minifizierte Assets
npm run build:watch- baut automatisch nach dem editieren von JavaScript / CSS Dateien neue Assets
Möchte man, dass beim Starten der Anwendung keine Testdaten generiert werden, muss man die Property testdata.create
in den application-dev.properties auf false setzen.
Die Standardkonfiguration im dev-Profil sorgt dafür, dass eine H2 Web Konsole aktiv ist.
Diese kann standardmäßig erreicht werden unter:
localhost:8080/h2-console/
Die H2 Konfigurationen können in der application-dev.properties überschrieben werden.
Die Urlaubsverwaltung verfügt über eine API, die unter http://localhost:8080/api erreichbar ist.
Siehe Authentifizierung
Möchte man LDAP oder Active Directory zur Authentifizierung nutzen, setzt man die Property auth entweder als System
Property oder man konfiguriert diese in den application.properties bzw. in den application-dev.properties.
Hinweis: Die Verbindung zum LDAP / Active Directory muss dafür selbstverständlich korrekt in den
application.properties bzw. in den application-dev.properties konfiguriert sein.
Die Anwendung mit dem Parameter -Dauth=ldap starten:
./mvnw clean spring-boot:run -Dauth=ldapOder die Property auth in den application.properties bzw. in den application-dev.properties setzen:
auth=ldap
Die Anwendung mit dem Parameter -Dauth=activeDirectory starten:
./mvnw clean spring-boot:run -Dauth=activeDirectoryOder die Property auth in den application.properties bzw. in den application-dev.properties setzen:
auth=activeDirectory
Wenn man in einer produktions-nahen Umgebung entwickeln oder Probleme nachstellen will, bietet es sich an, die extenen Systeme wie die Datenbank oder den LDAP-Server zu virtualisieren. Hier wird gezeigt, wie man das mit Docker tun kann.
Alle Änderungen an der Anwendung werden im Changelog gepflegt: Changelog
- Die Anwendung basiert auf dem Spring MVC Framework.
- Zur Ermittlung von Feiertagen wird das Framework Jollyday benutzt.
- Das Frontend beinhaltet Elemente von Bootstrap gewürzt mit einer Prise jQuery und Font Awesome. *Für die Darstellung der Benutzer Avatare wird Gravatar benutzt.
- Zur Synchronisation der Urlaubs- und Krankmeldungstermine mit einem Microsoft Exchange Kalender wird die EWS JAVA API genutzt.
- Zur Synchronisation der Urlaubs- und Krankmeldungstermine mit einem Google Calendar wird der Google API Client verwendet.
synyx/urlaubsverwaltung is licensed under the Apache License 2.0