File Fields

File fields associate uploaded or generated files with records in a Project Database table. Use them when a file belongs to a particular record, such as a customer, order, support ticket, registration, or document entry.

Examples include:

• A contract attached to a customer record.
• A receipt attached to an order.
• A profile photograph attached to a member record.
• Supporting documents submitted with an application or request.
• A generated report associated with a workflow record.

A file field is configured as the Files sub-type of a Text field. It can associate one or more files with the relevant record so that Forms, Pages, Page Flow, Cloud Flow, and other supported Project capabilities can work with them.

Important: Files associated with file fields follow the access rules of their Database table. A file field does not, by itself, make a file private. If the table allows public Read access, files associated with records in that table must be treated as publicly accessible.

File Fields vs. Media

File Fields and Project Media serve different purposes.

Feature	Intended Use	Access Consideration
Media	Public frontend assets such as logos, illustrations, banners, images, and publicly shareable documents.	Media files are public frontend resources.
File Fields	Files that belong to Database records, such as attachments, receipts, photographs, and user submissions.	File access follows the parent table's access rules. A publicly readable table makes its associated files publicly accessible.

For example, a public product catalog may use file fields for product images associated with individual product records. A customer support table may use file fields for attachments submitted with private support requests. These are both record-associated files, but they need different table access configurations.

Choose between Media and file fields based on the file's role in the application. Choose the table's access rules based on who should be able to access its records and attached files.

How File Fields Work

A file field connects a file value with a particular Database record.

A typical workflow is:

1. Create or identify the Database table that owns the record.
2. Add a Text field and select the Files sub-type.
3. Configure the table's access rules for the intended users and operations.
4. Add the corresponding Form field or implement a supported custom upload workflow.
5. Create or update the record with its associated file value.
6. Retrieve or use the file through a permitted Page, Widget, Page Flow, Cloud Flow, or custom application workflow.

For example, a SupportTickets table might contain:

Field	Purpose
Subject	Short description of the issue.
Description	Details provided by the requester.
Status	Current ticket status.
Attachment	File associated with the ticket.

The Form collects the ticket details and attachment. The record stores the file association. The table's access configuration governs access to the ticket and its associated file.

For details about creating and configuring table fields, see Table Fields. For Form configuration, see Form Layout and Fields.

File Access Inherits Table Access

Database file-field attachments use the same access rules as the table that contains their records. This is the central security consideration when deciding where to store files.

In particular:

• If a table permits Public Read access, the files associated with records in that table are publicly accessible.
• If a table restricts Read access to specific Project Users or User Groups, associated files are subject to that table's access restrictions.
• The table's Create, Update, and Delete permissions also matter when designing workflows that add, replace, or remove record-associated files. Use the appropriate permitted operations and any additional trusted processing required by the application.
• Do not assume that a file has its own independent privacy setting merely because it is stored in a file field.

Access Examples

Table Access Configuration	Effect on Associated Files	Example
Public Read	Attached files must be treated as publicly accessible, including to visitors who are not signed in.	Public product images or downloadable product specifications.
Public Create, restricted Read	Visitors may be able to submit records and attachments, while ongoing access to stored records and files is restricted according to the table's Read rules.	Public support or application submission with private follow-up.
Read restricted to a User Group	Associated files follow that group's permitted access to the table.	Internal team documents.
Admin-only Read	Associated files are intended for the permitted administrators rather than public visitors.	Administrative review attachments.

The scenarios are examples of permission design. Configure the actual permissions in the table's Access (Security) settings and test them with the intended user contexts.

For full table-permission guidance, see Table Access.

Publicly Readable Tables Mean Publicly Accessible Files

Consider a public Products table containing an Image file field. Public visitors need to read product records, and the attached product images are also intended to be public. This is a suitable use of a publicly readable table.

Now consider an Applications table containing an IdentityDocument or Resume file field. If that table also permits Public Read access, the associated documents are effectively public, even if your application does not display their links in a Page.

A hidden Button, omitted Table column, restricted Page, Data Design layout, or named query that excludes the file field does not change the table's access rules. Presentation and query configuration should not be used as a substitute for authorization.

Do not place sensitive attachments in a publicly readable table. If the application requires public access to some information but restricted access to attachments, separate that data into appropriately secured tables or implement a trusted file-access workflow designed for that requirement.

Record-Specific and Field-Specific Requirements

Table permissions establish access at the table level. Some applications need more restrictive behavior, for example:

• Each customer should see only their own uploaded documents.
• A reviewer should access attachments only for assigned applications.
• An administrator can view a file, but ordinary users cannot.
• A file becomes available only after an approval step.

