APIDownloadsIndex of dx CommandsLegal

Apps

Apps (applications) are applets that have been packaged to be standalone executables that are versioned and can be published to make them available to other users. Apps can be configured to be open-source or proprietary.

Apps are published in a global app namespace, and multiple versions can be created for a single app name. Once an app name is claimed by a developer, other developers cannot create new apps that use the same name unless they are also listed as developers of the same app name. The app name continues to be claimed even after all app versions have been deleted.

Developers can publish versions of the app and control the list of authorized users, or the accounts that can find and run the app. If you are interested in making an app available to all users of the DNAnexus Platform, please contact us at support@dnanexus.com.

Apps can be installed by any of their authorized users. For now, this is used as merely a bookmarking utility. In the future, proprietary apps may require installation as a means of agreeing to a billing schedule or a set of terms of service.

Apps are created from existing applets. To create an app, a user (developer) specifies the applet and additional metadata, including the name for the app and information on whether and how they want to be compensated by users installing and running the app in their accounts. Once created, the app is only visible to the user who created it, so it can be tested. If the developer is satisfied, they can publish the app, optionally specifying additional tags (which are similar to a version), and the app will become visible to all users under the combination of its name and aliases (version and attached tags).

Apps are launched in the same way as applets, and execute jobs the same way applets do. Unlike applets, apps must have both input and output specifications and thus can only be created from applets that have both the fields inputSpec and outputSpec.

App versioning and publishing

When a developer creates an app with a name and version, its ID is of the form "app-xxxx" much like other object IDs, and it can also be uniquely referred to by the alias "app-<name>/<version>", e.g. "app-micromap/0.0.1". Before a particular version of the app is published, it can still be updated in place (including its code) and is not visible to other users on the platform except to other developers of the same app. Once someone claims an app name, it cannot be used by anyone else except by other developers listed for that app name.

An authorized user may run a given version of an app in some fixed set of regions, denoted by the enabled regions of the app version. The set of enabled regions may be specified by the creator at the time the app version is created, and the set is fixed thereafter for the app version.

Once the developer calls the /app-xxxx/publish route and optionally supplies tags (which may represent a version or any other designation by the developer), the version of the app is locked down and is made available to the app's authorized users under both the names "app-micromap/0.0.1" as well as "app-micromap/<tag>" for all tags provided. Tags are reusable; a future version of the app can be published with the same tag and will replace the previous version that the tag referred to. However, unless explicitly destroyed, all previously published versions will always be accessible as "app-<name>/<version>".

Publishing an app only exposes it to the users named in its authorized users list. Developers can change the list of authorized users of the app at any time; this list is applied to all (past and future) versions of the app.

Apps can be marked as deleted using the /app-xxxx/publish route. After an app version is deleted, it can still be described (the response of which will indicate that it has been deleted), but it can no longer be run.

App Workspace and Containers

Like applets, apps receive a container to use as a temporary workspace, whose ID is available in the workspace field of the describe route of each job in the app’s execution. The semantics of this workspace are identical to those of the applet workspace.

In addition to the temporary workspace, apps have access to two more types of containers:

  • The resources containers, which can be used to store objects needed by the app. One resources container is maintained in each region in which the app may be run. These containers are created at app creation time and are persistent as long as the app object exists. The resources containers belong to the app developer. When running a job in a certain region, the resources container of the corresponding app in that region is read-only to the job, and it is not accessible to the user executing the app. A container's ID is available in the resources field of the describe route of each job in the app’s execution.

    • When creating an app, the contents of the resources container can be specified through the resources parameter.

  • The project cache container. This container is attached to the project from which the user has launched the app, and is for caching data useful for subsequent executions of the app. The cache is shared among all instances of this app running in this project, unless the project has been marked as PROTECTED. If the project has the PROTECTED flag set, then each time the app is run, it will get a fresh project cache container that is destroyed upon successful completion of the job. The project cache ID is available through the job property projectCache. Project members may access or delete objects in the container at any time; the app should be able to tolerate this when creating or accessing objects in it. The cache is not visible to the app developer.

For all types of containers, the job can specify the workspace ID in place of a project ID when performing API relating to data manipulation.

The container IDs to these two types of containers are provided to jobs via the following environment variables:

  • DX_RESOURCES_ID: a string containing the container ID of the job’s resources container.

  • DX_PROJECT_CACHE_ID: a string containing the container ID of the job’s cache for the project context.

Unlike the temporary app workspace, the global resources container and project cache are not deleted when an app finishes. For billing purposes, data in the resources container is the responsibility of the user or organization specified as billTo for the app; data in the project caches belongs to the project it's attached to.

The app also has read access to any objects which are listed in projects with public view access.

Unlike applets, apps by default do not have VIEW access to data in the project they were launched from. Apps’ default data access is limited to:

  • Data explicitly specified by the user as inputs

  • Data available in the resources container or the project cache

  • Data in public projects

  • However, if access.project or access.allProjects flags are set when calling /app/new, the app has access equal to that of the user in the project or everywhere on the platform, respectively. (When the user launches an app with these flags set, they are presented with a dialog asking them to confirm the elevated privileges.)

Developers

