Modify a task

📘
Navigation

Set output destinations via the visual interface

Use output destinations in API calls:

Create a new draft task

Get details of a task

Modify a task

Run a task

Rerun a task

Change the details of the specified task, including its name, description, and inputs. The task is referred to by its ID, which you can obtain by making the call to list all tasks you can access.

Note that you can only modify tasks with a task status of DRAFT. Tasks which are RUNNING, QUEUED, ABORTED, COMPLETED or FAILED cannot be modified in order to enable the reproducibility of analyses which have been queued for execution or has initiated executing.

https://cavatica-api.sbgenomics.com/v2/tasks/{task_id}

The task details include its creator, its start and end time, the number of jobs completed in it, and its input and output files. You can also see the status of the task.

Header fields

Name	Description
`X-SBG-Auth-Token` required	Your CAVATICA authentication token.

Path parameters

Name	Data type	Description
`task_id` required	string	The ID of the task you are querying.

Query parameters

Name	Data type	Description
`fields`	string	Selector specifying a subset of fields to include in the response.

Request

Request body

The request body should be a JSON object specifying the app that you want to run, and assigning input files to its input nodes. It is entered as a list of key-value pairs. The keys specify the name and description of the task to be created, the app to executed, and details of its inputs files. The keys, and their permitted values, are described below.

You can see a list of the app's input nodes on CAVATICA on the apps page for the project. Specify the files to input to the nodes using the files' IDs, which you can obtain using the call to get files.

Key	Data type	Description
`name`	string	The name of the task.
`description`	string	An optional description of the task.
`project`	string	The short name of the project that you want to create the task in.
`execution_settings`	dictionary	Detailed task execution parameters. Includes the instance type setting (`instance_type`) and/or the maximum number of parallel instances (setting `max_parallel_instances`). • `instance_type`: Possible value is the specific instance type, e.g. `"instance_type": "c4.2xlarge;ebs-gp2;2000"`. • `max_parallel_instances`: Maximum number of instances running at the same time. Takes any integer value equal to or greater than 1, e.g. `"max_parallel_instances": 2`. • `use_memoization`: Set to `false` by default. Set to `true` to enable memoization.
`app`	string	The specification of the app that you want to run. Recall that apps are specified by their projects, in the form `{project_owner}/{project}/{app_name}`.
`inputs`	dictionary	See the section on specifying task inputs for information on creating task input objects.
`output_location`	dictionary	Detailed parameters related to the output location where task outputs will be stored.
`batch`	boolean	This is set to `false` by default. Set to `true` to create a batch task and specify the `batch_input` and `batch_by` criteria as described below.
`batch_input`	string	The ID of the input on which you wish to batch. You would typically batch on the input consisting of a list of files. If this parameter is omitted, the default batching criteria defined for the app will be used.
`batch_by`	dictionary	This specifies the criteria on which to batch. It can be in one of two formats. If you wish to batch per item in the app's input (i.e., typically per file in a list of files) then specify a dictionary with the following format: `{ "type": "ITEM" }`. If you wish to batch by groups of inputs, you should specify the criteria satisfied by each group. This should be a common metadata value in one, or more, metadata fields. To do this, specify a dictionary with the following format: `{ "type": "CRITERIA", "criteria": [ "metadata.<field_1>", "metadata.<field_2>" ] }`. This will group inputs by shared metadata values for `<field_1>` and `<field_2>`, in that order. Arbitrarily many metadata fields may be listed, and the order in which fields are grouped will respect the order of the list.
`use_interrutible_instances`	boolean	This field can be true or false. Set this field to true to allow the use of spot instances.

Output location

The output_location dictionary allows you to define the exact location where your task outputs will be stored. The location can either be defined for the entire project using the main_location parameter, or individually per each output node, by setting the nodes_override parameter to true and defining individual output node locations within nodes_location. See the table below for more details.

