File reference
Value resolver – Abstract
Purpose: Allows reading, writing or deleting a file in the file system of the Lobster Data Platform server. The content of the referenced file is returned as a data object of the 'Content' type.
The File reference value resolver provides access to a file defined by an absolute or relative File path in the file system of the Lobster Data Platform server.
CAUTION
The Lobster Data Platform server provides 'public' read access for all files contained within the subfolder web of the designated upload folder via the URL for Lobster Data Platform / Orchestration.
Content saved to a File path starting with $home/web/ or an equivalent explicit path is therefore available without a Lobster Data Platform / Orchestration login.
A file saved to File path $home/web/gtc.htm can be read or downloaded via URL https://<pro_serverURL>/gtc.htm, without the use of credentials.
Files located within the upload folder but outside its web subfolder are accessible by the File manager within a Lobster Data Platform / Orchestration session.
A file with a File path like $home/logos/customer_4711.png is accessible by the File manager via the path ./logos/customer_4711.png,but not 'publicly' available via URL.
CAUTION
The
File reference resolver
grants access to parts of the server file system, that are not accessible by
File manager
. The following aspects should be considered carefully with respect to data security!
Event handling using the File reference resolver may not only read but also (re-)write or delete files.
Write and delete operations for files are irrevocably effective, even if executed in Tests!In the context of write operations any 'non-existing' folders will be created, if referred to within a File path.
The configuration file FileManager.xml (see example below) controls details for access to the server file system. Appropriately restrictive regulations should be applied there, to exclude risks from unauthorized or unintentional access.
<?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>Configuration
The File path parameter defines a text value, that is interpreted relative (if applicable) to the %HUB_HOME% folder of the Lobster Integration Server file system.
The File path can be defined either statically (via direct input) or dynamically – via any value resolver.
|
Static direct input for the file path |
|
|
In the example on the right, the File reference value resolver is to access a text file statically determined in the configuration with 'announcements', which an administrator can upload via the File manager to a dedicated subfolder of the upload directory for Lobster Data Platform / Orchestration. While the billboard subfolder appears in the File manager with the relative path ./billboard (see bottom right), the File path in the File reference value resolver must be formulated relative to the home directory of the Lobster integration server. As shown (see top right) the placeholder $home is used in the File path, which defines the path to the upload folder relative to the home directory of the Lobster Integration Server. A specific file path might look as follows: ./PRO/config/files/upload/billboard/admin_msg.txt ►NOTE◄ Depending on the configuration of the system, the File reference value resolver may allow access to files in the server's file system via absolute or relative file paths that are not accessible via File manager. The FileManager.xml configuration file (see below for details) can be used to control access to paths. |
Access via the File reference value resolver:
|
|
Select file via a Button |
|
|
The Select file Button opens a modal view for the File manager under the title File Picker, via which the path to a file determined by single selection can be adopted as a static value for the File path parameter using the Apply ribbon button. ►NOTE◄
|
File Picker via the File manager using the File Picker Button:
|
|
File path as return value of a resolver |
|
|
In the example on the right, the File path for the File reference value resolver is defined using a chain of value resolvers. Starting from a URL in the avatarURL field of a user account, the relative path to the profile picture of the respective user is obtained as a File path by multiple Replace text. Runtime example: for the Users 'admin' ./PRO/config/files/upload/web/avatar/user_avatar_admin.png ►NOTE◄ The profile image can be read under this path by File reference and used as a file attachment in a E-Mail event action. |
|
Read access
Provided that the file already exists at the specified location and there is read access on the server side, the value resolver returns an action event 'Content' object (Content) with the following properties of the file as a return value:
|
Field |
Data type |
Content |
Note |
|
name |
String |
File name |
The full File path does not appear as the file name. |
|
body |
Byte[](Array) |
File content (Byte Array) |
The number of bytes, i.e. the length of the byte array in the body field, defines the size of a file (in bytes). |
|
mediaType |
String |
not relevant in the context of the File reference value resolver |
|
If the specified File path cannot be resolved, the value resolver returns 'No value' ($null) on read access.
Write access (write/delete)
The File reference value resolver can be used as a target for a value assignment in a Set value event action, to perform write or delete operations.
Write or rewrite a file
Data assigned to the File reference value resolver is saved as the contents of the file specified in the File path, if the data type is appropriate (Content, String or byte[]).
If the file specified in the File path does not exist yet, it will be created.
If the File path refers to folders that do not yet exist, they will be created.
If the file specified in the File path already exists, it will be overwritten.
If the assigned value is of type 'Content' (Content) - for example provided by the File reference resolver (see 'Read access' above) - only the file content from the body field is copied to the target file.
Assignments of type 'byte array' (byte[]) or text (String) are applied immediately als content of the target file.
The name of the target file depends exclusively on the file name section of the given File path.
The file name should be followed by a significant and relevant extension, w.r.t to file content, as this may be crucial for the ability to 'View file' in the File manager.
►NOTE◄ It is possible to save a file without using an extension. However, this may lead to conflicts, when trying to create a folder using the same name as the file wihtin the same target folder:
|
In the example on the right a file named 04_APR (without an extension) was created in an archive folder, that should use that same name for a systematically created subfolder when there is data to archive for the month of April. Any attempt to save data to a File path like $home/archive/2020/04_APR/backlog.xml will fail, as long as this file exists. However, no error message or rollback will occur. The issue with creating the folder will only appear (in the 'Log') during Tests. |
|
Deleting a file or (empty) folder
If 'No value' ($null) is assigned to the File reference value resolver, this deletes the file specified in the File path.
Assigning 'No value' ($null) to the File path of an empty folder deletes this folder.
Assigning 'No value' ($null) to the File path of a non-empty folder is ineffective (wihtout error/notification).
►IMPORTANT◄ If a value of inappropriate data type (not Content, String or byte[]) is assigned to the File reference resolver, automatic type conversions fail rendering 'No value' ($null) as a result. If the given File path refers to an existing file or empty folder, they will be deleted.
Examples
► NOTE ◄ The following examples use the placeholder $home, that always refers to the upload folder, to make the File path robust against alternative configurations (via setHomeDirectory in the configuration file FileManager.xml).
Read access
For users with different Roles, specific instructions should appear as a notification when logging in to Lobster Data Platform / Orchestration, provided that a corresponding text file has been uploaded in a specific path of the server file system for the Role of session.
Runtime example:
|
|
This message is displayed via the Show alert (Popup) when logging in with the CustomerAccountManager role because it was placed as a text file with this name via the File manager in the ./billboard/roles folder (see left). |
Configuration:
|
An event handler that reacts to the Triggering event 'Client logged in' (see Login (Events)) is created and configured as shown on the right:
►NOTE◄ The file content can only be displayed directly to a popup because it is a text file where the 'body' provided as a byte array is readable as a character string. The same text appears as a string transformation if the Content action event object is assigned as a Message without explicitly accessing the body field. |
|
Write access (write)
Triggered by a Custom action event, a snapshot of a file named statusQuo.pdf is archived automatically as a copy.
The file path for the copy is defined as starting from the current date depending on the year (<yyy>) and month (<MM>) related to the time of execution, according to the following schema:
./journal/<yyyy>/<MM>/monthlyReport.pdf The file name of the copy is therefore always 'monthlyReport.pdf'.
The copy is always stored in the journal directory.
The subfolders for year and month are created automatically if they don't already exist.
If a copy already exists for the current month, it will be overwritten with the current data.
Configuration:
Creating the copy is accomplished within an event handler by a Set value event action as follows:
The content of the original file is transferred to the Content data object by the File reference value resolver on the right by read access.
On the left, another File reference value resolver implements the 'copying' of this data into the File path systematically built up by text concatenation:
The storage directory journal (at the top) and the file name monthlyReport.pdf (at the bottom) are defined statically.
In between, the string for the year ('yyyy') and month ('MM') folder levels is provided starting from today's date (see Relative date with time, 'Start today') via Format date.
CAUTION
For the Validating rule of the event handling, which is not described in detail here, a check whether the original file exists at all is strongly recommended. Otherwise, the target file (left) will be assigned 'No value'. If a copy already existed for the respective month, this copy will be permanently deleted (see 'Write access (delete)' below).
Runtime example:
If the event handling is executed on 11/02/2021, then the copy will appear at the location journal/2021/11 (subdirectory of the upload folder), which is controlled in the File manager above.
Write access (delete)
As an extension of the previous example ('Write access (write)'), the original file is to be deleted from the file system after copying.
Configuration:
The following Set value event action is attached to the event handling defined in the previous example:
The File reference value resolver on the left defines the File path of the file to be deleted by a static text value.
On the right, 'No value' is defined so that the file defined on the left is deleted.