This guide covers all administrative functions of LeaveFlow. Admins have access to the /admin/... area and are responsible for the full configuration of the system.
Configure the core profile of your organization.
| Field | Description |
|---|---|
| Company name | Displayed throughout the UI and in PDF exports |
| Address | Used in the statistics PDF letterhead |
| Tax ID / Commercial Register | Used in the PDF letterhead |
| Logo | PNG/JPG/SVG up to 1 MB — displayed in PDF exports |
| Accent color | Hex color (#RRGGBB) used in future UI theming |
| Approval escalation days | Days before an unanswered approval request is escalated to the department deputy |
| Retention period (months) | GDPR: how long employee data is retained after exit (default: 36 months) |
| Exit leave handling | What happens to remaining leave balance on employee exit: Pay Out, Mandatory Consumption, or Freistellung |
The company record is created during the first-run setup wizard. It can be edited at any time here.
Users are the login accounts for LeaveFlow. Every person who logs in needs a user account. An employee record is separate and links to a user account.
| Role | Access |
|---|---|
ROLE_EMPLOYEE |
Self-service: submit leave requests, view balance, manage profile |
ROLE_MANAGER |
Employee access + approval queue, team calendar |
ROLE_ADMIN |
Full access including all admin configuration |
/admin/users/newAdmins can also trigger a new password-reset link for existing users at any time from the user detail page.
The user list supports:
Set the user status to Inactive on the edit page. Inactive users cannot log in. Their leave history is retained.
If a user loses access to their authenticator app, an admin can reset their 2FA enrollment at /admin/users/{id}/2fa-reset. This requires a CSRF-protected confirmation. The user must re-enroll on next login.
Departments are used for approval routing and team calendar grouping.
| Field | Description |
|---|---|
| Name | Display name |
| Department Lead | The manager who receives approval requests for this department |
| Deputy | Fallback approver when the lead is unavailable (must differ from lead) |
Approval routing logic: When an employee submits a leave request, it is routed to their department lead. If no lead is configured, it falls back to any user with ROLE_ADMIN.
Every new company gets a default "Alle" department. Assign employees to departments in their employee profile.
Locations define where an employee works. They determine which federal state's public holiday calendar applies to leave calculations.
| Field | Description |
|---|---|
| Name | Display name (e.g., "Berlin Office") |
| Country | ISO-2 country code (currently DE) |
| Federal State | ISO 3166-2 code (e.g., DE-BY for Bavaria) |
| City | Optional display field |
The federal state is used by the
HolidayCalculatorto determine which public holidays are non-working days for employees at that location.
Absence types define what kind of leave can be requested. Each type controls whether it deducts from the entitlement balance and whether it requires manager approval.
| Field | Description |
|---|---|
| Name | Display name (e.g., "Urlaub", "Krankheit") |
| Deducts from leave balance | Whether approved requests consume entitlement hours |
| Requires approval | Whether requests enter the approval workflow (vs. being auto-recorded) |
| Color | Hex color used in the team calendar |
| Illness tracking | Flag for 6-week illness alert (§3 EntgFG) |
| Active | Inactive types are hidden from the request form |
Default absence types created for a new company:
| Type | Deducts | Requires Approval | Notes |
|---|---|---|---|
| Urlaub | Yes | Yes | Standard annual leave (BUrlG) |
| Resturlaub | Yes | Yes | Carryover from previous year |
| Krankheit | No | No | Sick leave — auto-recorded, illness tracking enabled |
| Überstundenabbau | Yes | Yes | Overtime compensation |
| Sonderurlaub | No | Yes | Special leave (§616 BGB) |
| Fortbildung | No | Yes | Training / further education |
Entitlements define how many leave hours an employee has available in a given year. LeaveFlow distinguishes between regular entitlement (granted at year start) and carryover (rolled over from the previous year, with an expiry date).
/admin/entitlements/newThe form shows a pro-rata hint when the employee joined mid-year (BUrlG §5 — the Zwölftelregel applies).
Admins can edit hoursGranted and the carryover expiresAt date on existing entitlements. Every change requires a mandatory reason and creates an audit entry visible below the form.
Run the year transition console command at the start of each new year to automatically create carryover entitlements from remaining regular balances:
# Dry run first
docker compose exec -u app app php bin/console app:entitlement:year-transition --year=2027 --dry-run
# Apply
docker compose exec -u app app php bin/console app:entitlement:year-transition --year=2027
LeaveFlow includes a built-in holiday engine covering all 16 German federal states, calculated using the Gaussian Easter formula.
Filter by year and federal state. Holidays are color-coded by scope:
| Scope | Color | Meaning |
|---|---|---|
| National | Blue | Applies to all federal states (e.g., Neujahr, Tag der Deutschen Einheit) |
| Regional | Green | Applies to specific federal states (e.g., Fronleichnam in BY, BW, ...) |
| Company | Orange | Company-wide non-working days added by the admin |
Override the calculated holiday calendar for specific situations:
added — add a holiday that the calculator does not include by default (e.g., Augsburger Friedensfest for BY-Augsburg offices)removed — remove a holiday from the default calculation (e.g., Mariä Himmelfahrt for Protestant-majority BY municipalities)Overrides can optionally be scoped to a specific location, so multi-office companies can maintain different calendars per site.
Add company-wide non-working days (e.g., Christmas shutdown Dec 27–31). These apply to all employees regardless of location or federal state.
Blackout periods block leave requests for a defined date range. When an employee tries to submit a request overlapping a blackout period, the system shows a blocking error in the live preview — before they even submit.
| Field | Description |
|---|---|
| Name | Description shown to employees (e.g., "Year-end closing") |
| Start / End | Inclusive date range |
| Department | Optional — scope to a specific department, or leave blank for company-wide |
LeaveFlow supports four login methods. Multiple adapters can be enabled simultaneously.
The default. Users log in with email + password. Password reset via email. Two-factor authentication (TOTP) available.
Enable Google OAuth login for your organization:
https://your-domain.com/connect/google/checkGOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env.local@your-company.com)Google users bypass the LeaveFlow 2FA requirement (Google's own IdP MFA applies).
Enable Entra ID (formerly Azure AD) SSO:
https://your-domain.com/connect/entra/checkENTRA_CLIENT_ID and ENTRA_CLIENT_SECRET in .env.localSetting a Tenant ID is strongly recommended. Without it, personal Microsoft accounts can supply arbitrary email claims (nOAuth vulnerability).
Entra users bypass LeaveFlow 2FA.
Enable LDAP for on-premise Active Directory integration:
LDAP_BIND_PASSWORD in .env.localLDAP users keep the LeaveFlow 2FA requirement (corporate AD typically does not enforce MFA).
Enforce 2FA for all local-auth users company-wide:
Individual users set up 2FA in their profile (/profile/2fa). They can:
The statistics dashboard is the landing page for admins after login. It shows:
PDF export — Printable A4 statistics summary with company letterhead (logo + address), KPI table, monthly text summary, and department breakdown. Generated via dompdf.
CSV export — Leave account balances for all employees, semicolon-separated with UTF-8 BOM (Excel/Numbers compatible). Supports year filter. Uses German decimal comma format.
Both exports are available via buttons on the statistics dashboard.
Import employees in bulk via a semicolon-separated CSV file.
Click Download Template to get a CSV with all required and optional columns pre-filled with examples.
| Column | Format | Example |
|---|---|---|
name |
Free text | Max Mustermann |
email |
Valid email | max@example.com |
employee_number |
Alphanumeric | EMP-001 |
location_id |
Integer (Location ID) | 1 |
joined_at |
DD.MM.YYYY or YYYY-MM-DD |
01.01.2024 |
| Column | Format | Default |
|---|---|---|
weekly_hours |
Decimal (comma or dot) | 40 |
role |
employee, manager, admin |
employee |
Upload your CSV file. LeaveFlow validates each row and shows a preview table. Rows with errors are highlighted with specific error messages.
Click Import to create all valid rows. LeaveFlow re-validates before committing (race-safe). A summary shows how many records were created.
LeaveFlow supports GDPR-compliant data lifecycle management.
Set the number of months employee data is retained after exit. Default: 36 months (BUrlG minimum for German companies).
Configure what happens to remaining leave balance when an employee exits:
| Option | Behavior |
|---|---|
| Pay Out | Admin is shown the remaining balance — payout handled externally |
| Mandatory Consumption | Employee must use remaining leave before exit date |
| Freistellung | Remaining days are recorded as a Freistellungs-absence |
After the retention period expires, a daily scheduler runs the anonymization routine:
The admin receives a 30-day advance warning notification before anonymization runs.
When recording an employee exit at /admin/employees/{id}/exit:
API tokens authenticate machine-to-machine requests to the LeaveFlow REST API. See the API Documentation for full endpoint reference.
/admin/api-tokens/new| State | Behavior |
|---|---|
| Active | Authenticates API requests |
Revoked (revokedAt set) |
Returns 401 Unauthorized |
Expired (expiresAt in past) |
Returns 401 Unauthorized |
Tokens are company-scoped — they can only access data belonging to the company they were created for.
To revoke a token: click Revoke on the token detail page. Revocation is immediate and cannot be undone.