Key	Data type	Description
`main_location`	string	Defines the output location for all output nodes in the task. Can be a path within the project in which the task is created, for example `'/Analysis/<task_id>_<task_name>/'` or a path on an attached volume, such as `"volumes://volume_name/<project_id>/html"`. Parts of the path enclosed in angle brackets `<>` are tokens that are dynamically replaced with corresponding values during task execution. See the list of available tokens.
`main_location_alias`	string	The location (path) in the project that will point to the actual location where the outputs are stored. Used if `main_location` is defined as a volume path (starting with `volumes://`), to provide an easy way of accessing output data directly from project files.
`nodes_override`	boolean	Enables defining of output locations for output nodes individually through `nodes_location` (see below). Set to `true` to be able to define individual locations per output node. Default: `false`. Even if `nodes_override` is set to `true`, it is not necessary to define output locations for each of the output nodes individually. Data from those output nodes that don't have their locations explicitly defined through `nodes_location` is either placed in `main_location` (if defined) or at the project files root if a main output location is not defined for the task.
`nodes_location`	dictionary	Contains output paths for individual task output nodes in the following format for each output node: `"{output-node-id}": { "output_location": "{output-path}", "output_location_alias": "{alias-path}" } For example: "b64html": { "output_location": "volumes://outputs/tasks/mar-19", "output_location_alias": "/rfranklin/tasks/picard" }` In the example above, `b64html` is the ID of the output node for which you want to define the output location, while the parameters are defined as follows: • `output_location`: Can be a path within the project in which the task is created, for example `'/Analysis/<task_id>_<task_name>/'` or a path on an attached volume, such as `"volumes://volume_name/<project_id>/html"`. Also accepts tokens. • `output_location_alias`: The location (path) in the project that will point to the exact location where the output is stored. Used if `output_location` is defined as a volume path (starting with `volumes://`).

Example request body

{
    "description": "my draft task",
    "name": "RFranklin, Experiment IV",
    "use_interruptible_instances": false,
    "execution_settings": {
        "instance_type": "c4.2xlarge;ebs-gp2;2000",
        "max_parallel_instances": 1
    },
    "inputs": {
        "cuffdiff_zip": {
            "class": "File",
            "path": "567895e6e4b00a1d67a8b1aa",
            "name": "example_human_known_indels.vcf"
        }
    },
    "output_location": {
        "main_location": "volumes://rfranklin/task-outputs/mar_19",
        "main_location_alias": "/outputs/<app_name>/mar_19",
        "nodes_override": true,
        "nodes_location": {
            "archive": {
                "output_location": "volumes://rfranklin/task-outputs/mar_19",
                "output_location_alias": "/outputs/<app_name>/mar_19/vcf"
            },
            "html": {
                "output_location": "/outputs/<app_name>/mar_19/html_reports"
            }
        }
    }
}

There are two further things to note if you are editing a batch task:

If you want to change the input on which to batch and the batch criteria, you need to specify the batch_input and batch_by parameters together in the same PATCH request.
If you want to disable batching on a task, set batch to false. Or, you can also set the parameters batch_input and batch_by to null.

{
    "batch":false
}

Response

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

Example response body

{
    "href": "https://cavatica-api.sbgenomics.com/v2/tasks/ea078c48-12c3-5460-a43b-4a1ab89e7f15",
    "id": "ea078c48-12c3-5460-a43b-4a1ab89e7f15",
    "name": "RFranklin, Experiment IV",
    "description": "my draft task",
    "status": "DRAFT",
    "project": "RFranklin/my-project",
    "use_interruptible_instances": false,
    "execution_settings": {
        "instance_type": "c4.2xlarge;ebs-gp2;2000",
        "max_parallel_instances": 1
    },
    "app": "RFranklin/my-project/new-test-app/0",
    "type": "v2",
    "created_by": "RFranklin",
    "start_time": "2016-01-12T19:20:10Z",
    "inputs": {
        "dispersion_threshold": null,
        "cuffdiff_zip": {
            "class": "File",
            "path": "567895e6e4b00a1d67a8b1cc",
            "name": "example_human_known_indels.vcf"
        },
        "density_threshold": null,
        "thresholds_off": null
    },
    "outputs": {
        "archive": null,
        "html": null
    },
    "output_location": {
        "main_location": "volumes://rfranklin/task-outputs/mar_19",
        "main_location_alias": "/outputs/<app_name>/mar_19",
        "nodes_override": true,
        "nodes_location": {
            "html": {
                "output_location": "/outputs/<app_name>/mar_19/html_reports"
            },
            "archive": {
                "output_location": "volumes://rfranklin/task-outputs/mar_19",
                "output_location_alias": "/outputs/<app_name>/mar_19/vcf"
            }
        }
    }
}