Application Triggering

Application Triggering is the process of a user launching an app with from within BaseSpace.

The App's Input Form

The app's input form is the form or page that a user is taken to as a first step of the analysis. The user will select some type of input data for their app and may need to enter some additional information in order to launch the analysis. The app can either ask for permission to the user's data before they are taken to this input form or the app can ask for appropriate permission after the user has made their input form selections.

The input form for the app can be created and displayed using two separate methods:

  1. Using the Forms Builder tool for BaseSpace. Apps do not need to use the OAuth workflow to request an access_token with . Rather, BaseSpace will automatically request an access_token with sufficient permission to access the data specified in the input form and the app will receive an access_token after the user submits the form which can then be used to make the necessary API requests to download data and upload results.

  2. Not using the Forms Builder tool for BaseSpace. App will need to use one of the methods to go through the OAuth workflow described below. The app has to request permission to the user's data and also exchange an authorization_code for the access_token.

Advantages to using the Forms Builder Tool

  1. Use simple JSON to define complex form inputs and controls

  2. Easy-to-use IDE built into the developer portal

  3. Form elements follow the BaseSpace look and feel

  4. The app does not have to manually perform the OAuth process to obtain an access_token

  5. Input form data and parameters are automatically stored as Properties on an AppSession, the app does not have to manually tag all of these Properties

  6. Simple functions available for form validation

Using the Forms Builder Tool

When the user submits the Forms Builder form for your app, they are first taken to the OAuth dialog. This OAuth dialog is automatically generated based on the permissions your input form needs to the data that is selected. For example, if the app takes a Sample as input with Id 1001, the User will automatically see an OAuth dialog requesting the permission to Read Sample 1001 (e.g. the traditional scope would be read sample 1001.) If the user clicks Accept on the OAuth dialog, they are redirected to your redirect_uri with the following query parameters:

  • appsessionuri: contains information about the app that was launched, the user who launched the app, and the resource in BaseSpace from which the app was launched. In addition, any values selected or entered on the form by the User will be stored as input.* and output.* Properties on the AppSession that is created here.
  • authorization_code: This value is exchanged for an access_token, this transaction is described in the OAuth Flow sections below.

For more information about the Forms Builder tool, please refer to the Forms Builder Documentation.

Not Using the Forms Builder Tool

