Summary

A TeamworkIQ task may optionally contain a form that lets assignees of the task submit information while performing the task. Such a form may optionally include File fields.

A File field allows the task assignee to upload one or more files, attaching them to the process data. A requester that has access to the task data may download the attached files. In particular, a client program that uses the TeamworkIQ API to access process data may download these files.

An attachment file is stored in an Amazon Web Services' S3 bucket. The file is not publicly accessible; it can only be accessed if a client uses a S3 Signed URI provided by TeamworkIQ.

Downloading files

The following diagram shows the interactions required to download an attached file.

Steps 1 through 3 are as follows:

  1. Get process data

  2. Get the download URL

  3. Get the file

1. Fetch the process (or task) data

The client must first fetch the process (or task) data by sending a HTTPS GET request to the following URI:

/api/v3/files/{account_no}/{process_no}/data

The response is a JSON object whose property names are the names of the process data fields and whose property values are the data values of those fields.

The data value of a File field is a JSON array of FileInfo objects, each of which represents one file that has been uploaded via the File field. Each FileInfo object has the following properties:

  • url is the URL for a Download Information object. This is a long-lived URI that looks like the following:
    /api/v3/files/{account_no}/{process_no}/{file_id}/download

  • file_type has a value that is the file's MIME type, e.g. image/png.

  • file_size has a value that is the file's size in bytes.

  • label has a value that is the file's name.

Step 2. Fetch the File Download URI for one of the uploaded files

The client must send an HTTPS GET request to an Information Download URI that was returned in Step 1.

The response body is a JSON object that contains a dynamically generated download URI for the file:

  • download_url has a value that is a short-lived AWS S3 "Signed URI". If used before it expires, this URI allows the client to download the file.

Step 3. Download the File

The client must send an HTTPS GET request to the S3 "Signed URI" that was provided in Step 2. The S3 endpoint will return the file content.

The S3 "Signed URI" will expire and become useless after 15 minutes. If the client still needs to download the file, the client must repeat Step 2 in order to obtain a new S3 "Signed URI".

The Security of your files

Signed URIs

Attachment files are stored in an Amazon Web Services' S3 bucket. This bucket is NOT publicly accessible; your files can only be accessed using S3 "Signed URIs". To download your files directly from the bucket, your client application must send a GET request to a Signed URI.

The Signed URI expires after 15 minutes. This is because a Signed URI grants access to the file without requiring additional authentication. The 15-minute expiration ensures that if the owners of a process remove a participant's access to the process, the Signed URIs will quickly expire, and the user will no longer be able to access the files.

Every "Signed URI" is digitally signed to prevent tampering with its parameters. Attempts to change the timeout, the target file, etc. will fail.

When is access granted?

TeamworkIQ only provides file download URIs to the following users:

  • To participants in the process who are not assignees of the task (but only only if the task's form data has been published)

  • To the assignees of the task, who may access the file even if the task's form data has not yet been published

  • To an authorized TeamworkIQ API client program for your account

A user who is not a participant in the process has NO access to the process's files.

Encryption

Each file is "encrypted at rest". This means that it is encrypted before it is written to disk. In the unlikely event that someone were to steal a disk drive from the Amazon Web Services data center, your files are encrypted using the Advanced Encryption Standard with 256 bit key (AES-256) and would be effectively unreadable.

Files are backed up to other buckets outside in a different geographic region. Backup files are likewise encrypted.

All interactions with TeamworkIQ and/or AWS S3 require HTTPS and requires modern, secure versions of Transport Layer Security (TLS).

File limits and file storage policy

See TeamworkIQ File Storage Policy.

Did this answer your question?