Eviworx
Docs
EN Zur Website

Settings API

Über die Settings API werden die allgemeinen Einstellungen (Firmenname, Application-URL), die Nummernkreise, die Anbindung von E-Mail, Microsoft Teams und Webex, die CAPTCHA-Konfiguration und die aktivierten Sprachen verwaltet. Außerdem liefert sie den Status der Benachrichtigungskanäle.

⚙️
Funktionen
✓ Nummernkreise je Objektart (Präfix + Stellenzahl)
✓ Firmenname und Application-URL
✓ Branding (Name, Logo, Favicon, Farben)
✓ E-Mail-Anbindung (SMTP/IMAP/Graph API)
✓ Teams- und Webex-Bot mit Verbindungstest
✓ Turnstile-CAPTCHA (Bot-Schutz)
✓ 5 aktivierbare Sprachen (DE, EN, ES, FR, IT)
✓ Secrets nie im GET (nur _has*-Flag)
✓ Eigene Rechte je Einstellungskategorie
✓ Audit-Log jeder Änderung

Authentifizierung, Permissions & Aufbau

Jeder Einstellungsschlüssel hat eine Lese- und eine Schreibberechtigung. Lesen darf, wer eine der beiden besitzt: Die Schreibberechtigung schließt das Lesen ein, damit beim Bearbeiten die gespeicherten Werte im Formular stehen und beim Speichern nicht durch Vorgabewerte ersetzt werden. PUT /api/settings/:key erwartet den Wert als { "value": … } und prüft ihn gegen das Schema des Schlüssels (z. B. bei den Nummernkreisen).

  • User-only: Alle Settings-Endpoints erfordern einen angemeldeten Benutzer; API-Keys werden abgewiesen. Ausnahmen sind die öffentlichen GETs /captcha und /enabled-languages.
  • settings.viewGeneral ist für Administratoren gedacht und in den System-Rollen End User und Agent nicht enthalten. general-settings und ui-settings (Branding, Sprache) darf jeder angemeldete Benutzer lesen.
  • Sensible Keys: entra-id-config, webex-settings und teams-settings sind nur über ihre eigenen Endpoints erreichbar (siehe Integration Settings). Diese geben Secrets nie im Klartext zurück.
  • Weitere Endpoints: /api/settings/license (Produktlizenz) und /api/settings/file-settings (Attachments) sind auf den verlinkten Seiten dokumentiert.

Systemwährung & Preismodus: general-settings enthält systemCurrency (einheitliche Währung für alle Beträge, Standard EUR, keine Umrechnung) und priceTaxMode (net | gross, Standard net; kennzeichnet Preisfelder, berechnet keine Steuer). Beide Werte gelten systemweit für Assets, Verträge, Lizenzen, Kostenstellen und Reports. Im Backend wirkt eine Änderung sofort; die Worker-Container übernehmen sie nach spätestens 60 Sekunden.

Globale Suche

Die entitätenübergreifende Suche (GET /api/search) ist eine eigene Domäne und hat eine eigene Seite: Globale Suche →.

Numbering Settings

Entity Number Formats

Entity Format Beispiel Reset-Policy
TicketPREFIX-NNNNNNTKT-000001Nie
ProblemPREFIX-NNNNNNPRB-000001Nie
ChangePREFIX-NNNNNNCHG-000001Nie
IncidentPREFIX-YYYY-NNNNNNINC-2026-000001Jährlich

Numbering Settings Endpoints

Method Endpoint Beschreibung
GET/PUT/api/settings/:keyNummernkreise für Tickets, Probleme, Changes und Incidents (key = ticket-numbering-settings, problem-numbering-settings, change-numbering-settings, incident-numbering-settings). PUT erwartet { "value": {…} } und prüft den Wert gegen das Schema des Schlüssels.

System & Sprachen

Method Endpoint Beschreibung
GET/api/settings/captchaTurnstile CAPTCHA Konfiguration (public)
GET/api/settings/enabled-languagesAktivierte Sprachen (public)
PUT/api/settings/enabled-languagesAktivierte Sprachen konfigurieren
GET/api/settings/channel-statusNotification-Channel-Status (E-Mail, Teams, Webex)
GET/api/settings/system-bannerSystem-Banner-Nachricht

General Settings: Firmenname (companyName) und Application-URL (applicationUrl) werden über PUT /api/settings/general-settings konfiguriert. Beide Werte werden für QR-Codes, PDF-Labels und E-Mail-Templates verwendet. Derselbe Schlüssel trägt die Systemvorgaben für Sprache (defaultLanguage), Zeitzone (timezone, Vorgabe Europe/Berlin) und Datumsform (dateTimeFormat, Vorgabe dd/MM/yyyy HH:mm). Sie gelten für jeden Benutzer ohne eigene Präferenz — in der Oberfläche ebenso wie in den Texten, die der Server erzeugt (E-Mail, Push, Webex, Teams). Es empfiehlt sich, Zeitzone und Datumsform bei der Einrichtung ausdrücklich zu setzen, damit beide Seiten dasselbe Bild zeigen.

