Dateireferenz

Wertauflöser - Kurzfassung

Zweck: Ermöglicht das Lesen, Schreiben oder Löschen einer Datei im Dateisystem des Lobster Data Platform-Servers. Der Inhalt der referenzierten Datei wird als Datenobjekt des Typs "Aktionsereignis-Inhalt" zurückgegeben.

Tooltip

• Verwendung:

  • Im Allgemeinen wird die per Dateipfad definierte Datei gelesen. Das Feld body des zurückgegebenen "Aktionsereignis Inhalt"-Objekts liefert dann den (binären) Dateiinhalt als Byte-Array.

  • Zum Schreiben einer Datei muss der Dateireferenz-Wertauflöser auf der linken Seite einer Zuweisung per Setze Wert verwendet werden.

  • Zum Löschen einer Datei muss dem Dateireferenz-Wertauflöser der Wert "Kein Wert" ($null) zugewiesen werden.

  • Beim Schreiben oder Löschen erscheint der zugewiesene Wert (aktualisierter Inhalt bzw. "kein Wert") als Rückgabewert.

• Parameter: Der Parameter Dateipfad definiert einen absoluten oder relativen Pfad im Dateisystem des Lobster Data Platform-Servers.

  • Das Startverzeichnis für den Dateimanager (upload -Ordner) kann im Dateipfad über den Platzhalter $home adressiert werden (z. B. $home/web/...).

  • Der Bezugspunkt für relative Pfade ist das Heimatverzeichnis des Lobster Integration Servers (%HUB_HOME%) und nicht etwa der upload-Ordner ($home).

• Warnung: Das Schreiben und Löschen von Dateien wirkt auch auch im Testmodus, also wenn mit einer Ereignisbehandlung Tests ausgeführt werden.

• Warnung: Das Löschen oder Überschreiben einer existierenden Datei erfolgt grundsätzlich ohne Rückfrage.

Der Dateireferenz-Wertauflöser ermöglicht das Lesen, Schreiben oder Löschen einer über den absoluten oder relativen Dateipfad definierten Datei im Dateisystem des Lobster Data Platform / Orchestration-Servers.

►WICHTIG◄ Relative Pfade / "Dateireferenz" vs. "Dateimanager"

---

Der Dateireferenz-Wertauflöser interpretiert relative Dateipfade ausgehend vom Heimatverzeichnis des Lobster Integration Servers (%HUB_HOME%), auf dem Lobster Data Platform betrieben wird.

Der Dateimanager von Lobster Data Platform / Orchestration interpretiert relative Dateipfade ausgehend vom upload-Ordner. Bei diesem handelt es sich um ein in der Serverkonfiguration festgelegtes Unterverzeichnis von %HUB_HOME%.

Typische relative Pfade zum upload-Ordner für Lobster Data Platform / Orchestration:

• ./PRO/config/files/upload Standard für aktuelle Installationen

• ./SCM/config/files/upload Standard in früheren Installationen

• ./upload alternative Einstellung für kürzere Dateipfade

---

►HINWEIS◄ Der Platzhalter $home kann im Parameter Dateipfad des Dateireferenz-Wertauflösers verwendet werden, um den konfigurierten upload-Ordner zu adressieren ohne den relativen Pfad explizit anzugeben.

►HINWEIS◄ Der Button Datei auswählen öffnet den Dateimanager modal, um eine "Dateiauswahl" für den Dateipfad zu ermöglichen. Allerdings funktioniert diese nur für Dateien die in oder unterhalb des upload -Ordners ($home) liegen.

ACHTUNG Der Lobster Data Platform-Server stellt alle Dateien innerhalb des des web-Unterverzeichnisses des designierten upload-Ordners über die URL für Lobster Data Platform / Orchestration "öffentlich" bereit.

• Inhalte, die in einen Dateipfad geschrieben werden, der mit $home/web oder einer gleichwertigen expliziten Pfadangabe beginnt, sind also auch ohne Lobster Data Platform / Orchestration-Anmeldung abrufbar.

  • Eine Datei im Dateipfad $home/web/gtc.htm kann über die URL https://<pro_serverURL>/gtc.htm ohne Anmeldedaten gelesen oder heruntergeladen werden.

• Auf Dateien, die sich innerhalb des upload-Ordners aber nicht in dessen web-Unterverzeichnis befinden, kann im Kontext einer Lobster Data Platform / Orchestration-Sitzung per Dateimanager zugegriffen werden.

  • Auf eine Datei mit dem Dateipfad wie $home/logos/customer_4711.png kann per Dateimanager über den Pfad ./logos/customer_4711.png interaktiv zugegriffen werden. Sie ist aber nicht "öffentlich" per URL abrufbar.

