File Share adapter

Updated September 17, 2026

Adapter

Two adapters over one file share abstraction. The Listener polls a share and publishes a message per file; the Caller writes one file per message. The Authentication decides the protocol.

File Share is not one adapter with two modes. It is two adapters that share a path model and a set of Authentications: the File Share Listener goes on a receive port, the File Share Caller on a send port. Neither holds a host name or a credential: that belongs to the Authentication, and the Definition chosen there is what decides which protocol the port speaks.

One thing bites people, so it is here rather than buried below. A Listener always deletes the file it picks up, before the Engine has seen the message. There is no setting to turn that off, so a share a Listener polls is a share it empties.

Start here

The Authentication picks the protocol

Each adapter offers the same two Definitions. The adapter configuration says nothing about where the server is, so moving an integration from a file server to an Azure file share is a change of Authentication and nothing else.

Definition	Target	What it carries
File Share Connection String	An Azure file share	Connection String, required. The share itself is named by the adapter's Share Name, so one Authentication serves any number of shares in the same storage account.
SMB File Share Connection	A file server, SMB 2 or 3 with NTLM	Host required, Port default 445, Domain optional, Username and Password required, Auth Protocol NTLM.

SMB needs private networking. Outbound TCP 445 to the file server is blocked towards the public internet on most cloud networks, so an SMB target has to be reachable over a VNet, a VPN or a private endpoint. An Azure file share reached by connection string has no such constraint.

The full Authentication dialog, both Definitions, field by field

File Share Connection String

Setting	Value
Name	Your name for the Authentication, no spaces or punctuation
Adapter	File Share Listener, or File Share Caller
Definition	File Share Connection String
Application	Preset, the Application you are working in
Connection String	Required. For example DefaultEndpointsProtocol=https;AccountName=…;AccountKey=…;EndpointSuffix=core.windows.net. It is not validated when you save, so a blank or malformed one is not reported until a port tries to use it.

SMB File Share Connection

Setting	Value
Name	Your name for the Authentication, no spaces or punctuation
Adapter	File Share Listener, or File Share Caller
Definition	SMB File Share Connection
Application	Preset, the Application you are working in
Host	Required. The file server, by name or address. Every address the name resolves to is tried.
Port	Defaults to 445. Any value from 1 to 65535 is accepted.
Domain	Optional. Leave it empty for a workgroup or local account.
Username	Required.
Password	Required.
Auth Protocol	NTLM. It is the only protocol implemented, and the field exists so that a Kerberos option can be added without reshaping the Authentication.

SMB1 and CIFS are not supported. Rotating a password on either Definition takes effect when the credential is refreshed, which happens on change and after an authentication failure, so editing the Authentication is what makes a new password live.

Auth Config Type is Static on the Listener and Static or Dynamic on the Caller. A receive port has no message to resolve a credential from, so every receive adapter offers Static alone. That is true across the platform, not a File Share quirk.

Shared by both

Paths and masks

Share Name names the share and is never part of a path. Path is always relative to it, and an empty Path means the share root.

Rule	Behaviour
Separators	Backslashes become forward slashes, and leading and trailing slashes are trimmed. `/inbox/a.xml`, `inbox/a.xml` and `\inbox\a.xml` are one path. A leading slash does not mean the root of the server.
Wildcards	`*` and `?` only. No character classes, no regular expressions. Everything else in the mask is matched literally.
What a mask matches	The entry name, never the full path, and case is ignored. `.xml` matches `Order.XML`; `inbox/.xml` matches nothing, because no entry is named with a slash in it.

Because a mask is tested against the name alone, it cannot narrow a walk to one subfolder. Include Subfolders decides how far down the walk goes, File Mask only decides which names survive it. To limit the scope, point Path at the folder you mean.

Receive side

File Share Listener

On its own interval the Listener lists the folder, takes as many files as its two budgets allow, reads each one, removes it from the share, and publishes it to the bus as a separate message.

The dialog, in order

Field	Default	What it does
Auth Config Type	Static	The only option on a receive port.
Auth Config	Required	The Authentication that supplies the protocol and the credentials.
Polling Interval (seconds)	Required, 1 or more	How long to wait between polls. One second is the floor. The next poll is scheduled from the moment the current one starts, so a slow poll does not push the following one further out.
Max Files Per Poll	20	A hard stop. Once this many files are published the pass ends and the remainder waits.
Max Batch Size in Bytes	102400	Total bytes one pass may deliver. There is no unlimited setting.
Share Name	Required	The share to poll.
Path	Empty	The folder inside the share. Empty means the share root.
File Mask	*	Which file names to take.
Include Subfolders	Off	Poll one folder level only. Turn it on to walk every subfolder under Path.

The Listener lists files only, so a folder whose name happens to match the mask is never picked up as if it were a file. The body it publishes is the file content: text is published as text, anything that does not read as text is published as Base64, and there is no payload mode to choose. Each message carries FileName, FilePath, FileSize and ShareName as context properties, and FilePath is how you tell two files of the same name in different subfolders apart when subfolders are included.

