Working With Files in Unqork

Estimated Reading Time:  6 minutes

Overview

In Unqork, you can use the File component to upload, maintain, and store items like supported documents and images. This reference guide explores the considerations, expectations, and limitations when working with files in Unqork.

File Storage Expectations

This section describes what you should expect when storing files in Unqork or an external storage system.

Storing Files in Unqork

To store files in the Unqork server, Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. can either:

• Set the File component's Store Data in Database setting to (ON) and create an Unqork submission.

• Manually send the file using a Plug-In component.

Storing to the Unqork servers provides you with the following advantages:

• No extra service configuration is needed because files are submitted using Unqork Submission Attachments API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. (application programming interface) calls.

• Before uploading to the server, the File component ensures all file type/extension validations are correct. Files that contradict the Set File Formats to Accept setting are rejected prior to uploading to the server.

• After passing any front-end validation, Unqork scans for malware Malware is software designed to disrupt, damage, or gain access to a computer system. before uploading the file to the server.

• Files are stored in the cloud with no practical storage quota.

• Only the user who submitted the file using a Cloud Storage Delivery URL has access.

Storing Files Externally

To store files using an external file service (outside of the Unqork servers), Creators must set the File component's Store Data in Database setting to (OFF) and use a Plug-In component to send the file. External file services include Google Drive, Dropbox, and so on.

Consider the following when storing externally:

• Creators must set up an API account with an 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. For example, see the documentation for integrating AWS S3 malware scanning in your application: https://aws.amazon.com/blogs/apn/integrating-amazon-s3-malware-scanning-into-your-application-workflow-with-cloud-storage-security/.

  NOTE  Virus scanning configuration is dependent on the external file service used.

• Permission to access the files depends on the external file service and its configuration.

How Files Are Represented in Unqork Submission Data

The File component’s submission data Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections. is an array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. of objects An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity., where each object represents a single file. How each object is represented depends on your configuration. There are two main representations:

• As a Base64 string.

• As an object stored in the cloud.

Cloud Storage

By default, the File component's Parse Files on Upload is set to (OFF). The file’s data object becomes a reference, with the file stored in the cloud the moment an Unqork submission is created.

Here's an example of a single file object stored before Unqork submission:

[
    {
        "storage": "cloud",
        "name": "Screenshot 2023-03-15 at 15.13.08.png",
        "id": "c83ffe8b-6e90-4920-8e37-44a46f21cf42",
        "size": 235157,
        "type": "image/png"
    }
]

Here's an example of a single file object stored after Unqork submission:

[
    {
        "storage": "cloud",
        "name": "Screenshot 2023-03-16 at 14.23.25.png",
        "id": "edd77456-fb52-4664-a2c0-5442fab7c7b7",
        "size": 793223,
        "type": "image/png",
        "data": "https://testx.unqork.io/fbu/files/submissionBase64/c79910d684253c282910315221269d9d.png?signature=<uniqueSignature>"
    }
]

Base64 Representation

When the File component's Parse Files on Upload is set to (ON), the file’s data is encoded as a Base64 string that becomes part of the component’s submission data. On submitting to Unqork, the file’s data object updates to a cloud storage link, retrieving and resolving the Base64 string. Therefore, when retrieving the Unqork submission, the file’s submission reduces in size.

Here's an example of a single Base64 file object stored before Unqork submission:

[
    {
        "storage": "base64",
        "name": "Screenshot 2023-03-15 at 15.59.06.png",
        "url": "data:image/png;base64,<base64string>",
        "size": 16760,
        "type": "image/png",
        "data": "<base64string>"
    }
]

Here's an example of a single Base64 file object stored after Unqork submission:

[
    {
        "storage": "base64",
        "name": "Screenshot 2023-03-15 at 15.59.06.png",
        "url": "https://testx.unqork.io/fbu/files/submissionBase64/15f80f953695e1e89a83123b42dc58e8.png?signature=<uniqueSignature>",
        "size": 16747,
        "type": "image/png",
        "data": "https://testx.unqork.io/fbu/files/submissionBase64/94896b69237d0dd91a9f58c5e5d54202.png?signature=<uniqueSignature>",
        "imageSrc": "https://testx.unqork.io/fbu/files/submissionBase64/15f80f953695e1e89a83123b42dc58e8.png?signature=<uniqueSignature>"
    }
]

