File Storage

The FNZ Studio Platform offers two ways to store files:

  • As local files stored directly in the local file system.
  • As cluster files which reside in a virtual directory hierarchy, which makes them available on all nodes of a clustered FNZ Studio installation.

Note: When generating PDF documents in FNZ Studio, a third variant is available: virtual files. If stored as a virtual file, the generated PDF document is stored only in memory and is accessible only for a configured time frame before it is deleted

On multi-node FNZ Studio installations, the cluster file type ensures that files are accessible on all nodes and remain available if a node fails. For installations running on a single server, using cluster files reduces the effort necessary to upgrade to multiple nodes at a later point in time.

The local file type can be used when a file does not need to be accessible on all nodes. For example, you may want to store a large temporary email attachment in the local file system in order to save memory space.

In FNZ Studio's Script Language, a file is represented by an instance of the Primitive Types ClusterFile or LocalFile. A ClusterFile object represents a global file accessible on all nodes, while a LocalFile object represents a file on the local file system. Both the ClusterFile and LocalFile Primitive Types can be used to perform file management operations such as read, write, move, copy, etc.

Alternatively, you can perform basic file operations using a set of Script Functions. If only a single operation on a file is required during a Process, it can be more convenient to call a global Script Function and thus avoid initializing a ClusterFile or LocalFile object to represent that file.

File Operations with Primitive Types

ClusterFile Primitive Type

A ClusterFile instance is a reference to a cluster file, similar to the "File" beans in other languages (e.g. java.io.File). It is instantiated with the cluster file's path (equivalent to the ID) as a parameter:

Copy
$clusterFile := NewObject(ClusterFile, $path);

Parameters:

  • $path (String) - Specifies the path (= ID) of the cluster file.

Once the ClusterFile object is initialized, use the methods listed in the table below to perform file operations.

Method Description
.exists()
Returns Boolean		 Checks if the cluster file represented by $clusterFile exists. Returns true if the cluster file exists.
$clusterFile.exists()
Parameters:
none
.getPath()
Returns String		 Gets the path (ID) of the cluster file represented by $clusterFile. Returns the cluster file's path.
$clusterFile.getPath()
Parameters:
none
.readText()
Returns String		 Reads the content of the cluster file as a String using the given encoding.
$clusterFile.readText($encoding)
Parameters:
$encoding (String, optional): encoding to be used. If not set, the default encoding is UTF-8.
.writeText()
Returns Nothing		 Writes the given text into the cluster file represented by $clusterFile, using the given encoding. If the file already exists, it is overwritten.
$clusterFile.writeText($text, $encoding)
Parameters:
$text (String): text to be written into the cluster file.
$encoding (String, optional): encoding to be used. If this parameter is not set, the default encoding is UTF-8.
.moveTo()
Returns ClusterFile		 Moves the cluster file represented by $clusterFile to the given cluster file path. After this operation, $clusterFile does not exist anymore.
Returns the cluster file at the new location.
$clusterFile.moveTo($dstClusterFilePath)
//or
$clusterFile.moveTo($dstClusterFile)
Parameters:
$dstClusterFilePath (String): path of the destination cluster file.
or
$dstClusterFile (ClusterFile)
.copyTo()
Returns ClusterFile		 Copies the cluster file represented by $clusterFile to the given cluster file path. Returns the cluster file at the new location.
$clusterFile.copyTo($dstClusterFilePath)
//or
$clusterFile.copyTo($dstClusterFile)
Parameters:
$dstClusterFilePath (String): path of the destination cluster file.
or
$dstClusterFile (ClusterFile)
.copyFromLocal()
Returns Nothing		 Copies the given local file into the cluster file represented by $clusterFile.
$clusterFile.copyFromLocal($localFilePath)
//or
$clusterFile.copyFromLocal($localFile)
Parameters:
$localFilePath (String): path to local file (absolute or relative to the datahome).
or
$localFile (LocalFile)
.copyToLocal()
Returns Nothing		 Copies the cluster file represented by $clusterFile to a local file with the given path. The parameter $localFilePath is an absolute path or one relative to the datahome; it must include the name of the local file to be created.
$clusterFile.copyToLocal($localFilePath)
//or
$clusterFile.copyToLocal($localFile)
Parameters:
$localFilePath (String): path to local file (absolute or relative to the datahome).
or
$localFile (LocalFile)
.delete()
Returns Nothing		 Deletes the cluster file represented by $clusterFile.
$clusterFile.delete()
Parameters:
None