A Listener with an invalid configuration goes quiet, not red. A receive port only joins the polling set when it is Active, has an Auth Config, and has a configuration that parses and validates. Fail any of those and the port is simply absent, with no error to look at: it reads as connected and idle. A Polling Interval or a Max Files Per Poll of zero, or a missing Share Name, is enough to do it. Save the port again after correcting it.

How the byte budget behaves, and the two log shapes it produces

Max Batch Size in Bytes is checked against the size the folder listing reports, before anything is downloaded. A file that would push the pass over its remaining budget is skipped and the pass carries on, so a smaller file later in the same listing can still be delivered in that pass. That produces two situations worth telling apart.

Situation	What it means
Deferred	The file fits the budget on its own, but not in what is left of this pass. It is left alone and picked up on a later poll. Logged for information.
Never fits	The file on its own is larger than Max Batch Size in Bytes, so no poll can ever deliver it. Logged as a warning on every pass until the budget is raised or the file is removed. A repeating warning here means a stuck file, not a busy share.

The budget trusts the size the listing reports, and a poll against a folder that does not exist returns nothing and says nothing. It is not an error, so a Listener pointed at a mistyped Path looks exactly like a Listener pointed at an empty one.

Send side

File Share Caller

The Caller does one thing: it writes the message body to the share as a file. Upload is the only operation. The port's whole job is deciding where the file lands and how the body becomes bytes.

The dialog, in order

Field	Default	What it does
Auth Config Type	Static or Dynamic	Static names one Authentication on the port, Dynamic resolves it per message.
Auth Config	Required	The Authentication that supplies the protocol and the credentials.
Share Name	Required	The share to write into.
Path	Required	The file to write, relative to the share, including the file name.
Overwrite	On	When off, an Upload aimed at an existing file fails instead of replacing it.
Create Directory If Not Exists	On	Creates the folders above the target. When off, a missing folder fails the Upload.
Request Payload Mode	Auto	How the message body becomes the bytes that get written. Auto is not implemented, so set Text or Base64.

Request Payload Mode ships holding Auto, and Auto is not implemented. It is a planned feature. Set Text for a character file and Base64 for a binary before the port goes anywhere near production.

Upload in detail: the two guards, and why there is no safe partial write

Overwrite off is a check made before the write, not a lock. It fails the operation if the file is already there, which is what you want for a partner drop where a repeat means a duplicate. It cannot promise that nothing else created the file between the check and the write, so treat it as a guard against your own duplicates rather than as mutual exclusion.

Create Directory If Not Exists builds every missing folder above the target, one level at a time. It does nothing for a file written straight into the share root, because there is no folder above it.

An Upload writes to Path directly. There is no temporary name and no rename into place, so anything watching the destination can see a partially written file. If the reader on the other side is a poller you do not control, have it wait for a marker file, or write into a staging folder the reader ignores.

Request Payload Mode: which one to set, and why Auto is not one of them

The mode applies only to a body that is text or an object. A body that is already raw bytes is written as it stands whatever the mode says, and an empty body writes an empty file.

Mode	What gets written
Auto	Not implemented. It is a planned feature, so do not leave the field on it. Set Text for character files and Base64 for binaries.
Text	The body is written as UTF-8 text. This is the one for CSV, XML, JSON and any other character file.
Base64	The body is treated as Base64 and decoded before writing. This is how a binary payload carried through the bus as Base64, a PDF for example, lands on the share as the real file. It applies only when the body is a string, and an invalid Base64 string fails the operation.
Json	The body is serialised as JSON. A string body comes out quoted and escaped, which is rarely what you want for a file.

What comes back, and what the port promotes

The response body is an echo of the request body, not the stored file. A success means the bytes were accepted by the share, nothing more.

The port promotes Path and FileName, so a later step can name the file it just wrote. The values are attached before the write runs, which means they are there on a failed response too.

Operations

Failures, retries and credentials

Where a problem surfaces decides what the platform does with it, and only failed responses are retried.

Kind of failure	Retried?	What happens
Configuration	No	A missing Share Name is rejected outright rather than returned as a failed response.
Missing credentials	No	A blank Azure connection string, or an SMB Authentication without a host, username or password. The connection is built before the operation is attempted, so this escapes the retry loop too.
Rejected credentials	Once	An Azure 401 or 403, and an SMB logon failure, access denied, disabled or locked account, or expired password. The platform refreshes the credential and tries again, so a password corrected on the Authentication recovers without a restart.
Anything the file system refuses	Yes	A missing file, a file that already exists with Overwrite off, a missing folder with Create Directory If Not Exists off, or any protocol error.

Retries do not distinguish a transient failure from a settled answer. A file that is not there will still not be there on the third attempt, but the port retries it just the same, so a Retry Count of five with a long interval turns a fast, clear failure into a slow one. Keep retries sized for the network, and size the Retry Count for a transfer that might genuinely succeed on a second attempt rather than for one that cannot.

That is the File Share adapter

A Listener that polls and consumes, a Caller that uploads and nothing else, and an Authentication that decides whether the target is an Azure file share or an SMB server. Remember the Listener always deletes. Back to Adapters.