129 lines
6.8 KiB
Markdown
129 lines
6.8 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 nur für Listenverwalter sichtbaren Befehl **„Expiry-Einstellungen“**.
|
||
|
||
## 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 die Hintergrundfarbe der kompletten Zelle und deren Textfarbe.
|
||
|
||
Die Berechnung arbeitet mit Kalenderjahren/-monaten/-tagen, nicht mit pauschalen 365-Tage-Jahren.
|
||
|
||
### 2. ListView Command Set
|
||
|
||
`ExpiryIndicatorCommandSet` stellt in der modernen Befehlsleiste zwei Aktionen 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.
|
||
- **Expiry-Einstellungen**
|
||
- nur sichtbar für Benutzer mit `ManageLists`-Berechtigung,
|
||
- öffnet einen Konfigurationsdialog für die aktuelle Liste/Bibliothek.
|
||
|
||
### 3. Konfiguration
|
||
|
||
Die Konfiguration wird pro Liste anhand ihrer GUID gespeichert. Dafür verwendet die App eine eigene, versteckte Konfigurationsliste im aktuellen Web. Diese technische Liste darf von der Solution beziehungsweise beim ersten Speichern der Einstellungen erzeugt werden; 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": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4. Aktivierung und Deployment
|
||
|
||
- Erstellung eines `.sppkg`-Pakets mit eingebetteten Client-Side Assets.
|
||
- Registrierung des Command Sets für moderne generische Listen und Dokumentbibliotheken.
|
||
- 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.
|
||
- [ ] SPFx-1.4.1-Projektstruktur anlegen.
|
||
- [ ] gemeinsame Modelle, Datumsberechnung und Regel-Auswertung implementieren.
|
||
- [ ] Regel-Engine für feldwertabhängige Laufzeiten und Farbschwellen implementieren.
|
||
- [ ] REST-Service für Konfiguration und Elementaktualisierungen implementieren.
|
||
- [ ] Field Customizer implementieren.
|
||
- [ ] ListView Command Set und Einstellungsdialog implementieren.
|
||
- [ ] Feature-XML für Command-Bar-Registrierung erstellen.
|
||
- [ ] CSOM-Aktivierungs- und Deaktivierungsskripte für die vorhandene `ExpiryDate`-Spalte erstellen.
|
||
- [ ] Lokalisierung Deutsch/Englisch ergänzen.
|
||
- [ ] Build mit der SPFx-1.4.1-kompatiblen Legacy-Toolchain ausführen.
|
||
- [ ] `.sppkg` erzeugen und Installationsanleitung ergänzen.
|
||
- [ ] Tests für Kalenderarithmetik, Schwellwerte und leere Ablaufdaten durchführen.
|
||
|
||
## 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.
|