Start an import job

This call lets you queue a job to import a file or folder from a volume into a project on CAVATICA. Essentially, you are importing an item from your cloud storage provider (Amazon Web Services or Google Cloud Storage) via the volume onto CAVATICA.

If successful, an alias will be created on CAVATICA. Aliases appear on CAVATICA and can be copied, executed, and modified as such. They refer back to the respective file on the given volume.

Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.

https://cavatica-api.sbgenomics.com/v2/storage/imports

Request

Example request

POST /v2/storage/imports HTTP/1.1
Host: cavatica-api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/json
curl --data '@import.json' -X POST -H "X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0" -H "Content-Type: application/json" 'https://cgc-api.sbgenomics.com/v2/storage/imports'

Header Fields

Key

Description of value

X-SBG-Auth-Token
required

Your CAVATICA authentication token.

Content-type
required

application/json

Request body

In the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table.

Key

Data type of value

Description of value

source
required

Object

This object should describe the source from which the file should be imported.

volume_id
required

String

Volume ID from which to import the file.

location
required

String

Volume-specific location pointing to the file or folder to import. This location should be recognizable to the underlying cloud service as a valid key or path to the item. If the item being imported is a folder, its path should end with a /.

Please note that if this volume was configured with a prefix parameter when it was created, the prefix will be prepended to location before attempting to locate the file on the volume.

destination
required

Object

This object should describe the Platform destination for the imported file.

project
required

String

The project in which to create the alias.

parent

String

The ID of the target folder to which the item should be imported.

Should not be used together with project. If parent is used, the import will take place into the specified folder, within the project to which the folder belongs. If project is used, the items will be imported to the root of the project's files.

name

String

The name of the alias to create. This name should be unique to the project. If the name is already in use in the project, you should use the overwrite query parameter in this call to force any file with that name to be deleted before the alias is created.

If name is omitted, the alias name will default to the last segment of the complete location (including the prefix) on the volume. Segments are considered to be separated with forward slashes /.

Allowed characters in file names are all alphanumerics and special characters except forward slash /, while folder names can contain alphanumerics and special characters _, - and ..

overwrite

Boolean

Whether to overwrite the file if the file with the same name already exists in the destination.

autorename

Boolean

Whether to automatically rename the item (by prefixing it's name with an underscore and number) if another one with the same name already exists at the destination.

preserve_folder_structure

Boolean

Whether to keep the exact source folder structure. The default value is true if the item being imported is a folder. Should not be used if you are importing a file.

Example request body

{  
   "source":{  
      "volume":"rfranklin/input",
      "location":"example_human_Illumina.pe_1.fastq"
   },
   "destination":{  
      "project":"rfranklin/my_project",
      "name":"my_uploaded_example_human_Illumina.pe_1.fastq"
   },
   "overwrite": true
}
{
     “source”: {
       “volume”: “rfranklin/my_volume”,
       “location”: “samples/november/”
     },
     “destination”: {
         “parent”: “567890abc9b0307bc0414164”
     }
}

Response

See a list of CAVATICA-specific response codes that may be contained in the body of the response.

Response body

The response object contains information about the specified volume. The information is structured using the following key-value pairs:

Key

Data type of value

Description of value

id

String

ID of this import job

state

String

The state of this import job. Possible values are:

  • PENDING: the import is queued;
  • RUNNING: the import is running;
  • COMPLETED: the import has completed successfully;
  • FAILED: the import has failed.

overwrite

Boolean

autorename

Boolean

source

Object

Import source, as passed when this job was started by the call to start an import job .

destination

Object

Import destination, as passed when this job was started by the call to start an import job

result

Object

File object that was imported.

error

Object

In case of error in the import job, standard API error is returned here.

started_on

Boolean

Time when the import job started.

finished_on

Boolean

Time when the import job ended.

Example response body

{
   “href”: “https://cavatica-api.sbgenomics.com/v2/storage/imports/Yrand0mERJY4F3grand0mzh5UuTdw2Ap“,
   “id”: “Yrand0mERJY4F3grand0mzh5UuTdw2Ap”,
   “state”: “COMPLETED”,
   “overwrite”: false,
   “autorename”: false,
   “source”: {
       “volume”: “rfranklin/my_volume”,
       “location”: “my-samples/november/sample1.bam”
   },
   “destination”: {
       “project”: “rfranklin/my-project”,
       “name”: “sample1.bam”,
       “parent”: “567890abc9b0307bc0414164"
   },
   “result”: {
       “href”: “https://cavatica-api.sbgenomics.com/v2/files/567890abc8a5136ec6127063”,
       “id”: “567890abc8a5136ec6127063”,
       “name”: “sample1.bam”,
       “size”: 1804,
       “project”: “rfranklin/my-project”,
       “created_on”: “2018-10-22T12:25:53Z”,
       “modified_on”: “2018-10-22T12:25:53Z”,
       “storage”: {
           “type”: “VOLUME”,
           “volume”: “rfranklin/my_volume”,
           “location”: “my-samples/november/sample1.bam”
       },
       “origin”: {},
       “tags”: [],
       “metadata”: {}
   },
   “started_on”: “2018-10-22T12:25:53Z”,
   “finished_on”: “2018-10-22T12:25:54Z”
}
{
   “href”: “https://cavatica-api.sbgenomics.com/v2/storage/imports/5rand0mXYcDQ3xtSHrKuK2jXNDtJhMBN“,
   “id”: “5rand0mXYcDQ3xtSHrKuK2jXNDtJhMBN”,
   “state”: “COMPLETED”,
   “overwrite”: false,
   “autorename”: false,
   “preserve_folder_structure”: true,
   “source”: {
       “volume”: “rfranklin/my_volume”,
       “location”: “my-samples/november"
   },
   “destination”: {
       “project”: “rfranklin/my-project”,
       “name”: “samples”,
       “parent”: “567890abc9b0307bc0414164”
   },
   “result”: {
       “href”: “https://cavatica-api.sbgenomics.com/v2/files/567890abc4f3066bc3750174”,
       “id”: “567890abc4f3066bc3750174”,
       “name”: “samples",
       “project”: “rfranklin/my-project”,
       “created_on”: “2018-10-22T12:28:10Z”,
       “modified_on”: “2018-10-22T12:28:10Z”
   },
   “started_on”: “2018-10-22T12:28:10Z”,
   “finished_on”: “2018-10-22T12:28:10Z”
}
Language
Click Try It! to start a request and see the response here!