181 lines
11 KiB
Markdown
181 lines
11 KiB
Markdown
# ExpiryIndicator – Vorgehen
|
||
|
||
## Ziel
|
||
|
||
Eine SharePoint-Framework-Solution für SharePoint Server Subscription Edition auf Basis von SPFx 1.4.1. Die App stellt für moderne Listen und Dokumentbibliotheken Folgendes bereit:
|
||
|
||
- farbliche Kennzeichnung einer frei konfigurierbaren vorhandenen Datumsspalte,
|
||
- Berechnung eines effektiven Ablaufdatums aus `Created`, wenn `ExpiryDate` leer ist,
|
||
- frei konfigurierbare Laufzeit-, Schwellenwert- und Farbregeln pro Liste/Bibliothek,
|
||
- einen Befehl **„Ablaufdatum +1 Jahr“** für ein oder mehrere ausgewählte Elemente,
|
||
- einen unsichtbar laufenden Application Customizer, der den Einstellungsdialog per URL-Parameter für Listenverwalter öffnet.
|
||
|
||
## Wichtige Randbedingung
|
||
|
||
Die fachliche Ablaufdatumsspalte wird **nicht** durch diese Solution angelegt oder geändert. Sie stammt aus dem Content Type Hub und kann bei jedem Kunden einen anderen internen Namen besitzen. Der interne Name wird pro Liste/Bibliothek konfiguriert und beim Aktivieren an das Skript übergeben. Falls das konfigurierte Feld fehlt, bleibt der Verlängerungsbefehl deaktiviert beziehungsweise verborgen; der Einstellungsbefehl bleibt für Listenverwalter verfügbar.
|
||
|
||
## Technischer Aufbau
|
||
|
||
### 1. Field Customizer
|
||
|
||
`ExpiryIndicatorFieldCustomizer` wird an die vorhandene Spalte `ExpiryDate` gebunden und rendert deren Zelle.
|
||
|
||
Berechnung des effektiven Ablaufdatums:
|
||
|
||
1. Ist das konfigurierte Ablaufdatumsfeld gesetzt, wird dieser Wert verwendet.
|
||
2. Ist es leer, werden die fachlichen `rules` in ihrer konfigurierten Reihenfolge ausgewertet.
|
||
3. Vor jeder Wertprüfung wird geprüft, ob `columnName` in der aktuellen Liste/Bibliothek existiert. Ein fehlendes Feld kann die Regel nicht erfüllen.
|
||
4. Existiert das Feld und entspricht sein Wert `columnValue`, werden `lifeTime` und `columnRule` dieser Regel verwendet.
|
||
5. Passt keine Regel oder existiert keines der Regelfelder, werden `default.lifeTime` und `default.columnRule` verwendet.
|
||
6. Die erste passende `columnRule` bestimmt den Zeilenverlauf vom Standardhintergrund zur Regel-Hintergrundfarbe, die Textfarbe und die optionale Beschriftung; die Auswahlspalte bleibt ungefärbt.
|
||
|
||
Die Berechnung arbeitet mit Kalenderjahren/-monaten/-tagen, nicht mit pauschalen 365-Tage-Jahren.
|
||
|
||
### 2. ListView Command Set
|
||
|
||
`ExpiryIndicatorCommandSet` stellt in der modernen Befehlsleiste eine fachliche Aktion bereit:
|
||
|
||
- **Ablaufdatum +1 Jahr**
|
||
- sichtbar, wenn mindestens ein Element gewählt wurde und `ExpiryDate` vorhanden ist,
|
||
- unterstützt Einzel- und Mehrfachauswahl,
|
||
- liest `Created` und `ExpiryDate` serverseitig über REST,
|
||
- verwendet bei leerem `ExpiryDate` zunächst das berechnete effektive Ablaufdatum,
|
||
- addiert ein Kalenderjahr und schreibt das Ergebnis nach `ExpiryDate`,
|
||
- zeigt eine Zusammenfassung über erfolgreiche und fehlgeschlagene Änderungen.
|
||
|
||
### 3. Application Customizer
|
||
|
||
`ExpiryIndicatorApplicationCustomizer` läuft ohne permanente Oberfläche. Auf einer modernen Listen- oder
|
||
Bibliotheksansicht öffnet `expiryIndicatorSettings=1` den Konfigurationsdialog für Benutzer mit
|
||
`ManageLists`-Berechtigung. Die Befehlsleiste enthält dadurch keinen Einstellungsbefehl.
|
||
|
||
### 4. Konfiguration
|
||
|
||
Die Konfiguration wird pro Liste als JSON in `ClientSideComponentProperties` des gebundenen lokalen Listenfeldes gespeichert. Eine zusätzliche Konfigurationsliste wird bei neuen Installationen nicht erzeugt. Für Upgrades darf eine bestehende `_ExpiryIndicatorConfiguration` ausschließlich als Lese-Fallback verwendet werden, bis die Konfiguration beim nächsten Speichern in die Component Properties migriert wurde. Die fachliche Spalte `ExpiryDate` bleibt davon unberührt.
|
||
|
||
Konfigurierbar sind mindestens:
|
||
|
||
- interner Name des Erstellungsfeldes, Standard `Created`,
|
||
- interner Name des Ablaufdatums, Standard `ExpiryDate`,
|
||
- Standardlaufzeit unter `default.lifeTime` als Wert und Einheit (`days`, `months`, `years`),
|
||
- Standard-Farbregeln unter `default.columnRule`,
|
||
- priorisierte fachliche Regeln mit `columnName`, `columnValue`, eigener `lifeTime` und eigenen `columnRule`-Einträgen,
|
||
- beliebig viele Farbregeln mit Operator, Tagesgrenze, Hintergrundfarbe, Textfarbe und Beschriftung,
|
||
- Darstellung bei fehlenden oder ungültigen Datumswerten,
|
||
- Bestätigungsdialog vor der Verlängerung.
|
||
|
||
Regeln werden deklarativ gespeichert. Es wird kein JavaScript aus der Konfiguration mit `eval` oder ähnlichen Mechanismen ausgeführt.
|
||
|
||
Beispiel einer Laufzeitkonfiguration:
|
||
|
||
```json
|
||
{
|
||
"baseField": "Created",
|
||
"expiryField": "ExpiryDate",
|
||
"default": {
|
||
"lifeTime": { "value": 3, "unit": "years" },
|
||
"columnRule": []
|
||
},
|
||
"rules": [
|
||
{
|
||
"columnName": "DataPrivacy",
|
||
"columnValue": "PersDat1",
|
||
"lifeTime": { "value": 1, "unit": "years" },
|
||
"columnRule": []
|
||
},
|
||
{
|
||
"columnName": "DataPrivacy",
|
||
"columnValue": "PersDat2",
|
||
"lifeTime": { "value": 3, "unit": "years" },
|
||
"columnRule": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5. Aktivierung und Deployment
|
||
|
||
- Erstellung eines `.sppkg`-Pakets mit eingebetteten Client-Side Assets.
|
||
- Registrierung des Command Sets und des Settings-Application-Customizers.
|
||
- Keine Provisionierung fachlicher Ablaufdatumsspalten, Site Columns oder Content Types.
|
||
- Bereitstellung eines PowerShell-/CSOM-Aktivierungsskripts, das den Field Customizer mit einer als Parameter angegebenen vorhandenen Ablaufdatumsspalte verknüpft.
|
||
- Bereitstellung eines entsprechenden Deaktivierungsskripts, das nur diese Verknüpfung und App-Custom-Actions entfernt, nicht aber fachliche Daten oder Spalten.
|
||
|
||
## Umsetzungsschritte
|
||
|
||
- [x] Architektur und Randbedingungen dokumentieren.
|
||
- [x] SPFx-1.4.1-Projektstruktur anlegen.
|
||
- [x] gemeinsame Modelle, Datumsberechnung und Regel-Auswertung implementieren.
|
||
- [x] Regel-Engine für feldwertabhängige Laufzeiten und Farbschwellen implementieren.
|
||
- [x] REST-Service für Konfiguration und Elementaktualisierungen implementieren.
|
||
- [x] Field Customizer implementieren.
|
||
- [x] ListView Command Set und Einstellungsdialog implementieren.
|
||
- [x] Settings-Application-Customizer mit URL-Aktivierung implementieren.
|
||
- [x] Feature-XML für Command-Bar-Registrierung erstellen.
|
||
- [x] CSOM-Aktivierungs- und Deaktivierungsskripte für die vorhandene `ExpiryDate`-Spalte erstellen.
|
||
- [x] Lokalisierung Deutsch/Englisch ergänzen.
|
||
- [x] Build mit der SPFx-1.4.1-kompatiblen Legacy-Toolchain ausführen.
|
||
- [x] `.sppkg` erzeugen und Installationsanleitung ergänzen.
|
||
- [x] Tests für Kalenderarithmetik, Schwellwerte und leere Ablaufdaten durchführen.
|
||
|
||
## Roadmap Version 2.0
|
||
|
||
### Logische Verkettung von Regeln
|
||
|
||
- [x] Konfigurationsschema für mehrere Bedingungen innerhalb einer Regel definieren.
|
||
- [x] Bedingungen mit den logischen Operatoren `AND` und `OR` verknüpfen können.
|
||
- [x] Verschachtelte Bedingungsgruppen und eine eindeutige Auswertungsreihenfolge festlegen.
|
||
- [x] Regel-Engine um die Auswertung verketteter Bedingungen erweitern.
|
||
- [x] Bestehende Version-1-Regeln mit `columnName` und `columnValue` abwärtskompatibel weiter unterstützen.
|
||
- [x] Einstellungsdialog um verkettete Regeln erweitern.
|
||
- [x] Optionale PortalSettings-Integration um einen zentralen Editor für verkettete Regeln erweitern.
|
||
- [x] Konfiguration validieren und verständliche Fehlermeldungen für ungültige Regelgruppen ausgeben.
|
||
- [x] Tests für `AND`, `OR`, gemischte Gruppen, fehlende Felder und Fallback auf die Standardregel ergänzen.
|
||
|
||
### Unterstützung klassischer SharePoint-Ansichten
|
||
|
||
- [x] Technisches Konzept für klassische Listen und Bibliotheken erstellen, da SPFx Field Customizer und ListView Command Sets dort nicht ausgeführt werden.
|
||
- [x] Darstellung und Zeilenverlauf für die klassische Ansicht über CSR/JSLink realisieren.
|
||
- [x] Die Aktion **„Ablaufdatum +1 Jahr“** in der klassischen Ribbon-/Listenoberfläche bereitstellen.
|
||
- [x] Zugriff auf die ExpiryIndicator-Einstellungen auch aus klassischen Ansichten ermöglichen.
|
||
- [x] Aktivierungs-, Deaktivierungs- und Upgrade-Skripte um die Classic-Registrierungen erweitern.
|
||
- [x] Dieselbe Konfiguration und dasselbe Regelverhalten in moderner und klassischer Ansicht verwenden.
|
||
- [ ] Funktions-, Berechtigungs- und Darstellungstests für klassische Listen und Dokumentbibliotheken ergänzen.
|
||
|
||
### Release 2.0
|
||
|
||
- [x] Versionsstände von Solution, Feature und SPFx-Komponenten auf `2.0.1` anheben.
|
||
- [x] README um V2-Regeln, Classic-Aktivierung und Deaktivierung ergänzen.
|
||
- [x] Pakete mit Node.js 8.17.0 erstellen und lokale Package-Validierung erfolgreich ausführen.
|
||
- [ ] Feature-Upgrade in SharePoint Server Subscription Edition testen.
|
||
- [ ] Modern-/Classic-Abnahmetest auf einer Testliste und einer Test-Dokumentbibliothek durchführen.
|
||
|
||
## Release 2.1 – zentrale Site-Collection-Konfiguration
|
||
|
||
- [x] Hierarchie `Liste > Subweb > Site Collection > eingebauter Standard` implementieren.
|
||
- [x] Moderne und klassische Laufzeit auf dieselbe Vererbungskette umstellen.
|
||
- [x] Solution-Descriptor und Bindungsinventar im Property Bag des Root Webs registrieren.
|
||
- [x] Bestehende vollständige Listenkonfigurationen beim erneuten Aktivieren erhalten.
|
||
- [x] Neue beziehungsweise leere Bindungen standardmäßig auf zentrale Vererbung stellen.
|
||
- [x] PortalSettings um providerbasierte Erkennung installierter Solutions erweitern.
|
||
- [x] ExpiryIndicator-Tab nur bei erkanntem Descriptor, Standard oder Bindungsinventar anzeigen.
|
||
- [x] Site-Collection-Standard in PortalSettings laden, validieren und speichern.
|
||
- [x] Registrierte Bindungen aus Root Web und Subwebs in PortalSettings anzeigen.
|
||
- [x] Einzelne oder alle registrierten Bindungen auf Vererbung umstellen können.
|
||
- [x] Versionen anheben und ExpiryIndicator- sowie PortalSettings-Pakete mit Node.js 8.17.0 bauen.
|
||
- [ ] Upgrade und zentrale Vererbung in SharePoint Server Subscription Edition testen.
|
||
- [ ] Berechtigungen mit Site-Collection-Administrator und normalem Listenverwalter prüfen.
|
||
|
||
## Abnahmekriterien
|
||
|
||
- Die Solution enthält und provisioniert keine Definition für eine fachliche Ablaufdatumsspalte.
|
||
- Erstellungsfeld, Ablaufdatumsfeld und Bedingungsfelder sind über interne Feldnamen konfigurierbar.
|
||
- Unterschiedliche Laufzeiten und Farbschwellen können anhand priorisierter Feldwertregeln bestimmt werden.
|
||
- Die Anzeige funktioniert in modernen Ansichten von Listen und Dokumentbibliotheken.
|
||
- Regeln und Farben sind pro Liste/Bibliothek ohne Codeänderung konfigurierbar.
|
||
- Leere Ablaufdaten werden aus `Created` und der Grundlaufzeit berechnet.
|
||
- Der Verlängerungsbefehl erhöht das effektive Ablaufdatum um genau ein Kalenderjahr.
|
||
- Mehrfachauswahl führt nicht zum vollständigen Abbruch, wenn einzelne Elemente nicht aktualisiert werden können.
|
||
- Benutzer ohne Bearbeitungsrechte können keine Elemente verlängern.
|
||
- Nur Listenverwalter können die Konfiguration ändern.
|