File Stores

Where uploaded files physically live (local disk, Amazon S3 or Azure Blob Storage), and File Stores: shared libraries of folders and files with their own permissions.

File Stores Overview

"File storage" covers two different things on this platform, and most confusion about files comes from mixing them up. One is the storage backend: where every uploaded file's bytes physically live. The other is a File Store: a shared library of folders and files with its own permissions, which people browse and pick files from.

Where to find it

Architect Panel → Data:

File Stores — the shared file libraries and their folder trees
Large Uploads — upload sessions in progress and recently finished

Architect Panel → Integration & Connections:

Deployments — the File Storage card, which shows the storage backend in use

Architect Panel → Security:

Security Check-up — the File storage and Stored file links rows

The storage backend: one per installation

Every file the platform stores (attachments on records, File Store contents and image thumbnails) goes to the same backend. There are three:

Local Web Server: files are written to folders on the server itself.
Amazon S3: files are written to one S3 bucket.
Azure Blob Storage: files are written to one container in an Azure storage account.

The backend is chosen by your hosting administrator in the server configuration, along with the bucket or container and its credentials. Nothing about it is set on a screen, and a File Store cannot have a backend of its own. Each tenant's files are kept under their own prefix within the one bucket or container. See Local, S3 or Azure Storage for how to choose.

Where a record's attachments go

A File Upload field on a datastore does not point at a File Store. Each field has its own storage mode (public, private or external, or a combination), which decides whether the file can be reached by a plain link or only through the platform's permission check. See Public & Private Paths.

File Stores: shared libraries

A File Store is a named library with a folder tree inside it. It is the right home for files that belong to nobody's record in particular: policies, templates, shared reference material, a team's working folders.

Folders nest, and each file keeps its earlier versions when it is replaced.
Permissions are per store, per security group: Read, Create Folders, Upload Files, Edit Existing Files/Folders and Delete Files/Folders.
People reach a store by browsing it, or through a File Store Selection field on a form or record, which lets them pick files out of a chosen store.
Files in a store can be adopted as documents, gaining document control features. See Bringing Documents In.

Checking what you have

Open Deployments and read the File Storage card. Storage Mode shows Local Web Server, Amazon S3 or Azure Blob Storage, with the S3 bucket or the storage account and container.
Open Security Check-up and read the File storage and Stored file links rows in the Data protection section.
Open File Stores to see which libraries exist, then check each one's permissions.

What goes wrong

Somebody asks to "put this File Store on S3". That cannot be done per store. Moving to a different backend moves every file on the installation and is a job for your hosting administrator.
Uploads fail across the whole site at once. Suspect the backend: credentials, bucket or container. Check the Error Log for storage errors.
A user can see a store's files but cannot add any. Their groups have Read on that store but not Upload Files.

Worked example

A charity runs on Amazon S3. Case attachments are private File Upload fields on the case datastore, so they are only served after a permission check. Separately, a "Policies" File Store holds the current policy set: all staff have Read, and the governance team also has Upload Files and Edit Existing Files/Folders. When an auditor asks where documents are kept, the administrator shows the Deployments card for the backend and the store's permissions for who can reach what.

Recommendations

Keep the two ideas separate when you plan: the backend is infrastructure, a File Store is a library.
Use private storage modes for attachments that hold personal data.
Use File Stores for shared material, not for records' attachments.
Grant store permissions to groups and review them like any other access.

Local, S3 or Azure Storage

The storage backend decides where the bytes of every uploaded file live: on the web server's own disk, in an Amazon S3 bucket or in an Azure Blob Storage container. There is one backend for the whole installation, chosen by your hosting administrator. This article explains what each one means for you as an administrator, and how to check which one you have.

Where to find it

Architect Panel → Integration & Connections:

Deployments — the File Storage card: Storage Mode, plus the S3 bucket or the Azure storage account and container

Architect Panel → Security:

Security Check-up — File storage and Stored file links, in the Data protection section

Architect Panel → Activity:

Error Log — storage errors, such as a refused upload or a missing credential

The three backends

Local Web Server: simplest, with nothing outside the server to configure. Files live and die with that server, so it suits a single long-lived server with its own backups, and does not suit containers that are replaced on each deployment.
Amazon S3: one bucket for the installation, with each tenant's files under its own prefix. Supports direct uploads from the browser for large files and the Web Video field type. Credentials are set by your hosting administrator; S3-compatible services from other providers are not supported, because there is no setting for a different endpoint.
Azure Blob Storage: one container in one storage account, signed with the storage account key. Suits organisations whose infrastructure is already in Azure. See Azure Blob Storage for what it does and does not support.

