# Global Workflows Global workflows are immutable workflows that can be versioned and *published* to make them available to other users. They reside in a global namespace, shared with apps. They are implemented as wrappers of regular, project-based workflow objects so any workflow can be converted to a global workflow with a unique name and version. Conceptually, and on the API level, global workflows are similar to [apps](https://documentation.dnanexus.com/developer/api/running-analyses/apps). Both are executables that: * are global objects that are not stored in any particular project but can be accessed by users from the DNAnexus Tools Library * have a unique name in the global namespace (this namespace includes both apps and global workflows) * can have multiple versions. Together with the name, versions allow users to uniquely identify the executable and access its provenance through the immutable version history * can be accessed by users or orgs listed in the authorized users list and the developers list * can be updated only by users or orgs listed in the developers list * can be labelled with a category and searched by that category. Examples of categories include Structural Variation and RNA-seq. A [resource container](#workflow-resource-containers) is associated with each version of a global workflow, a separate one is used for each of the enabled regions. The resource container contains the underlying (wrapped) workflow and all the dependencies necessary to run the global workflow. When a global workflow is launched, an analysis object is created, like for any workflow on the DNAnexus Platform. ## Name and Version The name, together with a version, uniquely identifies a global workflow. Once someone claims a name (for an app or another global workflow), it cannot be changed even if the global workflow has been deleted. When a developer creates a global workflow with a name and version, the DNAnexus Platform generates a unique ID of the form `globalworkflow-xxxx`. The workflow can be uniquely referred to by that ID or by the alias `globalworkflow-/`, for example, `globalworkflow-micromap/0.0.1`. One, and only one, version can be labeled with an additional `default` alias. This is assigned to the first version automatically and can be shifted to any other version. It allows the workflow to be referred to by its name only, for example, `globalworkflow-micromap`, in which case the version associated with the `default` flag is invoked. Before a particular version of the workflow is *published*, it is not visible to other users on the platform except to the developers of the same global workflow. ## Publishing Once the developer calls the [`/globalworkflow-xxxx/publish`](#api-method-globalworkflow-xxxx-yyyy-publish) API method, the version of the workflow is made available to the users that are specified as the workflow's authorized users. Before publishing only the developers can access it. The title, summary, and documentation can still be updated after the workflow is published but all the other metadata and functionality remain immutable. It is impossible to unpublish a global workflow version. ## Developers Similar to app developers, global workflow developers are a set of users or orgs that can update any version of the workflow, create new versions of the workflow with a particular name, and release (publish) workflow versions to authorized users. They can also update the list of developers and authorized users of the workflow. Developers have access to the workflow versions that are unpublished (under development). When a user first creates a global workflow with a particular name and version, that user is initially the sole developer. One difference between apps and workflows is that any developer of a global workflow can update, publish, or delete it, not only the creator of the version. As in the case of apps, the list of developers can be updated at any time and the list is applied to **all** (past and future) versions of the workflow. ## Authorized Users A list of users or organizations that can view and run the published versions of the global workflow. If the workflow is unpublished, only developers can access it. To run and view the workflow, the users must also be the authorized users of all the apps of the workflow and the apps must be published. As in the case of apps, developers can add and remove the members of the list at any time and the user list is applied to **all** (past and future) versions of the workflow. ## Categories As with apps, developers can add categories to global workflows. See [App Categories](https://documentation.dnanexus.com/developer/api/apps#categories) section for details on app categories that also apply to global workflows. ## Updating Workflow Versions Unlike apps, global workflows cannot be updated in place even when they are unpublished. You must change the version string when you want to make changes to the workflow. The only exception is metadata fields unrelated to the function of the workflow, such as title, summary, and documentation. These can be changed at any time for both published and unpublished versions of the workflow. ## Deleting Workflow Versions Global workflows can be marked as deleted using the [`/globalworkflow-xxxx[/yyyy]/delete`](#api-method-globalworkflow-xxxx-yyyy-delete) API method. After a global workflow version is deleted, it can still be described (the response of which indicates that it has been deleted), but it can no longer be run. To help maintain provenance, even if all the versions of the workflow are deleted the name of the workflow remains claimed and cannot be re-used. ## Workflow Resource Containers Just like apps, each global workflow has access to its resource container, which is used to store objects needed by the workflow. One resource container is maintained in each region in which the workflow may be run. These containers are created at global workflow creation time and remain persistent while the workflow object exists. When running an analysis in a certain region, the resource container of the corresponding workflow *in that region* is read-only to the jobs of the analysis, and it is not accessible to the user executing the workflow. The resource containers belong to the developer. For billing purposes, data in the container is the responsibility of the user or organization specified as `billTo` for the global workflow. ## Multi-Region Global Workflows A global workflow can run in multiple [regions](https://documentation.dnanexus.com/developer/api/regions). Each **enabled region** has its own container that stores the workflow executable specific to that region. When creating a workflow version, the developer selects which regions to enable. Once set, these regions cannot be changed for that version. When a global workflow is executed, the region of the project context decides which region the workflow runs in. If the workflow contains any apps, all the apps must be enabled in the regions in which the workflow is executed. ## Global Workflow API Method Specifications ### API method: `/globalworkflow/new` #### Specification Creates a global workflow. A read-only container for the global workflow's resources is created and initialized as specified by the `resources` option. Also, the workflow object defined under `regionalOptions` and the applets (together with their assets) that are defined in the workflow stages are copied into it. Developers of the global workflow have VIEW access to the resources container. After the workflow is published, the authorized users also have VIEW access to this container. If the workflow is being created for the first time, then the `billTo` defaults to the `billTo` of the requesting user (this is the same default billing account for new projects created by the user) unless otherwise specified. This same billing account **must** be used for all subsequent versions created under the same global workflow name. The fields `name`, `version`, `regionalOptions` (pointing to at least one `workflow` ID in one region) are required. The set of enabled regions of a particular version is the keys of the `regionalOptions` mapping. The set of enabled regions is fixed once the version is created. #### Inputs * `regionalOptions` **mapping** (required) Configurations for all [regions](https://documentation.dnanexus.com/developer/api/regions) in which this global workflow is enabled. Regions are specified with strings like `aws:us-east-1` or `azure:westus`. * **key** — Name of a region in which this workflow may be run. * **value** **mapping** — Configuration of this workflow in the corresponding region, with the following key-value pairs: * `workflow` **string** (required) ID of the underlying workflow of this global workflow in the corresponding region. It is a regular workflow, stored in any project as a data object. The I/O specifications of all specified underlying workflows must be equal. * `resources` **string or array of strings** (optional) For each region in `regionalOptions`, this field can be specified as either the string ID of a project to snapshot into the global workflow's resources container, or as an array of data object IDs to clone into the root folder of that container. If you specify `resources` for one region, you must specify it for all regions in `regionalOptions`. * `name` **string** (required) Name for the global workflow, for example `micromap`. Must match `/^[a-zA-Z0-9._-]+$/` and cannot start with the prefix `app-` or `globalworkflow-`. See [Name and version](#name-and-version). * `version` **string** (required) A nonempty freeform string representing the global workflow's version. Must be unique for the given global name (string provided must match /^\[a-zA-Z0-9.\_+-]+$/). See [Name and version](#name-and-version). * `title` **string** (optional) Title for the global workflow, for example "Micro Map". If no title (or an empty string) is found, then `name` is used as the title. * `summary` **string** (optional) A one-line description for the global workflow. * `description` **string** (optional) A longer description of the workflow, formatted in Markdown, to be displayed on the workflow's detail page. * `developerNotes` **string** (optional) More advanced documentation for the global workflow. * `billTo` **string** (optional) ID of the entity to which all resource/storage costs associated with this global workflow are billed. Must be the ID of the requesting user or an org of which the requesting user is a member with `allowBillableActivities` permission. If this is a subsequent version of an existing global workflow, then `billTo` **must** be the same as `billTo` of the existing global workflow. Defaults to the `billTo` of the requesting user issuing the API call. * `nonce` **string** (optional) Unique identifier (idempotency token) for this request. Ensures that even if multiple requests fail and are retried, only a single global workflow is created. For more information, see [Nonces](https://documentation.dnanexus.com/developer/api/nonces). * `treeTurnaroundTimeThreshold` **integer** (optional) The turnaround time threshold (in seconds) for trees (specifically, root executions) that run this executable. See [Job Notifications](https://documentation.dnanexus.com/user/running-apps-and-workflows/job-notifications) for more information about turnaround time and managing job notifications. * Defaults to the lowest `treeTurnaroundTimeThreshold` field across the `regionalOptions` workflows if the `billTo` of the global workflow has `jobNotifications` enabled, otherwise N/A (positive infinity, meaning "not available"). {% hint style="info" %} A license is required to use the `jobNotifications` feature. Contact [DNAnexus Sales](mailto:sales@dnanexus.com) to enable `jobNotifications`. {% endhint %} #### Outputs * `id` **string** ID of this workflow (of the form `globalworkflow-`). * `resourcesByRegion` **mapping** The resource containers created for this workflow. * **key** — Region name such as `aws:us-east-1` or `azure:westus`. * **value** **string** — ID of the resources container of this global workflow in the corresponding region. #### Errors * InvalidInput * If `regionalOptions` is specified, then it must be non-empty. * If `workflow` is specified for one region in `regionalOptions`, then it must be specified for *all* regions. * The workflow denoted by `regionalOptions[r].workflow` (where `r` is a region name) must reside in the region denoted by `r.` * `version` is already in use by an existing version of this global workflow, or is a `tag` for a published version of this workflow. * A `nonce` was reused in a request but other inputs had changed signifying a new and different request. * A `nonce` may not exceed 128 bytes. * PermissionDenied * VIEW access is required to the underlying workflow and to all required objects. * If the `name` provided is in use, then the user must also be listed as a developer for the name. * A full scope token or one with developer access is required. * `billTo` must be either the ID of the requesting user or the ID of an org of which the requesting user is a member with `allowBillableActivities` permission. * The `billTo` of the invoking user is an org and the user is no longer a member of that org. * The region of the workflow that this global workflow was created from must be one of the `permittedRegions` of this global workflow's `billTo.` * The project context is associated with a [TRE](https://documentation.dnanexus.com/developer/api/trusted-research-environments). Creating new global workflows is not allowed in TRE projects. See [Non-Configurable Restrictions](https://documentation.dnanexus.com/developer/trusted-research-environments#non-configurable-restrictions). * SpendingLimitExceeded * The `billTo` has reached its spending limit. * OrgExpired * The `billTo` organization has expired. ### API method: `/globalworkflow-xxxx[/yyyy]/update` #### Specification Updates the global workflow version with any fields that are specified below. Any developer of the global workflow can update it and unpublished as well as published versions can be updated. #### Inputs * `title` **string** (optional) The global workflow's title, for example, "Micro Map". * `summary` **string** (optional) The global workflow's summary. * `description` **string** (optional) The global workflow's description. * `developerNotes` **string** (optional) Advanced documentation for the global workflow. #### Outputs * `id` **string** ID of the global workflow (of the form `globalworkflow-`). #### Errors * InvalidInput * Invalid type values for any of the input fields. * ResourceNotFound * The specified global workflow does not exist. * PermissionDenied * User must be a developer of the global workflow. * A full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/addTags` #### Specification Adds the specified tags to this version of the global workflow. If any of the tags are already present, no action is taken for those tags. If any of the tags are already in use by different versions of this workflow, those tags are removed from the other versions and added to this version. This maintains the invariant that any tag only applies to a single version of a global workflow. Example: you have two published versions of a global workflow, `globalworkflow-foo/1.0.0` and `globalworkflow-foo/2.0.0`, and version 1.0.0 is the current default. You can make version 2.0.0 the default by calling `/globalworkflow-foo/2.0.0/addTags` with input `{"tags":["default"]}` #### Inputs * `tags` **array of strings** (required) List of tags to add to the specified global workflow version. #### Outputs * `id` **string** ID of the workflow (of the form `globalworkflow-`). #### Errors * ResourceNotFound * The specified global workflow does not exist. * InvalidInput * Input is not a hash, * `tags` is not present or is not an array of nonempty strings. * A tag is equal to an existing version, whether published or not. * PermissionDenied * User must be a developer of the global workflow. * A full scope token or one with developer access is required. * InvalidState * The global workflow object has already been deleted. ### API method: `/globalworkflow-xxxx[/yyyy]/removeTags` #### Specification Removes the requested aliases of `globalworkflow-/`. #### Inputs * `tags` **array of strings** (required) List of tags to remove from all versions of the global workflow. #### Outputs * `name` **string** Global workflow name modified, such as "bwa". #### Errors * ResourceNotFound * The specified global workflow name does not exist. * InvalidInput * Input is not a hash. * `tags` is not present or is not an array of nonempty strings. * A tag is equal to an existing version. * The tag includes the special tag "default". * PermissionDenied * User must be a developer of the global workflow. * A full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/publish` #### Specification Releases the version of the global workflow so that it is discoverable and runnable by authorized users on the platform. Once published, the workflow can be accessed by object ID, `globalworkflow-/`, and, if tags are present, by `globalworkflow-/`. Any developer of the global workflow can publish the version. #### Inputs * `makeDefault` **boolean** (optional) Whether this global workflow should take on the `default` tag, removing it from whichever workflow version was previously marked as `default`. Defaults to `false`. #### Outputs * `id` **string** ID of the workflow (of the form `globalworkflow-`). #### Errors * PermissionDenied * A full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/describe` #### Specification Describe the global workflow. #### Inputs * `fields` **mapping** (optional) Restrict the output of this method to have only the provided keys in this field. * **key** — Output field. See the "Outputs" section below for valid values here. * **value** **boolean or mapping** — A boolean value indicates whether to include the output field. #### Outputs * `id` **string** ID of the global workflow (of the form `globalworkflow-`). * `class` **string** The value `globalworkflow`. * `billTo` **string** ID of the user/organization that owns this global workflow's name (and is billed for the storage incurred by the workflow versions). * `name` **string** Name of the workflow. * `title` **string** Freeform name. * `version` **string** Version of the workflow. * `aliases` **array of strings** List that includes the version and all tags of this workflow by which it can be addressed using `globalworkflow-/`. * `summary` **string** A one-line description of the workflow. * `description` **string** A long description of the workflow, formatted in Markdown, to be displayed on the workflow's detail page. * `categories` **array of strings** List of categories the workflow belongs to. * `dxapi` **string** The version of the API used. * `createdBy` **string** ID of the user who created the workflow. * `created` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) When the workflow was created. * `modified` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) When this workflow was last modified. * `deleted` **boolean** Whether the workflow has been deleted. * `isDeveloperFor` **boolean** Whether the requesting user has developer permissions for the workflow AND the token provided has full scope or has developer access. * `authorizedUsers` **array of strings** List of user and org IDs representing who can describe and run this workflow. If the string "PUBLIC" is present, then all users can access this workflow. * `regionalOptions` **mapping** Contains the regional configurations for this workflow. * **key** — Region name such as `aws:us-east-1` or `azure:westus`. The existence of a region here indicates that this workflow may be run in this region, and absence of a region indicates otherwise. * **value** **mapping** — Configuration of this workflow in the corresponding region, with the following key-value pairs: * `workflow` **string** ID of the underlying workflow of this global workflow in the corresponding region. * `resources` **string** ID of the resources container of this global workflow in the corresponding region. It contains the underlying workflow and any other dependencies (files, applets). * `published` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which this workflow was published. * Only present when the workflow is published. The following fields are included by default (but can be disabled using `fields`): * `treeTurnaroundTimeThreshold` **integer** (nullable) The turnaround time threshold (in seconds) for trees (specifically, root executions) that run this executable. See [Job Notifications](https://documentation.dnanexus.com/user/running-apps-and-workflows/job-notifications) for more information about turnaround time and managing job notifications. {% hint style="info" %} A license is required to use the `jobNotifications` feature. Contact [DNAnexus Sales](mailto:sales@dnanexus.com) to enable `jobNotifications`. {% endhint %} #### Errors * InvalidInput * Input is not a hash. * `fields` if present is not a hash or has a non-boolean key. * ResourceNotFound * The specified workflow does not exist. * PermissionDenied * The requesting user must be represented in the access list or must be one of the workflow's developers. If the latter, a full scope token or one with developer access is required. * If the workflow is unpublished, the requesting user must be one of the workflow's developers, and a full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/run` #### Specification Run the specified global workflow. #### Inputs * `name` **string** (optional) Name for the resulting analysis. * Defaults to the global workflow's title if set, otherwise its name. * `input` **mapping** (optional) Input that the global workflow is launched with. * **key** — Input field name (as it appears in the input specification of any of the underlying workflows). * **value** — Input field value. * `project` **string** (required if invoked by a user, optional if invoked from a job with `detach: true` option, prohibited when invoked from a job with `detach: false`) The ID of the project in which this global workflow runs, also known as the *project context*. If invoked with the `detach: true` option, then the detached analysis runs under the provided `project` (if provided), otherwise project context is inherited from that of the invoking job. If invoked by a user or run as detached, all output objects are cloned into the project context. Otherwise, all output objects are cloned into the temporary workspace of the invoking job. See [The Project Context and Temporary Workspace](https://documentation.dnanexus.com/developer/api/running-analyses/..#project-context-and-temporary-workspace) for more information. {% hint style="info" %} A license is required to launch detached executions. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information. {% endhint %} * `folder` **string** (optional) The folder into which objects output by the analysis are placed. If the folder does not exist when the job is complete, the folder is created, along with any parent folders necessary. See [Customizing Output Folders](https://documentation.dnanexus.com/developer/api/workflows-and-analyses#customizing-output-folders) for more details on how it interacts with stages' output folders. * `stageFolders` **mapping** (optional) Override any stored options for the workflow stages' `folder` fields. See the [Customizing Output Folders](https://documentation.dnanexus.com/developer/api/workflows-and-analyses#customizing-output-folders) section for more details. * **key** — Stage ID or `"*"` to indicate that the value should be applied to all stages not otherwise mentioned. * **value** **null or string** — Value to replace the stored default. * `details` **array or mapping** (optional) Any conformant JSON, which means a JSON object or array per RFC4627. This is stored with the created analysis. Defaults to `{}`. * `systemRequirements` **mapping** (optional) Request specific resources for all stages not explicitly specified in `stageSystemRequirements`. Values are merged with stages' stored values as described in [System Requirements](https://documentation.dnanexus.com/developer/api/workflows-and-analyses#system-requirements). See [Requesting Instance Types](https://documentation.dnanexus.com/developer/api/applets-and-entry-points#requesting-instance-types) for more details. * `stageSystemRequirements` **mapping** (optional) Request specific resources by stage. Values are merged with stages' stored values as described in the [System Requirements](https://documentation.dnanexus.com/developer/api/workflows-and-analyses#system-requirements) section. * **key** — Stage ID. * **value** **mapping** — Value to override or merge with the stage's `systemRequirements` value. * `systemRequirementsByExecutable` **mapping** (optional) Request system requirements for all jobs in the resulting execution tree, configurable by executable and by entry point, described in more detail in the [Requesting Instance Types](https://documentation.dnanexus.com/developer/api/applets-and-entry-points#requesting-instance-types) section. * `timeoutPolicyByExecutable` **mapping** (optional) The timeout policies for jobs in the resulting job execution tree, configurable by executable and the entry point within that executable. See the `timeoutPolicyByExecutable` field in [`/applet-xxxx/run`](https://documentation.dnanexus.com/developer/api/applets-and-entry-points#api-method-applet-xxxx-run) for more details. * `delayWorkspaceDestruction` **boolean** (optional) If not given, the value defaults to false for root executions (launched by a user or detached from another job), or to the parent's `delayWorkspaceDestruction` setting. If set to true, the temporary workspace created for the resulting execution is preserved for 3 days after the job either succeeds or fails. * `nonce` **string** (optional) Unique identifier for this request. Ensures that even if multiple requests fail and are retried, only a single analysis is created. For more information, see [Nonces](https://documentation.dnanexus.com/developer/api/nonces). * `tags` **array of strings** (optional) Tags to associate with the resulting analysis. * `properties` **mapping** (optional) Properties to associate with the resulting analysis. * **key** — Property name. * **value** **string** — Property value. * `singleContext` **boolean** (optional) If true then the resulting jobs and all their descendants are only allowed to use the authentication token given to them at the onset. Use of any other authentication token results in an error. This option offers extra security to ensure data cannot leak out of your given context. In restricted projects user-specified value is ignored, and `singleContext: true` setting is used instead. * `detach` **boolean** (optional) This option has no impact when the API is invoked by a user. If invoked from a job with detach set to true, the new analysis is detached from the creator job and appears as a typical root execution. A failure in the detached analysis does not cause a termination of the job from which it was created and vice versa. The detached job inherits neither the access to the workspace of its creator job nor the creator job's priority. Detached analysis' access permissions are the intersection (most restricted) of access permissions of the creator job and the permissions requested by jobs' executables in the detached analysis. To launch the detached analysis, creator job must have CONTRIBUTE or higher access to the project in which the detached job is launched. The billTo of the project in which the creator job is running must be licensed to launch detached executions. {% hint style="info" %} [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for information on a license that supports launching detached executions. {% endhint %} * `rank` **integer** (optional) An integer between -1024 and 1023, inclusive. The rank indicates the priority in which the executions generated from this executable are processed. The higher the rank, the more prioritized it is. If no rank is provided, the executions default to a rank of zero. If the execution is not a root execution, it inherits its parent's rank. If a rank is provided, all executions relating to the workflow stages also inherit the rank. {% hint style="info" %} A license is required to use the Job Ranking feature. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information. {% endhint %} * `costLimit` **number** (optional) The limit of the cost that this execution tree should accrue before termination. This field is ignored if this is not a root execution. * `preserveJobOutputs` **mapping** (optional, nullable) Preserves all cloneable outputs of every completed, non-jobReused job in the execution tree launched by this API call in the root execution project, even if root execution ends up failing. Preserving the job outputs in the project trades off higher costs of storage for the possibility of subsequent job reuse. Defaults to `null`. \ When a non-jobReused job in the root execution tree that is launched with non-null `preserveJobOutputs` enters the "done" state, all cloneable objects referenced by the `$dnanexus_link` in the job's `output` field are cloned to the project folder described by `preserveJobOutputs.folder`. This happens unless the output objects already appear elsewhere in the project. Cloneable objects include files, records, applets, and closed workflows, but not databases. If the folder specified by `preserveJobOutputs.folder` does not exist in the project, the system creates the folder and its parents.\ \ As the root job or root analysis' stages complete, the regular outputs of the root execution are moved from `preserveJobOutputs.folder` to the regular output folders of the root execution. When you run your root execution without the `preserveJobOutputs` option to completion, some root execution outputs appear in the project in the root execution's output folders. If you had run the same execution with `preserveJobOutputs.folder` set to `"/pjo_folder"`, the same set of outputs would appear in the same set of root execution folders as in the first case at completion of the root execution. Some additional job outputs that are not outputs of the root execution would appear in `"/pjo_folder"`. `preserveJobOutputs` argument can be specified only when starting a root execution or a detached job.\ \ `preserveJobOutputs` value, if not **null**, should be a mapping that may contain the following: * **key** — `"folder"` **string** (optional). * **value** — `path_to_folder` **string** (required if "folder" key is specified). Specifies a folder in the root execution project where the outputs of jobs that are a part of the launched execution are stored. `path_to_folder` starting with `/` is interpreted as absolute folder path in the project the job is running in. `path_to_folder` not starting with `/` is interpreted as a path relative to the root execution's `folder` field. An empty string `path_to_folder` value (`""`) preserves job outputs in the folder described by root execution's `folder` field. If the `preserveJobOutputs` mapping does not have a `folder` key, the system uses the default folder value of `"intermediateJobOutputs"`. For example, `"preserveJobOutputs": {}` is equivalent to `"preserveJobOutputs": {"folder":"intermediateJobOutputs"}`. It is recommended to place preserveJobOutputs outputs for different root executions into different folders so as not to create a single folder with a large (>450K) number of files. {% hint style="info" %} A license is required to use `preserveJobOutputs`. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information. {% endhint %} * `detailedJobMetrics` **boolean** (optional) Requests detailed metrics collection for jobs if set to true. This flag can be specified for root executions and applies to all jobs in the root execution. The list of detailed metrics collected every 60 seconds and viewable for 15 days from the start of a job is available using [`dx watch --metrics`](https://documentation.dnanexus.com/user/helpstrings-of-sdk-command-line-utilities#watch-metrics-help). * Defaults to the project `billTo`'s `detailedJobMetricsCollectDefault` policy setting, or `false` if the org default is not set. {% hint style="info" %} A license is required to use `detailedJobMetrics`. Contact [DNAnexus Sales](mailto:sales@dnanexus.com) for more information. {% endhint %} #### Outputs * `id` **string** ID of the created analysis object, which is a string in the form `analysis-xxxx`. * `stages` **array of strings** List of job IDs that are created for each stage, as ordered in the workflow. #### Errors * ResourceNotFound * The specified workflow object, any referenced workflows, apps or applets, default input files, or project context does not exist. * PermissionDenied * The requesting user must be represented in the access list or must be one of the global workflow's developers. If the latter, a full scope token or one with developer access is required. * If the workflow is unpublished, the requesting user must be one of the global workflow's developers, and either (1) a full scope token or one with developer access is required or (2) the token belongs to a job that is already running the same global workflow. * CONTRIBUTE access to the project context is required unless called by a job. * The requesting user must be represented in the access list of all apps or must be the apps' developer. If the latter, a full scope token or one with developer access is required. * When specifying `allowSSH` or `debug` options, the user must have developer access to all apps in the workflow, or the apps must have the `openSource` field set to true. * If `preserveJobOutputs` is not **null** and `billTo` of the project where execution is attempted does not have preserveJobOutputs license. * `detailedJobMetrics` setting of true requires project's `billTo` to have `detailedJobMetrics` license feature set to true. * `app{let}-xxxx` can not run in `project-xxxx` because executable's `httpsApp.shared_access` should be `NONE` to run with Isolated Browsing. This check is applied to all workflow stages. * The `billTo` of the job's project must be licensed to start detached executions when invoked from the job with `detach: true` argument. * `timeoutPolicyByExecutable` for all executables should not be `null` * `timeoutPolicyByExecutable` for all entry points of all executables should not be `null` * `timeoutPolicyByExecutable` for all entry points of all executables should not exceed 30 days * Expected key `timeoutPolicyByExecutable.*` of input to match `/^(app|applet)-[0-9A-Za-z]{24}$/` * The project is associated with a [TRE](https://documentation.dnanexus.com/developer/api/trusted-research-environments) and `allowSSH` was specified. SSH access is not allowed in TRE projects. See [Execution Restrictions](https://documentation.dnanexus.com/developer/trusted-research-environments#execution-restrictions). * The project is associated with a TRE and one or more stage executables have HTTPS app settings that are not allowed. In TRE projects, only allowlisted HTTPS apps may expose HTTPS, and only on port `443`. See [Execution Restrictions](https://documentation.dnanexus.com/developer/trusted-research-environments#execution-restrictions). * The project is associated with a TRE and one or more stage executables are not in the project's `allowedExecutables` list, if the TRE policy restricts allowed executables. {% hint style="info" %} [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for information on a license that supports launching detached executions. {% endhint %} * If rank is provided and the `billTo` does not have license feature `executionRankEnabled` set to true. {% hint style="info" %} [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for information on a license to use this feature. {% endhint %} * InvalidInput * The workflow spec is not complete. * The workflow must be enabled in the region of the project context. * All data object inputs must be in the same region as the project context. * All inputs that are job-based object references must refer to a job that was run in the same region as the project context. * A `nonce` was reused in a request but some other inputs had changed signifying a new and different request. * A `nonce` may not exceed 128 bytes. * `preserveJobOutputs` is specified when launching a non-detached execution from a job. * `preserveJobOutputs.folder` value is a syntactically invalid path to a folder. * `detailedJobMetrics` can not be specified when launching a non-detached execution from a job. * `systemRequirements.*.instanceTypeSelector` keyword is not allowed at runtime * `systemRequirementsByExecutable.*.*.instanceTypeSelector` keyword is not allowed at runtime * `stageSystemRequirements.*.*.instanceTypeSelector` keyword is not allowed at runtime * InvalidState * Some input to the workflow is not in the "closed" state. * The project context's region is not among the enabled regions of the workflow. ### API method: `/globalworkflow-xxxx[/yyyy]/delete` #### Specification Mark a global workflow version as *deleted*. A deleted version can no longer be run, modified, nor published. This state is reflected in the output of describe. The associated resources container is made inaccessible. #### Inputs * None #### Outputs * `id` **string** ID of the workflow (of the form `globalworkflow-`). #### Errors * PermissionDenied * Requesting user must be the developer of the workflow. * A full scope token or one with developer access is required. * InvalidState * If the workflow has multiple versions, all other versions must be deleted before a workflow with the "default" can be deleted. ### API method: `/globalworkflow-xxxx[/yyyy]/addDevelopers` #### Specification Adds developers (users and/or orgs) to the global workflow. If the requesting user is not a developer of the global workflow, but they are the `billTo` of the workflow **or** the `billTo` of the workflow is an org and the user is an ADMIN of that org, then the user may invoke this method. They can grant themselves, and **only** themselves, developer access to the workflow. #### Inputs * `developers` **array of strings** (required) List of user and/or org IDs that are added as developers. #### Outputs * `name` **string** The global workflow name, such as "bwa". #### Errors * ResourceNotFound * Specified global workflow does not exist. * A specified user does not exist. * InvalidInput * If the requesting user is not a developer of the workflow **and** is or administers the `billTo` of the workflow, then `developers` may only contain the ID of the requesting user. * PermissionDenied * The requesting user must be a developer of the workflow, or they must be or administer the `billTo` of the workflow. * If the requesting user is a developer of the workflow, then the user must have either a full-scope token or a token with developer access. * If the requesting user is not a developer of the workflow but is or administers the `billTo` of the workflow, then the user must have a full scope token. ### API method: `/globalworkflow-xxxx[/yyyy]/listDevelopers` #### Specification List the developers of the global workflow. #### Inputs * None #### Outputs * `developers` **array of strings** List of user and/or org IDs that are developers. #### Errors * ResourceNotFound * The specified workflow does not exist. ### API method: `/globalworkflow-xxxx[/yyyy]/removeDevelopers` #### Specification Remove a list of developers from the global workflow. Attempting to remove a user or org who is not listed as a developer does not throw an error. If the billing account of the global workflow is a user ID, then the developer access of that user may **not** be revoked. #### Inputs * `developers` **array of strings** (required) list of user and/or org IDs that are removed as developers. #### Outputs * `name` **string** The global workflow name, such as "bwa". #### Errors * ResourceNotFound * The specified workflow does not exist. * InvalidInput * The billing account of the workflow is a user ID and `developers` contains that user ID. * PermissionDenied * User issuing the API call must be a developer of the workflow. * A full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/addAuthorizedUsers` #### Specification Add users and/or org IDs to the access list. The access list applies to all global workflow versions. #### Inputs * `authorizedUsers` **array of strings** (required) List of user and/or org IDs to add to the access list. #### Outputs * `name` **string** The global workflow name, such as "bwa". #### Errors * ResourceNotFound * A specified global workflow or user/org does not exist. * InvalidInput * Input is not a hash, `authorizedUsers` is missing or is not an array of nonempty strings. * PermissionDenied * User must be a developer of the global workflow. * A full scope token or one with developer access is required. * "PUBLIC" cannot be added as an authorized user. If you are interested in making an app or global workflow available to all users of the DNAnexus Platform, contact [Support](mailto:support@dnanexus.com). ### API method: `/globalworkflow-xxxx[/yyyy]/listAuthorizedUsers` #### Specification List the users and/or org IDs on the access list for the workflow. The string "PUBLIC" represents the set of all users on DNAnexus Platform. The access list applies to all global workflow versions. #### Inputs * None #### Outputs * `authorizedUsers` **array of strings** List of user and/or org IDs that can describe and run the workflow. If "PUBLIC" is present, this means all users can access the workflow. #### Errors * ResourceNotFound * The specified global workflow does not exist. * PermissionDenied * The requesting user must be represented in the access list or must be one of the workflow's developers. If the latter, a full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/removeAuthorizedUsers` #### Specification Remove a list of user and/or org IDs from the access list for the global workflow. Removing an entity that is not listed in the access list does not throw an error. #### Inputs * `authorizedUsers` **array of strings** (required) List of user and/or org IDs to remove from the access list. #### Outputs * `name` **string** The global workflow name, such as "bwa". #### Errors * ResourceNotFound * A specified global workflow does not exist. * InvalidInput * Input is not a hash. * `authorizedUsers` is missing or is not an array of nonempty strings. * PermissionDenied * User must be a developer of the global workflow. * A full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/addCategories` #### Specification Add categories for the global workflow. #### Inputs * `categories` **array of strings** (required) List of categories to add the workflow to. #### Outputs * `name` **string** The global workflow name, such as "bwa". #### Errors * ResourceNotFound * A specified global workflow does not exist. * InvalidInput * Input is not a hash * `categories` is missing or is not an array of nonempty strings. * A listed category is not allowed: "new", "recommended", or "popular". * PermissionDenied * User must be a developer of the global workflow. * A full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/listCategories` #### Specification List the categories that a global workflow is a member of. All authorized users can list the categories of a published workflow. Categories apply to all the versions of the global workflow. #### Inputs * None #### Outputs * `categories` **array of strings** List of categories the global workflow belongs to. #### Errors * ResourceNotFound * The specified global workflow does not exist. * PermissionDenied * The requesting user must be represented in the access list or must be one of the workflow's developers. If the latter, a full scope token or one with developer access is required. * If the workflow is unpublished, the requesting user must be one of the workflow's developers, and a full scope token or one with developer access is required. ### API method: `/globalworkflow-xxxx[/yyyy]/removeCategories` #### Specification Remove the categories from a global workflow. #### Inputs * `categories` **array of strings** (required) List of categories (strings) to remove from the global workflow. #### Outputs * `name` **string** The global workflow name, such as "bwa". #### Errors * ResourceNotFound * A specified global workflow does not exist. * InvalidInput * Input is not a hash, `categories` is missing or is not an array of nonempty strings. * PermissionDenied * User must be a developer of the workflow. * A full scope token or one with developer access is required. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.dnanexus.com/developer/api/running-analyses/global-workflows.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.