Developers are users who are authorized to create a new version of an app with a particular name. When a user creates the first app with a particular name, that user is initially the sole developer. Developers can also add and remove other users as developers, modify unpublished apps, publish the apps, change who can describe and run the app, and view the resources of any version of the app under development.

In general, jobs cannot call methods which require developer permissions unless they have been given the permissions to do on behalf of the user who ran the job. See Access Requirements for how to request that a particular app or applet always be given developer access.

Categories

Developers can add categories to an app; this applies the categories to all versions of the app. This is true even when the URL refers to a particular app version. There will be a list of categories that will be specially displayed in the UI, and developers are encouraged to use these categories in order to make their apps more accessible. There are, however, no restrictions on the categories the developers choose to use to describe their apps, and apps will be searchable by their categories.

App API Method Specifications

API method: /app/new

Specification

Creates an app.

A read-only container for the app's resources is created and initialized as specified by the resources option. In addition, the applet object and the resources specified in bundledDepends of the run specification are cloned into it. Developers of the app have VIEW access to the resources container.

If the app is being created for the first time, then the billTo of the app will default 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 app name.

If this app version is being initialized from another app version (via initializeFrom), then the set of enabled regions of this app version is the same as that of the app from which this app is being initialized. Otherwise, regionalOptions is required and the set of enabled regions of this app version will be the keys of the regionalOptions mapping. The set of enabled regions is fixed once the app version is created.

Inputs

  • regionalOptions mapping (required if initializeFrom is not specified; optional otherwise) Configurations for all regions (e.g., "aws:us-east-1", "azure:westus") in which this app will be enabled.

    • key Name of a region in which this app may be run.

    • value mapping Configuration of this app in the corresponding region, with the following key-value pairs:

      • applet string (required if initializeFrom is not specified; prohibited otherwise) ID of the underlying applet of this app in the corresponding region. The applet must have both input and output specifications. Additionally, the I/O specifications of all specified applets must be equal. The run specifications may differ in certain fields, in order to facilitate the use of different resources across different regions; for more information, refer to Run Specification. Note that if applet is specified for one region in regionalOptions, then it must be specified for all regions.

      • resources string or array of strings (optional) Either the string ID of a project that will be snapshotted into the corresponding resources container of this app, or an array of data object IDs that will be cloned into the root folder of that resources container. Note that if resources is specified for one region in regionalOptions, then it must be specified for all regions.

        If regionalOptions and initializeFrom are both specified, then regionalOptions must contain all regions, and only those regions, in which initializeFrom is enabled. That is, the set of regions in which this app will be enabled will be exactly the same as the set in which initializeFrom is enabled.

  • initializeFrom string (required if applet is not provided; cannot be present otherwise) An app identifier from which to use as default values for all the fields; if any of the other fields are given, they override the value stored for the app object. The following exceptions apply:

    • The version field must be provided for the new app object to be created

    • If resources is not provided, the resources container of the new app object will be a cloned copy of the initializeFrom app object’s resources container; it is not functionally the same as providing the same value of the field resources as before (the project contents or data objects may have changed in the meantime).

  • name string (optional if initializeFrom is an app identifier) Name for the app, e.g. "micromap". Must match /^[a-zA-Z0-9._-]+$/ and cannot start with the prefix "app-". See App versioning and publishing.

  • title string (optional) Title for the app, e.g. "Micro Map". If not provided, inherited from applet or initializeFrom as applicable; if no (or an empty) title is found from those options, then name is used as the title.

  • summary string (optional) A one-line description for the app. If not provided, inherited from applet or initializeFrom as applicable.

  • description string (optional) A longer description of the app, formatted in Markdown, to be displayed on the app's detail page). If not provided, inherited from applet or initializeFrom as applicable.

  • developerNotes string (optional) More advanced documentation for the app. If not provided, inherited from applet or initializeFrom as applicable.

  • details array or mapping (optional) Any conformant JSON (i.e. a JSON object or array, per RFC4627), which will be stored with the app

  • version string A nonempty freeform string representing the app’s version; must be unique from any existing app with the same name (string provided must match /^[a-zA-Z0-9._+-]+$/). See App versioning and publishing.

  • openSource boolean (optional, default false) Whether the contents of this app version’s resources container should be viewable by all members of the app's developers and authorized users

  • ignoreReuse boolean (optional, default false) If true then no job reuse will occur by default for this app.

  • access mapping (optional) Access requirements as described in the Access Requirements section

  • billTo string (optional, default is billTo of the requesting user) ID of the entity to which all costs associated with this app will be 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 app, then billTo must be the same as billTo of the existing app.

  • nonce string (optional) Unique identifier for this request. Ensures that even if multiple requests fail and are retried, only a single app is created. For more information, see Nonces.

  • treeTurnaroundTimeThreshold integer (optional, default: in this context, N/A is positive infinity. The lowest treeTurnaroundTimeThreshold field across the regionalOptions applets if the billTo of the app has the jobNotifications feature switch and initializeFrom is N/A. If this condition is not met, then default will be the treeTurnaroundTimeThreshold field of the initializeFrom app if the billTo of the app has the jobNotifications feature switch and initializeFrom is not N/A. Otherwise, default is N/A.) The turnaround time threshold in seconds for trees (specifically, root executions) that run this executable. See Job Notifications for more information about turnaround time and managing job notifications.

