# Universal Folder Listener

- Updated on Jun 17, 2025
- Published on Oct 10, 2024

- 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/v40/docs/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. If you would like to scan a subfolder of this folder, enter that folder's name or path in the text box. As a best practice, **we recommend having one Listener monitoring the base folder**. Setting up multiple Listeners for a single base folder may result in errors and resource collisions. |
| **File Extensions** | Yes | A list of the extensions that image files will need to have to be eligible for processing. If there are file extensions that you want to support but do not see in the drop-down list, select **other**, and enter the extensions in **Other File Extensions**. |
| **Other File Extensions** | No | A comma-separated list of file extensions that do not appear in **File Extensions**. This field only appears if **other** is selected in **File Extensions**. |
| **Include Submission Level Parameters** | No | Indicates whether the system will ingest JSON files along with document files and submission folders. These JSON files can contain information such as metadata, case data, and _external_id_ values. |
| **Group Subfolder Files** | No | Determines how files in a subfolder of the base folder are processed. 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. 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/v40/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. These include:

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

Before setting up a Universal Folder Listener connector and retiring your Folder Listener connection, you need to complete some preparatory steps.

### Check your folder structure

The Universal Folder Listener accepts both single files and folders of files as submissions. The processing is determined by location and 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. For greater security, you may want to modify the value of _FS_INPUT_PATH_.

### 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_. The name of this file depends on the submission type.

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 that you define:

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

Therefore, when migrating to the Universal Folder Listener, you need to change the names, file types, and content of your metadata files, as outlined in the following table.

|  | **Folder Listener** | **Universal Folder Listener** |
| --- | --- | --- |
| **File name** | _filename_index.txt_ | _filename.ext.json_<br>OR<br>_foldername.json_ |
| **File type** | Text | JSON |
| **Contents** | JSON-formatted key/value pairs of your choosing | - _metadata_ (key/value pairs of your choosing)<br>- _cases_<br>- _external_id_ |

### Check the location of metadata files

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