| Version 2.x wird nur noch bis zum 31.12.2019 mit Bug- und Sicherheitsupdates unterstützt. |
|---|
Aufgrund von umfangreicheren Neuerungen haben wir uns dafür entschieden, auf dem master Branch mit Version 3.x durchzustarten.
Version 2.x
Du bist auf der Suche nach Version 2.x? Diese findest du hier.
Du möchtest wissen, was alles zu tun ist, um von 2.x auf 3.x umzusteigen? Dann wirf einen Blick in den Migration Guide.
Bitte beachte, dass die Version 2.x nur noch bis zum 31.12.2019 mit Bug- und Sicherheitsupdates unterstützt wird. Danach wird ausschließlich an 3.x weiterentwickelt werden.
- Übersicht
- FAQ
- Changelog
- Berechtigungen
- REST-Schnittstelle
- Installation
- Testbetrieb
- Produktivbetrieb
- Entwicklung
- Technologien
- Lizenz
Die Urlaubsverwaltung ist eine Web-Anwendung, um Urlaubsanträge elektronisch verwalten zu können.
Mitarbeiter stellen Urlaubsanträge, die von den jeweils Berechtigten genehmigt oder abgelehnt werden können. Die Anwendung bietet einen komfortablen Überblick über offene Urlaubsanträge und den (verbleibenden) Urlaubsanspruch von Mitarbeitern.
Außerdem können auch Krankmeldungen und Überstunden erfasst und überblickt werden.
Zum Ausprobieren der Anwendung gibt es ein Demo System mit dem 'Office' Benutzer zum Testen. Die Rollen findest du im Abschnitt Testbenutzer.
Weitere Informationen zur Geschichte und Entwicklung der Urlaubsverwaltung findest du im synyx Blog:
Für Fragen, die bei der Benutzung der Urlaubsverwaltung aufkommen, gibt es ein FAQ. Sollte dieser Fragenkatalog nicht weiterhelfen, kannst du gerne ein neues Issue vom Typ "Question" erstellen.
Alle Änderungen an der Anwendung werden im Changelog gepflegt.
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 eine sich selbst beschreibende REST-Schnittstelle.
Diese kann über /api/ aufgerufen werden.
Um eine aktuelle Version der Urlaubsverwaltung zu installieren, bitte die folgende Anleitung befolgen.
Falls noch eine ältere Version (< 2.12.0) der Urlaubsverwaltung verwendet wird, können Details zur Installation und Konfiguration hier nachgelesen werden.
Zusätzlich wird die Urlaubsverwaltung auch als Docker Image synyx/urlaubsverwaltung bereitgestellt. Beispiele zu diesem Deployment gibt es hier.
- JDK 11
- MariaDB Datenbank (v10.4)
- Docker 17.12.0+ & Docker Compose
Die Anwendung steht auf Github 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.
Um die Anwendung möglichst schnell ausprobieren zu können, bietet es sich an die Datenbank via Docker Compose zu starten:
docker-compose upund die Anwendung mit dem Profil testdata zu starten:
java -jar -Dspring.profiles.active=testdata urlaubsverwaltung.warAuf diese Weise wird die Anwendung mit einer MariaDB-Datenbank gestartet und Testdaten generiert. Die Testdaten enthalten folgende Nutzer:
| Rolle | Benutzername | Passwort |
|---|---|---|
| User | user | secret |
| User & Abteilungsleiter | departmentHead | secret |
| User & Freigabe-Verantwortlicher | secondStageAuthority | secret |
| User & Chef | boss | secret |
| User & Chef & Office | office | secret |
| User & Admin | admin | secret |
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 der Spring Boot Dokumentation entnommen 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 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.
Im Produktivbetrieb mit der Produktivdatenbank darf die Anwendung natürlich nicht mehr mit Testdaten
gestartet werden, d.h. die Anwendung muss ohne -Dspring.profiles.active=testdata gestartet werden:
java -jar urlaubsverwaltung.warDie Anwendung verfügt über vier 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.
oidc- Authentifizierung via OpenID Connect (OIDC)
- Es müssen die OIDC issuerUri sowie die client id/secret definiert werden. Ausserdem müssen bei dem gewählten OIDC Provider die 'Allowed Logout URLs', die 'Allowed Callback URLs' und ggfs weitere Einstellungeun vorgenommen werden.
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.
Der Authentifizierungsmodus muss über die Property uv.security.auth in der eigenen Konfigurationsdatei gesetzt werden:
uv.security.auth=ldap
bzw.
uv.security.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.enabled bzw. uv.security.active-directory.sync.enabled auf true gesetzt wird:
uv.security.ldap.sync.enabled=truebzw.
uv.security.active-directory.sync.enabled=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 E-Mail-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 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 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 git@github.com:synyx/urlaubsverwaltung.gitFür ein Release wird das maven-release-plugin verwendet. Zum sorgenfreien Erstellen eines Release kann folgendes Skript verwendet werden.
export RELEASE_VERSION=0.10.0
export NEW_VERSION=0.11.0-SNAPSHOT
./release.sh
git fetchDa die Urlaubsverwaltung abhängig von einer MariaDB-Datenbank ist, kann diese über
docker-compose upgestartet werden. (Wie installiere ich Docker Compose?)
Die Urlaubsverwaltung ist eine Spring Boot Anwendung und kann mit dem Maven
Plugin gestartet werden. Es bietet sich an, die Anwendung mit dem Profil testdata zu starten, um Testdaten generieren
zu lassen:
./mvnw clean spring-boot:run -Dspring-boot.run.profiles=testdatabzw. für Windows Benutzer über:
./mvnw.cmd clean spring-boot:run -Dspring-boot.run.profiles=testdataHinweis: Aufgrund der Spring Boot Dev Tools wird das Profil via spring-boot.run.profiles gesetzt, statt via
spring.profiles.active. (vgl. spring-projects/spring-boot#10926)
Im Browser lässt sich die Anwendung dann über http://localhost:8080/ ansteuern.
Mit dem testdata Profil wird eine MariaDB-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.
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
- 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 asstes-mannifest.json angelegt.
Das Manifest beschreibt ein Mapping der bundles zum generierten Dateinamen inklusive Hash. Dieser gemappte Dateiname muss
in den JSPs integriert werden. Damit das nicht bei jeder Änderung manuell gemacht werden muss, kann der Dateiname mit Hilfe der
Taglib AssetsHashResolverTag.java zur Kompilierungszeit der JSP automatisiert werden.
<%@taglib prefix="asset" uri = "/WEB-INF/asset.tld"%>
<script defer src="<asset:url value='npm.jquery.js' />"></script>Möchte man, dass beim Starten der Anwendung keine Testdaten generiert werden, muss man die Property uv.development.testdata.create
in den application-testdata.properties auf false setzen.
Die Urlaubsverwaltung verfügt über eine API, die unter http://localhost:8080/api erreichbar ist.
Siehe Authentifizierung
Die Anwendung mit OpenID Connect (OIDC) starten:
./mvnw clean spring-boot:run -Duv.security.auth=oidcOder in den application.properties konfigurieren:
uv.security.auth=oidc
Die Anwendung mit LDAP starten:
./mvnw clean spring-boot:run -Duv.security.auth=ldapOder in den application.properties konfigurieren:
uv.security.auth=ldap
Die Anwendung mit Active Directory (AD) starten:
./mvnw clean spring-boot:run -Duv.security.auth=activedirectoryOder in den application.properties konfigurieren:
uv.security.auth=activedirectory
Wenn man in einer produktions-nahen Umgebung entwickeln oder Probleme nachstellen will, bietet es sich an, die externen Systeme wie die Datenbank oder den LDAP-Server zu virtualisieren. Hier wird gezeigt, wie man das mit Docker tun kann.
- Die Anwendung basiert auf dem Spring Boot 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.
- Zur Synchronisation mit Exchange wird die EWS Java API verwendet
- Initialisierung und Migration der Datenbank wird mit Liquibase durchgeführt
synyx/urlaubsverwaltung is licensed under the Apache License 2.0