A license is required to use the jobNotifications feature. Contact Sales to enable jobNotifications.

Deprecated fields:

  • applet string (required if neither initializeFrom nor regionalOptions[r].applet (for any region name r) is specified) ID of the applet from which the app will be created. The applet must have both input and output specifications. This field will be ignored if regionalOptions is specified. If applet is specified, then regionalOptions is not required above. If neither regionalOptions[r].applet (where r is a region name) nor initializeFrom is specified, then the enabled regions of this app will be the region of the specified applet.

  • resources string or array of strings (optional) Either a string containing the ID of a project which will be snapshotted into a resources container, or an array of data object IDs, which will all be cloned into the root folder of the resources container. All specified objects must reside in the same region as the applet denoted by applet. This field will be ignored if regionalOptions is specified.

Outputs

  • id string ID of this app (of the form app-<hash>).

  • resourcesByRegion mapping Mapping of the resources containers created for this app.

    • key Region name (e.g., "aws:us-east-1", "azure:westus").

    • value string ID of the resources container of this app in the corresponding region.

Deprecated fields:

  • resources string Arbitrarily selected ID of one of the resources containers of this app.

Errors

  • InvalidInput

    • If regionalOptions and initializeFrom are both specified, then regionalOptions must contain exactly the regions in which the app version denoted by initializeFrom is enabled.

    • If regionalOptions is specified, then it must be non-empty.

    • If applet (or resources) is specified for one region in regionalOptions, then it must be specified for all regions.

    • The applet denoted by regionalOptions[r].applet (where r is a region name) must reside in the region denoted by r.

    • Only one of initializeFrom or applet may be specified.

    • version (if specified) is already in use by an existing version of this app, or is a tag for a published version of this app.

    • The applet (if specified) contains bundled dependencies that reside in regions that differ from the region in which the applet was created.

    • If regionalOptions[r].applet (where r is a region name) is specified for at least one r, then the input, output, and run specifications of all specified applets must be equivalent, as defined above.

    • If regionalOptions[r].resources (where r is a region name) is specified for at least one r, then all of the objects denoted by r.resources must reside in the region denoted by r.

    • If resources is an array of objects, then all of the objects must reside in the same region as the one in which this app is being created.

    • If resources is a project id, then the project must reside in the same region as the one in which this app is being created and the project can contain any object that is not in live status.

    • A nonce was reused in a request but some of the other inputs had changed signifying a new and different request

    • A nonce may not exceed 128 bytes

  • PermissionDenied

    • VIEW access is required to the applet and to all required objects, or the invoking user must be a developer of the app specified in initializeFrom

    • VIEW access to the project specified by resources (if provided) is required

    • 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 original app or applet that this app was created from must be one of the permittedRegions of this app's billTo

    • The billTo of the app is not licensed to use jobNotifications. Contact sales@dnanexus.com to enable jobNotifications.

  • SpendingLimitExceeded

    • billTo has reached its spending limit

API method: /app-xxxx[/yyyy]/update

Specification

Updates the app version with any fields that are specified below.

If either regionalOptions[r].applet (where r is a region name) or regionalOptions[r].resources are specified, then, for each region in which this app version is enabled, the previous resources container will be emptied of its contents before initializing it again with the corresponding applet, its bundled dependencies, and the contents of the user-specified regionalOptions[r].resources field. Note that if regionalOptions[r].applet is provided but regionalOptions[r].resources is not, then this has the effect of having specified the empty list for regionalOptions[r].resources.

Inputs

  • regionalOptions mapping (optional) Configurations for all regions (e.g., "aws:us-east-1", "azure:westus") in which this app is enabled. This mapping must contain a key for each region in which this app version is enabled.

    • key Name of a region in which this app may be run.

    • value mapping Configuration of this app in the corresponding region, with the following key-value pairs:

      • applet string (optional) ID of the new underlying applet of this app in the corresponding region. The applet must have both input and output specifications. Additionally, the input, output, and run specifications of all specified applets must be equivalent. Note that if applet is specified in one region in regionalOptions, then it must be specified for all regions.

      • resources string or array of strings (optional) Either the string ID of a project that will be snapshotted into the existing resources container of this app in the corresponding region, or an array of data object IDs that will be cloned into the root folder of that resources container. The existing resources container's ID will remain unchanged. Note that if resources is specified for one region in regionalOptions, then it must be specified for all regions.

  • title string (optional) The app’s title, e.g. "Micro Map"

  • summary string (optional) The app’s summary

  • description string (optional) The app’s description

  • developerNotes string (optional) Advanced documentation for the app

  • details array or mapping (optional) Any conformant JSON (i.e. a JSON object or array, per RFC4627), which will be stored with the app

  • openSource boolean (optional) Whether the contents of this app version’s resources container should be viewable by all members of the app's developers and authorized users

  • access mapping (optional) Access requirements as described in the Access Requirements section