Example

  1. Copy a local file to cluster storage. PDFs that are generated with FNZ Studio are stored on the local file system. If you need to move a PDF to the cluster to make it available on all nodes, use the following script:

    Copy
    // Create a new cluster file with the path 'my-docs/my-document.pdf'
    ClusterFile $cf := NewObject(ClusterFile, 'my-docs/my-document.pdf');
    //Copy the PDF from local storage to cluster storage
    $cf.copyFromLocal($configuration.fileLocation);

    $configuration is an instance of PdfRenderConfiguration. It is used as configuration for the "Generate PDF" Task which stores the path of the generated file into the field $configuration.fileLocation.

  2. Move the file to a new location.

    Copy
    // Create a new cluster file with the destination path 'another-location/my-document.pdf'
    ClusterFile $newCf := NEW(ClusterFile, 'another-location/my-document.pdf');
    // Move the old file to the new location
    $cf.moveTo($newCf);

  3. Delete the file. Finally, if you no longer need the file, you can delete it as follows:

    Copy
    $newCf.delete()

LocalFile Primitive Type

A LocalFile instance is a reference to a file or a directory on one node's local file system. It is instantiated with the file's path (absolute of relative to the datahome) as a parameter:

  • Complete file path

    Copy
    LocalFile $localFile := NewObject(LocalFile, $path)
    $path (String) - Path to the local file (absolute or relative to the datahome)

  • File's parent path and file name

    Copy
    LocalFile $localFile := NewObject(LocalFile, $parentPath, $fileName)

    $parentPath (String) - Path to the file's parent directory (absolute or relative to the datahome)

    $fileName (String) - The file's name

  • Path to the file's parent directory (represented by another LocalFile instance) and file name

    Copy
    LocalFile $localFile := NewObject(LocalFile, $parentFile, $fileName)

    $parentPath (LocalFile) - Path to the file's parent directory

    $fileName (String) - The file's name

Once initialized, a LocalFile object representing a directory can be used to create, move, copy or delete that directory. If it represents a regular file, it can be used to read content from a file, write to it or perform file management operations like moving, copying, and deleting.

To move a local file to cluster storage or a cluster file to local storage, use a ClusterFile object (see section ClusterFile Primitive type).

Method Description
.exists()
Returns Boolean		 Checks if the local file represented by $localFile exists. Returns true if the file exists.
$localFile.exists()
Parameters:
none
.getPath()
Returns String		 Gets the local file's path.
$localFile.getPath()
Parameters:
none
.getName()
Returns String		 Gets the local file's name.
$localFile.getName()
Parameters:
none
.writeText()
Returns nothing		 Writes the given text into the local file represented by $localFile, using the given encoding. Any parent directories in the path that do not yet exist are created. If the file already exists, it is overwritten. Throws an IOException if there is an error while writing the file.
$localFile.writeText($text, $encoding)
Parameters:
$text (String): text to be written into the file
$encoding (String, optional): encoding to be used. If this parameter is not set, the default encoding is UTF-8.
.readText()
Returns String		 Reads the content of this local file as a String, using the given encoding. Throws an IOException if there is an error while writing the file.
$localFile.readText($encoding)
Parameters:
$encoding (String, optional): the encoding to be used. If not set, the default encoding is UTF-8
.makeDirectory()
Returns nothing		 Creates a directory at the path of the local file represented by $localFile. Any parent directories in the path that do not yet exist are created.
$localFile.makeDirectory()
Parameters:
none
.isDirectory()
Returns Boolean		 Checks if the local file represented by $localFile is a directory. Returns true if it is a directory, false if it is a simple file.
$localFile.isDirectory()
Parameters:
None
.moveInto()
Returns LocalFile		 Moves the local file represented by $localFile into the given local directory. Directories in a path that do not exist are created. Note: After this operation, the local file represented by $localFile does not exist anymore. Returns the local file at the new location. Throws an IOException if there is an error while reading the file at the source or writing the file at the destination location.
$localFile.moveInto($dstDirectoryPath)
//or
$localFile.moveInto($dstDirectory)
Parameters:
$dstDirectoryPath (String): path to the destination directory (absolute or relative to the datahome)
or
$dstDirectory (LocalFile)
.moveTo()
Returns LocalFile		 Moves the local file represented by $localFile to another location. Directories in the destination path that do not exist are created. Note: After this operation, the local file represented by $localFile does not exist anymore. Returns the local file at the new location. Throws an IOException if there is an error while reading the file at the source or writing the file at the destination location.
$localFile.moveTo($dstFilePath)
//or
$localFile.moveTo($dstFile)
Parameters:
$dstFilePath (String): path to the destination file (absolute or relative to the datahome)
or
$dstFile (LocalFile)
.copyTo()
Returns LocalFile		 Copies the local file represented by $localFile to the given local file path. Returns the local file at the new location. Throws an IOException if there is an error while reading the file at the source or writing the file at the destination location.
$localFile.copyTo($dstFilePath)
//or
$localFile.copyTo($dstLocalFile)
Parameters:
$dstFilePath (String): path to the destination file (absolute or relative to the datahome)
or
$dstLocalFile (LocalFile)
.copyInto()
Returns LocalFile		 Copies the local file represented by $localFile into the given local directory. Directories in the path that do not exist are created. Returns the local file at the new location. Throws an IOException if there is an error while reading the file at the source or writing the file at the destination location.
$localFile.copyInto($dstDirectoryPath)
//or
$localFile.copyInto($dstDirectory)
Parameters:
$dstDirectoryPath (String): path to the destination directory (absolute or relative to the datahome)
or
$dstDirectory (LocalFile)
.delete()
Returns nothing		 Deletes the local file represented by $localFile. If it is a directory, the directory and all of its content are deleted recursively. Throws IOException if there is an error while deleting a directory recursively.
$localFile.delete()
Parameters:
None

