DevelopersDeployment GuideGet Help

File Storage

The File component connects the form to a file storage provider and allows the user to upload, view, and manage files. Since <form.io> does not itself store files, we offer a range of 3rd party integrations to meet your File needs.

Azure Blob

The Azure Blob file upload system allows you to upload files from your hosted forms directly to an Azure Blob storage account. Here are the steps to set up this feature functionality.

Azure Portal

Before we begin, you must create or have an existing account within Microsoft Azure

Create new File Service

  • Once we are in the Azure portal interface, we will want to go click on Storage Accounts and add a new storage account.

  • Next, click on the Create button to create the new storage account.

  • After this operation has been completed, we will now need to click on that storage account, then click on Blobs under the Blob Service section, then click + Container.

  • Next, create a new Container by clicking on +Container and then provide a name for your container.

  • Next, we will need to ensure that we can upload files from the domain of our application, to do this, we will configure the CORS section with the domain where we are hosting our application as well as Form.io portal. To do this, we will click on the CORS section, and configure the Blob Storage cors as follows.

  • Now, we will click on Access Keys and copy the following credentials for use later.

Enter Azure Project Settings

  • On form.io go to your Project Settings page and Click on Integrations ❘ File Storage ❘ Azure Blob

  • Enter the information that you copied in the previous configurations as follows.

  • Save your project settings.

  • Now for every File component that you add to a form, you will need to select the Azure File Services Storage dropdown as follows.

Custom Url

Custom Url Provider does not have any settings in the Project Settings. Instead, it is set in the Url field on the form component when it is added to a form.

In order to use a Custom Url Provider, you will need to set up a service that can upload and serve files.

The information posted to the server will be

{
  file: file
}

The server should save the contents of the file somewhere and return the following object.

{
  url: 'http://link.to/file',
  name: 'The_Name_Of_The_File.doc',
  size: 1000
}

You may return additional attributes if desired.

S3

The S3 Storage provider allows file storage and retrieval using any S3 compatible service but was specifically designed for Amazon Web Services S3.

For an on-premise compatible solution, try minio. See our minio installation guide.

If you haven’t already done so, go to Amazon Web Services and sign up for an account.

In order to use S3, you will need to configure an IAM user and an S3 bucket.

Create an IAM user

  • Go to Services ❘ IAM and click on the Users tab.

  • Click the Add User button.

  • Enter a user name such as “S3” and then click Programmatic Access, then click the Next button.

  • Skip the page where you add the user to a group.

  • On the last page, press Create User

  • On the next page, it should show you your access keys. You will need to copy those and add them to a note on your computer which you will need later.

  • Now press Close button, which will take you back to the users list.

  • Find the user we just created and then click on their name, which will show you their Summary

  • Copy the ARN of that user and save it along with your Access Keys from earlier.

  • We are now ready to create the S3 bucket.

Create an S3 bucket

  • Go to Services ❘ S3

  • Click + Create Bucket and enter a name and region for the bucket and click Next

  • Click Next for all the other pages of the wizard to complete the creation of the bucket. We can configure all of these options after the bucket is created.

  • Click on that bucket which will take you to the bucket page. Click on the Permissions tab.

  • Now, click on Bucket Policy button and then add the following policy to your bucket.

     {
   "Version": "2012-10-17",
   "Statement": [
     {
       "Sid": "UploadFile",
       "Effect": "Allow",
       "Principal": {
         "AWS": "arn:aws:iam::XXXXXX:user/S3"
       },
       "Action": [
         "s3:GetObject",
         "s3:PutObjectAcl",
         "s3:PutObject"
       ],
       "Resource": "arn:aws:s3:::formio-upload/*"
     }
   ]
 }

  • If you wish to have Public Read access to your files, then you will need to add the following rule to your policy.

     {
    "Sid": "crossdomainAccess",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::formio-upload/crossdomain.xml"
 }

    So that it looks like the following.

     {
    "Version": "2012-10-17",
    "Statement": [
       {
          "Sid": "UploadFile",
          "Effect": "Allow",
          "Principal": {
             "AWS": "arn:aws:iam::XXXXXX:user/S3"
          },
          "Action": [
             "s3:GetObject",
             "s3:PutObjectAcl",
             "s3:PutObject"
          ],
          "Resource": "arn:aws:s3:::formio-upload/*"
       },
       {
          "Sid": "crossdomainAccess",
          "Effect": "Allow",
          "Principal": "*",
          "Action": "s3:GetObject",
          "Resource": "arn:aws:s3:::formio-upload/crossdomain.xml"
       }
    ]
 }

  • Important Note You will need to make sure you replace the arn:aws:iam::XXXXXX:user/S3 with the ARN you copied when you created the user, and also replace the formio-upload with the name of your new bucket.

  • Next click on CORS configuration and add the following.

     [
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "PUT",
            "POST",
            "HEAD",
            "DELETE"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    }
]

  • You may replace "AllowOrigins": ["*"] with the domain names of the sites your app will be running on or leave it open.

  • Make sure you save the configuration and the bucket settings.

