System Methods
Learn about miscellaneous system methods that are part of the DNAnexus Platform API.
Last updated
Was this helpful?
Learn about miscellaneous system methods that are part of the DNAnexus Platform API.
Last updated
Was this helpful?
/system/bulkRankUpdateGiven 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.
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 will not be performed.
updatedCount integer The amount of execution trees that were updated.
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 following execution IDs were not root executions: [...]
ResourceNotFound
The following execution IDs were not found: [...]
PermissionDenied
billTo does not have license feature executionRankEnabled
The following execution IDs were not allowed to have their rank updated: [...]
/system/describeDataObjectsDescribes data objects in bulk (providing functionality equivalent to the describe routes, but for multiple data objects at a time). The describe options (the mapping that would be supplied as input to file-xxxx/describe, etc.) 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 (e.g. "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.
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 an data object ID (e.g. "file-xxxx") to be described
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 values are mappings containing the describe options that will be supplied, or the boolean value true, indicating that empty describe options are to be supplied.
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
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 manner
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
/system/describeExecutionsDescribes 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 (i.e. "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.
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 (e.g. "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
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 will be supplied, or the boolean value true, indicating that empty describe options are to be supplied.
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 [[Protocols|Protocols#Errors]] documentation 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 manner.
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 (i.e. "job" or "analysis")
classDescribeOptions contains values that are neither hashes nor the value `true``
/system/describeProjectsDescribes 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) will be returned in the SAME order in which the projects were specified in the input.
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 will 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 will be used as the describe options for each project in projects specified as a string or specified as a mapping without the describe field.
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
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
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
/system/findDrivesSpecification
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. Currently 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 will contain only drives whose cloud matches the given string.
disabled - boolean (optional): If true, the result set will contain only drives which have been disabled. If false, the results will contain drives which have not been disabled. If not specified, both disabled and live drives will be returned.
describe - mapping (optional): If specified, the results will 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 frame. If not specified, there will be 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
/system/findGlobalWorkflowsThis route provides functionality to search for workflows; the ordering of results is arbitrary. Only workflows for which the requesting user has access to will be returned (for example, the user is on the authorized users list for the workflow).
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:
flags string (optional; can only be present if regexp is present) Currently 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) A category is defined by the grammar below:
category ::= < string >
category ::= {"$and": categoryArray}
category ::= {"$or": categoryArray}
categoryArray ::= [category, ...]
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 will contain only workflows whose billTo matches the string. If an array, then the result set will contain 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 frame. If not specified, there will be 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 will be 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 frame. If not specified, there will be no constraint on workflow creation time. If a created hash does not contain at least one of the following keys, an error will be 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
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)
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.
/system/generateBatchInputsGenerate inputs for a batch execution given a project-id, folder, and a mapping of input names and regular expressions.
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
batchInputs array of mappings array of results for each batchPattern
inputs mapping each inputName found for the batchPattern.
inputName
name string filename
ids array array of file-ids
error boolean (optional) true if multiple files are found for a single regexp
or not all inputs are satisifed for a batchPattern
batchPattern string Pattern of first group matched by the regular expression
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
/system/resolveDataObjectsResolves 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.
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 will be 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.
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
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 all of the project IDs specified in the objects mappings.
/system/whoamiReturns the user ID based on the authentication token.
fields mapping (optional) specifies the optional fields to include in the output of this method.
key string "clientIp"
value boolean the value true.
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.
InvalidAuthentication
The request is not from a legal, validated user
The keys may be the names of any data object class (e.g. "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 reference.
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
try non-negative integer (optional) The specific job try to fetch. Applies to jobs only. Defaults to the largest available try. See section for context.
If the project was not successfully described. See for more information
regexp string (mutually exclusive with glob; required if glob is not present) A regular expression that the name of all results must match
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 on each of the returned results; a value of true is equivalent to the empty hash input.
See
See for additional system methods related to finding objects based on certain criteria.