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 and client API programs to upload one or more files, attaching them to File fields.

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.

Uploading files

The following diagram shows the interactions required to upload and attach a file.

Steps 1 through 5 are as follows:

  1. Start the task
  2. Create a File Object in TeamworkIQ
  3. Get an Upload Info object that contains a short-lived Upload URL (optional)
  4. Upload the file content using the Upload URL
  5. Commit the file upload
  6. Submit the task form data
  7. Publish the draft form data to share it with others

Step 1. Start the task

A client program can only use the file upload API with an IN_PROGRESS task. If the task is not IN_PROGRESS, the file upload operations will fail. Forgetting this requirement is a common mistake for developers of client programs.

An API program should always start a task before doing the work involved in performing the task. If performing the task requires the client program to upload files, then the task must already be in progress when the client attempts to upload files.

Step 2. Create a File Object in TeamworkIQ

To attach a file to a File field in a task, the client must first create a File Object within TeamworkIQ. The File Object acts as a reference to the file. The file will be attached to that object, which will contain the name, size, MIME type and a reference to the file object in S3.

The following cURL command creates a File Object that will be attached to {task_no}:

curl -X POST \
-H "x-api-key-id: {api_key}" \
-H "Content-Type: application/json" \
-d '{ "purpose": "DATA", "task_no": {task_no} }' \
"https://api.teamworkiq.com/api/v3/files/{acc}/{pro}"

where:

  • {api_key} is an API Key
  • {acc} is an account number
  • {pro} is the number of a process workflow
  • {task_no} is the task number.

If the operation succeeds, the response from TeamworkIQ will contain the following information:

{ 
"file_no": "{file_no}",
"upload_url": "{new_s3_upload_url}"
}

where file_no specifies the ID of the newly created File Object and upload_url is a short-lived S3 URL that can be used to upload file content.

The client must store the {file_no} value, because the client will need this value to access the file and to attach the file to a File field in the task.

The client MAY immediately PUT file content to S3 using {new_s3_upload_url} .

A client program can only create a File Object with an IN_PROGRESS task. If the task is not IN_PROGRESS, the file upload operations will fail.

If there is a failure, check the detailed error code in the response body and search for the associated help page.

Step 3. Get Upload Info (optional)

The {new_s3_upload_url} URL is a signed S3 URL. It expires 15 minutes after it is created. If a client program needs to PUT file content after the upload URL expires, the client must request a new upload URL from TeamworkIQ.

The client can request a new Upload Info object by sending the following request:

curl -X GET \
-H "x-api-key-id: {api_key}" \
"https://api.teamworkiq.com/api/v3/files/{acc}/{pro}/{file}/upload"

where:

  • {api_key} is an API Key
  • {acc} is an account number
  • {pro} is the number of a process workflow
  • {file} is the file number.

This GET request returns Upload Info for the File Object. Specifically, it returns an Upload URL. The Upload Info object returned in the response will look like this:

{
"upload_url": "{new_s3_upload_url}"
}

The {new_s3_upload_url} is a new short-lived S3 URL that can be used to upload file content.

A client program can only get Upload Info for an IN_PROGRESS task. If the task is not IN_PROGRESS, this operation will fail.

Step 4. Upload the file content

The client program must now upload the file to S3 by PUTting it to {new_s3_upload_url}. For example:

curl -X PUT \
-H "Content-Type: {mime_type}" \
-F {file_path} \
"{new_s3_upload_url}"

where:

  • {mime_type} is the MIME type for the file
  • {file_path} is the file's path on your computer's file system
  • {new_s3_upload_url} is the S3 signed PUT URL.

When the client program receives the HTTP response, the client program must store the contents of the HTTP response header named x-amz-version-id . This information will be required to commit the upload in step 4.

The upload is not yet downloadable

At this point, the uploaded file is not yet visible to anybody. Even the client that uploaded it cannot download it. To make the uploaded file downloadable and reference-able, the upload must be committed (step 4).

Replacing an existing upload

If the client needs to replace the File Object's existing upload, then the client may do so by sending another PUT request to the S3 upload URL.Uploading more files does NOT attach more files to the File Object; the File Object will only allow downloads of the most recently uploaded file.

Step 5. Commit the upload

To make the uploaded file downloadable and reference-able, the upload must be committed. To commit the upload, the client sends the following request.

curl -X PUT \
-H "x-api-key-id: {api_key}" \
-H "Content-Type: application/json" \
-d '{ "version": "{x-amz-version-id}" }' \
"https://api.teamworkiq.com/api/v3/files/{acc}/{pro}/{file}/commit"

where:

  • {x-amz-version-id} is the x-amz-version-id header from the S3 file upload response.
  • {acc} is the account number
  • {pro} is the process workflow number
  • {file} is the file number

Once the upload is successfully committed, the assignees of the task (and client programs) will be permitted to obtain download URLs for the File Object.

This operation requires that the task is IN_PROGRESS. If the task is not IN_PROGRESS, a client cannot commit an upload; this operation will fail.

Step 6. Submit the task form

Committing the upload is helpful, but until the value of the File field is updated in the task form, users and client programs have no way to discover the file. The client must now update the file field, specifying a reference to the files that are to be attached to it.

A File field may be configured to permit only one attached file, or it may be configured to permit many attached files. The value of a File field is an array of JSON objects like this:

[
{
"url": "{download_url}",
"file_size": {file_size},
"file_type": "{mime_type}",
"label": "{file_name}"
}
]

The url property must contain a Download Info URI for the File Object:

/api/v3/files/{account_no}/{process_no}/{file_no}/download

The file_size property must contain a file size value. The file_type property must contain the MIME Type of the file. The label property must contain a file name.

This operation requires that the task is IN_PROGRESS. If the task is not IN_PROGRESS, attempts to submit new form data will, of course, fail.

Step 7. Publish the draft form data to share it with others

When a form is first submitted, the field values comprise a draft submission. Only assignees of the task (and API client programs) can see the field values. Other workflow participants cannot see the newly submitted form data until the the client publishes the draft. You can learn more about the life cycle of form submissions here.

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 upload files to the bucket, your client application must send a PUT request to a Signed URI.

The Signed URI expires after 15 minutes. This ensures that if the owners of a process remove a participant's access to the process, the Signed URIs will quickly expire. To get a new Signed URI from TeamworkIQ, the client must have permission to upload files to that task.

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 upload URIs to the following actors, and only if the task is IN_PROGRESS:

  • To the assignees of the task.
  • To an authorized TeamworkIQ API client program for your account

Steps 1-6 all require that the task be IN_PROGRESS. At every step, if the task is not IN_PROGRESS, the step will fail. This means, for example, that after a task completes or is skipped or disabled, it is impossible to upload more files and make them downloadable. Even possession of an unexpired S3 PUT URI is not sufficient, because an uploaded file is invisible to all actors until it is committed; but it can only be committed, and added to the form field value, if the task is currently IN_PROGRESS.

It makes sense that file uploads can only be completed while a task is IN_PROGRESS. Uploading files to form fields is part of the work that is required to complete the task. A task is in progress while the work of completing the task is ongoing; and after the task is marked as completed, no more such work (including the uploading of files) can occur without reopening the task.

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 require modern, secure versions of Transport Layer Security (TLS).

File limits and file storage policy

See TeamworkIQ File Storage Policy.


Did this answer your question?