Universal Folder Listener

Updated on Sep 24, 2025
Published on Mar 18, 2025
5 minute(s) read

The Universal Folder Listener allows you to ingest files from a Folder on your system.
The Universal Folder Listener Input connection is available only for on-premise / private cloud instances of Hyperscience.

Sample use cases

Another system places documents in a system folder on a regular basis. I want to ingest those files one by one.
I put several related files into subfolders to be ingested as one submission per subfolder into Hyperscience.
I want to regularly scan and ingest certain file types from a shared system folder.

Block settings table

In addition to the settings outlined below, you can also configure the settings described in Universal Integration Block Settings.

Name	Required?	Description
Folder To Scan For Submissions	No	The folder the connector will scan for image files. The default path is the path specified in the FS_INPUT_PATH ".env" file variable. As a best practice, we recommend having one Listener monitoring the base folder.
File Extensions	Yes	A list of the extensions that image files will need to have to be eligible for processing.
Other File Extensions	No	A comma-separated list of file extensions that do not appear in File Extensions.
Include Submission Level Parameters	No	Indicates whether the system will ingest JSON files along with document files and submission folders.
Group Subfolder Files	No	Determines how files in a subfolder of the base folder are processed. - If enabled, all files in a subfolder are processed together as a single submission. - If disabled, each file in a subfolder is processed as a single submission. Defaults to enabled.
Poll Interval (In Seconds)	No	The frequency at which the connector will monitor the base folder for submissions. Defaults to 10.
Warm-Up Interval (In Seconds)	No	The length of time that a file must remain unmodified before it is eligible for processing. Defaults to 15.
Empty Folder Cleanup Delay (In Hours)	No	The frequency at which the connector will delete empty folders inside the base folder. Defaults to 24.

Naming of files by the system

After files are ingested, the system adds $ufl_ to the beginning of each file name (e.g., file1.png in the folder1 subfolder becomes $ufl_folder1/file1.png).

These names appear in the submission output as submitted_filename values.

Setting up Universal Folder Listener

To set up the Universal Folder Listener, enter the settings as described in the Block settings table above.

Migrating from the Folder Listener

There are numerous benefits for users upgrading from the legacy Folder Listener to the Universal Folder Listener:

Submissions with multiple files
Simplified file structure
Support for Cases
Numerous UX improvements

Check your folder structure

The Universal Folder Listener accepts both single files and folders of files as submissions. Whether a file is processed as its own submission or as part of a larger submission is determined by its location and the configuration of the Listener.

Verify the path of your base folder

The system uses the file path in the FS_INPUT_PATH ".env" file variable as the default location of the base folder.

Update your metadata files

The Universal Folder Listener can accept a JSON file for each submission that contains metadata, case data, and an external_id.

An example JSON file for a Universal Folder Listener submission appears below.

{
    "metadata": {
         "test": "Metadata for inner1"
    },
    "cases": [{
         "external_case_id": "900",
         "filenames": ["div_lic_1.jpg", "div_lic_1.jpg"]
    }],
    "external_id": "123"
}

By contrast, the metadata text files supported by the original Folder Listener consist of key/value pairs:

{
    "key1": "value1",
    "Key2": "value2"
}

Check the location of metadata files

If Include Submission Level Parameters is enabled, metadata files are required and must be in the correct location for submissions to be created from the files they describe.