File Uploads

Upload Rules

Several settings decide what the platform accepts when somebody uploads a file.

Where to find it

Architect Panel → Configuration:

• Site Settings — the File Uploads and Audio/Video Conversion groups

Architect Panel → Data:

• File Stores — the stores themselves, and View File Store on a row
• Large Uploads — in-progress and stalled upload sessions
• File Import Routines — watched sources and their mappings

The settings

• Allow files without filenames.
• Allow files without extensions.
• Replace spaces in filenames.
• Force simple file names.
• Index document contents.
• Public and private upload paths.

Three of these are conveniences. The rest decide whether a hostile upload is a problem.

File scopes constrain the types

Separately from these settings, named scopes list the file types allowed in a particular context. That is where "images only" or "documents only" is expressed, per place rather than for the whole installation.

Use them. An upload field accepting anything is an upload field somebody will use for anything.

Uploads are user-supplied content

The framing that matters. A file is data from somebody you do not control, with a name they chose, in a format they chose. Treat every upload accordingly:

• Never trust the name.
• Never trust the declared type.
• Never serve it back from somewhere it could execute.

Private by default

Anything that is not deliberately public belongs on the private path, served through the platform so permissions apply. A file placed in a public directory is a file with a guessable address and no access control.

Keep names simple

The safe-name setting exists because filenames arrive containing anything a user’s device allowed — accents, emoji, path separators, control characters. Simplifying them avoids problems across operating systems, in URLs, and in downloads.

Set size limits realistically

Large enough for the documents people genuinely need to send, small enough that a mistake is not a storage incident. And remember that large files have their own chunked path — the limit that matters is often not the one you think.

Think about what accumulates

Uploads only grow. Attachments on records that were closed years ago, drafts, duplicates. Include files in whatever retention thinking covers your records, or storage becomes a surprise.

Test with an awkward file

A name with spaces and an accent, no extension, and a type your scope should refuse. Those three cover most upload behaviour, and they take a minute.

Worked example

An organisation restricts each upload field with a file scope, keeps everything on the private path except its public asset store, and forces simple names. A test with an unnamed, extensionless file confirmed it was refused rather than stored under a generated name nobody could find.

Recommendations

• Use file scopes per field, not one global rule.
• Private path by default.
• Force simple names.
• Test with deliberately awkward files.

Missing Names and Extensions

Two settings decide whether files arriving without a name, or without an extension, are accepted.

Where to find it

Architect Panel → Configuration:

• Site Settings — the File Uploads and Audio/Video Conversion groups

Files without extensions

Allowed by default. Plenty of legitimate files have no extension — anything produced on a system that does not use them, files renamed in transit, and some exports.

The cost is that neither the platform nor the user’s device can tell what the file is from its name, so it downloads as something nobody can open.

Files without names

Refused by default, and that default is right. A file arriving with no name at all is nearly always a fault — a broken form, a misbehaving integration, or something deliberate.

Accepting them means storing files under generated names that nobody can identify afterwards.

Neither is a security control

The important caution. An extension tells you what a file claims to be, not what it is. A document renamed to end in an image extension is still a document, and one that is genuinely dangerous is not made safe by its name.

File scopes, storage location and how a file is served back are the controls. These two settings are about usability.

Decide by what your users send

If your uploads come from an integration producing extensionless files, allow them. If they come from people using ordinary devices, requiring an extension catches mistakes early and produces files that open when downloaded.

A refusal must be explained

Whichever way you set them, the message when a file is rejected should say what was wrong and what to do. "Upload failed" produces a support call; "this file has no name — please rename it and try again" does not.

Watch the error log

A sudden run of rejected uploads usually means an integration has changed rather than that users have. The log is where that shows.

Consider the download experience

A stored file with no extension is one somebody downloads and cannot open. If you accept them, consider whether the platform can supply a sensible name on download instead.

Test both

Upload a file with no extension and one with no name, and see what happens. That is a two-minute check on behaviour that is otherwise only discovered by a user.

Worked example

An organisation allows extensionless files because a supplier integration produces them, and refuses nameless ones. The rejection message names the problem. A run of failures in the error log identified a form change on the supplier’s side within a day.

Recommendations

• Refuse nameless files — they are nearly always a fault.
• Do not treat extensions as security.
• Explain every refusal in the message.
• Watch the log for a run of rejections.

Spaces in Filenames

One setting decides whether spaces in uploaded filenames are replaced with underscores.

Where to find it

Architect Panel → Configuration:

• Site Settings — the File Uploads and Audio/Video Conversion groups

Where spaces cause trouble

• In addresses — a space has to be encoded, and a filename appearing in a link is a filename that will be encoded inconsistently somewhere.
• In command-line handling — anything processing files outside the platform.
• In copied links — a pasted address containing an encoded space breaks in messages and documents.
• Across systems — export, import, synchronisation, backup.

Where they do not

In the platform itself, where a stored filename is handled properly. If files are only ever uploaded, listed and downloaded through the interface, spaces are harmless.

Decide by what happens to the files

Files that stay inside the platform can keep their names as the user typed them, which is friendlier. Files that leave — into a share, an integration, a link somebody pastes into an e-mail — are better without spaces.