None of these is set on a screen, and File Stores and upload fields cannot use different backends. Switching backend means moving every existing file; the platform has no built-in migration, so plan it with your hosting administrator.

How download links work

With S3 or Azure, your hosting administrator also chooses a link mode, and it is the setting that decides whether a stranger holding a URL could read a file:

Signed links (the default on both): each download gets a short-lived signed URL, so the bucket or container can stay private. The Security Check-up shows this as OK.
Direct links: files are served by a plain URL straight from storage. Pages load faster and the server does less work, but the bucket or container must be publicly readable. The Security Check-up marks this as Review, with the note "files are served straight from storage, so the bucket/container must be public".

Private files are always checked against the person's permissions before any link is issued; the link mode only affects what happens after that check.

Thumbnails and content types

Image thumbnails are made for JPG, JPEG, PNG, GIF and BMP files when a File Upload field has thumbnail sizes set, and they are stored on the same backend. Thumbnails now carry the correct image type when they are written to S3 or Azure. Older thumbnails written to S3 before that fix may be stored with a generic type, which some browsers download instead of displaying; your hosting administrator has a repair script that corrects them, with a dry run first.

Checking your backend

Open Deployments and read Storage Mode on the File Storage card: Local Web Server, Amazon S3 or Azure Blob Storage.
Open Security Check-up and confirm the Stored file links row says every download is a short-lived signed URL, unless you have deliberately chosen direct links.
Upload a file to a private File Upload field, download it while signed in, and confirm it opens.
Open Error Log and check nothing was logged for the upload.

What goes wrong

Storage Mode shows Unknown. The configured backend name is not written exactly as expected. If it is not a recognised backend at all, the platform falls back to storing files on the local server, which is probably not what was intended. Ask your hosting administrator to check it.
Every upload fails with "Server error when trying to upload file". The Error Log entry says why: usually missing or wrong credentials, or a bucket or container that does not exist.
Images download instead of displaying. Likely an old S3 thumbnail with the wrong type; ask for the repair script to be run.
Files are readable by anybody with the link. Direct links are in use. Decide whether that is acceptable for the data you hold.

Worked example

A council moves its installation from a single server to containers. On Local Web Server, files would vanish with each replaced container, so the hosting administrator switches to Azure Blob Storage, where the council's other systems already live, and copies the existing files across first. Afterwards the administrator confirms Storage Mode reads Azure Blob Storage, the Security Check-up shows signed links, and a test upload and download leave nothing in the Error Log.

Recommendations

Use an object store (S3 or Azure) for anything running in containers.
Keep signed links unless every file you hold is meant to be public.
Read the Deployments card rather than assuming which backend you are on.
Plan any backend change as a migration, with a copy of every file and a test afterwards.

Configuring a File Store

A File Store is a shared library of folders and files that people browse, add to and pick from. Setting one up means deciding what kind of store it is, which columns people see, who may do what in it, and where they will reach it from. Where the files physically live is not part of a store's settings: that is the installation's storage backend, which your hosting administrator sets.

Where to find it

Architect Panel → Data:

File Stores — the stores and their settings
Datastores — where a File Store Selection field is added to a datastore

Admin Panel → User Administration:

User Groups — the security groups a store's permissions are granted to

What a store's settings hold

A name, which is what people see when they browse or pick from it.
Its path type: virtual or physical. A virtual store is a library the platform manages: folders, files and the earlier versions of each file are records, and the files themselves go to the installation's storage backend. A physical store lists a folder on the web server's own disk. Use virtual unless you have a specific reason not to; a physical store only makes sense on an installation that stores files locally, and it does not keep versions.
The columns to show when somebody browses the store, chosen from a list such as icon, file name, type, size and version, plus date and owner details. A store with no columns chosen cannot be browsed at all; it shows "There are no fields in this filestore - please go to the filestore settings to add some."
Permissions, per security group, covered in Structure and Permissions.

Setting up a store

Decide who the store is for. One store per audience keeps permissions simple: a store that two groups need to see differently is usually two stores.
Open File Stores and add a store with a clear name and a virtual path type.
Choose the columns people should see. File name, type, size and version are a sensible start.
Grant permissions to each security group that needs the store: Read for everybody who should see it, and Upload Files, Create Folders, Edit Existing Files/Folders or Delete Files/Folders only for the people who maintain it.
If people should pick files from the store on a form or record, add a File Store Selection field to that datastore, point it at the store, and set how many files may be picked.
Test it as a member of each group, as described below.

