Azure Blob adapter

Updated September 17, 2026

Adapter

Two adapters over one Azure Blob container. The Listener polls the container and publishes a message per blob; the Caller writes one blob per message.

Azure Blob is not one adapter with two modes. It is two adapters that share a naming model and a set of Authentications: the Azure Blob Listener goes on a receive port, the Azure Blob Caller on a send port. Neither adapter holds a storage account or a credential: that belongs to the Authentication. The adapter names the Container it works in.

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

Start here

The Authentication holds the storage account

Both adapters pair with an Authentication built on the Azure Blob Connection String Definition. It carries the storage account; the adapter names the container inside it, so one Authentication can serve several ports against several containers.

Setting	Value
Name	Your name for the Authentication, no spaces or punctuation
Adapter	Azure Blob Listener, or Azure Blob Caller
Definition	Azure Blob 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.

The container is not here. It lives on the adapter, so the Authentication says which storage account you are reaching and the port says which container inside it.

Shared by both

Containers, paths and masks

Container Name names the container and is never part of a path. Path is always relative to it, and an empty Path means the whole container.

A container has no folders. A blob called inbound/2026/order.xml is one blob whose name happens to contain slashes, not a file three directories deep. Azure shows those slashes as a folder tree in the portal, and the adapter follows the same convention, but nothing is really nested: there is no empty folder to create, and deleting the last blob under a prefix leaves nothing behind.

Rule	Behaviour
Separators	Forward slashes, and leading and trailing slashes are trimmed. `/inbound/a.xml` and `inbound/a.xml` are one path. On the Listener, Path is the name prefix to match; on the Caller it is the blob name to write.
Wildcards	`` and `?` only, and only in File Mask*. No character classes, no regular expressions. Everything else in the mask is matched literally.
What a mask matches	The last segment of the blob name, never the whole name, and case is ignored. `.xml` matches `inbound/Order.XML`; `inbound/.xml` matches nothing, because the mask is never tested against a segment containing a slash.

Because a mask is tested against the last segment alone, it cannot narrow a walk to one prefix. Include Subfolders decides how deep the listing goes, File Mask only decides which names survive it. To limit the scope, point Path at the prefix you mean.

Receive side

Azure Blob Listener

On its own interval the Listener lists the container, takes as many blobs as its two budgets allow, reads each one, removes it from the container, 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 storage account connection string.
Polling Interval (seconds)	Required, 1 or more	How long to wait between polls. 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	Required	A hard stop. Once this many blobs are published the pass ends and the remainder waits.
Max Batch Size in Bytes	Required	Total bytes one pass may deliver. There is no unlimited setting.
Container Name	Required	The container to poll.
Path	Empty	The name prefix to match inside the container. Empty means the whole container.
File Mask	*	Which blob names to take.
Include Subfolders	Off	Match blob names nested deeper under Path. Turn it off to take only the names directly under it.

The body the Listener publishes is the blob 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 and FileSize as context properties. FilePath is the full blob name, which is how you tell two blobs whose last segment is the same apart when subfolders are included.

Send side

Azure Blob Caller

The Caller does one thing: it writes the message body to the container as a blob. Upload is the only operation. The port's whole job is deciding what the blob is called 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 storage account connection string.
Container Name	Required	The container to write into.
Path	Required	The blob name to write, including any prefix you want it filed under.
Overwrite	On	When off, an Upload aimed at an existing blob fails instead of replacing it.
Request Payload Mode	Auto	How the message body becomes the bytes that get written. Auto is not implemented, so set Text or Base64.

There is no Create Directory If Not Exists here, and there is nothing missing. The other two file adapters carry that flag because they write into real directories that have to exist first. A container has no directories, so a prefix in the blob name needs nothing created ahead of it. The container itself does have to exist.

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.

Overwrite, and why a partial blob is not a worry here

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

Unlike a file share or an SFTP server, a blob becomes visible only once it has been committed. A reader listing the container does not see a half-written blob, and an upload that dies partway leaves nothing behind rather than a short file. This is the one place where the Blob adapter is safer than its two siblings.

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 blob.

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 the one for binaries: a PDF carried through the bus as Base64 lands in the container 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 blob.

What comes back, and what the port promotes

The response body is an echo of the request body, not the stored blob. A success means the bytes were committed to the container, nothing more.

The port promotes Path and FileName, so a later step can name the blob 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 Container Name is rejected outright rather than returned as a failed response.
Missing credentials	No	A blank connection string on the Authentication. The client is built before the transfer is attempted, so this escapes the retry loop too.
Rejected credentials	Once	A 401 or 403 from the storage account. The platform refreshes the credential and tries again, so a key corrected on the Authentication recovers without a restart.
Container missing	Yes	The container named on the port does not exist. The adapter does not create it, so this keeps failing until someone creates it in Azure.
Anything the service refuses	Yes	A blob that already exists with Overwrite off, a throttled request, or any transport error.

Retries do not distinguish a transient failure from a settled answer. A container that does not exist will still not exist on the third attempt, so a Retry Count of five with a long interval turns a fast, clear failure into a slow one. Size the Retry Count for a request that might genuinely succeed on a second attempt, such as a throttle, rather than for one that cannot.

That is the Azure Blob adapter

A Listener that polls and consumes, a Caller that writes and nothing else, and an Authentication that carries the storage account. Remember the Listener always deletes, and that a container has no real folders. Back to Adapters.