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 [email protected]
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
.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.
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 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.
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.
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 ifinitializeFrom
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 ifinitializeFrom
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 ifapplet
is specified for one region inregionalOptions
, 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 ifresources
is specified for one region inregionalOptions
, then it must be specified for all regions.IfregionalOptions
andinitializeFrom
are both specified, thenregionalOptions
must contain all regions, and only those regions, in whichinitializeFrom
is enabled. That is, the set of regions in which this app will be enabled will be exactly the same as the set in whichinitializeFrom
is enabled.
initializeFrom
string (required ifapplet
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 theinitializeFrom
app object’s resources container; it is not functionally the same as providing the same value of the fieldresources
as before (the project contents or data objects may have changed in the meantime).
name
string (optional ifinitializeFrom
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 fromapplet
orinitializeFrom
as applicable; if no (or an empty) title is found from those options, thenname
is used as the title.summary
string (optional) A one-line description for the app. If not provided, inherited fromapplet
orinitializeFrom
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 fromapplet
orinitializeFrom
as applicable.developerNotes
string (optional) More advanced documentation for the app. If not provided, inherited fromapplet
orinitializeFrom
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 appversion
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 usersignoreReuse
boolean (optional, default false) If true then no job reuse will occur by default for this app.billTo
string (optional, default isbillTo
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 withallowBillableActivities
permission. If this is a subsequent version of an existing app, thenbillTo
must be the same asbillTo
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.
Deprecated fields:
applet
string (required if neitherinitializeFrom
norregionalOptions[r].applet
(for any region namer
) 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 ifregionalOptions
is specified. Ifapplet
is specified, thenregionalOptions
is not required above. If neitherregionalOptions[r].applet
(wherer
is a region name) norinitializeFrom
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 byapplet
. This field will be ignored ifregionalOptions
is specified.
Outputs
id
string ID of this app (of the formapp-<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
andinitializeFrom
are both specified, thenregionalOptions
must contain exactly the regions in which the app version denoted byinitializeFrom
is enabled. - If
regionalOptions
is specified, then it must be non-empty. - If
applet
(orresources
) is specified for one region inregionalOptions
, then it must be specified for all regions. - The applet denoted by
regionalOptions[r].applet
(wherer
is a region name) must reside in the region denoted byr
. - Only one of
initializeFrom
orapplet
may be specified. version
(if specified) is already in use by an existing version of this app, or is atag
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
(wherer
is a region name) is specified for at least oner
, then the input, output, and run specifications of all specified applets must be equivalent, as defined above. - If
regionalOptions[r].resources
(wherer
is a region name) is specified for at least oner
, then all of the objects denoted byr.resources
must reside in the region denoted byr
. - 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 inlive
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 withallowBillableActivities
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'sbillTo
- SpendingLimitExceeded
billTo
has reached its spending limit
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 ifapplet
is specified in one region inregionalOptions
, 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 ifresources
is specified for one region inregionalOptions
, 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 summarydescription
string (optional) The app’s descriptiondeveloperNotes
string (optional) Advanced documentation for the appdetails
array or mapping (optional) Any conformant JSON (i.e. a JSON object or array, per RFC4627), which will be stored with the appopenSource
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
Deprecated fields:
applet
string (optional) Recreate the app using the provided applet ID. This field will be ignored ifregionalOptions
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 ifregionalOptions
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 inlive
status. - If
applet
(orresources
) is specified for one region inregionalOptions
, then it must be specified for all regions. - The applet denoted by
regionalOptions[r].applet
(wherer
is a region name) must reside in the region denoted byr
. - If
regionalOptions[r].applet
(wherer
is a region name) is specified for at least oner
, then the input, output, and run specifications of all specified applets must be equivalent, as defined above. - If
regionalOptions[r].resources
(wherer
is a region name) is specified for at least oner
, then all of the objects denoted byr.resources
must reside in the region denoted byr
.
- 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
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 appversion
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
Specification
Remove the requested aliases of "app-<name>/<tag>"
Inputs
tags
array of strings List of tags to remove from all versionsof 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
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
Specification
Describe the app.
Inputs
fields
mapping (optional) Restrict the output of this method to have only the provided keys in this field; theinputSpec
andoutputSpec
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
andoutputSpec
, 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 appversion
string Version of the appaliases
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 appcreated
timestamp When the app was createdmodified
timestamp When this app was last modifiedinstalled
boolean Whether the requesting user has installed the appopenSource
boolean Whether the app is open-source (and itsresources
container is accessible by all members ofauthorizedUsers
)ignoreReuse
boolean Whether job reuse is disabled by default for the appdeleted
boolean Whether the app has been deletedinstalls
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 accessauthorizedUsers
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 appregionalOptions
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 includeunit
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 configurationshared_access
string HTTPS access restriction for this jobports
array of integers Ports that are open for inbound accessdns
mapping DNS configuration for the jobhostname
string if specified, the URL to access this job in the browser will be "https://hostname.dnanexus.cloud" instead of the default "https://job-xxxx.dnanexus.cloud"
If the app is published:
published
timestamp Time at which this app was published
If the app has not been deleted:
title
string Freeform namesummary
string A one-line description of the appdescription
string A long description of the app, formatted in Markdown, to be displayed on the app's detail pagedetails
mapping or array Contents of the app’s detailscategories
array of strings List of categories the app belongs tolineItemPerTest
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 asinvoiceMetadata
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 appinputSpec
array of mappings The input specification of the appoutputSpec
array of mappings The output specification of the appdxapi
string The version of the API used by the encapsulated appletrunSpec
mapping The run specification of the app, without thecode
field (use the /app-xxxx/get method for obtaining the source code)
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 inregion
.resources
string ID of the resources container of this app inregion
(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
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
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
Specification
Returns the full specification of the app along with some of the usual fields returned in /app-xxxx/describe.
Inputs
Outputs
runSpec
mapping The full run specification of the app, including the fieldcode
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
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 jobinput
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" stateproject
string (required if invoked by a user; optional if invoked from a job withdetach: true
option; prohibited when invoked from a job withdetach: false
) The ID of the project in which this applet will be run (i.e., the project context). If invoked with thedetach: true
option, then the detached job will run under the providedproject
(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.
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. iffolder
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 jobproperties
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 jobsystemRequirements
mapping (optional) Request specific resources for each of the executable's entry points; see the Requesting Instance Types section for more detailsexecutionPolicy
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 theexecutionPolicy
field in the run specification supplied to /applet/new and can override part or all of theexecutionPolicy
mapping found in the app's run specification (if present).timeoutPolicyByExecutable
mapping (optional) Similar to thetimeoutPolicyByExecutable
field supplied to /applet-xxxx/run​ignoreReuse
boolean (optional) If true then no job reuse will by default for this applet. Takes precedence over value supplied forapp-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'sdelayWorkspaceDestruction
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 haslineItemPerTest
set to true, then the line item on the invoice will contain the key/value pairs provided here. If the app does not havelineItemPerTest
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, andsingleContext: 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.
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.
costLimit
float (optional) The limit of the cost this app should accrue before termination. This field will be ignored if app is not a root execution.headJobOnDemand
boolean (optional) If true, then the resulting root 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’sheadJobOnDemand
(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-nullpreserveJobOutputs
enters "done" state, all cloneable objects (e.g. files, records, applets, closed workflows, but not databases) referenced by the$dnanexus_link
in the job'soutput
field will be cloned to the project folder described bypreserveJobOutputs.folder
, unless the output objects already appear elsewhere in the project. If the folder specified bypreserveJobOutputs.folder
does not exist in the project, the system will create the folder and its parents.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 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'sfolder
field.path_to_folder
value of""
(i.e. empty string) will preserve job outputs in the folder described by root execution'sfolder
field. If thepreserveJobOutputs
mapping does not have afolder
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.
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 independsOn
- 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
ordebug
options, the user must be one of the app's developers, or the app must have theopenSource
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 andbillTo
of the project where execution is attempted does not have preserveJobOutputs license.
- 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 withdetach: 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.
- 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
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
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 beadded 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, thendevelopers
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
Specification
List the developers of the app
Inputs
- None
Outputs
developers
array of strings List of user and/or org IDs thatare developers
Errors
- ResourceNotFound
- The specified app does not exist
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 beremoved 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
Specification
Add users and/or org IDs to the access list.
Inputs
authorizedUsers
array of strings List of user and/or org IDsto 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 [email protected]
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.
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
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
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 belongsto
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
Inputs
categories