How people use a store

Browsing a store shows its folder tree from a Home breadcrumb, with Add Folder and Upload Files buttons for people whose groups hold those permissions. A File Store Selection field opens the same browser inside a form, so a person can pick an existing file rather than uploading a copy.

The File Store Selection field has a setting for permitted file types, but it is not yet enforced. To restrict file types today, use a File Upload field, which has its own allowed-file rules: see File Uploads.

Testing

Sign in as a member of a group with Read only. Confirm the store opens, and that Add Folder and Upload Files are not offered.
Sign in as a member of a maintaining group. Create a folder, upload a file, then upload a replacement and confirm the earlier version is kept.
Sign in as somebody with no permission on the store. Opening it should say "You do not have access to this file store."

What goes wrong

"There are no fields in this filestore": no columns are chosen in the store's settings.
"You do not have access to create folders in this file store." or a similar message for uploading, renaming or deleting: the person's groups lack that permission on this store.
A physical store shows nothing on S3 or Azure: physical stores read a folder on the web server, which object storage does not have. Use a virtual store.

Worked example

A school sets up a virtual "Staff Policies" store. All Staff get Read; the Business Manager group gets Upload Files, Create Folders and Edit Existing Files/Folders; only the Head's group can delete. A File Store Selection field on the incident form, limited to one file, lets staff attach the relevant policy without uploading a copy. Testing as a teacher confirms there is no Upload Files button.

Recommendations

Use virtual stores, which keep versions and work on every backend.
One store per audience, rather than folders with different expectations.
Grant Read widely and write narrowly.
Test as a member of each group, never as an administrator.

Structure and Permissions

A File Store is more than a folder. Inside a virtual store is a tree of folders and files in which every file keeps its earlier versions, and around it sits a set of permissions granted to security groups. This article explains both, so you can design a store that people can find things in and that only the right people can change.

Where to find it

Architect Panel → Data:

File Stores — the stores, their settings and their permissions
Large Uploads — upload sessions in progress and recently finished, including uploads into stores

Admin Panel → User Administration:

User Groups — the security groups a store is granted to

The folder tree

In a virtual store every entry names its parent, so folders nest to any depth. Each entry is either a file or a folder, and a file points at its current version. Replacing a file adds a new version rather than overwriting the old one, so earlier versions remain available.

Two consequences are worth planning for. A store grows faster than the number of files people think they have put in it, because every replacement is kept. And reorganising a large tree later is disruptive, because people have learned where things are.

Physical and virtual stores

A store is one or the other, not both. A virtual store is the managed library described above, and its files go to the installation's storage backend, whether that is local disk, S3 or Azure. A physical store simply lists a folder on the web server's own disk, with no versions; it does not work on an installation that keeps its files in S3 or Azure.

Permissions are per store, per group

Each grant names a security group and the permissions it holds on that store. People get the combination of everything granted to all their groups. The permissions are:

Read: open the store, browse its folders and download files. Without it, the store says "You do not have access to this file store."
Upload Files: add files. The Upload Files button only appears with this permission.
Create Folders: add folders. The Add Folder button only appears with this permission.
Edit Existing Files/Folders: rename entries.
Delete Files/Folders: remove entries. Deleting a folder removes everything below it, so grant this sparingly.

These are checked on the server for every action, whatever the screen shows.

Designing a store

Draw the boundary around an audience. Permissions attach to the whole store, not to folders inside it. If two groups need different access, make two stores.
Keep the tree shallow and obvious: by year, by type, by customer. Avoid mirroring an organisation chart that will change.
Grant Read to everybody who needs to see the store, and the other four permissions only to the people who maintain it.
Create the top-level folders yourself before opening the store to others, so the structure is set before files arrive.
Review the grants at least once a year. Stores accumulate access as groups are repurposed and projects end.

Bringing store files into document control

A file in a store can be adopted as a document, gaining classification, an access log and review dates, while the store keeps the original. The store's own Read permission is still checked whenever the file is downloaded. See Bringing Documents In.

What goes wrong

Somebody can see a store but has no Upload Files button. None of their groups holds Upload Files on that store.
A deleted folder took more than expected with it. Folder deletion cascades to everything below. Restrict Delete Files/Folders to a small group.
A store is filling up storage. Every replacement keeps the previous version. Check whether people are uploading new copies of large files repeatedly.

Worked example

