ExpiryIndicator/ToDo.md

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:

{
  "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

• 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.
• Settings-Application-Customizer mit URL-Aktivierung 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.

Roadmap Version 2.0

Logische Verkettung von Regeln

• Konfigurationsschema für mehrere Bedingungen innerhalb einer Regel definieren.
• Bedingungen mit den logischen Operatoren AND und OR verknüpfen können.
• Verschachtelte Bedingungsgruppen und eine eindeutige Auswertungsreihenfolge festlegen.
• Regel-Engine um die Auswertung verketteter Bedingungen erweitern.
• Bestehende Version-1-Regeln mit columnName und columnValue abwärtskompatibel weiter unterstützen.
• Einstellungsdialog um verkettete Regeln erweitern.
• Optionale PortalSettings-Integration um einen zentralen Editor für verkettete Regeln erweitern.
• Konfiguration validieren und verständliche Fehlermeldungen für ungültige Regelgruppen ausgeben.
• Tests für AND, OR, gemischte Gruppen, fehlende Felder und Fallback auf die Standardregel ergänzen.

Unterstützung klassischer SharePoint-Ansichten

• Technisches Konzept für klassische Listen und Bibliotheken erstellen, da SPFx Field Customizer und ListView Command Sets dort nicht ausgeführt werden.
• Darstellung und Zeilenverlauf für die klassische Ansicht über CSR/JSLink realisieren.
• Die Aktion „Ablaufdatum +1 Jahr“ in der klassischen Ribbon-/Listenoberfläche bereitstellen.
• Zugriff auf die ExpiryIndicator-Einstellungen auch aus klassischen Ansichten ermöglichen.
• Aktivierungs-, Deaktivierungs- und Upgrade-Skripte um die Classic-Registrierungen erweitern.
• 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

• Versionsstände von Solution, Feature und SPFx-Komponenten auf 2.0.1 anheben.
• README um V2-Regeln, Classic-Aktivierung und Deaktivierung ergänzen.
• 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

• Hierarchie Liste > Subweb > Site Collection > eingebauter Standard implementieren.
• Moderne und klassische Laufzeit auf dieselbe Vererbungskette umstellen.
• Solution-Descriptor und Bindungsinventar im Property Bag des Root Webs registrieren.
• Bestehende vollständige Listenkonfigurationen beim erneuten Aktivieren erhalten.
• Neue beziehungsweise leere Bindungen standardmäßig auf zentrale Vererbung stellen.
• PortalSettings um providerbasierte Erkennung installierter Solutions erweitern.
• ExpiryIndicator-Tab nur bei erkanntem Descriptor, Standard oder Bindungsinventar anzeigen.
• Site-Collection-Standard in PortalSettings laden, validieren und speichern.
• Registrierte Bindungen aus Root Web und Subwebs in PortalSettings anzeigen.
• Einzelne oder alle registrierten Bindungen auf Vererbung umstellen können.
• Neue Bindungen per PortalSettings-Popup ohne PowerShell registrieren können.
• Optionale Classic-Aktionen beim Anbinden per PortalSettings idempotent registrieren.
• 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.