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.

Tooltip

• Usage:

  • In general, the file defined by File path is read. The body field of the returned 'Content' object then returns the (binary) file content as a byte array.

  • To write a file, the File reference value resolver must be used on the left side of an assignment via Set value.

  • To delete a file, the File reference value resolver must be assigned the value 'No value' ($null) via Set value.

  • When writing or deleting, the assigned value (updated content or 'No value') appears as the return value.

• Parameter: The File path parameter defines an absolute or relative path in the Lobster Data Platform server file system.

  • The start directory for the File manager (upload folder) can be addressed in the File path via the placeholder $home (e.g. $home/web/...).

  • The reference point for relative paths is the home directory of the Lobster Integration Server (%HUB_HOME%) and not the upload folder ($home).

• Warning: Writing and deleting files also works in test mode, i.e. when Tests are executed with an event handler.

• Warning: The deletion or overwriting of an existing file is always done without further inquiry.

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.

►IMPORTANT◄ Relative paths / 'File reference' vs. 'File manager'

---

The File reference resolver interprets relative file paths relative to the home directory of the Lobster Integration Server (%HUB_HOME%), that Lobster Data Platform / Orchestration is running on.

The File manager of Lobster Data Platform / Orchestration interprets relative file paths relative to the upload folder, which is a sub-folder of %HUB_HOME% designated by server configuration.

The following relative paths indicate typical locations for the upload folder of Lobster Data Platform / Orchestration:

• ./PRO/config/files/upload Default for current installation

• ./SCM/config/files/upload Default for legacy installations

• ./upload Alternative setting enabling shorter paths

---

►NOTE◄ The $home placeholder can be used in parameter File path of the File reference resolver, to address the configured upload folder, without explicitly indicating its relative path.

►NOTE◄ The Select file Button opens the File reference modal to enable a ‘file selection’ for the File path. However, this only works for files that are in or below the upload folder ($home).

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.

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

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

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:

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 within the same target folder:

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 (without 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:

Configuration:

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:

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