1. Overview
  2. Upload File
  3. Download File
  4. File Preview

1 Overview

Avaya Spaces users have the option to attach files to their messages. The files are uploaded to Google's Cloud Storage Platform, where they are securely stored.

The two primary API methods used to interface with Cloud Storage are GET files/getuploadurl and GET files/getdownloadurl.

For a list of common MIME types see here.

2 Upload Files

To upload a file, client applications must first make a call to GET /api/files/getuploadurl, specifying the MIME type of the file to be uploaded and the size of the file in bytes. The method returns an upload URL for the file and a fileKey associated with the file. The upload URL links to a storage bucket on https://storage.googleapis.com. The client must now make a PUT request to the upload URL, specifying the MIME type of the file under the header "Content-Type" and attaching the file as a binary object BLOB in the body. If the upload URL responds with a status 200, the file has been uploaded. To reiterate:

  1. The client makes a call to GET /api/files/getuploadurl, which returns the upload URL.
  2. The client makes a PUT request to the upload URL, with the binary file data in its body.

The process can also be followed to upload multiple files. To do so, simply add multiple entries in the "files" array that gets passed to GET /api/files/getuploadurl. The method will return with multiple upload URLS, each of which can accept a file upload as specified in step 2.

Note: The upload URL will only accept a file with the exact same number of bytes that was specified in /api/files/getuploadurl.

3 Download Files

To download a file, the client must send a request to GET /api/files/getdownloadurl specifying the fileKey of the file they wish to download within the "fileKeys" array. This method returns a download URL on Cloud Storage Platform where the file can be retreived.

4 File Preview

When files are uploaded to a space a file preview must be generated if the file type is supported. When possible, the client application should generate a thumbnail version of the file being uploaded. This generated thumbnail should be uploaded in the same manner as any other file and the file key should be included in the message/post/task payload as thumbnailFile.

When it is not possible to generate a thumbnail on the client side, the server will attempt to do so for supported files. Supported file types for conversion: .pdf, .doc, .docx, .ppt, .pptx, .xls, .xlsx

Once a file has been uploaded for which no thumbnail was generated by the client. The server will begin to generate a thumbnail, the status of which is included in the payload of the object the file belongs to.

For example, when creating a Post (idea) with an attached .pdf file. The server will attempt to generate a thumbnail, but until this process is complete no thumbnail will be included when requesting the Post (idea). Instead we can see the status of the thumbnail conversion in the properties:

  • pages: (string) Number of pages found in file. This is determined by the thumbnail conversion process
  • nextSchedule: (string) Timestamp when thumbnail conversion will be retried
  • convertStart: (string) Timestamp when thumbnail conversion started
  • convertStatus: (string) the status of the thumbnail conversion: 0 - not started, 1 - in progress, 2 - complete, 3 - failed, 4 - failed but retrying
  • convertFailed: (string) Error message for failed thumbnail conversion