Skip to content

File and Attachment Handling

Overview

Formbird supports offline file attachments through two storage mechanisms: the Origin Private File System (OPFS) for efficient binary storage and IndexedDB for file metadata. Files are cached during the initial caching process and can be uploaded when the device reconnects.

Storage Architecture

Storage Layers

┌─────────────────────────────────────────────────────────────────────┐
│                    File Storage Architecture                         │
│                                                                      │
│  ┌─────────────────────────────┐   ┌─────────────────────────────┐  │
│  │   IndexedDB                 │   │   OPFS (Origin Private FS)  │  │
│  │                             │   │                              │  │
│  │  - documents collection     │   │  - Binary file data          │  │
│  │    (normal documents)       │   │  - Images, documents, media  │  │
│  │  - offlineFiles collection  │   │  - Efficient storage         │  │
│  │    (file attachments)       │   │  - File handles per user     │  │
│  │  - fileReference documents  │   │                              │  │
│  │  - File metadata            │   │                              │  │
│  └─────────────────────────────┘   └─────────────────────────────┘  │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    Cache Storage                             │   │
│  │  - Service worker cached files (static assets)               │   │
│  │  - Map icons, stylesheets                                    │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

IndexedDB Collections

On the IndexedDB side: - documents collection - Stores normal documents (templates, rulesets, regular documents) - offlineFiles collection - Stores file attachment metadata and references

OPFS (Origin Private File System)

OPFS provides efficient binary storage:

  • Direct file access - Uses the FileSystemDirectoryHandle API
  • User isolation - Separate storage per user
  • Large file support - Handles large attachments efficiently
  • Browser storage - Persists across sessions

Setting Up Offline File Attachments

To enable offline file attachments, you need to configure the fileReference template and ensure new file references receive offline keys.

1. Configure the fileReference Template

The fileReference template must have an offline key in its systemHeader.keyIds:

{
  "systemHeader": {
    "systemType": "template",
    "keyIds": ["your-offline-key"]
  }
}

2. Add Offline Keys to New File References

New fileReference documents need offline keys to be cached. Configure one of the following:

Option A: Using attachKeys on the Template

Add attachKeys to the fileReference template so new documents automatically receive the offline key:

{
  "attachKeys": ["your-offline-key"]
}

Option B: Using a preSaveClient or preSaveOffline Rule

Create a ruleset that adds the offline key to new fileReference documents before saving. This approach is useful when you need conditional logic for which files should be available offline.

  • preSaveClient - Runs on all client saves
  • preSaveOffline - Runs only when saving while offline

Verification

After setup, verify that: - The fileReference template has the offline key in keyIds - New file uploads create fileReference documents with the offline key - Files are being cached when offline caching is enabled

File Reference Documents

Structure

File attachments use fileReference documents to store metadata about cached files:

Property Description
fileName Original name of the file
fileNo Unique identifier for retrieving the file
contentType MIME type of the file
fileSize Size in bytes
accessKeys Keys that control offline caching

Offline Key Requirement

Only files with an offline access key in their fileReference document are cached for offline use. Files without an offline key will not be available when the device is offline.

Caching Process

When Files Are Cached

Files are cached after document caching completes:

  1. All documents are cached to IndexedDB
  2. The system queries IndexedDB for fileReference documents
  3. For each fileReference with an offline key:
  4. The file is downloaded from the server
  5. The file is stored in OPFS
  6. The fileReference is updated with the local path

Bulk Caching Efficiency

To maintain efficient caching:

  1. First pass - Bulk insert all documents to IndexedDB
  2. Second pass - Query for fileReference documents
  3. Parallel download - Download files in batches

This approach prevents slow sequential file downloads during document caching.

File Retrieval

Offline File Access

When retrieving a file while offline:

  1. The system first checks OPFS for the cached file
  2. If found, the file is returned from local storage
  3. If not found and online, the file is fetched from the server
  4. If not found and offline, an error is displayed

Display in Components

Components like sc-uploader automatically handle offline file retrieval, displaying cached files when available.

Uploading Files Offline

Upload Queue

Files uploaded while offline are stored locally and added to the sync queue. Each queued file includes:

  • The file data (stored in OPFS)
  • File metadata (name, type, size)
  • A temporary file reference
  • Queue status (unprocessed)

Sync Process

When connectivity is restored:

  1. The file is read from OPFS
  2. The file is uploaded to the server
  3. The document is updated with the server's file reference
  4. The file is removed from the upload queue

Multi-User Isolation

How It Works

OPFS files are organized by user directory to prevent conflicts when multiple users share a device:

  • Each user has their own directory in OPFS
  • Clearing one user's cache does not affect other users
  • Files with the same name can exist for different users

Directory Structure

OPFS/
├── user-a-uuid/
│   ├── file-a.pdf
│   ├── file-b.pdf
│   └── file-c.pdf
└── user-b-uuid/
    ├── file-b.pdf
    ├── file-c.pdf
    └── file-d.pdf

Storage Quota

You can monitor available storage through browser developer tools. If storage is running low, consider:

  • Reducing the number of cached files
  • Compressing images before upload
  • Clearing old cached data