Publishing Your BaseSpace App
There are many components to publishing an app. This document contains the follow sections:
When to Submit your App for Review
Once you are ready to make your application available to other users in BaseSpace, you can submit your app for review. There are a couple scenarios where you may want to do this:
- Brand new app: will go through the full review process
- New app version of an existing app: will go through an expedited review process, each new app version must be submitted and reviewed before it can be published
- Make app available for beta customers: if you would like to do beta testing with your app with a list of BaseSpace customers, your app will need to be submitted and reviewed to allow this functionality
Note: Once an app is published, you will no longer be able to change any values except What's New. If you would like to change anything else, please contact basespace-apptest@illumina.com
How to Submit your App for Review
Apps can be submitted for review through the developer portal. The app is ready to be reviewed once the App Publishing Requirements are met. Once the app is ready to be reviewed, simply follow these instructions to submit it for review:
- Navigate to the Developer Portal
- Click My Apps
- Select your app from the list
- Click Submit for Review
If some information was not properly entered, you will see some validation error messages now which should be resolved before submitting again.
The app is now in the Submitted state and is being reviewed by the BaseSpace team
- Send any inquiries about the app review process/status to basespace-apptest@illumina.com.
Note: Once an app version is published, you may no longer change any values for that app except the What's New content.
Requirements for Publishing an App
Long Description Content and Format
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.
For Native Apps - Docker Image Digest
WHen publishing a Native app, you are required to provide some additional information in your callbacks.js script in the Form in order 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.
A digest is required for all Native applications that are submitted for review to BaseSpace. In general, a new version of the app should be created whenever a digest is updated. This new app version will have to go through an expedited review process similar to the original app review.
Technical Checklist
These are the technical requirements for app publishing. Each app that is submitted will undergo internal review before it is published, please ensure that each of the following items have been addressed prior to submission.
| BaseSpace App Review 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. |
||||||
Valid SSL Certificate
An app should have a valid SSL Certificate on its site. The user should not be confronted with a browser SSL warning.
Test on Public BaseSpace Datasets
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
Test with Multiple Users
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.
Appropriate OAuth Flow
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. An app requesting greater permission than it needs to function will not be published. The more permissions requested the less likely the user will grant the rights.
Single Sign On
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.
Email opt-in
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.
Sharing User Data and Multi Tenancy
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.
Storing Data
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.
Returning to BaseSpace
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.
Hide the Access Token
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=metato 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.
Handle Incompatible Datasets
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.
Writing Back to BaseSpace
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.
Inappropriate Content
An app should never contain any inappropriate content. This includes, but is not limited to, inappropriate screenshots, icons, and descriptions.
Business Requirements
The app must adhere to the terms outlined in the BaseSpace Developer and Publishing Agreement.
No co-branding
The app is not allowed to use any Illumina or BaseSpace logos without explicit approval from Illumina.
No unsolicited marketing or advertising
The app cannot market any goods for sale that are not available on BaseSpace as a BaseSpace App.
BaseSpace is RUO Only
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.
EULA and Privacy Policy
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:
- EULA is between App and User and not Illumina, and that App is solely responsible for the application.
- Clear description of the Application, its intended use, and performance specifications, including without limitations explaining where, how and when the BaseSpace User's data will be transmitted outside of BaseSpace if at all.
- Research Use Only. Statement that the Application is for research use only purposes and is not intended to be used in the diagnosis, treatment, or care of persons or animals.
- Performance of the Application. Statement that Illumina and its affiliates are not responsible for the content of, use of, or performance of the Application.
- Warranty. The warranty, if any, you provide or statement of no warranty.
- Export Restrictions. Statement that Application may be subject to export laws and regulations.
- Location. Jurisdiction where User's data and any personal information may be processed if not occurring within BaseSpace.
- Privacy Policy. Link or display privacy policy that applies to the Application.
- Use of Data. Description of how you may utilize a BaseSpace User's data, unless addressed in Privacy Policy.
- Third Party Beneficiary. You and BaseSpace User must acknowledge and agree that Illumina and its affiliates are Third Party beneficiaries under the EULA.
Providing Support for Users
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, this will be verified during the review process.