System Methods
Learn about miscellaneous system methods that are part of the DNAnexus Platform API.
A license is required to use the Job Ranking feature. Contact DNAnexus Support.for more information.
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.
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: [...]
Describes 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 valuetrue
, 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 valuetrue
, 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 valuetrue
, 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 describeddescribe
mapping or boolean (optional) a mapping containing describe options; or the boolean valuetrue
, 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 (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 Data Object Classes reference. - 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 theobjects
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 routeerror
: mapping (only present if the item was NOT successfully described) a mapping, containing at leasttype
andmessage
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 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 valuetrue
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 valuetrue
, 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 valuetrue
, 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 valuetrue
, 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 describeddescribe
mapping or boolean (optional) a mapping containing the describe options to use for the corresponding execution ortrue
, 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 theexecutions
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 leasttype
andmessage
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 arrayexecutions
contains elements that are neither strings nor hashes of the form described aboveexecutions
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``
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) 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 describeddescribe
mapping or boolean (optional, defaultdefaultDescribeOptions
) Mapping containing the describe options to use for the corresponding project ortrue
, which is equivalent to specifying the empty hash as the describe options
defaultDescribeOptions
mapping or boolean (optional, defaulttrue
) mapping containing describe options ortrue
;defaultDescribeOptions
will be used as the describe options for each project inprojects
specified as a string or specified as a mapping without thedescribe
field.
results
array of mappings results of invoking/project-xxxx/describe
on each project inprojects
with its corresponding describe options. This is an array of the same length as theprojects
input, and it contains the results of/project-xxxx/describe
in the same order in which the projects were specified inprojects
. 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 thetype
andmessage
fields to indicate the nature of the error; may contain additional fieldsstatusCode
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
Generate inputs for a batch execution given a project-id, folder, and a mapping of input names and regular expressions.
project
string project IDfolder
string folder path inproject
to recursively queryinputs
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 providedinputName
string the name of the inputregexp
string regular expression to query for files
batchInputs
array of mappings array of results for eachbatchPattern
inputs
mapping each inputName found for the batchPattern.inputName
name
string filenameids
array array of file-ids
error
boolean (optional) true if multiple files are found for a single regexpor not all inputs are satisifed for a batchPatternbatchPattern
string Pattern of first group matched by the regular expression
- InvalidInput
project
is not a project ID.regexp
is not a valid regular expressionregexp
query returns greater than 100,000 results
- PermissionDenied
- At least VIEW access to the specified
project
is required
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.project
string (required unless everyobjects
entry containsproject
) The ID of the default project contextfolder
string (optional, default "/") Folder path inproject
that will be used as the default folder for objects that do not explicitly specify a folder pathobjects
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 resolvedfolder
string (required ifproject
is specified; otherwise optional, defaults to top levelfolder
input) folder path of the data object to be resolvedproject
string (optional, defaults to top levelproject
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 theobjects
input. Specifically, this means that this array has the same length asobjects
, andresults[i]
corresponds toobjects[i]
. Each entry inresults
contains zero or more mappings, each with the following fields:project
: The project ID in which the data object was resolvedid
: The data object ID
- InvalidInput
project
is not a project ID. This applies to both the top levelproject
and also to theproject
input in each element ofobjects
.objects
contains more than 1000 elementsfolder
if specified, must be a valid folder path- Within each element of
objects
,folder
must be specified ifproject
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 theobjects
mappings.
Returns 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
Last modified 11mo ago