An organisation runs three virtual stores: "Public Assets", readable by everybody and maintained by the communications team; "Customer Contracts", readable and maintained by the account team only; and "HR Files", restricted to two people who hold every permission. Each has a shallow tree by year. Because the boundaries follow the audiences, the answer to "who can see the contracts?" is one line per store.

Recommendations

Separate stores by audience, not by folders within one store.
Design a shallow tree before loading files.
Keep Delete Files/Folders to a few people.
Remember versioning when estimating storage.
Review each store's grants periodically.

Azure Blob Storage

Azure Blob Storage is the third storage backend, beside the local web server and Amazon S3. With it, every file the installation stores goes into one container in an Azure storage account. Choose it when your organisation's infrastructure, data residency commitments or contracts already sit in Azure.

Where to find it

Architect Panel → Integration & Connections:

Deployments — the File Storage card shows Azure Blob Storage, the Storage Account and the Container in use

Architect Panel → Security:

Security Check-up — File storage, and Stored file links for the link mode

Architect Panel → Activity:

Error Log — every Azure error, with the HTTP status and Azure's own error code

Everything else is set in the server configuration by your hosting administrator. There is no Azure settings screen.

Before you start

Azure support is new. It has been checked thoroughly by the platform's automated tests, but at the time of writing those tests run without a real storage account, so it has not yet been proven end to end against Azure itself. Trial it on a non-production installation, with the checks below, before you rely on it.

What your hosting administrator sets up

Create the storage account and the container in the Azure portal. The platform never creates a container, so it must exist first.
Decide the container's public access level. Leave it private unless you choose direct links (below).
Give the platform the storage account name, one of its access keys and the container name. These go in the server's private configuration, not in any synced settings file, because the key has full control of everything in the storage account. Sign-in by managed identity or a SAS token as the credential is not supported: only the account key.
Set the storage backend to Azure and choose the link mode.
Move any existing files into the container if the installation already has files on another backend. There is no built-in migration.

Link modes

Signed links (the default): each download gets a short-lived, read-only URL for that one file, valid for 60 minutes unless your hosting administrator sets another lifetime. Works with a private container.
Direct links: a plain URL to the file. Faster, with less load on the server, but it only works if the container's public access level allows anonymous reads of blobs, which means anybody with a URL can read the file. The Security Check-up marks this as Review.

Permissions are checked before either kind of link is given out. Because public access is set on the container, not per file, a public-or-private choice made for each S3 upload has no equivalent on Azure.

What works, and what does not

Works: uploads through File Upload fields and File Stores, private downloads, image thumbnails, deleting files, and eLearning packages.
Large files: the browser still sends large files to the server in chunks, so the browser side can resume. The server then sends the file to Azure in one piece, or in 64 MB blocks above that size. That server-to-Azure step does not resume; if it fails, the upload fails and is logged.
Not available on Azure: direct uploads from the browser to storage (an S3-only feature), and the Web Video field type, which stores the file as an ordinary file instead. Image moderation checks only images up to 5 MB, against 15 MB on S3.

Checking it works

Open Deployments and confirm Storage Mode reads Azure Blob Storage, with the right Storage Account and Container.
Upload a small file to a private File Upload field, then download it while signed in.
Upload an image to a field with thumbnails, and check the thumbnail displays.
Upload a file larger than 64 MB, if your upload limits allow it, to exercise the block path.
Open Error Log and confirm nothing was logged from Azure.

What goes wrong

"no Azure storage account is configured", "no Azure blob container is configured" or "the Azure storage account key is not valid base64" in the Error Log. A configuration value is missing or mistyped.
An Error Log entry naming a request, a status and an Azure error code, for example a 403 with an authentication failure. Usually the wrong key, or a key that has been rotated in the portal.
A block was refused during a large upload. The log says the staged blocks are billable until Azure removes them, which it does after seven days.
Direct links return an error. The container is private. Either set its public access level or go back to signed links.

Worked example

An NHS supplier must keep data in its own Azure tenancy. The hosting administrator creates a private container, configures the account key and switches the installation to Azure with signed links. On the test installation the administrator uploads a PDF, an image and a 120 MB video file as an ordinary attachment, downloads each, and checks the Error Log is clean before repeating the change on production.

Recommendations

Trial it on a test installation first, while Azure support is new.
Keep the container private and use signed links.
Rotate the account key with your hosting administrator, not alone; the platform stops storing files the moment its key is wrong.
Use S3 if you need direct browser uploads or Web Video fields.