Deprecated fields:

  • applet string (optional) Recreate the app using the provided applet ID. This field will be ignored if regionalOptions is specified.

  • resources string or array of strings (optional) Either a string containing the ID of a project which will be snapshotted into a resources container, or an array of data object IDs, which will all be cloned into the root folder of the resources container. The resource container's ID will not change. This field will be ignored if regionalOptions is specified.

Outputs

  • id string ID of the app (of the form "app-<hash id>")

Errors

  • InvalidInput

    • If regionalOptions is specified, then it must contain exactly the regions in which this app version is enabled and the project can contain any object that is not in live status.

    • If applet (or resources) is specified for one region in regionalOptions, then it must be specified for all regions.

    • The applet denoted by regionalOptions[r].applet (where r is a region name) must reside in the region denoted by r.

    • If regionalOptions[r].applet (where r is a region name) is specified for at least one r, then the input, output, and run specifications of all specified applets must be equivalent, as defined above.

    • If regionalOptions[r].resources (where r is a region name) is specified for at least one r, then all of the objects denoted by r.resources must reside in the region denoted by r.

  • ResourceNotFound (the specified app does not exist)

  • InvalidState (the app has already been published)

  • PermissionDenied

    • User must be the user who created the app

    • A full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/addTags

Specification

Adds the specified tags to this version of the app. 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 app, 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 an app.

Example: you have two published versions of an app, app-foo/1.0.0 and app-foo/2.0.0, and version 1.0.0 is the current default, you can make version 2.0.0 the default by calling /app-foo/2.0.0/addTags with input {"tags":["default"]}

Inputs

  • tags array of strings List of tags to add to the specified app

    version

Outputs

  • id string ID of the app (of the form "app-<hash id>")

Errors

  • ResourceNotFound

    • The specified app 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 app

    • A full scope token or one with developer access is required

  • InvalidState

    • The app object has already been deleted

API method: /app-xxxx[/yyyy]/removeTags

Specification

Remove the requested aliases of "app-<name>/<tag>"

Inputs

  • tags array of strings List of tags to remove from all versions

    of the app

Outputs

  • name string App name modified (e.g. "bwa")

Errors

  • ResourceNotFound

    • The specified app name does not exist

  • InvalidInput

    • Tnput is not a hash, tags is not present or is not an array of nonempty strings, a tag is equal to an existing version, or the tag includes the special tag "default"

  • PermissionDenied

    • User must be a developer of the app

    • A full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/publish

Specification

This version of the app is now discoverable by authorized users on the platform and can be accessed by object ID, "app-<name>/<version>", and "app-<name>/<tag>" if the app object also has tags. The app is now closed to further updates by the developers.

Inputs

  • makeDefault boolean (optional, default false) Whether this app should take on the "default" tag, removing it from whichever app version was previously marked as "default"

Outputs

  • id string ID of the app (of the form "app-<hash id>")

Errors

  • PermissionDenied

    • User must be the user who created the app

    • A full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/describe

Specification

Describe the app.

Inputs

  • fields mapping (optional) Restrict the output of this method to have only the provided keys in this field; the inputSpec and outputSpec fields can be further customized as well.

    • 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. For inputSpec and outputSpec, then the value may be a mapping with key/values restricting the fields returned for each input or output parameter specification. In such a case, the key/values must be:

      • key Field name of an I/O parameter descriptor, e.g. "name" or "choices" (see the documentation on input and output specifications for all possible choices)

      • value boolean Whether to include the field for all I/O parameter descriptors

Outputs

  • id string ID of the app (of the form "app-<hash id>")

  • class string The value "app"

  • billTo string ID of the user/organization that owns this app’s name (and is billed for the storage incurred by the app versions)

  • name string Name of the app

  • version string Version of the app

  • aliases array of strings List that includes the version and all tags of this app by which the app can be addressed using "app-<name>/<alias>"

  • createdBy string ID of the user who created the app

  • created timestamp When the app was created

  • modified timestamp When this app was last modified

  • installed boolean Whether the requesting user has installed the app

  • openSource boolean Whether the app is open-source (and its resources container is accessible by all members of authorizedUsers)

  • ignoreReuse boolean Whether job reuse is disabled by default for the app

  • deleted boolean Whether the app has been deleted

  • installs int Number of current installations (includes developers)

  • isDeveloperFor boolean Whether the requesting user has developer permissions for the app 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 app; if the string "PUBLIC" is present, then all users can access this app

  • regionalOptions mapping Mapping that contains the regional configurations for this app.

    • key Region name (e.g., "aws:us-east-1", "azure:westus"). Note that the existence of a region here indicates that this app may be run in this region, and that absence of a region indicates otherwise.

    • value mapping Mapping of the configuration of this app in the corresponding region, with the following key-value pairs:

      • applet string ID of the underlying applet of this app in the corresponding region.

      • resources string ID of the resources container of this app in the corresponding region.

      • pricingPolicy mapping or unset Unset if the app will be billed based on the compute cost in the region, or if the app has been deleted; otherwise, it is a mapping that describes how the app will be billed. This field can only be set by DNAnexus administrators. Keys/values may include

        • unit string The unit that will be billed (e.g. "run" for a single run of the app)

        • unitPrice number Price in dollars of the unit to be billed

  • httpsApp mapping HTTPS app configuration

    • shared_access string HTTPS access restriction for this job

    • ports array of integers Ports that are open for inbound access

    • dns mapping DNS configuration for the job

