Skip to main content

Illumina BaseSpace Destination

The Illumina BaseSpace Sequence Hub connector enables you to write data to BaseSpace, including uploading files to projects, creating sample records, and submitting data to BaseSpace applications. Follow the instructions below to create a new data flow that delivers data to an Illumina BaseSpace destination in Nexla.
illumina_basespace_api.png

Illumina BaseSpace

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Illumina BaseSpace connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Illumina BaseSpace instance, and click Next; or, create a new Illumina BaseSpace credential for use in this flow.

  3. In Nexla, Illumina BaseSpace destinations can be created using pre-built endpoint templates, which expedite destination setup for common Illumina BaseSpace write operations. Each template is designed specifically for the corresponding Illumina BaseSpace endpoint, making destination setup easy and efficient.
    • To configure this destination using a template, follow the instructions in Configure Using a Template.

    Illumina BaseSpace destinations can also be configured manually, allowing you to send data to Illumina BaseSpace endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this destination manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Illumina BaseSpace endpoints. Each template is designed specifically for the corresponding Illumina BaseSpace endpoint, making destination setup easy and efficient.

Endpoint Settings​

  • Select the endpoint to which this destination will send data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your destination for this endpoint.

    Upload File to AppResult

    Uploads a file into an existing AppResult using multi-part or single-part file upload. Use this endpoint to write analysis output files back to BaseSpace after processing in Nexla.

    • Sends a POST request to /v1pre3/appresults/{appResultId}/files with the file content as the request body.
    • Configure the following parameters: AppResult ID — the BaseSpace app result ID into which the file will be uploaded.

    The access token must have write scopes (e.g., CREATE GLOBAL) to upload files. Read-only tokens will be rejected by the BaseSpace API.

    Create AppResult Under a Project

    Creates a new AppResult under a project — the primary mechanism for writing analysis outputs back to BaseSpace. Use this endpoint to register analysis results in BaseSpace from external pipelines.

    • Sends a POST request to /v1pre3/projects/{projectId}/appresults with a JSON payload describing the new app result.
    • Configure the following parameters: Project ID — the BaseSpace project ID under which the new AppResult will be created.

    Creating an AppResult requires an active AppSession. Ensure the associated AppSession is in an active state before writing results. Use the Update AppSession Status endpoint to mark the session complete after all results are written.

    Update AppSession Status

    Updates an AppSession status (e.g., mark Complete or Aborted) to signal end-of-analysis. Use this endpoint to close out analysis sessions after all results and files have been written to BaseSpace.

    • Sends a POST or PATCH request to /v1pre3/appsessions/{appSessionId} with the new status value in the request body.
    • Configure the following parameters: AppSession ID — the BaseSpace app session ID whose status will be updated.

    Status transitions are one-way; a session marked Complete or Aborted cannot be re-opened. Confirm all results are successfully written before setting the terminal status.

    Create Project

    Creates a new project to organize samples and app results. Use this endpoint to programmatically provision BaseSpace projects from external sample management or LIMS systems.

    • Sends a POST request to /v2/projects (or /v1pre3/projects) with a JSON payload containing the project name and optional description.
    • No path parameters are required for project creation; all project fields are provided in the request body.

    Newly created projects are associated with the authenticated user's account. Ensure your credential has the CREATE GLOBAL scope to create projects in BaseSpace.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can send a test payload to the Illumina BaseSpace API to ensure that the destination is configured correctly.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Illumina BaseSpace destinations can also be configured to write data to any valid BaseSpace API endpoint that supports data creation or updates. Manual configuration gives you full control over the API method, endpoint URL, data format, and request structure.

API Method​

  1. Select the API method that will be used for calls to the Illumina BaseSpace API from the Method pulldown menu. For destination operations, the most common methods are:

    • POST: For creating new records, uploading files, or submitting data to BaseSpace (e.g., creating a new project, uploading a file to a sample)

    • PUT: For replacing an existing resource entirely

    • PATCH: For making partial updates to an existing resource

    Common BaseSpace write operations use POST requests. For example:

    • POST https://api.basespace.illumina.com/v2/projects — Creates a new project

    • POST https://api.basespace.illumina.com/v2/datasets — Creates a new dataset within a project

Data Format​

  1. Select the format in which data will be sent to the Illumina BaseSpace API from the Data Format pulldown menu. The BaseSpace API expects data in JSON format for most write operations.

    • JSON: The standard format for BaseSpace API request bodies. Most BaseSpace write endpoints accept a JSON object describing the resource to create or update.

Refer to the BaseSpace V2 API Reference for the specific request body schema required by each endpoint. Each endpoint's documentation specifies which fields are required and which are optional.

API Endpoint URL​

  1. Enter the URL of the Illumina BaseSpace API endpoint to which this destination will write data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters.

    Common BaseSpace destination endpoints include:

    • https://api.basespace.illumina.com/v2/projects — Create a new project

    • https://api.basespace.illumina.com/v2/biosamples — Create a new biosample

    • https://api.basespace.illumina.com/v2/datasets — Create a new dataset

    • https://api.basespace.illumina.com/v1pre3/projects/{'{projectId}'}/samples — Create a sample within a specific project

The access token configured in your credential must have the appropriate write scopes (e.g., CREATE GLOBAL) to perform write operations against the BaseSpace API. Read-only tokens will not be able to create or modify resources. Refer to the BaseSpace Permissions documentation for more information on required scopes.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers may be required for specifying content types or custom request parameters.

    You do not need to include the x-access-token authentication header — Nexla automatically includes your BaseSpace access token from the configured credential with every API request. The Content-Type: application/json header is also typically handled automatically.

Exclude Attributes​

Optional
  • To prevent specific data attributes from being included in the payload sent to the BaseSpace API, enter the attribute names to exclude in the Exclude Attributes field. This is useful when your Nexset contains fields that are not valid in the BaseSpace API request body or that should not be written to BaseSpace.

Record Batching​

Optional
  • If the Illumina BaseSpace API endpoint accepts arrays of records in a single request, you can configure Nexla to batch multiple records together into a single API call using the Record Batching settings. Batching reduces the number of API requests and can improve throughput when writing large volumes of records.

Not all BaseSpace API endpoints support batch record creation. Refer to the specific endpoint documentation in the BaseSpace API Reference to confirm whether batch requests are supported before enabling this option.

Response Webhook​

Optional
  • If you would like Nexla to capture and process the response returned by the BaseSpace API after each write request, configure the Response Webhook settings. This allows you to inspect the API response — for example, to capture newly created resource IDs returned by BaseSpace after a successful POST request — and use those values in downstream Nexla flows.

Save & Activate the Destination​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Illumina BaseSpace destination. Nexla will now begin delivering data to the configured BaseSpace endpoint according to the settings configured above.