ACHTUNG Der Dateireferenz-Wertauflöser ermöglicht Zugriffe im Dateisystem des Servers, die über den Dateimanager nicht möglich sind. Beachten Sie folgende Hinweise mit Blick auf die Datensicherheit!

• Ereignisbehandlungen können über den Dateireferenz-Wertauflöser Dateien nicht nur lesen sondern auch (über-)schreiben oder löschen.
  Das Schreiben und Löschen von Dateien ist auch in Tests sofort und unwiderruflich wirksam!

• Im Kontext eines Schreibzugriffs werden bei Bedarf "fehlende" Ordner neu erstellt, die der Dateipfad benennt.

• Die Konfigurationsdatei FileManager.xml (s. folgendes Beispiel) definiert wichtige Details für den Zugriff auf das Dateisystem. Dort sollten geeignet restriktive Regelungen getroffen werden, um Risiken durch unbefugte bzw. unbeabsichtigte Zugriffe auszuschließen.
  

PRO/config/etc/systemManagers/de.lobster.scm.system.FileManager.xml (Beispiel)

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC
 "-//EBD Integration//DTD Configure 1.3//EN"
 "http://www.ebd-integration.de/dtd/configure_1_3.dtd">
<Configure class="de.lobster.scm.system.FileManager">
    <Call name="setHomeDirectory"><Arg><SystemProperty name="scm.home" default="./SCM" />/config/files/upload</Arg></Call>
 
	<!-- default allowed path entries are ./conf/ -->
	<!-- to clear default list, call following method: -->
    <!--<Call name="clearAllowedFilePaths"></Call> -->
    <Call name="addAllowedFilePath"><Arg>/tmp</Arg></Call>
</Configure>

Konfiguration

Der Parameter Dateipfad definiert einen Textwert, der im Dateisystem des Lobster Integration Servers relativ zum %HUB_HOME%-Verzeichnis interpretiert wird.

Der Dateipfad kann wahlweise statisch (per Direkteingabe) oder dynamisch - über beliebige Wertauflöser - definiert werden.

Lesezugriff

Sofern die Datei am angegebenen Ort bereits existiert und serverseitig Lesezugriff besteht, gibt der Wertauflöser als Rückgabewert ein "Aktionsereignis-Inhalt"-Objekt (Content) mit den folgenden Eigenschaften der Datei zurück:

Falls der angegebene Dateipfad nicht aufgelöst werden kann, gibt der Wertauflöser beim Lesezugriff "Kein Wert" ($null) zurück.

Schreibzugriff (Schreiben/Löschen)

Der Dateireferenz-Wertauflöser kann in einer Setze Wert-Ereignisaktion als Ziel für eine Wertzuweisung eingesetzt werden, die entweder schreibend oder löschend wirkt.

Schreiben oder Überschreiben einer Datei

Dem Dateireferenz-Wertauflöser zugewiesene Daten werden als Inhalt der im Dateipfad angegebenen Datei gespeichert, sofern der Datentyp geeignet ist (Content, String oder byte[]).

• Existiert die im Dateipfad angegebene Datei noch nicht, wird sie erstellt.

• Beinhaltet der Dateipfad Ordner, die noch nicht existieren, werden diese erstellt.

• Existiert die im Dateipfad angegebene Datei bereits, wird sie überschrieben.

Handelt es sich beim zugewiesenen Wert um den Typ "Aktionsereignis-Inhalt" (Content) - z. B. aus einem Lesezugriff per Dateireferenz (s. o.) - wird nur der Dateiinhalt aus dessen body-Feld in die Zieldatei übernommen.

Die Zuweisung eines Byte-Arrays (byte[]) oder Textwerts (String) betrifft unmittelbar den Inhalt der Zieldatei.

• Der Name der Zieldatei hängt ausschließlich vom Dateinamen im Dateipfad ab.

• Der Dateiname sollte mit einer signifikanten und auf den Inhalt abgestimmten Dateierweiterung enden, da diese ausschlaggebend für den Erfolg eines Zugriffs über die Funktion "Datei anzeigen" im Dateimanager sein kann.

►HINWEIS◄ Eine Datei kann zwar auch ohne Angabe einer Dateierweiterung gespeichert werden. Allerdings führt dies zu Konflikten, falls später in demselben Zielordner ein Ordner mit dem Namen dieser Datei erstellt werden soll:

Löschen einer Datei oder eines (leeren) Ordners