Do not assume these rules are automatically enforced just because a record contains a user ID, owner field, or status value. Where table-level access is insufficient, use an appropriately restricted data model and trusted Backend checks before providing access.

If a table is already publicly readable, adding a Cloud Flow check to one download Button does not by itself make the table's attachments private. The underlying table access or storage arrangement must also meet the intended privacy requirement.

Planning File Access Before Building

Before adding a file field, determine:

1. Who is allowed to submit or upload the file?
2. Who may read the associated record and file?
3. Should the file be publicly accessible or restricted?
4. Can users replace or remove existing attachments?
5. Does access vary by user, group, record owner, or workflow status?
6. Does the file require protected processing, review, or temporary distribution?
7. Will the file contain confidential or personal information?

Plan the table and its permissions together. A file field may be technically correct for the record but unsuitable if the table is more widely readable than the file should be.

Using File Fields with Forms

File fields commonly appear in Table-Backed Forms and other supported upload workflows.

A typical example is a support request:

1. A visitor selects Submit Support Request.
2. The application opens a Form with fields for the issue and attachment.
3. The user enters details and selects a file.
4. The Form and configured workflow validate and submit the information.
5. On success, the support record is saved with its file association.
6. Authorized users can later view or process the attachment according to the table's access rules.

For file-related Forms, test both record creation and editing. A supported file control may need to distinguish files already associated with the record from files selected for upload but not yet submitted.

In edit workflows, verify the intended behavior for replacing an attachment, removing a pending upload, or marking an existing file for deletion where those operations are supported.

Avoid assuming that simply adding a generic file input creates the Database field binding or upload lifecycle. Use the supported Form field and workflow configuration for the intended behavior.

For details, see Form Layout and Fields and Form Page Flow.

Using Files in Pages and Custom Frontends

Files associated with records can be used by supported Page and Form features, Page Flow, Widgets, Data Design, and custom frontend JavaScript through the appropriate ioLoop Client APIs and workflows.

For example:

• A product Page may display a publicly accessible photograph associated with its product record.
• A customer portal may offer a document from a table whose access rules permit the current user to read it.
• An administrative Page may list records with attachments for authorized staff.
• A custom SPA-style frontend may implement its own upload and document-viewing interface using the same supported ioLoop Client APIs as built-in components.

Custom implementation does not change the underlying permissions. A custom file viewer, a built-in Form, and a Data Table Widget must all respect the same Database access rules and trusted authorization requirements.

Cloud Flow and File Operations

Use Cloud Flow when a file workflow requires trusted server-side processing, such as:

• Validating a request before processing or returning a file.
• Generating a document or report.
• Reading or transforming file contents.
• Copying a file or coordinating it with another service.
• Applying record-specific authorization before distributing a restricted file.
• Managing file-related work that uses protected credentials or private service connections.

Cloud Flow includes file-related blocks, and the ioLoop Server API provides $io.fs operations for creating, reading, copying, listing, deleting, and obtaining file download URLs. Refer to the Programming Guide for exact parameters and behavior.

Database File Fields vs. Server-Side File Storage

Database file fields associate files with records and follow the parent table's access rules.

The Server API also provides file operations that distinguish public and private cloud file storage. For example, supported $io.fs operations accept an isPublic setting for the relevant storage area, and the API provides download-URL functionality for private files.

These are related capabilities, but they should not be confused:

Capability	Primary Consideration
Database File Field	Record association and access inherited from the parent table.
Public file storage	Files are intended to be accessible publicly.
Private file storage and trusted Cloud Flow	Server-side control over protected files and how access is granted.

Where private distribution is required, ensure the actual storage and access path is private. A Cloud Flow check or expiring link is not sufficient protection for a file that is independently accessible through a publicly readable table or public storage URL.

For implementation details, see Using Files in Cloud Flow and the $io.fs Server API.

Upload, Download, Replacement, and Deletion

Consider the entire file lifecycle, not only the upload step.

Operation	What to Verify
Upload	The current user or workflow is allowed to submit the file and create or update the related record.
Download or View	The table's Read permissions and any additional required authorization permit access.
Replace	The workflow is allowed to update the record and handles the previous attachment appropriately.
Delete	The intended record and file are affected, with the necessary permissions and trusted checks.
Failure or Retry	The user receives meaningful feedback and the record/file state remains understandable.

Do not assume that removing a file reference from a record automatically deletes every stored copy of the underlying file, or that deleting a record automatically removes every associated object. Verify the supported deletion behavior of the particular Form or file workflow.

