Illumina no longer supports the submission and publication of applications for use by Illumina BaseSpace users. However, developers are still welcome to create and use apps for private use:
If you would like to discuss the development and publication of a potential application that fulfills an unmet need in omics, please contact Business Development at businessdevelopment@illumina.com.
Though publishing of native apps is no longer supported, the following requirements reflect best practices for private app development.
The Long Description field allows you to enter information in the markdown format.
The Long Description field for the app should follow this template:
App Inputs
====
This section includes a list of items:
* *Italics Item 1*
* **Bold Item 2**
* ***Italics and Bold Item 3***
* Item 4
These are the inputs for this application.
App Outputs
====
This section will list what the output data will be and what the user can expect for the results.
Known App Limitations
====
This section will list all known limitations in the application, e.g. genomes, builds, etc.
Link to a Demo Dataset
====
This section includes a link to a URL for more information: [This is the hyperlinked text](https://the.target.url.com)
Each of these sections should be filled out for the app. For an example, checkout the Kraken Metagenomics app on BaseSpace.
The callbacks.js script in the Form can be used to lock down a specific version of a Docker image for the application. This is done by using the Docker image digests that are available for each docker image.
In order to list the digest for your Docker image, simply type the following
docker images --digests=true
This command will return your Docker images with the digest id listed as well.
Now, in order to properly lock down your Native app to a specific digest of a Docker image, simply add the digest to your containerImageId in the callback as follows:
containerImageId : "[repository_name]/[image_name]@[digest]"
So, for example:
containerImageId : "docker.illumina.com/basespace/fastqc@sha256:e4150ec096becbc55d8de22a62bc7a5b66db62eb125ad113945f7de6ba41d8a4"
This will ensure that the specific digest of the Docker image is used and any updates made to the Docker image past the point of this digest will be ignored when pulling this image for analysis.
In general, a new version of the app should be created whenever a digest is updated.
| BaseSpace App Technical Checklist | ||||||||
|---|---|---|---|---|---|---|---|---|
| Item Number | Title | Item Description | Help Links and Documentation | |||||
| 1 | Input Form or Input Data | A. The app should use the input form using the Forms Builder tool whenever possible to launch the app. B. The app must handle incompatible datasets and either filter them out or report issues to the user. This is easily handled via the input form. C. The app must use the Formbuilder tool to create a form that filters down possible input data to the specific type(s) that the app accepts and create/assign validation rules for the input form |
Formbuilder Documentation | |||||
| 2 | Error Handling and Status Reporting | A. The app does not crash, but if it does it should crash gracefully and inform the user of the error. If the error persists then the app will not pass. B. The app does not stall. C. The app must report errors or warnings to the user via the AppSession Status, StatusSummary, and Logs. |
For Non-Native Apps: the AppSession's Status should be changed to "Aborted" and the StatusSummary should be updated. The app can also write to the AppSession's Logs.Tail Property to update the Logs window. For Native Apps: Reporting in the Logs Window |
|||||
| 3 | Status Reporting | A. The app must report status back to the user via the AppSession Status, StatusSummary, and Logs. B. Upon successful completion of the analysis, the AppSession Status must be marked as Complete. Use the AppSessions API to change the Status of the AppSession and update the StatusSummary to the final state. |
For Non-Native Apps: the AppSession's StatusSummary should be updated periodically. The app can also write to the AppSession's Logs.Tail Property to update the Logs window. For Native Apps: Reporting in the Logs Window |
|||||
| 4 | OAuth Process (For Non-Native Apps) | A. The app should use the appropriate OAuth flow (device vs. web) for the type of application B. The app should request the minimal amount of scope to a user's data that is needed in order to run the app. C. The app should use the Pre-Authorized when Triggered from BaseSpace setting in Application Permission Settings in the app's Details page in the developer portal whenever possible. |
App Triggering from BaseSpace Obtaining Access Tokens BaseSpace Permissions |
|||||
| 5 | Uploading Results | A. The app must write results to a Project to which the user has write permission B. The app writes back results to the specified AppResult or Project if asked for user input C. The app must link the AppResults back to the AppSession, then set the AppSession's Status to Complete. |
For Non-Native Apps: Writing back to BaseSpace For Native Apps: Upload Results in Native Apps |
|||||
| 6 | Tagging Properties | A. The app must write Properties to the AppResult that is generated. If multiple AppResults are generated, Properties should be tagged to each that are specific to that data. At a minimum, the AppResult should be tagged with input Project, input AppResult(s), and input Sample(s.) B. The app must write Properties on the AppSession for all input and output items that were used for the app, including Samples, AppResults, and other form elements. This is done automatically if the Formsbuilder tool is used. |
For Non-Native Apps: Writing back to BaseSpace and Properties API Reference For Native Apps: Upload Results in Native Apps |
|||||
| 7 | Documentation and Support | A. The app provides documentation for the user and instructions for use. B. The app must state known limitations in its description C. The app must indicate its version in its reports and in the general GUI for the application D. If the app provides a support link, ensure that it has a phone number or an email address. |
||||||
| 8 | Security | A. The app must have a valid SSL certificate B. The app must never share the user's data with any external source C. The app should never expose access tokens to the user via UI, links, or URLs D. The app must be multi-tenant, e.g. multiple users can use the app at the same time but each user only has permission to their own data from BaseSpace E. Users should never see information about other user's data, usage, or patterns in the app unless the user explicitly grants the app permission to do so. F. The user's BaseSpace data must not be stored outside of BaseSpace. Any data that the app used from the user's BaseSpace account must be removed from any external site. G. The app should not redirect, divert, direct, or link to any products, applications, software, or service, excluding public data sources (e.g. PubMed) |
||||||
| 9 | Misc | A. The app must provide a link back to BaseSpace B. The app must have single-sign on. Users should not be asked to create new accounts in the app, they must be able to seamlessly use their BaseSpace credentials to automatically log into the app after launch. If the user logs out of the app, they must be taken back to BaseSpace. C. The app cannot contact the user directly without an opt-in by the user. The opt-in can be via a checkbox within the app or on the input form. D. The app must provide full functionality to the user regardless of the user's opt-in status. E. The app must select appropriate categories F. The app must provide one or more example dataset share links or links to public datasets for example input and output data for the app. |
||||||
An app should have a valid SSL Certificate on its site. The user should not be confronted with a browser SSL warning.
BaseSpace offers many publicly available datasets for developers to use to test their app. Some of these datasets are shared upon BaseSpace registration whereas others are shared through links in the BaseSpace Blog. Simply find the Runs and Project links for each dataset and share them.
Being shared a project will only give you READ and BROWSE access to the project, unless the project owner enables you as a Writer through BaseSpace.
The following Data Central page contains a full list of Publicly available datasets that you can gain access to in BaseSpace:
https://basespace.illumina.com/datacentral
In the app configuration page in the developer portal, developers are able to invite users to test the application before publication. In the "Authorize Test Users by Email" text box, simply type the email address of the BaseSpace user to invite and they will be automatically authorized to begin launching your app in BaseSpace.
Apps must be able to handle large volumes of launches and users.
All Non-Native applications should use the App Triggering from BaseSpace OAuth flow whenever possible. If an app is not using this OAuth flow, the Launch Permissions in the Edit page of the app in My Apps should all be unchecked and the app should use the workflow described in Obtaining Access Tokens. This eliminates the user being prompted with redundant OAuth dialogs.
In addition, apps that require multiple permissions through the Obtaining Access Tokens workflow should combine the scope whenever possible. Remember that READ contains BROWSE and WRITE contains READ and BROWSE.
An app should only request the level of permissions it needs to operate. For example, if an app does not write anything back to BaseSpace it should not request create projects or write scopes. The more permissions requested the less likely the user will grant the rights.
An app should never require the user to sign in or create an account once the app is launched--this should be done automatically. The only exception to this would be to link the incoming user's account to an existing account in the app but this does not need to get in the way of a user immediately getting some use out of the app.
After obtaining an access token, an app can use the access token with the method GET: users/current to get the user's id, email address, and name directly from the API. This information should be used to verify the user coming from BaseSpace and automatically create an account or sign in on the app.
If a user comes to your application directly and not by starting it via BaseSpace, you may authenticate the user through the use of an OAuth flow. Please refer to Authenticating and Getting User Information.
An app should never automatically opt the user into receiving any emails without receiving the user's explicit opt-in.
The app may use the email address to create a unique account, but the user must grant consent to the app to send any emails.
An app should never allow users to access another user's data without the user's permission. Any sharing of information that would violate the data sharing model in BaseSpace is not allowed without explicit permission from the user.
An app should support multiple users using the app concurrently. The users should not see any other users' data without explicitly sharing the data with specific users. Any data generated by the app or options saved in the app by a user should not be visible to other users.
An app should not keep copies of BaseSpace data locally. Any files that are downloaded or pulled from BaseSpace should be deleted after the user ends the app's session. The file(s) should then be re-requested should the user launch the app again on the same data.
An app must include a simple and consistent way to return to BaseSpace from the app. The destination may be the BaseSpace front page or to the page from which the user launched the app (this URI is available in the AppSession).
If the user logs out of the app inside of the app, they should be returned to BaseSpace. They should not be taken to a login page for the app.
An app should never expose the access token to the user in an obvious fashion. This includes areas such as inside of an email (which are often forwarded), included within a page URL that is often copy/pasted to other users, etc. Store the access token on your server and use a session cookie or similar technique to track the user. Don't use an access token as a means of tracking unique users.
When a user wishes to view or download a file, do not include the access token in the url. Instead, the following methods could be used:
Link to the app's web server and use the API method GET: files/{id}/content?redirect=meta to get the S3 URI.
Link without the access token, this will use the user's BaseSpace cookie to authenticate. Using this workflow, the user's cookie may expire after ~24 hours.
An app must have a mechanism to identify and ignore irrelevant or incompatible datasets. If an app is started with incompatible or invalid input, simply inform the user about what type if input is allowed.
Any app that generates result files should write those back to BaseSpace. For example, if a .bam or .vcf file was generated as a result of the analysis an app completed on a user's data, those files should be written back to BaseSpace in an AppResult within the same Project or in a Project chosen or created by the user. This requirement also applies to any report files that are generated via the app.
Sample and AppResult References
In addition, if any data from BaseSpace was used as input for the app, the input Sample or AppResult should be added in the References of the output AppResult otherwise the user will not see the results in BaseSpace. This workflow is described in the Writing Back to BaseSpace Guide.
Naming Convention
When writing back an AppResult to BaseSpace, the name of the AppResult should be meaningful for the User. For example, we suggest using the name of the Sample that was analyzed in the case of a single Sample input. This will ensure that the name of the AppResult in the UI will be user-friendly.
An app should never contain any inappropriate content. This includes, but is not limited to, inappropriate screenshots, icons, and descriptions.
The app must adhere to the terms outlined in the BaseSpace Developer and Publishing Agreement.
The app is not allowed to use any Illumina or BaseSpace logos without explicit approval from Illumina.
The app cannot market any goods for sale that are not available on BaseSpace as a BaseSpace App.
BaseSpace is a RUO only platform at the moment. In the future, this limitation may be raised, but for now the data in BaseSpace may only be used for research purposes. Please include the statement "This app is for RUO." in the app's Long Description and/or the app's EULA.
The app should provide its own End User License Agreement and Privacy Policy. There is no requirement for the Privacy Policy but we strongly encourage providing one.
The EULA should include the following information:
The app developer is required to provide support for their application in BaseSpace. Illumina is not responsible for supporting your App. Developers need to provide a valid support email address for their application.