NOTE  Unless you need to read or display file data in your UI (for example, read data from an XLSX/CSV file or render a thumbnail preview), it is recommended that you avoid storing files as Base64 strings. Base64 is an inefficient way to encode file data and causes a 33% increase in the original file size—and even more for smaller files.

[
    {
        "storage": "cloud",
        "name": "Screenshot 2023-03-15 at 15.13.08.png",
        "id": "c83ffe8b-6e90-4920-8e37-44a46f21cf42",
        "size": 235157,
        "type": "image/png"
    }
]

[
    {
        "storage": "cloud",
        "name": "Screenshot 2023-03-16 at 14.23.25.png",
        "id": "edd77456-fb52-4664-a2c0-5442fab7c7b7",
        "size": 793223,
        "type": "image/png",
        "data": "https://testx.unqork.io/fbu/files/submissionBase64/c79910d684253c282910315221269d9d.png?signature=<uniqueSignature>"
    }
]

File Size Limits

The accepted file size limit depends on the configuration and where you store the file. File size limits are not dependent on the device (desktop/mobile, Windows/Mac, iOS/Android). File size limits are enforced regardless of the value entered in the File component's Set Maximum Size field.

NOTE  Any file-related or API request lasting longer than five minutes is not supported and will fail.

If storing the files in Unqork (setting the File component's Store Data in Database to (ON)), the file size limit depends on the File component's Parse Files on Upload setting:

• When Parse Files on Upload is set to (ON), the file size limit is approximately 18 MB (the entire submission payload). The limit decreases if the Unqork submission contains other component data.

• When Parse Files on Upload is set to (OFF), the file size limit is 100 MB per file.

File Compression

This section focuses on image file compression expectations and limitations when using the File component.

• Only .PNG & .JPG file types can be compressed.

• Compression applies regardless of the device, operating system, or image source (desktop/mobile, Windows/Mac/Android/iOS, file picker/image, library/direct photo capture).

• Compression is lossy and may somewhat reduce image quality.

• Image compression is not applied when storing files in Unqork as cloud storage. Storing files in cloud storage occurs when the File component's Parse Files on Upload setting is set to (OFF).

• The File component's Display Thumbnail Images or Icons and Set Image Width settings do not affect compression or storage of the file. These settings only affect how the image thumbnail renders.

Sending and Retrieving Files Using a Plug-In Component

Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. can also manually send or retrieve files captured from the File component using a Plug-In component.

Sending Files Using a Plug-In Component

If storing the files externally (setting the File component's Store Data in Database to (OFF)), the file size upload limit depends on the Plug-In component's file request limit:

• When submitting a file to an external file service using a Plug-In component, the file size limit is 500 MB per file.

When sending files to a server-side executed module using a proxy request, the limit is five files at 100 MB per file. This scenario is specific to the Execute via Proxy - POST Unqork service of the Plug-In component.

Retrieving Files Using a Plug-In Component

Creators can retrieve files already stored in the Unqork cloud storage using a Plug-In component and following configuration.

• To retrieve as binary, use a Plug-In component from the context of a server-side execute module with:

• To retrieve as Base64, consider using the resolveBase64 option or two Plug-In components with the following settings:

1.

Plug-In One: A GET request with Expect binary response set to (ON).

2.

Plug-In Two: A POST request.

File Component Limitations

The following are important limitations of the File component:

• The File component is not a media player or media renderer. It does not support viewing or playing the files it accepts. The only exception is the Display Thumbnail Images of Icons setting.

• The File component is not supported inside the following components:

Other Considerations

Below are some final considerations to keep in mind when dealing with files in Unqork.

• Never augment, extend, or otherwise modify file objects in submission data. These file objects represent an Unqork file and altering them can cause issues with file uploads and downloads.

• Using logic components to trigger a file download using the page or pageOpen Output Types is supported. But the value used with these Output Types must be a valid URL. Ideally this is the Cloud Storage Delivery URL.

• The following are some helpful formulas when dealing with file data: