# Create a File Event Listener
To create a File Event Listener, click the **New** button on the upper-left corner and fill in these fields:
* **General Information**: assign a name to the File Event Listener you are creating and optionally enter a description.
* **Listening folder (local or remote)**:
* **Local | Remote**: select the location type for your File Event Listener. You can either enter the file system folder (use this format: /home/dms/tmp) or a remote location. Remote locations are the Links configured in the [Links](/data-mover-smart/services/links.md) section. Select the Link and fill in the Credential and remote path (if applicable).
* **Mode**: **Automatic | Manual**: select **Automatic** to activate monitoring according to the recurrence configured in the **Polling** setting. Select **Manual** to activate monitoring on demand via API or via SPXP command line.
* **Polling**: this setting determines the interval, in seconds, at which the system will monitor the folder for changes.
* **Icon**: assign an icon to the File Event Listener you are creating.
* **In case of error**: select the action to execute when an error occurs during file acquisition. The **Execute script** option runs a predefined script to handle the error condition. See [Error handling in file acquisition](#error-handling-in-file-acquisition) below for details.
* **Trigger**:
* **New file**: in the **Choose a period** section, you can optionally specify a time window during which the system should search for files. If no period is selected, files will be searched at any time.
* **From / To**: select a start and end time using the clock icons.
* **Timed (default)**: the system repeatedly checks the file to ensure it is stable (i.e., no longer changing) before proceeding. These two settings work together to ensure that files are stable and fully written before the system processes them.
* **Check File**: this option appears only when the listening folder is Local and sets how many times the system should verify that a file remains unchanged before proceeding.
* **Check Every (seconds)**: define the interval, in seconds, between each stability check.
* **Flag file**: define the prefix or suffix of the *flag file* that must appear in the file system to indicate that a corresponding file is ready to be processed. Both the prefix and suffix **must include the dot**. You must enter either the prefix **or** the suffix in this field. The system will use it to detect the presence of the flag file and determine when processing can safely begin.
* **Condition branch**: define multiple branches that determine different actions to be executed according to the condition attributes, actions and mode selected in the following sections. Additional conditions can be created using the + button on the right.\
Conditional branches allow you to define which actions to execute when specific conditions occur. For example, you may want to rename or zip a file depending on its name. If multiple conditions are met, only the first will be executed, and the rest will be ignored.
* **Condition attributes**: click the + button and select or create a Condition Attribute, which defines the criteria that must be met. Condition attributes can be based on specific file characteristics, such as file size, or file name.\
When using the **maxFileSize** and **minFileSize** attributes, enter the number of bytes in the **Value** field. \
When using the **filename** attribute, you can choose one of the following matching options:
* **RegExp** to define the condition using a **regular expression**. This option allows advanced and precise pattern matching. The **Value** field accepts a valid regular expression. \
**Example**: `.*\.txt` → matches all files with the .txt extension.
* **Wildcard** to define the condition using **simple wildcard characters**. \
The **Value** field supports `*` to match any sequence of characters and `?` to match a single character. \
**Example**: `report_*` → matches all files starting with report\_.
{% hint style="info" %}
File Event Listeners condition attributes are configured in **Settings** → [Metadata](/data-mover-smart/settings/metadata.md) and belong to the Fel\_condition category.
{% endhint %}
* **Actions**: select the action to be executed when the condition attribute is set. Ensure you are in the correct branch if you have created multiple condition branches. You can run a script, decrypt and encrypt files using PGP, rename, zip files. For a description of these options, go to the [Actions](/data-mover-smart/file-event-listeners/actions.md) page.
* **Mode**: select either **Copy** or **Move** to copy or move the file and set a destination folder where the action will be executed. Ensure you are in the correct branch if you have created multiple condition branches.
* **Destination folder (VFS)**: set a destination folder for the files involved in the action configured in the File Event Listener.
* **Attributes**: assign attributes to the File Event Listener. When you click the + button, the **Attribute** pane opens. Selecting the **Dictionary** icon displays a tooltip with available macros, which can be used in the **Value** field. You can either enter a specific value or type ${ to insert the macro. To create a new attribute, click **New**; the **New Metadata** window appears with the **Fel\_attribute** category already set.
When done, click the **Save** button. The File Event Listener will be added to the list of options, in status "running" - if created correctly.
### File Event Listener settings
When configuring a **File Event Listener**, a panel on the left side of the screen allows you to manage the listener status, behavior, execution timezone, and tags, as well as perform common actions.
* **Enabled**: the **Enabled** toggle controls whether the File Event Listener is active.
* When enabled, the listener monitors the configured folder and processes file events according to its configuration.
* When disabled, the listener remains configured but does not process any file events.
* **Pull On Init**: by default, this setting is turned off.
* When **Pull on init** is enabled, the File Event Listener applies the conditions to the files that already exist in the monitored folder at the time the File Event Listener is created.
* The **Pull on init** does not have any effects when a File Event Listener is re-enabled or re-started.
* If the File Event Listener is **stopped** and, during this period, files are added or modified in the monitored folder, those files can still be acquired: when the File Event Listener is re-started and you answer “Yes” to the prompt “Do you want to consider the files currently in the folder?”, the files that were added or modified during the interruption are acquired by the system.
* If a manual File Event Listener is restarted, files in the monitored folder are considered based on the **Pull on init** setting.
* **Timezone**: this section defines the timezone used to evaluate **time‑based operations** associated with the File Event Listener.
* **System timezone**: displays the system default timezone (for example, *Europe/Rome (UTC +02:00)*).
* **Override with**: allows you to override the system timezone by selecting a different timezone from the drop‑down list.
* The selected timezone is applied only to the File Event Listener.
* The **X** icon removes the override and restores the system timezone.
* The drop‑down arrow opens the list of available timezones.
* **Tags**: allows you to assign one or more **tags** to the File Event Listener. Click the **+** icon to add a tag. Tags can be used to classify, filter, and group File Event Listeners in the list view.
* **Actions**:
* **Clone**: creates a copy of the File Event Listener configuration.
* **Delete**: deletes the File Event Listener. A confirmation is required to proceed.
### File Event Listener summary
At the bottom of the screen, a **summary bar** provides a **human‑readable recap** of the File Event Listener configuration:
* The File Event Listener name.
* Whether **Pull On Init** is enabled.
* The monitored folder and polling interval.
* The trigger condition (for example, *new file*).
* The configured conditions and actions applied to detected files.
The summary is updated automatically as the configuration changes, allowing you to quickly validate the listener behavior. Click **Save** to apply and persist the configuration. Changes are not applied until the File Event Listener is saved.
### Draft saving behavior
When creating a new **File Event Listener**, Data Mover Smart automatically saves a **draft** as soon as you start typing in any field. The draft mechanism prevents accidental loss of work and allows you to safely pause configuration activities and resume them later without re‑entering information.
As soon as a draft is created, a \* **Draft saved** chip appears next to the **New** button. This indicates that the current configuration has been temporarily saved, even if the entity has not been explicitly saved.
If you leave the page **without saving** (for example, by returning to the File Event Listeners list), the draft is preserved. In this case, the **New** button in the list view displays a \* **Draft** chip.
When you click **New** again, the previously entered values are automatically restored and displayed in the configuration form, allowing you to continue where you left off.
The **broom icon** allows you to reset all fields or remove the saved draft. After clearing the draft, clicking **New** opens a blank configuration form.
### Error handling in file acquisition
To configure error handling during file acquisition, select the **Execute script** action and complete the following fields:
* **Script type (\*)**: select how the script will be provided.
* **Saved**: runs a script previously saved in **Settings** → [Scripts](/data-mover-smart/settings/scripts.md).
* **Path**: runs a script located in the file system. When selecting this option, enter the script location in the **Script path** field.
* **Script (\*)**: when using **Saved** script type, select the script from the drop‑down list.\
When using **Path**, enter the corresponding script path.
* After selecting the script from the drop‑down list, you can add new environment variables or override existing environment variables. See [Manage File Event Listener-level variables](/data-mover-smart/file-event-listeners/actions/execute-script.md#manage-file-event-listener-level-variables) for details.
* **Script variables**: click the **New** icon to add a variable for the script. Enter the variable value manually or type `${` to use available macros.\
Click the **Dictionary** icon to display the list of supported macros.
* **Force action error**: enable this option to force the action to return an error status after running the script.
* **Return code ok (\*)**: enter the return code that the system should interpret as a successful script execution. If the script returns a different code, the action will be considered failed.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.primeur.com/data-mover-smart/file-event-listeners/create-a-file-event-listener.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
**Dictionary** icon displays a tooltip with available macros, which can be used in the **Value** field. You can either enter a specific value or type ${ to insert the macro. To create a new attribute, click **New**; the **New Metadata** window appears with the **Fel\_attribute** category already set.
When done, click the **Save** button. The File Event Listener will be added to the list of options, in status "running" - if created correctly.
### File Event Listener settings
When configuring a **File Event Listener**, a panel on the left side of the screen allows you to manage the listener status, behavior, execution timezone, and tags, as well as perform common actions.
* **Enabled**: the **Enabled** toggle controls whether the File Event Listener is active.
* When enabled, the listener monitors the configured folder and processes file events according to its configuration.
* When disabled, the listener remains configured but does not process any file events.
* **Pull On Init**: by default, this setting is turned off.
* When **Pull on init** is enabled, the File Event Listener applies the conditions to the files that already exist in the monitored folder at the time the File Event Listener is created.
* The **Pull on init** does not have any effects when a File Event Listener is re-enabled or re-started.
* If the File Event Listener is **stopped** and, during this period, files are added or modified in the monitored folder, those files can still be acquired: when the File Event Listener is re-started and you answer “Yes” to the prompt “Do you want to consider the files currently in the folder?”, the files that were added or modified during the interruption are acquired by the system.
* If a manual File Event Listener is restarted, files in the monitored folder are considered based on the **Pull on init** setting.
* **Timezone**: this section defines the timezone used to evaluate **time‑based operations** associated with the File Event Listener.
* **System timezone**: displays the system default timezone (for example, *Europe/Rome (UTC +02:00)*).
* **Override with**: allows you to override the system timezone by selecting a different timezone from the drop‑down list.
* The selected timezone is applied only to the File Event Listener.
* The **X** icon removes the override and restores the system timezone.
* The drop‑down arrow opens the list of available timezones.
* **Tags**: allows you to assign one or more **tags** to the File Event Listener. Click the **+** icon to add a tag. Tags can be used to classify, filter, and group File Event Listeners in the list view.
* **Actions**:
* **Clone**: creates a copy of the File Event Listener configuration.
* **Delete**: deletes the File Event Listener. A confirmation is required to proceed.
### File Event Listener summary
At the bottom of the screen, a **summary bar** provides a **human‑readable recap** of the File Event Listener configuration:
* The File Event Listener name.
* Whether **Pull On Init** is enabled.
* The monitored folder and polling interval.
* The trigger condition (for example, *new file*).
* The configured conditions and actions applied to detected files.
The summary is updated automatically as the configuration changes, allowing you to quickly validate the listener behavior. Click **Save** to apply and persist the configuration. Changes are not applied until the File Event Listener is saved.
### Draft saving behavior
When creating a new **File Event Listener**, Data Mover Smart automatically saves a **draft** as soon as you start typing in any field. The draft mechanism prevents accidental loss of work and allows you to safely pause configuration activities and resume them later without re‑entering information.
As soon as a draft is created, a \* **Draft saved** chip appears next to the **New** button. This indicates that the current configuration has been temporarily saved, even if the entity has not been explicitly saved.