S3 Bucket Encryption (optional)

Form.io also supports S3 Encryption to provide further safety with the files that are stored within the S3 system. If you wish to enable this feature, you can do so by click on the Properties tab, then click on Default Encryption and then provide the encryption you would like to use.

Your S3 bucket should now be properly configured.

Enter S3 Project Settings

  • On form.io go to your Project Settings page and Click on Integrations ❘ File Storage ❘ S3 Storage

  • Enter the information for the IAM user and S3 bucket you just created. Make sure to provide all the necessary configurations that match the setup that you configured. For example, like this.

  • The following credentials can be provided.

    Setting

    Description

    Example

    Use MinIO Server

    Check this if you would like to use these settings to Connect to a Minio Server

    Access Key ID

    This is the IAM user Access Key ID that you copied when setting up the S3 user.

    ALIAQIQUCRXQ7Q2I8UYQ

    Secret Access Key

    This is the IAM user Secret Access Key that you copied when setting up the S3 user.

    IykVuiJPYidDhTWyFSfyIOVXuX7tIwIpCC3Sqql/

    Bucket Name

    The name of the bucket you created.

    formio-upload

    Bucket URL

    If you are using your own S3 compatible server, then provide the url here.

    https://formio-upload.s3.amazonaws.com/

    Bucket Region

    The region which you setup your Bucket within

    us-west-2

    Starts With

    This is the top-most folder you wish to place all the files from this project within.

    files/

    Access Control List

    Determines the Access Control of the files within this bucket.

    private

    S3 Encryption

    The type of encryption you are using for this S3 bucket.

    AES-256

    KMS Key ID

    Only valid if you are using KMS encryption where you then need to provide your KMS Key ID

    Max Size

    The maximum file size for uploads going into this bucket.

    100MB

    Policy Expiration

    The amount of seconds that the Upload policy is valid for

    3600

  • Now make sure to Save the project settings.

  • Now for every File component that you add to a form, you will need to select the S3 Storage dropdown as follows.

Multipart Upload

AWS S3 offers a Multipart Upload feature that allows users to upload files up to 5TB in size. It can also provide enhanced flexibility when it comes to uploading smaller files. Form.io's File Component supports this feature by letting the form builder opt in to Multipart Upload support on a per form basis.

The Multipart Upload feature is not yet compatible with Minio S3.

To use the File Component with Multipart Upload support:

  • Ensure that your AWS S3 bucket CORS policy exposes the "ETag" header.

  • In the File Component settings, select the checkbox labeled "Use the S3 Multipart Upload API."

  • Enter a "part size" in megabytes. The Multipart Upload feature works by "chunking" the file(s) into parts as close to this size as possible. Although this field is required, you can enter your best estimate based on what kinds of files you believe your form users will be uploading. If the file happens to be smaller than the chunk size, Form.io will use a "best-guess" part size to upload the file, so don't worry about being too precise.

MinIO

The Form.io platform supports On-Premise or Private Cloud file hosting through the use of MinIO Server. These instructions step through how to setup and configure a MinIO deployment and integrate it into to the Form.io platform.

MinIO Setup

To deploy a new MinIO server, complete the following pre-requisite steps:

  1. Install Docker either on the local machine, or on a private cloud server.

  2. Install MinIO on the same system:

    • If the Form.io Platform was deployed using the docker-compose method, MinIO is already installed.

    • In other cases, first create the necessary directories:

    mkdir ~/minio/data
mkdir ~/minio/config

    Then run the following command to pull the MinIO container from Docker Hub: 

    docker pull minio/minio

When the pre-requisite configuration has been complete, proceed with the following steps:

  1. Run the following command to spin up a new Minio instance:

docker run -itd \
  -e "MINIO_ROOT_USER=CHANGEME" \
  -e "MINIO_ROOT_PASSWORD=CHANGEME" \
  -e "MINIO_HOST: 127.0.0.1" \
  -e "S3_ENDPOINT: $MINIO_HOST:9000/minio/formio" \
  --name formio-minio \
  --restart unless-stopped \
  -p 9000:9000 \
  -p 9001:9001 \
  -v ~/minio/data:/data \
  -v ~/minio/config:/root/.minio \
  minio/minio server /data --console-address ":9001"

Note that the sample credentials "CHANGEME" should be updated to reflect the credentials intended for access to the file storage.

In this example, note that MinIO is mounting the folder ~/minio. This can be changed to any drive on the system machine where MinIO should store files.

  1. Verify the formio-minio container is running by executing the following command:

docker ps

The result should look similar to the following:

  1. Modify the hosts file to allow easy access to MinIO:

    • On MacOS/Linux: From the terminal run the following command, logging in if prompted:

sudo nano /etc/hosts

  • On Windows: Use Notepad as an Administrator to open the file C:\Windows\System32\Drivers\etc\hosts Once the file is open, modify the appropriate line to read:

127.0.0.1       localhost minioSave the file and exit the text editor.

  1. In a browser, navigate to http://minio:9001/ ( or http://localhost:9001) to view the MinIO interface. Log in using the MINIO_ROOT_USER and MINIO_ROOT_PASSWORD previously used to start the container.

  2. After successfully loading the MinIO dashboard, navigate to Buckets under the Administrator tools on the left-hand menu.

  1. Create a new Bucket by clicking on the Create Bucket+ button. Give the bucket a descriptive name and record the choice for future configurations.

Using NGROK for local testing (Optional)

To test this capability locally, the tool NGROK can be used to create a web accessible proxy to the local host. Create an NGROK account and install the application, then run the following command to create a secure web tunnel to the localhost:

ngrok http 9000

With this running, go to the HTTPS URL provided by the NGROK output in a browser to access the MinIO server portal. Keep this URL for the next steps.

Form.io Configuration

Once MinIO Server is running, configure the Form.io Platform settings to point to the running MinIO endpoint in the Form.io Project settings. Complete the following steps:

  1. Open the project in the Form.io platform.

  2. Open the Settings menu from the left-hand pane.

  3. From the Settings menu, navigate to Integrations > File Storage.

  4. On the Amazon S3 / MinIO tab, check the Use MinIO Server box.

  5. Configure the MinIO settings as follows:

    • MinIO Server URL- http://minio:9000 Form.io may display an error requesting a complete URL. It can be disregarded; the settings can be saved despite the warning.

    • Access Key ID- Enter the value specified forMINIO_ROOT_USER.

    • Secret Access Key- Enter the value specific for MINIO_ROOT_PASSWORD.

    • Bucket Name- Enter the name of the bucket created in the MinIO dashboard.

  1. Press Save to save your settings.

Create a Form that uses MinIO

To verify file storage has been correctly integrated, create a new API Web Form that has a File component.

After dropping the File component on the Form, open the configuration options. Open the File tab and verify that Storage is set to S3.

Use the Form to upload a file. Verify that there are no errors on the Form, and that the file is placed in the MinIO bucket as expected.

Google Drive

Google Drive allows for external applications to create and update files within the Google platform. Before File Storage can be configured for Google Drive, you must first establish a connection between the Google Developer Cloud and Form.io. Follow the File Storage steps below once the Google Drive configuration is complete.

Click Here for documentation on how to integrate Google Developer Cloud with Form.io.

  1. Within the Form.io Project, navigate to the Google Drive file storage settings Settings > Integrations > File Storage > Google Drive

  2. Click the Enable Google Drive button to configure the storage integration

  1. Add a File Component to your form

    • Click the File tab

    • Select the Google Drive from the Storage dropdown

File Folder

If you want to route your file uploads to a specific folder in your Drive, simply add the Folder ID found within the URL to the Folder ID setting within the File component.

  1. Navigate to your Google Drive folder

  2. Copy the Folder ID within the URL

  1. Add the ID to the Folder ID field within the File Component settings.

PreviousEmail IntegrationsNextGoogle Developer Console

Last updated

Was this helpful?