derTobsch / urlaubsverwaltung

Schluss mit Papierchaos und langweiliger Software. Wir zeigen dir, dass Urlaubsverwaltung auch Spaß machen kann.

Version 3.x

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.

Urlaubsverwaltung

• Übersicht
  • Demo System
• FAQ
• Changelog
• Berechtigungen
• REST-Schnittstelle
• Installation
  • Systemvoraussetzungen
  • Download
• Betrieb
  • Konfiguration
  • Testbetrieb
    • Starten der Anwendung
    • Aufrufen der Anwendung
  • Produktivbetrieb
    • Anwendung als Service
    • Konfiguration
    • Datenbank
    • Starten der Anwendung
    • Authentifizierung
    • Synchronisation der User-Datenbank
    • Synchronisation mit Kalender
    • Konfiguration Microsoft Exchange
    • Konfiguration Google Calendar
• Entwicklung
• Technologien
• Lizenz

---

Übersicht

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.

Demo System

Zum Ausprobieren der Anwendung gibt es ein Demo System mit dem 'Office' Benutzer zum Testen. Die Rollen findest du im Abschnitt Testbenutzer.

Geschichte

Weitere Informationen zur Geschichte und Entwicklung der Urlaubsverwaltung findest du im synyx Blog:

• Stand November 2011
• Stand November 2012
• Stand Oktober 2014
• Stand April 2017

---

FAQ

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.

Changelog

Alle Änderungen an der Anwendung werden im Changelog gepflegt.

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
• 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.

REST-Schnittstelle

Die Urlaubsverwaltung besitzt eine sich selbst beschreibende REST-Schnittstelle. Diese kann über /api/ aufgerufen werden.

---

Installation

Um eine aktuelle Version der Urlaubsverwaltung zu installieren, bitte die folgende Anleitung befolgen.

Zusätzlich wird die Urlaubsverwaltung auch als Docker Image synyx/urlaubsverwaltung bereitgestellt. Beispiele zu diesem Deployment gibt es hier.

Systemvoraussetzungen

• JDK 11
• MariaDB Datenbank (v10.4)
• Docker 17.12.0+ & Docker Compose

Download

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.

Betrieb

Konfiguration

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.

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.

Welche Möglichkeiten es bei Spring Boot gibt, damit die eigene Konfigurationsdatei genutzt wird, kann hier nachgelesen werden.

Nachstehend alle spezifischen Konfigurationsmöglichkeiten der Urlaubsverwaltung

# account
uv.account.default-vacation-days = 20
uv.account.update.cron = 0 0 5 1 1 * (on 1st January at 05:00 am)

# application
uv.application.reminder-notification.cron = 0 0 7 * * * (every day at 07:00 am)

# development
uv.development.testdata.create

# mail
uv.mail.administrator
uv.mail.application-url
uv.mail.sender

# security
uv.security.auth =  default

uv.security.directory-service.identifier
uv.security.directory-service.last-name
uv.security.directory-service.first-name
uv.security.directory-service.mail-address
uv.security.directory-service.sync.cron = 0 0 1 * * ? (every night at 01:00 am)
uv.security.directory-service.filter.member-of
uv.security.directory-service.filter.object-class = person

## active directory
uv.security.directory-service.active-directory.url = ldap://ad.example.org/
uv.security.directory-service.active-directory.domain = example.org
uv.security.directory-service.active-directory.sync.enabled = false
uv.security.directory-service.active-directory.sync.password = password
uv.security.directory-service.active-directory.sync.user-dn = cn=Administrator,cn=users,dc=example,dc=org
uv.security.directory-service.active-directory.sync.user-search-base = dc=example,dc=org

## ldap
uv.security.directory-service.ldap.url = ldap://ldap.example.org/
uv.security.directory-service.ldap.base = dc=example,dc=org
uv.security.directory-service.ldap.manager-dn
uv.security.directory-service.ldap.manager-password
uv.security.directory-service.ldap.user-search-filter = (uid={0})
uv.security.directory-service.ldap.user-search-base = ou=accounts
uv.security.directory-service.ldap.sync.enabled = false
uv.security.directory-service.ldap.sync.password = password
uv.security.directory-service.ldap.sync.user-dn = uid=username,ou=other,ou=accounts,dc=example,dc=org
uv.security.directory-service.ldap.sync.user-search-base = ou=people,ou=accounts

