Introduction

ROQ Platform provides a complete solution for file management including these features:

  • Single file upload

  • Bulk file upload

  • Private files

  • Public files

Under the hood ROQ Platform is using GCP Cloud Storage.

Basic concepts

Concept

Description

File visibility

A file can have public or private visibility.

File categories

Often it makes sense to group files into project-specific categories, like “USER_FILES” or “CONTRACT_FILES”

Content types

The list of all available types is available here:

📖 Media Types

File status

The status of a file which can be one of: UPLOAD_PENDING, READY, CANCELLED or ERROR

File associations

When a file is stored on ROQ Platform, then it always belongs to another entity. For instance PDF files can be uploaded and related to a contract:

How it works

If you are building on top of ROQ One then all this logic is implemented and working out of the box and nothing needs to be done! You can still read this documentation in case you want to customize it or you are just curious how things are working.

Get files by associated entity

This is the typical method for accessing files in ROQ Platform. First, you fetch the ID of an object from your database and then query the related documents. For instance, the query shown below requests all files that are associated with a specific user. You can use the files() query with these parameters:

entityName

Name of the entity (e.g “user”, “contract”). This is usually an object from your own database.

entityIdentifiers

ID of the related objects E.g. this can be a user ID or a set of user IDs.

query {
  files(filter: {
    entityName: {
      equalTo: "User"
    },
    entityIdentifiers: {
      equalTo:"c5fd2d87-6e74-4125-9389-f2f950d40676"
    }}) {
    data {
      id
      name
      contentType
    }
  }
}
GRAPHQL

In case you want to filter by several IDs then the syntax looks like this:

query {
  file(fileId: "b10baede-bbd6-4a96-b92b-a9114a174bd8") {
    id
    name
    url
  }
}
GRAPHQL

As a result you’ll receive a list of files with their ID and name that you can use to show in a list or to download them. You can also filter it down by the content type like this:

query {
  file(fileId: "b10baede-bbd6-4a96-b92b-a9114a174bd8") {
    id
    name
    url
  }
}
GRAPHQL

Download a file

To download a single file, you will need to use the file() query. For files marked as “public,” the returned URL is static. If the file is marked as “private,” then the URL is referred to as a signed URL which is created for only one purpose. A signed URL works only for a short amount of time and is not intended to be published. You can read more about signed URLs here: ➚Signed URLs

query {
  file(fileId: "b10baede-bbd6-4a96-b92b-a9114a174bd8") {
    id
    name
    url
  }
}
GRAPHQL

Upload a single file

The upload process requires several steps:

  1. Generate a signed URL

  2. Upload file via the signed URL

  3. Set status of the file

All uploaded files have a private visibility. You can make a file public using the makeFilePublic() mutation.

(1) Generate a signed URL

To create the signed URL you need to use the createFileUploadUrl() mutation with these parameters:

name

Name of the file when downloaded.

contentType

Content type, e.g. “image/png”. See full list here:

📖 Media Types

fileCategory

File category, e.g. USER_FILES. Please obey the file category needs to exist already. You can add file categories using the createFileCategory() mutation.

fileAssociationOptions

Defines to what entity the file will be associated.

mutation{
  createFileUploadUrl(createFileDto: {
    name: "filename",
    contentType: "image/png",
    fileCategory: "USER_FILES"
    fileAssociationOptions: [
      {
        entityName: "User",
        entityIdentifier: "4434e4b6-cc82-41a2-a0fd-99fe33d9ebbb"
      }
    ]
  }){
    id
    uploadUrl
  }
}
GRAPHQL

When this mutation was used then the information about file is already saved on ROQ Platform side with the status UPLOAD_PENDING.

(2) Upload file via the signed URL

As a result of the createFileUploadUrl() mutation you will receive the ID of the file and the signed URL (called uploadUrl) which will look something like below:

https://storage.googleapis.com/space-roq-snapshot/26dace71...
CODE

You can use the above signed URL to actually do a PUT request to upload the file using ➚Postman or any other client. Make sure to pass the ContentType and X-Goog-Content-Length-Range like this:

curl --location --request PUT 'https://storage.googleapis.com/space-roq-snapshot/26dace71...' \
--header 'X-Goog-Content-Length-Range: 0,5000000' \
--header 'Content-Type: image/png' \
--data-binary '@zOGx1dpMz/spec.png'
CODE

In Postman it looks like this:

You may need to use these additional HTTP headers:

  • X-Goog-Content-Length-Range - 0,20000000 - File Size Range, cant exceed more than 20MB

  • Content-Type - image/png - Type of file

(3) Set status of the file

When the file was successfully uploaded, then you need to set the status to READY otherwise you cannot download it.

mutation{
  updateFileStatus(
    fileId: "8f628084-7f6f-429b-9137-79620646a9be",
    status: READY
  ){
    id
    createdAt
    updatedAt
  }
}
GRAPHQL

In case the upload was interrupted then the status should be set to CANCELLED. If there was an error (e.g. wrong file type) then the status should be set to ERROR.

Rename a file

To rename a file or change any other parameter you can use the updateFile() mutation with these parameters:

fileId

ID of the related file

updateFileDto

An object containing properties of the file that need to be updated with name and customMetaData

mutation{
  updateFile(
    fileId: "b10baede-bbd6-4a96-b92b-a9114a174bd8",
    updateFileDto: {
      name: "Alphabet"
    }
    ) {
    id
    name
  }
}
GRAPHQL

Make a file public

To make a file public to anyone you can use this mutation:

mutation{
  makeFilePublic(fileId: "8f628084-7f6f-429b-9137-79620646a9be") {
    id
    name
  }
}
GRAPHQL

Make a file private

To make a file private you can use the makeFilePrivate() mutation.

Note that when you create a URL for download, this URL can still be shared with other users. The main difference from a public file is that the URL will work only for a short period.

mutation{
  makeFilePrivate(fileId: "8f628084-7f6f-429b-9137-79620646a9be") {
    id
    name
  }
}
GRAPHQL

Managing file categories and content types

Files are always categorized so that you can filter accordingly. To load all files that belong to a category you can use the files() query:

query {
  files(filter: {
    entityName: { equalTo: "User" },
    fileCategory: { equalTo: "USER_FILES"}
    entityIdentifiers: {
       equalTo:"c5fd2d87-6e74-4125-9389-f2f950d40676"
    }}) {
    data {
      id
      contentType
    }
  }
}
GRAPHQL

You can retrieve all categories using the fileCategory() and fileCategories() queries. To manage categories you need to login to the Console: ➚console.roq.tech/settings/file-management/file-categories