In the App Dashboard page, an app may be configured to launch from various resources in BaseSpace and to automatically ask the user for a certain level of permission. These fields are named Launch Permissions and App Launch Location in the edit page of the app (https://developer.basespace.illumina.com/apps/{id}/edit).

So, for example, if Projects is selected as an App Launch Location and Read is the selected Launch Permission,

App Edit Page Example

the app would be displayed in the App Launcher in BaseSpace located at the Project level and would automatically direct the user to the OAuth dialog with a scope of read project {id}.

Project App Launcher Example

Here's a summary of steps for starting an application from within BaseSpace:

  • The user starts an application and is automatically redirected to the OAuth dialog from BaseSpace with the scope specified in App Dashboard.
  • Using the above app configuration, the user will see the following OAuth dialog, which will be populated by the read project {id} permission and some other information to denote app triggering.

OAuth Dialog and Scope Example

  • If the user grants access, the user's browser is directed to your app's configured redirect_uri
  • The app uses the included query parameter authorization_code to retrieve an access_token from the API which may be used to access data on behalf of the user
  • The AppSessionUri contains information about the app that was launched, the user who launched the app, and the resource in BaseSpace from which the app was launched

Please read the following sections for more details of the above summary.

OAuth flow for web apps apps started from within basespace

This is the OAuth workflow for a web app started from within BaseSpace.

Getting the authorization_code

When an app is started from within BaseSpace, the user authorizes the app to start with the given input data and permissions (as you configured in the App Dashboard).

BaseSpace will direct the user to the redirect_uri you configured with the following additional query parameters:

  • authorization_code - This code indicates that the user has authorized your app to start with the permissions you indicated in the App Dashboard. This will need to be exchanged for an access_token in order to access data on behalf of the user
  • AppSessionURI - a URI to the BaseSpace API containing details about what the user had optionally selected in BaseSpace (i.e. projects, samples, etc)

Using the app configuration described above, here is an example of the parameters the redirect to will contain after a user grants permission:

https://uri.to/your/application?action=trigger&appsessionuri=v1pre3/appsessions/{AppSessionId}&authorization_code={code}

Getting an access_token

Once you have the authorization_code, you’ll need to exchange it for an access_token by performing a POST to our API at:

https://api.basespace.illumina.com/v1pre3/oauthv2/token

This request must be authenticated with your client_id and client_secret that are available in the application management screen for your app. You may provide these credentials encoded via the standard Authorization header or in the body (but not both).

The request should have the standard content-type of application/x-www-form-urlencoded used for form POSTs.

Include the following parameters:

  • code (required): The authorization_code provided as a query parameter to the redirect_uri.
  • redirect_uri (required): The redirect_uri for the application that you have configured for your application.
  • grant_type (required): Must be the value authorization_code
  • client_id: If not using the Authorization header
  • client_secret: If not using the Authorization header

Example curl request using the Authorization header approach:

curl -v -u {YOUR CLIENT_ID}:{YOUR CLIENT_SECRET} \
-d "code={YOUR AUTHORIZATION CODE}" \
-d "redirect_uri={YOUR REDIRECT_URI}" \
-d "grant_type=authorization_code" \
https://api.basespace.illumina.com/v1pre3/oauthv2/token

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 07 Mar 2012 14:50:42 GMT
Content-Length: 105

{
    "access_token":"{YOUR ACCESS TOKEN}"
}

If you get a status code 200 response, the JSON document will include your access_token. Otherwise, the response will include an error_code and an error_description to help you figure out the problem.

Fetching the App Session

An AppSession is created or assigned each time an app is launched by the user via BaseSpace or when an application creates an AppResult in BaseSpace. The AppSessionUri is a query parameter that is passed with the app's redirect_uri. The AppSession contains information about the app that was launched, the user who launched the app, and the resource(s) in BaseSpace from which the app was launched.

The appsessionuri will look like:

v1pre3/appsessions/{AppSessionId}

Perform a GET request to the API using the appsession id with client_id and client_secret. Both of these fields are available in your App Dashboard. This call request will return detailed information about the appsession id that was assigned or created for your application running on the context from which the user ran your application.

When you get the response, it will be a JSON document with the following fields:

  • Response - The response object

    The Response object contains the following fields:

    • References - Detailed information about the context from which the app was launched
      • Rel - Only "Input" for now
      • Type - The type of data that the app was triggered on, can be a project, sample, appresult
      • Content - Gives Resource details, along with information about the user who owns the Resource that the application was called on, if the user launched your application within the context of a project this field would contain information about the project. The same principle applies to samples and runs.
    • Id - Id of the appsession, there are multiple id fields which correspond to the project, userownedby, and application as well
    • Application - detailed information about the application which created or maintains this appsession, in this case it would be your application
    • UserCreatedBy - The user that the app was triggered by
    • Status - Status of the app session, see App Sessions in the API Reference for values of the status parameter
    • StatusSummary - A brief summary of the app session, this can be set by making a POST request to the appsession
    • DateCreated - Date on which the app session was created and this application was triggered

  • ResponseStatus - contains human-readable explanations of failures

  • Notifications - System notifications, like scheduled downtime

Example curl request using the appsessionuri with value v1pre3/appsessions/d840251ab9c441639a9b2f047ded51fd:

curl -v -u {CLIENT_ID}:{CLIENT_SECRET} \
http://api.basespace.illumina.com/v1pre3/appsessions/d840251ab9c441639a9b2f047ded51fd

Example response:

{
    "Response": {
        "References": [
            {
                "Rel": "Input",
                "Type": "Project",
                "Href": "v1pre3/projects/76076",
                "HrefContent": "v1pre3/projects/76076",
                "Content": {
                    "Id": "76076",
                    "UserOwnedBy": {
                        "Id": "74074",
                        "Href": "v1pre3/users/74074",
                        "Name": "BaseSpace Illumina"
                    },
                    "Href": "v1pre3/projects/76076",
                    "Name": "Project_BacillusCereus",
                    "DateCreated": "2012-08-21T07:31:37.0000000"
                }
            }
        ],
        "Id": "d840251ab9c441639a9b2f047ded51fd",
        "Href": "v1pre3/appsessions/d840251ab9c441639a9b2f047ded51fd",
        "Application": {
            "Id": "3003",
            "Href": "v1pre3/applications/3003",
            "Name": "BaseMaker 5000",
            "HomepageUri": "http://www.yourapphomepageuri.com/",
            "ShortDescription": "Just an app...",
            "DateCreated": "2012-06-04T20:23:02.0000000"
        },
        "UserCreatedBy": {
            "Id": "37037",
            "Href": "v1pre3/users/37037",
            "Name": "John Doe"
        },
        "Status": "Running",
        "StatusSummary": "",
        "DateCreated": "2012-09-04T08:44:38.0000000"
    },
    "ResponseStatus": {},
    "Notifications": []
}

This example response would indicate that user John Doe with user id '37037' started your application and he selected a project with id 76076 on which to run your application.

Although some basic information is provided about the project here, your application will not be able to get any more information or download project information yet. In order to get more access, you'll need to ask the user for a level of access to it. You may do this using the workflows described in Obtaining Access Tokens.

More information about the appsession can be found in the API Reference.

Using the Access Token to get BaseSpace Data

Now that you have the context from which the user launched the app and also the access_token, the next step is to use the API methods to get user data. With every API request your app will need to pass the access_token. Using the access_token with each API method is described in more detail in the API Reference.

Even though your app was started from within BaseSpace, you may request that the user grant you higher access to a given resource or to other resources by invoking one of the OAuth flows described in Obtaining Access Tokens.