# oidc (openid connect)
uv.security.oidc.client-id
uv.security.oidc.client-secret
uv.security.oidc.issuer-uri
uv.security.oidc.logout-path

# person
uv.person.can-be-manipulated = false

# sick-note
uv.sick-note.end-of-pay-notification.cron = 0 0 6 * * * (every day at 06:00 am)

# workingtime
uv.workingtime.default-working-days[0] = 1 (monday till friday)
uv.workingtime.default-working-days[1] = 2
uv.workingtime.default-working-days[2] = 3
uv.workingtime.default-working-days[3] = 4
uv.workingtime.default-working-days[4] = 5

mit ihren Standartwerten.

Testbetrieb

Starten der Anwendung

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

docker-compose up

und die Anwendung mit dem Profil testdata zu starten:

java -jar -Dspring.profiles.active=testdata urlaubsverwaltung.war

Auf diese Weise wird die Anwendung mit einer MariaDB-Datenbank gestartet und Testdaten generiert. Die Testdaten enthalten folgende Nutzer:

Testbenutzer

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

Aufrufen der Anwendung

Folgende systeme sind erreichbar

Service	Port
Urlaubsverwaltung	8080
Mailhog	8025
Mailhog SMTP	1025

Produktivbetrieb

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:

• Linux Service
• Windows Service

Datenbank

Die in der Konfigurationsdatei konfigurierte Datenbank muss existieren.

Starten der Anwendung

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.war

Authentifizierung

Die 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 Einstellungen 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

Synchronisation der User-Datenbank

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.directory-service.ldap.sync.enabled bzw. uv.security.directory-service.active-directory.sync.enabled auf true gesetzt wird:

uv.security.directory-service.ldap.sync.enabled=true

bzw.

uv.security.directory-service.active-directory.sync.enabled=true

Synchronisation mit Kalender

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.

Konfiguration Microsoft Exchange

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.

Konfiguration Google Calendar

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."

Client anlegen

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.

Kalender anlegen/konfigurieren

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.

Urlaubsverwaltung Weiterleitungs-URL

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.

---

Entwicklung

Im Folgenden werden die durchzuführenden Schritte beschrieben, wenn man an der Urlaubsverwaltung entwickeln möchte.

Repository clonen

git clone [e-mail]:synyx/urlaubsverwaltung.git

Release

Fü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 fetch

Anwendung starten

Da die Urlaubsverwaltung abhängig von einer MariaDB-Datenbank ist, kann diese über

docker-compose up

gestartet 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=testdata

bzw. für Windows Benutzer über:

./mvnw.cmd clean spring-boot:run -Dspring-boot.run.profiles=testdata

Hinweis: 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)

Anwendung nutzen

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.

Frontend Entwicklung

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

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

• bundles sind in den JSPs 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 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>

Anlegen von Testdaten deaktivieren

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.

API

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

Authentifizierung

Siehe Authentifizierung

Die Anwendung mit OpenID Connect (OIDC) starten:

./mvnw clean spring-boot:run -Duv.security.auth=oidc

Oder in den application.properties konfigurieren:

uv.security.auth=oidc

Die Anwendung mit LDAP starten:

./mvnw clean spring-boot:run -Duv.security.auth=ldap

Oder in den application.properties konfigurieren:

uv.security.auth=ldap

Die Anwendung mit Active Directory (AD) starten:

./mvnw clean spring-boot:run -Duv.security.auth=activedirectory

Oder in den application.properties konfigurieren:

uv.security.auth=activedirectory

Externe Systeme mit Docker virtualisieren

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.

---

Technologien

• 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

---

Lizenz

synyx/urlaubsverwaltung is licensed under the Apache License 2.0