S3

Upload files and images directly into your own S3 buckets.

When collecting binary data from your flows, such as images or documents from file, image upload, or signature questions, we upload them directly into your infrastructure from the responder's browser. Answers will not be sent to an S3 integration.

The answer associated with the question will contain the Object URL of the uploaded asset, such as https://s3.amazonaws.com/{{YOUR_BUCKET_NAME}}/formsort/{{FILENAME}}.jpg

This way, you retain control over your responder's data: the S3 bucket can only provide write access to Formsort, so the data uploaded can be secure.

Setting up new S3 credentials

If you don't have an S3 bucket already, or wish to create a new one, see our guide on Setting up the S3 Bucket. Take note of the bucket name as well as the region (ie. us-east-2) of the bucket. Configure the "bucket owner preferred" setting so all new objects in the bucket will be owned by your organization.

In the integrations editor, under S3, click Add new credential...

Provide your bucket name, region, and a description of the bucket

In the S3 interface, add a bucket policy to allow the Formsort uploader user to write to the bucket:

{
    "Version": "2012-10-17",
    "Id": "FormsortPolicy",
    "Statement": [
        {
            "Sid": "FormsortPutObjectsPolicy",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::129119527019:user/s3-upload"
            },
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::{{YOUR_BUCKET_NAME}}/formsort/*"
        }
    ]
}

Since we'll be uploading from the user's browser, you need to set a CORS policy as well.

JSON schema:

[
  {
    "AllowedHeaders": [
        "*"
    ],
    "AllowedMethods": [
        "POST",
        "GET"
    ],
    "AllowedOrigins": [
        "*"
    ]
  }
]

XML schema (deprecated in AWS):

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <CORSRule>
    <AllowedOrigin>*</AllowedOrigin>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
  </CORSRule>
</CORSConfiguration>

How Object URLs are generated

All uploaded assets will reside within a formsort/ folder.

At the level of the flow's integration, a base path can be specified. This adds an additional prefix that is used to create Object URLs for all uploaded assets. One helpful trick is to create a base path like /prod for the production environment, to distinguish from assets uploaded to other environments.

At the level of a particular question, additional filename patterns can be specified:

Specifying a file destination

Take care that every URL has some uniqueness to it, whether it be the responder UUID, a timestamp, or random UUID, so that uploads from different responders do not overwrite one another.

In the above configuration, uploaded assets would be located at https://s3.amazonaws.com/your.aws.s3.bucket/formsort/{{randomUuid}}.png, which is what would be provided in the answers stored in the flow itself.

Setting up the S3 Bucket in AWS

To upload your data to Amazon S3, you must first create an Amazon S3 bucket in one of the AWS Regions. Since there are many variations on the configuration of S3 buckets, this guide is meant to cover the basic features needed to get a bucket up and running.

AWS' official guide to creating an S3 can be viewed here.

To get started, you'll want to sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

Choose Create Bucket

In the General Configuration menu, choose a DNS-compliant name for your bucket, and select the AWS region you want the bucket to reside.

You can see all of Amazon's rules for bucket name here.

Next, in the Object Ownership menu, choose to enable or disable Access Control Lists (ACLs). ACLs are used to provide ownership of every object in your bucket, which simplifies access management.

ACLs disabled

• Bucket owner enforced - Only the bucket owner owns and has full control over every object in the bucket. Access control for the bucket is based on polices (IAM/S3 bucket policies) rather than ACLs.

ACLs enabled

• Bucket owner preferred - Bucket and objects ACLs are accepted. Objects uploaded with bucket-owner-full-control ACLs will be owned by the bucket owner. Otherwise, the object-writer owns the object.

• Object Writer - Objects are owned by the AWS account that uploads them.

See a more detailed explanation of ACLs and ACL configuration here

Once you ACL settings have been set, configure your Public Access Settings. This feature provides settings for access points, buckets, and accounts to help manage public access to your S3 resources. By default, new buckets do not allow public access.

See a more in-depth explanation of Public Access setting here.

If keeping multiple variants of an object is important to you, can choose to enable or disable bucket versioning. This can help preserve, retrieve, and/or restore versions of objects. By default this feature is disabled.

For more information about bucket versioning, see the docs here.

Tags and Default Encryption are disabled by default, and configuration is not required to get the S3 set up. However, if you'd like to learn more about them, you can visit the tag docs here, and the docs for Default Encryption here.

Setting up the S3 Integration

Once you have an S3 bucket set up in AWS, you can configure it's integration into Formsort to receive images or documents from file, image upload, or signature questions. Answers will not be sent to an S3 integration.

You will find the S3 menu in the Integrations tab of the flow. Once in the S3 menu, click "add credential".

The S3 menu is located in the "Integrations" tab of the flow

Click on the "Add New" tab, and enter the S3 bucket information into the "Specify destination S3 bucket" field. Bucket should exactly match the way the bucket is named in AWS, but Region only needs to be written using the dash-separated name, e.g. "us-east-2". A Description is optional.

View of the bucket in the AWS S3 console

The Bucket name and Region match the information in the AWS console

The next step, Set up a bucket policy, will be pre-filled with the appropriate information by Formsort. No changes need to occur here. Copy this policy...

Copy this policy

...and paste into your AWS bucket, under Permissions -> Bucket Policy -> Edit. Be sure to click Save Changes at the bottom of the Edit Bucket Policy page.

Edit your Bucket Poilcy

Paste the auto-generated Formsort policy here

Once the Bucket Policy has been updated, head back to the S3 menu in Formsort and copy the CORS configuration code, found in Set up CORS configuration.

Formsort's CORS configuration code

Paste this CORS policy into the CORS section of your AWS console, by clicking Edit. Be sure to click Save Changes.

The CORS configuration section in AWS

Paste the code into AWS\

Once that is finished, head back to the Formsort S3 menu and click Save bucket info. Be sure the bucket is selected from the Pick a credential to use for this integration menu, and the bucket will be set to receive data.

Make sure the bucket is selected in the menu

Once the S3 bucket is selected, it will be automatically set at the question level to receive images or documents from file, image upload, or signature questions. Answers from any other question component will not be sent to your S3 integration.

If you have deployed flows previous to integrating with your S3 bucket, it is advisable to re-deploy those flows.