# Collect files and images
URL: https://docs.awellhealth.com/docs/design-care-flows/file-upload

> For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt).











Forms can collect documents and images using the **File upload** and **Image upload** question types.
A patient can photograph a wound, or upload a referral letter or an identity document.

Uploaded files never live in Awell. They go straight from the respondent's browser into a storage
bucket the organization owns, and Awell keeps a URL pointing at them. So there are two halves to this:
someone sets up the bucket once, and then anyone building a form can point questions at it.

## Storage has to be set up first [#storage-has-to-be-set-up-first]

These question types don't work until file storage is set up on the **Integrations** page of the
organization. Choose one of these:

1. **Connect the organization's own storage provider**, Google Cloud Storage or Amazon S3.
   This is preferred: the uploaded files stay under the organization's control.
2. **Let Awell store them.** Where there's no storage provider, email
   [support@awellhealth.com](mailto:support@awellhealth.com) to get this set up.

The rest of the setup is under [Set up file storage](#set-up-file-storage) below.

## One file per question [#one-file-per-question]

Both question types support **one file each**. For both sides of an identity document, use two
questions, one for the front and one for the back.

## Set the destination and file types per question [#set-the-destination-and-file-types-per-question]

<img alt="The Options tab of an upload question, with a question key, a file storage destination dropdown, and a comma-separated list of accepted file types" src="__img0" />

For each upload question, on the **Options** tab:

* Select the **file storage destination**, one of the configurations from **Integrations**. The
  **Manage your file storage** link next to it opens that page.
* Set the **accepted file types**, as a comma-separated list of
  [unique file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers)
  such as `image/*,image/jpeg,image/gif`.

Restrict file types to formats the care team can open.

Shelly can write the file type list for you. See
[Build forms with Shelly](/docs/design-care-flows/build-forms-with-shelly).

## Set up file storage [#set-up-file-storage]

An organization can have more than one file storage configuration, each pointing at a different
bucket. Set them up on the **Integrations** page. Both Google Cloud Storage and Amazon S3 are
supported.

A configuration name can't be changed after it's created, so pick one that will still make sense
later, such as `patient-upload-id-cards` rather than `bucket-2`.

### Google Cloud Storage [#google-cloud-storage]

#### Step 1: Create the bucket [#step-1-create-the-bucket]

Create the bucket in the [Google Cloud console](https://console.cloud.google.com/storage/browser).
Note the **bucket name**; it goes into Awell in step 4.

#### Step 2: Grant Awell write access to the bucket [#step-2-grant-awell-write-access-to-the-bucket]

In the bucket, click **Permissions**, then **Grant access**, and give the **Storage Object Creator**
and **Storage Object User** roles to Awell's service account. The account differs per environment:

| Environment   | Service account                                                  |
| ------------- | ---------------------------------------------------------------- |
| Sandbox       | `awell-file-storage@awell-sandbox.iam.gserviceaccount.com`       |
| Production EU | `awell-file-storage@awell-production.iam.gserviceaccount.com`    |
| Production UK | `awell-file-storage@awell-production-uk.iam.gserviceaccount.com` |
| Production US | `awell-file-storage@awell-production-us.iam.gserviceaccount.com` |

<img alt="The Google Cloud Grant access dialog, with an Awell file storage service account under New principals and the Storage Object Creator role assigned" src="__img1" />

These roles let Awell write objects into the bucket. They don't let Awell read them back.

#### Step 3: Allow CORS on the bucket [#step-3-allow-cors-on-the-bucket]

Files are uploaded straight from the browser, through Awell Care or Hosted Pages, so the bucket has
to allow Cross-Origin Resource Sharing, or CORS:

1. Install the [Google Cloud SDK CLI](https://cloud.google.com/sdk/docs/install).
2. Log in with `gcloud init`.
3. Create a `cors.json` file with the config below.
4. Apply it with `gsutil cors set cors.json gs://{ YOUR_BUCKET_NAME }`.
5. Confirm it with `gsutil cors get gs://{ YOUR_BUCKET_NAME }`.

```json
[
  {
    "origin": ["*"],
    "responseHeader": ["*"],
    "method": ["PUT"],
    "maxAgeSeconds": 3600
  }
]
```

#### Step 4: Finish the configuration in Awell [#step-4-finish-the-configuration-in-awell]

Back in Awell, give the configuration a name, enter the bucket name and a description, and save.

<img alt="The Create File Storage Configuration form in Awell, with a configuration name, Google Cloud Storage as the storage type, a bucket name, and a description" src="__img2" />

The configuration is now selectable as a file storage destination on any upload question.

### Amazon S3 [#amazon-s3]

#### Step 1: Create the bucket [#step-1-create-the-bucket-1]

Create the bucket in the [AWS console](https://aws.amazon.com/console/). Note the **bucket name** and
the **region**; both go into Awell in step 5.

#### Step 2: Allow CORS on the bucket [#step-2-allow-cors-on-the-bucket]

Files are uploaded straight from the browser, through Awell Care or Hosted Pages, so the bucket has
to allow CORS. Keep blocking all public access to the bucket.

1. Go to the **Permissions** tab of the bucket.
2. Find the **Cross-origin resource sharing** section, marked CORS, and edit the configuration.
3. Add the config below, listing the domains uploads will come from. `*` allows all of them.

```json
[
  {
    "AllowedHeaders": [
      "*"
    ],
    "AllowedMethods": [
      "PUT"
    ],
    "AllowedOrigins": [
      "https://care.us.awellhealth.com",
      "https://hosted-pages.yourdomain.com"
    ],
    "ExposeHeaders": [
      "ETag"
    ],
    "MaxAgeSeconds": 3000
  }
]
```

#### Step 3: Create an IAM user that can write to the bucket [#step-3-create-an-iam-user-that-can-write-to-the-bucket]

Create an IAM user, or reuse an existing one, and grant the user or their group a policy that writes
objects to the bucket. Replace `your-s3-bucket-name` with the real bucket name:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AwellDirectUploads",
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::your-s3-bucket-name/*"
        }
    ]
}
```

#### Step 4: Generate an access key for the IAM user [#step-4-generate-an-access-key-for-the-iam-user]

1. Go to the **Security credentials** tab for the IAM user.
2. Under **Access keys**, click **Create access key**.
3. Choose **Application running outside AWS** as the use case.
4. Describe the key, for example "Awell direct upload".
5. Click **Create access key**.
6. Copy the **Access key** and **Secret access key**, or keep the page open until step 5.

#### Step 5: Finish the configuration in Awell [#step-5-finish-the-configuration-in-awell]

Back in Awell, give the configuration a name, then enter the bucket name, the region, the access key,
the secret access key, and a description, and save.

<img alt="The Create File Storage form in Awell with Amazon S3 selected, showing fields for bucket name, region, access key ID, secret access key, and description" src="__img3" />

The configuration is now selectable as a file storage destination on any upload question.

## How uploaded files are named [#how-uploaded-files-are-named]

The original filename is prefixed with a UNIX timestamp when the file is written to the bucket.
Nothing else is added: the uploaded objects carry no other metadata.

That makes the bucket itself the only organizing tool available, so set up several configurations and
route different upload questions to different buckets. It's easier to keep one bucket of ID cards
tidy than one bucket of everything.

For richer metadata or a different file layout, email
[support@awellhealth.com](mailto:support@awellhealth.com).

## Getting at the uploaded files [#getting-at-the-uploaded-files]

Once a respondent uploads a file, the care team or another system usually needs to get at it.

**Reference by URL.** Awell stores the URL of the uploaded file, and that URL can be used inside the
care flow or passed to another system such as an EMR. If the bucket is public, anyone with the URL
can open the file. If the bucket or folder is private, the receiving system needs a signed URL.
Email [support@awellhealth.com](mailto:support@awellhealth.com) to work out that setup.

**Binary upload.** To send the file's contents to another system rather than a link to it, email
[support@awellhealth.com](mailto:support@awellhealth.com).

## Next steps [#next-steps]

**Next:** [Add a calculation](/docs/design-care-flows/add-a-calculation) to turn collected answers into
a score.

Before going live with uploads in Production, check the
[go-live checklist](/docs/design-care-flows/go-live-checklist). File storage is configured per
environment, so a Sandbox bucket does not carry across.