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.
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.
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.
<?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.
|
Statische Direkteingabe für den Dateipfad |
|
|
Im Beispiel rechts soll der Dateireferenz-Wertauflöser auf eine in der Konfiguration statisch bestimmte Textdatei mit "Bekanntmachungen" zugreifen, die ein Administrator über den Dateimanager in einen dedizierten Unterordner des upload-Verzeichnisses für Lobster Data Platform / Orchestration hochladen kann. Während der Unterordner billboard im Dateimanager mit dem relativen Pfad ./billboard erscheint (s. rechts unten), muss der Dateipfad im Dateireferenz-Wertauflöser relativ zum Heimatverzeichnis des Lobster Integration Servers formuliert werden. Im Bild rechts oben wird der Platzhalter $home verwendet, der den relativen Pfad vom Heimatverzeichnis zum konfigurierten upload-Verzeichnis repräsentiert. Der konkrete relative Dateipfad könnte hier z. B. lauten: ./PRO/config/files/upload/billboard/admin_msg.txt ►HINWEIS◄ Abhängig von der Konfiguration des Systems ermöglicht der Dateireferenz-Wertauflöser über absolute oder relative Dateipfade unter Umständen Zugriffe auf Dateien im Dateisystem des Servers, die per Dateimanager nicht zugänglich sind. Die Konfigurationsdatei FileManager.xml (Details s. u.) regelt, auf welche Verzeichnisse effektiv Zugriff besteht. |
Zugriff über den Dateireferenz-Wertauflöser:
|
|
Datei auswählen per Button |
|
|
Der Button Datei auswählen öffnet unter dem Titel Dateiauswahl eine modale Ansicht für den Dateimanager, über die der Pfad zu einer per Einfachauswahl bestimmten Datei per Ribbon Button Übernehmen als statischer Wert für den Parameter Dateipfad übernommen werden kann. ►HINWEISE◄
|
Dateiauswahl per Dateimanager via Button Datei auswählen:
|
|
Dateipfad als Rückgabewert eines Wertauflösers |
|
|
Im Beispiel rechts wird der Dateipfad für den Dateireferenz-Wertauflöser über eine Kette von Wertauflösern definiert. Ausgehend von einer URL im Feld avatarURL eines Benutzerkontos wird durch mehrfaches Text ersetzen der relative Pfad zum Profilbild des betreffenden Benutzers als Dateipfad gewonnen. Laufzeitbeispiel: für den Benutzer "admin" ./PRO/config/files/upload/web/avatar/user_avatar_admin.png ►ANMERKUNG◄ Das Profilbild kann unter diesem Pfad per Dateireferenz gelesen und z. B. als Dateianhang in einer E-Mail-Versand-Ereignisaktion verwendet 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:
|
Feld |
Datentyp |
Inhalt |
Hinweis |
|
name |
String |
Dateiname |
Als Dateiname erscheint nicht der komplette Dateipfad. |
|
body |
Byte[] (Array) |
Dateiinhalt (Byte-Array) |
Die Anzahl der Bytes, also die Länge des Byte-Arrays im Feld body, definiert die Größe einer Datei (in Byte). |
|
mediaType |
String |
im Kontext des Dateireferenz-Wertauflösers nicht relevant |
|
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:
|
Im Beispiel rechts wurde eine Datei mit dem Namen 04_APR ohne Dateierweiterung in einem Archiv-Ordner angelegt, in dem derselbe Name systematisch für einen Unterordner verwendet werden soll, sobald Daten für den Monat April zu archivieren sind. Der Versuch, Daten in einen Dateipfad wie $home/archive/2020/04_APR/backlog.xml zu archivieren, scheitert solange diese Datei existiert. Dabei tritt keine Fehlermeldung mit Rollback auf. Nur im Kontext von Tests erscheint im "Log" ein Hinweis auf das Problem beim impliziten Anlegen des Ordners. |
|
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:
|
|
Diese Nachricht wird beim Anmelden mit der Rolle CustomerAccountManager per Hinweis anzeigen (Popup) angezeigt, weil sie als Textdatei mit diesem Namen per Dateimanager im Ordner ./billboard/roles (s. links) platziert wurde. |
Konfiguration:
|
Eine Ereignisbehandlung, die auf das Auslösende Ereignis "Client angemeldet" (s. Anmeldung (Ereignisse)) reagiert, wird angelegt und wie rechts abgebildet konfiguriert:
►ANMERKUNG◄ Der Dateiinhalt kann nur direkt einem Popup angezeigt werden, weil es sich um eine Textdatei handelt, bei der der als Byte-Array bereitgestellte "body" als Zeichenfolge lesbar ist. Derselbe Text erscheint als String-Transformation, falls das Aktionsereignis-Inhalt-Objekt als Meldung zugeordnet wird, ohne explizit auf das Feld body zuzugreifen. |
|
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.