System Methods

Learn about miscellaneous system methods that are part of the DNAnexus Platform API.

System API Method Specifications

API method: /system/bulkRankUpdate

A license is required to use the Job Ranking feature. Contact DNAnexus Support for more information.

Specification

Given a list of root executions (either jobs or analyses) and a new rank, update the rank of all executions related to the provided root executions. The following restrictions apply:

• A valid rank field must be provided.

• At least one execution ID must be present.

• A maximum of 100 root executions can be provided at once.

• All execution IDs must be valid executions.

• All executions must belong to a singular billTo.

• The organization associated with the executions must have the license feature executionRankEnabled active.

• The user must be the original launcher of the executions or is an administrator of the organization.

• A maximum of 1000 executions total can be updated at once.

A dry-run flag can be provided to skip the final update call.

Inputs

• execIds array of strings Must be a list of root executions (either jobs or analyses).

• rank integer The rank to set all executions to.

• dryRun boolean (optional) If set to true, the final update call is not performed.

Outputs

• updatedCount integer The amount of execution trees that were updated.

Errors

• InvalidInput

  • input is not a hash

  • Expected input to have property "rank"

  • Expected key "rank" of input to be an integer

  • Expected key "rank" of input to be in range [-1024, 1023]

  • Expected input to be an array of nonempty strings

  • Expected key dryRun of input to be a boolean

  • At least one execution ID must be provided

  • The max number of root executions updated at once is 100

  • All input executions must have the same billTo

  • The execution IDs were not root executions

• ResourceNotFound

  • The execution IDs were not found

• PermissionDenied

  • billTo does not have license feature executionRankEnabled

  • The execution IDs were not allowed to have their rank updated

API method: /system/describeDataObjects

Specification

Describes data objects in bulk, providing functionality equivalent to the describe routes, but for multiple data objects at a time. The describe options, for example, the mapping that would be supplied as input to file-xxxx/describe, for each object are determined from the following sources, in decreasing order of priority:

• If the object is specified as a mapping that has the describe field set, rather than as just a bare string, this value is used as the describe options (or, if set to the value true, empty describe options are given).

• Otherwise, if the classDescribeOptions field contains an entry for the class of the data object such as "file", this value is used as the describe options (or, if set to the value true, empty describe options are given).

• Otherwise, if the classDescribeOptions field contains an entry for the key "*", this value is used as the describe options (or, if set to the value true, empty describe options are given).

• Otherwise, empty describe options are given.

Inputs

• objects array of strings or mappings array of items, each representing a data object to be described. The array may contain up to 1000 elements. Each item is one of the following:

  • a string indicating a data object ID to be described, such as "file-xxxx"

  • a mapping with the following fields, indicating that the data object is to be described with the specified options:

    • id string ID of the data object to be described

    • describe mapping or boolean (optional) a mapping containing describe options. Or the boolean value true, indicating that empty describe options are to be supplied.

• classDescribeOptions mapping of strings to mappings or booleans (optional) specifies default describe options for each data object class (which may be overridden on a per-object basis). If supplied, this mapping should contain the following keys/values:

  • The keys may be the names of any data object class, such as "file", indicating a default value to be supplied for all data objects of that class. Or the string "*", indicating a default value to be supplied for all data objects that are of classes not otherwise named. For a list of data object classes, see the Data Object Classes reference.

  • The values are mappings containing the describe options that are supplied, or the boolean value true, indicating that empty describe options are to be supplied.

Outputs

• results array of mappings the results. This is an array of the same length as the objects field of the input, containing the corresponding describe call results in the same order. For each item in the input, the corresponding item is a mapping with the following fields:

  • describe: mapping (only present if the item was successfully described) the output hash from the describe route

  • error: mapping (only present if the item was NOT successfully described) a mapping, containing at least type and message fields, that indicates the nature of the error. See Errors (Protocols)

  • statusCode: int (only present if the item was NOT successfully described) the HTTP status code that would have been returned if the describe route had been invoked in a standalone way

Errors

• InvalidInput

  • objects is not an array, contains elements that are neither strings nor hashes of the form described above, contains more than 1000 elements, or contains IDs that are not of a data object class.

  • classDescribeOptions contains values that are neither hashes nor the value true