If the app is published:

  • published timestamp Time at which this app was published

If the app has not been deleted:

  • title string Freeform name

  • summary string A one-line description of the app

  • description string A long description of the app, formatted in Markdown, to be displayed on the app's detail page

  • details mapping or array Contents of the app’s details

  • categories array of strings List of categories the app belongs to

  • lineItemPerTest boolean (optional, default false) Whether the final invoice will include a line item for each execution of this app. The text of the line will be determined by the value given as invoiceMetadata when calling /app-xxxx[/yyyy]/run if present and will otherwise contain some basic metadata about the job (including the job's name, ID, and name of the app run). At this time, this field can only be set by DNAnexus administrators.

  • access mapping The access requirements of the app

  • inputSpec array of mappings The input specification of the app

  • outputSpec array of mappings The output specification of the app

  • dxapi string The version of the API used by the encapsulated applet

  • runSpec mapping The run specification of the app, without the code field (use the /app-xxxx/get method for obtaining the source code)

The following fields are included by default (but can be disabled using fields):

  • treeTurnaroundTimeThreshold integer or null The turnaround time threshold (in seconds) for trees (specifically, root executions) that run this executable. See Job Notifications for more information about turnaround time and managing job notifications.

A license is required to use the jobNotifications feature. Contact sales@dnanexus.com to enable jobNotifications.

Deprecated fields:

  • region string Arbitrarily selected name of one of the regions in which this app may be run.

  • applet string ID of the underlying applet of this app in region.

  • resources string ID of the resources container of this app in region (present only if the app has not been deleted).

Errors

  • InvalidInput

    • Input is not a hash, or fields if present, is not a hash or has a non-boolean key

  • ResourceNotFound

    • The specified app does not exist

  • PermissionDenied

    • The requesting user must be represented in the access list or must be one of the app's developers; if the latter, a full scope token or one with developer access is required

    • If the app is unpublished, the requesting user must be one of the app's developers, and a full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/install

Specification

Installs the app into the user’s account. For apps that do not require additional terms of service or billing agreements, this serves mostly as a bookmarking functionality. Once installed, the user can run any version of the app.

Inputs

  • None

Outputs

  • name string The app name (e.g. "bwa")

Errors

  • InvalidState

    • App object specified has been deleted or is not yet published

  • PermissionDenied

    • The requesting user must be represented in the access list or must be one of the app's developers; if the latter, a full scope token is required

    • If the app is unpublished, the requesting user must be one of the app's developers, and a full scope token is required

API method: /app-xxxx[/yyyy]/uninstall

Specification

Uninstalls the app from the user’s account. If it was not originally installed or the app does not (or no longer) exists, then this does not throw an error.

Note that developers can uninstall an app, but they will always still be able to run it by virtue of being a developer.

Inputs

  • None

Outputs

  • name string The app name (e.g. "bwa")

Errors

  • PermissionDenied

    • The requesting user must be represented in the access list or must be one of the app's developers; if the latter, a full scope token is required

    • If the app is unpublished, the requesting user must be one of the app's developers, and a full scope token is required

API method: /app-xxxx[/yyyy]/get

Specification

Returns the full specification of the app along with some of the usual fields returned in /app-xxxx/describe.

Inputs

Outputs

  • Same as the output for /app-xxxx/describe, with the following exception:

  • runSpec mapping The full run specification of the app, including the field code containing the source code

Errors

  • InvalidInput

    • Input is not a hash, or fields if present, is not a hash or has a non-boolean key

  • ResourceNotFound

    • The app does not exist

  • InvalidState

    • The app has been deleted

  • PermissionDenied

    • Requestor must have VIEW access into the resources container, i.e. either a developer of the app or a job running the app

API method: /app-xxxx[/yyyy]/run

Specification

Run the specified app.

Inputs

  • name name (optional, default is the app's title if set and otherwise the app's name) Name for the resulting job

  • input mapping Input that the app is launched with

    • key Input field name (as it appears in the input specification of the app)

    • value Input field value

  • dependsOn array of strings (optional) List of job, analysis and/or data object IDs; the app will not begin running any of its entry points until all jobs and analyses listed have transitioned to the "done" state, and all data objects listed are in the "closed" state

  • 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 applet will be run (i.e., the project context). If invoked with the detach: true option, then the detached job will run 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 will be cloned into the temporary workspace of the invoking job. See The Project Context and Temporary Workspace for more information.

A license is required to launch detached executions. Contact DNAnexus Sales for more information.

  • folder string (optional, default "/") The folder into which objects output by the job will be placed. If the folder does not exist when the job completes, the folder (and any parent folders necessary) will be created. The folder structure that output objects reside in is replicated within the target folder, e.g. if folder is set to "/myJobOutput" and the job outputs an object which is in the folder "/mappings/mouse" in the workspace, the object is placed into "/myJobOutput/mappings/mouse".

  • tags array of strings (optional) Tags to associate with the resulting job

  • properties mapping (optional) Properties to associate with the resulting job

    • key Property name

    • value string Property value

  • details mapping or array (optional, default { }) JSON object or array that is to be associated with the job

  • systemRequirements mapping (optional) Request specific resources for each of the executable's entry points; see the Requesting Instance Types section for more details

  • 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 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 thetimeoutPolicyByExecutable field in /applet-xxxx/run for more details.

  • executionPolicy mapping (optional) A collection of options that govern automatic job restart upon certain types of failures. The format of this field is identical to that of the executionPolicy field in the run specification supplied to /applet/new and can override part or all of the executionPolicy mapping found in the app's run specification (if present).

  • ignoreReuse boolean (optional) If true then no job reuse will by default for this applet. Takes precedence over value supplied for app-xxxx/new.

  • 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 job will be preserved for 3 days after the job either succeeds or fails.

  • invoiceMetadata mapping (optional) If the app has lineItemPerTest set to true, then the line item on the invoice will contain the key/value pairs provided here. If the app does not have lineItemPerTest set to true, then this field is ignored.

    • key Metadata key to provide on invoice

    • value string Metadata value to provide on invoice

  • allowSSH array of strings (optional, default [ ]) Array of IP addresses or CIDR blocks (up to /16) from which SSH access will be allowed to the user by the worker running this job. Array may also include '*' which is interpreted as the IP address of the client issuing this API call as seen by the API server. See Connecting to Jobs for more information.

  • debug mapping (optional, default { }) Specify debugging options for running the executable; this field is only accepted when this call is made by a user (and not a job)

    • debugOn array of strings (optional, default [ ]) Array of job errors after which the job's worker should be kept running for debugging purposes, offering a chance to SSH into the worker before worker termination (assuming SSH has been enabled). This option applies to all jobs in the execution tree. Jobs in this state for longer than 2 days will be automatically terminated but can be terminated earlier. Allowed entries include "ExecutionError", "AppError", and "AppInternalError".

  • singleContext boolean (optional) If true then the resulting job and all of its descendants will only be allowed to use the authentication token given to it at the onset. Use of any other authentication token will result 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.

  • nonce string (optional) Unique identifier for this request. Ensures that even if multiple requests fail and are retried, only a single job is created. For more information, see Nonces.

  • 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 job will be detached from the creator job and will appear as a typical root execution. A failure in the detached job will not cause a termination of the job from which it was created and vice versa. Detached job will inherit neither the access to the workspace of its creator job nor the creator job's priority. Detached job's access permissions will be the intersection (most restricted) of access permissions of the creator job and the permissions requested by the detached job's executable. To launch the detached job, creator job must have CONTRIBUTE or higher access to the project in which the detached job is launched. Additionally, the billTo of the project in which the creator job is running must be licensed to launch detached executions.

A license is required to launch detached executions. Contact DNAnexus Sales for more information.

  • rank integer (optional) An integer between -1024 and 1023, inclusive. The rank indicates the priority in which the executions generated from this executable will be processed. The higher the rank, the more prioritized it will be. If no rank is provided, the executions default to a rank of zero. If the execution is not a root execution, it will inherit its parent's rank.

A license is required to use the Job Ranking feature. Contact DNAnexus Sales for more information.

  • costLimit float (optional) The limit of the cost that this execution tree should accrue before termination. This field will be ignored if this is not a root execution.

  • headJobOnDemand boolean (optional) If true, then the resulting master job will be allocated to an on-demand instance, regardless of its scheduling priority. All of its descendent jobs (if any) inherit its scheduling priority, and their instance allocations are independent from this option. This option overrides the settings in the app’s headJobOnDemand (if any).

  • preserveJobOutputs mapping (optional, default is null). 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.

    When a non-jobReused job in the root execution tree launched with non-null preserveJobOutputs enters "done" state, all cloneable objects (e.g. files, records, applets, closed workflows, but not databases) referenced by the $dnanexus_link in the job's output field will be cloned to the project folder described by preserveJobOutputs.folder, unless the output objects already appear elsewhere in the project. If the folder specified by preserveJobOutputs.folder does not exist in the project, the system will create the folder and its parents. As the root job or root analysis' stages complete, the regular outputs of the root execution will be moved from preserveJobOutputs.folder to the regular output folder(s) of the root execution. So if you [1] run your root execution without the preserveJobOutputs option to completion, some root execution outputs will appear in the project in the root execution's output folder(s). 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 [1] at completion of the root execution, while 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)

    • valuepath_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 will be 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. path_to_folder value of "" (i.e. empty string) will preserve job outputs in the folder described by root execution's folder field. If the preserveJobOutputs mapping does not have a folder key, the system will use the default folder value of "intermediateJobOutputs" (i.e. "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 very large (>450K) number of files.

A license is required to usepreserveJobOutputs. Contact DNAnexus Sales for more information.

  • detailedJobMetrics boolean Requests detailed metrics collection for jobs if set to true. The default value for this flag is project billTo's detailedJobMetricsCollectDefault policy setting or false if org default is not set. This flag can be specified for root executions and will apply 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 here.

A license is required to use detailedJobMetrics. Contact DNAnexus Sales for more information.

Outputs

  • id string ID of the created job (i.e. a string in the form "job-xxxx").

Errors

  • ResourceNotFound

    • The specified app or project context does not exist, or one of the IDs listed in dependsOn does not exist).

  • PermissionDenied

    • The requesting user must be represented in the access list or must be one of the app's developers; if the latter, a full scope token or one with developer access is required.

    • If the app is unpublished, the requesting user must be one of the app'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 app.

    • CONTRIBUTE access to the project context is required unless called by a job.

    • VIEW access is required for any objects listed in dependsOn and for the project contexts of any jobs listed in dependsOn.

    • The user has too many nonterminal (running, runnable, etc.) jobs and must wait for some to finish before creating more; the default limit is 65,536 jobs.

    • When specifying allowSSH or debug options, the user must be one of the app's developers, or the app must have the openSource field set to true.

    • If rank is provided and the billTo does not have license feature executionRankEnabled 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.

  • InvalidInput

    • An invalid link syntax appears in the input

    • The input does not satisfy the app’s input specification

    • All data object inputs that are specified directly 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.

    • allowSSH accepts only IP addresses or CIDR blocks up to /16

    • A nonce was reused in a request but some of the other inputs had changed signifying a new and different request

    • A nonce may not exceed 128 bytes

    • The billTo of the job's project must be licensed to start detached executions when invoked from the job with detach: true argument.

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

    • 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}$/

  • InvalidState

    • Some input to the app is not in the "closed" state

    • Some execution in dependsOn has already failed or been terminated

    • The project context's region is not among the enabled regions of the app