Consistency matters more than the choice

Either setting is defensible. What causes problems is changing it midway, so half your files have spaces and half do not, and anything matching filenames has to handle both.

Set it before there are files

Because it applies on upload. Existing files keep the names they were given, so a change produces a split library rather than a converted one.

It is not the same as safe names

The separate safe-name setting handles the genuinely problematic characters — accents, symbols, control characters, path separators. Spaces are a usability question; those are a correctness one.

Turn safe names on regardless of what you do about spaces.

Users notice

Somebody who uploads "Annual Report 2026.pdf" and downloads "Annual_Report_2026.pdf" will ask why. It is a small thing and worth a line of explanation next to the upload field if you have set it.

Worked example

An organisation replaces spaces because its files are synchronised to a shared drive and referenced in generated documents. It set this at installation, so the whole library is consistent, and the upload field says filenames will be simplified.

Recommendations

• Replace spaces if files leave the platform.
• Set it before there are files — it is not retrospective.
• Turn safe names on regardless.
• Tell users if names will change.

Safe Filenames

The safe-name setting reduces uploaded filenames to characters that behave predictably everywhere. It is on by default and should stay on.

Where to find it

Architect Panel → Configuration:

• Site Settings — the File Uploads and Audio/Video Conversion groups

What arrives in a filename

Whatever the user’s device allowed. Accented characters, non-Latin scripts, emoji, quotation marks, semicolons, path separators, and occasionally control characters.

All of these are legitimate on somebody’s machine and several of them are a problem on yours.

Why it matters beyond tidiness

• Path separators in a name are an attempt, deliberate or accidental, to write outside the intended directory.
• Control characters can truncate or disguise what a name appears to be.
• Names designed to look like something else — a long name whose visible portion suggests a different type.

Simplifying the name removes a class of problem rather than mitigating it.

It is not a substitute for the rest

A safe filename does not make a file safe. What matters equally is where it is stored, whether it can be executed, and how it is served back.

Private storage served through the platform, so permissions apply, is the control that does the heavy lifting.

Keep the original name somewhere

Users recognise their own filenames. Where the stored name is simplified, showing the original in the interface and using it on download keeps the file recognisable without storing it unsafely.

Watch out for collisions

Simplification can turn two different names into the same one. Confirm what happens when it does — a file silently replacing another is a data loss that nobody reports.

Test with a genuinely hostile name

Something containing a path separator, a quotation mark and a non-Latin script. Confirm it is stored under a name you are comfortable with and that it downloads correctly.

Do not turn it off for convenience

The usual reason is that somebody wants exact filenames preserved for an integration. Solve that by keeping the original name as data rather than by storing it as the actual name.

Worked example

An organisation keeps safe names on and stores the user’s original filename alongside, displaying it in the interface and using it on download. A test upload containing a path separator was stored under a simplified name, which is what the setting is for.

Recommendations

• Leave it on, always.
• Keep the original name as data, not as the stored name.
• Check what happens on a collision.
• Remember storage and serving matter more.

Large Uploads

Large files are not uploaded in one request. They are split into chunks, and the transfer is tracked as a session.

Where to find it

Architect Panel → Data:

• File Stores — the stores themselves, and View File Store on a row
• Large Uploads — in-progress and stalled upload sessions
• File Import Routines — watched sources and their mappings

What a session records

An upload key and an owner, the filename, extension and type, the declared size against how much has been received, the chunk size and how many chunks are expected and received, where it is going — table, field, record and storage kind — its state, the resulting file or document, any error, a staging path, who started it and when, when the last chunk arrived, and when it completes or expires.

Each chunk is verified

Chunks record their number, size, checksum, location and arrival time. So a corrupted chunk is detected rather than assembled into a broken file.

Why chunking matters

A single large request fails entirely on a dropped connection, times out on a slow one, and cannot report progress. Chunks fail individually and can be retried, which is the difference between a large upload that works on a mobile connection and one that never completes.

Sessions expire

An upload that never finishes would otherwise hold staged data forever. The expiry is what cleans that up, and it is why an abandoned upload does not accumulate.

Stalled sessions are a diagnostic

A user reporting that a large upload "does not work" can be answered from the session: how much arrived, when the last chunk came, and what the error was.

That is far more useful than asking them to try again.

A pattern of stalls means something

Several users stalling at a similar point usually means a size limit somewhere in the path — a proxy, a web server, a load balancer — rather than the platform. The received size at which they stop is the clue.

Tell users what is happening

A large upload takes time, and an interface that gives no indication produces users who navigate away part way through. Progress and a clear completion message are worth the effort.

Staged data is real data

A partly uploaded file is a partly uploaded file of something, sitting in a staging area. It should be protected like the finished article and removed when the session expires.

Test on a poor connection

Not on a wired desk. Upload something genuinely large from a phone on mobile data, and interrupt it. That is how your users will do it.

Worked example

A team investigating failed uploads found sessions consistently stalling near the same received size, which identified a proxy limit rather than a platform one. Expired sessions were confirmed to be clearing their staged data.

Recommendations

• Use the session to diagnose, not the user’s account.
• A common stall size means a limit in the path.
• Show progress for large uploads.
• Test from a phone on mobile data, and interrupt it.