API method: /system/describeExecutions

Specification

Describes executions in bulk (providing functionality equivalent to the describe routes, but for multiple executions at once). The describe options (the mapping that would be supplied as input to job-xxxx/describe and/or /analysis-xxxx/describe) for each execution are determined from the following sources, in decreasing order of priority:

• If the execution is specified as a mapping that has the describe field set, rather than as just a bare ID string, the describe field is used as the describe options (or, if set to the value true, empty describe options are given).

• Otherwise, if the classDescribeOptions field contains an entry for the class of the execution, either "job" or "analysis", this value is used as the describe options (or, if set to the value true, empty describe options are given).

• Otherwise, if the classDescribeOptions field contains an entry for the key "*", this value is used as the describe options (or, if set to the value true, empty describe options are given).

• Otherwise, the empty hash as the describe options is given which would then return the default describe fields of each execution.

Inputs

• executions array of strings or mappings array of items, each representing an execution to be described. The array may contain up to 1000 elements. Each item is one of the following:

  • a string indicating an execution ID, such as "job-xxxx", to be described

  • a mapping with the following fields, indicating that the execution is to be described with the specified options:

    • id string ID of the execution to be described

    • try non-negative integer (optional) The specific job try to fetch. Applies to jobs only. Defaults to the largest available try. See Restartable Jobs section for context.

    • describe mapping or boolean (optional) a mapping containing the describe options to use for the corresponding execution or true, which is equivalent to specifying the empty hash as the describe options

• classDescribeOptions mapping of strings to mappings or booleans (optional) specifies default describe options for each execution class (which may be overridden on a per-object basis). If supplied, this mapping should contain the following keys/values:

  • The keys may be the names of any execution class (either "job" or "analysis"), indicating a default value to be supplied for all executions of that class. Or the string "*", indicating a default value to be supplied for all executions that are of classes not otherwise named.

  • The values are mappings containing the describe options that are supplied, or the boolean value true, indicating that empty describe options are to be supplied.

Outputs

• results array of mappings an array of the same length as the executions field of the input, containing the corresponding describe call results in the same order. For each item in the input, the corresponding item is a mapping with the following fields:

  • If the execution was successfully described:

    • describe: mapping the output hash from the describe route

  • If the execution was not successfully described (see the protocol errors for more information):

    • error: mapping a mapping, containing at least type and message fields, that indicates the nature of the error.

    • statusCode: int the HTTP status code that would have been returned if the describe route had been invoked in a standalone way.

Errors

• InvalidInput

  • executions is not an array

  • executions contains elements that are neither strings nor hashes of the form described above

  • executions contains more than 1000 elements, or contains IDs that are not of an execution class ("job" or "analysis")

  • classDescribeOptions contains values that are neither hashes nor the value true

API method: /system/describeProjects

Specification

Describes all specified projects. This method provides similar functionality to that of the /project-xxxx/describe method but is used to describe multiple projects at once. Describe options (the mapping normally provided as input to /project-xxxx/describe to customize its output) may be specified for all projects and/or overridden on a per-project basis. The project descriptions and/or error descriptions (for cases in which projects cannot be successfully described) are returned in the SAME order in which the projects were specified in the input.

Inputs

• projects array of strings or mappings array of items representing the projects to be described. The array may contain up to 1000 elements. Each element may be one of the following:

  • a string indicating the ID of the project to be described. The describe options for the corresponding project default to defaultDescribeOptions

  • a mapping with the following fields:

    • id string ID of the project to be described

    • describe mapping or boolean (optional, default defaultDescribeOptions) Mapping containing the describe options to use for the corresponding project or true, which is equivalent to specifying the empty hash as the describe options

• defaultDescribeOptions mapping or boolean (optional, default true) mapping containing describe options or true. defaultDescribeOptions is used as the describe options for each project in projects specified as a string or specified as a mapping without the describe field.

Outputs

• results array of mappings results of invoking /project-xxxx/describe on each project in projects with its corresponding describe options. This is an array of the same length as the projects input, and it contains the results of /project-xxxx/describe in the same order in which the projects were specified in projects. Each result is a mapping with the following fields:

  • If the project was successfully described:

    • describe mapping the output of invoking /project-xxxx/describe

  • If the project was not successfully described. See Errors (Protocols) for more information

    • error mapping a mapping containing the type and message fields to indicate the nature of the error. May contain additional fields

    • statusCode int the HTTP status code that would have been returned had /project-xxxx/describe been individually invoked for the project