File Operations with Script Functions

Use the built-in Script Functions listed in this chapter to perform basic file operations anywhere in a script.

Cluster File Functions

ListClusterFiles()

The Script Function ListClusterFiles() lists all cluster file paths (or, equivalently, IDs), optionally filtered with a given regular expression.

Copy
ListClusterFiles()

Parameter Description
$filterExpression
String, Optional		 A regular expression that is used to filter the cluster file paths.
Example: 'foo/bar/.*'

Return value Description
Indexed ClusterFile An indexed collection of the cluster files available in memory.
Note that if you are evicting cluster files they are removed from memory after the defined lifetime and will not be returned by ListClusterfiles after being evicted.
Example:
Copy 
ListClusterFiles(null)

READCLUSTERFILE()

The Script Function READCLUSTERFILE() reads the content of the given cluster file into a String.

Copy
READCLUSTERFILE($filepath)

Parameter Description
$filepath
String		 The path to the file.
Example: 'foo/bar/thefile.txt'
$encoding
String, Optional		 The encoding of the file, default is 'UTF-8'.
Example: 'UTF-8'

Return value Description
String Content of the given file or null if the file does not exist.
Example:
Copy 
READCLUSTERFILE('foo/bar/thefile.txt', 'UTF-8')

WRITECLUSTERFILE()

The Script Function WRITECLUSTERFILE() writes the given string into a cluster file at the given path. Any already existing file at this location is overwritten.

Copy
WRITECLUSTERFILE($filepath, $data)

Parameter Description
$filepath
String		 The path to the file.
Example: 'foo/bar/thefile.txt'
$data
String		 The content of the file to be written.
Example: 'This is the file content.'
$encoding
String, Optional		 The encoding of the file, default is 'UTF-8'.
Example: 'UTF-8'


Returns Nothing

Example:
Copy 
WRITECLUSTERFILE('foo/bar/thefile.txt', 'This is the file content.', 'UTF-8')

DELETECLUSTERFILE()

The Script Function DELETECLUSTERFILE() deletes the cluster file with the given path (ID). If the file does not exist, nothing is done.

Copy
DELETECLUSTERFILE($filepath)

Parameter Description
$filepath
String		 The path to the file to delete.
Example: 'foo/bar/thefile.txt'


Returns Nothing

Example:
Copy 
DELETECLUSTERFILE('foo/bar/thefile.txt')

Local File Functions

FILEEXISTS()

Copy 
FILEEXISTS($path)
Parameter Description
$path
String		 The file to check
Example: 'infos.xml'

Return value Description
Boolean Returns true if the file already exists
Example:
Copy 
FILEEXISTS('infos.xml')

LISTFILES()

The Script Function LISTFILES() gets an indexed collection of file names contained in a directory. Files are ordered by name (case insensitive). If the directory doesn't exist, null is returned. Relative paths are interpreted relative to the Data Home.

Copy 
LISTFILES($path)
Parameter Description
$path
String		 The directory to list the files from
Example: 'uploads/2006'
Return value Description
Indexed String Returns an indexed collection of file names
Example:
Copy 
LISTFILES($path)

3.2.3 READTEXTFILE()

The Script Function READTEXTFILE() reads the content of the given file into a String. Relative paths are interpreted relative to the Data Home.

Copy 
READTEXTFILE($filepath)
Parameter Description
$filepath
String		 The path to the file.
Example: '{DATA_HOME}/work/tmp/thefile.txt'
$encoding
String, Optional		 The encoding of the file, default is 'UTF-8'.
Example: 'UTF-8'
Return value Description
String Read text from the given file.
Example:
Copy 
READTEXTFILE('{DATA_HOME}/work/tmp/thefile.txt', 'UTF-8')

WRITETEXTFILE()

Writes the given data to the given file. Relative paths are interpreted relative to the Data Home, use '{DATA_HOME}' to refer to the nm data home location.