API method: /app-xxxx[/yyyy]/delete

Specification

Mark an app version as deleted. A deleted app can no longer be run, modified, nor published. This state is reflected in the output of describe. The associated resources container is made inaccessible. Any non-default tags associated with this app are invalidated and do not refer to any version of the app.

If this is the final or only version of the app, the app will also be uninstalled for all users.

Inputs

  • None

Outputs

  • id string ID of the app (of the form "app-<hash id>")

Errors

  • PermissionDenied

    • User must be the user who created the app

    • A full scope token or one with developer access is required

  • InvalidState

    • If an app has multiple versions, all other versions must be deleted before an app with the "default" can be deleted

API method: /app-xxxx[/yyyy]/addDevelopers

Specification

Adds developers (users and/or orgs) to the app. Additionally, all new user developers will automatically have the app installed to their accounts.

If the requesting user is not a developer of the app, but they are the billTo of the app or the billTo of the app is an org and the user is an ADMIN of that org, then the user may invoke this method to grant themself, and only themself, developer access to the app.

Inputs

  • developers array of strings List of user and/or org IDs that will be

    added as developers

Outputs

  • name string The app name (e.g. "bwa")

Errors

  • ResourceNotFound

    • Specified app does not exist

    • A specified user does not exist

  • InvalidInput

    • If the requesting user is not a developer of the app and is or administers the billTo of the app, then developers may only contain the ID of the requesting user

  • PermissionDenied

    • The requesting user must be a developer of the app, or they must be or administer the billTo of the app

    • If the requesting user is a developer of the app, 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 app but is or administers the billTo of the app, then the user must have a full scope token