• Wird dem Dateireferenz-Wertauflöser "Kein Wert" ($null) zugewiesen, löscht das die per Dateipfad angegebene Datei.

  • Das Zuweisen von "Kein Wert" ($null) an den Dateipfad eines leeren Ordners löscht diesen Ordner.

  • Das Zuweisen von "Kein Wert" ($null) an den Dateipfad eines nicht-leeren Ordners wird ohne Fehlermeldung ignoriert.

►WICHTIG◄ Falls im Kontext einer Zuweisung an den Dateireferenz-Wertauflöser ein ungeeigneter Datentyp (nicht Content, String oder byte[]) als Wert zugewiesen wird, schlägt der Versuch einer automatischen Typumwandlung mit dem Ergebnis "Kein Wert" ($null) fehl. Sofern unter dem angegebenen Dateipfad eine Datei oder ein leerer Ordner existiert, wird diese gelöscht!

Beispiele

►HINWEIS◄ Die folgenden Beispiele verwenden den Platzhalter $home, der immer auf den upload -Ordner verweist, um den Dateipfad robust gegen abweichende Konfigurationen (per setHomeDirectory in der Konfigurationsdatei FileManager.xml) zu machen.

Lesezugriff

Für Benutzer mit unterschiedlichen Rollen sollen beim Anmelden an Lobster Data Platform / Orchestration spezifische Hinweise als Benachrichtigung erscheinen, sofern für die Rolle der Session eine entsprechende Textdatei in einem bestimmten Pfad des Server-Dateisystems hochgeladen wurde.

Laufzeitbeispiel:

Konfiguration:

Schreibzugriff (Schreiben)

Ausgelöst durch ein Eigenes Aktionsevent soll automatisch ein Schnappschuss einer Datei mit dem Namen statusQuo.pdf als Kopie archiviert werden.

Der Dateipfad für die Kopie soll ausgehend vom Tagesdatum abhängig vom Jahr (<yyyy>) und Monat (<MM>) bezogen auf den Ausführungszeitpunkt nach folgendem Schema definiert sein:

$home/journal/<yyyy>/<MM>/monthlyReport.pdf

• Der Dateiname der Kopie lautet also immer "monthlyReport.pdf".

• Die Kopie wird immer im Verzeichnis journal abgelegt.

• Die Unterordner für Jahr und Monat sind entweder bereits vorhanden oder werden automatisch erstellt.

• Existiert für den aktuellen Monat bereits eine Kopie, wird diese mit den aktuellen Daten überschrieben.

Konfiguration:

Das Erstellen der Kopie wird innerhalb einer Ereignisbehandlung durch eine Setze Wert-Ereignisaktion wie folgt bewerkstelligt:

• Der Inhalt der Originaldatei wird durch den Dateireferenz-Wertauflöser rechts per Lesezugriff in ein Aktionsereignis-Inhalt-Datenobjekt übertragen.

• Links wird durch einen weiteren Dateireferenz-Wertauflöser das "Kopieren" dieser Daten in den per Textverkettung systematisch aufgebauten Dateipfad realisiert:
  

  • Das Ablageverzeichnis journal (ganz oben) und der Dateiname monthlyReport.pdf (ganz unten) sind dabei statisch definiert.

  • Dazwischen wird die Zeichenfolge für die Ordnerebenen Jahr (yyyy) und Monat (MM) ausgehend vom Tagesdatum (s. Relatives Datum mit Zeit, "Anfang heute") per Datum formatieren passend bereitgestellt.

ACHTUNG Für die "Prüfende Regel" der hier nicht ausführlich dargestellten Ereignisbehandlung ist eine Prüfung, ob die Originaldatei überhaupt vorhanden ist, dringend zu empfehlen. Anderenfalls wird der Zieldatei (links) "Kein Wert" als Wert zugewiesen. Existierte für den jeweiligen Monat bereits eine Kopie, wird diese Kopie dadurch unwiderruflich gelöscht (s. u. "Schreibzugriff (Löschen)").

Laufzeitbeispiel:

• Wird die Ereignisbehandlung am 29.10.2021 ausgeführt, dann erscheint die Kopie am oben im Dateimanager angesteuerten Pfad journal/2021/10 (Unterverzeichnis des upload-Ordners).

Schreibzugriff (Löschen)

Als Erweiterung des vorigen Beispiels ("Schreibzugriff (Schreiben)"), soll die Originaldatei nach dem Kopieren aus dem Dateisystem gelöscht werden.

Konfiguration:

Die folgende Setze Wert-Ereignisaktion wird an die im vorigen Beispiel definierte Ereignisbehandlung angehängt:

• Der Dateireferenz-Wertauflöser links definiert den Dateipfad der zu löschenden Datei durch einen statischen Textwert.

• Rechts wird "Kein Wert" definiert, damit die links definierte Datei gelöscht wird.

Dateireferenz