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 (required) Must be a list of root executions (either jobs or analyses).

• rank integer (required) The rank to set all executions to.

  • Must be between -1024 and 1023.

• 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 API methods, 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 a 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 (required) 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:

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

  • If a mapping, indicates that the data object is to be described with the specified options:

    • id string (required) ID of the data object to be described.

    • describe mapping or boolean (optional) A mapping containing describe options, or the boolean value true to supply empty describe options.

• classDescribeOptions mapping (optional) Specifies default describe options for each data object class (which may be overridden on a per-object basis).

  • key — the name of any data object class (for example, file), or * as a fallback for classes not otherwise named. See Data Object Classes for valid classes.

  • value mapping or boolean — the describe options to supply, or true to supply empty describe options.

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.

  • describe mapping The output hash from the describe API method.

    • Only present when the item was successfully described.

  • error mapping A mapping containing at least type and message fields, indicating the nature of the error. See Errors (Protocols).

    • Only present when the item was NOT successfully described.

  • statusCode integer The HTTP status code that would have been returned if the describe API method had been invoked in a standalone way.

    • Only present when the item was NOT successfully described.

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 API methods, 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 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 (required) 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:

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

  • If a mapping, indicates that the execution is to be described with the specified options:

    • id string (required) ID of the execution to be described.

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

    • describe mapping or boolean (optional) A mapping containing the describe options to use for the corresponding execution, or true to supply empty describe options.

• classDescribeOptions mapping (optional) Specifies default describe options for each execution class (which may be overridden on a per-object basis).

  • key — the name of any execution class (job or analysis), or * as a fallback for classes not otherwise named.

  • value mapping or boolean — the describe options to supply, or true to supply empty describe options.

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.

  • If the execution was successfully described:

    • describe mapping The output hash from the describe API method.

  • 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, indicating the nature of the error.

    • statusCode integer The HTTP status code that would have been returned if the describe API method 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 (required) 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:

  • If a string, indicates the ID of the project to be described. The describe options default to defaultDescribeOptions.

  • If a mapping, with the following fields:

    • id string (required) ID of the project to be described.

    • describe mapping or boolean (optional) Mapping containing the describe options to use for the corresponding project, or true to supply empty describe options. Defaults to "defaultDescribeOptions".

• defaultDescribeOptions mapping or boolean (optional) Mapping containing describe options, or true. Used as the describe options for each project in projects specified as a string or specified as a mapping without the describe field. Defaults to true.

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, in the same order.

  • 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 integer 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.

  • 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.

Outputs

• results array of mappings List of results.

  • id string ID of the result.

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

    • Only present when describe was set in the input.

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 API method 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 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) Whether to remove the restriction that only workflow versions tagged with "default" are returned. Defaults to false.

• 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) Controls whether extra metadata is retrieved with the results. Defaults to false.

  • If a mapping, represents the input for calling /globalworkflow-xxxx/describe on each of the returned results.

• 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 integer (optional) Maximum number of results that may be returned. Defaults to 1000. Must be between 1 and 1000.

Outputs

• results array of mappings List of results.

  • id string ID of the result.

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

    • Only present when the describe input was set.

• next string (nullable) Pagination cursor, or null if all results were reported in results. If a string, pass this value 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 (required) Project ID.

• folder string (required) Folder path in project to recursively query.

• inputs mapping (required) 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.

  • key — the name of the input.

  • value string — the 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 — the desired output field (for example, clientIp).

  • value boolean — the value true.

Outputs

• id string ID of the user.

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

  • Only present when the corresponding field in the fields input is set to true.

Errors

• InvalidAuthentication

  • The request is not from a legal, validated user

API method: /system/findDataCatalogs

Specification

Returns Omics Data Catalogs available to the user. Data catalogs are returned if the user belongs to an organization that owns the data catalog (billTo) or has been invited to access it. If the requesting user is not a member of any organization with access to a data catalog, the API method doesn't return any results.

Inputs

• region string (optional) Region to filter by.

• starting string (optional) Pagination token to retrieve subsequent results. The value from next in the response of a prior call.

• limit integer (optional) Specifies the maximum number of results to return.

• describe boolean or mapping (optional) Controls whether extra metadata is retrieved. Defaults to false. A value of true is equivalent to the empty mapping input, and the default list of fields is returned.

  • If a mapping, represents the input for calling the /dataCatalog-xxxx/describe API method on each of the returned results.

Outputs

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

  • id string Data catalog ID.

  • describe mapping Data catalog metadata properties. Only present when the describe input is specified.

    • url string Server URL for the data catalog endpoint used for Omics Data Catalog API method calls.

    • region string The region where the data catalog metadata is stored.

    • billTo string Organization ID that the data catalog belongs to.

    • name string Human-readable name of the data catalog, calculated by org name + region.

• next string (nullable) Pagination token for the next set of results, or null if no more results are available.

Errors

See Protocols for standard error handling.

Search-Related Methods

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