# System Methods

## System API Method Specifications

### API method: `/system/bulkRankUpdate`

{% hint style="info" %}
A license is required to use the Job Ranking feature. [Contact DNAnexus Support](mailto:support@dnanexus.com) for more information.
{% endhint %}

#### 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](https://documentation.dnanexus.com/developer/api/introduction-to-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)](https://documentation.dnanexus.com/developer/api/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](https://documentation.dnanexus.com/user/running-apps-and-workflows/job-lifecycle#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](https://documentation.dnanexus.com/developer/protocols#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`](https://documentation.dnanexus.com/developer/data-containers/projects#api-method-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)](https://documentation.dnanexus.com/developer/api/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`](https://documentation.dnanexus.com/developer/introduction-to-data-object-classes/drives#api-method-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**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time.
  * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (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](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) 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**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results that were last modified at or after this time
  * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (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**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time
  * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (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`](https://documentation.dnanexus.com/developer/running-analyses/global-workflows#api-method-globalworkflow-xxxx-yyyy-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)](https://documentation.dnanexus.com/developer/api/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](https://documentation.dnanexus.com/user/omics-data-catalog) 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](https://documentation.dnanexus.com/developer/omics-data-catalog#api-method-datacatalog-xxxx-invite) 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](https://documentation.dnanexus.com/developer/api/regions) 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`](https://documentation.dnanexus.com/developer/omics-data-catalog#api-method-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](https://documentation.dnanexus.com/developer/api/omics-data-catalog) 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](https://documentation.dnanexus.com/developer/protocols#errors) for standard error handling.

## Search-Related Methods

See [Search](https://documentation.dnanexus.com/developer/api/search) for additional system methods related to finding objects based on certain criteria.