When changing a table's access rules, also review files and links that may have already been distributed. Do not assume previously shared URLs are automatically invalidated without testing.

Development, Preview, and Production

During Preview, built-in Database operations automatically use the Project's development database. This includes supported operations working with Database records containing file fields.

Use development records and test attachments to verify upload, viewing, replacement, deletion, and access behavior before publishing.

Keep in mind:

• Development and production records are separate.
• The published application uses its production data environment where supported.
• File paths, previously distributed URLs, Cloud Flow operations, and external integrations may require separate environment and access verification.
• Testing a workflow in Preview does not automatically prove that its associated files will be handled correctly in the published application.

For more information, see Development and Production Data and Previewing.

Example: Public Submission with Restricted Attachments

Consider a Project that collects supporting documents for service applications.

The application needs to let public visitors submit an application, while only authorized staff should review the submitted documents.

A suitable implementation approach is:

1. Create an Applications table with the application fields and a file field for supporting documents.
2. Configure the table to permit the necessary public submission operation, but not Public Read of stored application records and attachments.
3. Build a Form that collects the required values and file upload.
4. Use the appropriate authorized backend workflow if the application requires additional validation, review routing, or protected file processing.
5. Build a staff-only Page or workflow for reviewing permitted applications and attachments.
6. Preview as Public, an authorized reviewer, and a user who should be denied access.
7. Confirm that the document cannot be retrieved through an unintended public path.

Contrast this with a public catalog: a Products table containing downloadable brochures can intentionally permit Public Read when those brochures are suitable for public distribution.

Testing File Access

Test the same file workflow under multiple user contexts.

Test	Expected Question
Public visitor with a publicly readable table	Can the visitor retrieve its associated files, as intended?
Public visitor with a restricted table	Is unauthorized read or download blocked?
Authorized User Group	Can permitted users retrieve the files they need?
Unauthorized signed-in user	Are restricted files inaccessible?
Public submission	Can the user upload as intended without gaining unwanted read access to other records?
File replacement	Are the correct record and attachment affected?
Previously shared URL	Does the link's actual access behavior match the current privacy requirement?
Development versus production	Do the correct files and permissions apply in each environment?

Test both the normal interface and any supported direct file-access path. Hiding links or excluding a file field from a table display is not proof of protection.

Troubleshooting

Issue	What to Check
An attachment is unexpectedly accessible to public visitors	Whether its table permits Public Read and whether any public file URL was distributed.
An authorized user cannot access an attachment	The table's Read rules, current user context, record association, and applicable workflow.
The Form saves without the expected file	Field binding, upload state, validation, submission result, and record value.
A replacement or deletion does not behave as expected	Whether the workflow updates the record reference and underlying file correctly.
A download URL remains accessible	The actual file storage/access configuration and whether the URL was intended to expire or be revoked.
A file works in Preview but not after publishing	Development-versus-production record data, file references, current permissions, and external dependencies.

Good Practices

• Match file privacy to table access. Treat files in publicly readable tables as publicly accessible.
• Keep sensitive attachments out of public-read tables. Public submission does not require public record reading.
• Use Media for public interface assets. Use record-associated file fields for files belonging to application data.
• Design the complete lifecycle. Test upload, retrieval, replacement, deletion, and errors.
• Use the appropriate trusted Backend processing. Apply additional authorization where table-level permissions do not express the required policy.
• Review distributed file links. Verify that the actual access path matches the intended restrictions.
• Test different user contexts. Include Public, permitted groups, and denied users.

Common Mistakes

Avoid these patterns:

• Assuming that all files stored in Database file fields are private.
• Configuring Public Read on a table that contains confidential attachments.
• Hiding a download link or excluding a file field from a query and treating that as security.
• Adding a Cloud Flow authorization check while leaving the same file accessible through a public table or URL.
• Confusing file-field access rules with the public/private storage options of the Server API.
• Testing only uploads, without checking direct file retrieval and previously distributed links.
• Assuming deleting a record automatically deletes the underlying file without verifying the workflow.
• Using public Media for sensitive user-submitted documents.

File fields make files part of Project data. Their accessibility must be designed together with the access rules of the table that owns them. In particular, a publicly readable table makes its associated files publicly accessible.

Technical Reference

• Cloud Flow Files Blocks
• $io.fs Server API
• Form Layout and Fields
• Form Page Flow

Related Topics

• Database
• Table Fields
• Table Access
• Forms
• Using Files in Cloud Flow
• Media
• Development and Production Data