Errors

• InvalidInput

  • projects is not an array.

  • projects contains elements that are neither strings nor mappings.

  • projects contains more than 1000 elements.

  • projects contains project ids that do not match the project ID syntax/

API method: /system/findDrives

Specification

• Find drives accessible to a user.

Inputs

• name - string or mapping (optional): If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:

  • regexp string (mutually exclusive with glob, required if glob is not present) A PCRE regular expression that the name of all results must match

  • flags string (optional). Can only be present if regexp is present. This field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression

  • glob string (mutually exclusive with regexp, required if regexp is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character)

• cloud - string (optional): If provided, the result set contains only drives whose cloud matches the given string.

• disabled - boolean (optional): If true, the result set contains only drives which have been disabled. If false, the results contain drives which have not been disabled. If not specified, both disabled and live drives are returned.

• describe - mapping (optional): If specified, the results contain descriptive metadata about the found drives. The mapping is equivalent to the input used for calling /drive-xxxx/describe.

• created - mapping (optional): If at least one of the following keys is specified, the resulting drives must have been created in the indicated time period. If not specified, there is no constraint on drive creation time. The created hash should contain at least one of the following keys:

  • after timestamp (optional) If specified, only return results created at or after this time. The value should be a positive number and should be less than or equal to the before value if specified

  • before timestamp (optional) If specified, only return results created at or before this time. The value should be a positive number.

Outputs

• results - array of mappings: List of results, each with the following fields:

  • id - string ID: of the result If describe was set to a mapping

  • describe - mapping The output of the result's corresponding describe method

Errors

• Unauthorized

  • Must supply authentication token

• InvalidInput

  • The input is not a hash

  • name - (if provided) is not a string or does not conform to the expected input mapping

  • cloud - (if provided) is not a string

  • disabled - (if provided) is not a boolean

  • describe - (if provided) does not conform to the input format of /drive-xxxx/describe

  • created - (if provided) does not conform to the expected input mapping

  • modified - (if provided) does not conform to the expected input mapping

API method: /system/findGlobalWorkflows

Specification

This route provides functionality to search for workflows. The ordering of results is arbitrary. Only workflows for which the requesting user has access to are returned. This includes workflows where the user is on the authorized users list.

Inputs

• name string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:

  • regexp string (mutually exclusive with glob, required if glob is not present) A PCRE regular expression that the name of all results must match

  • flags string (optional, can only be present if regexp is present) This field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression

  • glob string (mutually exclusive with regexp, required if regexp is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).

• category string or mapping (optional) Specifies the category or categories that matching workflows must have. Can be provided in the following ways:

  • A simple string to match a single category exactly, for example, "Alignment".

  • An AND condition requiring all specified categories to match, for example, {"$and": ["Alignment", "NGS"]}.

  • An OR condition requiring at least one specified category to match, for example, {"$or": ["Alignment", "Variant Calling"]}.

  • Complex nested conditions: {"$or": ["Alignment", {"$and": ["NGS", "RNA-Seq"]}]}.

• allVersions boolean (optional, default false) Whether to remove the restriction that only workflow versions tagged with "default" are returned

• published boolean (optional) If true, only published workflows are returned. If false, only unpublished workflows are returned

• billTo string or array of strings (optional) If a string, then the result set contains only workflows whose billTo matches the string. If an array, then the result set contains only workflows whose billTo is one of the specified entities.

• createdBy string (optional) ID of the user who created the workflow

• developer string (optional) ID of a developer the workflow must have

• authorizedUser string (optional) userID, orgID or "PUBLIC" that must exist in each workflow's authorizedUsers list

• modified mapping (optional) If at least one of the following keys is specified, the resulting workflows must have been last modified in the indicated time period. If not specified, there is no constraint on when the workflow was last modified. If a modified hash does not contain at least one of the following keys, an error is thrown.

  • after timestamp (optional) If specified, only return results that were last modified at or after this time

  • before timestamp (optional) If specified, only return results that were last modified at or before this time

