Import from Hotfolder

A hotfolder connector watches a folder and imports every new matching file into your project automatically. Each file becomes one transaction with one document, processed by your workflow like any uploaded file.

Typical uses: a scanner that saves PDFs to a network share, an ERP that drops documents into an exchange folder, or any legacy system that can write files but cannot call an API.

Availability

The hotfolder connector needs a real filesystem the application can see, so availability depends on your deployment:

Deployment	Availability
Self-hosted (on-premises, Docker)	Available by default
Managed in Azure	Available on request: it is enabled as a deployment setting, and an Azure Files share is provisioned and mounted for you automatically. Contact your DocAI Fabric contact to switch it on.
SaaS (app.docaifabric.com)	Not available. Use Import from Email instead, or wait for the planned cloud storage connectors (your own bucket).

If the folder options are hidden in the connector settings, your deployment does not offer them.

How it works

1. The connector polls the watched folder on a schedule (default: every 60 seconds).
2. A file is picked up only when it matches the filename mask and has been stable (no size or timestamp changes) for the stability wait. This prevents importing a file that is still being written.
3. The file is copied into DocAI Fabric, a transaction is created, and the workflow starts.
4. Only after the workflow has started is the source file released: moved to the processed subfolder (or deleted, per your settings).
5. If an import keeps failing, the file is moved to the error subfolder after several attempts, so problems are always visible in the folder itself.

The same file is never imported twice. If you drop a new version of a file (same name, different content), it is imported again as a new transaction, which is usually what you want.

Setting up a connector

1. Open your project and go to the Workflow tab.
2. Select the Import activity. The Import Connectors panel appears in its settings.
3. Click Add connector.
4. Choose the folder mode:
   • Managed (auto-created): DocAI Fabric creates a folder for you and shows its path after you save. You provision nothing; just drop files into that folder.
   • Custom mounted path: you point the connector at a folder you have mounted yourself (for example an NFS or SMB share). Enter its path as seen inside the container. The folder must be inside one your administrator has allowed (see Allowing custom folders); until one is allowed, this mode is off.
5. Adjust the settings if needed (see the reference below).
6. Click Save.

Where the managed folder lives

• Self-hosted Docker: the managed folder is created inside the application data volume. With the standard Compose setup that maps ./data/storage to the container, the folder appears on the host under ./data/storage/hotfolder/<key>. You can share that path over your network (SMB, NFS) or let another system write into it directly.
• Managed in Azure: the managed folder lives on the Azure Files share that was mounted when the feature was enabled. Drop files into it with Azure Storage Explorer, the Azure portal, or by mounting the share on a workstation over SMB.

Allowing custom folders

A connector moves the files it imports, so it may only watch folders an administrator has chosen. Set INGEST_CUSTOM_ROOTS to the container-side paths of the shares you mounted, separated by commas, for example INGEST_CUSTOM_ROOTS=/data/hotfolder. A custom connector can then watch that folder or any folder inside it.

• Self-hosted Docker: add the variable to your .env next to the volume you mounted, then restart.
• Managed in Azure: the mounted share is allowed automatically.

The application's own data folder and the managed folders of other connectors can never be watched this way.

Testing before going live

Two buttons on each connector let you verify the setup safely:

• Test (dry-run): lists the files that would be imported right now, without importing anything. Use it to check the path and the filename mask.
• Import to Playground: saves your changes and takes you to the Playground, where you pick which of the waiting files to import using your draft settings. Each file imports in the background, one at a time in the progress panel, so you can inspect results in the transaction viewer as they arrive instead of waiting for a whole folder.

You can also start this from the Playground itself at any time: New Transaction → Import waiting items. There, Import next brings in the next waiting file without waiting for a list to build, or tick the files you want and the button becomes Import N items.

A test import consumes the files

Importing from the Playground runs exactly the same way production will, including the On success setting — with the default, an imported file moves to the processed subfolder. Point a test connector at a test folder.

Production behavior

Automatic import targets the Production dataset and starts only once the project has a published version. Until you publish, the connector simply waits (files stay in the folder); it activates on its own when you publish. This means you can safely configure and test a connector while the project is still a draft.

Settings reference

Setting	Description	Default
Folder	Managed (auto-created) or a custom mounted path	Managed
Watched folder path	Custom mode only: the folder to watch, as seen inside the container	(empty)
Filename mask (regex)	Regular expression a filename must match to be imported, matched from the start of the name and case-sensitive unless it starts with (?i) (see Regular Expressions)	.*\.pdf$
Poll interval (s)	How often the folder is checked for new files	60
Stability wait (s)	How long a file's size and timestamp must be unchanged before it is picked up	5
On success	Move the file to a subfolder, or delete it	Move to subfolder
Success subfolder	Where successfully imported files go	processed
On failure	Move the file to a subfolder, or leave it in place	Move to subfolder
Failure subfolder	Where files that repeatedly failed to import go	error

Notes:

• The processed and error subfolders are created inside the watched folder and are never scanned for new files.
• To import images as well as PDFs, widen the mask, for example .*\.(pdf|png|jpg|jpeg|tiff?)$. The Import activity converts them the same way it converts uploads.
• To accept ZIP archives, add zip to the mask, for example .*\.(pdf|zip)$. An archive is opened into one transaction exactly as when it is uploaded in the dialog: its supported files become the documents, the archive is kept with the transaction, and anything not imported is listed in the transaction's Activity Log. An archive that holds nothing importable is treated as a failed file and moved to the failure folder. Saved emails (.eml, .msg) dropped in the folder are opened the same way when the mask allows them.
• The housekeeping of the processed folder is yours: DocAI Fabric moves files there but never deletes them. Set On success to Delete if you prefer not to accumulate them.