pkONE^® : VzDocumentation

Um die Relevanz der angezeigten Dokumente beim Einstieg zu erhöhen und den Overload zu reduzieren:

E-Mail-Benachrichtigungen sollen einen Deep Link enthalten, wodurch direkt auf das Dokument oder auch nur auf eine Kategorie, zum Beispiel Rechnungen, verlinkt werden kann.

Wechsel vom alten VZ-Design auf das neue Design:

Einführung von Badges und neuen Dokument-Status:

Das folgende Mockup zeigt die geplante Neugestaltung des DocumentStores. Bitte beachten, dass es sich um einen Entwurf handelt, dessen finale Umsetzung von dieser Darstellung abweichen kann.

Um sicherzustellen, dass wichtige Dokumente, wie die Faktura, nicht untergehen, wird das Modul "MyTasks" eingeführt und um Dokumenttypen erweitert:

Anzeige: Tasks verschwinden standardmässig aus der "Offen"-Ansicht, sobald der Status auf erledigt wechselt.

Jeder Task hat eine Benachrichtigungsdefinition hinterlegt. So kann für den jeweiligen Task konfiguriert werden, wie viele Notifizierungen in welchen Abständen verschickt werden sollen.

Einführung von Action als 1st-class-Entity: Eine Verlinkung innerhalb pkONE, die über Parameter eine spezifische Entity adressieren kann. Eine Action kann von überall her getriggert werden. Siehe auch ActionToClassNavigationMapping für das aktuelle Mapping.

Beispiele:

Severity: NORMAL, HIGH, VERY HIGH

Möglichkeit der Markierung von "kritisches Events", Typ/Entity-basiert. Bspw.

Bitte beachten, dass die Statistiks im Benutzer nicht audtiert werden! Ansonsten führen z.B Logins jeweils zu einer Tabelleneintrag, das ist nicht gewünscht.

Enthält eine Liste von Activities inklusive ActivityType (true/false auf ActivityType)-

Definition ActivityType’s

Relevante Properties werden auf DAO Klassen mittels Annotation markiert (z.B. ActivityAudit)

Persistenz Code wird dahingehend erweitert, dass Entitäten für welche Activity Logging konfiguriert ist (via ActivityType) bei add/edit/delete entsprechende Activities persistiert werden.

Mit jeder Persistierung (obiger Punkt) werden die relevanten Property changes ebenfalls persistiert (ActivityItem’s)

The decision was made to use manual event-based auditing because:

Location: AdminDomain/src/main/java/ch/optimizeit/domain/admin/audit/

Database Tables:

AuditService Interface (PkOneBusinessLayerApi/…​/audit/AuditService.java):

AuditServiceImpl (PkOneBusinessLayer/…​/audit/AuditServiceImpl.java):

AuditActivityDao (PkOneBusinessLayerApi/…​/data/AuditActivityDao.java):

OmanUserServiceImpl (PkOneBusinessLayer/…​/OmanUserServiceImpl.java) integrates with AuditService:

OmanUser (BusinessDomain/…​/entities/OmanUser.java) is annotated for auditing:

Location: Oman/src/main/java/ch/optimizeit/pkone/ui/audit/

Features:

applicationContext-services.xml - AuditService bean wiring:

application_de.properties (and other locales):

AuditServiceTest (13 tests):

UserAuditTest (12 tests):

Total: 25 tests, 100% passing

The UI styling has been updated to match the existing pkONE table styling (e.g., Users list):

ActivityList.html changes:

ActivityDetailPanel.html changes:

Note: Application restart required for HTML changes to take effect.

Severity classification for certain events:

DataView provides:

Low code friction. Just @Audited on entities and Envers automatically tracks changes via Hibernate events. Minimal refactoring needed.

Temporal queries. You can ask "what did this policy look like on 2024-06-15?" which is genuinely useful. The fluent API is reasonable.

Mature & battle-tested. It’s been in production since Hibernate 3.x. Integration with Spring Data JPA and your existing stack is straightforward.

Audit table explosion. Envers creates parallel {entity}_AUD tables for every audited entity. With your multi-module architecture and many domain entities, you’re doubling storage immediately. At insurance policy scale, this adds up.

Revision granularity mismatch. Envers groups all changes in a single transaction into one "revision." For your domain, you likely need finer business context—not just "who changed it and when," but why (policy amendment reason, employer request, regulatory update, etc.). Your current mutation/mutationdata system probably captures this better.

Performance overhead at scale. Envers triggers on every insert/update/delete. In high-volume scenarios (batch imports, nightly jobs), the audit logging can noticeably slow transaction throughput.

Your existing system conflict. You already have proprietary auditing for mutations. Mixing Envers (automatic, row-level changes) with your mutation-based tracking (business-event-based) creates two parallel audit trails that diverge conceptually and operationally. This gets messy during incident investigation.

Envers works well for administrative entities (users, settings, permissions)—things where "what changed and when" is sufficient.

Envers is redundant for insurance/mutation core if you already have solid mutation tracking. You’d be auditing the same changes twice, differently.

Better hybrid approach:

Key question to ask: Does your mutation system already give you the audit trail you need? If so, Envers is probably solving a problem you don’t have.

What’s the main audit gap you’re trying to close—is it missing business context, performance on retrieving historical state, or coverage of entities outside the mutation system?

Exact match for the audit need. Users, permissions, settings, and job configurations don’t carry the same business context complexity as policies. You just need: "who changed what, when, to what value." That’s Envers' sweet spot.