Numbering Configuration

// GET Response
GET /api/settings/ticket-numbering-settings

Response:
{
  "prefix": "TKT",              // 1-10 uppercase letters
  "suffixLength": 6,            // 1-10 digits (zero-padded)
  "lastAssignedNumber": 12345  // read-only: last number handed out (null = none yet)
}

// Generated Ticket Number:
// TKT-012345 (prefix + zero-padded atomic counter)

Numbering aktualisieren

// Custom numbering for tickets
const update = await fetch('/api/settings/ticket-numbering-settings', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    value: {
      prefix: "TICKET",    // Custom prefix (only prefix + suffixLength are settable)
      suffixLength: 4      // Shorter suffix
    }
  })
});

const result = await update.json();
console.log(result);
// {
//   "prefix": "TICKET",
//   "suffixLength": 4,
//   "lastAssignedNumber": null   // read-only; the atomic counter keeps numbers unique
// }

// Next generated ticket number continues from the atomic counter:
// e.g. TICKET-2175, TICKET-2176, ...

⚠️ Warnung: Numbering-Settings sollten VOR Production-Start konfiguriert werden. Änderungen nach ersten Tickets können zu verwirrenden Nummern führen.

Year-Based Numbering (Incidents)

// Incidents have year-based counters
// Counter key: "incident-number-{YEAR}"

// 2025:
INC-2025-000001
INC-2025-000002
...
INC-2025-012345

// 2026 (automatic reset):
INC-2026-000001
INC-2026-000002
...

// Advantage: easy filtering by year

Application Settings

Settings Endpoints

Method Endpoint Beschreibung
GET/api/settingsAlle Einstellungen der Kategorie general
GET/api/settings/:keySpezifisches Setting abrufen
PUT/api/settings/:keySetting aktualisieren
DELETE/api/settings/:keySetting löschen

UI Settings (Application Branding)

// Get UI settings
GET /api/settings/ui-settings

Response:
{
  "applicationName": "ACME IT Helpdesk",
  "logo": {
    "url": "/uploads/logo.png",
    "width": 200,
    "height": 60
  },
  "favicon": {
    "url": "/uploads/favicon.ico"
  },
  "theme": {
    "primaryColor": "#3b82f6",
    "accentColor": "#8b5cf6"
  },
  "branding": {
    "companyName": "ACME Corporation",
    "supportEmail": "support@acme.com",
    "supportPhone": "+1 555 1234567"
  }
}

// Update UI settings
PUT /api/settings/ui-settings
{
  "value": {
    "applicationName": "New Helpdesk Name",
    "logo": {
      "url": "/uploads/new-logo.png"
    }
  }
}

Language Settings

// Available languages (PUBLIC endpoint)
GET /api/settings/enabled-languages

Response:
{
  "languages": ["de", "en"]
}

// Update language settings (Admin)
PUT /api/settings/enabled-languages
{
  "languages": ["de", "en", "fr"]
}
// The effective default language must stay in the list —
// otherwise 400 DEFAULT_LANGUAGE_NOT_ENABLED

Integration Settings

E-Mail Settings

Method Endpoint Beschreibung
GET/api/settings/emailE-Mail-Settings (SMTP/Graph; Secrets nur als _has*-Flag)
POST/api/settings/emailE-Mail-Settings aktualisieren
POST/api/settings/email/test-smtpSMTP-Verbindung testen
POST/api/settings/email/test-graphMicrosoft Graph API-Verbindung testen
 
// Update email settings
POST /api/settings/email
{
  "isEnabled": true,
  "smtp": {
    "enabled": true,
    "host": "smtp.gmail.com",
    "port": 587,
    "security": "tls",
    "username": "notifications@company.com",
    "password": "app-specific-password",
    "fromAddress": "notifications@company.com",
    "fromName": "IT Helpdesk",
    "tlsVerify": true
  }
}

// Test SMTP connection
POST /api/settings/email/test-smtp

Response:
{
  "connected": true,
  "diagnostic": null   // optional technical diagnostic from the email worker
}
// Failure: 400 EMAIL_CONNECTION_TEST_FAILED

Teams Settings

Method Endpoint Beschreibung
GET/api/settings/teamsTeams Bot Framework Settings
POST/api/settings/teamsTeams-Settings aktualisieren
POST/api/settings/teams/testTeams Bot-Verbindung testen
POST/api/teams/botTeams Bot Framework Messaging-Endpoint (von Microsoft aufgerufen)
 
