ExpiryIndicator/README.md

ExpiryIndicator

SPFx-1.4.1-Solution für moderne Listen und Dokumentbibliotheken in SharePoint Server Subscription Edition.

Funktionen

• Farbliche Anzeige einer vorhandenen, frei wählbaren Ablaufdatumsspalte.
• Fallback-Berechnung aus einem konfigurierbaren Erstellungsfeld und defaultLifetime.
• Priorisierte Regeln mit eigener Laufzeit und eigenen Farbschwellen anhand vorhandener Feldwerte.
• Command-Bar-Befehl zum Verlängern eines oder mehrerer Elemente um ein Kalenderjahr.
• Pro Liste/Bibliothek gespeicherte Konfiguration.

Die Solution provisioniert ausdrücklich keine fachliche Ablaufdatumsspalte und keinen Content Type.

Regelauswertung

rules werden von oben nach unten geprüft. Für jede Regel gilt:

1. Das konfigurierte interne Feld muss in der Liste/Bibliothek existieren.
2. Erst dann wird sein Wert geprüft.
3. Die erste Regel mit passendem columnValue bestimmt lifeTime und columnRule.
4. Wenn keine Regel passt oder keines der Regelfelder vorhanden ist, gilt der gesamte default-Block.

Beispiel der intern gespeicherten Gesamtstruktur (nicht vollständig in eines der JSON-Felder des Dialogs einfügen):

{
  "baseField": "Created",
  "expiryField": "ExpiryDate",
  "default": {
    "lifeTime": { "value": 2, "unit": "years" },
    "columnRule": [
      {
        "daysUntilExpiry": 0,
        "operator": "lessOrEqual",
        "backgroundColor": "#a4262c",
        "textColor": "#ffffff",
        "label": "Abgelaufen"
      }
    ]
  },
  "rules": [
    {
      "columnName": "DataPrivacy",
      "columnValue": "PersDat1",
      "lifeTime": { "value": 1, "unit": "years" },
      "columnRule": [
        {
          "daysUntilExpiry": 30,
          "operator": "lessOrEqual",
          "backgroundColor": "#ffaa44",
          "textColor": "#000000",
          "label": "Läuft bald ab"
        }
      ]
    }
  ]
}

Konfiguration über "Expiry-Einstellungen"

Voraussetzungen

1. Die App muss in der betreffenden Site installiert sein.
2. Die Liste oder Bibliothek muss die moderne Oberfläche verwenden.
3. Der angemeldete Benutzer benötigt die SharePoint-Berechtigung Listen verwalten.
4. Das konfigurierte Ablaufdatumsfeld muss bereits vorhanden sein. Die Solution legt dieses Feld nicht an.

Nach der Installation erscheint in modernen Listen und Dokumentbibliotheken der Befehl Expiry-Einstellungen in der Befehlsleiste. Falls der Befehl nicht sichtbar ist, zunächst prüfen, ob die App in der Site installiert und die Berechtigung Listen verwalten vorhanden ist.

Interne Feldnamen ermitteln

Es müssen interne SharePoint-Feldnamen verwendet werden, nicht die angezeigten Spaltennamen.

1. Listeneinstellungen beziehungsweise Bibliothekseinstellungen öffnen.
2. Die gewünschte Spalte anklicken.
3. In der URL den Wert hinter Field= ablesen.

Beispiel: Bei ...FldEdit.aspx?Field=DataPrivacy lautet der interne Feldname DataPrivacy. Ein Anzeigename wie "Ablaufdatum" kann intern beispielsweise ExpiryDate oder CustomerExpiryDate heißen.

Allgemeine Einstellungen

• Internes Basis-Datumsfeld: Ausgangsdatum für die Berechnung, normalerweise Created.
• Internes Ablaufdatumsfeld: Vorhandenes Datumsfeld, beispielsweise ExpiryDate.
• Standardlaufzeit: Zahl für die Laufzeit, beispielsweise 2.
• Einheit: days, months oder years.
• Verlängerung vorher bestätigen: Zeigt vor der Verlängerung eine Sicherheitsabfrage.
• Text bei fehlendem Datum: Wird angezeigt, wenn weder Basis- noch Ablaufdatum gelesen werden können.

Ist das Ablaufdatumsfeld eines Elements bereits gefüllt, wird dieser gespeicherte Wert verwendet. Nur bei einem leeren Ablaufdatumsfeld wird das Datum aus Basisdatum plus passender Laufzeit berechnet. Ein berechnetes Datum wird durch die Anzeige allein nicht in das SharePoint-Feld geschrieben.

Standard-Farbregeln

In Standard-Farbregeln wird nur das JSON-Array für default.columnRule eingetragen:

[
  {
    "daysUntilExpiry": 0,
    "operator": "lessOrEqual",
    "backgroundColor": "#a4262c",
    "textColor": "#ffffff",
    "label": "Abgelaufen"
  },
  {
    "daysUntilExpiry": 30,
    "operator": "lessOrEqual",
    "backgroundColor": "#ffaa44",
    "textColor": "#000000",
    "label": "Läuft bald ab"
  },
  {
    "daysUntilExpiry": 90,
    "operator": "lessOrEqual",
    "backgroundColor": "#fff4ce",
    "textColor": "#000000",
    "label": "Beobachten"
  }
]

Die Farbregeln werden von oben nach unten ausgewertet; die erste passende Regel gewinnt. Deshalb muss <= 0 vor <= 30 und <= 90 stehen. Ohne passende Farbregel wird das Datum ohne besondere Farbe angezeigt. Eine passende Regel färbt die komplette SharePoint-Zeile mit einem durchgehenden Verlauf vom weißen SharePoint-Standardhintergrund links bis zur konfigurierten backgroundColor rechts. Die Auswahlspalte bleibt ungefärbt. textColor bestimmt die Schriftfarbe der eingefärbten Zellen. Ein konfiguriertes label wird in derselben SharePoint-Standardschrift direkt neben dem Datum dargestellt.