API method: /app-xxxx[/yyyy]/listDevelopers

Specification

List the developers of the app

Inputs

  • None

Outputs

  • developers array of strings List of user and/or org IDs that

    are developers

Errors

  • ResourceNotFound

    • The specified app does not exist

API method: /app-xxxx[/yyyy]/removeDevelopers

Specification

Remove a list of developers from the app. Attempting to remove a user or org who is not listed as a developer will not throw an error. If the billing account of the app is a user ID, then the developer access of that user may not be revoked.

Inputs

  • developers array of strings list of user and/or org IDs that will be

    removed as developers

Outputs

  • name string the app name (e.g. "BWA")

Errors

  • ResourceNotFound

    • The specified app does not exist

  • InvalidInput

    • The billing account of the app is a user ID and developers contains that user ID

  • PermissionDenied

    • User must be a developer of the app

    • A full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/addAuthorizedUsers

Specification

Add users and/or org IDs to the access list.

Inputs

  • authorizedUsers array of strings List of user and/or org IDs

    to add to the access list.

Outputs

  • name string The app name (e.g. "BWA")

Errors

  • ResourceNotFound

    • A specified app or user 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 app

    • 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 available to all users of the DNAnexus Platform, please contact us at support@dnanexus.com.

API method: /app-xxxx[/yyyy]/listAuthorizedUsers

Specification

List the users and/or orgIDs on the access list for the app. The string "PUBLIC" represents the set of all users.

Inputs

  • None

Outputs

  • authorizedUsers array of strings List of user and/or org IDs that can describe and run the app; if "PUBLIC" is present, this means all users can access the app

Errors

  • ResourceNotFound

    • The specified app does not exist

  • PermissionDenied

    • The requesting user must be represented in the access list or must be one of the app's developers; if the latter, a full scope token or one with developer access is required.

API method: /app-xxxx[/yyyy]/removeAuthorizedUsers

Specification

Remove a list of user and/or org IDs from the access list for the app. Removing an entity that is not currently listed in the access list does not throw an error.

Inputs

  • authorizedUsers array of strings List of user and/or org IDs to remove from the access list

Outputs

  • name string The app name (e.g. "bwa")

