Managing Your BaseSpace App

Before the particular version of an app is published, the developer has the ability to customize a large amount of content. In this section, the basics and best practices of app management in BaseSpace are described.

Release Notes

For any app, you have the option to provide release notes. For all new versions of apps in BaseSpace, we recommend that developers provide some content in Release Notes or What's New.

Release Notes should be restricted to only bug fixes and new features in a new app version.

This field is required, supports up to 4000 characters including spaces, and also supports markdown. This section cannot be changed once the app version is published.

What's New

A description of the latest information about app app since its publication. This section should primarily be used to notify users about a bug or issue with the current version or the app or if any pricing information or content has been updated in the current version.

This section is optional, supports up to 4000 characters, and supports markdown. This section can be changed even after an app version is published, along with pricing.

App Versions

BaseSpace offers the ability to add versions to your BaseSpace apps.

Apps should no longer include a version in its Name, all versioning should be done through the versioning functionality in the developer portal.

BaseSpace versions are setup in the following way:

[0-999].[0-999].[0-999]

The developer is free to determine how they want to represent minor and major versions for an app using this syntax. For example, you may have a few versions of an app including 1.0.0, 1.0.1, 1.1.1, 11.11.1, and so on.

In the developer portal, versions of applications can be automatically created using the following feature in the developer portal user interface:

After clicking the dialogue, you will be asked to enter an incremental version number for the new version of the app:

The app's version is listed for the end user in a few places:

  • The Input Form for an app

  • The App Overview page

When the user views the version from the dropdown menu in this view, they can also see the published status of the version (if it is not yet published and they have access.)

Note: All content for app name, company name, icons, screenshots, descriptions, release notes, what's new, documents, invited users, forms, and reports are per application version, so each new version of an application may have new content for any of the above fields. If you wish to change any of this content once the app is published, please contact basespace-apptest@illumina.com

Invited Users

While the application is unpublished, you can invite users in BaseSpace to try out the application. In the application's details tab in the developer portal, scroll down and you will find the Test Users section.

In this section, you may click the button to add users by their basespace account usernames (email addresses) to view your application.

Once added to the list, a user will be able to see your application in the BaseSpace UI at http://basespace.illumina.com/apps. The user will then be able to use your app.

App Types

The App Type for an app is very important, it can determine certain functionality for an app.

There are three types of apps in BaseSpace:

  • Web/Desktop Visualization
  • Web/Desktop Other
  • Native

Web/Desktop Visualization: This is a web or desktop application that does not write any data back to BaseSpace. Examples of visualization apps re genome browsers. AppSessions ("Analyses") for these apps are not displayed in the BaseSpace UI.

Web/Desktop Other: This is a general web and desktop application category, any applications that use the API or SDKs to function with BaseSpace fall into this category. Web applications are hosted outside of BaseSpace and that infrastructure is managed by the application developer.

Native: Native applications are command-line tools that run in the BaseSpace environment. When this option is selected, the callbacks.js template script is made available in the Form Builder for the app.

For more information about application types and how they vary please view the following documentation:

App Launch Locations

Besides launching the app from the Apps list page at http://basespace.illumina.com/apps, you can also specify two other areas where the app will be displayed to allow the user to launch from.

The first area is the Project Overview page, by selecting Projects. On this page, there is a Launch App dropdown menu that will list all of the apps that have this option selected. Once the user clicks on the app icon from here they would be taken to the app's input form to launch the app.

The second area is the Sample Details page, by selecting Samples. On this page, there is a Launch App dropdown menu as well that will list all of the apps that have this option selected. Once the user clicks on the app, they will be taken to the input form as usual.

Categories

There are some categories available for you to help classify your application. These categories are also available to the user and they can use them to filter down the list of apps to find the ones that are relevant to their research.

You may choose multiple categories for your application.

Design Guidelines

When an application has been thoroughly tested and is ready to appear on the BaseSpace App Store, it will go through the submittal process to become published. This process will require the developer to give detailed information about the app, if they have not already filled out these fields in My Apps. A few of these fields have limitations on them that are highlighted later in this document. These fields include:

  • App Name
  • Short Description
  • Long Description
  • Homepage URL
  • Redirect URI
  • Developer Name and Contact Information
  • App Icon
  • Screenshots
  • App Category
  • Type of Application
  • Pre-Authorized Permissions
  • Launch Sources

App Name