No conceptual conflict. These entities aren’t part of your mutation/mutationdata system, so you’re not creating duplicate audit trails. Clean separation.

Storage overhead is manageable. Admin/config tables are typically small. The _AUD tables won’t balloon like they would if you audited the entire policy domain.

Compliance angle. For user access logs and setting changes, having an immutable audit trail is often a regulatory or security requirement. Envers gives you that cleanly.

Entities to audit:

What you get:

Trade-offs are minimal here:

Since you’re on Spring Boot 3.x with Hibernate 6.2, Envers integration is straightforward:

Enable in your Spring context and you’re mostly done. Flyway migrations will handle the _AUD table creation.

Make sure you capture WHO changed things. Envers tracks the revision number and timestamp, but you need to ensure the Spring Security principal is available to record the username. This usually requires a custom RevisionListener:

Otherwise you’ll get "user changed this" but not which user.

Bottom line: For your stated scope, Envers is the right tool. It solves the problem without added complexity. I’d recommend it.

Short answer: Envers tracks n:m collection changes, but with important caveats.

If you have:

Envers will create a user_employer_AUD table and track when rows are added/removed. You can query: "What employers did user X have on 2024-01-15?"

1. Collection initialization matters. If the employers collection isn’t fully loaded when you modify it, Envers may miss changes. This is a real problem in Spring Data scenarios where you lazily fetch collections.

2. The audit trail is collection-level, not granular. You see "employer was added/removed" with a timestamp, but not:

3. Bidirectional consistency. If admins are directly manipulating the join table or the relationship, you risk corrupting the audit trail if both sides aren’t synchronized properly.

For user-employer assignments, you likely do want those details. Map it explicitly:

Then on User:

Why this is better:

Your admin edit form would then do:

Envers captures the entire UserEmployer entity change—no ambiguity.

For simple add/remove tracking: Standard @ManyToMany with @Audited works, but watch for collection initialization.

For your scenario (admin-managed user-employer assignments): Definitely map the join table as an entity. You’ll want to know who assigned what and when, and that requires capturing more than just the join table’s foreign keys.

This also aligns better with your existing mutation/mutationdata philosophy—you’re treating the assignment as a business event with context, not just a relationship change.

Model it like your existing mutation/mutationdata system. Don’t try to auto-track everything—capture auditable events at the business logic layer.

Then at the service layer, you explicitly log:

1. Intent is explicit. You know why every line of audit code exists. No mystery framework magic.

2. Context is captured naturally. The reason field, the performing user, the exact action—all there because you wrote it.

3. High-volume performance is irrelevant. User/employer assignments aren’t high-frequency. You can afford to explicitly log each one.

4. Query simplicity. Want to know "all employers assigned to user X in the last 90 days?"

5. Compliance audit trail. For regulatory purposes, you can easily generate reports: "Who assigned this employer to this user and why?"

6. No mysterious side effects. If a bug corrupts your audit log, you wrote the bug—you can see it.

For your use case (user/employer/settings changes)? Manual auditing wins. These are intentional admin actions, not high-frequency system noise. You want to capture intent and context. Writing the code explicitly makes that natural.

Envers would buy you: Less boilerplate, but at the cost of clarity and context.

What I’d actually do: Combine both approaches:

Or just stick with manual for everything admin-related and save the Envers dependency entirely. The audit logging layer you’d write is ~200 lines of code, one-time investment, and you own it forever.

A dedicated DocumentType (e.g. KONTOKORRENT_SALDO0) is introduced alongside the existing KONTOKORRENT type. It represents invoices/statements that require no action from the employer.

The existing document distribution pipeline uses a filename convention to distinguish the two cases. Focus delivers zero-balance Kontokorrente with a _Saldo0 suffix in the filename:

A second DocumentDistributionDefinition with a matching regex routes _Saldo0 files to the new DocumentType. Documents are imported and distributed to the employer as usual — nothing is suppressed or hidden.

A new screen in the employer/webcustomer portal lets users configure which DocumentTypes should trigger notifications. Employers who don’t want to be notified about zero-balance Kontokorrente simply disable notifications for that DocumentType.

We’ll introduce a new column showing a document’s document type.

A new filter field will allow the user to filter for any of the configured document types.

The new preferences screen (point 3, above) will also allow the user to set filter pre-sets on the level of the document type. This way, the user has the option to exclude certain document types from showing when he/she navigates to the DocumentStore. Once in the document store, the filter pre-sets can be overridden (e.g. by clearing the filter pre-set and thus showing all document types)

New DocumentType KONTOKORRENT_SALDO0 in DocumentTypeProviderVz, plus a second DDD with a regex matching the _Saldo0 filename suffix. Straightforward configuration work following established patterns.

New entity (e.g. EmployerNotificationPreference) with DB migration, DAO/repository, and service layer. New Wicket page/panel in the webcustomer portal for managing preferences per DocumentType. Integration into the notification pipeline (DocumentNotificationEventListener) to check preferences before dispatching. This is the main work item — no existing webcustomer settings/preferences screen exists to build on.

Abzuklären: lösen wir dies mittels Settings? Existiert ein Konzept von per-user settings?

Add a "Dokument-Typ" column to DocumentStorePanel and a corresponding dropdown filter. The Document entity already has a documentType reference. Requires extending DocumentMetaDataProvider filtering logic.

Extend the preferences screen (B) to also allow setting default DocumentType filters for the DocumentStore view. On navigation to DocumentStore, apply these pre-sets as initial filter state. User can override in-session.