Errors

  • ResourceNotFound

    • A specified app 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 app

    • A full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/addCategories

Specification

Add categories for the app.

Inputs

  • categories array of strings List of categories to add the app to

Outputs

  • name string The app name (e.g. "bwa")

Errors

  • ResourceNotFound

    • A specified app 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 app

    • A full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/listCategories

Specification

List the categories that an app is a member of. Anyone can list the categories of a published app.

Inputs

  • None

Outputs

  • categories array of strings List of categories the app belongs

    to

Errors

  • ResourceNotFound

    • The specified app does not exist

  • PermissionDenied

    • The requesting user must be represented in the access list or must be one of the app's developers; if the latter, a full scope token or one with developer access is required

    • If the app is unpublished, the requesting user must be one of the app's developers, and a full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/removeCategories

Inputs

  • categories array of strings List of categories to remove the app from

Outputs

  • name string The app name (e.g. "bwa")

Errors

  • ResourceNotFound

    • A specified app 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 app

    • A full scope token or one with developer access is required

API method: /app-xxxx[/yyyy]/isCompatible

Specification

Checks whether the app object specified in the URL can replace the app object specified in the otherVersion field of the input in a workflow without user intervention.

The following changes to the input and output specifications of the app specified in otherVersion can be made while remaining compatible:

  • Changing any label or help fields

  • Setting optional to true for any input field

  • Setting default to some valid value for any input field

  • Adding additional optional inputs

  • Adding additional outputs

The following changes result in incompatibility:

  • Making an optional input required

  • Adding a required input

  • Renaming or changing the class or type specification for an existing input or output field name

  • Removing an output

Inputs

  • otherVersion string An app identifier (see the list of Valid App Identifiers for allowed examples) with which to test compatibility; this app object can be a deleted version

Outputs

  • id string ID of the app object checked for compatibility

  • otherVersion string ID of the app object specified as otherVersion in the input

  • compatible boolean True if it is compatible and false otherwise

Errors

  • ResourceNotFound

    • One of the specified apps does not exist

  • InvalidInput

    • Input is not a hash, otherVersion is not present or is not a nonempty string

  • PermissionDenied

    • The requesting user must be represented in the access list or must be one of the app's developers; if the latter, a full scope token or one with developer access is required.

    • If the app is unpublished, the requesting user must be one of the app's developers, and a full scope token or one with developer access is required.

  • InvalidState

    • The app object in the URL has already been deleted

API method: /app-xxxx[/yyyy]/validateBatch

Specification

This API call verifies that a set of input values for a particular app can be used to launch a batch of jobs in parallel.

Batch and common inputs:

batchInput: mapping of inputs corresponding to batches. The nth value of each array corresponds to nth execution of the app. Including a null value in an array at a given position means that the corresponding app input field is optional and the default value, if defined, should be used. E.g.:

{
  "a": [{$dnanexus_link: "file-xxxx"}, {$dnanexus_link: "file-yyyy"}, ....],
  "b": [1,null, ...]
}

commonInput: mapping of non-batch, constant inputs common to all batch jobs, e.g.:

{
  "c": "foo"
}

File references:

files: list of files (passed as $dnanexus_link references), must be a superset of files included in batchInput and/or commonInput e.g.:

[
  {$dnanexus_link: "file-xxxx"},
  {$dnanexus_link: "file-yyyy"}
]

Output: list of mappings, each mapping corresponds to an expanded batch call. Nth mapping contains the input values with which the nth execution of the app will be run, e.g.:

[
  {"a": {$dnanexus_link: "file-xxxx"}, b: 1, c: "foo"},
  {"a": {$dnanexus_link: "file-yyyy"}, b: null, c: "foo"}
]

It performs the following validation:

  • the input types match the expected app input field types,

  • provided inputs are sufficient to run the app,

  • null values are only among values for inputs that are optional or have no specified default values,

  • all arrays of batchInput are of equal size,

  • every file referred to in batchInputs exists in files input.

Inputs

  • batchInput mapping Input that the app is launched with

    • key Input field name. It must be one of the names of the inputs defined in the app input specification.

    • value Input field values. It must be an array of fields.

  • commonInput mapping (optional) Input that the app is launched with

    • key Input field name. It must be one of the names of the inputs defined in the app input specification.

    • value Input field values. It must be an array of fields.

  • files list (optional) Files that are needed to run the batch jobs, they must be provided as $dnanexus_links. They must correspond to all the files included in commonInput or batchInput.

Outputs

  • expandedBatch list of mappings Each mapping contains the input values for one execution of the app in batch mode.

Errors

  • InvalidInput

    • Expected batchInput to be a JSON object

    • Expected commonInput to be a JSON object

    • Expected files to be an array of $dnanexus_link references to files

    • The batchInput field is required but empty array was provided

    • Expected the value of batchInput for an app input field to be an array

    • Expected the length of all arrays in batchInput to be equal

    • The app input field value must be specified in batchInput

    • The app input field is not defined in the input specification of the app

    • All the values of a specific batchInput field must be provided (cannot be null) since the field is required and has no default value

    • Expected all the files in batchInput and commonInput to be referenced in the files input array

Last updated

Copyright 2024 DNAnexus