The name of the app is important as it is one of the first things that a user will see about an app. First impressions are crucial and a misleading or uninformative app name may be the difference between a viral and non-viral application. Also, names that are too long are a deterrent for users. In the App Store, the name of the developer will be shown directly under the name of the App, so an application should not contain redundant developer information in it. For example, Illumina’s BaseSpace Genome Browser should be called “BaseSpace Genome Browser” with the developer name “Illumina.”

There is no limit on the app name in BaseSpace, however the name of the app will be truncated past 40 characters (including spaces). This means that if an applications name is greater than 40 characters, the name of the app until 40 characters will be shown with a “…” following it. A user will still be able to see the entire name when they go to the app’s homepage or hover over the name of the app in the App Store or in the BaseSpace UI.

Note: The app name should not include the version number for the app. Instead, the app should use the versioning features in BaseSpace that are described above.

Short Description

A short description of the application is required for the App Store listing. This description should contain any information the user will need to understand what the app does, how it will affect their data, what the output looks like, and other general information about the app. The description will be shown on the app’s page in the App Store where the user will go to purchase or try the app, but it does not exist in any other location on BaseSpace.

The short description has a maximum limit of 128 characters (including spaces) which may be flexible depending on developer demand.

Long Description Content and Format

The long description contains detailed information about the app in addition to the description in the short description. The long description has a maximum limit of 4000 characters (including spaces).

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.

Homepage URL

This is the homepage url for the app, specified in the developer dashboard and completely determined by the app developer. There are no restrictions for this parameter.

Redirect URI

This is the redirect for the app, specified in the developer dashboard and completely determined by the app developer. There are no restrictions for this parameter.

Developer Name and Contact Information

The developer name and contact information are required so that the user has more information about the app origin. Contact information will be private unless the app developer wishes it to be listed on the app’s page in the App Store. The contact information is primarily used as a means to contact support for the app. The developer name will be listed everywhere that the app name is listed, but it will be smaller sized text listed under the app name. The developer name should not be listed in the app name.

App Icon

The application icon is incredibly important. Along with the app name, the app icon will be present in BaseSpace, the App Store, and on the app’s homepage. The app icon should be well-designed, aesthetically pleasing, and beautiful, it visually represents the app and is one of the first things that a user will see about an application.

The app icon should be three different sizes of 30px x 30px, 57px x 57px, and 100px x 100px. These will be displayed in different locations in the UI.

Screenshots

Screenshots give the user a visual representation of how the app functions, what it looks like, and what is returned by the app. Screenshots should show more than simply the home page that is loaded when the app is launched. They should essentially walk the user through the information in the description section, and give them an understanding of the app visually. Screenshots are shown on the app’s page in the App Store, so the user will have a chance to see some actual screenshots of the app before deciding to purchase it.

Screenshots should be 800px x 500px. Multiple screenshots can be submitted and the user can flip through them on the app’s page in the App Store. If your app does not have a UI, (e.g. it is a Native App) screenshots are not required.

App Category

Apps will be sorted by category in the App Store. Some apps may perform an analysis on user data, these would fall under the Analysis category. Other apps could be genome browsers which are more in the Visualization category. Other categories will be added for apps that do not fall within either of these. The category provides a sorting parameter for the user in the App Store.

Type of Application

The type of application shows the user how and where the application is used. The four categories here are Web, Desktop, Mobile, and Native. These four application types are described in more detail in the Getting Started portion of the documentation. This gives information to both BaseSpace and the user about how to launch the app, what platform it will be run on, and what device to use to run the app.

Pre-Authorized Permissions

The user will need general information about the level of access that an app will need. The level(s) of access that an app may request is described in the BaseSpace Permissions portion of the documentation.

Essentially, an app will request BROWSE or READ permission to any or all of a user’s data. There are other permissions that can be requested on launch, these are BROWSE GLOBAL, CREATE PROJECTS, and CREATE GLOBAL. This level of access requested will be shown in the App Store listing for each app.

To gain a better understanding of how to use the Pre-Authorized Permissions Settings to launch your app, please refer to the App Triggering guide.

Launch Sources

Launch Sources are selected from the Apps Dashboard. There are App Launchers in the BaseSpace UI that are located at different resource levels. These include Projects, Samples, AppResults, and AppStore. This field denotes the location from which your app can be launched in BaseSpace. Please set these appropriately in the developer portal.