# 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](https://help.hyperscience.ai/v42/docs/universal-integration-block-settings).

| **Name** | **Required?** | **Description** |
| --- | --- | --- |
| **Folder To Scan For Submissions** | No | The folder the connector will scan for image files.<br>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.  <br>- If enabled, all files in a subfolder are processed together as a single submission.  <br>- If disabled, each file in a subfolder is processed as a single submission.  <br>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\_<file_path_after_base_folder>_ 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](https://help.hyperscience.ai/v42/docs/universal-folder-listener#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.

```json
{
    "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:

```json
{
    "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.