Unterstützte Operatoren:

Operator	Bedeutung
lessThan	Resttage kleiner als Grenzwert
lessOrEqual	Resttage kleiner oder gleich Grenzwert
equal	Resttage genau gleich Grenzwert
greaterOrEqual	Resttage größer oder gleich Grenzwert
greaterThan	Resttage größer als Grenzwert

Feldabhängige Regeln

In Feldwertregeln wird nur das JSON-Array für rules eingetragen. Folgendes Beispiel verwendet bei DataPrivacy = PersDat1 eine Laufzeit von einem Jahr und bei PersDat2 eine Laufzeit von drei Jahren:

[
  {
    "columnName": "DataPrivacy",
    "columnValue": "PersDat1",
    "lifeTime": {
      "value": 1,
      "unit": "years"
    },
    "columnRule": [
      {
        "daysUntilExpiry": 0,
        "operator": "lessOrEqual",
        "backgroundColor": "#a4262c",
        "textColor": "#ffffff",
        "label": "Abgelaufen"
      },
      {
        "daysUntilExpiry": 30,
        "operator": "lessOrEqual",
        "backgroundColor": "#ffaa44",
        "textColor": "#000000",
        "label": "Läuft bald ab"
      }
    ]
  },
  {
    "columnName": "DataPrivacy",
    "columnValue": "PersDat2",
    "lifeTime": {
      "value": 3,
      "unit": "years"
    },
    "columnRule": [
      {
        "daysUntilExpiry": 0,
        "operator": "lessOrEqual",
        "backgroundColor": "#a4262c",
        "textColor": "#ffffff",
        "label": "Abgelaufen"
      },
      {
        "daysUntilExpiry": 60,
        "operator": "lessOrEqual",
        "backgroundColor": "#ffaa44",
        "textColor": "#000000",
        "label": "Läuft bald ab"
      }
    ]
  }
]

Die Regeln werden von oben nach unten geprüft. Dabei gilt:

1. Existiert columnName in der Liste oder Bibliothek?
2. Entspricht der Feldwert dem konfigurierten columnValue?
3. Die erste passende Regel liefert Laufzeit und Farbregeln.
4. Existiert das Feld nicht oder passt kein Wert, werden Standardlaufzeit und Standard-Farbregeln verwendet.

Nach Speichern wird die Konfiguration pro Liste beziehungsweise Bibliothek in der ausgeblendeten Liste _ExpiryIndicatorConfiguration der aktuellen Site gespeichert. Anschließend die Ansicht neu laden.

Anzeige aktivieren

Der Field Customizer wird einmal pro Liste beziehungsweise Bibliothek mit dem mitgelieferten Skript an der Ablaufdatumsspalte registriert:

.\scripts\Enable-ExpiryIndicator.ps1 `
  -SiteUrl 'https://sharepoint/sites/fachbereich' `
  -ListTitle 'Dokumente' `
  -ExpiryFieldInternalName 'CustomerExpiryDate'

Der Wert von ExpiryFieldInternalName muss mit Internes Ablaufdatumsfeld in den Einstellungen übereinstimmen. Das Command Set wird durch die Installation der App registriert. Danach die Listenansicht neu laden.

Ablaufdatum um ein Jahr verlängern

Ein oder mehrere Elemente markieren und Ablaufdatum +1 Jahr auswählen. Ist bereits ein Ablaufdatum gespeichert, wird dieses um ein Kalenderjahr verlängert. Ist das Feld leer, wird zunächst das berechnete Ablaufdatum verwendet, um ein Jahr verlängert und anschließend in das Ablaufdatumsfeld geschrieben.

Der Befehl ist nur sichtbar, wenn das konfigurierte Ablaufdatumsfeld existiert, mindestens ein Element markiert wurde und der Benutzer Elemente bearbeiten darf.

Build

SPFx 1.4.1 verwendet die Legacy-Toolchain. Unterstützt wird Node.js 6 oder 8; empfohlen wird für reproduzierbare Builds Node.js 8.17.0.

npm install
npm run package

Das Paket wird als sharepoint/solution/expiry-indicator.sppkg erzeugt.

Installation

1. expiry-indicator.sppkg in den App Catalog der On-Premises-Farm laden.
2. Die App in der gewünschten Site installieren.
3. Eine moderne Liste/Bibliothek öffnen und wie im Abschnitt Konfiguration über "Expiry-Einstellungen" beschrieben konfigurieren.
4. Den Field Customizer mit der vorhandenen Ablaufdatumsspalte verbinden:

.\scripts\Enable-ExpiryIndicator.ps1 `
  -SiteUrl 'https://sharepoint/sites/fachbereich' `
  -ListTitle 'Dokumente' `
  -ExpiryFieldInternalName 'CustomerExpiryDate'

Das Skript ist in einer SharePoint Management Shell beziehungsweise auf einem Rechner mit den passenden SharePoint-CSOM-Assemblies und Zugriff auf die Site auszuführen.

Deaktivierung

.\scripts\Disable-ExpiryIndicator.ps1 `
  -SiteUrl 'https://sharepoint/sites/fachbereich' `
  -ListTitle 'Dokumente' `
  -ExpiryFieldInternalName 'CustomerExpiryDate'

Das Skript entfernt ausschließlich die Field-Customizer-Verknüpfung. Die Spalte und alle fachlichen Daten bleiben erhalten. Die Command-Set-Registrierung wird durch das Entfernen der App aus der Site beseitigt.