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 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 Hintergrundfarbe, Textfarbe und optionale Beschriftung.

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:

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

• 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.