// Teams Bot Framework konfigurieren
POST /api/settings/teams
{
  "appId": "00000000-0000-0000-0000-000000000000",  // Azure App Registration (GUID)
  "appPassword": "your-bot-secret",
  "tenantId": "your-tenant-id",
  "isEnabled": true
}

// Test senden
POST /api/settings/teams/test

Response:
{
  "connected": true,
  "connectedUsers": 12,
  "connectedChannels": 2,
  "testMessageSent": true
}

Webex Settings

Method Endpoint Beschreibung
GET/api/settings/webexWebex-Bot-Settings (Token nur als _hasToken-Flag)
POST/api/settings/webexWebex-Settings aktualisieren
POST/api/settings/webex/testWebex-Bot-Connection testen
 
// Webex Bot konfigurieren
POST /api/settings/webex
{
  "botToken": "Bearer_YOUR_BOT_TOKEN_HERE",
  "isEnabled": true
}

// Bot-Connection testen
POST /api/settings/webex/test

Response:
{
  "connected": true,
  "botId": "webex-bot-id",
  "botName": "Helpdesk Bot",
  "botEmail": "bot@webex.bot"
}

Settings Categories & Permissions

Category Settings-Keys Permissions
Email /api/settings/email (eigener Endpoint) settings.viewEmail, settings.editEmail
Integrations webex-settings, teams-settings, entra-id-config (eigene Endpoints; Secrets nur als _has*-Flag) settings.viewIntegrations, settings.editIntegrations
Numbering ticket/problem/change/incident-numbering-settings settings.viewNumbering, settings.editNumbering
Security captcha/turnstile-settings settings.editSecurity
SLA sla-settings settings.editSLA (lesen UND schreiben)
General general-settings, ui-settings (lesbar für alle angemeldeten Benutzer) settings.viewGeneral (für Administratoren), settings.editGeneral

SLA-Schwellwerte (sla-settings)

PUT /api/settings/sla-settings
{
  "value": {
    "warningThresholdPercent": 80,     // 50–99
    "criticalThresholdMinutes": 60     // 5–1440
  }
}

Ab wann ein SLA als WARNING gilt und wann ein Breach zu CRITICAL eskaliert. sla-settings gehört zur Kategorie sla und ist daher nicht in GET /api/settings enthalten; Lesen und Schreiben erfordern settings.editSLA, damit die SLA-Schwellwerte nicht jedem Inhaber von settings.viewGeneral angezeigt werden. Details und Cache-Verhalten: SLA Management API.

Security Features

Secret-Masking

// GET Response maskiert Secrets
GET /api/settings/webex

Response:
{
  "isEnabled": true,
  "_hasToken": true          // Secret never returned — only this boolean flag
}

// GET response for SMTP
{
  "smtp": {
    "username": "notifications@company.com",
    "_hasPassword": true      // Secret never returned — only this boolean flag
  }
}

Secrets werden im GET nie zurückgegeben — nur ein _has*-Flag zeigt an, ob ein Wert hinterlegt ist. Zusätzlich werden SMTP-Passwort, MS-Graph- und Entra-clientSecret sowie Webex-botToken und Teams-appPassword beim Speichern mit AES-256-GCM verschlüsselt abgelegt. Details auf der Sicherheits-Seite.

RBAC-Integration

  • Kritische Einstellungen: Bei jeder Änderung wird die Berechtigung direkt in der Datenbank geprüft, ohne Cache; ein entzogenes Recht greift sofort

SSRF Protection

Die Teams-Bot-Kommunikation akzeptiert nur Service-URLs auf freigegebenen Microsoft-Domains über HTTPS. Die Liste der Domains steht unter Integrations →.

Notification Channel Status

Channel Status Endpoint

// Get status of all notification channels
GET /api/settings/channel-status

Response:
{
  "EMAIL":  { "enabled": true,  "configured": true },
  "TEAMS":  { "enabled": true,  "configured": true },
  "WEBEX":  { "enabled": false, "configured": false },
  "IN_APP": { "enabled": true,  "configured": true },
  "PUSH":   { "enabled": true,  "configured": true }
}

Best Practices

  1. Numbering-Setup: Konfiguriere VOR Production-Start, verwende aussagekräftige Prefixes
  2. Suffix-Length: 6 Digits für große Deployments (bis 999.999), 4 für kleine
  3. E-Mail-Test: Immer test-smtp/test-graph nach Settings-Change ausführen
  4. Channel-Status: Prüfe nach Änderungen per channel-status, ob alle Kanäle aktiviert und konfiguriert sind
  5. UI-Branding: Logo max. 200x60px, Favicon 32x32px für beste Darstellung
  6. Secrets: Verwende starke Passwords, rotiere Tokens regelmäßig
  7. Language-Support: Aktiviere nur Sprachen mit vollständigen Templates
  8. Permissions: Nur ADMIN sollte settings.editIntegrations haben (kritisch)

Verwandte Dokumentation

← Absences API
Global Search API →