Working with Files

The File component handles file uploads in Unqork. This guide covers storage options, Cloud Storage Delivery URLs, how files are represented in , retrieval patterns, and limitations.

Storage Options

Files can be stored in Unqork's cloud storage or in an external file service. The choice is controlled by the File component's Store Data in Database setting.

Storing Files in Unqork

When Store Data in Database is set to ON, files are submitted to Unqork's cloud storage. Unqork handles validation and storage automatically:

• File type and extension are validated before upload. Files that do not match the Set File Formats to Accept setting are rejected.
• Files up to 100 MB are automatically scanned for malware before being stored. Files above 100 MB are not automatically scanned.
• Files are stored in the cloud with no practical storage quota.
• A Cloud Storage Delivery URL is generated for each file. See Cloud Storage Delivery URL for details.

No additional service configuration is needed—files are uploaded using Unqork's Attachments API.

Storing Files Externally

When Store Data in Database is set to OFF, Creators must use a Plug-In component to send the file to an external file service like Google Drive or Dropbox.

Consider the following when storing externally:

• Creators must set up an API account with the external file service and configure the service in Services Administration.
• Creators are subject to the external file service's pricing and usage quotas.
• Creators and the external file service assume all responsibility for virus scanning.
• File access permissions depend on the external file service and its configuration.

Cloud Storage Delivery URL

When a file is stored in Unqork cloud storage, a Cloud Storage Delivery URL is generated to provide access to the file. This URL includes a unique signature tied to the logged-in Creator or service account.

• Only the user who generates the URL can use it to access the file.
• When the file is first uploaded, the returned URL can be saved in a submission. Each time a Creator with access to that submission retrieves the URL, a new signature is generated for that user.
• Cloud Storage Delivery URLs expire after 24 hours.

How Files Are Represented in Submission Data

The File component's submission data is an array of objects, where each object represents one file. The structure depends on the Parse Files on Upload setting.

Cloud Storage (Parse Files on Upload: OFF)

When Parse Files on Upload is OFF (the default), the file is stored as a reference in the cloud. The submission data object contains:

[
  {
    "storage": "cloud",
    "name": "document.pdf",
    "id": "c83ffe8b-6e90-4920-8e37-44a46f21cf42",
    "size": 235157,
    "type": "application/pdf"
  }
]

Base64 (Parse Files on Upload: ON)

When Parse Files on Upload is ON, the file's data is encoded as a Base64 string before submission. On submitting to Unqork, the Base64 data is replaced with a cloud storage link.

Important: Avoid storing files as Base64 unless necessary—for example, to read data from an xlsx or CSV file, or to render a thumbnail preview. Base64 encoding increases the original file size by approximately 33%, which reduces the submission size limit to approximately 18 MB.

File Compression

Unqork automatically compresses images in some cases:

• Only PNG and JPG file types can be compressed.
• Compression applies regardless of the device or operating system.
• Compression is lossy and might reduce image quality.
• Compression is not applied when Parse Files on Upload is OFF (cloud storage mode).

Sending and Retrieving Files Using a Plug-In Component

Sending Files Externally

When sending files to an external file service using a Plug-In component:

• JSON request body: 50 MB — applies to all JSON requests sent through Unqork's server, including requests that send Base64-encoded data to external services.
• Binary file upload (multipart): 500 MB per file.
• When sending files to a server-side executed module using a proxy request, the limit is 25 files at 500 MB total. This applies to the Execute via Proxy - POST Unqork service.

Check the external file service's documentation to verify the file size limits accepted by its API. Some external services require batching file uploads into multiple fragments—the Plug-In component does not support batching.

Retrieving Files Using a Plug-In Component

To retrieve a file stored in Unqork cloud storage using a Plug-In component:

As binary:

1. Use a Plug-In component in a server-side execute module.
2. Set Data Source URL to the Cloud Storage Delivery URL (for example, {{data.fileUrl}}).
3. Set Request Type to GET.
4. Set Expect Binary Response to ON.

As Base64:

Use the resolveBase64 output type, or chain two Plug-In components—a GET request with Expect Binary Response set to ON, followed by a POST request.

Note: Using the contents Output Type to retrieve a file as Base64 has a limit of 10 MB.

File Component Limitations

• Not a media player: The File component does not support viewing or playing uploaded files. The only exception is the Display Thumbnail Images or Icons setting.
• Not supported inside grids: The File component cannot be used inside the Advanced Datagrid, Data Grid, Freeform Grid, or Uniform Grid components.
• Request timeout: Any file-related or API request lasting longer than five minutes will fail.

Working with File Data in Formulas

The following formulas are useful when working with file data in the Calculator or Data Workflow component:

Important: Never modify file objects stored in submission data. File objects represent Unqork files, and altering them can cause issues with uploads and downloads.