File storage
Keep uploaded files in Dropbox, Google Drive, OneDrive, S3 and S3-compatible storage, or Box.
File storage connections copy the files people upload (File upload, Image upload and Signature fields, including those inside a Repeating group) to Dropbox, Google Drive, OneDrive or SharePoint, Amazon S3 or an S3-compatible service, or Box. They are ordinary connections: set the service up once, add it to a form, and it runs in the background with conditions, logs and retries.
Where uploads go first#
Every upload is first kept on the site. Kindly Edit > Forms > Settings > Uploads has Keep uploaded files in: A private folder (only people who see entries), The Media Library, or Both. Delete files from unsent forms after (days) removes uploads from forms that were never sent.
A storage connection then copies the files to the service. It can also remove the site's private copy once the service has the file.
Set up a service#
Open Kindly Edit > Forms > Connections and choose the service.
| Service | What you need |
|---|---|
| Dropbox | An app in the Dropbox App Console with scoped access and files.content.write, files.content.read and sharing.write. Its App key is the OAuth client ID. |
| Google Drive | A Web application OAuth client in the Google Cloud console with the Google Drive API enabled. Access: Only folders and files Kindly makes, or All of Drive (to use folders you made yourself). Sign in again after changing it. |
| OneDrive | An app registered in the Microsoft Entra admin center with a Web redirect address and the delegated permissions Files.ReadWrite.All and offline_access. Its Application (client) ID is the OAuth client ID. Tenant: empty for any account, or your directory's ID or domain. |
| Box | A Custom App in the Box Developer Console with user authentication (OAuth 2.0) and the scope to read and write files. |
| Amazon S3 and compatible storage | An Access key ID and Secret access key that may put objects in the bucket (s3:PutObject, and s3:ListBucket for the connection check), and the Bucket. |
For the four sign-in services, give the service the address shown as Address to give the service, type the client ID and Client secret, choose Save and check, then Sign in to the service. The tile then shows the account it is connected as.
S3 has more settings for other providers:
- Region: such as
us-east-1. Cloudflare R2 usesauto. - Endpoint: empty for Amazon S3. Otherwise the service's S3 address, such as
https://ACCOUNT.r2.cloudflarestorage.com(Cloudflare R2),https://s3.us-east-1.wasabisys.com(Wasabi),https://nyc3.digitaloceanspaces.com(DigitalOcean Spaces) orhttps://s3.us-west-004.backblazeb2.com(Backblaze B2). - Put the bucket in the path, not the host name: for MinIO and services without bucket host names.
- Public address: optional, the address the files are public at (a CDN or the bucket's public domain), for public links.
Keys and secrets are kept on the server and never shown again. See How keys are kept.
Add storage to a form#
In the form's Connections tab, choose Add a connection and pick the service from File storage. Its settings:
| Setting | What it does |
|---|---|
| Upload fields | Which upload fields to store. Leave empty to store the files of every upload field. |
| Folder | Where the files go. Starts as Forms/{form_title}/{entry_id}. Missing folders are made. |
| File names | Keep the name it was sent with, or Use a pattern. |
| Name pattern | With a pattern: starts as {entry_id}-{file.name}. The file's extension is always kept. |
| Link | Whether to make a share link, and for whom. The choices depend on the service (below). |
| Remove the copy on this site once the file is stored | Removes the site's private copy after the service confirms the file. |
Each service adds one setting of its own:
- Google Drive and Box: Start in folder (ID), the folder's ID from its address (after
/folders/in Drive, after/folder/in Box). Empty starts in My Drive or All Files. - OneDrive: Drive ID, for a SharePoint document library. Empty uses the signed-in account's OneDrive.
- S3: Bucket (empty uses the connection's bucket) and Storage class (The bucket's default, Standard, Infrequent access, Intelligent tiering or Glacier instant retrieval).
Run and Run only when conditions are met work as for every connection. Storage usually runs When sent, or When payment succeeds for order forms.
Folder and name patterns#
The folder and name patterns accept any smartcode, such as {form_title} or {inputs.last_name}, plus these:
| Code | Is |
|---|---|
{entry_id} |
The entry's ID |
{entry_serial} |
The entry's number within its form |
{field} |
The upload field's name |
{file.name} |
The file's name as it was sent, without the extension |
{file.ext} |
The extension |
{file.index} |
The file's number within its field (1, 2, 3 ...) |
Slashes in the folder make subfolders. Characters the services refuse (such as \ : * ? " < > | # %) become hyphens, and each folder or file name is cut to 120 characters.
Example: Members/{inputs.last_name}/{entry_serial} with the name pattern {field}-{file.index} stores the second photo of entry 12 from Rivera as Members/Rivera/12/photos-2.jpg.
Share links#
| Service | Link choices |
|---|---|
| Dropbox, Google Drive | No link, A view link for anyone who has it |
| OneDrive | No link, A view link for anyone who has it, A view link for people in your organization |
| Box | No link, A link for anyone who has it, A link for people in your company |
| S3 | A private link through this site, The public address |
With No link, the stored file is still listed on the entry and opens the file's page in the service for people signed in to it.
S3 has no lasting private link. A private link through this site is a site address that checks the person can see the form's entries (or carries a signature from an email), then sends them to a fresh S3 address that works for 5 minutes. The public address uses the connection's Public address and needs the bucket or CDN to serve files publicly.
Removing the site copy#
With Remove the copy on this site once the file is stored, the site's private copy is deleted only when every storage connection of the form that covers that field has stored the file. The answer keeps the file's name and points at the stored file instead, so {all_data}, {inputs.FIELD}, the entry screen and exports link there. The Activity log records "Site copy removed after storing" with the file names.
A Media Library copy is never removed this way; it stays the copy shown.
Timing#
Storage runs in the background queue, after the entry is stored. Emails set to go When sent are sent during the submission, before the upload has happened. So:
- Emails sent on submit link to the site's own private copy, not to the cloud.
- Cloud links appear on the entry, and in
{inputs.FIELD}, only after the background upload has finished and the site copy was removed. - If an email must carry the cloud link, send it on a later event (such as When approved), after the upload has run.
Large files and retries#
Small files go in one request. Larger ones go through the service's upload sessions in pieces of about 8 MB (filter kindly_forms_storage_chunk_size). The files are read from disk piece by piece, never all at once.
If a queue run runs short of time, the upload stops with "The upload carries on in the next run." Its progress is kept for a week, so the next attempt carries on where it stopped. A retry, or Run connections again on the entry, sends only the files that aren't stored yet; the log says "Every file was already stored" when there is nothing left to do.
If a share link fails after the file is stored, the log says "Stored, but the link wasn't made", and the next attempt only makes the link.
On the entry#
The entry's view in Entries has a Stored files panel: each file with the service's name, a link to open it and its folder path. The connection's lines in Logs > Connection calls show each request, with file contents and signed addresses left out.
Check it before going live#
Send a harmless test file through the form, then confirm it in the service's folder, on the entry's Stored files panel and in Logs before using the connection on a live form.