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[/yyyy]/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[/yyyy]/delete 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.

List of App API Methods

Valid App Identifiers

In the API methods operating on app instances, apps can be represented by any of the following in the URL:

  • app-<hash id>, e.g. app-B7Z2QZ00GqgvQbfB6J7Q0003
  • app-<name> (equivalent to app-<name>/default), e.g. app-bwa
  • app-<name>/<version>, e.g. app-bwa/1.0.0
  • app-<name>/<tag>, e.g. app-bwa/default

Note that using the form app-<hash id>/<version or tag> will be rejected. This is because a hash ID indicates a unique, immutable version which could conflict with the given version or tag.

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

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

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.
    • 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
  • 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.
    • 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 (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, 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)
  • 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.

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
  • pricingPolicy mapping or null Null if the app is only billed based on compute cost; otherwise, it is a hash with parameters describing how running the app will be billed. This field can only be set by DNAnexus administrators. Key/values may include the following:
    • 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
  • 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[/yyyy]/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 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[/yyyy]/describe.

Inputs

Outputs

  • Same as the output for /app-xxxx[/yyyy]/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 stages 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 when called by a user; cannot be provided when called by a job) ID of the project in which the app will be run, i.e. the project context; any output objects will be placed into this project. If this method is called by a job (and therefore this field is not present), the project context of the new job is set to that of the job making the request, but the output objects will be placed in the temporary workspace of the job. See The Project Context and Temporary Workspace for more details.
  • 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 stages; see the Requesting Instance Types section 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).
  • timeoutPolicyByExecutable mapping (optional) Similar to the timeoutPolicyByExecutable field supplied to /applet-xxxx/run
  • delayWorkspaceDestruction boolean (optional, default false) Whether the temporary workspace created for the resulting job should be kept around 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 hostnames (translated into CIDR blocks) or hostmasks from which SSH access will be allowed to the user by the worker running this app's job(s). 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".
  • 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.

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
  • 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.
    • 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
  • 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 he is the billTo of the app or the billTo of the app is an org and he is an ADMIN of that org, then the user may invoke this method to grant himself, and only himself, 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 he 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)

Last edited by pnguyen, 2017-06-13 14:50:57

 Feedback