• created mapping (optional) If at least one of the following keys is specified, the resulting workflows must have been created in the indicated time period. If not specified, there is no constraint on workflow creation time. If a created hash does not contain at least one of the following keys, an error is thrown.

  • after timestamp (optional) If specified, only return results created at or after this time

  • before timestamp (optional) If specified, only return results created at or before this time

• describe boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling /globalworkflow-xxxx/describe on each of the returned results. A value of true is equivalent to the empty hash input.

• starting string (optional) Continue a previous query that had reached its limit. The value that was returned as next in the query's output should be provided here

• limit int (optional, default 1000) Maximum number of results that may be returned. Must be between 1 and 1000 (inclusive)

Outputs

• results array of mappings List of results, each with the following fields:

  • id string ID of the result

  • describe mapping The output of the result's corresponding describe method if the describe method was set as an input

• next string or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed directly to starting in a subsequent query if more results are desired.

Errors

See Errors (Protocols)

API method: /system/generateBatchInputs

Specification

Generate inputs for a batch execution given a project-id, folder, and a mapping of input names and regular expressions.

Inputs

• project string project ID

• folder string folder path in project to recursively query

• inputs mapping where each item is a mapping with the following format: inputName: regexp where inputName is name of an input for an applet and regexp is the query. At least one group must be provided

  • inputName string the name of the input

  • regexp string regular expression to query for files

Outputs

• batchInputs array of mappings array of results for each batchPattern

  • inputs mapping each inputName found for the batchPattern.

    • inputName

      • name string filename

      • ids array a list of file IDs

  • error boolean (optional) true if multiple files are found for a single regexp or not all inputs are satisfied for a batchPattern

  • batchPattern string Pattern of first group matched by the regular expression

Errors

• InvalidInput

  • project is not a project ID.

  • regexp is not a valid regular expression

  • regexp query returns greater than 100,000 results

• PermissionDenied

  • At least VIEW access to the specified project is required

API method: /system/resolveDataObjects

Specification

Resolves data objects in bulk. This method takes as input a list of object specifications, which may include the project id, folder path, and object name. Each object specification is processed in the following way: a search is performed for all data objects that exist in the specified project and folder and have the specified name. An array is returned containing all the matching results, where each element in the array is a mapping with keys project and id and values being the respective DNAnexus IDs for the project and object.

Inputs

• project string (required unless every objects entry contains project) The ID of the default project context

• folder string (optional, default "/") Folder path in project that is used as the default folder for objects that do not explicitly specify a folder path

• objects array of mappings array of object specifications, each representing a data object to be resolved. The array may contain up to 1000 elements. Each item is a mapping with the following fields:

  • name string the name of the data object to be resolved

  • folder string (required if project is specified. Otherwise optional, defaults to top level folder input) folder path of the data object to be resolved

  • project string (optional, defaults to top level project input) ID of the project in which to resolve this data object. If specified, folder must also be specified in this mapping.

Outputs

• results array of array of mappings the results. This is an array that is parallel to the objects input. Specifically, this means that this array has the same length as objects, and results[i] corresponds to objects[i]. Each entry in results contains zero or more mappings, each with the following fields:

  • project: The project ID in which the data object was resolved

  • id: The data object ID

Errors

• InvalidInput

  • project is not a project ID. This applies to both the top level project and also to the project input in each element of objects.

  • objects contains more than 1000 elements

  • folder if specified, must be a valid folder path

  • Within each element of objects, folder must be specified if project is specified

• PermissionDenied

  • At least VIEW access to the specified project is required, as well as at least VIEW access to the project IDs specified in the objects mappings.

API method: /system/whoami

Specification

Returns the user ID based on the authentication token.

Inputs

• fields mapping (optional) specifies the optional fields to include in the output of this method.

  • key string "clientIp"

  • value boolean the value true.

Outputs

• id string ID of the user. The following fields are only returned if the corresponding field in the fields input is set to true:

• "clientIp" string IP address as seen by the API server.

Errors

• InvalidAuthentication

  • The request is not from a legal, validated user

Search-Related Methods

See Search for additional system methods related to finding objects based on certain criteria.