Copy 

    WRITETEXTFILE($filepath, $data)
  
Parameter Description
$filepath
String		 The path to the file.
Example: '{DATA_HOME}/work/tmp/thefile.txt'
$data
String		 The data to be stored in the file.
Example: 'some text'
$encoding
String, Optional		 The encoding of the file, default is 'UTF-8'.
Example: 'UTF-8'
$append
Boolean, Optional		 Append to an existing file? Default: 'false'
Example: 'false'

Returns Nothing

Example:
Copy 

    WRITETEXTFILE('{DATA_HOME}/work/tmp/thefile.txt', 'some text')
  

APPENDTOTEXTFILE()

Appends the given data to the given file. Relative paths are interpreted relative to the Data Home, use '{DATA_HOME}' to refer to the nm data home location.

Copy 

    APPENDTOTEXTFILE($filepath, $filepath, $data)
  
Parameter Description
$filepath
String		 The path to the file.
Example: '{DATA_HOME}/work/tmp/thefile.txt'
$data
String		 The data to be stored in the file.
Example: 'some text'
$encoding
String, Optional		 The encoding of the file, default is 'UTF-8'.
Example: 'UTF-8'

Returns Nothing

Example:
Copy 

    APPENDTOTEXTFILE('{DATA_HOME}/work/tmp/thefile.txt', 'some text')
  

MOVEFILE()

Moves a file to a new location. If the target file already exists, this function will overwrite it. If the target is a directory, a file with the same name as the source file will be created in it. If the directory of the target file does not exist, it will be created. Relative paths are interpreted relative to the Data Home.

Copy 

    MOVEFILE($sourcePath, $targetPath)
  
Parameter Description
$sourcePath
String		 The file to move.
Example: 'infos.xml'
$targetPath
String		 The target location.
Example: 'content/infos.xml'
Return value Description
Boolean Returns true if the operation was successful.
Example:
Copy 

    MOVEFILE('infos.xml', 'content/infos.xml')
  

COPYFILE()

Copies a file to a new location. If the target file already exists, this function will overwrite it. If the target is a directory, a file with the same name as the source file will be created in it. If the directory of the target file does not exist, it will be created. Relative paths are interpreted relative to the Data Home.

Copy 

    COPYFILE($sourcePath, $targetPath)
  
Parameter Description
$sourcePath
String		 The file to copy.
Example: 'infos.xml'
$targetPath
String		 The target location.
Example: 'content/infos.xml'
Return value Description
Boolean Returns true if the operation was successful.
Example:
Copy 

    COPYFILE('infos.xml', 'content/infos.xml')
  

DELETEFILE()

Deletes a file. Relative paths are interpreted relative to the Data Home.

Copy 

    DELETEFILE($path)
  
Parameter Description
$path
String		 The file to delete.
Example: 'infos.xml'
Return value Description
Boolean Returns true if the operation was successful.
Example:
Copy 

    DELETEFILE('infos.xml')
  

Virtual Files

Storing files as "virtual files" is a feature which can be used when generating PDF files. Virtual files are stored only in memory and are accessible only for a configured time frame before they are deleted. This functionality is useful when generating PDF documents containing sensitive information which you do not want to save to disk.

Whether a generated PDF document is saved to disk or stored only in memory is determined by the Boolean flag virtualFileStore available in the PdfRenderConfiguration Data Class. If set to true, the generated PDF document is only stored in memory. In the default configuration, a virtual file is accessible for only 5 minutes and is automatically deleted after 10 minutes latest. This gives the user time to view and download the generated PDF document, but leaves no traces of the document on the server afterwards.

The following configuration properties allow you to set the default behavior of virtual files:

  • nm.pdfrenderer.virtualstorage Sets the default value for the Boolean flag virtualFileStore. Default: true
  • nm.virtualfilestore.job.lifetime Sets the default lifetime of virtual files in milliseconds. Default: 300000 (300000 ms = 300 sec = 5 min)
  • nm.virtualfilestore.job.schedule Schedules the 'Virtual Files Maintenance' job which deletes virtual files after they have reached the end of their lifetime. Default: 0 0/5 * * * ? (every 5 minutes)
  • nm.virtualfilestore.job.paused If set to true, pauses the 'Virtual Files Maintenance' job by default on start-up. Default: false
Tip: To expose a PDF in FNZ Studio which was stored as a virtual file, use the FILESYSTEMURL Script Function.

Keep the following limitations of the virtual files functionality in mind:

  • There are no functions for the script language to access virtual files.
  • The implementation is not cluster-aware. This means that virtual files are only stored and are only accessible on one cluster node. If users log out and back in again, they can be redirected to a different cluster node and no longer have access to the virtual file.