# Welcome
Accelerate your genomics journey with the Illumina BioInsight Platform (formerly Connected Software). Unlock insights, streamline workflows, and collaborate seamlessly—all in one integrated ecosystem.
## :dna: Discover the Illumina BioInsight Platform
Illumina BioInsight Platform (formerly Connected Software) refers to Illumina's portfolio of software products, including BaseSpace Sequence Hub, BioInsight Platform Core, and more.
The Illumina BioInsight Platform is Illumina's unified cloud software suite, providing access to the full portfolio of bioinformatics applications—including BaseSpace Sequence Hub, BioInsight Platform Core, Connected Multiomics, Illumina Connected Insights, and Emedgene—from a single account and subscription.
The following steps represent the end-to-end user journey, from managing workflows in the lab to interpreting data from analyses. Click on each step in the workflow for relevant support provided by Illumina's suite of software solutions.
🚀 New to the Platform? Start Here
Sign up for free at [login.illumina.com/login](https://login.illumina.com/login) — no prior purchase required. Choose a **Free Trial** (100 BioInsight Credits, 30 days, full access) or go directly to a **PAYG subscription** (monthly usage-based billing).
See the [Getting Started](/getting-started) guide to walk through sign-up, domain provisioning, and your first steps on the platform.
🔐 Log In
Log in to your Illumina BioInsight Platform (formerly Connected Software) account [here](https://login.illumina.com/login/). You can also click **"Sign In"** in the top right. Please note that an account is required to log in. To register your software and add users, refer to the instructions provided in the [Software Setup](/getting-started/rg-registration) section.
📦 Have a Sales Order Code?
If your organization purchased software through an Illumina sales representative and you received an order code, use the [Order Registration](/getting-started/rg-registration) process to activate your software.
{% hint style="info" %}
You can search our help documentation or ask questions with AI-generated answers using the search-box at the top of the page.
Navigate and explore using the left-panel.
{% endhint %}
# Getting Started
Sign up for the Illumina BioInsight Platform and start exploring the full suite of cloud bioinformatics applications—no prior purchase required.
The Illumina BioInsight Platform is a unified cloud software suite that gives you access to BaseSpace Sequence Hub, Illumina BioInsight Platform Core, and Connected Multiomics from a single account and subscription.
## First, figure out which path applies to you
| Your situation | What to do |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **First person at your organization** signing up | Sign up to create a new domain — see **Creating a New Domain** below |
| **Your organization already has a domain** | Request an invitation from your Domain Administrator — see **Joining an Existing Domain** below |
| **You have an order code** from an Illumina sales purchase | Use [Order Registration](/getting-started/rg-registration) instead |
***
## Creating a New Domain
Follow these steps if you are the first person at your organization setting up the platform.
When you complete sign-up, you become the **Domain Owner** — the primary account holder who can manage the subscription, invite users, and handle billing.
1. Go to and click **Sign Up**.
2. Create an Illumina account with your email address, or sign in if you already have one.
3. Choose a subscription plan — see [Subscription Plans](#subscription-plans) below.
4. Select a **region** for your data. Contact [Illumina Support](mailto:customerservice@illumina.com) if you need to change this later — the platform does not support cross-region data transfers.
5. Click **Create domain**. Your domain is ready within seconds.
After sign-up, invite team members from the [Admin Console](/account-management/admin-console) > **Domain** > **User Management** > **+ Invite**.
***
## Joining an Existing Domain
Follow these steps if a Domain Administrator has invited you to your organization's existing domain.
1. Open the invitation email and click **Accept Invitation**.
2. Sign in with your Illumina account, or create one using the same email address the invitation was sent to.
3. You are added to the domain and redirected to the platform home.
{% hint style="info" %}
You do not choose or pay for a subscription when joining an existing domain. Your access is governed by your organization's plan and the permissions assigned by the Domain Administrator.
{% endhint %}
If your invitation link has expired, ask your Domain Administrator to re-send it from **Admin** > **Domain** > **User Management** > **+ Invite**.
***
## Subscription Plans
Two plans are available when creating a new domain.
| Plan | What's included |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| **Free Trial** | Try the platform at no cost for 30 days. 100 BioInsight Credits included. No payment required. |
| **Pay-As-You-Go (PAYG)** | Full, ongoing access billed monthly based on usage. No fixed commitment. |
***
## Free Trial
The Free Trial lets you explore the platform at no cost. No payment information is required.
| | |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| **Duration** | 30 days from the day you sign up |
| **BioInsight Credits** | 100 credits to use for analysis and storage |
| **Storage** | 1 TB |
| **Applications** | Full access to BaseSpace Sequence Hub, BioInsight Platform Core, and Connected Multiomics |
BioInsight Credits (BIC) are the platform's usage currency — consumed when you run analyses, store data, or transfer files. Your balance is shown in the platform header.
If you use up all 100 credits before your 30 days are up, new analyses and uploads will pause. You can still read and download your existing data. Upgrading to PAYG immediately restores full access.
### After 30 days
When your trial ends, a **30-day grace period** begins. During this time:
* You can still **read and download** all your data
* You cannot start new analyses or upload new files
* You can **upgrade to PAYG** at any time to continue working
{% hint style="warning" %}
If you do not upgrade before the grace period ends, **all your data will be permanently deleted**. Download anything you want to keep before day 30 of the grace period.
{% endhint %}
{% hint style="info" %}
**BaseSpace Sequence Hub access is preserved indefinitely**, even after your trial ends. You can continue uploading sequencing runs at no cost, regardless of your subscription status.
{% endhint %}
***
## Pay-As-You-Go (PAYG)
The PAYG subscription gives you full, ongoing access to the platform. You pay at the end of each month based on what you actually used — no fixed fee, no long-term commitment.
| Feature | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| **Applications** | Full access to BaseSpace Sequence Hub, BioInsight Platform Core, and Connected Multiomics |
| **BioInsight Credits (BIC)** | Usage currency. BIC are billed monthly. |
| **Storage** | Metered and billed monthly |
| **Users** | Invite your team |
| **SSO / SAML** | Included |
At the end of each month, you receive an invoice for your total usage. If you prefer not to receive monthly invoices, you can prepurchase BIC in advance — those are drawn down first, and any remaining usage is invoiced at month-end. See [Software Billing](/account-management/software-billing) for more information.
{% hint style="info" %}
Data stored on the platform continues to accrue storage charges even when you are not actively running jobs. Delete data you no longer need to keep costs down.
{% endhint %}
You can cancel your PAYG subscription at any time. Cancellation takes effect at the end of the current billing period, after which a retention window applies before permanent deletion.
***
## Choosing a Plan
| | Free Trial | PAYG |
| ------------------------ | ----------------------- | -------------------------- |
| Cost | Free | Pay for what you use |
| Duration | 30 days | Ongoing |
| BioInsight Credits (BIC) | 100 included | Billed monthly |
| Payment required | No | Yes |
| Best for | Evaluating the platform | Production or ongoing work |
***
## Upgrading to PAYG
You can upgrade from the Free Trial to PAYG at any point — before, during, or after your trial. The trial subscription can be upgraded from the platform Applications view — an **Upgrade** button is shown at the top of the page.
{% hint style="warning" %}
Only the **Domain Owner** (the user who originally signed up) can initiate an upgrade.
{% endhint %}
All data, projects, and settings created during the trial are fully preserved. There is no migration step.
| Timing | What happens |
| ------------------------------- | --------------------------------------------------------- |
| **During the active trial** | No interruption to work in progress. |
| **After credits are exhausted** | Upgrade to resume submitting new jobs and uploading data. |
| **During the grace period** | Upgrade to restore full access. |
***
## Frequently Asked Questions
Can I upgrade if my trial has already expired and my domain is in the grace period?
Yes. You can upgrade at any point during the grace period to restore full access.
Is there any downtime during the upgrade?
No. The subscription update completes within approximately 60 seconds of payment confirmation. Running jobs and existing data are not affected.
# Order Registration (Sales-Led)
{% hint style="info" %}
**New to the platform?** If you are signing up for the first time without a sales order code, see [Getting Started](https://github.com/illumina-swi/ics-docs/tree/main/docs/account-management/getting-started.md) to sign up directly and start a Free Trial or PAYG subscription.
{% endhint %}
{% hint style="info" %}
"Order Registration" and "Software Registration" terms are used interchangeably.
{% endhint %}
## Setting up Illumina BioInsight Platform
Thank you for purchasing Illumina BioInsight Platform (formerly Connected Software). To begin using the software, please complete the setup process. This process activates the software and allows you to assign access to specific users. To get started, follow the steps below.
## Setting up Software Purchased Through Illumina Sales
This guide covers activation of Illumina BioInsight Platform software purchased through an Illumina sales representative. If you received an **order code**, follow the steps below to register your software, assign users, and provision your domain.
## Accessing Orders Page
If you already have a user account for Illumina BioInsight Platform (formerly Connected Software), enter those credentials into the login screen. If you do not have an Illumina user account, then select the "Sign up" link to create a new account. You should choose this option if this is the first time you have registered through the Order Registration Portal.
Once you have logged in, you will either be directed straight to the Order setup page (if you created a new account), or you will see your [BioInsight Platform](/account-management/platform-home) (if you are logging into an existing account).
To access the Orders page from BioInsight Platform, select "Orders" from the left navigation menu.
Accessing Orders page from Left Navigation Menu
Once you have made it to the Order Registration page, you should see a table displaying all the orders that need to be registered. This includes details such as the Product name, Setup status, Order date, Order number, Customer id, and Assignees.
## Order Registration
If you’ve been given an order code, you can enter it using the "Enter order code" option at the at the top right corner above the table. This will add the order to your account so you can proceed with registration.
## Assign additional users to set up the software (Optional)
For each order awaiting registration, you can assign specific users to set up the software. Click the button “Manage" under Assignees column, a modal window is displayed where you can view the users currently assigned to the order.
To add a new Assignee, you can enter the email address of the person you wish to invite and click "Add". Press the “Confirm” button to send an email to that person containing a link to the Order Registration portal. To remove someone, click the **X** next to their email address and press "Confirm".
{% hint style="warning" %}
The purchaser of the software cannot be removed from the order, and you cannot remove yourself.
{% endhint %}
## Configure software settings and set up the software
### Review Order Details
You can review the "Order details" for each order by clicking on the "Order number" link in the table. This information includes the date the order was placed, the order number, the purchaser email, the subscription term, and other key informations about the order. This information is not editable.
### Set Up the Software
To set up the order, select the order you want to setup and click on the "Setup" option next to the "Enter order code" at the top right corner above the table.
You can select multiple orders to set them up at once. The "Setup" option contains software settings. You will need to select a region and domain/workgroup to which the software will be registered. The domain and region cannot be easily changed after the setup is complete.
#### Select a Region
First, select the region for the software subscription. This determines the cloud region where data will be stored and analyzed. It is best practice to choose a region that is geographically close to where the software will be used.
Software consumable order items (e.g. BioInsight Credits) do not require a region selection.
#### Select a Domain/Workgroup
Next, select the domain or workgroup to which the software will be registered.
{% hint style="info" %}
This step may vary slightly depending on the type of software you're registering:
1. **Software Subscriptions**
* Examples:
* Illumina BioInsight Platform
* Illumina Connected Insights, Connected Multiomics
2. **Software Consumables**
* Examples:
* BioInsight Credits (BIC), Genome Equivalent Samples
For software subscriptions such as BaseSpace Sequence Hub Professional, you will need to select a workgroup during setup. For all other software subscriptions, you will need to select a domain. For software consumables (e.g., BioInsight Credits or Sample Analyses), you may choose either a workgroup or a domain to apply them to.
{% endhint %}
{% hint style="warning" %}
It is important to *complete the setup for subscriptions FIRST* before registering software consumables. Software consumables require an active subscription for them to be used.
{% endhint %}
Setup of Software Consumable - BIC
If the account you're logged in with has access to existing domains or workgroups, they will be listed on the page for you to choose from. Selecting an existing domain or workgroup will not affect or modify user access permissions associated with that account.
If you do not have existing domains or workgroups, then select the "Create a new domain" or "Create a new workgroup" button (depending on the type of order you are registering).
**Create a New Domain**
{% hint style="info" %}
Note: When creating a new domain, you will be considered the administrator for that domain. The domain administrator can later be changed in the [Admin Console](/account-management/admin-console).
{% endhint %}
Upon clicking "Create a new domain", a modal window will be displayed where you can enter the following details for your domain:
* **Name:** Nickname for domain that is unique and easy to identify (ex. “My Company Name’s Domain”). You may only use lowercase alphanumeric, dash (-), max 50 characters and no spaces.
* .
{% hint style="info" %}
The list of allowed emails and email extensions can be updated later in the [Admin Console](/account-management/admin-console).
{% endhint %}
Click "Setup" to create the domain. Make sure to select the name of your domain once it's been created.
### Complete the Setup
Once the configuration settings have been selected, press the button at the bottom of the order item to make the software available for use. Upon clicking this button, you will no longer be able to access or modify the order in the Order Registration Portal.
you will receive a welcome notification that includes getting started information about your subscription
At this point, all users in the domain or workgroup should be able to access the software from [BioInsight Platform](/account-management/platform-home). However, if you have a software which requires adding specific users to the subscription before someone can access the associated application—such as ICM—you can navigate to the [Subscriptions](/account-management/platform-home#subscriptions) page to assign users.
If you have a software which requires every user to be part of a workgroup before they can access the app—such as ICI, Emedgene, and ICM— you can navigate to the [Admin Console](/account-management/admin-console) to create workgroups and add users to the workgroup.
From the Admin Console, you can also assign different domain admins.
{% hint style="info" %}
See the [FAQ](/getting-started/rg-faq) for frequently asked questions and answers.
{% endhint %}
# FAQ
Frequently Asked Questions
## Order Registration
## **Q: What types of Illumina Software require order registration?**
A: Order registration is used to activate software purchased through an Illumina sales representative. There are two types:
* Software Subscriptions
1. BaseSpace Professional Subscriptions
2. BioInsight Platform Core Professional, BioInsight Platform Core Enterprise, Illumina Connected Insights, Connected Multiomics Subscriptions, etc.
* Software Consumables
1. Examples: BioInsight Credits (BIC), Genome Equivalent Samples, Illumina Complete Long Reads cloud analysis, Consumption billing
## **Q: Why is selecting workgroups or domains required?**
A: Workgroups and Domains are used by Illumina software to control access to different customers' data and assets. Examples of a domain are dcehealth.Illumina.com or coreseqinc.Illumina.com.
Choosing a domain is required when registering BaseSpace Enterprise, BioInsight Platform Core, or Cohorts Subscriptions. Choosing a workgroup is required when registering BaseSpace Professional. Software consumables (such as BIC) can be applied to either domains or workgroups of active subscriptions.
Below is a description of how workgroups and domains are used by Illumina software.
| Subscription Type | Location for BIC | Description |
| ----------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------- |
| All other software products (Platform Core, ICI, ICM, etc.) | Domain | All other software subscriptions use domains to control access to software consumables. |
| BaseSpace Sequence Hub Professional | Workgroup | BaseSpace Pro subscriptions use workgroups to control access to software consumables. |
## **Q: Why do I not see my orders listed on the Order Registration page?**
A: If you arrive at the Software Registration Portal page and see no orders listed, this means that the orders have not been associated with your email address.\\
You have most likely been forwarded an Illumina registration email and clicked on the link to get to the registration portal. The portal does not recognize your email because the person that forwarded the message did not request that your email be assigned to register new products.
The solution for this is to ask the person who forwarded the email to you to log into the registration portal and add your email address using the "Assign User" button. If this does not resolve the issue or you are unable to locate your order after logging in, please contact or click on the [FAQ](https://support.illumina.com/support-content/NoPendingReg.html) link on the Registration Page.
## **Q: I completed my registration, why can I not access my software?**
A: After registration is completed, a notification will be sent to your email address to confirm the account details.
Provisioning of your software in the cloud can take up to 15-30 minutes after registration is complete. When provisioning is completed, you will receive a welcome notification that includes getting started information about your subscription.
# Platform Home
BioInsight Platform's Applications Page is the landing central hub for managing account in Illumina.
{% hint style="info" %}
Note: "BioInsight Platform" and "Platform Home" terms are used interchangeably.
{% endhint %}
## Access BioInsight Platform
Once you have [set up your software](/getting-started/rg-registration), you can log in through the [Illumina login](https://login.illumina.com/login) to access BioInsight Platform. From this page, you can click on any app tile to launch a product.
Once you're inside an application, you can return to BioInsight Platform at any time by clicking on the waffle menu present to the top right corner and selecting "Platform Home." From the waffle menu, you can also switch between any of the applications you have access to.
The left navigation menu in BioInsight Platform provides various options to manage account in Illumina.
## Usage
The Illumina Usage Explorer allows you to track your usage costs across Illumina cloud products with detailed insights and trends. To learn more about the usage explorer visit [Usage Explorer](/account-management/usage-explorer).
## User
In the left navigation menu, the User component features a dropdown list containing options for managing the following:
* Profile
* API keys
* Sessions
* Passwords
* Communications
User option in the left navigation menu
### Profile
The **"Profile"** option takes you to a page where you can update your profile information. Please note that the email address associated with your profile cannot be changed. However, you can edit the following fields: **first name, last name, company name, job title,** and **country/region**.
Click **"Save"** to apply your changes, or **"Cancel"** to discard them.
### API Keys
The **"API Keys"** page allows you to view and manage all your API keys.
**Manage Existing API Keys**
You will see a list of all the API keys associated with your domain, including their status, creation date, expiration date, last used date, and available actions. You can expand the dropdown for each key to view the roles associated with it, if applicable.
Click the icon to generate a new version of an existing API key. Regenerating an API key creates a new key value that replaces the old one. This is often done for security reasons—such as when you suspect a key has been exposed—or to rotate credentials regularly. Please note: if you regenerate a key, any existing integrations that rely on the original key may stop working unless you update them with the new key.
Click the  icon to edit an API key. You can update the key name and choose whether the changes apply to all future workgroups and roles within the domain. You can also specify which current workgroups and domains the updated name applies to.
Click theicon to delete an API key. You can no longer access the API key once it's deleted.
 
**Generate New API Key**
To create a new API key, click the **"Generate"** button. Provide a name for the key, then choose to either include all workgroups or select specific workgroups that the key should have access to.
Once generated, the API key will be displayed in a hidden format. Use the **"Show Key"** button to reveal it, and optionally download the key as a file for secure storage.
⚠️ **Important:** Once this window is closed, the key will no longer be accessible through the domain interface. Be sure to store it securely for future use.
After generating a key, keep it in a safe location to use when accessing the platform via the command-line interface (CLI) or APIs.
### Sessions
The **"Sessions"** page takes you to a table displaying a log of your user account session activities. Activities such as sign-ins, session generations, and sign-outs from different devices are recorded.
You’ll also see additional columns providing details about each activity, including the device, browser, IP address, creation time, last activity time, and action.
From the **Action** column, you can click **"Sign Out"** to end any active sessions.
Lastly, click the waffle menu next to each column header to pin, autosize, reset, or customize the ccolumns displayed.
 
### Password
The **Password** page allows you to change the password for the domain.
### Communication
The **Communication** page allows you to choose the communication preference from Illumina
## Subscriptions
The **"Subscriptions"** link takes you to a table displaying all subscriptions associated with the domain. This includes details such as the subscription name, subscription number, status, start date, end date, email address, and available actions.
The end date indicates when the subscription is scheduled to expire.
Most subscriptions—such as BioInsight Platform Core—provide access to applications for all users in a domain.
For certain subscriptions—such as [ICM](https://help.connected.illumina.com/multiomics-software/connected-multiomics)—specific users need to be assigned to the subscription in order for someone to access the associated application. Only domain admins have permission to assign or unassign users to these type of subscriptions. To assign a user, click "Assign" and enter the user’s email address.
To unassign a user, click the "Unassign" link and the user will be removed.
Click the waffle menu next to each column to filter, pin, autosize, reset, or customize the columns displayed.
  
## Orders
The Orders Registration page allows you to set up and manage software orders. To learn more about the Order Registration and Software setup visit [Software Setup](/getting-started/rg-registration).
## Admin
The Illumina Admin console is a platform designed for administrators to manage product usage, control workgroup permissions, and oversee domain access. To learn more about the Roles, Workgroup and Domain visit [Admin console](/account-management/admin-console).
# Admin Console
The Admin Console provides centralized management of domain settings, workgroups, user accounts, and security policies.
## Access Admin Console
To access the Admin Console, log in through the [Illumina login](https://login.illumina.com/) to go to the [BioInsight Platform](/account-management/platform-home). From there, select **Admin** from the left navigation menu. You can also access it directly at `https://.login.illumina.com/iam`.
The Admin Console contains two main sections accessible from the left navigation: **Workgroups** and **Domain**.
## Roles
The roles within a domain that users may be assigned are:
| Role | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Domain Admin** | Read/write access to all resources created by users in the domain. Manage domain and workgroup membership. |
| **Workgroup Admin** | Read/write access to all resources created by users in the workgroup. Manage workgroup membership. |
| **Workgroup User** | Read/write access to all resources created by users in the workgroup. |
## Get Started
# Workgroups
## Workgroups Overview
Workgroups are groups of users that can share projects and data. To view all workgroups in your domain, navigate to **Admin** from BioInsight Platform and select **Workgroups** from the left navigation menu.
The workgroups table displays the following columns:
| Column | Description |
| ----------------- | ----------------------------------------------------------------------------------- |
| **Workgroup** | The name of the workgroup. Click the name to open the workgroup detail page. |
| **Description** | A short description of the workgroup. |
| **Owner** | The primary administrator and main point of contact for the workgroup. |
| **Collaboration** | Indicates whether the workgroup allows collaboration with users outside the domain. |
| **Created on** | The date the workgroup was created. |
| **Status** | Whether the workgroup is Active or Archived. |
| **Actions** | Edit (pencil icon) or Archive the workgroup. |
Use the **Search workgroup name** box to filter the list. Toggle **Show archived** to include archived workgroups in the results. Use the page size selector and navigation arrows to page through large lists.
## Create a Workgroup
Domain administrators can create new workgroups. To create a workgroup, click **+ Create workgroup** in the top right of the Workgroups page.
Fill in the following fields:
* **Name** — A unique name for the workgroup.
* **Description** — An optional description of the workgroup's purpose.
* **Owner email** — The email address of the workgroup owner. The owner is the primary administrator and is automatically added as a workgroup admin and user. Must be a valid email address.
* **Collaboration** — Choose whether outside collaborators are allowed:
* **Don't allow outside collaborators** — Only users within the domain can be added.
* **Allow collaborators outside of this domain** — Users from other domains can be invited to this workgroup.
{% hint style="warning" %}
The Collaboration setting cannot be changed after the workgroup is created.
{% endhint %}
Click **Create workgroup** to save, or **Cancel** to discard.
## Edit Workgroup Settings
To quickly edit a workgroup's name, description, or owner from the workgroup list, click the **pencil icon** in the Actions column. This opens the **Edit workgroup settings** modal.
Update the **Name**, **Description**, or **Owner email** as needed, then click **Save**. Workgroup settings can also be edited from the **Settings** tab within the workgroup detail page (see [Settings](#settings) below).
## Archive a Workgroup
To archive a workgroup, click the **archive icon** in the Actions column for that workgroup.
A confirmation dialog will appear describing the effect of archiving:
* Users will no longer be able to access the workgroup.
* Data associated with the workgroup will not be deleted.
{% hint style="warning" %}
Archiving a workgroup cannot be undone. To reactivate an archived workgroup, contact Illumina Support.
{% endhint %}
Click **Archive workgroup** to confirm, or **Cancel** to go back.
## Workgroup Detail
Click on a workgroup name to open the workgroup detail page. The detail page displays the workgroup name and description at the top, and contains three tabs: **Users**, **Apps**, and **Settings**.
### Users
The **Users** tab shows all users in the workgroup and their application access. The workgroup owner is displayed at the top of the page.
The user table shows each member's name, username, workgroup role (Admin or User), and their access level for each application available to the workgroup.
Use the **Search user** box to find a specific user, or use the role filter dropdown to show **All users**, **Admins**, or **Users** only.
#### Change Workgroup Owner
The current workgroup owner is shown at the top of the Users tab. To change the owner, click **Change owner**.
Enter the email address of the new owner and click **Change owner**. The new owner will automatically be added as a workgroup admin and user if they are not already.
#### Invite User
To invite a new user to the workgroup, click **+ Invite**.
Configure the following:
* **Collaboration** — Select how the user should be invited (e.g., via the current domain, or via collaborative enterprise). This setting cannot be changed after the invitation is sent.
* **Users** — Enter up to 50 email addresses, separated by commas or semicolons.
* **Workgroup access** — Select the workgroup role: **Admin** or **User**.
* **Application access** — For each application available to the workgroup, choose **Has Access** or **No Access**.
Click **Invite to workgroup** to send the invitation, or **Cancel** to discard.
#### Change User Access
To change a user's workgroup role or application access, select the checkbox next to their name and click **Change access**.
Update the **Role** and any **Application access** settings, then click **Change access** to save.
#### Remove User
To remove one or more users, select the checkbox next to their name(s) and click **Remove**. A confirmation dialog will appear before the user is removed from the workgroup.
{% hint style="info" %}
Workgroup owners cannot be removed directly. To remove a workgroup owner, first change the workgroup owner to another user, then remove the original owner.
{% endhint %}
#### View User Details
Click a user's name to open their **User details** page. This page shows the user's profile (name, email, join date, status), their domain role, and a list of all workgroups they belong to with their application access in each.
From the User details page, you can:
* **Change domain role** — Click the edit icon next to the user's domain role to change it between **Admin** and **User**.
* **Change access** — Select a workgroup row and click **Change access** to update the user's role or application access in that workgroup.
* **Remove access** — Select a workgroup row and click **Remove access** to remove the user from that workgroup.
* **Manage API keys** — Click **Manage API keys** in the top right to view and delete the user's API keys.
* **Expire user** — Click **Expire user** in the top right to expire the user's account.
### Apps
The **Apps** tab lists all applications available to the workgroup, along with the number of users in the workgroup who have access to each application.
Click the **view icon** in the Actions column to see the list of users with access to that application.
### Settings
The **Settings** tab displays the workgroup's name, description, and collaboration mode.
Click **Edit** to open the **Edit workgroup settings** modal, where you can update the name, description, and owner email. Click **Save** to apply changes.
# Domain
## Overview
The **Domain** section of the Admin Console displays domain-level settings and allows administrators to manage users, security policies, access controls, and integrations. To view Domain settings, navigate to **Admin** from BioInsight Platform and select **Domain** from the left navigation menu.
The Domain settings page contains the following sections, accessible from the left navigation submenu:
| Section | Description |
| ------------------- | ------------------------------------------------------------------------ |
| **Usage reports** | Generate reports on user sessions, login activity, and workgroup events. |
| **Sessions** | Configure idle session timeout, JWT expiration, and API key settings. |
| **User management** | Manage domain users, allowed emails, and service accounts. |
| **Access** | Restrict domain access by IP address or CIDR range. |
| **Collaboration** | Configure collaboration domain namespaces. |
| **Roles** | Create and manage custom roles with unique permission settings. |
| **Authentication** | Configure the authentication type (Default or SAML SSO). |
| **DNS domain** | Verify DNS domain ownership for SSO configuration. |
| **About** | View the domain name, namespace, and ID. |
## About
The **About** section displays basic information about the domain: the domain **Name**, **Namespace**, and **ID**. Click **Change name** to update the domain display name.
## Usage Reports
The **Usage reports** section allows you to generate reports on domain activity.
Select a report type:
| Report Type | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| **General Usage Report** | User sessions, last login details, registration date, and usernames. |
| **Login Report** | Account activity including client IP addresses, applications accessed, event types, and user emails. |
| **Workgroup Report** | Workgroup activities, including event data for actions performed by each user. |
Select a **Date range** and enter the email addresses of the **Recipients** who should receive the report. Click **Generate reports** to submit.
{% hint style="info" %}
Usage reports can only be generated for the last 90 days. For information older than 90 days, contact Illumina Support.
{% endhint %}
## Sessions
The **Sessions** section allows you to configure session timeout and API key settings.
#### Idle Session and JSON Web Token (JWT)
| Setting | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Session timeout** | The number of minutes a session can be idle before it times out. Accepted values are 5–60 minutes. Set to -1 to disable. |
| **JSON Web Token (JWT) expiration** | The duration before the JWT token expires. Accepted values are 120–10,080 minutes (2 hours to 7 days). |
#### API Keys
| Setting | Description |
| ----------------------- | ------------------------------------------------------------------------------ |
| **API keys expiration** | The number of days before an API key expires. Set to -1 to disable expiration. |
| **Max active API keys** | The maximum number of active API keys a user can have at the same time. |
Click **Edit** to modify these settings.
## User Management
The **User management** section contains three tabs: **Users**, **Allowed emails**, and **Service accounts**.
### Users
The **Users** tab displays a list of all domain users with their name, email, domain role, and action buttons.
The **Domain owner** is displayed at the top of the page. Use the **Search username** box and **All users** dropdown to filter by name or role.
Each user row shows:
| Column | Description |
| --------------- | ---------------------------------------------------- |
| **Name** | The user's display name. Click to view user details. |
| **Email** | The user's email address. |
| **Domain role** | Admin or User. |
| **Actions** | View user details or delete the user. |
#### Change Domain Owner
To change the domain owner, click **Change owner** at the top of the Users tab.
The domain owner is the primary administrator and main point of contact for the domain. They receive monthly emails about BIC balances and are automatically assigned to any new orders placed for the domain. Enter the new owner's email address and click **Change owner**.
{% hint style="info" %}
Assigning a domain owner automatically makes them a domain administrator. The previous domain owner will remain a domain administrator.
{% endhint %}
#### Invite Users
To invite users to the domain, click **+ Invite** at the top of the Users tab. Enter one or more email addresses to send domain invitations.
### Allowed Emails
The **Allowed emails** tab controls which email addresses can join the domain.
| Setting | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Allowed email addresses** | Users can join the domain if their email exactly matches one of these addresses. |
| **Allowed email suffixes** | Users can join the domain if their email contains one of these suffixes (do not include the @ symbol). |
{% hint style="warning" %}
It is not recommended to allow common email suffixes such as gmail.com.
{% endhint %}
Click **Edit** to add or remove allowed emails and suffixes.
### Service Accounts
The **Service accounts** tab displays special accounts used by applications or services to interact with the domain without requiring a user to log in.
Toggle **Enable service accounts** to allow or block service accounts. When disabled, existing service accounts are blocked and new ones cannot be created.
The service accounts table shows each account's PGUID, status, activation date, expiration date, associated application, and action buttons. Click the **manage** icon in the Actions column to view the account's state and API keys.
## Access
The **Access** section allows you to restrict domain access by IP address or CIDR range.
Select a method of access management:
* **Create an allow-list for IP addresses/CIDR to allow access** — Only the specified addresses will be allowed.
* **Create a block-list of IP addresses/CIDR to block access** — The specified addresses will be blocked.
Enter IP addresses or CIDR ranges separated by commas (e.g., `192.10.10.1`, `192.255.10.*`, `192.10.10.0/32`). Click **Edit** to modify these settings.
## Collaboration
The **Collaboration** section allows you to configure the collaboration domain namespaces for inviting users via Collaborative Enterprise.
Enter a domain namespace and click **Edit** to add it to the allowed list. Users from these namespaces can be invited to workgroups via Collaborative Enterprise.
## Roles
The **Roles** section allows domain administrators to create and manage custom roles with unique permission settings that provide access control within workgroups.
{% hint style="warning" %}
Be cautious when applying custom roles — incorrect setup may lead to restricted access and unexpected issues.
{% endhint %}
Use the **Search** box to filter by application name or role name. The table displays each role's name, associated application, description, type (System or Custom), last modified date, and available actions.
Click a role name to view its detailed permissions. To create a new role, click **+ Create role**, select an application, enter a role name and optional description, and select at least one permission.
## Authentication
The **Authentication** section allows you to configure the domain's authentication method.
#### Authentication Type
| Type | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Default** | The Illumina Authentication System manages user credentials. |
| **SAML** | Users are redirected to your Identity Provider (IdP) to authenticate via SAML 2.0 (see [Single Sign-On](#single-sign-on-sso) below). |
#### Multi-Factor Authentication (MFA)
{% hint style="info" %}
If your Authentication Type is configured to SAML, MFA settings are managed by your SAML provider.
{% endhint %}
| Setting | Description |
| -------------------------------------- | -------------------------------------------------------------------------------- |
| **Require MFA** | Enable or disable multi-factor authentication for the domain. |
| **Users need to configure MFA within** | The number of days users have to complete MFA setup before it becomes mandatory. |
| **Lock user account after** | The number of unsuccessful MFA attempts before the account is locked. |
Click **Edit** to modify authentication settings.
### Single Sign-On (SSO)
{% hint style="warning" %}
SSO requires an Illumina BioInsight Platform (formerly Connected Software) domain subscription. It is not available for BaseSpace Free Trial or BaseSpace Professional accounts, which do not include a domain.
{% endhint %}
To enable logging into the platform using your organization's identity provider (IdP), configure SAML in the Authentication section.
To configure SSO, follow these steps:
1. Verify your organization's DNS domain in Illumina BioInsight Platform (formerly Connected Software).
2. Create a SAML 2.0 application in your IdP.
3. Configure ICS with your IdP metadata and attribute mappings.
4. Switch your domain authentication to SAML and test.
#### Prerequisites
* An active **Illumina domain subscription**
* A domain administrator account for your Illumina domain
* Access to your IdP to configure the SP application
* Your IdP configurations:
1. Metadata XML
2. SAML Attributes for EmailId, firstName, LastName
#### Configure DNS Domain
**Step 1: Create DNS Domain record**
1. Go to the [Admin Console](https://platform.login.illumina.com/iam) for your Illumina domain, and navigate to the **Domain** tab.
2. Navigate to the **DNS domain** menu.
3. Enter your domain (e.g., company.com) and click **Add**.
4. Copy the TXT record value for the new entry.
**Step 2: Verify DNS Domain**
To confirm domain ownership, add a TXT record to your Domain Name System (DNS) host using the TXT Record Value. DNS propagation can take up to 72 hours. Illumina BioInsight Platform (formerly Connected Software) automatically checks for the record during this time.
{% tabs %}
{% tab title="AWS Route 53" %}
1. To add your TXT record to AWS, see [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html).
2. Wait up to 72 hours for TXT record verification.
3. After the record is live, go to **DNS domain** in the Admin Console and select **Verify**.
{% endtab %}
{% tab title="Google Cloud DNS" %}
1. To add your TXT record to Google Cloud DNS, see [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt).
2. Wait up to 72 hours for TXT record verification.
3. After the record is live, go to **DNS domain** in the Admin Console and select **Verify**.
{% endtab %}
{% tab title="GoDaddy" %}
1. To add your TXT record to GoDaddy, see [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232).
2. Wait up to 72 hours for TXT record verification.
3. After the record is live, go to **DNS domain** in the Admin Console and select **Verify**.
{% endtab %}
{% tab title="Other providers" %}
1. Sign in to your domain host.
2. Add a TXT record to your DNS settings and save the record.
3. Wait up to 72 hours for TXT record verification.
4. After the record is live, go to **DNS domain** in the Admin Console and select **Verify**.
{% endtab %}
{% endtabs %}
#### Connect SSO
**Step 1: Create SSO connection in IdP**
The Illumina BioInsight Platform (formerly Connected Software) service provider (SP) application uses the following configuration:
* **Entity ID**: `https://login.illumina.com/saml-service/saml/metadata`
* **ACS (Assertion Consumer Service) URL**: `https://login.illumina.com/saml-service/saml/SSO`
* **Binding**: HTTP-POST
* **NameID Format**: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
{% tabs %}
{% tab title="Okta" %}
1. Sign in to your Okta account and open the Admin portal.
2. Select **Administration** and then **Create App Integration**.
3. Select **SAML 2.0**, then **Next**.
4. Name your app "Illumina BioInsight Platform".
5. Optional: Upload a logo.
6. Paste the service provider configuration values from above:
* ACS URL → **Single Sign On URL**
* Entity ID → **Audience URI (SP Entity ID)**
7. Configure the following settings:
* Name ID format: `EmailAddress`
* Application username: `Email`
* Update application username on: `Create and update`
8. Under **Attribute Statements**, enter the following Name → Value attributes. Make sure the **Name format** is set to "URI Reference."
1. email → user.email
2. first → user.firstName
3. last → user.lastName
9. Select **Next**.
10. Select the **This is an internal app that we have created** checkbox.
11. Select **Finish**.
{% endtab %}
{% tab title="Microsoft Entra ID" %}
1. Sign in to Microsoft Entra (formerly Azure AD).
2. Select **Default Directory** > **Add** > **Enterprise Application**.
3. Choose **Create your own application**, name it "Illumina BioInsight Platform", and choose **Non-gallery**.
4. After creating your app, go to **Single Sign-On** and select **SAML**.
5. Select **Edit** on the **Basic SAML configuration** section.
6. Edit **Basic SAML configuration** and paste values from above:
* Entity ID → **Identifier**
* ACS URL → **Reply URL**
7. Save the configuration.
8. From the **SAML Signing Certificate** section, download the **Federation Metadata XML**.
{% endtab %}
{% endtabs %}
**Step 2: Connect Illumina BioInsight Platform (formerly Connected Software) to your IdP**
Complete the integration by pasting your IdP values into Illumina BioInsight Platform:
1. Go to the [Admin Console](https://platform.login.illumina.com/iam) for your Illumina domain, and navigate to the **Domain** tab.
2. Navigate to the **Authentication** menu and enable the **SAML** Authentication Type.
{% tabs %}
{% tab title="Okta" %}
1. In Okta, select your app and go to **View SAML setup instructions**.
2. Copy the Identity Provider **Single Sign-in URL**.
3. Copy and paste the **IDP Metadata** into a text editor. Save the file.
4. Return to the Illumina BioInsight Platform Admin Console.
5. Paste the **Sign-in URL** in the IdP URL field.
6. Upload the IDP Metadata file to the "Select SAML Configuration File" file uploader.
7. Add the SAML Attribute Mappings:
* EmailId → email
* Last name → last
* First name → first
8. Review and select **Save**.
{% endtab %}
{% tab title="Microsoft Entra ID" %}
1. In Entra ID, copy the **Login URL** from the Configuration URLs.
2. Return to the Illumina BioInsight Platform Admin Console.
3. Paste the **Login URL** in the IdP URL field.
4. Upload the **Federation Metadata XML** file to the "Select SAML Configuration File" file uploader.
5. Add the SAML Attribute mappings:
* EmailId →
* Last name →
* First name →
6. Review and select **Save**.
{% endtab %}
{% endtabs %}
Allow 15 minutes for the Illumina Service Provider to update with the provided information. To confirm SAML configuration changes, attempt to log in using a qualified email (e.g., @company.com).
## Passwords
{% hint style="warning" %}
**Deprecated —** [**PCN 2026-1866**](https://sharecontent.illumina.com/i/GihqYR4sJQkt62H4Tf6rw0vKP2SxHbFmAC___4eHin8IWMeQeDtEXvL6PLUSSIGNOt0mPLUSSIGNc3___DL26wgUV3IZs9jeH9X1kutzTsudNQaVBwTIODpnCeK1UPu4tlkYizMg1cMoh5EapPLUSSIGN)
Domain password policy settings have been deprecated. Minimum password complexity across the Illumina BioInsight Platform now meets or exceeds any previously configurable policy, so these settings are no longer available.
To manage custom password settings, configure [Single Sign-On (SSO)](#single-sign-on-sso) for your domain.
{% endhint %}
# Software Billing
Illumina software usage is measured in two ways:
* **Illumina BioInsight Credits (BIC)**: Used for data analysis, computation, storage, and transfer. BIC is the unified currency for all Illumina software products.
* **Samples**: Used for interpreting sequenced samples on products that have not yet transitioned to BIC pricing. Different types exist based on the software and use case, such as:
* Emedgene Genomic Equivalent Samples
* Emedgene Array Samples
* Illumina Connected Insights Genomic Equivalent Samples
{% hint style="info" %}
If you previously used iCredits, your existing balance has been automatically converted to BIC at a 1:1 ratio. No action is required. Your balance amount remains the same.
{% endhint %}
{% hint style="info" %}
If you signed up for the platform through self-serve (Free Trial or PAYG), see [Subscriptions](https://github.com/illumina-swi/ics-docs/tree/main/docs/account-management/getting-started.md) for details on your subscription type and billing.
{% endhint %}
Ensure you purchase the correct samples for your workflow requirements. Products are transitioning to BIC pricing on a rolling schedule. Please see the migration timeline below.
## Illumina software products and usage pricing overview
Below are the Illumina software products, their BIC pricing availability, and usage details:
| Product | BIC Pricing Live | Usage Types |
| --------------------------------------- | ---------------- | ------------------------------------------------ |
| BioInsight Platform Core (formerly ICA) | August 4, 2026 | Compute, storage, scratch storage, data transfer |
| BaseSpace Sequence Hub (BSSH) | August 4, 2026 | Compute, storage, apps |
| Connected Multiomics (ICM) | August 4, 2026 | Compute, storage |
| Illumina Connected Insights (ICI) | September 2026 | Panel analysis, genomic interpretation |
| Emedgene | October 2026 | Genomic analysis |
BioInsight Platform Core (formerly ICA)
**BioInsight Platform Core (formerly ICA)** is a cloud-based platform for omics data management and analysis. Charges for storage and compute workloads are in BIC. For pricing details, visit the [BioInsight Platform Core Pricing](https://help.connected.illumina.com/connected-analytics/reference/r-pricing) page.
BaseSpace Sequence Hub
**BaseSpace Sequence Hub** provides genomic data analysis, storage, instrument connectivity, and run planning. It supports apps for alignment, variant calling, and data visualization. Costs for storage, compute, and apps are in BIC. For pricing details, visit [BaseSpace Pricing](https://help.connected.illumina.com/basespace/manage-your-account/icredits-and-billing) page.
Connected Multiomics
**Connected Multiomics (ICM)** is a cloud platform for biologists and bioinformaticians to analyze multiomics data efficiently. It organizes data into studies, applies statistical methods, references biological databases, correlates results across data types, and offers visualization tools for interpretation. Costs for this streamlined data analysis are in BIC. For pricing details, visit [ICM Pricing](https://help.connected.illumina.com/icm/reference/icredits) page.
Illumina Connected Insights
**Illumina Connected Insights (ICI)** is a robust software for interpreting and reporting NGS data. It processes DNA and RNA oncology assay data, supporting common tumor variants like SNVs, indels, CNVs, SVs, fusions, and splice variants, as well as biomarkers such as TMB, MSI, and GIS for HRD assessment. By integrating with multiple genomic databases, it provides biological insights and creates tailored summary reports.
There are two ways to access Connected Insights:
* Cloud - Costs for cloud analysis are charged in Genomic Samples (GEs) and costs for data storage on BioInsight Platform Core are charged in BIC. GEs will transition to BIC-based product allowances in September 2026.
* Local - Costs for local analysis via DRAGEN Server are charged in GEs.
For pricing details, visit [ICI Pricing](https://help.connected.illumina.com/connected-insights/resources-and-references/usg-introduction) page. ICI will transition to BIC-based pricing in September 2026.
Emedgene
Emedgene unlocks genomic insights for hereditary disease and streamlines your tertiary analysis workflows. The Emedgene platform is divided into two applications:
* **Analyze** - Genomic analysis workbench, where you can accession, interpret, curate and report on your cases, while also efficiently managing the lab workflow
* **Curate** - A repository for all of your organizational curated knowledge
Costs for this analysis are in Genomic Samples (GEs). GEs will transition to BIC-based pricing in October 2026.
## How Your Usage is Priced
When you use Illumina software, the system automatically applies the best available rate from your account. Each usage event is priced using exactly one mechanism, checked in this order:
| Priority | Pricing Mechanism | Description |
| -------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Usage Discount Rate | A negotiated discount rate applied at the time of each usage event for a specific product or usage type. The discount is realized when you consume the service, not at purchase. |
| 2 | Savings Plan | A cross-product percentage discount earned by making an upfront BIC commitment. Applies automatically to all eligible usage events across your account. |
| 3 | List Price | The standard BIC rate for the usage type. |
{% hint style="info" %}
**Best discount guarantee:** If you have both a Usage Discount Rate and a Savings Plan discount, the system automatically applies whichever gives you the greater savings at the time of each usage event. Discounts are never stacked — only one pricing mechanism applies per event.
{% endhint %}
### Discountable vs. Non-Discountable Usage
Savings Plan discounts and Usage Discount Rates apply only to usage types that do not pass through underlying infrastructure costs.
| Category | Examples | Discount Eligible? |
| --------------------------------------- | ----------------------------------------------- | ------------------------------------------------ |
| Cloud Infrastructure (Non-Discountable) | Compute, storage, scratch storage | No; always billed at list price |
| Everything else (Discountable) | DRAGEN pipelines, Emedgene analyses, ICI panels | Yes; Savings Plan and Usage Discount Rates apply |
## Savings Plans
Save on eligible Illumina software usage by purchasing a Savings Plan. The more you commit, and the longer your term, the higher your discount. Savings Plans provide cross-product discounts that automatically apply to all eligible usage events across your account.
### How Savings Plans Work
* Commit to a BIC amount for a defined term.
* Available commitment amounts range from 50,000 BIC to 10,000,000 BIC.
* Term options: 1 year, 3 years, or 5 years.
* Discounts vary based on your commitment amount and term length.
* Your discount applies automatically at the time of each usage event. There is no manual action needed.
Contact your Illumina sales representative for detailed pricing and to find the right Savings Plan for your organization.
### Multiple Savings Plans
If you hold multiple active Savings Plans, the best (highest) discount is always applied. Expired plans do not contribute to your available discount.
### Savings Plan Expiration
Your Savings Plan discount remains active for the full term of your commitment. When your commitment term ends, usage is billed at list price or your next-best active discount. Any pipelines started before expiration complete at the original discounted rate.
{% hint style="warning" %}
**Important:** Your BIC balance and your Savings Plan discount have independent expiration timelines. When a Savings Plan expires, the discount benefit ends — but your BIC balance may also have its own expiration date. Review both your balance expiry and your Savings Plan term in Usage Explorer to stay informed.
{% endhint %}
## Billing Model Overview
### Platform Usage
**All software usage** is eligible for charging. This includes any compute, storage, data transfer, or other metered activity associated with your account.
We recommend that you regularly review your usage and understand how costs accrue, both in one-time costs, such as compute events, or ongoing, such as storage. You are responsible for **stopping usage and deleting any data/storage** you no longer want to pay for.
{% hint style="info" %}
Billing is usage-based: if resources continue running or data remains stored on the platform, costs continue to accrue. To avoid charges, please shut down usage and remove data you no longer need.
{% endhint %}
### Usage Tracking
The [Usage Explorer](https://help.connected.illumina.com/account-management/usage-explorer) is your central tool for managing and optimizing software consumption at Illumina. It helps you to:
**Monitor Usage in Real Time**
* Track how BIC or samples are consumed across various products and projects.
**Manage Billing Balances**
* Easily view **Pre-Funded** and **Post-Paid** balances at a glance.
* View your active Savings Plan discount rate and expiration date.
* View consumption details showing the rate applied per event.
* View discount savings per transaction.
**Audit and Forecast**
* Access detailed monthly usage statements.
* Generate custom usage reports to analyze trends, forecast future needs, and prevent unexpected costs.
**Optimize Behavior**
* Identify high-usage patterns and adjust workflows to remain within budget.
### How software usage is billed
Software usage requires a subscription and can be billed through either **monthly invoicing** or **pre-funded credits**.
#### BIC Billing
We offer two billing options for BIC. Use [Usage Explorer](/account-management/usage-explorer) to understand your BIC consumption.
**1. Post-Paid (Monthly Invoicing) Billing:**
* You pay for usage **after it occurs**, billing is in monthly arrears.
* This is the **default billing method.** There are two mechanisms for payment:
* **Credit Card:** At the start of each month, your credit card will be charged to cover the prior month's BIC usage. Usage Explorer shows details of what activities contributed to the BIC consumption.
* **Purchase Order (PO):** Illumina customers can supply a Purchase Order to purchase BioInsight Credits (BIC) to cover for BioInsight Platform usage. Two types of Purchase Order are supported:
* **Upfront PO:** Your entire PO is invoiced immediately, all credits are applied to your tenant and show up in the Usage Explorer. As the platform is used, credits are consumed and the Usage Explorer shows the credit balance.
* **Open PO:** At the start of each month, your PO is invoiced in the amount of BIC sufficient to cover the prior months usage. Usage Explorer shows details of what activities contributed to the BIC consumption.
* [**Support/Customer Care**](#help-and-support) can assist with any questions about the various payment mechanisms.
* Invoices are sent to the Bill-To contact on your account — typically your organization's Finance or Accounts Payable team, or another designated recipient. Some customers also receive invoices through portals like Ariba or Coupa, depending on their setup. If you need to update the Bill-To contact or add additional recipients, [**Support/Customer Care**](#help-and-support) can assist.
* If you do not purchase or contract any pre-funded BIC in advance, your usage will be billed automatically at the end of the month.
**2. Pre-Funded Billing:**
You can purchase BIC in advance of usage and draw down from your balance as you incur usage. You should submit either a purchase order for the BIC and a separate Open PO to cover any overages OR a single Open PO that covers a greater amount than the BIC purchase. The Open PO will not be drawn down until the pre-funded balance is negative, at which point you will switch to Post-Paid billing.
{% hint style="info" %}
**Pre-Paid BIC vs. Savings Plan:** Pre-Paid BIC is a simple upfront purchase at list price with no commitment term. A Savings Plan is an upfront commitment with a defined term that earns you a discount on eligible usage. Both add BIC to your account.
{% endhint %}
{% hint style="info" %}
**Important:** Any BIC usage beyond your Pre-Funded balance will be billed automatically via post-paid.
{% endhint %}
See an Example for Pre-funded billing
You purchase 1,000 BIC before March 1. If you use 800 by mid-month, your remaining balance is 200. Based on your average usage, you will likely need to purchase additional BIC before the billing period ends (March 31). If your balance reaches zero, any further usage will automatically switch to post-paid billing, which will be applied to your Open PO.
See an Example for Post-paid/Open PO billing
You contract an Open Purchase Order on Jan 1 for 10,000 BIC with an expiration date of December 31. Over the first 9 months, you use 8,000 BIC with variable usage. Each month, the appropriate amount of BIC is drawn down from the PO consistent with what was consumed in the prior month. On October 1, you have a balance of 2,000 BIC remaining.
#### Sample Billing
Only available through pre-funded billing for products that have not yet transitioned to BIC pricing.
* **Pre-paid Samples**
* You purchase a fixed amount of Samples upfront.
* Usage draws down from your balance until it reaches zero.
* When your balance runs out, you will need to purchase additional Samples to continue usage.
{% hint style="info" %}
Products are transitioning from Sample-based billing to BIC-based Product Allowances on a rolling schedule. See the migration timeline in the products section above.
{% endhint %}
## Pay-As-You-Go
New customers can start with a free trial and convert to Pay-As-You-Go (PAYG) billing when ready.
| Feature | Details |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| Available products | BioInsight Platform Core, BSSH, ICM |
| How billing works | Usage is billed monthly. No upfront commitment required. |
| Support fee | A support fee applies based on your usage level (a minimum fee or a percentage of usage, whichever is greater). |
| Converting from trial | Self-serve conversion. Usage from your conversion date forward is billed. |
PAYG customers have access to all products currently on BIC pricing. As additional products transition to BIC, they become available to PAYG customers automatically.
## Transitioning to BIC
If you are an existing Illumina software customer, here is what has changed and what you need to know.
### iCredits to BIC
Your existing iCredit balance has been automatically converted to BIC at a 1:1 ratio. If you had 5,000 iCredits, you now have 5,000 BIC. No action is required on your part.
| Item | Details |
| ---------------- | ---------------------------------------------------------------------------- |
| Conversion ratio | 1 iCredit = 1 BIC |
| Action required | None — automatic |
| New purchases | iCredits are no longer available for purchase. All new purchases are in BIC. |
## How to avoid unintended charges
#### **Before Your Subscription Expires:**
* **Review active resources** (workflows, pipelines, jobs) and **stop** anything you no longer need.
* **Delete storage** and any temporary data you do not want to keep.
* **Download or export** anything you need to retain off-platform.
#### Best Practices to Avoid Unwanted Charges
* **Set alerts** in Usage Explorer (see [Notifications & Alerts](/account-management/usage-explorer/notifications-and-alerts)).
* **Schedule a pre-expiry cleanup**: shut down jobs and delete storage you do not need.
* **Use project tags/labels** to find and remove old or orphaned resources quickly.
* **Review** [Usage Explorer](/account-management/usage-explorer) **weekly** to catch unexpected activity.
## **Help and Support**
For customer service inquiries, email:
Visit our website at: [www.illumina.com](http://www.illumina.com)
# Usage Explorer
The Illumina Usage Explorer allows you to track your usage costs across Illumina cloud products with detailed insights and trends.
## Access Usage Explorer
To access the Usage Explorer, log in through the [domain login URL](https://ilmn.login.illumina.com/platform-home/#/home), and navigate to the [product dashboard](/account-management/platform-home). From there, select "Usage Explorer" from the list of available applications.
The Usage Explorer can also be accessed by clicking the top left waffle menu and selecting "Usage Explorer".
Access Usage Explorer from Waffle Menu
To access the Usage Explorer, login through the [Illumina login](https://login.illumina.com/login) to go to BioInsight Platform. From there, select “Usage” from the left navigation menu.
Access Usage Explorer from Left Navigation Menu
The usage shown here depends on your level of access to the Illumina software i.e. Domain Admin or User or Workgroup. For example, a domain admin has access to all domain usage, including users, workgroups, and ICA projects, while a workgroup or ICA project admin has access to usage within that specific workgroup or project, respectively.
## Overview
The Overview tab gives an overall summary about your usage and displays Trends and details of your usage data with a chart and a table at the granularity you choose. Also, provides a range of features to help you understand and optimize your resource usage such as Usage Reports, Cost Breakdown and Notification Alerts.
### Summary
Below the chart, a table summarizes the data and can be exported as a CSV file. The usage shown depends on several factors including your subscription and admin status. For example, a domain admin has access to all domain usage, including users, workgroups, and BioInsight Platform Core (formerly ICA) projects, while a workgroup or Platform Core project admin has access to usage within that specific workgroup or project, respectively.
The **Summary** section at the top of the Overview tab gives you a quick look at your account balances. Balances are separated into two categories:
Post-paid balances - Once your BIC usage goes beyond your prepaid BIC balance, your remaining monthly BIC usage will be invoiced on the first day of the following month.\
Pre-funded balances - Shows your current prepaid BIC and sample balance. You can purchase additional BIC directly from this section by clicking "Purchase more BIC".
Some of the Software consumables are **BIC**, ICI **Samples**, EMG Samples, PRS Samples and are charged based on the type of services. To learn more about software consumables and its pricing visit [Software Billing](/account-management/software-billing) page.
Domain admins have access to click "View account information" in the top right corner to see additional details about your account, subscription, and payment method.
### Monitoring
The **Monitoring** section provides a snapshot of your usage **History** with regards to Cost unit balance for the Software consumables (Cost units are the prepaid currency for services or products at Illumina).\
This section gives insights into consumption for the current month, quarter, and year, and details about your total storage space by tiers: **Standard and Archived**.\
You can also purchase more of the Cost units by clicking on the **Purchase more** external link.
The **Monitoring** section provides at-a-glance visibility into your storage footprint, support tier, and budget status. \\
\
Current total storage - Displays your total data stored, separated by **Standard** and **Archived** tiers. For data you don't need to access frequently, archiving it can reduce ongoing storage costs. \\
Support Tier - Shows your current support plan level (e.g., Basic). \\
Budget alerts - Set a monthly BIC budget and receive notifications when spending approaches your threshold. Toggle budget notifications on, then click "Edit budget settings" to specify a BIC threshold and add email recipients who should be notified.
{% hint style="info" %}
Budget notifications help you avoid unexpected costs by alerting you before your monthly usage exceeds the amount you've planned for. You can change or turn off the budget at any time.
{% endhint %}
Domain admins can manage usage by setting a budget threshold, and if set it will display in the summary section. To set a budget threshold, switch on the budget notifications toggle. You can see the percentage of your total usage of Cost unit next to the toggle. Click "**Edit budget settings**" to set a cost unit threshold and can share the budget threshold to any members of the domain via email.
### Trend & Details
The Trend & Details section gives you the ability to filter, group, and explore your usage. The controls on the right side have a variety of options (listed below in Filter options Table) that allow you to examine your data at the granularity you choose. Above the chart, usage and storage metrics such as Total usage, Monthly average, Standard storage and Archive storage are displayed that update with the filter settings.
You can use the following options and filters to customize usage data for trend and details:
### Filter Options Table
| Filter Name | Type | Description | Example Values |
| ---------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Date Range** | Date picker | Filters usage data for the selected period of time. | 08/06/2024 – 08/06/2025 |
|
The default range is set to one year to date. You can also set this to Monthly, Quarterly, Yearly, 5 years or 10 years.
| | | |
| **Time Granularity** | Dropdown | Filters usage data for the selected time range. | Monthly, Yearly or Daily based on the selected time period. |
| **Group By** | Dropdown | Filter usage data for the selected group. | Category, Usage context, Region, Product, Usage type etc., |
| **Cost Unit** | Dropdown | Filter usage data for the selected cost unit. | BIC, Samples, GEs etc., |
| **Category** | Dropdown | Filter usage data for the selected usage category. | Storage, Compute and Transfer. |
| **Product** | Dropdown | Filter usage data for the selected product | Basespace sequence hub, BioInsight Platform Core etc., |
| **Usage contexts** | Dropdown | Filter usage data for the selected Usage contexts. |
User, Workgroup, ICA project etc.,
|
| **User/Workgroup/ICA Project** | Dropdown | Based on the usage context selected you can further filter your usage by selecting a specific user or workgroup or ICA project. |
User - Workgroup – Arrays, Test workgroup etc., ICA project – Frankfurt, GDA project etc.,
|
| **Usage types** | Dropdown | Filter usage data for the selected Usage type. | Standard storage, Archive storage, ICA compute, ICA bench storage etc., |
| **Regions** | Dropdown | Filter usage data for the selected geographical region of usage/storage. | London, Canada etc., |
Below the chart, a table summarizes the data based on the applied filters and can be exported as a CSV file.
## Allowances, plans & rates
### Balance
Displays the total amount of available prepaid BIC on your account, either through savings plans or at list price. If no prepaid balance is available, usage will be invoiced monthly at list price.
### Allowances
Allowances are product-specific usage units that are consumed before your BIC balance.
### Discounts & Custom Rates
Savings Plan discounts — If you have an active Savings Plan, the associated discount is applied to eligible usage. \\
\
Custom rates — contracted that rates only apply to specific usage types. Not all usage is covered by custom rates. \\
\
In all cases, the best available rate is automatically applied to each usage event.
## Reports
The Reports tab allows you to download detailed usage reports in CSV format. Usage costs are reported at the most granular level available. \\
\
To generate a report: \\
\
1\. Select the report type from the "Report" dropdown (e.g., BIC, Samples, All). \\
2\. Choose a date range from the "Date range" dropdown (reports are available by month). \\
3\. Click "Download report" to export the CSV file. \\
\
The downloaded report contains line-item detail for each usage event in the selected period, including product, usage type, context, quantity, rating mechanism, and cost.
Selecting 'Other' from the Date Range filter allows you to choose a custom date range, up to three months.
By default, the reports are generated in the latest usage report format, which is more detailed, but the legacy option is also available to support existing processes.
The Latest reports provides comprehensive details about User account, Usage metrics and associated costs such as:
1. **Usage ID** - Random IDs generated for each of the usage.
2. **UC Name** - Customer name registered in the Illumina software system.
3. **Billable Account ID** - A unique ID for the account/domain.
4. **Account Name** - Associated account or domain name of the user.
5. **Account Type** - Type of the associated account such as domain or workgroup or user.
6. **Usage Context** - Name of the Usage Context Type e.g. For 'project' Usage Context Type the Usage context is 'Migration'.
7. **Usage Context Type** - Type of the context of usage e.g. User or Workgroup or Project.
8. **User Name** - Name of the user who used/consumed the usage i.e email id of the user.
9. **Product** - Name of the product the user has availed in Illumina e.g. Illumina Connected Analysis etc.,
10. **Usage Type Description** - Description of the usage type e.g. Standard storage, Archive storage etc.,
11. **Quantity** - Total quantity of the usage unit.
12. **Usage Unit** - Unit of usage e.g. TB-Months, BIC, Samples, etc.
13. **Category** - Category of usage e.g. Storage, Compute and Transfer.
14. **Usage Timestamp** - Date and time of the usage.
15. **Region** - Geographical region of usage/storage.
16. **Metadata** - Any additional information about the usage if available.
17. **Billing Date** - The date on which your usage charges are processed and billed
18. **Cost Unit** - The currency used to pay for the service or product (for example, BIC, Samples, or other prepaid units).
19. **Pricing Mechanism** - The pricing model applied to this usage event, such as an allowance, savings plan discount, or usage rate discount.
20. **List Rate** - The standard published rate for this type of usage before any discounts or pricing adjustments are applied.
21. **Applied Rate** - The actual rate used to calculate the cost of this usage event after any applicable pricing mechanisms have been applied.
22. **Cost** - The total cost of the usage event, calculated as **Quantity × Applied Rate**.
23. **Cost Saved** - The amount saved on this usage event due to a pricing mechanism, calculated as the difference between the List Rate and the Applied Rate.
# Notifications & Alerts
Illumina provides a range of automated notifications to help users effectively manage their usage and billing, focusing on low balances, threshold alerts, and invoice triggers.
**Usage Explorer Notifications**
* **BIC Monthly Budget Alerts**: Notifications are sent when your configured monthly budget threshold is reached, allowing you to monitor spending and take action before exceeding your planned usage. You can set up or adjust your monthly budget notification at any time in **Usage Explorer**.
**BIC Pre-Funded Billing Notifications**
* **Low Balance Alerts**: Notifications are sent when both Pre-Paid and contracted Open Purchase Order BIC balances are low.
**BIC Post-Paid Billing Notifications**
* **End of Billing Period Alerts**: Invoices are sent at the end of each billing cycle.
{% hint style="info" %}
Savings Plan expiration notifications are planned for a future release. At launch, your earliest possible commitment expiration is at least one year away, providing ample time for renewal planning.
{% endhint %}
This system ensures users can stay informed and proactive in managing their financial commitments efficiently.
# Custom Design Products
Custom design software helps create custom microarray probes and sequencing panels optimized for specific genomic content of interest. These software tools support a broad range of applications, including custom microarray-based genotyping applications, custom targeted amplicon sequencing, and custom target enrichment.
Refer to the respective documentation sites via the links below for more information. Access the full list of Illumina software products at the [Illumina Support Center](https://support.illumina.com/).
🖍️ Design tool for creating custom microarray probes for multiple species.
# Lab Management Products
Lab management software enables labs to track samples, streamline complex tasks, generate sample sheets, and catch poor quality samples before running them on a sequencing system.
Refer to the respective documentation sites via the links below for more information. Access the full list of Illumina software products at the [Illumina Support Center](https://support.illumina.com/).
🧪 Laboratory information management system (LIMS) for genomics labs.
# Run Set Up Products
Run set up refers to configuring settings for sequencing on Illumina instruments. In addition, users can provide settings for data analysis, location of the output data, and other parameters.
Sequencing runs can be set up using software applications and by downloading and editing sample sheet templates that are uploaded into the sequencer. The Run Planning tool in BaseSpace Sequence Hub and sample sheets are both generic and support run set-up for a broad spectrum of instruments and analysis pipelines. Other software applications support run set-up and analysis only for specific instruments, assays, and analysis pipelines.
Refer to the respective documentation sites via the links below for more information. Access the full list of Illumina software products at the [Illumina Support Center](https://support.illumina.com/).
🗓️ Includes Run Planning tool for run set-up and sample sheet generation.
# Run Workflows
## Cloud Orchestrated Cloud Analysis
The Cloud Orchestrated Cloud Analysis workflow streamlines sequencing run planning and cloud-based secondary analysis using the BaseSpace Sequence Hub Run Planning interface. With Cloud Orchestrated Cloud Analysis, you can plan a sequencing run for a specific instrument platform and configure the associated cloud secondary analysis using the BaseSpace Sequence Hub Run Planning interface. Once the run has been planned, any instrument of that platform can access and kick off the run, provided you log into the instrument using the same workgroup context as the run was planned in.
Sequencing runs using this workflow require you to upload your run data to BaseSpace Sequence Hub so that it can be used to run the associated secondary analysis.
Once the sequencing run is complete and all primary analysis data has been uploaded to BaseSpace Sequence Hub, the secondary analysis is automatically kicked off in the cloud and linked to the run in BaseSpace Sequence Hub.
{% hint style="info" %}
Current instrument platforms that support Cloud Orchestrated Cloud Analysis:
* NextSeq 1000 / NextSeq 2000
* NovaSeq X Series
* MiSeq i100 Series
{% endhint %}
***
## Cloud Orchestrated Local Analysis
The Cloud Orchestrated Local Analysis workflow enables you to plan your sequencing run (associated with a specific instrument platform) and the associated on-instrument secondary analysis using the BaseSpace Sequence Hub Run Planning interface. Once the run has been planned, any instrument of that platform can access and kick off the run, provided you log into the instrument using the same workgroup context as the run was planned in.
Sequencing runs using the Cloud Orchestrated Local Analysis workflow require you to send *at least* run monitoring data to BaseSpace Sequence Hub so that the run planned in the cloud can be kept in sync with the instrument.
Once the sequencing run is complete and all primary analysis data has been generated, the secondary analysis is automatically kicked off on the instrument as specified by the user during run planning.
{% hint style="info" %}
Current instrument platforms that support Cloud Orchestrated Local Analysis:
* NextSeq 1000 / NextSeq 2000
* MiSeq i100 Series
{% endhint %}
***
## Locally Orchestrated Local Analysis
The Locally Orchestrated Local Analysis workflow enables you to plan a sequencing run and associated on-instrument secondary analysis using the on-instrument Run Planning interface. Once the run has been planned, any user can access and kick off the run upon logging into the instrument.
Once the sequencing run is complete and all primary analysis data has been generated, the secondary analysis is automatically launched on the instrument, as specified by the user during run planning.
Sequencing runs using the Locally Orchestrated Local Analysis workflow enable you to use any level of cloud connectivity and data upload. On NovaSeq X Series or MiSeq i100 Series instruments, you can also optionally upload FastQ and BAM/CRAM files to the cloud if desired.
{% hint style="info" %}
Current instrument platforms that support Locally Orchestrated Local Analysis:
* NovaSeq X Series
* MiSeq i100 Series
{% endhint %}
***
## Manual Run with Sample Sheet Based Local Analysis
The Sample Sheet Driven Local Analysis workflow leverages DRAGEN on the instrument, relying on a sample sheet to provide the necessary details for orchestrating and executing the analysis directly onboard. In order to use this workflow, select the option when setting up a run to perform local analysis using a sample sheet, and attach the desired sample sheet to your run.
When using this workflow, the DRAGEN analysis is started onboard automatically when the sequencing data is in a ready state to begin analysis.
For optimal results, it is recommended to generate the initial sample sheet using the BaseSpace Sequence Hub Run Planning interface for local analysis. This will ensure proper formatting and acceptable values for all fields.
{% hint style="info" %}
Current instrument platforms that support Sample Sheet Driven Local Analysis:
* NextSeq 1000 / NextSeq 2000
* NovaSeqX Series
* MiSeq i100 Series
{% endhint %}
# Sample Sheet
### What is a Sample Sheet?
A sample sheet is a comma-separated value (\*.csv) file format used by Illumina instruments, platforms, and analysis pipelines to store settings and data for sequencing and analysis. The sample sheet uses American Standard Code for Information Interchange (ASCII) character encoding.
The system using the sample sheet as input validates the data within the sample sheet based on validation rules. Validation rules differ from section to section. Incorrectly formatted data are considered invalid and causes software to throw an error. Refer to the validation rules for each section for more information on acceptable formatting and allowable values.
### How to Use a Sample Sheet?
A v2 sample sheet can be obtained from one of the following options.
1. A v2 sample sheet can be created in BaseSpace using Run Planning.
1. In BaseSpace Sequence Hub, select the **Runs** tab > **New Run** > **Run Planning** > **Local Mode** > **Export Sample Sheet**.
2. For this option, all sample and index information is entered in Run Planning and is included in the exported v2 sample sheet.
2. A v2 sample sheet template can be downloaded and filled out manually.
1. Download the template with the link below and use a text editor program to alter the sections according to your chosen instrument or analysis. *Using a spreadsheet editor can cause errors with sample sheet validation and analysis. Save the sample sheet to a folder accessible by your instrument or analysis software.*
2. Follow instructions to fill out the sample sheet. See resources below:
1. [Sample Sheet Structure](/run-set-up/overview/sample-sheet-structure)
2. [Instrument Settings](/run-set-up/overview/instrument-settings)
3. [Cloud Analysis Auto-launch Settings](/run-set-up/overview/auto-launch-settings)
4. [Index Orientation Guide](/run-set-up/overview/index-orientation-guide)
5. [Resources](/run-set-up/overview/resources)
3. Download [SampleSheet\_v2\_template.csv](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6HNTm8iYkD7XsLmbBKpL%2Fuploads%2FRWeWpFrs9RdtRlP00Z3P%2FSampleSheet_v2_template.csv?alt=media\&token=3db5253a-8c99-4314-bcdd-5f01732eccdf)
# Sample Sheet Structure
The information contained within a sample sheet is organized into various sections, like Header, Reads, Manifests, Data, and Settings. There are two types of sections:
**Standalone sections**—Contain run settings and data that do not pertain to a specific application.
**Applications sections**—Contain run settings and data required by specific applications.
### Standalone Sections
The Header and Reads sections contain run settings and data. The Header and Reads sections are present in every v2 sample sheet. Additional standalone sections such as Sequencing Settings can be added and do not produce an error.
A new section includes a section header that precedes the data contained within the section. A section header consists of the name of the section within brackets, as seen in the first line of the following example.
```
[Header],,,
FileFormatVersion,2,,
RunName,MyRun,,
InstrumentPlatform,NextSeq1k2k,,
InstrumentType,NextSeq2000,,
,,,
```
### Application Sections
The application sections contain data required to run Illumina applications. Application settings differ from instrument to instrument. Refer to the applicable[ instrument settings](/run-set-up/overview/instrument-settings) section.
Designate an applications section by appending Settings or Data to the section name as seen in the following example.
```
,,,
[BCLConvert_Settings],,,
SoftwareVersion,x.y.z,,
,,,
,,,
[BCLConvert_Data],,,
Lane,Sample_ID,index,index2
1,S01-TOO-12plex-P1-rep1,ATCCACTG,AGGTGCGT
1,S02-TOO-12plex-P1-rep2,GCTTGTCA,GAACATAC
1,S03-TOO-12plex-P1-rep3,GCTTGTCA,GAACATAC
1,S04-TOO-12plex-P1-rep4,GCTTGTCA,GAACATAC
```
Each application can have a maximum of one Settings section and one Data section.
**Settings section**—This section contains key-value pairs that configure settings for the application, as seen in the example. The Settings section is applied globally to all samples.
**Data section**—This section contains per sample data (in tabular format) used as input by the given application. The data in the first non-empty line of the application data section forms the column headers for the rest of the section. The Data section is uniquely applied to each sample.
# Section Requirements
Section Type
Requirements
All sections
Data items cannot contain commas.
Supported line endings are \n, \r\n, and .
Required characters are all ASCII characters except for * and the control characters CR and LF.
Standalone
Only key-value pairs are supported.
Each key must have exactly one value.
The same key cannot be specified more than one time in a single standalone section.
Opening and closing brackets are both required, and must be the first and last character in the section header line (other than whitespace and commas).
A standalone section cannot be empty.
Data in standalone sections must not contain brackets.
Header
There can only be one data item in a section header line.
Section headers are required to start with an opening square bracket, and end with a closing square bracket
Opening and closing brackets are both required, and must be the first and last character in the section header line (other than whitespace and commas)
Application
The application name cannot include Settings or Data.
The application name cannot be empty.
The application name cannot include -.
Each application can have a maximum of one Settings section and one Data section.
Application Settings
Settings sections can support only key-value pairs.
Each key can have only one value.
The application name cannot include -.
Applications sections cannot be empty. At least one key-value pair must be specified.
Keys and values cannot contain [ or ].
Note: The Settings section is applied globally to all samples.
Application Data
For each line that follows the column header line in the application data section, the number of empty plus non-empty data items cannot be less than the number of column headers.
For each line that follows the column header line in the Application Data section, the number of non-empty values cannot be greater than the number of column headers.
Column headers must all be unique.
Each application data section must contain a column header called Sample_ID.
Column headers and values cannot contain [ or ].
Note: The Data section is uniquely applied to each sample.
# BCL Convert Interactive Sample Sheet
Below you can find an interactive sample sheet with example values filled out for BCL Convert. Click on the dotted underlines for pop-ups with more information on each section.
[^1]: The Header is a standalone section which provides information about the run.
[^2]: This field must exist in the header section with a value of 2 in order to identify the sample sheet as a v2 sample sheet.
[^3]: Used to capture the name of your run.
[^4]: Identifies the instrument platform to be used for the run.
[^5]: Specifies the direction you wrote your indices. If forward, the software will automatically create the reverse complement of the sequences provided for the appropriate instrument type.
[^6]: Reads is a standalone section which contains information about the read cycles and index cycles.
[^7]: Number of cycles for Read 1.
[^8]: Number of cycles for Read 2. Required only when running a paired-end sequencing run.
[^9]: Number of cycles in Index Read 1. Required if more than one sample is present in sample sheet.
[^10]: Number of cycles in Index Read 2. Required if using dual indexes for demultiplexing.
[^11]: This section contains key-value pairs that configure settings for the application, as seen in the example. The Settings section is applied globally to all samples.
[^12]: Software version of BCL Convert analysis
[^13]: If set to false or 0, UMI sequences are not trimmed from output FASTQ reads. The UMI is still placed in sequence header.
[^14]: Specifies the sequencing and indexing cycles to be used when processing the sequencing data.
* `Y`—Specifies a sequencing read
* `I`—Specifies an indexing read
* `U`—Specifies a UMI cycle
* `N`—Specifies trimmed reads
For instruments with `RunInfo.xml`having IsReverseComplement set to `Y` for Index2, then Index2 is processed in reverse complement orientation. Apply any trimming to the end of the sequence as it transitions to the adapter, which means the N cycles specified in OverrideCycles must be in the beginning of the Index Read.
Example of 8 bp i5 index with the last two (adapter) bases to be trimmed where XX is part of the adapter sequence.
* Forward i5: `XXATCGCGGT`
* ReverseComp i5: `ACCGCGATXX`(this is the direction of sequencing)
* OverrideCycles for Index2: `N2I8`
Although Index2 is processed on the instrument in reverse complement format, Index2 and OverrideCycles are entered in the sample sheet in forward, non-complemented format for user convenience.
[^15]: The compression format for the FASTQ output files. Example values are `gzip` or `dragen`.
[^16]: This section contains per sample data (in tabular format) used as input by the given application. The data in the first non-empty line of the application data section forms the column headers for the rest of the section. The Data section is uniquely applied to each sample.
[^17]: Specifies the analyses to be launched. Analyses to be launched can be discovered by looking in the "**Cloud\_Settings**" section for key's ending in '\_Pipeline' with string prefix \ (ie, BCLConvert\_Pipeline).
[^18]: This value should always be set to ica\_workflow\_1 if doing cloud analysis. This section is not needed if doing local analysis.
[^19]: This analysis will be launched because it exists in the **Cloud\_Settings** section in the format \\_Pipeline. There must be corresponding "**\\_Settings**" and "**\\_Data**" sections present, which you can find in the rows above. This section is not needed if doing local analysis.
[^20]: This section contains data used for cloud analyses.
# Intrument Settings
The sample sheet for each instrument contains fields that must be filled accurately to specify the analyses to be performed. Refer to the instrument settings for sample sheet instructions specific to your instrument.
* [NovaSeq X Settings](/run-set-up/overview/instrument-settings/novaseq-x-series-settings)
* [NextSeq 1000/2000 Settings](/run-set-up/overview/instrument-settings/nextseq-1000-2000-settings)
# NovaSeq X Settings
## Standalone Sections
### Header Section
Parameter
Required
Description
Requirements
Custom_*
No
Custom field used to capture run metadata.
String with ASCII characters except for * and the control characters CR and LF.
FileFormatVersion
Yes
Used to identify the sample sheet as a v2 sample sheet. This field must always exist in the header section with a value of 2.
Must always be 2.
InstrumentPlatform
No
Identifies the instrument platform to be used for the run.
For example, enter NovaSeqXSeries for NovaSeq X Series.
String with ASCII characters except for * and the control characters CR and LF.
InstrumentType
No
Identifies the instrument to be used for the run.
For example: if using NovaSeq X, populate the field with NovaSeq X.
String with ASCII characters except for * and the control characters CR and LF.
RunDescription
No
The run description can contain 255 alphanumeric characters, spaces, dashes, and underscores.
String with ASCII characters except for * and the control characters CR and LF.
RunName
Yes
The run name can contain 255 alphanumeric characters, spaces, dashes, and underscores.
String with ASCII characters except for * and the control characters CR and LF.
### Reads Sections
Parameter
Required
Description
Requirements
Index1Cycles
No¹
Number of cycles in Index Read 1. Required if more than one sample is present in sample sheet.
Must be an integer ≥ 0.
Depending on your sequencing system and reagent kit, there can be limitations on the number of cycles in the Index Read.
Warning if values in range [1–5] inclusive.
If there is more than 1 sample per lane, must be > 0.
If OverrideCycles is present in the BCL_Settings section, must be consistent with the sum of the Index1 section of OverrideCycles.
Index2Cycles
No¹
Number of cycles in Index Read 2. Required if using dual indexes for demultiplexing.
Must be an integer ≥ 0.
Depending on your sequencing system and reagent kit, there can be limitations on the number of cycles in the Index Read.
Warning if values in range [1–5] inclusive.
If OverrideCycles is present in the BCL_Settings section, must be consistent with the sum of the Index1 section of OverrideCycles.
Read1Cycles
Yes
Number of cycles for Read 1.
Must be an integer > 0.
Warning if less than 26.
If OverrideCycles is present in the BCL_Settings section, must be consistent with the sum of the Read1 section of OverrideCycles.
Read2Cycles
Yes
Number of cycles for Read 2. Required only when running a paired-end sequencing run.
Must be an integer ≥ 0.
Warning if values in range [1–25] inclusive.
If OverrideCycles is present in the BCL_Settings section, must be consistent with the sum of the Read2 section of OverrideCycles.
¹ Depending on the run or library prep kit, this parameter might be required.
### Sequencing Section
Parameter
Required
Description
Requirements
CustomIndex1Primer
No¹
Indicates if a Custom Index 1 primer is used for the run.
Values true and false allowed. Value true only allowed if Index1Cycles is specified.
CustomIndex2Primer
No¹
Indicates if a Custom Index 2 primer is used for the run.
Values true and false allowed. Value true only allowed if Index2Cycles is specified.
CustomRead1Primer
No¹
Indicates if a Custom Read 1 primer is used for the run.
Values true and false allowed. Value true only allowed if Read1Cycles is specified.
CustomRead2Primer
No¹
Indicates if a Custom Read 2 primer is used for the run.
Values true and false allowed. Value true only allowed if Read2Cycles is specified.
LibraryPrepKits
Yes
Identifies the library prep kit used for the run.
String with ASCII characters except for * and the control characters CR and LF.
If more than one library prep kit is being used, use semicolons to separate the names of the different library prep kits.
¹ Depending on the run or library prep kit, this parameter might be required.
## Application Sections
For NovaSeq X Series, there is a limit of four application sections for onboard analysis or eight application sections for cloud analysis.
### BCL Convert
{% tabs %}
{% tab title="4.3.13" %}
**BCLConvert\_Settings**
Parameter
Required
Description
SoftwareVersion
Yes
The version of the software to be used to perform BCL conversion on the Sample_IDs that only exist in the BCL Convert Data section of the sample sheet. The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0.
FastqCompressionFormat
Yes
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
GenerateFastqcMetrics
No
Enable/disable generation of FAST QC Metrics. Default = False. If included in the Sample Sheet, then all DRAGEN versions (for BCL Convert and non-BCL Convert workflows) must be 4.3.13 or later. Not applicable for the Cloud pipeline mode.
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
AdapterRead2
No
See description of AdapterRead1, applied to AdapterRead2.
BarcodeMismatchesIndex1
No
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
BarcodeMismatchesIndex2
No
See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2.
OverrideCycles
No
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing each index cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 5 bases toward the limit of 27 for Index1, and as 5 bases toward the limit of 27 for Index2
"I4N1I3;I5N3": counts as 8 bases toward the limit of 27 for Index1, and as 5 bases toward the limit of 27 for Index2
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles:
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2.
Sample_ID
Yes
ID for the sample with the following requirements: • Must be alphanumeric string with _ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample_ID
Lane
Yes
Specifies FASTQ files only for the samples with the specified lane number.
Must adhere to the following requirements:
Must be an integer
Value must be in the range of lanes specified in RunInfo.xml
Ranges are not supported with '-' or '+'
If not supplied, it is assumed that all samples are present in all lanes specified in the RunInfo.xml
If supplied, only lanes specified in the column will be converted from BCL to FASTQ
For NovaSeqX, values must be in the range of lanes specified in RunInfo.xml
1.5B Flow Cell: 1-2
10B Flow Cell: 1-8
25B Flow Cell: 1-8
Index
Yes
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of NA must be used if:
No indexes are specified in OverrideCycles for a sample
The version of the software to be used to perform BCL conversion on the Sample_IDs that only exist in the BCL Convert Data section of the sample sheet., The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0.
FastqCompressionFormat
Yes
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
**BCLConvert\_Data**
Parameter
Required
Description
AdapterRead1
No
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
AdapterRead2
No
See description of AdapterRead1, applied to AdapterRead2.
BarcodeMismatchesIndex1
No
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
BarcodeMismatchesIndex2
No
See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2.
OverrideCycles
No
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml or and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2.
Sample_ID
Yes
ID for the sample with the following requirements: • Must be alphanumeric string with _ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample_ID
Lane
Yes
Specifies FASTQ files only for the samples with the specified lane number.
Must adhere to the following requirements:
Must be an integer
Value must be in the range of lanes specified in RunInfo.xml
Ranges are not supported with '-' or '+'
If not supplied, it is assumed that all samples are present in all lanes specified in the RunInfo.xml
If supplied, only lanes specified in the column will be converted from BCL to FASTQ
For NovaSeqX, values must be in the range of lanes specified in RunInfo.xml
1.5B Flow Cell: 1-2
10B Flow Cell: 1-8
25B Flow Cell: 1-8
Index
Yes
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
The version of the software to be used to perform BCL conversion on the Sample_IDs that only exist in the BCL Convert Data section of the sample sheet., The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0.
FastqCompressionFormat
Yes
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
**BCLConvert\_Data**
Parameter
Required
Description
AdapterRead1
No
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
AdapterRead2
No
See description of AdapterRead1, applied to AdapterRead2.
BarcodeMismatchesIndex1
No
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
BarcodeMismatchesIndex2
No
See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2.
OverrideCycles
No
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml or and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2.
Sample_ID
Yes
ID for the sample with the following requirements: • Must be alphanumeric string with _ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample_ID
Lane
Yes
Specifies FASTQ files only for the samples with the specified lane number.
Must adhere to the following requirements:
Must be an integer
Value must be in the range of lanes specified in RunInfo.xml
Ranges are not supported with '-' or '+'
If not supplied, it is assumed that all samples are present in all lanes specified in the RunInfo.xml
If supplied, only lanes specified in the column will be converted from BCL to FASTQ
For NovaSeqX, values must be in the range of lanes specified in RunInfo.xml
1.5B Flow Cell: 1-2
10B Flow Cell: 1-8
25B Flow Cell: 1-8
Index
Yes
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
The version of the software to be used to perform BCL conversion on the Sample_IDs that only exist in the BCL Convert Data section of the sample sheet., The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0.
FastqCompressionFormat
Yes
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
GenerateFastqcMetrics
No
Import option only. Enable/disable generation of FAST QC Metrics. Default = True.
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
AdapterRead2
No
See description of AdapterRead1, applied to AdapterRead2.
BarcodeMismatchesIndex1
No
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
BarcodeMismatchesIndex2
No
See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2.
OverrideCycles
No
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing each index cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 5 bases toward the limit of 27 for Index1, and as 5 bases toward the limit of 27 for Index2
"I4N1I3;I5N3": counts as 8 bases toward the limit of 27 for Index1, and as 5 bases toward the limit of 27 for Index2
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2.
Sample_ID
Yes
ID for the sample with the following requirements: • Must be alphanumeric string with _ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample_ID
Lane
Yes
Specifies FASTQ files only for the samples with the specified lane number.
Must adhere to the following requirements:
Must be an integer
Value must be in the range of lanes specified in RunInfo.xml
Ranges are not supported with '-' or '+'
If not supplied, it is assumed that all samples are present in all lanes specified in the RunInfo.xml
If supplied, only lanes specified in the column will be converted from BCL to FASTQ
For NovaSeqX, values must be in the range of lanes specified in RunInfo.xml
1.5B Flow Cell: 1-2
10B Flow Cell: 1-8
25B Flow Cell: 1-8
Index
Yes
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
The version of the DRAGEN software used to process the DragenGermline pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN Germline), using all three integers included in the version name. For example, 1.0.0.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. If MapAlignOutFormat is None, VariantCallingMode cannot be None for any sample.
**DragenGermline\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".".
VariantCallingMode
Yes
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, CNV, Repeat Expansions, ROH, CYP2D6, CYP2B6, CYP21A2, SMN, GBA, LPA, RH, and SMN (silent carrier).
QcCoverage1BedFile
No
File name in text (*.txt) or gzip (*.gz) format. Must include the prefix DragenGermline/. Alphanumeric string with underscores (_) or dashes (-) or periods (.) with no spaces allowed. If QcCoverage1BedFile exists in the Data section, but a file is not provided, a value of na must be specified.
QcCoverage2BedFile
No
File name in text (*.txt) or gzip (*.gz) format. Must include the prefix DragenGermline/. Alphanumeric string with underscores (_) or dashes (-) or periods (.) with no spaces allowed. If QcCoverage2BedFile exists in the Data section, but a file is not provided, a value of na must be specified.
QcCoverage3BedFile
No
File name in text (*.txt) or gzip (*.gz) format. Must include the prefix DragenGermline/. Alphanumeric string with underscores (_) or dashes (-) or periods (.) with no spaces allowed. If QcCoverage3BedFile exists in the Data section, but a file is not provided, a value of na must be specified.
QcCrossContaminationVcfFile
No
File name in text (*.txt) or gzip (*.gz) format. Must include the prefix DragenGermline/. Alphanumeric string with underscores (_) or dashes (-) or periods (.) with no spaces allowed. If QcCrossContaminationVcfFile exists in the Data section, but a file is not provided, a value of na must be specified.
The version of the DRAGEN software, used to process the DragenGermline pipeline, including conversion to FASTQ, Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN Germline), using all three integers included in the version name. For example, 1.0.0.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. If MapAlignOutFormat is None, VariantCallingMode cannot be None for any sample.
**DragenGermline\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".".
VariantCallingMode
Yes
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, CNV, Repeat Expansions, ROH, CYP2D6, CYP2B6, CYP21A2, SMN, and GBA.
QcCoverage1BedFile
No
File name in text (*.txt) or gzip (*.gz) format. Must include the prefix DragenGermline/. Alphanumeric string with underscores (_) or dashes (-) or periods (.) with no spaces allowed. If QcCoverage1BedFile exists in the Data section, but a file is not provided, a value of na must be specified.
QcCoverage2BedFile
No
File name in text (*.txt) or gzip (*.gz) format. Must include the prefix DragenGermline/. Alphanumeric string with underscores (_) or dashes (-) or periods (.) with no spaces allowed. If QcCoverage2BedFile exists in the Data section, but a file is not provided, a value of na must be specified.
QcCoverage3BedFile
No
File name in text (*.txt) or gzip (*.gz) format. Must include the prefix DragenGermline/. Alphanumeric string with underscores (_) or dashes (-) or periods (.) with no spaces allowed. If QcCoverage3BedFile exists in the Data section, but a file is not provided, a value of na must be specified.
QcCrossContaminationVcfFile
No
File name in text (*.txt) or gzip (*.gz) format. Must include the prefix DragenGermline/. Alphanumeric string with underscores (_) or dashes (-) or periods (.) with no spaces allowed. If QcCrossContaminationVcfFile exists in the Data section, but a file is not provided, a value of na must be specified.
The version of the DRAGEN software, used to process the DragenGermline pipeline, including conversion to FASTQ, Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN Germline), using all three integers included in the version name. For example, 1.0.0.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. If MapAlignOutFormat is None, VariantCallingMode cannot be None for any sample.
**DragenGermline\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".".
VariantCallingMode
Yes
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, CNV, Repeat Expansions, ROH, CYP2D6, CYP2B6, CYP21A2, SMN, and GBA.
The version of the DRAGEN software, used to process the DragenGermline pipeline, including conversion to FASTQ, Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN Germline), using all three integers included in the version name. For example, 1.0.0.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. If MapAlignOutFormat is None, VariantCallingMode cannot be None for any sample.
**DragenGermline\_Data**
| Parameter | Required | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ReferenceGenomeDir | Yes | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| VariantCallingMode | Yes |
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, CNV, Repeat Expansions, ROH, CYP2D6.
The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN Enrichment), using all three integers included in the version name. For example, 1.0.0.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. If MapAlignOutFormat is None, VariantCallingMode cannot be None for any sample.
**DragenEnrichment\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".".
Bedfile
Conditionally required
BED file to be used for analysis in text (*.txt) or gzip (*.gz) format. Only required if VariantCallingMode is not None. Must include the prefix DragenEnrichment/ before the BED file name. Alphanumeric string with _ or - or . with no spaces allowed. The value must be na if BedFile is placed in the Data section and VariantCallingMode = None.
GermlineOrSomatic
Yes
Accepted values are germline or somatic.
AuxNoiseBaselineFile
No
Alphanumeric string with "_" or "-" or ".". and no spaces in text (*.txt) or gzip (*.gz) format. Applicable only if GermlineOrSomatic is Somatic and VariantCallingMode is not None.
The value must be na if AuxNoiseBaselineFile is placed in the Data section and no AuxNoiseBaselineFile is provided for the sample."
AuxCnvPanelOfNormalsFile
No
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxCnvPanelOfNormalsFile is placed in the Data section and no AuxCnvPanelOfNormalsFile is provided for the sample.
VariantCallingMode
Yes
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, and CNV callers (if panel of normals is provided).
AuxCnvPopBAlleleVcfFile
No
Alphanumeric string with _ or - or . with no spaces allowed. Text or gzip format. Optional only if VariantCallingMode = AllVariantCallers and GermlineOrSomatic=somatic. Error otherwise. A note should be added to the UI to indicate that CNV output will only be generated if this file is provided.
AuxGermlineTaggingFile
No
Alphanumeric string with _ or - or . with no spaces allowed. Binary file with .bin extension. Optional when SmallVariantCaller or AllVariantCaller option selected and GermlineOrSomatic=somatic. Error otherwise.
The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ, , Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN Enrichment), using all three integers included in the version name. For example, 1.0.0.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. If MapAlignOutFormat is None, VariantCallingMode cannot be None for any sample.
**DragenEnrichment\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".".
Bedfile
Conditionally required
BED file to be used for analysis in text (*.txt) or gzip (*.gz) format. Only required if VariantCallingMode is not None. Must include the prefix DragenEnrichment/ before the BED file name. Alphanumeric string with _ or - or . with no spaces allowed. The value must be na if BedFile is placed in the Data section and VariantCallingMode = None.
GermlineOrSomatic
Yes
Accepted values are germline or somatic.
AuxNoiseBaselineFile
No
Alphanumeric string with "_" or "-" or ".". and no spaces in text (*.txt) or gzip (*.gz) format. Applicable only if GermlineOrSomatic is Somatic and VariantCallingMode is not None.
The value must be na if AuxNoiseBaselineFile is placed in the Data section and no AuxNoiseBaselineFile is provided for the sample."
AuxCnvPanelOfNormalsFile
No
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxCnvPanelOfNormalsFile is placed in the Data section and no AuxCnvPanelOfNormalsFile is provided for the sample.
VariantCallingMode
Yes
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, and CNV callers (if panel of normals is provided).
The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ, , Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN Enrichment), using all three integers included in the version name. For example, 1.0.0.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. If MapAlignOutFormat is None, VariantCallingMode cannot be None for any sample.
**DragenEnrichment\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".".
Bedfile
Conditionally required
BED file to be used for analysis in text (*.txt) or gzip (*.gz) format. Only required if VariantCallingMode is not None. Must include the prefix DragenEnrichment/ before the BED file name. Alphanumeric string with _ or - or . with no spaces allowed. The value must be na if BedFile is placed in the Data section and VariantCallingMode = None.
GermlineOrSomatic
Yes
Accepted values are germline or somatic.
AuxNoiseBaselineFile
No
Alphanumeric string with "_" or "-" or ".". and no spaces in text (*.txt) or gzip (*.gz) format. Applicable only if GermlineOrSomatic is Somatic and VariantCallingMode is not None.
The value must be na if AuxNoiseBaselineFile is placed in the Data section and no AuxNoiseBaselineFile is provided for the sample."
AuxCnvPanelOfNormalsFile
No
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxCnvPanelOfNormalsFile is placed in the Data section and no AuxCnvPanelOfNormalsFile is provided for the sample.
VariantCallingMode
Yes
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, and CNV callers (if panel of normals is provided).
The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ, , Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN Enrichment), using all three integers included in the version name. For example, 1.0.0.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. If MapAlignOutFormat is None, VariantCallingMode cannot be None for any sample.
**DragenEnrichment\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".".
Bedfile
Conditionally required
BED file to be used for analysis in text (*.txt) or gzip (*.gz) format. Only required if VariantCallingMode is not None. Must include the prefix DragenEnrichment/ before the BED file name. Alphanumeric string with _ or - or . with no spaces allowed. The value must be na if BedFile is placed in the Data section and VariantCallingMode = None.
GermlineOrSomatic
Yes
Accepted values are germline or somatic.
AuxNoiseBaselineFile
No
Alphanumeric string with "_" or "-" or ".". and no spaces in text (*.txt) or gzip (*.gz) format. Applicable only if GermlineOrSomatic is Somatic and VariantCallingMode is not None.
The value must be na if AuxNoiseBaselineFile is placed in the Data section and no AuxNoiseBaselineFile is provided for the sample."
AuxCnvPanelOfNormalsFile
No
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxCnvPanelOfNormalsFile is placed in the Data section and no AuxCnvPanelOfNormalsFile is provided for the sample.
VariantCallingMode
Yes
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, and CNV callers (if panel of normals is provided).
The version of the DRAGEN software used to process the DragenRna pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN RNA), using all three integers included in the version name. For example, 1.0.0.
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. Selecting none is not allowed if RnaPipelineMode is set to FulPipeline for any sample.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
DifferentialExpressionEnable
No
Accepted values are true or false. If DifferentialExpressionEnable is true, then RnaPipelineMode must be FullPipeline.
**DragenRna\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".". Can be placed in either settings or data section.
RnaGeneAnnotationFile
No
Genotype reference file. Alphanumeric string with "_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome.
RnaPipelineMode
Yes
Accepted values are MapAlign or FullPipeline. The full pipeline option includes quantification and fusion detection.
DownSampleNumReads
No
Specifies the number of fragments to downsample to. For paired-end sequencing, the number of reads at the down-sampling output will be twice the number of fragments specified. Accepted values are integers. If DownSampleNumReads is placed in the Data section, and downsampling is not desired for that sample, a value of na must be used.
Sample_ID
Yes
See description in the BCL Convert section.
Comparison1
No
Accepted values are control, comparison, or na. Use only if DifferentialExpressionEnable is true. If RNAPipelineMode is MapAlign, this value must be na. Must have at least 2 control and 2 comparison samples. May have a max of 15 control or comparison samples. All control and comparison samples must have FullPipeline for RnaPipelineMode value and have the same ReferenceGenomeDir and RnaGeneAnnotationFile values.
The version of the DRAGEN software used to process the DragenRna pipeline, including conversion to FASTQ,, Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN RNA), using all three integers included in the version name. For example, 1.0.0.
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. Selecting none is not allowed if RnaPipelineMode is set to FulPipeline for any sample.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
DifferentialExpressionEnable
No
Accepted values are true or false. If DifferentialExpressionEnable is true, then RnaPipelineMode must be FullPipeline.
**DragenRna\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".". Can be placed in either settings or data section.
RnaGeneAnnotationFile
No
Genotype reference file. Alphanumeric string with "_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome.
RnaPipelineMode
Yes
Accepted values are MapAlign or FullPipeline. The full pipeline option includes quantification and fusion detection.
DownSampleNumReads
No
Specifies the number of fragments to downsample to. For paired-end sequencing, the number of reads at the down-sampling output will be twice the number of fragments specified. Accepted values are integers. If DownSampleNumReads is placed in the Data section, and downsampling is not desired for that sample, a value of na must be used.
Sample_ID
Yes
See description in the BCL Convert section
Comparison1
No
Accepted values are control, comparison, or na. Use only if DifferentialExpressionEnable is true. If RNAPipelineMode is MapAlign, this value must be na. Must have at least 2 control and 2 comparison samples. May have a max of 15 control or comparison samples. All control and comparison samples must have FullPipeline for RnaPipelineMode value and have the same ReferenceGenomeDir and RnaGeneAnnotationFile values.
The version of the DRAGEN software used to process the DragenRNA pipeline, including conversion to FASTQ,, Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN RNA), using all three integers included in the version name. For example, 1.0.0.
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. Selecting none is not allowed if RnaPipelineMode is set to FulPipeline for any sample.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
DifferentialExpressionEnable
No
Accepted values are true or false. If DifferentialExpressionEnable is true, then RnaPipelineMode must be FullPipeline.
**DragenRna\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".". Can be placed in either settings or data section.
RnaGeneAnnotationFile
No
Genotype reference file. Alphanumeric string with "_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome.
RnaPipelineMode
Yes
Accepted values are MapAlign or FullPipeline. The full pipeline option includes quantification and fusion detection.
DownSampleNumReads
No
Specifies the number of fragments to downsample to. For paired-end sequencing, the number of reads at the down-sampling output will be twice the number of fragments specified. Accepted values are integers. If DownSampleNumReads is placed in the Data section, and downsampling is not desired for that sample, a value of na must be used.
Sample_ID
Yes
See description in the BCL Convert section
Comparison1
No
Accepted values are control, comparison, or na. Use only if DifferentialExpressionEnable is true. If RNAPipelineMode is MapAlign, this value must be na. Must have at least 2 control and 2 comparison samples. May have a max of 15 control or comparison samples. All control and comparison samples must have FullPipeline for RnaPipelineMode value and have the same ReferenceGenomeDir and RnaGeneAnnotationFile values.
The version of the DRAGEN software used to process the DragenRNA pipeline, including conversion to FASTQ,, Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Yes
The version of the workflow-specific application (i.e., DRAGEN RNA), using all three integers included in the version name. For example, 1.0.0.
MapAlignOutFormat
Yes
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. Selecting none is not allowed if RnaPipelineMode is set to FulPipeline for any sample.
KeepFastQ
Yes
Select whether FASTQs are saved (true) or discarded (false).
DifferentialExpressionEnable
No
Accepted values are true or false. If DifferentialExpressionEnable is true, then RnaPipelineMode must be FullPipeline.
**DragenRna\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Yes
Genome name consisting of alphanumeric string with "_" or "-" or ".". Can be placed in either settings or data section.
RnaGeneAnnotationFile
No
Genotype reference file. Alphanumeric string with "_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome.
RnaPipelineMode
Yes
Accepted values are MapAlign or FullPipeline. The full pipeline option includes quantification and fusion detection.
DownSampleNumReads
No
Specifies the number of fragments to downsample to. For paired-end sequencing, the number of reads at the down-sampling output will be twice the number of fragments specified. Accepted values are integers. If DownSampleNumReads is placed in the Data section, and downsampling is not desired for that sample, a value of na must be used.
Sample_ID
Yes
See description in the BCL Convert section
Comparison1
No
Accepted values are control, comparison, or na. Use only if DifferentialExpressionEnable is true. If RNAPipelineMode is MapAlign, this value must be na. Must have at least 2 control and 2 comparison samples. May have a max of 15 control or comparison samples. All control and comparison samples must have FullPipeline for RnaPipelineMode value and have the same ReferenceGenomeDir and RnaGeneAnnotationFile values.
The version of the DRAGEN software used to process the DragenSomatic pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Required
The version of the workflow-specific application (i.e., DRAGEN Somatic), using all three integers included in the version name. For example, 1.0.0.
MapAlignOutFormat
Required
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output.
KeepFastq
Required
Select whether FASTQs are saved (true) or discarded (false).
**DragenSomatic\_Data**
Parameter
Required
Description
AuxNoiseBaselineFile
Optional
Alphanumeric string with "_" or "-" or ".". and no spaces in text (*.txt) or gzip (*.gz) format. Applicable only if GermlineOrSomatic is Somatic and VariantCallingMode is not None.
The value must be na if AuxNoiseBaselineFile is placed in the Data section and no AuxNoiseBaselineFile is provided for the sample."
AuxSvNoiseBaselineFile
Optional
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxSvNoiseBaselineFile is placed in the Data section and no AuxSvNoiseBaselineFile is provided for the sample.
AuxCnvPopBAlleleVcfFile
Optional
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxCnvPopBAlleleVcfFile is placed in the Data section and no AuxCnvPopBAlleleVcfFile is provided for the sample. CNV output will only be generated if this file is provided.
AuxGermlineTaggingFile
Optional
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxGermlineTaggingFile is placed in the Data section and no AuxGermlineTaggingFile is provided for the sample. Germline tagging output will only be generated if this file is provided.
VariantCallingMode
Required
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, and CNV callers (if panel of normals is provided).
The version of the DRAGEN software used to process the DragenSomatic pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Required
The version of the workflow-specific application (i.e., DRAGEN Somatic), using all three integers included in the version name. For example, 1.0.0.
MapAlignOutFormat
Required
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output.
KeepFastq
Required
Select whether FASTQs are saved (true) or discarded (false).
**DragenSomatic\_Data**
Parameter
Required
Description
AuxNoiseBaselineFile
Optional
Alphanumeric string with "_" or "-" or ".". and no spaces in text (*.txt) or gzip (*.gz) format. Applicable only if GermlineOrSomatic is Somatic and VariantCallingMode is not None.
The value must be na if AuxNoiseBaselineFile is placed in the Data section and no AuxNoiseBaselineFile is provided for the sample."
AuxSvNoiseBaselineFile
Optional
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxSvNoiseBaselineFile is placed in the Data section and no AuxSvNoiseBaselineFile is provided for the sample.
AuxCnvPopBAlleleVcfFile
Optional
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxCnvPopBAlleleVcfFile is placed in the Data section and no AuxCnvPopBAlleleVcfFile is provided for the sample. CNV output will only be generated if this file is provided.
AuxGermlineTaggingFile
Optional
Alphanumeric string with "_" or "-" or "." and no spaces in text (*.txt) or gzip (*.gz) format. Optional if VariantCallingMode is AllVariantCallers.
The value must be na if AuxGermlineTaggingFile is placed in the Data section and no AuxGermlineTaggingFile is provided for the sample. Germline tagging output will only be generated if this file is provided.
VariantCallingMode
Required
Variant calling mode for the run.
Accepted values are None, SmallVariantCaller, AllVariantCallers. The option for all variant callers includes Small, Structural, and CNV callers (if panel of normals is provided).
The version of the DRAGEN software used to process the DragenMethylation pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
AppVersion
Required
The version of the workflow-specific application (i.e., DRAGEN Methylation), using all three integers included in the version name. For example, 1.0.0.
MapAlignOutFormat
Required
Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output.
KeepFastq
Required
Select whether FASTQs are saved (true) or discarded (false).
UsesTaps
Required
Select whether the TAPS assay, which directly converts methylated C to T, is used (true) or not used (false).
**DragenMethylation\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Required
Genome name consisting of alphanumeric string with "_" or "-" or ".". Can be placed in either settings or data section.
MethylationProtocol
Required
Select the library protocol for methylation analysis from the set {'directional’, ‘non-directional’, ‘directional-complement’,‘pbat’}
Sample_ID
Required
See description in the BCL Convert section
{% endtab %}
{% tab title="4.1.23" %}
**DragenMethylation\_Settings**
| Parameter | Required | Description |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenMethylation pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| AppVersion | Required | The version of the workflow-specific application (i.e., DRAGEN Methylation), using all three integers included in the version name. For example, 1.0.0. |
| MapAlignOutFormat | Required | Formatting of the output files. Accepted values are bam, cram, or none. Selecting none produces no map/align output. |
| KeepFastq | Required | Select whether FASTQs are saved (true) or discarded (false). |
| UsesTaps | Required | Select whether the TAPS assay, which directly converts methylated C to T, is used (true) or not used (false). |
**DragenMethylation\_Data**
Parameter
Required
Description
ReferenceGenomeDir
Required
Genome name consisting of alphanumeric string with "_" or "-" or ".". Can be placed in either settings or data section.
MethylationProtocol
Required
Select the library protocol for methylation analysis from the set {'directional’, ‘non-directional’, ‘directional-complement’,‘pbat’}.
Sample_ID
Required
See description in the BCL Convert section.
{% endtab %}
{% endtabs %}
# NovaSeq X Sample Sheet Version History
* :white\_check\_mark: = Supported
* :yellow\_square: = Supported. Change in definition from prior release. See Release Notes and/or Sample Sheet Definition for each version for details.
* Blank = Not supported
String with ASCII characters except for * and the control characters CR and LF.
FileFormatVersion
Yes
Used to identify the sample sheet as a v2 sample sheet. This field must always exist in the header section with a value of 2.
Must always be 2.
InstrumentPlatform
No
Identifies the instrument platform to be used for the run.
For example, enter NextSeq1k2k for NextSeq 1000/2000 Series.
String with ASCII characters except for * and the control characters CR and LF.
InstrumentType
No
Identifies the instrument to be used for the run.
For example: if using NextSeq 2000, populate the field with NextSeq2000.
String with ASCII characters except for * and the control characters CR and LF.
RunDescription
No
The run description can contain 255 alphanumeric characters, spaces, dashes, and underscores.
String with ASCII characters except for * and the control characters CR and LF. Enter NextSeq 1000 or NextSeq 2000.
RunName
No
The run name can contain 255 alphanumeric characters, spaces, dashes, and underscores.
String with ASCII characters except for * and the control characters CR and LF. Enter NextSeq 1000 or NextSeq 2000.
### Reads Sections
Parameter
Required
Description
Requirements
Index1Cycles
No
Number of cycles in Index Read 1. Required if more than one sample is present in sample sheet.
Must be an integer ≥ 0.
Depending on your sequencing system and reagent kit, there can be limitations on the number of cycles in the Index Read.
Warning if values in range [1–5] inclusive.
If there is more than 1 sample per lane, must be > 0.
If OverrideCycles is present in the BCL_Settings section, must be consistent with the sum of the Index1 section of OverrideCycles.
Index2Cycles
No
Number of cycles in Index Read 2. Required if using dual indexes for demultiplexing.
Must be an integer ≥ 0.
Depending on your sequencing system and reagent kit, there can be limitations on the number of cycles in the Index Read.
Warning if values in range [1–5] inclusive.
If OverrideCycles is present in the BCL_Settings section, must be consistent with the sum of the Index1 section of OverrideCycles.
Read1Cycles
Yes
Number of cycles for Read 1.
Must be an integer > 0.
Warning if less than 26.
If OverrideCycles is present in the BCL_Settings section, must be consistent with the sum of the Read1 section of OverrideCycles.
Read2Cycles
Yes
Number of cycles for Read 2. Required only when running a paired-end sequencing run.
Must be an integer ≥ 0.
Warning if values in range [1–25] inclusive.
If OverrideCycles is present in the BCL_Settings section, must be consistent with the sum of the Read2 section of OverrideCycles.
### Sequencing Section
Parameter
Required
Description
Requirements
CustomIndex1Primer
No¹
Indicates if a Custom Index 1 primer is used for the run.
Values true and false allowed. Value true only allowed if Index1Cycles is specified.
CustomIndex2Primer
No¹
Indicates if a Custom Index 2 primer is used for the run.
Values true and false allowed. Value true only allowed if Index2Cycles is specified.
CustomRead1Primer
No¹
Indicates if a Custom Read 1 primer is used for the run.
Values true and false allowed. Value true only allowed if Read1Cycles is specified.
CustomRead2Primer
No¹
Indicates if a Custom Read 2 primer is used for the run.
Values true and false allowed. Value true only allowed if Read2Cycles is specified.
LibraryPrepKits
No
Identifies the library prep kit used for the run.
String with ASCII characters except for * and the control characters CR and LF.
Only one library prep kit is allowed.
In the NextSeq 1000/2000 Control Software v1.3 or later, the required custom recipe is automatically selected if one of the following kits is specified as the library prep kit.
Illumina Stranded Total RNA Prep with Ribo-Zero Plus kit
Illumina Stranded mRNA Prep kit
Enter one of the following values.
For Illumina Stranded Total RNA Prep with Ribo-Zero Plus kit, enter ILMNStrandedTotalRNA.
For Illumina Stranded mRNA Prep kit, enter ILMNStrandedmRNA.
¹ Depending on the run or library prep kit, this parameter might be required.
## Application Sections
### BCL Convert
{% tabs %}
{% tab title="4.2.7" %}
**BCLConvert\_Settings**
Parameter
Type
Description
SoftwareVersion
Required
The version of the software to be used to perform BCL conversion on the Sample_IDs that only exist in the BCL Convert Data section of the sample sheet. The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0.
AdapterRead1
Optional
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
AdapterRead2
Optional
See description of AdapterRead1, applied to AdapterRead2.
BarcodeMismatchesIndex1
Optional
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
BarcodeMismatchesIndex2
Optional
See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2.
OverrideCycles
Optional
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151;I8N2;N10;Y151
Y151;N2I8;I8N2;Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2.
FastqCompressionFormat
Optional
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
NoLaneSplitting
Optional
If set to true, output all lanes of a flow cell to the same FASTQ files consecutively.
**BCLConvert\_Data**
Parameter
Type
Description
Sample_ID
Required
ID for the sample with the following requirements: • Must be alphanumeric string with _ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample_ID
Index
Optional
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
Index2
Optional
See description of Index, applied to Index2.
{% endtab %}
{% tab title="3.10.12" %}
**BCLConvert\_Settings**
| Parameter | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the software to be used to perform BCL conversion on the Sample\_IDs that only exist in the BCL Convert Data section of the sample sheet. The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0. |
| AdapterRead1 | Optional |
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
|
| AdapterRead2 | Optional | See description of AdapterRead1, applied to AdapterRead2. |
| BarcodeMismatchesIndex1 | Optional |
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
|
| BarcodeMismatchesIndex2 | Optional | See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2. |
| OverrideCycles | Optional |
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml or and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2,
|
| FastqCompressionFormat | Optional |
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
ID for the sample with the following requirements: • Must be alphanumeric string with \_ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample\_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample\_ID
|
| Index | Optional |
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
|
| Index2 | Optional | See description of Index, applied to Index2. |
| {% endtab %} | | |
{% tab title="3.10.10" %}
**BCLConvert\_Settings**
| Parameter | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the software to be used to perform BCL conversion on the Sample\_IDs that only exist in the BCL Convert Data section of the sample sheet. The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0. |
| AdapterRead1 | Optional |
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
|
| AdapterRead2 | Optional | See description of AdapterRead1, applied to AdapterRead2. |
| BarcodeMismatchesIndex1 | Optional |
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
|
| BarcodeMismatchesIndex2 | Optional | See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2. |
| OverrideCycles | Optional |
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml or and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2,
|
| FastqCompressionFormat | Optional |
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
ID for the sample with the following requirements: • Must be alphanumeric string with \_ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample\_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample\_ID
|
| Index | Optional |
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
|
| Index2 | Optional | See description of Index, applied to Index2. |
| {% endtab %} | | |
{% tab title="3.9.3" %}
**BCLConvert\_Settings**
| Parameter | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the software to be used to perform BCL conversion on the Sample\_IDs that only exist in the BCL Convert Data section of the sample sheet. The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0. |
| AdapterRead1 | Optional |
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
|
| AdapterRead2 | Optional | See description of AdapterRead1, applied to AdapterRead2. |
| BarcodeMismatchesIndex1 | Optional |
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
|
| BarcodeMismatchesIndex2 | Optional | See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2. |
| OverrideCycles | Optional |
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml or and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2,
|
| FastqCompressionFormat | Optional |
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
ID for the sample with the following requirements: • Must be alphanumeric string with \_ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample\_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample\_ID
|
| Index | Optional |
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
|
| Index2 | Optional | See description of Index, applied to Index2. |
| {% endtab %} | | |
{% tab title="3.8.4" %}
**BCLConvert\_Settings**
| Parameter | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the software to be used to perform BCL conversion on the Sample\_IDs that only exist in the BCL Convert Data section of the sample sheet. The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0. |
| AdapterRead1 | Optional |
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
|
| AdapterRead2 | Optional | See description of AdapterRead1, applied to AdapterRead2. |
| BarcodeMismatchesIndex1 | Optional |
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
|
| BarcodeMismatchesIndex2 | Optional | See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2. |
| OverrideCycles | Optional |
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml or and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2,
|
| FastqCompressionFormat | Optional |
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
ID for the sample with the following requirements: • Must be alphanumeric string with \_ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample\_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample\_ID
|
| Index | Optional |
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
|
| Index2 | Optional | See description of Index, applied to Index2. |
| {% endtab %} | | |
{% tab title="3.7.4" %}
**BCLConvert\_Settings**
| Parameter | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the software to be used to perform BCL conversion on the Sample\_IDs that only exist in the BCL Convert Data section of the sample sheet. The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0. |
| AdapterRead1 | Optional |
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
|
| AdapterRead2 | Optional | See description of AdapterRead1, applied to AdapterRead2. |
| BarcodeMismatchesIndex1 | Optional |
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
|
| BarcodeMismatchesIndex2 | Optional | See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2. |
| OverrideCycles | Optional |
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml or and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2,
|
| FastqCompressionFormat | Optional |
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
ID for the sample with the following requirements: • Must be alphanumeric string with \_ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample\_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample\_ID
|
| Index | Optional |
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
The version of the DRAGEN software used to process the DragenGermline pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5.
ReferenceGenomeDir
Required
Genome name consisting of alphanumeric string with "_" or "-" or ".".
MapAlignOutFormat
Optional
Formatting of the output files. Accepted values are bam, cram, or none. Default is bam.
KeepFastQ
Optional
Select whether FASTQs are saved (true) or discarded (false).
**DragenGermline\_Data**
Parameter
Type
Description
Sample_ID
Required
See description in the BCL Convert section.
{% endtab %}
{% tab title="3.10.12" %}
**DragenGermline\_Settings**
| Parameter | Type | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software\~\~,\~\~ used to process the DragenGermline pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
**DragenGermline\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.10.10" %}
**BCLConvert\_Settings**
| Parameter | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the software to be used to perform BCL conversion on the Sample\_ID's that only exist in the BCL Convert Data section of the sample sheet., The version is specified using all three integers included in the DRAGEN version name. For example, 1.0.0. |
| AdapterRead1 | Optional |
The sequence of the Read 1 adapter to be masked or trimmed. To trim multiple adapters, separate the sequences with a plus sign (+) indicating independent adapters that must be independently assessed for masking or trimming for each read. Characters must be A, C, G, or T.
A value of na (case insensitive) must be used if:
the AdapterRead1 field is placed in the Data section of the Sample Sheet, and
no adapter trimming is desired for the sample
|
| AdapterRead2 | Optional | See description of AdapterRead1, applied to AdapterRead2. |
| BarcodeMismatchesIndex1 | Optional |
Specifies barcode mismatch tolerance for Index 1. Possible values are 0, 1, or 2, or na. The default value is 1. Only allowed if Index is specified in RunInfo.xml file and in the Reads section of the Sample Sheet.
A value of na must be used if:
BarcodeMismatchesIndex1 exists in the Data section of the Sample Sheet, and
OverrideCycles exist in the data section, and
Index 1 is masked out for the sample in the OverrideCycles
|
| BarcodeMismatchesIndex2 | Optional | See description of BarcodeMismatchesIndex1, applied to BarcodeMismatchesIndex2. |
| OverrideCycles | Optional |
Specifies the sequencing and indexing cycles to be used when processing the sequencing data. Must adhere to the following requirements: • Must be same number of fields (delimited by semicolon) as sequencing and indexing reads specified in RunInfo.xml or and in the Reads section of the Sample Sheet. • Indexing reads are specified with I, sequencing reads are specified with Y, UMI cycles are specified with U, and trimmed reads are specified with N. • The number of cycles specified for each read must equal the number of cycles specified for that read in the RunInfo.xml file and in the Reads section of the Sample Sheet. • Only one Y or I sequence can be specified per read.
'I' cycles can only be specified for index reads
'Y' cycles can only be specified for genomic reads
The total number of cycles used for demultiplexing by both indexes together cannot exceed 27. Note that this includes all cycles between the first "I" cycle used by any sample and the last "I" cycle used by any sample within each index.
"I5N3;I5N3" : counts as 10 bases toward the limit of 27
"I4N1I3;I5N3": counts as (8+5) 13 bases toward the limit of 27
The following are examples of OverrideCycles input: U8Y143;I8;I8;U8Y143 N10Y66;I6;N10Y66
For a sample sheet containing two samples having the following OverrideCycles
Y151; I8N2; N10; Y151
Y151; N2I8; I8N2; Y151
the number of cycles used for demultiplexing sums to 18.
For sequencers with RunInfo.xml having "IsReverseComplement" set to "Y" for Index2, then Index2 is processed in reverse complement orientation. Any trimming should be applied to the end of the sequence as it transitions to the adapter, which means the "N" cycles specified in OverrideCycles must be in the beginning of the index read.
Example of 8bp i5 index with the last two (adapter) bases to be trimmed:
Forward i5: XXATCGCGGT
ReverseComp i5: ACCGCGATXX (this is the direction of sequencing)
OverrideCycles for Index2: N2I8
where XX is part of the adapter sequence.
Although Index2 is processed on the sequencer in reverse complement format, Index2 and OverrideCycles are entered in the Sample Sheet in forward, non-complemented format for user convenience (see diagram below).
Note that NovaSeq X has a RunInfo.xml with "IsReverseComplement" set to "Y" for Index2,
|
| FastqCompressionFormat | Optional |
The compression format for the FASTQ output files. Allowed values are gzip or dragen.
ID for the sample with the following requirements: • Must be alphanumeric string with \_ or - and no spaces. • Case sensitive (i.e., a Sample Sheet with the samples MySample and mysample is not allowed)
The same Sample\_ID may exist on more than one row of the Sample Sheet (e.g., one sample spanning more than one lane)
Undetermined is not allowed as a Sample\_ID
|
| Index | Optional |
The Index 1 (i7) index sequence. Format is a sequence using ACTG. Required if index cycles are specified for the sample in the OverrideCycles.
Must adhere to the following requirements:
Can only contain A, C, G, or T
Length of string must match number of first index cycles in RunInfo.xml or the number specified in OverrideCycles
A value of na must be used if:
No indexes are specified in OverrideCycles for a sample
|
| Index2 | Optional | See description of Index, applied to Index2. |
| {% endtab %} | | |
{% tab title="3.9.3" %}
**DragenGermline\_Settings**
| Parameter | Type | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software\~\~,\~\~ used to process the DragenGermline pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
**DragenGermline\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.8.4" %}
**DragenGermline\_Settings**
| Parameter | Type | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software\~\~,\~\~ used to process the DragenGermline pipeline, including conversion to FASTQ, Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
**DragenGermline\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.7.4" %}
**DragenGermline\_Settings**
| Parameter | Type | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software\~\~,\~\~ used to process the DragenGermline pipeline, including conversion to FASTQ, Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
**DragenGermline\_Data**
| Parameter | Type | Description |
| ------------- | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
| {% endtabs %} | | |
### DRAGEN Enrichment
{% tabs %}
{% tab title="4.2.7" %}
**DragenEnrichment\_Settings**
| Parameter | Type | Description |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| Bedfile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| GermlineOrSomatic | Required | Indicator of pipeline type. Accepted values are germline or somatic. |
| AuxNoiseBaselineFile | Optional | Alphanumeric string with "\_" or "-" or ".". and no spaces in text (\*.txt) or gzip (\*.gz) format. Applicable only if GermlineOrSomatic is Somatic. |
| AuxCnvPanelOfNormalsFile | Optional | Alphanumeric string with "\_" or "-" or "." and no spaces in text (\*.txt) or gzip (\*.gz) format. |
**DragenEnrichment\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section. |
| {% endtab %} | | |
{% tab title="3.10.12" %}
**DragenEnrichment\_Settings**
| Parameter | Type | Description |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| Bedfile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| GermlineOrSomatic | Required | Indicator of pipeline type. Accepted values are germline or somatic. |
| AuxNoiseBaselineFile | Optional | Alphanumeric string with "\_" or "-" or ".". and no spaces in text (\*.txt) or gzip (\*.gz) format. Applicable only if GermlineOrSomatic is Somatic. |
| AuxCnvPanelOfNormalsFile | Optional | Alphanumeric string with "\_" or "-" or "." and no spaces in text (\*.txt) or gzip (\*.gz) format. |
**DragenEnrichment\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.9.3" %}
**DragenEnrichment\_Settings**
| Parameter | Type | Description |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| Bedfile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| GermlineOrSomatic | Required | Indicator of pipeline type. Accepted values are germline or somatic. |
| AuxNoiseBaselineFile | Optional | Alphanumeric string with "\_" or "-" or ".". and no spaces in text (\*.txt) or gzip (\*.gz) format. Applicable only if GermlineOrSomatic is Somatic. |
**DragenEnrichment\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.8.4" %}
**DragenEnrichment\_Settings**
| Parameter | Type | Description |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| Bedfile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| GermlineOrSomatic | Required | Indicator of pipeline type. Accepted values are germline or somatic. |
| AuxNoiseBaselineFile | Optional | Alphanumeric string with "\_" or "-" or ".". and no spaces in text (\*.txt) or gzip (\*.gz) format. Applicable only if GermlineOrSomatic is Somatic. |
**DragenEnrichment\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.7.4" %}
**DragenEnrichment\_Settings**
| Parameter | Type | Description |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenEnrichment pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| Bedfile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| GermlineOrSomatic | Required | Indicator of pipeline type. Accepted values are germline or somatic. |
**DragenEnrichment\_Data**
| Parameter | Type | Description |
| ------------- | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
| {% endtabs %} | | |
### DRAGEN RNA
{% tabs %}
{% tab title="4.2.7" %}
**DragenRna\_Settings**
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| DifferentialExpressionEnable | Optional | Accepted values are true or false. |
**DragenRna\_Data**
| Parameter | Required | Description |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section. |
| Comparison1 | Optional | Accepted values are control, comparison, or na. Use only if DifferentialExpressionEnable is true. Must have at least 2 control and 2 comparison samples. May have a max of 15 control or comparison samples. |
| Comparison2 | Optional | See Comparison1 description. |
| Comparison3 | Optional | See Comparison1 description. |
| Comparison4 | Optional | See Comparison1 description. |
| Comparison5 | Optional | See Comparison1 description. |
| {% endtab %} | | |
{% tab title="3.10.12" %}
**DragenRna\_Settings**
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| DifferentialExpressionEnable | Optional | Accepted values are true or false. |
**DragenRna\_Data**
| Parameter | Required | Description |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section. |
| Comparison1 | Optional |
Accepted values are control, comparison, or na. Use only if DifferentialExpressionEnable is true. Must have at least 2 control and 2 comparison samples. May have a max of 15 control or comparison samples.
|
| Comparison2 | Optional | See Comparison1 description. |
| Comparison3 | Optional | See Comparison1 description. |
| Comparison4 | Optional | See Comparison1 description. |
| Comparison5 | Optional | See Comparison1 description. |
{% endtab %}
{% tab title="3.9.3" %}
**DragenRna\_Settings**
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| DifferentialExpressionEnable | Optional | Accepted values are true or false. |
**DragenRna\_Data**
| Parameter | Required | Description |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section |
| Comparison1 | Optional |
Accepted values are control, comparison, or na. Use only if DifferentialExpressionEnable is true. Must have at least 2 control and 2 comparison samples. May have a max of 15 control or comparison samples.
|
| Comparison2 | Optional | See Comparison1 description. |
| Comparison3 | Optional | See Comparison1 description. |
| Comparison4 | Optional | See Comparison1 description. |
| Comparison5 | Optional | See Comparison1 description. |
{% endtab %}
{% tab title="3.8.4" %}
**DragenRna\_Settings**
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
| DifferentialExpressionEnable | Optional | Accepted values are true or false. |
**DragenRna\_Data**
| Parameter | Required | Description |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| Comparison1 | Optional | Accepted values are control, comparison, or na. Use only if DifferentialExpressionEnable is true. Must have at least 2 control and 2 comparison samples. May have a max of 15 control or comparison samples. |
| Comparison2 | Optional | See Comparison1 description. |
| Comparison3 | Optional |
See Comparison1 description.
|
| Comparison4 | Optional |
See Comparison1 description.
|
| Comparison5 | Optional |
See Comparison1 description.
|
| {% endtab %} | | |
{% tab title="3.7.4" %}
**DragenRna\_Settings**
| Parameter | Type | Description |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
**DragenRna\_Data**
| Parameter | Required | Description |
| ------------- | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
| {% endtabs %} | | |
### DRAGEN Single Cell RNA
{% tabs %}
{% tab title="4.2.7" %}
**DragenSingleCellRna\_Settings**
| Parameter | Type | Description |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenSingleCellRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| BarcodePosition | Required | Text string indicating the location of the bases corresponding to the Barcode within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. Examples: 0\_15, or 0\_8**+**21\_29**+**43\_51 if the barcodes are not contiguous. |
| UmiPosition | Required | Text string indicating the location of the bases corresponding to the UMI within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. For example, 16\_27. |
| BarcodeRead | Required | Text string indicating the location within the sequencing run of the Barcode Read, which contains both the Barcode and the Umi. Readn, where n is from the set { 1, 2 }. |
| BarcodeSequenceWhiteList | Required | List of expected barcode sequences. |
| BarcodeSequenceList | Required | List of expected barcode sequences. |
| RnaLibraryType | Required | Valid values are StrandedForward, StrandedReverse, Unstranded. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section. |
| {% endtab %} | | |
{% tab title="3.10.12" %}
**DragenSingleCellRna\_Settings**
| Parameter | Type | Description |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenSingleCellRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| BarcodePosition | Required | Text string indicating the location of the bases corresponding to the Barcode within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. Examples: 0\_15, or 0\_8**+**21\_29**+**43\_51 if the barcodes are not contiguous. |
| UmiPosition | Required | Text string indicating the location of the bases corresponding to the UMI within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. For example, 16\_27. |
| BarcodeRead | Required | Text string indicating the location within the sequencing run of the Barcode Read, which contains both the Barcode and the Umi. Readn, where n is from the set { 1, 2 }. |
| BarcodeSequenceList | Required | List of expected barcode sequences. |
| RnaLibraryType | Required | Valid values are StrandedForward, StrandedReverse, Unstranded. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.9.3" %}
**DragenSingleCellRna\_Settings**
| Parameter | Type | Description |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenSingleCellRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| BarcodePosition | Required | Text string indicating the location of the bases corresponding to the Barcode within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. Examples: 0\_15, or 0\_8**+**21\_29**+**43\_51 if the barcodes are not contiguous. |
| UmiPosition | Required | Text string indicating the location of the bases corresponding to the UMI within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. For example, 16\_27. |
| BarcodeRead | Required | Text string indicating the location within the sequencing run of the Barcode Read, which contains both the Barcode and the Umi. Readn, where n is from the set { 1, 2 }. |
| BarcodeSequenceList | Required | List of expected barcode sequences. |
| RnaLibraryType | Required | Valid values are StrandedForward, StrandedReverse, Unstranded. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.8.4" %}
**DragenSingleCellRna\_Settings**
| Parameter | Type | Description |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenSingleCellRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| BarcodePosition | Required | Text string indicating the location of the bases corresponding to the Barcode within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. Examples: 0\_15, or 0\_8**+**21\_29**+**43\_51 if the barcodes are not contiguous. |
| UmiPosition | Required | Text string indicating the location of the bases corresponding to the UMI within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. For example, 16\_27. |
| BarcodeRead | Required | Text string indicating the location within the sequencing run of the Barcode Read, which contains both the Barcode and the Umi. Readn, where n is from the set { 1, 2 }. |
| BarcodeSequenceList | Required | List of expected barcode sequences. |
| RnaLibraryType | Required | Valid values are StrandedForward, StrandedReverse, Unstranded. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
| {% endtab %} | | |
{% tab title="3.7.4" %}
**DragenSingleCellRna\_Settings**
| Parameter | Type | Description |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenSingleCellRNA pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| RnaGeneAnnotationFile | Optional | Genotype reference file. Alphanumeric string with "\_" or "-" or "." with no spaces allowed. If DifferentialExpressionEnable is True., the GTF file must be provided by the user or included with the reference genome. |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| BarcodePosition | Required | Text string indicating the location of the bases corresponding to the Barcode within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. Examples: 0\_15, or 0\_8**+**21\_29**+**43\_51 if the barcodes are not contiguous. |
| UmiPosition | Required | Text string indicating the location of the bases corresponding to the UMI within the specified BarcodeRead. Base positions are indexed starting at position zero in the Read. For example, 16\_27. |
| BarcodeRead | Required | Text string indicating the location within the sequencing run of the Barcode Read, which contains both the Barcode and the Umi. Readn, where n is from the set { 1, 2 }. |
| BarcodeSequenceWhitelist | Required | List of expected barcode sequences. |
| RnaLibraryType | Required | Valid values are StrandedForward, StrandedReverse, Unstranded. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ---------- | -------- | ------------------------------------------ |
| Sample\_ID | Required | See description in the BCL Convert section |
{% endtab %}
{% endtabs %}
### DRAGEN Amplicon
{% tabs %}
{% tab title="4.2.7" %}
**DragenAmplicon\_Settings**
| Parameter | Type | Description |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenAmplicon pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| DnaBedFile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| DnaGermlineOrSomatic | Required | Indicator of "germline" or "somatic" type for DNA samples. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ------------ | -------- | --------------------------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section. |
| DnaOrRna | Required | Indicator of a DNA or RNA sample. Valid values are dna and rna. |
| {% endtab %} | | |
{% tab title="3.10.12" %}
**DragenAmplicon\_Settings**
| Parameter | Type | Description |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenAmplicon pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| DnaBedFile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| DnaGermlineOrSomatic | Required | Indicator of "germline" or "somatic" type for DNA samples. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ------------ | -------- | --------------------------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section. |
| DnaOrRna | Required | Indicator of a DNA or RNA sample. Valid values are dna and rna. |
| {% endtab %} | | |
{% tab title="3.9.3" %}
**DragenAmplicon\_Settings**
| Parameter | Type | Description |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenAmplicon pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| DnaBedFile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| DnaGermlineOrSomatic | Required | Indicator of "germline" or "somatic" type for DNA samples. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ------------ | -------- | --------------------------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section |
| DnaOrRna | Required | Indicator of a DNA or RNA sample. Valid values are dna and rna. |
| {% endtab %} | | |
{% tab title="3.8.4" %}
**DragenAmplicon\_Settings**
| Parameter | Type | Description |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software used to process the DragenAmplicon pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| MapAlignOutFormat | Optional | Formatting of the output files. Accepted values are bam, cram, or none. Default is bam. |
| ReferenceGenomeDir | Required | Genome name consisting of alphanumeric string with "\_" or "-" or ".". |
| KeepFastQ | Optional | Select whether FASTQs are saved (true) or discarded (false). |
| DnaBedFile | Required | BED file to be used for analysis in text (\*.txt) or gzip (\*.gz) format. Alphanumeric string with \_ or - or . with no spaces allowed. |
| DnaGermlineOrSomatic | Required | Indicator of "germline" or "somatic" type for DNA samples. |
**DragenSingleCellRna\_Data**
| Parameter | Type | Description |
| ------------- | -------- | --------------------------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section. |
| DnaOrRna | Required | Indicator of a DNA or RNA sample. Valid values are dna and rna. |
| {% endtab %} | | |
| {% endtabs %} | | |
### DRAGEN GeoMxNGS
{% tabs %}
{% tab title="4.2.7" %}
**DragenGeoMxNGS\_Settings**
| Parameter | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software\~\~,\~\~ used to process the DragenGeoMxNGS pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| GeoMxConfigFile | Required | GeoMx configuration file. |
| BarcodeSequenceList | Required | List of expected barcode sequences. |
| KeepFastq | Optional | Select whether FASTQs are saved (true) or discarded (false). |
**DragenGeoMxNGS\_Data**
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section. |
| {% endtab %} | | |
{% tab title="3.9.3" %}
**DragenGeoMxNGS\_Settings**
| Parameter | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SoftwareVersion | Required | The version of the DRAGEN software\~\~,\~\~ used to process the DragenGeoMxNGS pipeline, including conversion to FASTQ. Specified using all three integers included in the DRAGEN version name. For example, 4.1.5. |
| GeoMxConfigFile | Required | GeoMx configuration file. |
| BarcodeSequenceList | Required | List of expected barcode sequences. |
| KeepFastq | Optional |
Select whether FASTQs are saved (true) or discarded (false).
|
**DragenGeoMxNGS\_Data**
| Parameter | Type | Description |
| ------------- | -------- | ------------------------------------------- |
| Sample\_ID | Required | See description in the BCL Convert section. |
| {% endtab %} | | |
| {% endtabs %} | | |
# NextSeq 1000/2000 Sample Sheet Version History
* :white\_check\_mark: = Supported
* :yellow\_square: = Supported. Change in definition from prior release. See Release Notes and/or Sample Sheet Definition for each version for details.
* Blank = Not supported
Pipeline
Section
Type
Key Word
3.5.8
3.7.4
3.8.4
3.9.3
3.10.10
3.10.12
4.2.7
DRAGEN BCL Convert
[BCLConvert_Settings]
Required
SoftwareVersion
✅
✅
✅
✅
✅
✅
✅
DRAGEN BCL Convert
[BCLConvert_Settings]
Optional
OverrideCycles
✅
✅
✅
✅
✅
✅
✅
DRAGEN BCL Convert
[BCLConvert_Settings]
Optional
AdapterRead1
✅
✅
✅
✅
✅
✅
✅
DRAGEN BCL Convert
[BCLConvert_Settings]
Optional
AdapterRead2
✅
✅
✅
✅
✅
✅
✅
DRAGEN BCL Convert
[BCLConvert_Settings]
Optional
FastqCompressionFormat
✅
✅
✅
✅
✅
✅
DRAGEN BCL Convert
[BCLConvert_Settings]
Optional
NoLaneSplitting
✅
DRAGEN BCL Convert
[BCLConvert_Data]
Required
SampleID
✅
✅
✅
✅
✅
✅
✅
DRAGEN BCL Convert
[BCLConvert_Data]
Optional
Index
✅
✅
✅
✅
✅
✅
✅
DRAGEN BCL Convert
[BCLConvert_Data]
Optional
Index2
✅
✅
✅
✅
✅
✅
✅
DRAGEN Germline
[DragenGermline_Settings]
Required
SoftwareVersion
✅
✅
✅
✅
✅
✅
DRAGEN Germline
[DragenGermline_Settings]
Required
ReferenceGenomeDir
✅
✅
✅
✅
✅
✅
DRAGEN Germline
[DragenGermline_Settings]
Optional
MapAlignOutFormat
✅
✅
✅
✅
✅
✅
DRAGEN Germline
[DragenGermline_Settings]
Optional
KeepFastq
✅
✅
✅
✅
✅
DRAGEN Germline
[DragenGermline_Data]
Required
SampleID
✅
✅
✅
✅
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Settings]
Required
SoftwareVersion
✅
✅
✅
✅
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Settings]
Required
ReferenceGenomeDir
✅
✅
✅
✅
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Settings]
Optional
MapAlignOutFormat
✅
✅
✅
✅
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Settings]
Required
BedFile
✅
✅
✅
✅
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Settings]
Required
GermlineOrSomatic
✅
✅
✅
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Settings]
Optional
KeepFastq
✅
✅
✅
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Settings]
Optional
AuxNoiseBaselineFile
✅
✅
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Settings]
Optional
AuxCnvPanelOfNormalsFile
✅
✅
DRAGEN Enrichment
[DragenEnrichment_Data]
Required
SampleID
✅
✅
✅
✅
✅
✅
DRAGEN RNA
[DragenRna_Settings]
Required
SoftwareVersion
✅
✅
✅
✅
✅
✅
DRAGEN RNA
DragenRna_Settings]
Required
ReferenceGenomeDir
✅
✅
✅
✅
✅
✅
DRAGEN RNA
DragenRna_Settings]
Optional
RnaGeneAnnotationFile
✅
✅
✅
✅
✅
✅
DRAGEN RNA
DragenRna_Settings]
Optional
MapAlignOutFormat
✅
✅
✅
✅
✅
✅
DRAGEN RNA
DragenRna_Settings]
Optional
KeepFastq
✅
✅
✅
✅
✅
DRAGEN RNA
DragenRna_Settings]
Optional
DifferentialExpressionEnable
✅
✅
✅
✅
DRAGEN RNA
[DragenRna_Data]
Required
SampleID
✅
✅
✅
✅
✅
✅
DRAGEN RNA
[DragenRna_Data]
Optional
Comparison1
✅
✅
✅
✅
DRAGEN RNA
[DragenRna_Data]
Optional
Comparison2
✅
✅
✅
✅
DRAGEN RNA
[DragenRna_Data]
Optional
Comparison3
✅
✅
✅
✅
DRAGEN RNA
[DragenRna_Data]
Optional
Comparison4
✅
✅
✅
✅
DRAGEN RNA
[DragenRna_Data]
Optional
Comparison5
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Required
SoftwareVersion
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Required
ReferenceGenomeDir
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Optional
MapAlignOutFormat
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Optional
RnaGeneAnnotationFile
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Optional
KeepFastq
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Required
BarcodePosition
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Required
UmiPosition
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Required
BarcodeRead
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Required
BarcodeSequenceWhitelist
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Required
BarcodeSequenceList
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Settings]
Required
RnaLibraryType
✅
✅
✅
✅
✅
DRAGEN Single Cell
[DragenSingleCellRna_Data]
Required
SampleID
✅
✅
✅
✅
✅
DRAGEN Amplicon
[DragenAmplicon_Settings]
Required
SoftwareVersion
✅
✅
✅
✅
DRAGEN Amplicon
[DragenAmplicon_Settings]
Required
ReferenceGenomeDir
✅
✅
✅
✅
DRAGEN Amplicon
[DragenAmplicon_Settings]
Required
DnaBedFile
✅
✅
✅
✅
DRAGEN Amplicon
[DragenAmplicon_Settings]
Optional
MapAlignOutFormat
✅
✅
✅
✅
DRAGEN Amplicon
[DragenAmplicon_Settings]
Optional
KeepFastq
✅
✅
✅
✅
DRAGEN Amplicon
[DragenAmplicon_Settings]
Required
DnaGermlineOrSomatic
✅
✅
✅
✅
DRAGEN Amplicon
[DragenAmplicon_Data]
Required
DnaOrRna
✅
✅
✅
✅
DRAGEN Amplicon
[DragenAmplicon_Data]
Required
SampleID
✅
✅
✅
✅
Nanostring
[DragenGeoMxNGS_Settings]
Required
SoftwareVersion
✅
✅
Nanostring
[DragenGeoMxNGS_Settings]
Optional
KeepFastq
✅
✅
Nanostring
[DragenGeoMxNGS_Settings]
Required
GeoMxConfigFile
✅
✅
Nanostring
[DragenGeoMxNGS_Settings]
Required
BarcodeSequenceList
✅
✅
Nanostring
[DragenGeoMxNGS_Data]
Required
SampleID
✅
✅
# Cloud Analysis Auto-launch Settings
## Sample Sheet
The orchestration of auto-launched Platform Core pipelines is driven by information provided in the sequencing run sample sheet. When leveraging BaseSpace Run Planning to plan a run, the sample sheet is automatically generated. The sample sheet may also be attached to the run manually on the sequencer. The following sections are necessary for powering the autolaunch of secondary analysis after the sequencing run completes.
To retreive the most up-to-date sample sheet template for your instrument, generate an example using BaseSpace Run Planning.
### Use Run Planning to Export a Sample Sheet
1. Log into your BaseSpace Sequence Hub account.
2. Select the **Runs** tab, and then select the **New Run** drop-down.
3. Select **Run Planning**.
4. In the **Run Name** field, enter a unique name of your preference to identify the current run. The run name can contain a maximum of 255 alphanumeric characters, spaces, dashes, and underscores.
5. *Optional:* Enter a description for the run. The run description can contain a maximum of 255 characters.
6. Select your sequencing system as the instrument platform.
7. For Secondary Analysis, Select **BaseSpace**.
1. Note that if you have a Platform Core subscription, this option will read **BaseSpace / BioInsight Platform Core**.
8. *Optional:* Enter the ID for your library tube. The library tube ID is located on the label of your library tube strip.
9. Select **Next**.
10. Select your analysis application. If only one option is available, it will be selected automatically.
11. *Optional:* Enter a description for the configuration.
12. Select an existing library prep kit, or add a new custom library prep kit as follows:
1. Select **Add Custom Library Prep Kit** under the Library Prep Kit dropdown.
2. Enter the name, read types, default read cycles, and compatible index adapter kits for your custom library prep kit.
3. Select **Create New Kit**.
13. Select an existing index adapter kit, or add a new a custom index kits as follows. If you are using more than one library, the libraries must have the same index read lengths.
1. Select **Add Custom Index Adapter Kit** under the Index Adapter Kit dropdown.
2. Select a template type and enter the kit name, adapter sequences, index strategies, and index sequences. Make sure the second index (i5) adapter sequences are in forward orientation.
3. Select **Create New Kit**.
14. If applicable to your application, select a reference genome.
15. Select **Next** to configure secondary analysis settings. Detailed instructions for each application and version can be found here.
16. Select **Next** to review the Run and Analysis details.
17. Select **Export** to save the Sample Sheet to your device.
The `FileFormatVersion` in the `[Header]` section must be set to `2` to indicate the sample sheet as *v2* format.
```csv
[Header],
FileFormatVersion,2
```
Sample sheets generated using BaseSpace Run Planning may contain additional *optional* header fields such as `RunName`, `InstrumentPlatform`, and `IndexOrientation`.
### Primary Analysis Settings
The primary analysis settings consist of the information used for the on-instrument sequencing and demultiplexing of raw sequencing output data. This includes information about reads, indices, primers, etc.
These sections vary greatly depending on the instrument type used and sequencing configuration. The below examples are used for demonstration purposes only.
```csv
[Reads],
Read1Cycles,1
Read2Cycles,1
Index1Cycles,1
Index2Cycles,1
```
```csv
[Sequencing],
CustomRead1Primer,false
CustomRead2Primer,false
CustomIndex1Primer,false
CustomIndex2Primer,false
```
```csv
[BCLConvert_Settings],
SoftwareVersion,0
BarcodeMismatchesIndex1,
BarcodeMismatchesIndex2,
AdapterRead1,
AdapterRead2,
OverrideCycles,
```
For demultiplexing the raw sequencing output data, the settings for demultiplexing (ie, BCL Convert) are included. The below examples are used for demonstration purposes only.
```csv
[BCLConvert_Settings],
Sample_ID,NS001
Index,T
Index2,A
Lane,1
```
### Secondary Analysis Settings
A `[Cloud__Settings]` and `[Cloud__Data]` setting are provided for each secondary analysis pipeline to be auto-launched after sequencing. The value used for `` can be any value. It's best practice to refer to the analysis type such as "DragenGermline", "BCLConvert", etc. These sections provide input parameters to the pipelines. The contents of these sections, including the columns, may vary depending on the pipeline used for secondary analysis. The below snippet demonstrates using "DragenGermline" as an example.
```csv
[Cloud_DragenGermline_Settings]
SoftwareVersion,4.1.5
MapAlignOutFormat,bam
[Cloud_DragenGermline_Data]
Sample_ID,ReferenceGenomeDir,VariantCallingMode
,urn:ilmn:ica:region::data:#,None
,urn:ilmn:ica:region::data:#,None
```
The `[Cloud_Settings]` section must be present and include:
1. `Cloud_Workflow` value set to `ica_workflow_1`
2. `BCLConvert_Pipeline` set a valid Platform Core Uniform Resource Name (URN) for demultiplexing
1. Note: To find secondary analysis URNs for a specific pipeline, click on the pipeline in the **Pipelines** section in BioInsight Platform Core, and view the Information tab.
3. \[Optional] One or more `Cloud__Pipeline` entries set to a valid Platform Core URN for secondary analysis.
```csv
[Cloud_Settings]
GeneratedVersion,0.0.0
Cloud_Workflow,ica_workflow_1
BCLConvert_Pipeline,urn:ilmn:ica:pipeline:#
Cloud_DragenGermline_Pipeline,urn:ilmn:ica:pipeline:#
```
{% hint style="info" %}
The \`\\` used in the \`\[Cloud\_\\_Settings]\` and \`\[Cloud\_\\_Data]\` must exactly match the value used in the \`\[Cloud\_Settings]\` section for the \`\[Cloud\_\\_Pipeline]\`.
{% endhint %}
# Index Orientation Guide
## Guidelines for reverse complementing i5 sequences for demultiplexing
When performing dual indexing, all Illumina sequencers read the first index (i7) in the same direction; however, the second index (i5) is read in different orientations depending on the instrument and chemistry, in particular, differences between when the paired-end turnaround and i5 read take place:
* On the MiSeq, HiSeq 2000/2500, and the **MiniSeq Rapid kits** the i5 sequence is read in the **forward orientation**.
* On the iSeq 100, MiniSeq, NextSeq 500/500, NextSeq 1000/2000, HiSeq 3000/4000/X systems, NovaSeq 6000 (**v1.5 reagents**), and the NovaSeq X/X Plus the i5 sequence is read in the **reverse complement orientation**.
{% hint style="info" %}
See the [Index Orientation Table](/run-set-up/overview/index-orientation-guide/i5-index-orientation-table) for information on when to use which orientation of the i5 sequence for these platforms depending on the analysis software used.
{% endhint %}
When demultiplexing, the final sample sheet provided to the FASTQ generation software needs to have the i5 index in the correct orientation for that platform. However, most Illumina sample sheet generation software handles this automatically. This means that these software work on the assumption that your **i5 sequence is always in the forward orientation** and will automatically create the reverse complement of the sequences provided for the appropriate instrument type.
The following provides guidance on when to reverse complement and when to not reverse complement the i5 sequences when analyzing iSeq, MiniSeq, NextSeq 500/550, NextSeq 1000/2000, HiSeq 3000/4000/X, NovaSeq 6000 (v1.5 reagents), or NovaSeq X/X Plus data.
{% tabs %}
{% tab title="Run Planning" %}
**BaseSpace Run Planning**
For Run Planning in BaseSpace, the output is always a v2 sample sheet for BCL Convert:
* NextSeq 1000/2000 and NovaSeq X/X Plus i5 indexes will correctly be output in the **forward orientation** for later downstream processing. Custom kits should also have the i5 indexes entered in the **forward orientation**.
* For other supported platforms (such as the NovaSeq 6000), Run Planning will add a line to the Header section of the v2 sample sheet (IndexOrientation,Forward) and the i5 will be written in the **forward orientation** and processed correctly downstream.
* If generating v2 sample sheets for instruments other than the ones listed, confirm the final sample sheet has the i5 index in the correct orientation as described above.
{% endtab %}
{% tab title="Manual Run Upload" %}
**Runs Uploaded Manually**
For runs uploaded manually (i.e., an Illumina tool is not being used to generate the sample sheet), the index orientation depends on which instrument you are using. Please see the [Index Orientation Table](/run-set-up/overview/index-orientation-guide/i5-index-orientation-table) for information on how to enter the i5 sequence depending on the instrument and software used.
{% endtab %}
{% tab title="IEM" %}
**IEM**
When using IEM, i5 sequences must be entered into these software in the **forward orientation** in all circumstances and for all instrument types.
The sequences displayed are what is entered into the final sample sheet. Kit definitions have the i5 in the forward orientation. The i5 sequences will be appropriately reverse complemented and displayed in the IEM interface based on instrument/reagent type. IEM will use the instrument/reagent type selected in the setup wizard to generate the final sample sheet with the i5 sequences in the correct orientation.
{% endtab %}
{% tab title="PrepTab" %}
**BaseSpace PrepTab**
When using BaseSpace Sequence Hub PrepTab, i5 sequences must be entered into these software in the **forward orientation** in all circumstances and for all instrument types.
The software automatically creates the reverse complement as needed for analysis. If the sequence is reverse complemented, this will only be shown in the SampleSheetUsed.csv file.
{% endtab %}
{% tab title="LRM" %}
**LRM**
When using LRM, i5 sequences must be entered into these software in the **forward orientation** in all circumstances and for all instrument types.
The software automatically creates the reverse complement as needed for analysis. If the sequence is reverse complemented, this will only be shown in the SampleSheetUsed.csv file or the SampleSheet.csv file created by LRM at the analysis start. LRM will detect the instrument type from the run files and create a final sample sheet with the i5 indexes in the correct orientation for that platform.
{% endtab %}
{% endtabs %}
#### **Important Caveats for MiniSeq Rapid Kits**
* The MiniSeq Rapid made a recipe change that uses the grafted oligo for the i5 index priming, so it is read in the forward orientation similar to a MiSeq.
* If running in manual mode and using bcl2fastq or BCL Convert, or uploading the sample sheet to BaseSpace as a manual mode run and attaching a sample sheet, enter the i5 sequence in the **forward direction**. Runs uploaded in manual mode have their data directly passed to bcl2fastq with no further processing.
* For Local Run Manager (LRM), input the sequences in the **reverse complement** when setting up the run so the software automatically creates the **forward orientation** as needed for analysis. This is the opposite of most of our guidance and is only for the MiniSeq Rapid kits.
#### **Color Balance Considerations**
When assessing index sets for color balance, the sequence *observed* by the instrument must be assessed, regardless of the orientation used for the sample sheet. For the i7 index, always asses color balance using the "i7 bases for sample sheet" column orientation. For the i5 index, assess color balance using the forward orientation for MiSeq runs and MiniSeq runs with rapid reagents, and the reverse-complement orientation for all other instruments.
#### Which orientation are the indexes in Top\_Unknown\_Barcodes output from BclConvert?
For The NextSeq 1000/2000 and NovaSeq X/X Plus platforms, the RunInfo.xml file includes the IsReverseComplement flag. With this flag, the index sequences that BCL Convert recognizes and outputs are in the following orientations in the Top\_Unknown\_Barcodes output file.
* Index 1: the i7 index column is in the forward orientation (match the orientation if the i7 indexes in the sample sheet).
* Index 2: the i5 index column is in the reverse complement orientation (are the reverse complement of the i5 indexes in the sample sheet).
For all instruments, the indexes shown in the Top\_Unknown\_Barcodes are the sequences as they were sequenced/read by the sequencer.
# i5 Index Orientation Table
This table describes how to enter the i5 sequence, Forward (F) or Reverse Complement (RC), depending on the instrument and software used.
{% hint style="info" %}
* LRM: Local Run Manager
* IEM: Illumina Experiment Manager
* BSSH: BaseSpace Sequence Hub
* IRM: Illumina Run Manager
* Manual Edit: When manually preparing the Sample Sheet in the text editor
{% endhint %}
[^1]: MiniSeq Rapid Kits: Always forward orientation
# Resources
Please see the pages below for troubleshooting guidance.
* [BCL Convert Parameter Usage](/run-set-up/overview/resources/bcl-convert-parameter-usage)
* [Illumina Knowledge Help](/run-set-up/overview/resources/illumina-knowledge-help)
* [FAQ](/getting-started/rg-faq)
# BCL Convert Parameter Usage
In this section, we highlight various desired outcomes and provide examples to show how they can be achieved.
{% hint style="info" %}
For more information on how to use each parameter, see the [Instrument Settings](/run-set-up/overview/instrument-settings) guide.
{% endhint %}
Depending on version, index collision checks are relaxed, strict, or configurable:
3.9.x: Relaxed by default, no option to change. A collision in one index can be rescued by having enough diversity in the combined dual index sequence.
v3.10 and 4.0: Strict by default, no option to change. For a dual index run, requires only 1 index (index1 or index2) to have a collision in order to error out based on a barcode collision. Identical indexes within index1 or index2 (combinatorial dual indexes) still supported.
4.1.5: Strict by default but configurable to relaxed mode using sample sheet option:
CombinedIndexCollisionCheck,value Where value corresponds to the number of the lane or lanes to use this behavior; multiple lane values should be semicolon-separated.
4.1.7 and 4.2.x: Relaxed mode by default. CombinedIndexCollisionCheck removed. Mode now configured by using sample sheet option:
IndependentIndexCollisionCheck,value to allow optional strict checking, where value corresponds to the number of the lane or lanes to use this behavior; multiple lane values should be semicolon-separated.
Note: OverrideCycles can be specified in the BCL Convert Settings section to be applied globally or in the BCL Convert Data section to be applied uniquely per-sample.
Index FASTQs
CreateFastqForIndexReads, 0 or 1 (default 0)
Minimum Number of ATCG Bases per Read
MaskShortReads,# (default 22)
Minimum Read Length
MinimumTrimmedReadLength,# (default 35)
Trimming last bases when they match the adapter
MinimumAdapterOverlap,# (default 1, 1-3 allowed) Never trims or masks less than X bases when they overlap with the adapter provided regardless of stringency settings, where X is the MinimumAdapterOverlap provided.
UMI Settings
OverrideCycles,U# TrimUMI,0 or 1 (default 1)
Use a subset of bases for i7/i5 indexes
Use subset of index cycles for demultiplexing by providing shortened sequence in index or index2 column and providing desired length in OverrideCycles setting (default use all index cycles defined in RunInfo.xml)
# Illumina Knowledge Help
[Illumina Knowledge](https://knowledge.illumina.com/) is a knowledge base which hosts a variety of articles related to sequencers, sample sheet, analysis and troubleshooting. See below for some relevant articles.
#### Troubleshooting
* [Troubleshooting Demultiplexing issues using onboard DRAGEN on the NextSeq 1000/2000](https://knowledge.illumina.com/software/on-instrument-analysis-software/software-on-instrument-analysis-software-reference_material-list/000003817)
* [Troubleshooting Sample Sheet will not Load into MiSeq Control Software](https://knowledge.illumina.com/instrumentation/miseq/instrumentation-miseq-troubleshooting-list/000001455)
* [Sample Sheet Import Errors on the NextSeq 1000/2000](https://knowledge.illumina.com/instrumentation/nextseq-1000-2000/instrumentation-nextseq-1000-2000-troubleshooting-list/000003521)
# MiSeq: Run Set Up
## Configure Cloud Connectivity in MiSeq Control Software
1. From the **Main Menu**, select **System Settings**.
2. Select the **Run Settings** tab.
3. Select the **BaseSpace** tab.
4. *Optional*: Select **Turn on Illumina Proactive Support** to enable the Illumina Proactive monitoring service.
5. Select the region the instrument should connect to. This setting is used to ensure proper data storage is sent to Illumina Proactive Support and BaseSpace Sequence Hub.
6. *Optional:* Select **Private Domain** and enter the private domain of your Enterprise BaseSpace Sequence Hub account, if applicable.
## Set Up Sequencing Run with Cloud Analysis Sample Sheet
1. From the Home screen, select **Sequence**.
2. From the Run Setup Option screen, select **Manual**.
3. From the BaseSpace Options screen, select **Use BaseSpace™ Sequencing Hub for this run**.
1. Select the **Run analysis, collaboration, and storage** option to send all run data to BaseSpace Sequence Hub.
2. Enter your BaseSpace Sequence Hub account credentials.
3. Select **Sign In**.
4. Select the Workgroup.
4. Select **Next**.
5. Set the Read Type, Read Length and Custom Primers for all of your cycles.
6. Browse to select your sample sheet file. See [here](/run-set-up/overview/auto-launch-settings#e2euserguidedraftmiseq-userunplanningtoexportasamplesheet) for information on how to download a sample sheet file.
7. Select Next.
8. Continue to set up the sequencing run as per the [MiSeq System Product Documentation](https://support.illumina.com/downloads/miseq-product-documentation.html).
# Analysis Products
Data analysis software includes a broad spectrum of products covering variant calling, annotation, pipeline development, data management, storage and sharing. The products cover multiple applications (eg, germline, somatic, infectious disorders, and microbiology), data types (eg, sequencing, microarrays, multiomics), analysis throughput, deployment mode (eg, cloud, on-premises, on-board), and other options.
Refer to the respective documentation sites via the links below for more information. Access the full list of Illumina software products at the [Illumina Support Center](https://support.illumina.com/).
Cover image
🧬 Secure storage, management, and analysis of large volumes of multiomics data.
# Cloud Analysis Auto-launch
Cloud analysis auto-launch refers to the automated launch of secondary analysis by Illumina's cloud platforms after a sequencing run is completed. Coupled with the ability to automatically output sequencing data to a cloud location, the auto-launch functionality minimizes user touchpoints and decreases turnaround time.
Sequencing run management, including run planning, run monitoring, and viewing results, is performed via BaseSpace Sequence Hub (BaseSpace). The post-sequencing secondary analysis (ie, demultiplexing, DRAGEN) is powered by Illumina BioInsight Platform Core (formerly Illumina Connected Analytics) pipelines. The analysis results are stored in an /ilmn-analyses/\ subfolder in Illumina BioInsight Platform Core. See the [Sequencer Auto-launch Analyses Compatibility](/analysis/sequencer-reference) table for available instruments and pipelines.
* **BaseSpace** is used for sequencing run planning and monitoring. See [BaseSpace Setup ](#basespace-setup)for more information.
* **Illumina BioInsight Platform Core** is used to store sequencing run data and perform secondary analysis. See [Sequencer Run Data in Illumina BioInsight Platform Core](#sequencer-run-data) for more information.
1. **Run Planning** - performed in BaseSpace to configure a sequencing run including choosing instrument type, analysis, and sample settings.
2. **Start Sequencing Run** - performed on the sequencing instrument to select the planned run and launch the run.
3. **Data Upload and Run Monitoring**
* Data Upload - the sequencing instrument uploads the sequencing run output data to Platform Core.
* Run Monitoring - sequencing run monitoring is available in BaseSpace.
4. **Auto-launch Analysis** - the secondary analysis is automatically launched in Illumina BioInsight Platform Core upon sequencing run completion.
5. **Auto-launch Analysis Monitoring** - the secondary analysis status is monitored in BaseSpace.
6. **Edit & Requeue SampleSheet to trigger #4 (optional)** - if an error occurs during secondary analysis, the analysis may be requeued (re-launched) from BaseSpace.
Further details about each step above is described in the sections below.
## BaseSpace Setup
BaseSpace settings must be configured to send sequencing run data to Platform Core prior to sequencing. For workgroups, this must be configured by the workgroup administrator. Workgroup users have read-access to the toggle switch setting, but cannot modify it.
Navigate to the BaseSpace Settings view. In the "Settings" section, set the "Platform Core Run Storage" setting to ON.
{% hint style="info" %}
This setting is not necessary for NovaSeq X Series instrument type
{% endhint %}
{% hint style="info" %}
The visibility of the "Platform Core Run Storage" configuration setting is controlled by Illumina support. Contact Illumina Support to request the setting be made available for your domain.
{% endhint %}
## Sequencing Run Planning
Sequencing run planning in BaseSpace Sequence Hub is the first step in preparing a sequencing run with automated post-sequencing analysis.
A sequencing run can be started from the instrument using either:
1. Planned sequencing run setup in Basespace Run Planning (recommended). See [Plan the Sequencing Run](/cross-product-tutorials/novaseqx-bcl-autolaunch#plan-the-sequencing-run) for a guided example.
2. Sample Sheet imported during the on-instrument Run Setup. See [Cloud Analysis Auto-launch Settings](/run-set-up/overview/auto-launch-settings) for more information.
Refer to [Sequencer Autolaunch Analyses Compatibility](/analysis/sequencer-reference) for guidance on sequencer compatibility with different versions of analyses applications.
## Sequencing Run Monitoring in BaseSpace
Monitoring the status of an ongoing sequencing run is done through BaseSpace. See the [View Runs](https://help.basespace.illumina.com/data/view-data/view-runs) BaseSpace help documentation for more information.
1. Find the sequencing run in BaseSpace Sequence Hub by logging in, selecting the Runs tab, and selecting the appropriate sequencing run from the list.
2. When the sequencing run completes uploading, the run status in BaseSpace Sequence Hub will move to **Pending Analysis**. Analysis will automatically launch based on the information in the Sample Sheet.
1. If there is an issue with the Sample Sheet, the status will move to **Needs Attention**. Use the Requeue feature to correct any issues and re-launch analysis*.* See [Requeue Analysis](#requeue-analysis).
3. When the analysis launches, the run status will move to **Analyzing**. The associated analysis can be found on the Run Details tab under Latest Analysis, or in the Analysis list.
4. Click the analysis link to go to the **Analysis Details** page. Information about the analysis progress will be displayed in the Logs section.
1. If the analysis aborts with an error, logs and any files that had been produced prior to the error will available in the Files tab.
5. When the analysis completes, any aggregate and/or sample reports can be viewed in the Reports tab. Logs and other output files can be viewed in the Files tab.
## View Sequencer Run Data and Analysis
{% tabs %}
{% tab title="View Files in Illumina BioInsight Platform Core" %}
**Sequencer Run Data in Illumina BioInsight Platform Core**
Sequencer run data is stored in Illumina BioInsight Platform Core in an [externally-managed project](https://help.ica.illumina.com/home/h-projects#externally-managed-projects) created by BaseSpace. Operations in BaseSpace, including planning and monitoring instrument runs, are performed in a given user or workgroup *context*. To preserve permission boundaries between applications, an externally-managed project is created for each user/workgroup context per region. The Illumina BioInsight Platform Core project will be named using the convention `BSSH {context name}`, where *{context-name}* is the user or workgroup name operating in BaseSpace. For workgroups, the project will be created on behalf of the workgroup owner. The project Team includes an entry for the workgroup to grant all workgroup users read-only access to the project. While Team members may be assigned the Contributor role in the externally-managed project, they will not have write access (ie, create/delete data, run pipelines) in the project.
In the example below, the project is created for a workgroup with name "Research" where the workgroup owner is "".
The project contains the following tags:
* Technical Tags: `bssh.project.user:{user/workgroup ID}`
For workgroups, users who are members of the workgroup will have access to the data in the externally-managed project.
All sequencing run data is stored in the `ilmn-runs` folder. Within that folder, the data for each sequencing run is stored in a sub-folder named based on the run name used to create the run during run planning (or as specified in the `RunName` row of the `[Header]` section in the sample sheet) appended with a unique identifier.
The screenshot below provides an example of a sequencer run output folder uploaded to Illumina BioInsight Platform Core.
{% hint style="info" %}
Sequencer run data uploaded directly to Illumina BioInsight Platform Core via CLI or Service Connector to a user-managed project will not be available in BaseSpace.
{% endhint %}
{% hint style="info" %}
Sequencer run data stored outside of Illumina BioInsight Platform Core or BaseSpace may be uploaded using the BaseSpace CLI (command-line interface) to make it available in both BaseSpace and Illumina BioInsight Platform Core.
Use the BaseSpace [Uploading a run](https://developer.basespace.illumina.com/docs/content/documentation/cli/cli-examples#Uploadingarunanamerun-uploada) instructions to upload a sequencer run output folder.
{% endhint %}
**Automated Secondary Analysis in Illumina BioInsight Platform Core**
When the sequencing run data upload has completed, the post-sequencing secondary analysis described in the sample sheet will be automatically started.
In Illumina BioInsight Platform Core, secondary analyses launched after a sequencing run completes is orchestrated by a parent process called a *Workflow Session*. The workflow session serves as a parent process orchestrating the secondary analysis, including launching secondary analysis pipelines and creating sample entities in Illumina BioInsight Platform Core.
Upon completion of the sequencing run data upload, a workflow session record is created and visible in the Illumina BioInsight Platform Core "Analyses" view. The workflow session record can be identified by the User Reference, which will have "ws" preceding the run name.
The workflow session details view includes a section **Orchestrated Analyses** to indicate analyses launched by the workflow session as part of the automated secondary analysis. These orchestrated analyses are driven by the information in the sample sheet, including the pipeline to launch, reference data, and sample-specific settings.
{% hint style="info" %}
Currently, only a limited set of Illumina-provided pipelines are compatible with workflow session automation.
{% endhint %}
{% endtab %}
{% tab title="View Files in BaseSpace" %}
**Sequencer Run Data in BaseSpace**
For users intending to use BaseSpace for FASTQ generation and DRAGEN Secondary Analysis, the data will be associated with several BaseSpace Projects.
**1**. **SampleSheet ProjectName**
When using ProjectName values in Run Planning, the FASTQ files will be written to those locations.
In the SampleSheet.csv, this will be reflected in the \[Cloud\_Data] section.
Once BCL Convert (and any associated downstream analysis) is completed, the FASTQ files will be associated with the ProjectName specified on BaseSpace. The project column is not required to be specified, and if left blank, the FASTQ Files will be written to a BaseSpace project following the nomenclature:
**2**. **bssh**\_\[**region**]\_\[**run ID**]
For example:
bssh\_use1-prod\_277283070
More information about regions can be found in the BaseSpace Help center article [Global Regions](https://help.basespace.illumina.com/manage-your-account/regions). The run ID corresponds to the numerical value observed in the web address bar when viewing the run.
If any DRAGEN Secondary analysis is performed, this project will also contain the DRAGEN output.
{% endtab %}
{% endtabs %}
## Requeue Analysis
{% tabs %}
{% tab title="Requeue Analysis in Illumina BioInsight Platform Core" %}
**Manually Launch Analysis in Illumina BioInsight Platform Core**
There may be situations when an analysis needs to be launched manually in Illumina BioInsight Platform Core, such as if the auto-launched analysis failed. Analyses can be launched manually in Illumina BioInsight Platform Core with a few extra steps to prepare the input data.
For example, if the demultiplexing analysis fails due to a sample sheet mistake or a system error, the analysis can be launched manually in Illumina BioInsight Platform Core by following these instructions:
1. Create a new or choose an existing user-managed project to link the data to and run the analysis in.
2. Follow instructions to [Link Project Data](https://help.ica.illumina.com/project/p-data#link-project-data) to link the sequencing run output data to the user-managed project data.
{% hint style="warning" %}
The "ilmn-runs" folder contains all sequencer run data managed by BaseSpace and should not be linked to a user-managed project. Only link individual sequencer run output folders within the ilmn-runs folder. See [Sequencer Run Data](#sequencer-run-data) for details on how to find the correct folder to link.
{% endhint %}
3. Link the Bundle containing the Illumina BioInsight Platform Core pipeline to the user-managed project (e.g., "DRAGEN Analysis 4.1.7 - Sequencer Integration Only") (See [Link Bundles](https://help.ica.illumina.com/project/p-details#link-bundles)).
4. Fix the sample sheet by downloading the original sample sheet from the sequencing run output folder, modify, and re-upload the file to the user-managed project.
5. Launch the pipeline (e.g., BclConvert\_v4\_1\_7) with the corrected sample sheet as input.
{% embed url="" %}
Manually Launch an Analysis in Illumina BioInsight Platform Core
{% endembed %}
{% endtab %}
{% tab title="Requeue Analysis in BaseSpace" %}
**Requeue Analysis in BaseSpace**
The secondary analysis for a sequencing run may need to be re-executed for a variety of reasons including:
* Fix a Sample Sheet error
* Intermittent analysis failure
The operation to manually relaunch the secondary analysis is referred to as "requeue". Requeues are performed from BaseSpace Sequence Hub.
{% hint style="info" %}
* This instruction below can be used to requeue auto-launch analysis for NovaSeq X/X Plus, NovaSeq 6000, NextSeq 500/550, NextSeq 1000/2000.
* **Requeue > Sample Sheet** will load the original sample sheet and can be modified directly in the browser. This is for advanced users and less validation of the sample sheet will be performed than if using **Requeue > Planned Run.**
{% endhint %}
To requeue autolaunch analysis in the BaseSpace UI, follow the steps:
1. Click on your run in the "Runs" tab. From the Run Summary Page, select **Status > Requeue > Planned Run.**\\
Upload your new, corrected Sample Sheet. This should be the v2 sample sheet that is used for autolaunch.
{% endtab %}
{% endtabs %}
## Using API to Launch Analysis
There may be situations when an analysis needs to be launched manually with the Illumina BioInsight Platform Core API if the auto-launched analysis failed. Use the API to create an analysis and **set the input type to basespace** (for example `/api/projects/{projectId}/analysis:nextflow` with `analysisInput > inputs > externalData > type:basespace`) This works for both files and folders.
```
{
"externalData": [
{
"url": "https://api.servername.illumina.com/v2/files/your_files",
"type": "basespace",
"mountPath": "/location_where_input_file_is_saved_on_machine_running_pipeline",
"basespaceDetails": {
"workgroupId": "wid:123" (Optional workgroup id to filter on)
"extensions": "vcf" (Optional BSSH API query param to filter based on file extensions)
"pathPrefix": "/path/to/files" (Optional BSSH query string param to filter files/folder)
}
}
]
}
```
## Secondary Analysis Troubleshooting
Secondary analysis failures may happen for a variety of reasons. When an error occurs, the Sequencing Run in BaseSpace will indicate a failure with the analysis. Depending on the specific failure, the workflow session and/or the orchestrated analysis in Illumina BioInsight Platform Core will indicate a "Failed" status with an Error output in the details view.
Starting with BaseSpace 7.29, there is now improved error reporting through BaseSpace. A link in the logs section of the Analysis Summary tab opens a modal displaying a list of failed steps and relevant log file contents.
### Analyses Not Showing Up in Illumina BioInsight Platform Core
* If no BaseSpace-managed runs appear in Illumina BioInsight Platform Core, verify in [IAM](https://help.ica.illumina.com/account-management/am-iam) that the workgroup used in BaseSpace **has access** to Illumina BioInsight Platform Core.
* Ensure that the option **Has Access** is selected in [IAM](https://help.ica.illumina.com/account-management/am-iam) as the option **Has Access+Archive** has been decommissioned.
# Sequencer Auto-launch Analyses Compatibility
This page provides guidance on sequencer compatibility with different versions of DRAGEN secondary analysis pipelines and applications with auto-launch capabilities. This includes:
* Pipelines with [cloud analysis auto-launch](/analysis/analysis_autolaunch). This type of workflow is available for BaseSpace and BioInsight Platform Core (formerly ICA) users and includes automatic launch of secondary analysis in the cloud after sequencing completion.
* Applications installed onboard of sequencers and on DRAGEN servers paired with sequencers. These type of applications allow you to configure settings for the run and analysis upfront and launch secondary analysis automatically after sequencing completes.
* Tertiary analysis compatibility. Click on underlined versions in the table to view details on pipelines’ compatibility with Emedgene and Illumina Connected Insights.
This table does not cover all DRAGEN pipelines and applications. If a pipeline is not included in the table, it means that the auto-launch may not be available for it at all or not available for a specific instrument/pipeline combination. In this case, the pipeline could be used with the instrument if launched manually in BaseSpace, Platform Core or on the DRAGEN server. Non-DRAGEN pipelines are not included. Please check [Local Run Manager materials](https://support.illumina.com/sequencing/sequencing_software/local-run-manager.html) and other resources on [Illumina Support Center](https://support.illumina.com/) for additional onboard applications.
[^1]: * Compatible with Illumina Connected Insights
[^2]: * Onboard app v1.0.13
[^3]: * Onboard app v1.0.41
# Interpretation Products
Interpretation software includes products that help generate meaningful clinical insights from NGS and other data. They cover statistical and visualization tools, solutions for cohort analysis, variant interpretation, and report generation.
Refer to the respective documentation sites via the links below for more information. Access the full list of Illumina software products at the [Illumina Support Center](https://support.illumina.com/).
🧬 Customizable automated variant interpretation for somatic oncology.
# Multiomics Products
Multiomics software offers a comprehensive range of solutions to streamline your journey from sample collection to multiomic insights. Discover analysis for designed for protein data, spatial data, single-cell RNA data, and more.
Our powerful study management tool helps organize your data from ingestion to analysis, while our advanced analysis platform generates actionable insights to drive your research forward.
Refer to the respective documentation sites via the links below for more information. Access the full list of Illumina software products at the [Illumina Support Center](https://support.illumina.com/).
Cover image
🧬Scalable platform for multiomic data analysis, visualization, and biological interpretation across modalities.
# NovaSeq X: BCL Convert Auto-launch Analysis in Cloud
This section provides a guided example of the end-to-end user flow for performing a sequencing run with data storage and automated analysis in BioInsight Platform Core.
{% embed url="" %}
Analysis Auto-launch Tutorial
{% endembed %}
## Configure BaseSpace
Follow [BaseSpace Setup](/analysis/analysis_autolaunch#basespace-setup) instructions to configure sequencing run upload to Platform Core.
## Plan the Sequencing Run
BaseSpace Run Planning provides an interface for planning a sequencing run. Only specific sequencing instruments support Basespace Run Planning. Refer to [Sequencer Auto-launch Analyses Compatibility](/analysis/sequencer-reference) for details.
Navigate to [BaseSpace](https://basespace.illumina.com/) and change to your desired workgroup or personal context. This may require you login to your domain first.
After selecting the appropriate user/workgroup context, navigate to the Runs tab in BaseSpace. Then click the New Run button and select Run Planning.
Use the guided Basespace Run Planning to create a planned run. See the [BaseSpace Run Planning](https://help.basespace.illumina.com/sequence/plan-runs) documentation for details.
Set the Analysis Location to "BaseSpace/BioInsight Platform Core" to configure for Cloud analysis.
The configuration input forms vary depending on the instrument type, including the available secondary analysis applications (see [Sequencer Autolaunch Analyses Compatibility](/analysis/sequencer-reference) for details). Subsequent configuration input forms vary depending on the secondary analysis application chosen. The images below demonstrate screens using a NovaSeq X Series instrument with Illumina DRAGEN BCL Convert analysis.
Upon completion of the Run Planning inputs, the sequencing run can be either saved as a planned run in BaseSpace or exported as a Sample Sheet, depending on the instrument type.
## Start the Sequencing Run
Follow the instructions for the sequencer to execute the planned sequencing run for cloud analysis. If the sequencer does not support consuming planned runs from BaseSpace, attach the sample sheet generated by Run Planning to a manual mode sequencing run.
## Monitor the Sequencing Run
After a sequencing run is started, BaseSpace is used for monitoring the run through completion. Use the [BaseSpace Run Summary](https://help.basespace.illumina.com/data/view-data/view-runs/run-summary) view to track the run progress.
## View Sequencing Run Output
Refer to [Sequencer Run Data in Platform Core](/analysis/analysis_autolaunch#sequencer-run-data) for guidance on viewing the sequencing run data in Platform Core.
## Monitor Secondary Analysis
In Platform Core, the workflow session is launched and a record is present in the Analyses view in the project. The workflow session record can be identified by the User Reference, which will have "ws" preceding the run name.
Check the "status" of the workflow session to monitor progress in Platform Core. As orchestrated analyses are launched, analysis records will show in the Analyses view and in the workflow session details.
The workflow session details contain an "Orchestrated Analyses" section with the secondary analyses launched by the workflow session listed. Check the "status" of each analysis for progress. In the example below, a BCL Convert pipeline is launched by the workflow session.
The workflow session details also contain links to the BaseSpace Run Summary, which provides further information about the analyses, such as metrics, logs and reports.
## View Secondary Analysis Results
The analysis output folder is stored in the `ilmn-analyses` folder in the project data view. The output folder name can be found in the Analysis Details view in the Output Files section. Filter for the correct output folder by copying the folder name from the Analysis Details view. The image below shows an example output folder from a BCL Convert automated analysis.
Post-sequencing automated analysis will typically include a demultiplex step using the Illumina-provided BCL Convert pipeline. The demultiplexed outputs from this pipeline result in the creation of project sample assets linked to associated demultiplexed data (ie, FASTQs).
### Link Output Data to Other Projects
With analysis data available in the BaseSpace externally-managed project, the data can be linked to other Platform Core projects to serve as inputs for running pipelines, etc. Users with access to the BaseSpace externally-managed project can create links from the destination project Samples and Data views. See the [Link Project Data](https://help.ica.illumina.com/project/p-data#link-project-data) and [Link Project Sample](https://help.ica.illumina.com/project/p-samples#link-project-sample) Platform Core documentation for details on linking sample data.
# NovaSeq 6000: BCL Convert Auto-launch Analysis in Cloud
This tutorial will walk through the end-to-end flow for running a NovaSeq 6000 sequencing run with secondary analysis auto-launch in BioInsight Platform Core (formerly ICA). The secondary analysis will consist of BCL Convert only.
{% hint style="info" %}
This tutorial is intended to provide guidance for the cloud analysis-related functions. Specific settings and configurations for sequencing will need to be modified for compability.
{% endhint %}
The main steps in the tutorial consist of:
1. Run Planning
2. Prepare Sample Sheet
3. Instrument Run Setup
4. Run Monitoring
5. Analysis Monitoring
6. Review Analysis Output
Follow the [BaseSpace Setup](/analysis/analysis_autolaunch#basespace-setup) instructions to configure BaseSpace to upload run data to Platform Core.
## Run Planning
To plan the sequencing run, navigate to BaseSpace Sequence Hub.
1. Go to the "Runs" view using top menu navigation.
2. Click the "New Run" button.
3. Click "Run Planning".
Follow the Run Planning input form:
1. Input the RunName (ie, NovaSeq6000Tutorial).
2. Set the Instrument Platform to "NovaSeq".
3. Ensure Secondary Analysis is set to "BaseSpace".
4. Click "Next".
Complete the next input form:
1. Set the Application to "Illumina BCL Convert for Platform Core - 4.1.5".
2. Set the Library Prep Kit (ie, Illumina DNA Prep).
3. Set the Index Adapter Kit (ie, Nextera DNA CD Indexes (24 Indexes, 24 Samples)).
4. Click Next.
Complete the next input form to configure the settings for the secondary analysis, including settings used for demultiplexing.
1. Select the Library Prep Kit (ie, Illumina DNA Prep).
2. Set the Index Reads (ie, 2 Indexes).
3. Set the Read Type (ie, Paired End).
4. Set the Read Lengths.
5. Complete the Sample form, including Lane, Sample ID, and index information.
6. (Optional) Add analysis settings.
7. Click Next.
Review the planned run on the final screen. Once the planned run is confirmed, click the "Export" button to download the Sample Sheet. The Sample Sheet location will need to be accessible from the instrument (ie, USB Drive, Network Location, etc.).
## Instrument Run Setup
Start the NovaSeq 6000 instrument. Refer to the [NovaSeq 6000 documentation](https://support.illumina.com/sequencing/sequencing_instruments/novaseq-6000/documentation.html) for details.
During the Login step, select "Illumina Cloud Options" and "Run Monitoring and Storage" to have the run monitoring and secondary analysis performed in BaseSpace and Platform Core. Login to the same account used to plan the run and click Next.
Refer to the [NovaSeq 6000 documentation](https://support.illumina.com/sequencing/sequencing_instruments/novaseq-6000/documentation.html) for guidance on the Run Setup screen.
Select to "Browse" for the Samplesheet and select the modified sample sheet from the last section. Click Next when complete.
Review the run configuration on the final screen. Once confirmed, click to Start Run.
## Run Monitoring
Once the run has been started on the instrument, the run will show in the BaseSpace Runs view after the connection has been established from the instrument to BaseSpace.
Navigate to BaseSpace and select "Runs" in the top menu navigation. Find the run name specified during Run Planning. Click to view the Run Summary view.
Run data will be uploaded to Platform Core. Navigate to Platform Core to verify the data is present.
## Analysis Monitoring
Secondary analysis will start after the sequencing run data has been uploaded. BaseSpace will indicate the analysis starting on the Run Summary view in the "Pending Analyses" list.
Once the analysis has been launched, a workflow session is launched in Platform Core. This can be found in the BaseSpace externally-managed project where the sequencing run data is uploaded. See [Sequencer Run Data in Platform Core](/analysis/analysis_autolaunch#sequencer-run-data) for more information.
Navigate to the "Analyses" view within the project to find the workflow session. As the workflow session runs, the secondary analysis pipelines are launched and show in the "Analyses" view, or in the "Orchestrated Analyses" section of the workflow session details view. See [Automated Secondary Analysis in Platform Core](/analysis/analysis_autolaunch#automated-secondary-analysis-in-ica) for more information.
## Review Analysis Output
The results of the secondary analysis can be viewed in BaseSpace and Platform Core.
To view the analysis results in BaseSpace:
1. Navigate to the Run Summary view.
2. Click the analysis in the Latest Analysis or Prior Analyses sections.
3. Analysis results are shown in the Summary. Navigate to the Files tab to find the output files.
To view the analysis results in Platform Core:
1. Navigate to the BaseSpace externally-managed Platform Core project corresponding to the workgroup/user the run was performed with.
2. Navigate to the Project Analyses.
3. Find the analysis with the User Reference prefixed with the sequencing run name.
4. Click to view the analysis details.
5. Copy the User Reference.
6. Navigate to the Project Data.
7. Search the Project Data using the copied User Reference value from step 5.
8. Navigate into the folder resulting from the filter to find the analysis output data.
# NovaSeq 6000Dx: TSO 500 Auto-launch Analysis in Cloud
This section provides a guided example of the end-to-end user flow for a sequencing run for TruSight Oncology 500 on NovaSeq 6000Dx (RUO mode). The workflow includes automated data streaming to cloud and auto-launch of secondary analysis minimizing manual touchpoints. The tutorial covers:
1. Instrument and BaseSpace configuration.
2. Run Set-up, start and monitoring.
3. Accessing data in BioInsight Platform Core (formerly ICA) and BaseSpace.
## Instrument and BaseSpace Configuration
### Configure BaseSpace
Follow [BaseSpace Setup](/analysis/analysis_autolaunch#basespace-setup) instructions to configure sequencing run upload to Platform Core.
### Configure BaseSpace connection on NovaSeq 6000Dx
1. On the RUO side of the instrument, select **Instrument Settings**.
3. Select **RUO SETTINGS** tab to configure BaseSpace connection.
4. Select the box **BaseSpace Sequence Hub: (Optional to upload and store run data in cloud server)**
5. Select **Run Monitoring and Storage** (image below) in the hosting location dropdown menu
6. Choose the region where BaseSpace is hosted from the hosting location dropdown menu
8. Specify the domain name. It is only possible to use a private domain. Contact the IT department to add the correct URLs to the firewall allow list. For further information, please refer to [Network Connections](https://support-docs.illumina.com/SHARE/NetworkSecurity/Content/SHARE/NetworkSecurity/NetworkConnections.htm) and [Control Computer Firewall](https://support-docs.illumina.com/SHARE/NetworkSecurity/Content/SHARE/NetworkSecurity/ControlComputerFirewall.htm).
## Run Set-up, start and monitoring
### Plan the Sequencing Run
BaseSpace Run Planning provides an interface for planning a sequencing run.
1. Navigate to [BaseSpace](https://basespace.illumina.com/) and change to your desired workgroup or personal context. This requires you to login to your domain first.
2. Navigate to the "Runs" tab in BaseSpace. Select the "New Run" button and select "Run Planning".
### Create a run
1. Use the BaseSpace Run Planning tool to create a planned run.
2. Set the Analysis Location to "BaseSpace/BioInsight Platform Core" to configure for Cloud analysis.
The configuration input forms vary depending on the instrument, secondary analysis pipeline, and other selections (see [Sequencer Auto-launch Analyses Compatibility](/analysis/sequencer-reference) for details). The images below demonstrate screens using a NovaSeq 6000 Dx instrument with DRAGEN TSO500 analysis.
3. Select "DRAGEN TSO 500 Analysis Software - 2.5.2" or "DRAGEN TruSight Oncology 500 Analysis Software - 2.5.2 (with HRD)" from the **Application** drop-down menu.
4. Select **TruSight Oncology 500** or **TruSight Oncology 500 High Throuput** From the **Library Prep Kit** drop-down menu.
5. Click **Next** to navigate to the next step.
6. Enter the names of the samples in the run. Alternatively, you can download a sample template by clicking "DOWNLOAD TEMPLATE" as indicated in the image below, then use it to import the sample information.
7. In the **Per Sample Configuration** section, add **Sample Type**, **Pair ID**, and **Sample Feature**. For HRD sample, specify "**HRD**" in the **Sample Feature** field, otherwise leave it empty.
8. Upon completion, export the sequencing run as a SampleSheet.csv file.
### Start the Sequencing Run
Follow the instructions for the sequencer to execute the planned sequencing run for cloud analysis. Attach the SampleSheet.csv saved from the previous step.
### Monitor the Sequencing Run
After a sequencing run is started, use BaseSpace to monitor the run through completion. Use the [BaseSpace Run Summary](https://help.basespace.illumina.com/data/view-data/view-runs/run-summary) view to track the run progress.
## View Sequencing Run Output
Refer to [Sequencer Run Data in Platform Core](/analysis/analysis_autolaunch#sequencer-run-data) for guidance on viewing the sequencing run data in BioInsight Platform Core.
## View Secondary Analysis Results
When secondary analysis finishes, the results can be viewed in BaseSpace in the corresponding project. The result files can be viewed and downloaded from the **Files** tab. In addition, the files can be downloaded using BaseSpace Sequence Hub CLI (BaseSpace CLI) tool.
# MiSeq: DRAGEN Amplicon and Connected Insights Auto-launch Analysis in Cloud
This tutorial provides a guided example of the end-to-end workflow for a sequencing run on MiSeq with automated launch of secondary and tertiary analysis in Illumina Connected Insights.
## Prerequisites
* The latest v4.1.0 version of MiSeq Control Software (MCS)
* Illumina BioInsight Platform Core (formerly Illumina Connected Analytics) subscription (comes with included BaseSpace subscription)
* Illumina Connected Insights subscription
* Positive balance of Genome Equivalent Samples and iCredits
* At least one workgroup
> Personal context is not supported in Connected Insights
## Configure Cloud Connectivity in MiSeq Control Software
1. From the **Main Menu**, select **System Settings**.
2. Select the **Run Settings** tab.
3. Select the **BaseSpace** tab.
4. *Optional*: Select **Turn on Illumina Proactive Support** to enable the Illumina Proactive monitoring service.
5. Select the region the instrument should connect to. This setting is used to ensure proper data storage is sent to Illumina Proactive Support and BaseSpace Sequence Hub.
6. Select **Private Domain** and enter the private domain of your BaseSpace Sequence Hub account.
## Configure BaseSpace
1. Log in to BaseSpace as the Workgroup Owner and make sure the desired workgroup is selected.
> Workgroup Administrators can change the workgroup owner in IAM Console
2. Click on the workgroup name from the BaseSpace header, select **Settings** from the expanded menu.
3. Make sure **Illumina BioInsight Platform Core** is turned on.
## Configure Connected Insights
1. Log in and navigate to Connected Insights, making sure the same workgroup is selected as in the previous steps.
2. *Optional*: Navigate to **Configuration -> Report Automation** and configure report automation with preferred settings. This feature allows for the automatic generation of a draft report based on user settings.
3. Navigate to **Configuration -> Test Definition** and create a test definition with preferred settings. **Turn on Report Automation** if you configured report automation settings in the previous step.
4. Navigate to **Configuration -> Data Upload -> From Illumina BioInsight Platform Core**, add the **DRAGEN Amplicon v4.2** pipeline, and select the test definition created in the previous step.
## Plan the Sequencing Run in BaseSpace
1. Log in to [BaseSpace](https://basespace.illumina.com/) and make sure the same workgroup is selected.
2. Navigate to the **Runs** tab, select **New Run**, and then select **Run Planning**.
3. Select **Instrument Platform** as "MiSeq".
4. Set the **Secondary Analysis** to "BaseSpace/BioInsight Platform Core".
The configuration input forms vary depending on the instrument platform, secondary analysis pipeline, and other selections (see [Sequencer Auto-launch Analyses Compatibility](/analysis/sequencer-reference) for details). The following images demonstrate screens using a MiSeq instrument with DRAGEN Amplicon analysis.
5. Select "DRAGEN Amplicon for Illumina BioInsight Platform Core - 4.2.7" from the **Application** dropdown menu.
6. Select the desired library prep kit from the **Library Prep Kit** dropdown menu.
7. Select **Index Adapter Kit**.
8. Click **Next** to continue.
9. Use default values for **Index Reads**, **Read Type**, and **Read Length** or change as needed.
10. Input Sample IDs and appropriate I7 and I5 indices for each sample. Alternatively, download a sample template and use it to import the sample information.
Under the **Analysis Settings** section:
11. Make sure **BAM** is selected in the **Map/Align Output Format** field. Note: Connected Insights doesn't support CRAM yet.
12. Select the **DNA BED file** matching the Library Prep Kit if DNA samples are included in the run.
13. Select **Somatic** from the **DNA Caller Variant** dropdown menu.
14. *Optional*: Select or upload a new **CNV Panel of Normal** file if DNA samples are included in the run and you want to enable the CNV caller.
15. *Optional*: Select Yes for **DNA Enable SV Calling** if DNA samples are included in the run and you want to enable the SV caller.
16. Select the **RNA BED file** matching the Library Prep Kit if RNA samples are included in the run.
17. Select No for **RNA Enable Differential Expression**.
18. In **Per Sample Configuration**, add **DNA or RNA** and **Pair ID**. One DNA sample and one RNA sample can be paired and analyzed in Connected Insights in a single case if they share the same Pair ID.
19. Upon completion, export sequencing run settings as a SampleSheet.csv file.
### Optional: Update the Sample Sheet to Provide Disease Information
Connected Insights requires sample's disease information to start the analysis. Users can provide disease information in several ways, incorporating disease information into the sample sheet is one of them.
1. Use a text editor to open the SampleSheet.csv file generated in the previous step.
2. Find `[Cloud_DragenAmplicon_ICA_Data]` or `[Cloud_DragenAmplicon_Data]` section.
3. Add `,Tumor_Type` at the end of the next line after `[Cloud_DragenAmplicon_ICA_Data]`.
4. Add [SNOMED CT](https://browser.ihtsdotools.org/) code for each sample following a `,`. Note: samples sharing the same Pair ID should have the same Tumor Type.
5. Save the file.
## Set Up Sequencing Run with Cloud Analysis Sample Sheet
1. From the Home screen, select **Sequence**.
2. From the Run Setup Option screen, select **Manual**.
3. From the BaseSpace Options screen, select **Use BaseSpace™ Sequencing Hub for this run**.
1. Select the **Run analysis, collaboration, and storage** option to send all run data to BaseSpace Sequence Hub.
2. Enter your BaseSpace Sequence Hub account credentials.
3. Select **Sign In**.
4. Select the Workgroup.
4. Select **Next**.
5. Set the Read Type, Read Length, and Custom Primers for all of your cycles.
6. Browse to select the sample sheet CSV file generated and updated in the previous step.
7. Select **Next**.
8. Continue to set up the sequencing run as per the [MiSeq System Product Documentation](https://support.illumina.com/downloads/miseq-product-documentation.html).
## Monitoring Sequencing Run
Sequencing run results will be uploaded to Illumina BioInsight Platform Core. Users can monitor the sequencing run status from the instrument or BaseSpace.
## Secondary Analysis Auto-launch
Secondary analysis will automatically start upon the sequencing run completion. Users can monitor the secondary analysis status from BaseSpace or Illumina BioInsight Platform Core.
## Tertiary Analysis Auto-launch in Connected Insights
Cases are automatically created in Connected Insights upon the successful completion of secondary analysis. The tertiary analysis automatically starts if disease information is provided in the sample sheet.
If disease information was not provided in the sample sheet, the case will be created with the "Missing Required Data" status. To start the analysis, follow these steps:
1. Log in to Connected Insights and make sure the right workgroup is selected.
2. Open a case with the "Missing Required Data" status.
3. Click the **Edit Case** button, then input the tumor type in the **Disease** field.
4. Click the **Save** button. The case will start processing after a few seconds.
For additional options to provide case disease information with the Case Metadata file, access \[DATA UPLOAD -> Custom Case Data Upload] in the Connected Insights user guide accessible in the software.
## View Tertiary Analysis Results
Users can open the case to review the tertiary analysis results after the case finishes processing and the status changes to "Ready for Interpretation". A draft report will be ready for review if the Report Automation feature is turned on.
## Requeue Secondary Analysis
Use the following steps to requeue secondary analysis in case of its failure:
1. Delete failed cases in Connected Insights if needed.
2. Log in to BaseSpace and open the run.
3. Click the hourglass icon, then select **Requeue -> Planned Run**.
4. Choose either the Sample Sheet from the run or upload a new Sample Sheet to requeue the secondary analysis.
5. New cases will be created in Connected Insights after the secondary analysis completes.
# NextSeq 550/550Dx: TSO 500 and Connected Insights Auto-launch Analysis in Cloud
This tutorial provides a guided example of the end-to-end workflow for a sequencing run on NextSeq 550 or NextSeq 500Dx (RUO Mode) with automated launch of secondary and tertiary analysis in Illumina Connected Insights.
## Prerequisites
* The latest v4.2.0 version of NextSeq 550 Control Software (NCS)
* Illumina BioInsight Platform Core (formerly Illumina Connected Analytics) subscription (comes with included BaseSpace subscription)
* Illumina Connected Insights subscription
* Positive balance of Genome Equivalent Samples and iCredits
* At least one workgroup
> Personal context is not supported in Connected Insights
## Configure Cloud Connectivity in NextSeq Control Software
1. From the NextSeq Control Software home page, navigate to **Manage Instrument**.
2. Select **System Configuration**.
3. Select **BaseSpace Sequence Hub Configuration**.
4. Change the **Hosting Location** to the appropriate region and check the box for **Private Domain**. Enter your domain name in the text box to designate the Enterprise Account Domain. Then select **Save**.
## Configure BaseSpace
1. Log in to BaseSpace as the Workgroup Owner and make sure the desired workgroup is selected.
> Workgroup Administrators can change the workgroup owner in IAM Console
2. Click on the workgroup name from the BaseSpace header, select **Settings** from the expanded menu.
3. Make sure **Illumina BioInsight Platform Core Run Storage** is turned on.
## Configure Connected Insights
1. Log in and navigate to Connected Insights, making sure the same workgroup is selected as in the previous steps.
2. *Optional*: Navigate to **Configuration -> Report Automation** and configure report automation with preferred settings. This feature allows for the automatic generation of a draft report based on user settings.
3. Navigate to **Configuration -> Test Definition** and create a test definition with **GRCh37** human reference genome. **Turn on Report Automation** if you configured report automation settings in the previous step.
4. Navigate to **Configuration -> Data Upload -> From Illumina BioInsight Platform Core**, add the **DRAGEN TruSight Oncology 500 Analysis Software v2.5.2 (with HRD)** pipeline, and select the test definition created in the previous step.
## Plan the Sequencing Run in BaseSpace
1. Log in to [BaseSpace](https://basespace.illumina.com/) and make sure the same workgroup is selected.
2. Navigate to the **Runs** tab, select **New Run**, and then select **Run Planning**.
3. Select **Instrument Platform** as "NextSeq 500/550".
4. Set the **Secondary Analysis** to "BaseSpace/Illumina BioInsight Platform Core".
The configuration input forms vary depending on the instrument platform, secondary analysis pipeline, and other selections (see [Sequencer Auto-launch Analyses Compatibility](/analysis/sequencer-reference) for details). The following images demonstrate screens using a NextSeq 550 instrument with DRAGEN TruSight Oncology 500 Analysis Software v2.5.2 (with HRD) analysis.
5. Select "DRAGEN TruSight Oncology 500 Analysis Software - 2.5.2 (with HRD)" from the **Application** dropdown menu.
6. Select "TruSight Oncology 500" from the **Library Prep Kit** dropdown menu.
7. Select "TruSight Oncology 500 (NovaSeq6000Dx with SP Flow Cell, NovaSeq6000, NextSeq)" from the **Index Adapter Kit** dropdown menu.
8. Click **Next** to continue.
9. Use default values for **Index Reads**, **Read Type**, and **Read Length** or change as needed.
10. Input Sample IDs and appropriate Index IDs for each sample. Alternatively, download a sample template and use it to import the sample information.
11. In **Per Sample Configuration**, add **Sample Type**, **Pair ID** and **Sample Feature**. One DNA sample and one RNA sample can be paired and analyzed in Connected Insights in a single case if they share the same Pair ID.
12. Upon completion, export sequencing run settings as a SampleSheet.csv file.
### Optional: Update the Sample Sheet to Provide Disease Information
Connected Insights requires sample's disease information to start the analysis. Users can provide disease information in several ways, incorporating disease information into the sample sheet is one of them.
1. Use a text editor to open the SampleSheet.csv file generated in the previous step.
2. Find `[Cloud_TSO500S_Data]` section.
3. Add `,Tumor_Type` at the end of the next line after `[Cloud_TSO500S_Data]`.
4. Add [SNOMED CT](https://browser.ihtsdotools.org/) code for each sample following a `,`. Note: samples sharing the same Pair ID should have the same Tumor Type.
5. Save the file.
## Set Up Sequencing Run with Cloud Analysis Sample Sheet
1. From the NextSeq Control Software Home screen, select **Experiment**.
2. On the Select Assay screen, select **Sequence**.
3. On the Run Setup screen, select **Manual** as run mode.
4. Select **Use BaseSpace Sequence Hub Setting** and then select "Run Monitoring and Storage". Enter your BaseSpace Sequencing Hub username and password. If prompted, select a workgroup to upload run data to. You are prompted only if you belong to multiple workgroups.
5. Select **Next**.
6. Enter a run name of your preference.
7. **Optional:** Enter a library ID of your preference.
8. From the Recipe drop-down list, select a recipe. Only compatible recipes are listed.
9. Select **Paired-End** as read type.
10. Enter the number of cycles for each read in the sequencing run using the same value as the sample sheet generated from previous step.
11. Set the output folder location for the current run. Select **Browse** to navigate to a network location.
12. Select **Browse** to navigate to a sample sheet.
13. Select **Purge consumables for this run**. The setting purges consumables automatically after the current run.
14. Select **Next**.
15. Select **Next** to start the sequencing.
## Monitoring Sequencing Run
Sequencing run results will be uploaded to Illumina BioInsight Platform Core. Users can monitor the sequencing run status from the instrument or BaseSpace.
## Secondary Analysis Auto-launch
Secondary analysis will automatically start upon the sequencing run completion. Users can monitor the secondary analysis status from BaseSpace or Illumina BioInsight Platform Core.
## Tertiary Analysis Auto-launch in Connected Insights
Cases are automatically created in Connected Insights upon the successful completion of secondary analysis. The tertiary analysis automatically starts if disease information is provided in the sample sheet.
If disease information was not provided in the sample sheet, the case will be created with the "Missing Required Data" status. To start the analysis, follow these steps:
1. Log in to Connected Insights and make sure the right workgroup is selected.
2. Open a case with the "Missing Required Data" status.
3. Click the **Edit Case** button, then input the tumor type in the **Disease** field.
4. Click the **Save** button. The case will start processing after a few seconds.
For additional options to provide case disease information with the Case Metadata file, access \[DATA UPLOAD -> Custom Case Data Upload] in the Connected Insights user guide accessible in the software.
## View Tertiary Analysis Results
Users can open the case to review the tertiary analysis results after the case finishes processing and the status changes to "Ready for Interpretation". A draft report will be ready for review if the Report Automation feature is turned on.
## Requeue Secondary Analysis
Use the following steps to requeue secondary analysis in case of its failure:
1. Delete failed cases in Connected Insights if needed.
2. Log in to BaseSpace and open the run.
3. Click the hourglass icon, then select **Requeue -> Planned Run**.
4. Choose either the Sample Sheet from the run or upload a new Sample Sheet to requeue the secondary analysis.
5. New cases will be created in Connected Insights after the secondary analysis completes.
# Software Release Notes
This page includes release notes for Account Management, which apply to all software products. For release notes related to a specific product, please refer to that product's documentation site.
## 2026 August 19
**Login and Sign Up**
* The self-serve sign-up region selector no longer includes US West.
**Fixes**
* Fixed an issue that prevented BaseSpace Professional workgroup admins from inviting new members to their workgroup.
## 2026 August 5
**Login and Sign Up**
* Users can now join a domain during login or sign-up without a direct invitation. If their email is allowed by the domain's access rules, they're automatically joined and taken into the domain; otherwise, a clear error is shown.
**Applications**
* The Applications page has been updated with minor layout and display improvements.
* Regions listed on application tiles are now ordered consistently with the region selection order used during subscription registration.
**Fixes**
* Fixed a login issue on the domain selection screen in Electron-based applications (e.g., DRAGEN Spatial) where all radio buttons could appear checked at once on certain Chromium versions, preventing login.
## 2026 July 27
**Fixes**
* Fixed an issue where saving domain settings failed with a validation error when the allowed email suffixes list was empty.
## 2026 July 22
**Login and Sign Up**
* Users who sign up through legacy Login and Sign Up pages are now directed to the unified registration experience, ensuring a consistent sign-up process across all entry points.
* Password changes made on classic login pages are now reflected in the unified login experience, so users can sign in seamlessly regardless of which interface they used to update their password.
* Single sign-on login now handles cases where the email entered and the identity returned by the identity provider differ — users are shown a confirmation page before proceeding.
* Domain administrators can now require multi-factor authentication for their domain independently of single sign-on, ensuring all users are challenged for MFA even when signing in through an external identity provider.
* Instrument users who encounter the Unified EULA during login are guided to complete EULA acceptance in a browser, preventing them from getting stuck on devices that cannot open new tabs.
* Password complexity is updated to require a minimum of 10 characters. Users whose current password does not meet the new requirements will be prompted to update it at their next login (instrument logins are exempt).
**Identity & Access Management**
* Domain administrators can now reset or remove a user's multi-factor authentication registration and clear an MFA lockout directly from the User Management page.
* Tenant admins can now configure a data use preference ("Do not use my de-identified data to improve AI capabilities") in Domain Settings.
**Fixes**
* Fixed an intermittent error that could occur during single sign-on after domain selection or multi-factor authentication — sign-in now completes reliably.
* Fixed a bug where an "invalid redirect URL" error was incorrectly shown after clicking an account activation or password reset link from email.
* Fixed a bug where the success confirmation was not displayed after successfully resetting a password.
* Fixed a bug that caused IAM logout to fail, leaving the user session active.
* Fixed a bug where the MFA verification page was incorrectly shown again after a user had already successfully verified.
* Fixed workgroup admin invitations not updating from "pending" to accepted once the invitee accepts.
* Fixed app tile visibility: Illumina Connected Multiomics now appears correctly for Free Trial users in the London region, and an invalid app tile no longer appears.
## 2026 May 27
**Login and Sign Up**
* The "Remember email" and "last-accessed domain" preferences on the login page now persist correctly across sessions.
**Domain & Workgroup Management**
* Domain administrators can now invite any user by email without needing to first update the domain's allowed-email list, simplifying the invitation process.
**Software Registration**
* Duplicate order lines caused by certain order update scenarios in the Software Registration portal are now resolved.
**Usage and Billing**
* IMF1 instrument data is now included in Usage and Billing analytics, expanding the data available in usage reports.
**Fixes**
* Disabled workgroup roles no longer appear in the Workgroup Invitation role dropdown — only actively enabled roles are shown.
* Domain administrators can no longer downgrade their own domain role to a regular user.
* Domain Admin user search from the User Management page now returns results correctly.
* The pending invite status tooltips on the Users page no longer display incorrect values.
* The error message shown when a usage report is too large now correctly indicates that a custom date range can be selected to reduce the report size.
* Saving session settings with invalid values now shows a single, specific error message instead of two overlapping error toasts.
* The MFA skip-days label no longer shows the incorrect plural "days" when the value is set to 1.
## 2026 April 28
**Admin Console**
* The Admin Console has been redesigned with a refreshed interface and improved navigation for domain and workgroup administrators
## 2026 February 10
**Usage and Billing**
* Improved usage reports now include domain/workgroup identifiers, billing dates, and billable account IDs for clearer invoice reconciliation.
* Monthly iCredit invoicing information is now reflected in the usage explorer to support automated billing processes.
**Fixes**
* Improved performance for user authentication and related APIs.
* Addressed issues with SAML SSO file uploads, custom role creation, and incorrect error logging.
* Various UI updates including footer links, validation messages, and order item handling.
## 2025 December 10
**Login and Sign Up**
* Password reset flow simplified: users are redirected to the login page after resetting their password.
* Invisible reCAPTCHA added for sign-up and password reset for better security.
* Fixed login reliability issues, including handling special characters and improving error messages.
* Full UTF-8 support for names and sign-up field
**Software Registration Enhancements**
* Clearer error messages when exceeding registrant limits.
**Performance & Stability**
* Faster application performance through optimized caching.
* Fixed intermittent navigation and order display issues.
## 2025 October 29
**Login and Sign Up**
* Fixed login issues for users with UTF8 characters in passwords. Affected accounts will be automatically repaired upon next login.
**Software Registration**
* Order setup modal now includes a loading indicator during setup operations, improving user experience and clarity.
* Restored visibility of order item assignees during multi-item registration workflows.
* Improved order registration confirmation message to clearly guide users to check their email for next steps.
## 2025 October 7
**Login and Sign Up**
* Unified Login now features a cleaner interface with automatic SSO redirection and improved keyboard navigation.
* Enhanced password flexibility and support for email addresses containing "+".
**Software Registration**
* Multi-order registration is now supported, allowing users to configure and register several orders at once.
* Welcome emails are dispatched immediately after registration, speeding up onboarding.
* UI improvements include better navigation, clearer messages, and visibility of MFA options when enabled.
**Usage and Billing**
* Fixed a bug where downloading usage reports over 3 months caused indefinite loading. Users are now informed of the 3-month limit.
## 2025 August 12
**New Features and Enhancements**
* **Customer Number added to User Registration**\
A new optional "Customer Number" field has been added to the signup form and is now synced with MyIllumina.
**Fixed Issues**
* The email field in the signup form now supports addresses containing the '+' symbol, ensuring compatibility with more email formats.
## 2025 June 18
**New Features and Enhancements**
* **Connected Navigation Experience**\
We’ve introduced a unified navigation experience across the platform. The new connected home header and local navigation menus are now available, making it easier to move between key sections based on your access.
* **SSO and Email Extension Configuration**\
Domain administrators can now configure Single Sign-On (SSO) behavior more precisely. This includes the ability to claim corporate domains, enforce SSO login based on email domains, and manage an exclusion list for users who can still log in with a password.
* **Improved Order Registration Experience**\
Multiple updates have been made to the software registration page (now called "Orders"), including clearer button labels, improved tooltips, and more intuitive text descriptions to guide users through the setup process.
* **Streamlined Order Assignment**\
Assigning users to orders is now more efficient. We’ve removed unnecessary email notifications and simplified the assignment flow to reduce clutter and confusion.
* **Visual and Text Updates**\
We’ve made several UI improvements including updated banner messages, clearer error messages, and more accessible layouts.
**Fixed Issues**
* **Login and Authentication**
* Resolved problems with expired or inactive accounts.
* Addressed bugs affecting SSO login.
* Added support for `+` character in usernames.
* Fixed case sensitivity issues in email addresses during registration.
* **User Interface Fixes**
* Resolved a range of visual bugs and inconsistencies to reduce confusion and improve clarity.
* Fixed icon colors, toast messages, and layout glitches introduced in recent updates.
* **Notification Improvements**
* Reduced unnecessary email alerts.
* Ensured consistent and user-friendly messaging across different user actions.
## 2025 May 28
**New Features and Enhancements**
* [Usage Explorer](/account-management/usage-explorer)
* You can now select "DRAGEN GB License" as the Usage Type. When this option is selected, the "Measure By" dropdown allows you to view usage by either cost (iCredits) or quantity (gigabases).
**Fixed Issues**
* [Usage Explorer](/account-management/usage-explorer)
* Fixed an issue where the iCredit balance was not displayed in the Usage Explorer for inactive subscriptions. The balance will now always be shown, regardless of subscription status.
## 2025 May 20
**New Features and Enhancements**
* [Usage Explorer](/account-management/usage-explorer)
* Defaulted the cost unit to iCredits when no usage data is present.
**Fixed Issues**
* [Usage Explorer](/account-management/usage-explorer)
* Fixed an issue where the usage context switcher was occasionally not displayed.
* [Platform Home - Login](/account-management/platform-home)
* Fixed an issue where the Product Dashboard was not displayed after logging in using the new login experience.
* Fixed an issue that prevented users from logging in to Illumina cloud software from certain instruments.
## 2025 April 28
**New Features and Enhancements**
* [Usage Explorer](/account-management/usage-explorer)
* The Usage tab currently available in Admin Console was deprecated and replaced by the new [Usage Explorer](/account-management/usage-explorer).
* You can now access the Usage Explorer by clicking "Usage Explorer" in the [Platform Home dropdown menu](/account-management/platform-home#profile-dropdown-options).
* [Admin Console](/account-management/admin-console)
* Removed the low/negative iCredit balance banners in favor of the new "[Usage Explorer](/account-management/usage-explorer)" view
**Fixed Issues**
* [Admin Console](/account-management/admin-console)
* Current Domain Owner can no longer remove themself from Domain Administrators
* Updates to the Admin Console labels, errors, and tool tips
* [Software Setup](/getting-started/rg-registration)
* Fixed issue preventing registration of BaseSpace Professional subscriptions when users were logged with a user other than their public domain user.
## 2025 April 2
**New Features and Enhancements**
* [Software Setup](/getting-started/rg-registration)
* Domain admins can now assign and unassign users to subscriptions on the [Platform Home Subscriptions page](/account-management/platform-home#subscriptions). This is useful for products that require specific users to be assigned to the subscription in order for someone to access the associated application.
* Illumina registration emails now include order codes that users can share. These codes allow any user to self-assign to all pending order items in the Illumina Software Registration Portal.
* The Illumina Software Registration Portal link is now accessible from the Product Dashboard top-right dropdown within any domain.
* The number of users that can be assigned to pending order items in the Illumina Software Registration Portal has increased from 3 to 20.
* You can no longer change domain and workgroup owners in the Software Registration Portal. This action is now available from Admin Console and Platform API.
* Software subscriptions for the same product can now be registered to domains with overlapping start and end dates.
* A single registration email which includes an order code will now be sent to the users that are automatically assigned to that order (such as the purchaser).
* [Platform Home](/account-management/platform-home)
* Added pagination for [View Activity Log](/account-management/platform-home#view-activity-log) page.
* [Admin Console](/account-management/admin-console)
* You can no longer change the domain owner (i.e. the primary domain admin) from the Illumina Software Registration Portal. You must go to the Admin Console to update the domain owner. This is now consistent with how workgroup owners are managed.
* Workgroup admins can now change workgroup owners in the Admin Console and updates are reflected in the Software Registration Portal.
* Workgroup owners for BaseSpace Sequence Hub Professional workgroups can now be changed via the Admin Console, consistent with other domain workgroups.
* You can no longer set the account unlock time from the Admin Console. It is now fixed at 30 minutes and can only be modified by contacting Illumina Support.
* You can no longer add duplicate emails/email extensions to the "allowed emails" for a domain in Admin Console.
* Added search box on Admin Console Workgroup Users and Admin pages
* Provided more clarity in the error message displayed when an issue occurs while inviting a user to a workgroup.
* Domain admins can now view all workgroups a domain user has access to.
* You can now see a banner at the top of the Admin Console Usage tab to indicate page retirement on April 30.
* Made updates to Admin Console UI and loading messages.
**Fixed Issues**
* [Software Setup](/getting-started/rg-registration)
* Fixed an edge-case where subscriptions involving apps containing a dot "." would not be processed by Subscription Service properly
* [Platform Home - Login](/account-management/platform-home)
* Allow special characters in passwords for v1/v2 login
* Allow special characters (e.g. "+" and "%") in Admin Console search patterns when included in usernames
* Fixed an issue that caused users to be logged out immediately after login
* [Admin Console](/account-management/admin-console)
* Fixed a rare case where certain users could not be set as workgroup owner/workgroup admin due to email restrictions
* Improved workgroup and domain search functionality
* Fixed an issue that allowed deletion of system roles without a warning message
* Fixed an issue that allowed user to update the workgroupID for a workgroup they are not a member of
* Fixed an issue where domain users without allowed email address are unable to be set as a workgroup owner
* [Usage Explorer](/account-management/usage-explorer)
* Fixed Usage Explorer date range selector when using a non-US region in browser settings
# Documentation Revision History
## 2025 September 23
* Added [Multiomics Products](/multiomics/multiomics-products) page showcasing assays and visualization tools within the Multiomics suite.
## 2025 April 10
* Added [Platform Home](/account-management/platform-home) section with information about Managing API Keys, Subscriptions and more.
* Updated [Software Setup](/getting-started/rg-registration) docs to reflect changes in software registration process.
## 2025 February 17
* Added [Usage Explorer](/account-management/usage-explorer) section with information on how to navigate the new tool and track usage across products.
## 2025 January 6
* Updated [Sample Sheet](/run-set-up/overview) documentation.
* You can now view sample sheet parameters and definitions by selecting your instrument under the ["Instrument Settings"](/run-set-up/overview/instrument-settings) section, choosing the desired pipeline from the right navigation panel, and selecting the appropriate version.
* Added a [BCL Convert Interactive Sample Sheet](/run-set-up/overview/sample-sheet-structure/bcl-convert-interactive-sample-sheet), allowing users to click on different parameters to view detailed explanations of each.
* Included an [Index Orientation Guide](/run-set-up/overview/index-orientation-guide) and [i5 Index Orientation Table](/run-set-up/overview/index-orientation-guide/i5-index-orientation-table) to clarify which i5 sequence orientation to use for different platforms, based on the analysis software.
* Added information about various [Run Workflows](/run-set-up/run-workflows) and their compatibility with different instrument platforms.
* A new "[Resources](/run-set-up/overview/resources)" section provides additional information on [BCL Convert Parameter Usage](/run-set-up/overview/resources/bcl-convert-parameter-usage), [Illumina Knowledge Help](/run-set-up/overview/resources/illumina-knowledge-help), and a comprehensive [FAQ](/getting-started/rg-faq).
* Updated [Software Setup](/getting-started/rg-registration) documentation
* Added information on the [Admin Console](/account-management/admin-console)/IAM Console.
## 2024 December 11
* Updated [Sequencer Auto-Launch Analyses Compatibility](/analysis/sequencer-reference) table
## 2024 October 25
* Updated [Sequencer Auto-Launch Analyses Compatibility](/analysis/sequencer-reference) table
* Added [Secondary Analysis Troubleshooting](/analysis/analysis_autolaunch#secondary-analysis-troubleshooting) information for analyses not showing up in ICA
## 2024 September 4
* Updated [Sequencer Auto-Launch Analyses Compatibility](/analysis/sequencer-reference) table
## 2024 August 2
* Added links to [Custom Design Products](/custom-design/lab-management-products)
* Updated user documentation links
* Updated [Cloud Analysis Auto-Launch](/analysis/analysis_autolaunch) page to include instructions for viewing sequencer run data and analysis in BaseSpace
* Made changes to [Cloud Analysis Auto-Launch](/analysis/analysis_autolaunch) page to include updated information for requeuing an analysis in BaseSpace
* Updated [Sequencer Auto-Launch Analyses Compatibility](/analysis/sequencer-reference) table
* Added [Document Revision History](/reference/document-revision-history) page in Reference section
## 2024 June 25
* Initial release
* Added [Software Registration instructions](/getting-started/rg-registration) and [FAQ](/getting-started/rg-faq)
* Added links to all documentation sites in the Illumina Connected Software suite
* Added [Sample Sheet v2](/run-set-up/overview) instructions
* Added [Run Set Up instructions](/run-set-up/miseq-run-setup) for MiSeq
* Added comprehensive guide for performing [Cloud Analysis Auto-launch](/analysis/analysis_autolaunch)
* Created [Sequencer Auto-launch Analyses Compatibility](/analysis/sequencer-reference) table with guidance on sequencer compatibility with different versions of DRAGEN secondary analysis pipelines and applications with auto-launch capabilities
* Added [cross-product tutorials](broken://spaces/6HNTm8iYkD7XsLmbBKpL/pages/8FjTYdIuuJi4N8yrfWou) with step-by-step instructions for performing downstream analyses and interpretation in the Cloud
# Welcome to DesignStudio Array
DesignStudio Microarray Assay Designer is a web-based software tool that allows customers to bring in their design files and perform the design process for Illumina Microarrays using web-based interface. The software will perform target level and design level validations, score each individual target for its designability and produce a final score/error file based on the outcome. DesignStudio Microarray also allows users to view their designs and design summaries.
#### POWERFUL CUSTOM INFINIUM ARRAYS
Supports successful probe design for single-nucleotide polymorphisms (SNPs), insertions/deletions (indels), and methylation designs targeting CpG and CpH sites by providing predicted success and Infinium validation status.
#### SOPHISTICATED DESIGN TOOLS
DesignStudio is an online tool for creating custom and semi-custom Infinium BeadChips, including features such as:
* Login using MyIllumina account
* Supports creation of custom and semi-custom Infinium BeadChips in the following assay formats:
* EX-24
* EX-48
* HTS
* XT (Genotyping only)
* Allows design of semi-custom content based on popular catalog array backbones.
* Designs one to four species on a single array for XT Genotyping BeadChips.
* Designs BeadChips for human and agricultural species.
* Generates designs using:
* **Genotyping**
* rsIDs from dbSNP (human only).
* Genomic coordinates (human only).
* Gene names (human only).
* Existing Illumina IDs (ILMN IDS).
* Flanking sequences and alleles.
* Previous score file.
* **Methylation**
* Cg IDs from Illumina cg database.
* Coordinates for CpG/CpH targets.
* Gene names (human only).
* Region definitions.
* Alerts to potential issues with submitted design.
* View project status.
# Get Started
DesignStudio is integrated with the MyIllumina ordering system. You will need a MyIllumina account to access the design tool. To create an account, visit the [MyIllumina website](https://my.illumina.com/).
You can create custom panel designs for the following assays:
### Genotyping
* Infinium HTS
* Infinium XT (for select customers)
* Infinium EX-24
* Infinium EX-48
### Methylation
* Infinium HTS
* Infinium EX-24
* Infinium EX-48
You can also add custom content to commercially available Illumina catalog arrays.
## Before You Begin
Determine which of the following assay options to use:
### Genotyping
* Infinium HTS iSelect
* Supports 3,072 to 700,000 custom target with a minimum purchase order of 1,152 samples.
* Infinium XT iSelect
* Supports 500 to 50,000 custom targets with a minimum purchase order of 50,000 samples.
* Infinium EX-24 iSelect
* Supports 3,072 to 1,200,00 custom targets with a minimum purchase order of 1,152 samples.
* Infinium EX-48 iSelect
* Supports 3,072 to 600,000 custom targets with a minimum purchase order of 1,152 samples.
* Commercial+
* Supports supplemental custom content to commercially available Illumina catalog arrays with a minimum purchase order of 1,152 samples.
### Methylation
* Infinium HTS iSelect Methyl
* Supports 500 to 100,000 custom target with a minimum purchase order of 5000 samples.
* Infinium EX-24 iSelect Methyl
* Supports 500 to 100,000 custom targets with a minimum purchase order of 5000 samples.
* Infinium EX-48 iSelect Methyl
* Supports 500 to 100,000 custom targets with a minimum purchase order of 5000 samples.
* Commercial+
* Supports supplemental custom content to commercially available Illumina catalog arrays with a minimum purchase order of 5000 samples.
## Microarray Designer Workflow
Familiarize yourself with the workflow of the Microarray Designer:
1. **Create Input Files**
* Use templates from download templates to create score, sequence, gene, identity, coordinates and region files.
2. **Select Assay**
* Choose assay option in Microarray Assay Designer tool.
3. **Configure Design**
* Select species.
4. **Upload Targets**
* Upload input files to design tool.
5. **Review Design**
* Review design details and summary.
6. **Order Design**
* Finalize product name and complete order.
# Download Files
The following sections describe how to download files and manifest files and where to view design details.
## Download Files
1. From the Microarray Designer window, select **Download Files** from the toolbar.
2. Select **Download Files** to download one or more of the following files for analysis. The files are provided in CSV (\*.csv) format.
1. **Genotyping**
1. Score
2. Excluded Content
3. Error
4. Input Target
2. **Methylation**
1. Design File
2. Input Target
3. Excluded Content
4. ErrorFile
3. After downloading the files, you can view them in Microsoft Excel or a spreadsheet program.
## Download Manifest Files
To download the manifest files for a custom order:
1. From the Microarray Designer window, select **Download Files**.
2. Select **Looking for your manifest files**.
* The MyIllumina window opens.
3. Select **Get Product Files**.
4. To locate the manifest file associated with the order, enter the part number or purchase order number, and then select **Product Files Search**.
5. Download the resulting manifest files.
## Download File Toolbar
The Download Files toolbar provides the details of all the designs.
| Column Heading | Description |
| -------------- | -------------------------------- |
| Design ID | The unique design ID number. |
| Design Name | The user-defined design name. |
| Array type | The array type. |
| Bead count | The bead count for the species. |
| Status | The design status. |
| Species | The number of species. |
| Added | The date the design was created. |
# Assay Design
Use the following steps to create an assay design. Refer to the following Design Considerations for information on design options.
### Design Considerations **(Genotyping)**
* **Total bead count** — Always consider total bead count when creating a design. Infinium I designs require two probes per SNP, which increases the bead count. Replication multiplies the number of beads needed for each probe by two or three depending on the Replication\_Count. Refer to [Input Target Files](/design-studio-array/product-guides/input-target-files) for more information on replication settings.
* **Multiallelic targets** — Check the **convert multi-allelic** checkbox to convert multi-allelic loci to bi-allelic loci. DesignStudio supports design and analysis of bi-allelic designs only. If the designer is not able to determine clearly which minor allele to pick up based on MAF values, then that target is added to the identity error file and is excluded from the final design.
* **Bi-allelic conversion —** During bi-allelic conversion, the system evaluates the Minor Allele Frequency (MAF) for each minor allele. If one minor allele has a MAF value **below** the defined threshold (currently set to 1%) and the other has a MAF value **above** the threshold, the allele with the MAF above the threshold will be designated as the minor allele for the purpose of bi-allelic conversion.
### Design Considerations **(Methylation)**
* **MostImportant Flag —** User can mark any target MostImportant in Identity File in order to have that target replicated three times.
* **Control Targets —** When a user marks checkbox to "Include SNP Probes for sample Identification", it adds the SNP control targets into the Design file. These targets are strictly for control purposes. Please refer to more [details here on this topic.](https://knowledge.illumina.com/microarray/general/microarray-general-reference_material-list/000003719)
[Design the Assay](/design-studio-array/product-guides/assay-design/design-assay)\
[Review Design Summary](/design-studio-array/product-guides/assay-design/review-design)\
[Add Custom Content to Commercial Arrays](/design-studio-array/product-guides/assay-design/add-custom)
# Design the Assay
1. From the Microarray Designer toolbar, select **Start Design**.
2. \[Optional] To view a detailed comparison between the iSelect and XT iSelect assays, select **Compare Assays**.
* This option is available if you have access to XT iSelect.
3. Select one of the following assay options:
* **EX-24 iSelect / EX-24 iSelect +**
* **EX-48 iSelect / EX-48 iSelect +**
* **HTS iSelect / HTS iSelect+**
* **XT iSelect / XT iSelect+ (Genotyping ONLY)**
* **Commercial+**\
Each assay option includes information on the minimum and maximum limits.
4. Select one of the following design options:
* **Custom** — Create a fully custom design.
* **Add on to Existing Design** — Add content to an existing custom design.
5. Enter a name for the design.
* Invalid characters include: plus sign (+), ampersand (&), backslash (\\), slash (/), colon (:).
6. \[Optional] Enter a description for the design.
7. Select **Next**.
* The Configure Design screen opens.
8. Select a species from the **Select your species** drop-down list, and then select **Add Species**.
* You can select up to four species for XT iSelect.
9. Select **Next**.
* The Upload Targets screen opens. Refer to [Input Target Files](/design-studio-array/product-guides/input-target-files) for information on input target files, including templates and settings.
10. From the **Select File Type** drop-down, select the file type you want to upload.
* \[Optional] Select the **Lowercase Weighting** sequence file type option to weight the final score of lowercase nucleotides to reflect suboptimal probe placement for lowercase regions.
* \[Optional] Select **Update Annotations** to display updated annotations (if available) for design targets in the resulting score file. This option only applies to existing design or score file types.
11. Select **Submit for Design**. When the design completes without errors, the software updates the session status and sends you an email notification. If the design fails, an error message appears with details of the issue. Refer to [Output Files](/design-studio-array/product-guides/output-files) for more information on errors.
# Review Design Summary
When the design completes, DesignStudio shows the design summary in the Review and Order Design screen.
* To download the created files for troubleshooting, select **Download Files**.
* To upload new target files for the design tool to validate, select **Upload New Targets**.\
\
The design summary includes the following items:
* Number of assays submitted.
* Number of assays designed.
* Number of assays excluded.
* Options selected.
* Content breakdown by species (For Genotyping designs on XT platform).
* Normalization bins and total bead count for selected species. (Genotyping ONLY).\
\
When you are ready to order your products, contact Illumina Customer Care.
# Add Custom Content to Commercial Arrays
1. From the Microarray Designer toolbar, select **Start Design**.
2. Select **Commercial+**.
3. Select **Select Base Content**.
* The Select Commercial+ Base Content dialog opens.
4. \[Optional] In the Search field, enter the design name, ID, or species.
5. Select the content in the order that you want to use as base content for your design, and then select **Use as base content**.
* The selected content appears in the Commercial Base Content field on the Select Assay screen.
# Input Target Files
Input target files contain information for the requested targets. To download templates of input target file formats, select **Download File Templates** from the Upload Targets screen. Use a text editor or spreadsheet program to enter custom targets into the template file (\*.csv).
The types of files that can be uploaded as input target files include:
### Genotyping
* Gene (Human only)
* Region (Human only)
* Identity (Human only)
* Sequence
* Existing design
* Score
### Methylation
* Gene (Human only)
* Region
* Identity
* Co-ordinates
Refer to the following sections for information on the contents of the input target files:
## Gene (Genotyping/Human Only)
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Gene\_Name | Gene name. |
| Bases\_Upstream | Search database for targets with coordinates greater than the gene start position. For example, entering 1000 bases upstream to include and search dbSNP for any rsIDs within 1000 base pairs above the gene coordinates. |
| Bases\_Downstream | Search database for targets with coordinates less than the gene start position. For example, entering 1000 bases downstream to include and search dbSNP for any rsIDs within 1000 base pairs below the gene coordinates. |
## Region (Genotyping/Human Only)
| Field | Description |
| ----------------- | ---------------------------------------------------------------------------- |
| Chromosome | Chromosome name. |
| Start\_Coordinate | Search databases for targets with coordinates greater than start coordinate. |
| End\_Coordinate | Search database for targets with coordinate less than end coordinate. |
## Identity (Genotyping/Human Only)
| Field | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Locus Name | Locus name. Enter rsID for the locus. Valid characters: alphanumeric, numbers, hyphens, and underscores. Example: rs1234567. |
| Replication\_Count | Replicate the design targets in output files. Select no repeat (1), duplicate (2), or triplicate (3). Valid characters: 1, 2, 3. |
## Sequence (Genotyping)
| Column | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Locus\_Name | Locus name. Valid characters: alphanumeric, numbers, hyphens, and underscores. |
| Target\_Type | Target type. Enter SNP or INDEL. |
| Sequence | Loci sequence. Specified sequence must have greater than 50 base pairs on both sides of the variant. |
| Chromosome | Locus chromosome name. |
| Coordinate | Genomic position start. |
| Genome\_Build\_Version | Genome build version. Example: 38. |
| Source | Reported source of the sequence and annotation data. Example: dbSNP. |
| Source\_Version | Source version number. |
| Sequence\_Orientation | Direction that was selected for primer DNA synthesis. Can be forward, reverse or unknown. Selecting unknown makes it impossible to run a strand report later. |
| Plus\_Minus | DNA strand orientation. |
| Species | Species name. Example: human. |
| Force\_Infinium\_I | Force the design using Infinium I chemistry. Enter TRUE to force Infinium II SNPs to be designed as Infinium I. Enter FALSE for content to be designed as recommended. |
| Replication\_Count | Replicate the design targets in output files. Select no repeat (1), duplicate (2), or triplicate (3). Valid characters include: 1, 2, 3. |
## Existing Design (Genotyping)
| Field | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ilmn\_ID | Illumina ID from existing designs. |
| Species | Species name. Example: human. |
| Force\_Infinium\_I | Force the design using Infinium I chemistry. Enter TRUE to force Infinium II SNPs to be designed as Infinium I. Enter FALSE for content to be designed as recommended. |
## Score (Genotyping)
The score file is produced as an output file by DesignStudio and contains targets from the score file data section of the existing design that produced it. The output score file can be used as input after the headers have been removed.
## Gene (Methylation/Human Only)
| Field | Description |
| ---------- | ----------- |
| Gene\_Name | Gene name. |
## Region (Methylation)
| Field | Description |
| ----------------- | ---------------------------------------------------------------------------- |
| Chromosome | Chromosome name. |
| Start\_Coordinate | Search databases for targets with coordinates greater than start coordinate. |
| End\_Coordinate | Search database for targets with coordinate less than end coordinate. |
## Identity (Methylation)
| Field | Description |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| Locus\_name | Locus name. Valid characters: alphanumeric, numbers, hyphens, and underscores. |
| MostImportant | When the `mostImportant` parameter is set to **TRUE**, the system will replicate the target three times. |
## Coordinate (Methylation)
| Field | Description |
| --------------- | ------------------------------------------------------------------------------ |
| Chromosome | Chromosome name. |
| Locus\_Name | Locus name. Valid characters: alphanumeric, numbers, hyphens, and underscores. |
| Position\_Start | Value of coordinate that is location of the target. |
| Type | Type of the target(CpG/CpH). |
# Output Files
The DesignStudio Microarray Assay Designer outputs files during the design process. Design error information is found in multiple files. Review all the output files for complete information.
The following files are produced by DesignStudio:
* Excluded content
* Identity error
* Error
* Score
Refer to the following sections for information on the contents of the output files regarding errors:
* [Target Files Error Code](/design-studio-array/product-guides/output-files/target-files-error-code)
* [Target Files Common Errors](/design-studio-array/product-guides/output-files/target-files-common-errors)
# Target Files Error Code
***
#### Genotyping
| Error Code | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 101 | Flanking sequence is too short. |
| 102 |
Polymorphism is not appropriate for the Illumina platform.
Possible causes can include:
Tri- or quad-alleic SNP.
Contains characters other than A, G, C, T.
|
| 105 |
Polymorphism is on the mitochondrial genome. Illumina does not recommend using mitochondrial polymorphisms for oligo pools.
Possible solution:
Remove any polymorphism on the mitochondrial DNA from your target file and resubmit your design.
|
| 106 | Degenerate nucleotides are included in the assay design region. For example, the W, R, S, N assay, or others. |
| 107 | Cannot locate the SNP sequence. |
| 108 | The final score is under assay limit. |
| 109 | The indels do not support the Infinium I assay type. |
| 110 |
The locus name is duplicated in the base commercial content.
Possible solution:
Rename the locus name that is identified as duplicate in the excluded content file.
|
| 111 |
The normalization bin count for the following species does not meet the minimum limit (100) required for ordering: Homo sapiens.
Scenario:
Any design that has normalization bin A/B that is > 0 and < 100, or a normalization bin C that is > 0 and < 1000.
Possible solution:
Remove or add \[G/C] and \[A/T] SNPs to within the limit.
Use the score.csv file to identify Bin A/B content and fill in a new Sequence Input file.
Replicate these designs, with unique names, to > 99.
Use the score.csv file to identify Bin C content. Redesign all Bin C using sequence input file, forcing Infinium I chemistry (Force\_Infinium\_to True), using unique names. Use the resulting score.csv file to fill Bin A/B to > 99. Combine content from multiple score files using the Existing Input file.
|
| 112 |
The total bead count for this add-on does not meet the minimum limit {{MinBeadCount}} required for ordering.
Scenario:
An Infinium iSelect design doesn't meet the required bead count limit for ordering.
An Infinium iSelect+ design does not meet the minimum bead count in the add-on content.
Possible solution:
Add more content or replicate the existing content using unique names.
|
| 113 |
The total bead count exceeds the maximum limit {{MaxBeadCount}} and cannot be ordered.
Scenario:
A design exceeds the max bead count for ordering.
Possible solution:
Trim lower value content to below the limit.
Alternatively, contact Sales for additional options.
|
| 114 |
The following species must occupy at least 20% of the total content for this design to be orderable: Hordeum vulgare.
Scenario:
An Infinium XT iSelect design has a spewcies that does not occupy at least 20% of the total design.
Possible solution:
Add more content for the specified species or replicate the existing content using unique names.
Remove content from higher-represented species.
|
| 115 |
The number of designed targets does not meet the minimum limit {MinimumTargetLimit}} required for ordering.
Scenario:
An Infinium design does not meet the minimum target count for ordering.
An Infinium XT iSelect+ design does not have the minimum target count in the add-on content.
Possible solution:
Add more content or replicate the existing content using unique names.
|
| 116 |
The number of designed targets does not meet the maximum limit {MaxTargetDesignLimit}} required for ordering. Refer to the data sheet for the base content array and for the allowable add-on content.
Scenario:
An Infinium design exceeds the maximum targets allowed for ordering.
An Infinium XT iSelect+ design's target count exceeds the maximum capacity.
Possible solution:
Trim lower value content to below the limit.
Alternatively, contact your Illumina sales representative for additional options.
|
| 117 |
The number of chromosomes exceeds the maximum allowed unique chromosomes per design. For example, 255.
Scenario:
Any design exceeding 255 unique chromosomes will not proceed.
Possible solution:
Change chromosome fields to 0 until below the limit. Keep the look-up file as a reference during analysis.
|
| 118 |
Representation of sex chromosome loci {sexrepresentation}% for normalization bin A {binA total count} exceeds limit of {RepresentationLimit}%.
Scenario:
Any design with sex representation for Normalization Bins exceeding 20% of the total count for the bin will not proceed.
Possible solution:
Add non-sex chromosone content to Bin until below the limit. Or, remove sex chromosome content from Bin until below the limit.
|
| 301 | Polymorphism in duplicated region. |
| 302 | Melting temperature is outside assay limits. |
| 304 | There are SNPs in the probe region. Refer to the Underlying\_SNP column for details. |
| 311 | SNP is not supported for Infinium I assay type. |
| 340 | Another polymorphism on the list is equal to or fewer than 60 nucleotides away. |
| 360 |
Low design score:
Possible solution:
Remove the targets with a low design score and resubmit the targets for design.
|
| 399 | Review the Score File or Input File used to create the design for inaccuracies. |
| 601 | The genome has multiple target sequences. |
| 602 | Probe sequence is duplicated in the base commercial content. |
| 603 |
Probe sequence is duplicated in the custom content.
Possible solution:
Remove the probes with duplicated sequence and resubmit the probes for design.
|
| 604 |
The normalization bin count does not meet the recommended limit (200) for optimal performance if the species is a polyploid organism.
Secnario:
Any polyploid design that has a normalization bin that falls between 100 and 200.
Possible solution:
Remove or add \[G/C] and \[A/T] SNPs to be within the limit.
Use the score.csv file to identify Bin A/B content and fill in a new Sequence Input file.
Replicate these designs, with unique names, to > 99.
Use the score.csv file to identify Bin C content. Redesign all Bin C using sequence input file, forcing Infinium I chemistry (Force\_Infinium\_I to True), using unique names. Use the resulting score.csv file to fill Bin A/B to > 99. Combine content from multiple score files using the Existing Input file.
Polymorphism is on the mitochondrial genome. Illumina does not recommend using mitochondrial polymorphisms for oligo pools.
Possible solution:
Remove any polymorphism on the mitochondrial DNA from your target file and resubmit your design.
|
| 107 | Target Not found. |
| 108 | The final score is under assay limit. |
| 115 |
The number of designed targets does not meet the minimum limit {MinimumTargetLimit}} required for ordering.
Scenario:
An Infinium design does not meet the minimum target count for ordering.
Possible solution:
Add more content or replicate the existing content using unique names.
|
| 116 |
The number of designed targets does not meet the maximum limit {MaxTargetDesignLimit}} required for ordering. Refer to the data sheet for the base content array and for the allowable add-on content.
Scenario:
An Infinium design exceeds the maximum targets allowed for ordering.
Possible solution:
Trim lower value content to below the limit.
Alternatively, contact your Illumina sales representative for additional options.
|
| 117 |
The number of chromosomes exceeds the maximum allowed unique chromosomes per design. For example, 255.
Scenario:
Any design exceeding 255 unique chromosomes will not proceed.
Possible solution:
Change chromosome fields to 0 until below the limit. Keep the look-up file as a reference during analysis.
|
| 301 | Polymorphism in duplicated region. This means that a multi-mapper is found for this target. Hence, this target has been excluded. |
| 399 | Review the Design File or Input File used to create the design for inaccuracies. |
# Target Files Common Errors
***
**Genotyping Common Errors**
| Target Files | Input Format/Source | Common Errors |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity List |
rsID numbers from dbSNP.
Known markers described in the dbSNP.
| Duplicate rsID numbers, RNA, or nonbiallelic SNPs. The sequence associated with the rsID may change over time based on the dbSNP Build. View the DesignStudio homepage for the dbSNP build currently referenced. |
| Sequence List |
Sequence includes:
SNPs: (...AGC\[G/T]AC...).
Indels: (...TGC\[-/AG]CCG...).
The file template must have an additional species column for XT iSelect.
Markers from private databases.
Requires a minimum of 50 bp sequence on either side of SNP.
|
Locus names that begin with rs or cg, or contain characters (%/='?@;\`,\_ or space).
Duplicate probe names.
SNP/Indel not annotated properly.
|
| Region List |
Chromosome, start and end coordinate.
List of chromosomal regions that are referenced from dbSNP.
|
Repetitive regions.
Markers with ambiguous or multiple loci.
|
| Gene List |
Gene Name RefSeq accession ID or HUGO ID.
Bases upstream and downstream.
Provides design of all markers with a gene along upstream and downstream regions.
| File includes 600 genes or more or upstream and downstream regions are 10,000 or more bases, which exceeds the 1 million SNPs limit per file. |
| Existing Design |
List of ILMN IDs from previous designs for iSelect, XT iSelect, or Illumina commercial assays.
Requires an additional species column for XT iSelect ILMN ID.
|
Duplicate probe names.
Species don't match between Illumina original design and input file.
|
| SNP Score File |
Microarray Designer generates the score file.
Before importing, remove the header section above the Locus\_Name.
Requires an additional species column for XT iSelect.
| Header section above locus name is not removed. |
**Methylation Common Errors**
| Target Files | Input Format/Source | Common Errors |
| ------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity |
Locus\_name
MostImportant
|
Locus\_Name must not be empty.
MostImportant must not be empty.
MostImportant must be a valid boolean.
|
| Coordinates |
Locus\_name
Chromosome
Position\_start
|
Chromosome must not be empty.
Position\_Start must not be empty.
Position\_Start must be a valid number.
Type (VariantType) must not be empty.
Type (VariantType) must be of value 'cg' or 'ch'.
|
| Gene |
Gene\_Name
|
Gene\_Name must not be empty.
|
| Region |
Start\_Coordinate
End\_Coordinate
Chromosome
|
Chromosome must not be empty.
End\_Coordinate must not be empty.
Start\_Coordinate must be a valid number.
End\_Coordinate must be a valid number.
Start\_Coordinate must be less than or equal to End\_Coordinate.
Start\_Coordinate cannot be a negative number
End\_Coordinate cannot be a negative number
|
# View or Delete Designs
The View Designs screen contains existing designs and details about each design, including status. From the Microarray Designer toolbar, select **View Designs**. To delete designs, select **Delete**.
### Design Information:
| Column Heading | Description |
| -------------- | -------------------------------- |
| Design ID | The unique design ID number. |
| Design Name | The user-defined design name. |
| Array Type | The array type. |
| Beadcount | The bead count for the species. |
| Status | The design status. |
| Species | The number of species. |
| Added | The date the design was created. |
### Design Statuses:
| Status | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Created | The design request is created. |
| Created (with error) | There is an error in the design. |
| Designing | The design tool is processing the design. |
| Designed/Unorderable | The design has no errors but does not meet the criteria for ordering. Refer to [Review Design Summary](/design-studio-array/product-guides/assay-design/review-design). |
| Ready to Order | The design has no errors. You can start ordering Illumina products. |
| Product Name Finalized | You have entered a validated product name. |
| Ordered | Your order is completed. |
| Unknown Failure | There is an unknown error in your design. |
# Arrays finder
Match up to 50k variants or genomic loci to Illumina commercial base content and download overlap results.
* Array Finder enables customers to search a design target list against Illumina's commercial array database to determine which array best provides the content they need.
* Users can enter input in the UI or upload an input file.
* If users upload a file, they can download the input template.
* Users can also select a major genome build for the species. For example, Homo sapiens searches can target build 37 or 38. Select the target build up front.
* Searching 50k targets can take up to 30 seconds.
* When the search is complete, users land on a summary page. The summary shows overlapping targets between the user input and each commercial base. User can also get details like the target build that was used by clicking "Export details" button.
* Users can download either the search summary or detailed search results for each chip.
* If any targets are excluded from the search, they are listed in the `excludedContent` file.
* If users want to search for a locus that is not a known target, use a genomic location search.
# Additional Resources
## Technical Support
For support, questions, and feedback on DesignStudio Array, please contact Illumina Tech Support at .
## Additional Resources
| Resource | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Support Pages](https://support.illumina.com/array/array_software/designstudio-microarray.html) | The DesignStudio support pages provide additional resources. These resources include software, training, compatible products, and documentation. Always check support pages for the latest versions. |
| [Infinium Lab Setup and Best Practices](http://support-docs.illumina.com/ARR/InfLabSetup/Content/ARR/FrontPages/inf_lab_bp.htm) | The Infinium Lab support pages provide information on lab setup and maintenance of Infinium assays. |
| [Infinium Consumables](http://support-docs.illumina.com/ARR/Consumables/Content/ARR/FrontPages/inf_ce.htm) | The Infinium Consumables support pages provide information on the consumables and equipment use in Infinium assays. |
| [GenomeStudio](https://support.illumina.com/array/array_software/genomestudio.html) | The GenomeStudio support pages provide additional resources on manual analysis of multi-nucleotide variants (MNVs). |
| [CpG loci identification](https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/cpg-loci-identification-tech-note-m-gl-00921/cpg-loci-identification-tech-note-m-gl-00921.pdf) | The technical support document provides guidance on CpG loci identification, specifically detailing the 122-mer designation of CG numbers (CG#s). It serves as a reference for understanding how CG#s are defined and applied within the 122-mer context. |
# Frequently Asked Questions
**1. What is the expected lead time for my custom array order?**\
For new custom methylation array orders, the typical lead time is 14–16 weeks from order completion. For custom genotyping array lead times, please contact your local Illumina sales representative for details.
\
**2. How do I choose kit sizing in DesignStudio Array?**\
Kit sizing is finalized in collaboration with Illumina Customer Care during the order completion process.
\
**3. Can I reorder additional samples of an existing design through DesignStudio?**\
To reorder more samples of a previously completed design, please reach out to your local sales representative for assistance.
\
**4. Who should I contact for help with technical issues in DesignStudio Array?**\
For software-related issues or error messages in DesignStudio Array, please contact Illumina Technical Support at . For questions related to array design, your local sales representative is the best point of contact.
\
**5. Can I make changes to my design after the order is finalized?**\
Before manufacturing begins, you’ll review and approve your custom design via an intake form. Once manufacturing is initiated, design changes are no longer possible.
\
**6. Can I include both genotyping and methylation markers on the same beadchip?**\
DesignStudio Array does not currently support combining genotyping and methylation markers on a single beadchip. However, custom methylation arrays may support SNP designs on a case-by-case basis. Please contact your sales representative, who can connect you with the Concierge team to explore feasibility.
\
**7. Can I design for multiple species on a single array?**\
Multispecies design is available only on XT arrays, supporting up to four different species per array.
# Release Notes
The following versions of DesignStudio Array have been released:
* [DesignStudio Array v2.1.0 Release Notes](/design-studio-array/reference/release-notes/designstudio-array-v2.1.0-release-notes)
* [DesignStudio Array v2.2.0 Release Notes](/design-studio-array/reference/release-notes/designstudio-array-v2.2.0-release-notes)
* [DesignStudio Array v2.2.1 Release Notes](/design-studio-array/reference/release-notes/designstudio-array-v2.2.0-release-notes/designstudio-array-v2.2.1-release-notes)
* [DesignStudio Array v3.0 Release Notes](/design-studio-array/reference/release-notes/designstudio-array-v3.0-release-notes)
* [DesignStudio Array v3.0.1 Release Notes](/design-studio-array/reference/release-notes/designstudio-array-v3.0-release-notes/designstudio-array-v3.0.1-release-notes)
* [DesignStudio Array v3.1.0 Release Notes](/design-studio-array/reference/release-notes/designstudio-array-v3.1.0-release-notes)
# DesignStudio Array v2.1.0 Release Notes
#### Release date
February 20, 2024
#### Key Highlights
* Added replication support for assay design workflows.
* Improved error code reporting in output and troubleshooting flows.
# DesignStudio Array v2.2.0 Release Notes
#### Release date
May 2024
#### RELEASE V.2.2.0 HIGHLIGHTS
* Ability to design EX-24 and EX-48 iSelect BeadChips.
#### NEW FEATURES IN DETAIL
* Options within Select Assays to design EX-24 iSelect and EX-48 iSelect BeadChips.
* Updates to Compare Assays table to show new BeadChip types and specifications.
* Out-of-date rsIDs submitted are automatically updated to the revised merged rsID per dbSNP.
* Identity error file lists submitted rsID alongside revised merged rsID.
* Score file automatically includes revised merged rsID.
* rsIDs submitted with capital letters are automatically lowercased for consistent formatting.
* Designs that use the automated strategy to convert from multi-allelic to bi-allelic are more clearly indicated in Review and Order Design page and output files.
* Score file name updated from 'Failure\_Codes' to 'Warning\_Codes' to more accurately reflect the purpose.
#### KNOWN ISSUES
* Non-specific failures occur when:
* Loci names include two dashes ("--") in the input file.
* A M or MT chromosome designation is used for equine as species.
* Submitting sequence files with certain formatting errors. The workflow terminates without allowing access to the error file.
* When using an existing design file, a dropdown exists but the stand type cannot be changed.
* Rare, specific Infinium II indels designing as Infinium I with a 3' ambiguity error message.
# DesignStudio Array v2.2.1 Release Notes
#### Release date
August 2024
#### NEW FEATURES
* None
#### FIXED ISSUES
* Fixed issue impacting the addition of Commercial+ (semi-custom) EX BeadChips. Semi-custom EX BeadChips can now be created.
#### KNOWN ISSUES
* Non-specific failures occur when:
* Loci names include two dashes ("--") in the input file.
* A M or MT chromosome designation is used for equine as species.
* Submitting sequence files with certain formatting errors. The workflow terminates without allowing access to the error file.
* When using an existing design file, a dropdown exists but the stand type cannot be changed.
# DesignStudio Array v3.0 Release Notes
Version DSA 3.0 delivers the Methylation Release, introducing major enhancements to probe design workflows, expanded Illumina Connected Analytics (ICA) integration, improved performance, and numerous.
#### Release date
January 2026
#### Methylation Enhancements
* Dedicated **Methylation Designer** updates, including improved handling of excluded content, normalization bins, error reporting, and output file structures.
* Support for additional commercial panels and improved error handling in test runs.
* New controls and validation checks for probe design integrity.
#### Illumina Connected Analytics (ICA) Integration
* Direct ICA pipeline launch from DSA.
* Subscription and access improvements (dynamic subscription creation, handling delays, public domain access).
* File management and ICA analysis consumers fully integrated.
* Expanded endpoint coverage for design status, events, coordinates, and target retrieval.
#### User Experience & Interface
* Updated tooltips, toggles, and styling.
* Improved species selection and population handling.
* Enhanced download templates and output file formats.
* New options for orderability checks and commercial probe management.
#### Known Issues
* Validation error does not occur when submitting an empty input file
* Invalid characters in design names do not trigger an error
* Email templates still include some irrelevant error and warning codes
* Intermittent UI error may occur in Chrome
# DesignStudio Array v3.0.1 Release Notes
#### Release date
January 2026
#### Key Highlights
* Moved file staging from FTP to SFTP.
# DesignStudio Array v3.1.0 Release Notes
#### Release date
March 2026
#### Key Highlights
* New **Array Finder** tool to match up to **50k variants (rsID/cgID) or genomic loci** against Illumina commercial base content.
* Supports **target entry through the UI or file upload** using a template.
* Allows selection of the **species genome build** (for example, *Homo sapiens* build 37 or 38) before running the search.
* Displays a **summary of overlapping targets across commercial arrays** with downloadable summary and detailed results files.
* Outputs an **excludedContent** file listing targets excluded from the search.
#### Resolved Issues
* Improved bin assignment for Infinium I indels by categorizing insertion and deletion variants. This helps organize genetic data for accurate identification and interpretation of variants.
#### Known Issues
* Validation error does not occur when submitting an empty input file
* Invalid characters in design names do not trigger an error
* Email templates still include some irrelevant error and warning codes
* Intermittent UI error may occur in Chrome
# Revision History
The version history for DesignStudio Array product documentation:
| Version | Date | Description of Change |
| ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| 1.0.0 | 2016 | Initial release. |
| 1.1.2 | Jul 25, 2019 | Node-sass issue fix and header security updates. |
| 1.2.0 | May 6, 2022 | Manifest Checker. |
| 2.0.0 | Apr 4, 2023 | dbSNP updates, Ex-24/48 enablement in background. |
| 2.0.1 | May 26, 2023 | dbSNP UI Upates. |
| 2.0.2 | Jan 3, 2024 | Hotfix to incorporate platform security protocol changes and update UI version numbers. |
| 2.1.0 | Feb 20, 2024 | Replication feature, error-code improvements. |
| 2.2.0 | May 27, 2024 | Regex updates, multi-allelic UI enhancements, EX-24/48 support, DSS validation integration, and UI version updates. |
| 2.2.1 | Aug 21, 2024 | Enable add-on for Excalibur, Summary page improvements. |
| 2.2.2 | Sep 23, 2024 | Make Ex-24/48 visible |
| 3.0.0 | December 3, 2025 | Methylation enablement. |
| 3.1.0 | March 2026 | Arrays Finder tool (commercial base content overlap search). |
# Announcements
## What's New
**Date:** August 2026
***
The latest releases introduce new updates to sequencing instrument integration support, expanded sequencing capabilities, and workflow usability improvements. It also resolves several defects that affected metrics reporting and workflow automation.
***
## Clarity LIMS v6.3.5
Clarity LIMS v6.3.5 delivers product updates, fixes and security improvements
* Updated PostgreSQL to version 15.18 to maintain platform stability and security
* Upgraded the LabLink Angular framework to a modern version (v21.2) to improve performance and maintainability
* Improved LabLink page display and usability for custom dropdown fields with large option sets causing the option list to overflow the screen and obscure selectable options.
* Improved project handling in Lablink to prevent temporary projects from appearing in Advanced Search results when project creation is unsuccessful.
* Addressed general security vulnerabilities across the platform
* Improved support for downloading files and folders from remote HTTP and HTTPS storage locations in Clarity LIMS v6.3.2 and later.
***
## NovaSeq X Series
### Unified Cloud and On-Premises Workflow
The NovaSeq X Series workflows for Cloud-hosted and On-Premises deployments have been **consolidated into a single unified workflow**. This simplifies configuration management and ensures consistent behavior across deployment types.
***
### Pool of Pools Support
Clarity LIMS now supports **pool of pools** workflows for NovaSeq X Series runs. Customers who perform pooling at the library preparation stage (prior to the bulk pooling step) can now manage and route those pre-pooled samples directly within Clarity LIMS without manual workarounds.
A new **Skip Pooling** option is available in the Assign ACT step to route samples that have already been pooled during library prep directly to the Dilute and Denature step.
***
### Sample Project Support
Customers can now assign a **Sample Project** value to individual samples within Clarity LIMS. When Sample Project is specified, it is included in the generated sample sheet to enable BCL Convert to separate FASTQ output files into project-specific subdirectories.
***
### Per-Lane Sequencing Metrics
Clarity LIMS now parses and displays **per-lane sequencing run metrics** for NovaSeq X Series instruments upon run completion. Previously, only per-run (aggregate) metrics were available.
***
### No Analysis mode
Clarity LIMS supports creating a planned sequencing run with no analysis. The Clarity workflow will only track sequencing run status and primary metrics and analysis step is skipped.
***
### 1.5B Flowcell Supports 600-Cycle Kit
The NovaSeq X Series 1.5B flowcell now supports the **600-cycle sequencing kit** in Clarity LIMS. The cycle preset options have been expanded accordingly.
* **System software v1.4 or newer is required for the 2 × 300 1.5B flow cell.**
***
### New 5B Flowcell Support
Clarity LIMS now supports the new **5B flowcell** for NovaSeq X Series instruments. The 5B flowcell supports 100, 200, and 300-cycle kits and follows the same dilution and denature protocol as the 10B flowcell.
* **System software v1.4 or newer is required for the 5B flow cell.**
***
### NextSeq 1000/2000 — Occupancy Metric Replaces Density Metric
The sequencing run metrics displayed in Clarity LIMS for NextSeq 1000/2000 instruments have been updated to show **Occupancy (%)** in place of the Density metric. Occupancy is a more relevant and actionable metric for NextSeq 1000/2000 users when evaluating run quality.
***
## Additional Resources
* [IPP v2.12 Release Notes](/clarity-lims/illumina-preset-protocols/ipp-v2.12/ipp-v2.12.0-release-notes)
* [NovaSeq X Series Integration v1.4.0 Release Notes](/clarity-lims/instruments-and-integrations/novaseq-x-series/novaseqx/novaseqx-v1.4.0-release-notes)
* [NovaSeq X Series On-Prem Integration v1.1.0 Release Notes](/clarity-lims/instruments-and-integrations/novaseq-x-series/novaseqx-onprem/novaseqx-onprem-v1.1.0-release-notes)
* [NextSeq 1000/2000 Integration v2.6.0 Release Notes](/clarity-lims/instruments-and-integrations/nextseq1k2k/nextseq1k2k-v2.6.0/nextseq1k2k-v2.6.0-release-notes)
* [NextSeq 1000/2000 On-Prem Integration v1.1.0 Release Notes](/clarity-lims/instruments-and-integrations/nextseq1k2k-onprem/nextseq1k2k-onprem-v1.1.0/nextseq1k2k-onprem-v1.1.0-release-notes)
***
## Clarity LIMS
Clarity LIMS software is a powerful laboratory information management system (LIMS) designed to optimize genomics sample and workflow management. It enables labs to track samples, streamline complex tasks, generate sample sheets, and identify poor-quality samples before they reach the sequencing system.
* Saves time and minimizes errors in sample handling through an automated workflow.
* Out-of-the box integration with Illumina instruments. Accelerate adoption of Illumina NGS and array protocols with preconfigured workflows that require no coding experience.
* Designed with compliance features including data entry validation, workflow enforcement, audit trails, electronic signatures and role-based permissions.
* Easily collect and share data in real-time with external clients via LabLink. Collaborate on sample submission, status, and results delivery in a single, secure environment.
* Scales with laboratory needs, accommodating third-party instruments and software through a robust RESTful Application Programming Interface (API).
* Flexible deployment options with cloud and local implementations supported.
{% embed url="" %}
{% embed url="" %}
## Latest Releases
* [Clarity LIMS v6.3.5 Release Notes](https://help.connected.illumina.com/clarity-lims/clarity-lims-v6.3-and-lablink-v2.5/readme/release-notes-clarity-lims-v6.3.5)
* [Illumina Run Manager Integration v1.1.2 Release Notes](/clarity-lims/instruments-and-integrations/irm/illumina-run-manager-v1.1.2/irm-v1.1.2-release-notes)
* [IPP v2.12 Release Notes](/clarity-lims/illumina-preset-protocols/ipp-v2.12/ipp-v2.12.0-release-notes)
* [NovaSeq 6000 API-based v3.7.2](/clarity-lims/instruments-and-integrations/novaseq6k-api/novaseq-6000-api-based-v3.7.2/novaseq6k-api-v3.7.2-release-notes)
* [NovaSeq 6000Dx API-based v1.3.2](/clarity-lims/instruments-and-integrations/novaseq6kdx/novaseq-6000dx-api-based-v1.3.2/novaseq6kdx-v1.3.2-release-notes)
## Security Bulletin
* [Investigation of OpenSSH vulnerability with Clarity LIMS](/clarity-lims/announcements/announcement/security-bulletin/investigation-of-openssh-vulnerability-with-clarity-lims)
## Customer Notifications
* [17 July 2025 Clarity LIMS Hosted Instance Interruption - Resolved](/clarity-lims/announcements/announcement/customer-notifications/2025-july-17-clarity-lims-hosted-instance-interruption-resolved)
# Security Bulletin
# Investigation of OpenSSH vulnerability with Clarity LIMS
Published: July 30, 2024
Vulnerability CVE-2024-6387 was found to allow an unauthenticated remote code execution in OpenSSH’s server (sshd) that grants full root access. It affects the default configuration and does not require user interaction, posing a significant exploit risk.
The vulnerability affects OpenSSH version:
* < 4.4p1 (unless the version is patched for CVE-2006-5051 and CVE-2008-4109)
* \>= 8.5p1
* < 8.7p1
* < 9.8p1
The affected OpenSSH versions reported in Vulnerability CVE-2024-6387 are not used for released ClarityLIMS version 6.2.0, 6.2.1 and 6.3.0:
| ClarityLIMS version | Server OS | OpenSSH version |
| :-----------------: | :---------------: | :-------------: |
| 6.2, 6.2.1 | Oracle Linux 8.9 | 8.0p1 |
| 6.3 | Oracle Linux 8.10 | 8.0p1 |
#### References
*
*
*
*
# Customer Notifications
# 17 July 2025 Clarity LIMS Hosted Instance Interruption - Resolved
Published: Aug 15, 2025
We want to provide an update to you about a recent service interruption that affected Clarity hosted instances. The issue was first reported on 17 July 2025 (0210 UTC) and fully resolved on 17 July 2025 (1315 UTC). You might have had encountered slowness within Clarity LIMS or Clarity LIMS failed to start during the period.
The issue was due to Illumina's managed HashiCorp Vault cluster service outage. The HashiCorp Vault outage was caused by surge in the number of active leases¹. All services have been restored with corrective and preventive actions in place. Additional monitoring and alerting have been added to ensure future stability.
We sincerely apologize for the disruption and impact that was caused to your operations.
{% hint style="danger" %}
**Important Recommendations**
We strongly recommend you to have your instance upgraded to the latest Clarity LIMS version 6.3.2 which has a fix to prevent similar issues. Release notes can be found at .
{% endhint %}
Please contact Illumina tech support team should you have any question.
¹
# Clarity & LabLink
{% embed url="" %}
# Other Release Notes
# Clarity LIMS v6.1
Published: 2021
Latest Release: v6.1.0
These Release Notes describe the key changes made to software components for Clarity LIMS v6.1. The Clarity LIMS v6.1 release supersedes v6.0. It is intended for customers on or migrating to Clarity LIMS v6.0.
When upgrading from a version before v6.0, review the release notes for v6.0 for a list of features and bug fixes introduced in that version.
Clarity LIMS v6.1 is deployable in both cloud hosted and on-premise environments.
For API related information, refer to the changes in the current revision of the API Portal. If you have created scripts using our pre-release API endpoints, contact the Illumina Support team for a complete change list to make sure that your scripts continue to function.
### New Features
* Advanced Search can now be used to search by one or more user-customized conditions based on Sample, Project, Container, Step, or File. There are also options for saving and importing queries and exporting search results.
* Read-Only permission — Can be assigned to users that need to view system information, but cannot create, edit, or delete information.
### Updates
* Includes a security improvement that updates jQuery from 3.2.1 to 3.5.1.
### Bug and Security Vulnerability Fixes
The following issues applicable to Clarity Core v6.0.0 and v6.0.1 were resolved:
* The association between the audit event log and the audit change log is missing in Clarity LIMS.
* Adding a control to associated samples shows up in other unrelated workflows that contain the same samples.
* Config slicer log file does not show the actual +/- difference of the conflict.
* Log files fill up with error messages for the Clarity LIMS instance with the remote PostgreSQL database setup.
* Downloaded version of the sample sheet cannot be uploaded when the modify samples function is used.
* \[v6.0.1] Samples cannot be assigned or routed into QC protocols when using the OpenAPI endpoint (`/route/artifacts`).
* \[v6.0.0 and v6.0.1] The derived pool name is not being updated properly based on the naming convention configured in the pooling step.
* \[v6.0.0 and v6.0.1] Pooled samples replicate using the same label, which does not allow users to continue the demultiplexing step.
* Fixes the following bug for LabLink v2.2.0: The association between the audit event log and the audit change log is missing in LabLink.
* Fixes the following bug in Clarity Core v4.3: A user with HTTP/HTTPS/FTP file stores is unable to upload or download files.
### Additional Notes
* Clarity LIMS no longer performs a full nightly indexing in v6.1 by default. Instead, Clarity LIMS performs rolling updates, which index entities for a configurable window of time.
* With the introduction of Advanced Search, basic search no longer finds samples using containers and project custom fields.
* For questions or assistance, contact the Illumina Support team.
# Clarity LIMS v6.0
Published: 2021
Latest Release: v6.0.0
These Release Notes describe the key changes made to software components for Clarity LIMS since version 5.4. The Clarity LIMS v6.0 release supersedes v5.4. It is intended for customers on or migrating to Clarity LIMS v5.4.
When upgrading from a version prior to v5.4, review the release notes for v5.4 for a list of features and bug fixes introduced in that version.
Clarity LIMS v6 is deployable in both cloud hosted and on-premise environments.
### New Features
* Technology updates — An up-to-date technical stack ensures continued reliability, improved speed and capacity, and optimized system performance. For a complete list of updates, refer to the Appendix.
* Project level automation — Users can now write custom scripts and perform custom actions on submitted samples. These custom actions can be triggered manually from the Projects & Samples screen.
* Performance improvements — Improvements to the overall performance of Clarity LIMS v6 and to the existing API endpoints. A complete list of enhancements is provided in the Appendix.
* Support for on-premise customers — Clarity LIMS v6 supports on-premise deployment renewals at launch. Contact your local sales specialist for more information.
* ICA integration — Wet lab data can now be made available to data analysis pipelines via step level scripts.
### Bug and Security Vulnerability Fixes
* An Elasticsearch error is no longer generated when date-formatted text is entered in a non-date field type.
* Resolved an issue where controls were added to more workflows than samples processed in a step.
* An API call to the reagent lot endpoint no longer fails when the lot status is expired automatically by the Clarity LIMS system.
* Resolved inconsistent behavior on archived controls and deleted instrument types in Manifest and XML configuration slice files.
* The root artifact name no longer reverts to default when updates to submitted sample details are submitted via automation.
* Executing the Processes API endpoint on projects with over 500 samples and with a project name filter no longer returns an incomplete set of data.
* A completed workflow stage is no longer missing from the Artifacts API endpoint if the previous step was not an output step.
* Queue screen page load performance has been optimized.
* Users no longer experience decreased performance associated with the Queue API making too many calls.
* Users no longer experience decreased performance when loading Previous Step queue grouping.
* Users no longer experience decreased performance when grouping types on Ice Bucket screen.
* Dropdown fields that do not allow custom entries and have first option set as default are no longer silently applied to various API endpoints and sample sheet upload.
* The changeWorkflow script no longer fails when processing 1152 derived samples.
* Naming syntax LIST option now permits a combination of letters and numbers.
* Master step configuration can now be updated when there is a comma in the naming convention.
### Additional Notes
* Clarity LIMS v4.x is no longer supported by Illumina.
* Clarity LIMS v6 does not support Oracle database. Illumina will continue to support v5.2 for on-premise customers requiring Oracle.
* Clarity LIMS v6 does not support the Reporting module.
* Clarity LIMS v6 has been reviewed for log4j vulnerabilities. All potential vulnerabilities have been addressed.
* For questions or assistance, contact the Illumina Support team.
### Appendix
#### Technical Update Details
| Component | Clarity LIMS v5.4.0 | Clarity LIMS v6.0.0 |
| ------------------------- | ------------------- | ------------------- |
| Elasticsearch | 6.2.4 | 7.16.3 |
| Java | Oracle JDK 8u202 | AdoptOpenJDK 8u292 |
| RabbitMQ Server | 3.6 | 3.8.16 |
| Tomcat Application Server | 8.5.54 | 9.0.54 |
| Grails Web Framework | 2.4.5 | 4.0.10 |
| PostgreSQL Database | 12.4 | 12.7 |
#### Performance Details
The overall performance of the Clarity LIMS system has been optimized on the following screens/actions:
* Sample accessioning
* Assigning samples to workflow
* Removing samples from workflow
* Queue screen page load
* Ice Bucket screen load and loading of all grouping types
* Adding labels to samples
* Record Details screen
* Next Steps screen
* Search indexing
List of API endpoints with enhanced performance is as follows:
* `POST /api/{version}/samples/batch/retrieve`
* `POST /api/{version}/samples/batch/create`
* `POST /api/{version}/route/artifacts`
* `POST /api/{version}/artifacts/batch/update`
* `POST /api/{version}/artifacts/batch/retrieve`
* `PUT /api/{version}/steps/{limsid}/actions`
* `GET /api/{version}/steps/{limsid}/actions`
* `POST /api/{version}/steps`
* `GET /api/{version}/steps/{limsid}/details`
* `GET /api/{version}/queues/{protocolStepId}`
* `POST /api/{version}/steps/{limsid}/advance`
# Clarity LIMS v5.4
Published: 2021
Latest Release: v5.4.0
These Release Notes describe the key changes made to software components for BaseSpace Clarity LIMS since version 5.3. This is an optional software update for customers interested in the new features available with this release.
If you are upgrading from a version prior to v5.3, review the release notes for v5.3 for a list of features and bug fixes introduced in that version.
### New Features
* **Genealogy View** — Provides an interactive and hierarchical view of the history of an experiment processed through BaseSpace Clarity LIMS. Genealogy view shows the relationship between submitted samples, derived samples, and related outputs. Information is presented in a hierarchy, starting with the submitted sample and progressing through all steps performed on derived samples. Genealogy view can also be used for troubleshooting and to help those upgrading from Clarity LIMS v4.x to the latest version of v5.x in the cloud.
* **Email notifications for LabLink notes** — LabLink will send an email notification when a new Project Note or Sample Note is created on the Project Overview or Sample tab. This feature is not active by default.
* **LDAP support for LabLink users** — LabLink now supports LDAP authentication. Customers with LDAP authentication enabled for Clarity LIMS are now able to sign in to LabLink.
* **Security improvements** — When upgrading to v5.4, for password management, users must now provide an email address and reset the password.
### Bug and Security Vulnerability Fixes
* Move to Next Step when uploading a measurement file to Standard QC step artifact.
* Remove from Workflow assigned by Script is not recognized when used on a Pooling Step.
* Running Automations on Step Entry with AutoPlacement and different destination container type no longer results in a 500 error message.
* The Show History feature correctly displays the QC step values.
* The Custom Fields screen can now be accessed by LabLink when Numeric Range fields only have a lower limit.
### Known Issues
* You may experience a decrease in performance when handling large pools of samples (approximately 4000) from the Clarity LIMS interface in pool creation or the creation of output container.
* When using the Processes REST API endpoint with a `projectname` filter on projects with more than 500 samples, the query returns an incomplete set of data.
# API Portal
Together, REST and External Program Integration Plug-ins (EPP)/automation provide powerful and simple-to-use scripting. Before working with the REST API, understand the conceptual structure and design of these interfaces.
The links below provide overview information to help you get started, a self-training Cookbook guide with example scripts, and videos that supplement the API training materials.
* [REST](/clarity-lims/api-and-database/api-docs/rest)
* [Getting Started with API](/clarity-lims/api-and-database/api-docs/getting-started-with-api)
* [Automation](/clarity-lims/api-and-database/api-docs/automation)
* [Tips and Tricks](/clarity-lims/api-and-database/api-docs/tips-and-tricks)
* [Cookbook](/clarity-lims/api-and-database/api-docs/cookbook)
* [Application Examples](/clarity-lims/api-and-database/api-docs/application-examples)
* [Resources and References](/clarity-lims/api-and-database/api-docs/application-examples/resources-and-references)
#### Current API Version:
[Clarity LIMS v6.3](https://d10e8rzir0haj8.cloudfront.net/6.3/REST.html) - v2 r34
#### Previous API Versions:
[Clarity LIMS v6.2](https://d10e8rzir0haj8.cloudfront.net/6.2/REST.html) - v2 r33
# REST
### Overview
The internal Clarity LIMS API (eg, ) is the API used to deliver the Clarity LIMS web interface. This interface is not typically meant for public consumption. However, some customers use it for troubleshooting and to mitigate system issues.
#### Preventing CSRF Attacks
As of Clarity LIMS v5.1, access to the internal Clarity LIMS API changed to enhance security and prevent Cross Site Request Forgery (CSRF) attacks. Two new HTTP headers must now be present when issuing PUT, POST, DELETE, and PATCH requests:
* **Origin**—This header must be set to the scheme and authority of the server being accessed (eg, https\:// example.claritylims.com).
* **X-Requested-With**—This header must be set to XMLHttpRequest.
The attached cURL, Python, and Java examples demonstrate how to authenticate and issue internal API requests. These examples assume a Clarity LIMS server at .
csrf headers.sh:
{% file src="/files/w0XVQOVlZHYvfLfUYCs0" %}
csrf headers.py:
{% file src="/files/kYOJp5yceaql07R9wxVe" %}
csrf headers.java:
{% file src="/files/9l3Mpv7sHymfPGboNHj2" %}
# Filtering List Resources
When submitting a GET request to certain REST API resources (also known as list resources), the system returns a list of records. For example, submitting a GET request to the samples resource returns a list of all submitted samples stored in the system. Depending on the resource being used, use various query parameters to filter the records based on certain criteria. For more information about the parameters that are available, refer to the reference documentation for the desired resource.
To filter a list, the resource and parameter must be separated with a question mark (?). The parameter and the value you want to base the query on must be separated with an equal sign (=).
When filtering a list of artifacts, combine parameters within the same query statement. You can also repeat certain parameters, specifying a new value with each occurrence of the parameter.
The first parameter must be preceded with a question mark (?). Add additional parameters by separating each parameter with an ampersand (&).
Repeating a parameter with new values:
Combining parameters:
When combining or repeating parameters, each record returned matches one of the parameter values, or all the parameter values, depending on the usage:
* If the query statement contains multiple values for the same parameter, the ampersands are treated as an OR.
* If the query statement contains values for multiple parameters, the ampersands are treated as an AND.
For example, if a project LIMS ID and a process type are provided as parameters, the system returns only the files that match both the project LIMS ID and the process type. To see the files that match the project LIMS ID or the process type, issue two separate GET requests and combine the results.
* **/api/v2/processes**—This URI returns all processes run in the system.
* **/api/v2/processes?type=MALDI**—This URI returns all MALDI processes run in the system.
* **/api/v2/processes?type=Sample Prep\&type=MALDI**—This URI returns all MALDI or Sample Prep processes run in the system.
* **/api/v2/containers**—This URI returns all containers in the system.
* **/api/v2/containers?type=Tube**—This URI returns all tubes in the system.
* **/api/v2/containers?type=Tube\&name=27-111\&name=27-112**—This URI returns the tubes in the system that are named 27-111 OR 27-112.
### Using the Last-Modified Parameter
Certain resources include the last-modified query parameter.
When used, the system displays only the results that have been modified because the last-modified date. The last-modified date is represented in ISO 8601 Complete date including hours, minutes, and seconds format: YYYY-MM-DDThh:flag\_mm:ssTZD.
### Viewing Paginated Results
Lists of records are often large, spanning multiple pages. Many list resources include parameters that are used to work with paginated results.
### Using UDF and UDT parameters
Certain resources include parameters that can be used to filter the results displayed based on UDF information that is associated with the results:
* **udf.UDFNAME\[.OPERATOR]=UDFVALUE**—This parameter filters the results based on a specified value for a specified UDF. Any item that contains the value for the UDF is returned, unless parameters include an optional operator filter ( \[.OPERATOR] in the expression provided). The lowercase filter operators of min or max are described later.
* **udt.name=UDTNAME**—This parameter filters the results based on a specified UDT. Any item that has the UDT selected is returned.
* **udt.UDTNAME.UDFNAME\[.OPERATOR]=UDFVALUE**—This parameter filters the results based on a specified value for a specified UDF that resides within a specified UDT. Any item that contains the value for the UDF is returned, unless parameters include an optional operator filter ( \[.OPERATOR] in the expression provided). The lowercase filter operators of min or max are described later.
To To filter results using UDF information, use the following query structure:
To filter results using the name of a UDT, use the following query structure:
To filter results using UDF information that is part of a specific UDT, use the following query structure:
When filtering lists and using date or numeric UDF or UDT values, use operators to restrict a query. The following operators are supported:
* **.min**—This operator displays results that are greater than or equal to the specified value.
* **.max**—This operator displays results that are less than or equal to the specified value.
Examples:
* **/api/v2/processes?type=Sample Prepandudt.name=Plasma**—This URI returns all Sample Prep processes run in the system that have the Plasma UDT selected.
* **/api/v2/processes?type=Sample Prepandudt.Plasma.Platelet Count.min=50**—This URI returns all Sample Prep processes that have a UDF named Platelet Count with a value of 50 or greater, within a UDT named Plasma.
* **/api/v2/processes?type=Sample Prepandudf.Sample=Serumandudf.Sample=Tissue**—This URI returns all Sample Prep processes that have a UDF named Sample with a value of Serum OR a UDF named Sample with a value of Tissue.More examples of filtering exist in the Cookbook.
For more examples of filtering, see the [Cookbook](/clarity-lims/api-and-database/api-docs/cookbook).
When filtering with UDT or UDF parameters, all special characters in the parameter string must be URL encoded. The Pipe ( | ) or the URL-encoded pipe ( ) cannot be used.
When filtering on a UDF that is configured as a Multiline Text UDF, if a value contains a hard return, the value must include the URL-encoded line feed () at the appropriate location. Depending on how API requests are issued (via a browser or a script), spaces in names or values may require URL encoding, and trailing spaces in a name or value always require encoding. For example, for results to be returned, ‘name ‘ requires ‘name’.
# HTTP Response Codes and Errors
The REST API methods attempt to return appropriate HTTP status codes for every request. To use the REST API effectively, a good understanding of HTTP and status codes is required. A complete list of HTTP status codes and definitions can be found at the following website: [HTTP/1.1 Status Code Definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
The primary status codes used by the REST API are as follows:
* **200 OK:** Success.
* **201 Created:** A resource was successfully created.
* **400 Bad Request:** Invalid data was supplied for the relevant resource type.
* **401 Unauthorized:** The requested resource cannot be loaded until valid logon credentials have been entered. If this error is received after logon credentials have been entered, this indicates that the credentials are not valid.
* **403 Forbidden:** Access to the requested resource has been denied. (Make sure that the authorized user has administrative privileges.)
* **404 Not Found:** The URI requested is invalid or the resource requested does not exist.
* **413 Request Entity Too Large:** The request is larger than the server is willing or able to process.
* **500 Internal Server Error:** A generic error message, given when there is no suitable specific message.
### Error message format
Error messages are returned as exception elements with a message element containing a user-facing error message.
The exception may also include a suggested-actions element with more detail on how to resolve the error.
User-facing XML error messages are not returned for 401 and 403 errors. In these cases, the HTTP error must be resolved.
# Requesting API Version Information
When submitting a request to the REST API, specify the version of the API being used. The version number is a path parameter in each resource URI. The desired API version is substituted into the request URI as follows:
Changes to the API are tracked with a version number (version major) and a revision number (version minor).
* The version number indicates forwards and backwards compatibility.
* The revision number within the version describes features added to the API that will not negatively affect current functionality.
Only the version number is referenced as part of the request. The revision number simply tracks incremental enhancements to the API.
When a new version of the API is released, update the scripts and code as soon as possible.
### Check API Version
To find out what version of the API is available from a given server, submit a GET request to the base API URI. For example, in a web browser, browse to:
The system will return the version:
### Exception for Legacy Systems
The API was originally intended for internal use or for just a few customers. In those early days, API versioning was different. If working with legacy scripts, this older functionality can be maintained. For example, if scripts were written before v2 and have nondefault system configuration properties for api.prefix and api.rewrite on the server, the …/api/ URI lists the resources and does not provide version information.
# REST General Concepts
REST and automation are the key interfaces for scripting. A language-agnostic application programming interface (API) is important to scientists as it allows for broad and diverse integration. Together, REST and automation provide powerful and easy-to-use scripting. However, you first need to understand the conceptual structure and design of these interfaces.
Within the Clarity LIMS Rapid Scripting API, REST technology is used to provide data specifically structured for life science research.
{% hint style="info" %}
The API documentation includes the terms External Program Integration Plug-in (EPP) and EPP node.
As of BaseSpace Clarity LIMS v5.0, these terms are deprecated. The term EPP has been replaced with automation. EPP node is referred to as the Automation Worker or Automation Worker node. These components are used to trigger and run scripts, typically after lab activities are recorded in the LIMS.
{% endhint %}
**NOTE**: If you are new to the REST Web Service, we recommend that you read [Development Prerequisites](/clarity-lims/api-and-database/api-docs/getting-started-with-api/development-prerequisites) and [REST Web Services](/clarity-lims/api-and-database/api-docs/rest/rest-web-services).
### REST: a web service for data access
The **REST Web Service** is the fundamental **data access interface** using XML over HTTP. It is agnostic to programming languages as most languages support HTTP and XML with libraries or built-in methods.
In life science research labs, tracking samples and the data associated with biology, research, and lab work is complex. The REST resources return information that is human-readable and interpretable. Use a web browser to explore the XML returned.
REST represents real laboratory items and activities in self-contained groups of data called **resources**. It provides access to recorded lab steps and to sample test results, and it provides this access using **resources**. For example:
* The **process** and **steps** resources track the steps in the lab in terms of who did what and when.
* The **sample** and **artifact** resources contain information on the submitted sample and test results on sample derivatives (also referred to as derived samples).
The REST resources and their relationships are explained in [Structure of REST Resources](/clarity-lims/api-and-database/api-docs/getting-started-with-api/structure-of-rest-resources).
The full details of each resource are described in the [API Portal](/clarity-lims/api-and-database/api-docs).
### General concepts
Requests are made to the API by sending XML messages:
* **POST** is used to create an item.
* **GET** is used to read an item.
* **PUT** is used to update an item.
* **DELETE** is used to delete an item.
**Note**: **HEAD** requests are not supported.
The full URL to which requests should be sent will vary depending on the specific installation, but will generally follow this format:
```
http[s]://:/api/
```
### Automation / EPP: GUI trigger for calling scripts
Automation / EPP is used to trigger scripts from within the Clarity LIMS interface.
Script-triggering is often used because the data collected needs to be dispatched for further processing. Automating data processing and returning information, in the appropriate format, to the lab for immediate use increases efficiency and quality.
**File handling** and **file management** are fundamental elements in life science scripting. When triggered, scripts can issue a command, transfer files for processing, and collect and transfer files back to the server. To enable triggering of scripts in any programming language, the information and files are provided for batch processing at the **operating system command line level**.
#### For Clarity LIMS (v5 and later)
{% hint style="info" %}
As of Clarity LIMS v5, the Operations Interface Java client, which was used by administrators to configure processes, consumables, user-defined fields, and users, has been deprecated. All configuration and administration tasks are now executed in the Clarity LIMS web interface.
{% endhint %}
**To use automation, administrators complete the following steps:**
1. In Clarity LIMS, create and configure master steps.
2. Configure automations that trigger scripts. Enable those automations on the master steps.
3. Use the configured master steps as building blocks to create and configure steps to be run by lab scientists.
Related Resources
* [Automation](/clarity-lims/api-and-database/api-docs/automation)
* [Work with EPP/Automation and Files](/clarity-lims/api-and-database/api-docs/cookbook/work-with-epp-automation-and-files)
# REST Web Services
The Clarity LIMS Rapid Scripting™ API provides scientific programmers with self-descriptive, yet flexible, data access. It uses a RESTful model for data access because this model is well suited to these requirements. This article provides a high-level introduction to REST concepts and technologies.
### Introduction to REST Web Service Technology
Representational State Transfer (REST) is a style of software architecture for distributed information retrieval systems, most commonly observed by using the web.
* REST governs proper behavior. It is not a methodology or a design principal, but rather a **set of rules** to which a system should conform.
* REST allows a **uniform interface** between clients and servers that is **simple** and **decoupled**, enabling each system to evolve independently.
* REST is referred to as **stateless** because each new API request contains all the information required to complete it, without relying on previous requests. Conforming to these REST principals is referred to as being RESTful.
* REST was **developed in parallel with HTTP** and makes use of this protocol. It is an elegant way to programmatically access resources over HTTP. It is very flexible because you can use it with any language or tool that supports HTTP.
#### Other uses of REST
The web is probably the largest known RESTful system. Its behavior is very simple:
1. When you click a link in a web browser, your system requests information by sending a **GET** request to the specified URL. This URL is a **resource**.
2. The server that hosts the URL responds, typically with one of two things:
* If the page exists, the server sends the browser an **HTTP 200** response code and the contents of the page.
* If the page does not exist, the server sends an **HTTP 404** response code and an error message indicating that the page cannot be found.
Many software development groups use RESTful APIs. Google, Yahoo, and many public web sites use the RESTful model for information access.
### Communicating with the REST API
The REST API allows you to retrieve and update information using HTTP operations. This ability provides some flexibility in how to communicate with the system.
While REST requests and responses can be in a variety of formats, we chose XML. Each resource and XML element is detailed in the [API Portal](/clarity-lims/api-and-database/api-docs).
#### Authenticating with the API
To use the REST API, sign in using HTTP BASIC authentication. The method used to authenticate will depend on how you use the API:
* When using a browser to retrieve information from the API, sign in to the browser with a user name and password. When signing in using a browser, the session remains open until the browser is closed.
* When using an HTTP request tool to retrieve, add, update, or remove data using the API, the tool asks for a user name and password each time you submit a request to the system.
* When using a script to communicate with the API, the script must first authenticate with the API. The session remains open for as long as the script is being actively read by the system.
The account you use to sign in to the API must have System Administrator or Facility Administrator privileges.
#### Understanding URIs used by the API
The API allows self-discovery of an object. When you request information about an object, the system typically returns URIs to its children and, sometimes, its parent. Use one URI to find the next URI in a hierarchy.
When viewing XML in a browser, tools can automatically create links from the URIs returned by the system. Examples of such tools are the Firefox [Text Link](https://addons.mozilla.org/en-US/firefox/addon/1939/) or [Linkificator](https://addons.mozilla.org/en-US/firefox/addon/linkificator/) add-ons. This way, you can select URIs to browse through the API.
Requests are made to the API by sending XML in HTTP calls:
* **GET** is used to read an item.
* **POST** to create an item.
* **DELETE** to delete an item.
* **PUT** is used to update an item.
In its simplest form, use a browser to enter and read the content of a URI, which allows browsing through the system. When using this method, a GET request is issued to the API for a specified object (referred to as a resource). The request returns XML containing the metadata about that **resource**. See the following section for details.
If you want to add, update, and delete small amounts of data using the API, use an HTTP request tool, such as the Firefox [RESTClient](https://addons.mozilla.org/en-US/firefox/addon/restclient/) add-on.
### Resources and Namespaces
When working with REST, there are references to **resources** and **namespaces**.
For references:
A RESTful API groups related information into resources, each of which is referenced with a global identifier (URI).
In the API, for example, every sample in the LIMS has a resource for its information. When scripting, the resource is created or updated with POST and PUT HTTP calls. There are two types of resources: **single** and **list** types.
* A list resource is used to access a collection of single resources (such as a listing of all samples).
* The single resource type is used to access details on just one resource (a sample, for example).
It's important to understand how the information in the LIMS has been grouped and structured into resources. To learn more, see [Structure of REST Resources](/clarity-lims/api-and-database/api-docs/getting-started-with-api/structure-of-rest-resources).
For namespaces:
An API that uses XML relies on namespaces. In XML, namespaces define the vocabulary of elements and attributes in an XML document. Each REST resource references the XML structure defined by a particular namespace.
When scripting, we use namespaces to look up specific details related to the XML data elements, attributes, and formats that represent a resource. Namespaces also order the subelements of the XML document.
In the current revisions of the API, the PUT and POST methods read the subelements of the XML independent of order, but the namespace still defines the order of the XML provided in GET calls.
#### Additional Information
For sophisticated write operations and automation of work, you must use a script to communicate with the API. The [Cookbook](/clarity-lims/api-and-database/api-docs/cookbook) contains examples that demonstrate how to use scripts to perform your work.
# Traversing a Genealogy
### Traversing Up a Genealogy
The artifacts resource includes a parent-process element that provides a URI to the process that created an artifact.
To facilitate walking up the genealogy, the processes resource exposes the parent process for an input artifact in the input-output-map of a process:
The parent-process element does not display if the parent process is not supported by the API.
### Traversing Down a Genealogy
The processes resource supports an inputartifactlimsid query parameter. This parameter limits the list of processes to those processes with one of the specified artifacts as an input.
1. Start with the initial sample.
2. The processes for the sample can be queried, as follows.
3. The process contains an input-output-map for the input artifact.
4. The steps can then be repeated using the LIMS ID of each output artifact that is associated with the input artifact.
# Viewing Paginated List Resources
The REST API only returns 500 results per request. Because of this feature, with certain resources, you can use the start-index parameter and previous-page and next-page elements to work with large amounts of data.
For example, the following request is submitted to the API:
The response looks like this:
Note the presence of the previous-page and next-page URIs, which allow moving within the pages of results.
### Viewing Results from a Specified Point
Use the start-index parameter to view results from a specified point in a list. The first record in a list is index 0, and you can use values that are positive, whole numbers. If the value specified is greater than the number of results available from a resource, the system returns an empty list.
### Configuring the Maximum Number of Requests
By default, the REST API only returns 500 results per request. To change the default number, contact the Illumina Support Team.
# Working with Batch Resources
When multiple users are working on multiple plates in high-throughput labs, programmers may find that the large number of HTTP method calls to the REST API can slow down their scripts.
To improve performance, Illumina has created the following batch resources:
* artifacts.batch.retrieve
* artifacts.batch.update
* containers.batch.create
* containers.batch.retrieve
* containers.batch.update
* files.batch.retrieve
* files.batch.update
* samples.batch.create
* samples.batch.retrieve
* samples.batch.update
Use the batch resources to access a group of artifacts or a group of containers using a single batch method call. Using these resources to iterate a list of items significantly improves script execution times.
### Key Concepts
Batch resources are best thought of as unordered collections or lists of items accessed. A POST to batch/create, batch/update or batch/retrieve, therefore, is a request to create, update, or retrieve those items. There is no guaranteed order to batch responses.
Batch resources are nonbreaking additions to the existing REST API. Updated scripts can still use their existing nonbatch methods.
For example, the resources may have URIs (Universal Resource Identifiers) such as:
Batch operations do not require sophisticated HTTP client or server methods. The only HTTP method for batch resources is POST.
### What is sent in a batch resource POST?
To update a group of artifacts, use a POST operation to the /artifacts/batch/update resource. The XML input payload consists of a series of elements, as follows.
### What is returned from a batch resource POST?
As large data transfers can affect performance, it is important to return concise XML in response to a batch resource request. Therefore, except for retrieve resources, the XML output payload consists of a list of created or updated URI links, such as the following:
### Return codes
The batch resources use common HTTP return codes:
* An HTTP 200 (OK) code is returned when batch resources have been successfully created or updated.
* An HTTP 400 error code is returned if the input payload details included incorrect, mixed, or duplicate URI links. For example, if the details of an artifacts.batch.update (list) request included a container resource.
# Working with User-Defined Fields (UDF) and Types (UDT)
### Removing Fields and Types
To remove a UDF or UDT value, submit a PUT request with the desired UDF or UDT omitted from the XML.
### Updating Resources
When submitting a PUT, it is critical to update all information. The submitted XML must include all the current UDFs and UDTs for the resource. If the field and type elements for a UDF and UDT are not included, the system removes those fields and types.
To update the UDF information for an item, the PUT request can add new UDF values and update or remove current UDF values. When working with UDTs, replace the current UDT with another UDT, or add or remove fields within the current UDT.
* Update all UDFs and UDTs in a PUT
* Even if the current user-defined values are not changing, include the current UDF and UDT values in the XML representation for a PUT request.
### Filtering with UDF and UDT Values
Data formatting of the UDF and UDT values is important when filtering a resource list with a query parameter. When using UDF or UDT values as a query parameter, all nonalphanumeric characters must be URL encoded.
### Data Type Formats
UDFs and UDTs are presented as fields and types in the XML. The following example shows a representation of fields and types returned by a GET request for a sample:
### Data Type Values in XML
XML resource representations do not render UDF values in the same format as views in the client user interface. The table later in this section compares images taken from the client user interface and the XML from an http GET.
The differences are intentional, to remove ambiguity and aid script writers when handling the data values.
The following table compares the values displayed by the user interface and the API for UDF data types.
| **Configured Data Type** | **API XML Response Element Type Name** | **Client Display** | **API Element Type Format** |
| ------------------------ | -------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Single-line Text | String | Leading and trailing spaces rendered | Leading and trailing spaces rendered |
| Multi-line Text | Text | Leading and trailing spaces rendered | Leading and trailing spaces rendered |
| Numeric | Numeric | Set by display-precision ie, 4.5300 is displayed when display-precision equals 4 | Simplest numeric form, removing trailing zeros ie, 4.53 |
| Date | Date | mmmm dd, yyyy ie, Feb 15, 2019 | yyyy-mm-dd ie, 2019-02-15 |
### Numerics and Significant Digits
Trailing zeros are removed to support both integer and real numerics. Determine the significant digits by looking up the display-precision element of the /configuration/udfs/{udfid} resource.
### EPP UDF Date format
When Date UDFs are expanded on the EPP command line, their format differs from the one used in the Clarity LIMS GUI and the REST API.
# XML UTF-8 Character Encoding
When generating XML, explicitly set the document to UTF-8 character encoding.
If using other encoding methods (eg, MacRoman for OS X), special characters such as μg/ml are stored incorrectly. This could cause data integrity issues.
In Groovy, set the encoding attribute on the StreamingMarkupBuilder object as shown in the following example:
# Getting Started with API
The internal Clarity LIMS API (eg, ) is the API used to deliver the Clarity LIMS web interface. This interface is not typically meant for public consumption. However, some customers use it for troubleshooting and to mitigate system issues.
### Preventing CSRF Attacks
As of Clarity LIMS v5.1, access to the internal Clarity LIMS API changed to enhance security and prevent Cross Site Request Forgery (CSRF) attacks. Two new HTTP headers must now be present when issuing PUT, POST, DELETE, and PATCH requests:
* **Origin**—This header must be set to the scheme and authority of the server being accessed (eg, https\:// example.claritylims.com).
* **X-Requested-With**—This header must be set to XMLHttpRequest.
The attached cURL, Python, and Java examples demonstrate how to authenticate and issue internal API requests. These examples assume a Clarity LIMS server at .
### Attachments
csrf headers.sh:
{% file src="/files/w0XVQOVlZHYvfLfUYCs0" %}
csrf headers.py:
{% file src="/files/kYOJp5yceaql07R9wxVe" %}
csrf headers.java:
{% file src="/files/9l3Mpv7sHymfPGboNHj2" %}
# API-Based URIs (LIMS v4 and later)
Clarity LIMS version 4.0 introduced architectural changes that enforce SSL-based security. As a result, the structure of the URIs that reference the Clarity LIMS API was modified, and scripts written before Clarity LIMS v4.0 may require updating.
### Details
Scripts that use the API do so by using RESTful methods on specific URIs. The base portion of the URI references the server on which the Clarity LIMS application is running.
Before Clarity LIMS v4.0 the base portion of the URI took the following form:
http\[s]://\:\/api
Where:
* The protocol could either be HTTP or HTTPS, depending on whether the application was SSL-enabled or not.
* \ represented the fully qualified domain name (or IP address) relating to the server on which the Clarity LIMS application was running.
* \ represented the port number (typically 8080) on which the Clarity LIMS application was listening.
In Clarity LIMS v4.0 and later, the base portion of the URI is in the following form:
https\://\/api
Where:
* The protocol must be HTTPS, because the Clarity LIMS application is now installed with SSL enabled.
* The server name must match the certificate that was purchased and installed into Clarity LIMS.
* The port number (and the colon) is no longer required. Do not provide it.
### When to Update Existing Scripts
The following information should help determine if updates to the scripts are needed.
Scripts generally determine the API URI in one of the following ways:
1. The URI is passed to the script by the automation or External Program Plugin (EPP) component, as a parameter or command-line argument.
2. The URI is passed to the script by another script or a command line embedded in a crontab file.
3. The script contains the URI as a hard-coded string literal.
4. The script determines the fully qualified domain name of the server and adds the prefix (http\://) and suffix (:8080) accordingly.
5. The script imports, or includes a file that contains, the URI.
Most scripting uses methods one or three. However, other methods may be used in the facility.
* If method one is used, it is not necessary to update the scripts because Clarity LIMS passes in the new form of the URI.
* If other methods are used, you likely need to update the scripts to convert the URI to the new format. Often, a search and replace tool is able to make these changes.
To make sure that the correct locations are searched, keep in mind that scripts are often stored in the following locations:
1. In the /opt/gls/clarity/customextensions folder (and subfolders) on the server where Clarity LIMS is running. This location is the domain of the default Automation Worker (AW)/Automated Informatics (AI) node, which listens on the channel name of limsserver.
2. If there are additional AW/AI nodes on the server, in the folders used by these nodes.
3. If there are additional AW/AI nodes external to the Clarity LIMS server, within the folders used by these nodes.
4. If scripts are launched by cron, or other mechanisms, they could be stored anywhere and may not even be on the Clarity LIMS server itself.
For points 1–3, query Clarity LIMS (via either the API or the database) to produce a listing of all the scripts it is configured to use. As a result, determine on which node they run and their location.
For point 4, there is no easy answer. Hopefully, if the script is important, the location has been documented.
{% hint style="info" %}
As of Clarity LIMS v5.0, the terms External Program Integration Plug-in (EPP), EPP node, and AI node are deprecated.
The term EPP has been replaced with automation, while the Automated Informatics (AI) node is referred to as the Automation Worker (AW) node.
{% endhint %}
# Development Prerequisites
Understanding lab information management in a scientific context is one of the more powerful skills in genomics research today. The Clarity LIMS Rapid Scripting™ API is designed to use these skills, allowing a knowledgeable scientific programmer to adapt lab informatics with scripts and automation.
**NOTE**: Based on experience working with bioinformaticians and scientific programmers, assumptions about your background, setup, and skills have been made.
### Before you begin
Before using the API Cookbook, set up a [#h\_19503004-55bb-48e6-a8ad-af73e66a1d54](#h_19503004-55bb-48e6-a8ad-af73e66a1d54 "mention").
If any of the topics covered on this page are a concern, contact the IlluminaSupport team for additional training or custom scripting services.
### Terminology
Within the Cookbook, the term scripting refers to programs running independently of the client and server that direct the input and output of information. Use scripts and the API for file handling and text processing in the context of biological samples, containers, and instruments.
### Skills and Training
* This API Cookbook assumes that you can program in modern computer languages, and are comfortable with scripting and bioinformatics.
* The topics are best understood by those users who can program small applications and are experienced with experimental processes in molecular biology.
* The topics assume that you have received administrator-level training or know how to configure the system. The topics also assume that a nonproduction server is set up to play with cookbook examples, develop real scripts, and test before deploying in production.
* Be comfortable with the following skills:
* XML
* System file handling
* General-purpose scripting languages
* Working on the command line
### Non-production scripting sandbox servers
Illumina provides multiple server licenses for API users: a **production server license** and one or more **non-production server licenses** for developing and testing.
To allow developers to design, build, test, and upgrade efficiently, it is recommended to install at least two servers. Installing three is even better.
The non-production server licenses serve the following purposes:
* To provide a sandbox in which to experiment with the API and the system configuration.
* To provide a verification platform for upgrading scripts, software components, and overall system integration before deploying to production.
All the examples in the [Cookbook](/clarity-lims/api-and-database/api-docs/cookbook) are intended to be used with the nonproduction scripting sandbox server. See [Useful Tools](/clarity-lims/api-and-database/api-docs/application-examples/resources-and-references/useful-tools).
{% hint style="info" %}
If you do not have the time or resources to use the API, but are interested in expanding your implementation, contact the Illumina Support team. There are various consulting, training, and scripting services available.
{% endhint %}
# Integrating Scripts
The BaseSpace Clarity LIMS Rapid Scripting™ API adapts lab informatics using the Clarity LIMS platform.
It is important to integrate scripting into the overall processes. Begin by identifying any areas that may require adaptation to fit the lab workflow. It also helps if users are involved in the early stages of the software system analysis process.
Most scripts in an implementation are finalized towards the end of the process, as the full impact and benefits of the new system become clear.
Take some time to become familiar with the user interface, learn how to configure the product, and work with the tools that the lab uses. Also, establish the workflows and the configuration of the system before investing in API scripts and automation.
### **Start with Administrator Training**
New customers receive administrator-level training before working with the API.
If you are not comfortable configuring steps, custom fields, containers, etc., in Clarity LIMS, you may find the API material difficult to understand. Contact Illumina for more information on administrator training and training materials.
If you are not comfortable configuring steps, custom fields, containers, etc., in the LIMS, you will find the API material difficult to understand. Contact Illumina for more information on administrator training and training materials.
### Defining the Lab Solution
Before committing time and resources to using the API, it is important to define what you would like to accomplish. Understanding the key outcomes, use cases, users, and constraints of the lab helps with learning the API more quickly and improves efficiency.
If you require assistance, Illumina can provide expert resources to audit and analyze the laboratory users, processes, workflows, instrumentation, data production, and environment. This careful and focused analysis results in a requirements specification that provides extensive value to the facility.
### Related Resources
* [Useful Tools](/clarity-lims/api-and-database/api-docs/application-examples/resources-and-references/useful-tools)
* [Suggested Reading](/clarity-lims/api-and-database/api-docs/application-examples/resources-and-references/suggested-reading)
# Structure of REST Resources
The information recorded in BaseSpace Clarity LIMS is organized into resources within the REST API. Each resource refers to an XML schema associated with a namespace. Before working with the REST Web Service, understand how the information recorded in Clarity LIMS translates to the REST resources.
The following diagram highlights the major REST resources. Each resource is discussed further in the following sections.
* **Samples** are the objects that are entered into the LIMS before processing begins. Every sample belongs to a single **project** and has a related **analyte** (sample) artifact. Every project must have an associated **researcher**.
* When you add a sample to the system, it is classified as a **submitted sample**. This allows the original samples, and any related data, to remain separate and distinct, even as processing and aliquoting occurs. Every sample or file created by running a step from the LIMS user interface can be traced back to a submitted sample.
* In Clarity LIMS, processes (know as steps in the user interface) are run on analyte (derived sample) artifacts. Samples must always be in containers.
* Clarity LIMS v4.x and earlier: In the Clarity LIMS Operations Interface processes are run on analyte (sample) or result file artifacts. Samples must always be in containers.
* As of BaseSpace Clarity LIMS v5, the Operations Interface Java client used by administrators to configure processes, consumables, user-defined fields, and users have been deprecated. All configuration and administration tasks are now executed in the Clarity LIMS web interface.
* To understand how API terminology maps to terminology used in the Clarity LIMS v5 interface, see [Understanding API Terminology (LIMS v5 and later)](/clarity-lims/api-and-database/api-docs/getting-started-with-api/understanding-api-terminology-lims-v5-and-later).
### Samples
Within the REST Web Service, the **samples resource** is key.
The **samples** resource represents submitted samples and contains information about those samples, including:
* The dates samples are entered and received.
* Any user-defined data related to the samples.
When a sample is added to the LIMS, the system also creates an **artifact** (see [#artifacts](#artifacts "mention")).
While the artifact associated with a submitted sample is only seen at the database or REST level, and is never exposed in the LIMS interface, the system uses this artifact when running protocol steps.
When running a step on a submitted sample, the **artifact is used as an input** to the step, and not the submitted sample itself. All artifacts reside within the **artifacts resource**.
When a submitted sample is processed, the system generates **output artifacts**. Depending on the configuration of the process, many types of artifacts - including result files - can be generated. Any downstream sample created by running a process is considered an **analyte artifact** (referred to as a **derived sample** in the user interface).
### Projects
Projects are used to group samples based on the originating lab (account) or study. Projects collect all records related to that sample in the LIMS.
A project stores information about:
* The client (researcher) who owns it
* Significant dates
* The status of the project
* Any user-defined information that the lab needs to collect
After creating a project, you can add samples to it. Samples can then be added to workflows, and steps (processes) are run on those samples to reflect the analysis performed in the lab.
In the REST Web Service, a submitted sample can only belong to one project. You can use the **projects resource** to return projects.
Note the following details regarding projects:
* Every submitted sample must belong to a **project**.
* Every project must be assigned to a researcher (an owner) that corresponds to a client in the system.
* **NOTE**: In the LIMS user interface, the term **Contact** has been replaced with **Client**. However, the API permission is still called **contact**.
The **researchers resource** represents clients in the system.
When working with projects, each project must list a client as the owner of the project. This role generally represents the person who submitted the original samples.
The client does not need to have a user account.
### Processes
{% hint style="info" %}
In Clarity LIMS v5, the API still uses the term process. However, in the user interface, this term has been replaced with master step. Also, the Operations Interface has been deprecated.
{% endhint %}
* **Clarity LIMS v5 and later**—Created in the Clarity LIMS web interface, master steps model and track the work performed on the samples in the lab. These master steps are then used as building blocks to create and configure steps. These steps are known as processes in the API.
Different interfaces may allow you to run steps/processes on different artifacts.
In the API view, a process takes in one or many analytes and/or result files and creates one or many analytes and/or result files.
When running a step in Clarity LIMS, lab scientists record information about the step, the instruments used, and the properties and characteristics of the samples.
Depending on the configuration of the process/master step on which it is based, the step can generate another sample analyte and/or placeholders to which result files can be attached for storage in the system.
With the REST Web Service, the **processes resource** is used to track these activities.
Note the following details regarding processes:
* Processes are used to represent work that occurs in the lab or in silico.
* Processes take inputs and create outputs. With the REST **processes resource**, this is modeled using the **input-output-map** element.
In addition to tracking historical work via the processes resource in the REST Web Service, use the service to POST new processes to the system.
POSTing a process to the REST Web Service creates the process itself, along with the outputs of the process. However, all the input and output containers must exist in the system already.
* For a simple example of the XML required to POST a process, see the processes (list) section of the REST resources space.
* For basic details about POSTing processes, see Working with Processes/Steps in the Cookbook section.
* For examples of process POSTing, see Pooling Samples with Reagent Labels and Demultiplexing in the Cookbook section.
* To find out how to integrate automation with process POSTing to set quality control flags, see the Setting Quality Control Flags application example.
Query the processes resource using input artifact LIMS IDs. This query allows you to find the processes that were run at each step in the workflow or on each artifact generated during processing.
### Artifacts
All inputs and outputs of a process are artifacts, and can be returned via the **artifacts resource**.
Note the following details about artifacts:
* An artifact is a derivative of a sample and is used as an input to a process.
* An artifact may be a sample analyte or a result file.
* The **artifacts resource** includes artifacts for the submitted sample and all process outputs, both file- and sample-based.
Artifacts are categorized by type, to distinguish between pure information results (file-based artifacts, such as result files) and the biological material created by processing the sample (analyte artifacts).
In Clarity LIMS, the term artifact is used to describe items needing to be processed. Think about artifacts as the intellectual property added by the lab.
For example, applying reagents to change the nature of a sample creates an artifact, as does generating and analyzing data files by running a sample on a NextGen or microarray instrument.
Anything created by a process in the system is an artifact. In the REST Web Service, there are several types of artifacts, but this article focuses on two:
* Computer-generated files called **result files**
* Physical sample derivatives called **analytes**.
The high-level relationship between artifacts, analytes, and result files is shown in the following diagram.
An artifact references data elements, which vary depending on the type of artifact you are working with. For example, a result file has an **attached-to** URI that links to a **files resource**, whereas an analyte has a **location** URI that links to the **containers resource**.
Artifacts are key to tracking lab process activities and also link to a submitted sample.
All artifacts include one or more sample URI data elements, which make it easy to trace any lab-generated product or result directly back to its original sample.
When working with artifacts in the REST API, their URIs often include a numeric state. The state is used to track historical QC, volume, and concentration values.
Unless you are interested in a historical state, it is best practice not to include state when using an artifact URI. When state is omitted, the API defaults to the most recent state.
### Containers
When samples are processed in the lab, they are always placed into containers of some sort (tubes, 96-well plates, flow cells, etc.) and moved into new containers as processing occurs.
For many kinds of processing, the container placement is a critical piece of information. Further processing of the sample, and data files created by analyzing the sample, are often linked based on the placement of the sample in the container.
Containers are central to processing in the lab. In Clarity LIMS, therefore, the samples (analyte artifacts) must also always be placed into a container resource.
When working with the REST Web Service, analyte artifacts include a URI that links to the container housing the artifact. Use the containers resource to view all the containers registered in the system.
Details on finding contents of a container can be found in the [Cookbook](/clarity-lims/api-and-database/api-docs/cookbook).
Note the following details about containers:
* Containers represent the tubes, plates, flow cells, and other vessels that can be populated with a sample.
* All samples/analytes must reside in a container or they will not be visible in the LIMS client.
All containers include a **name** and a **LIMS ID**.
* The name is a text element over which the scientific programmer has full control.
* The LIMS ID is a unique identifier generated by the system in a fixed format.
The name, LIMS ID, and any container-level [#udfs](#udfs "mention") provide various options for container labeling.
For assistance, the Illumina Consulting team can recommend various settings, such as uniqueness constraints, based on your requirements.
### Files
A lab produces various files: large scientific result data files, summary result files, image files, label files, equipment and robotic setup files, and software logs.
These files are stored in different locations and it can be challenging to manage the relationship between a file on a computer or hard disk and the sample, step, or project with which it is associated.
Clarity LIMS lets you store files related to a project or sample and files generated during a step in a workflow. These files can be imported in various locations within the client and are stored on the file server.
To model this feature within the REST Web Service, there are two resources:
* **files** resource
* **glsstorage** resource
Within the REST Web Service, files are represented by the files resource. This resource manages files and the resources or artifacts to which they are related, and stores information about:
* The sample, project, or process output with which the file is associated, referenced by the **attached-to URI**.
* Where the file was imported from, and its original name, referenced by the **original-location URI**.
* The location of the file, referenced by the content-location URI. It also specifies the transfer protocol that can be used to retrieve the file. The following transfer protocols are supported:
* ftp
* sftp
* HTTP
#### **Files added using the LIMS client**
If you are using REST to view a file that was added through the LIMS client, the **content-location URI** will reference a location on the file server. This location is where the system stores all files that are imported through the Clarity LIMS client.
#### **Files added using REST**
If you are using REST to import a file into the system, do one of the following:
**Store the file on the file server:**
1. Use the **glsstorage resource** to create a unique storage location and file name on the file server.
2. After this step is complete, the system returns a location and file name using the **content-location URI** element.
3. Then do as follows.
* Provide the URI to the **files resource**.
* Put the file in the specified location.
**Store the file somewhere other than on the file server:**
* Use the **files resource** and reference the name and location of your file with the **content-location URI** element.
* This feature must be configured by Illumina. For more information, contact the Illumina Support team.
Not the following key concepts:
* **Files**: The **files resource** defines the location of a file and its relationship with other REST resources, such as artifacts and projects.
* **Glsstorage**: The **glsstorage resource** allocates space on the file server.
* **XML elements**: Within the XML used by the files and glsstorage resources, the **attached-to** and **content-location** URIs are used to link disk files to file-based artifacts produced by a process, or to link disk files to projects or samples.
The following diagram outlines how the XML elements link files to system resources and artifacts:
#### **Using the REST Web Service to Work with Files**
In the lab, one of the most important associations that must be made is between:
* A **file** that is the result of an instrument run
\- and -
* The **sample** that was analyzed to produce that file.
In Clarity LIMS, this association is represented by creating a process that takes a sample analyte and produces a result file.
When you run a process configured to create a result file, the process generates a placeholder for a file. To populate the placeholder, simply import the result file generated by the instrument into Clarity LIMS.
While working in the lab, lab scientists can upload result files that are used or produced while samples are processed. However, it may sometimes be more appropriate to automate this work. In these cases, you can use the REST files and the **glsstorage** **resource**.
Depending on the file storage needs and how the files are generated, there are two ways to do this process.
* Import a file and store it on the file server.
* Import a file and store it on a different server.
**Import a result file and store it on the file server:**
1. POST conforming XML to the **glsstorage resource**.
2. This action returns XML that includes a name and storage location for the file.
3. Place the file into the specified location using the file name provided in the XML.
4. POST the returned XML to the **files resource**, which links the file on disk to the result file placeholder.
**Import a result file and store it on a different server:**
1. Make sure that the file exists in the desired location.
2. POST conforming XML to the files resource, referencing the name and location of your file with the content-location element. The file path must contain the transfer protocol supported by the server. For example:\
sftp\://192.168.13.247/home/glsftp/Process/2010/10/SCH-RAA-101013-87-1/ADM53A1PS3-40-1.dat\
\
**NOTE:** It is not necessary to POST to the glsstorage resource.
#### Attaching Reference Information
If you have files that were not generated during the analysis of a sample, you can also attach reference information to projects and samples.
For example, suppose you receive an e-mail when a sample is submitted to the lab, you may want to store that information in the LIMS. In this case, when you POST XML to the **files resource**, the XML links the file to the desired submitted sample – instead of to a result file placeholder.
**Clarity LIMS v5.x and later:**
In Clarity LIMS, the file is attached to the **Sample Details** section of the **Sample Management** screen.
1. On the Projects and Samples screen, select the project containing the sample for which you have posted a result file.
* Scroll down to the **Samples and Workflow Assignment** section of the screen and select the appropriate sample.
* Select **Modify 1 Sample**.
2. On the **Sample Management** screen, scroll to the bottom of the **Sample Details** section to find the attached file.
**Before Clarity LIMS v5:**
In the Clarity LIMS web interface, the file is attached to the Sample Details section of the Sample Management screen.
* For details on accessing the file, see the previous content on Clarity LIMS v5.x and later.
In the Clarity LIMS Operations Interface, the file is attached to the Files tabbed page of the applicable submitted sample.
1. In the **Clarity LIMS Explorer**, click **Opened Projects**.
2. In the **Opened Projects** list, double-click the project containing the sample for which you have posted a result file.
3. On the project details page, click the **Samples** tab.
4. At the bottom of the tab, in the **Containers** pane, double-click the appropriate sample.
5. On the sample details page, click the **Files** tab to find the attached file.
|
Important!
Before POSTing to the files resource, make sure that the file exists in the location referenced by the content-location element. If the file does not exist in this location, the POST fails.
|
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
The REST Web Service separates the resources needed for files and file storage.
This action allows for greater control and the flexibility to apply various tracking and storage strategies. The content-location element can be used to define the file location without having to move the file. This ability is key in next-generation sequencing, which requires the management of large files, such as assemblies.
The content-location element needs to reference the file location in a storage system using a specific file transfer protocol. Currently only FTP, SFTP, and HTTP protocols are supported.
This mechanism makes file management flexible, but it maintains access to the file from REST with a single link. However, this feature must be configured by Illumina. For more information, contact the Support team.
### User-Defined fields (UDFs)
Note the following key concepts about UDFs and UDTs:
* UDFs and UDTs are configured to collect information that is important to the lab.
* With the REST Web Service, you can include UDF and UDT values in the XML representation of any individual resource that has a UDF or UDT defined.
* Not all artifacts have both UDFs and UDTs.
In Clarity LIMS v5 and later:
* The API still uses the term **udf** the term. However, in the user interface, this term has been replaced with **custom** **field**.
* UDTs are not supported.
You can configure the system to collect user-defined information. Consider the following examples:
* You can create UDFs to add options and fields to the user interface when working with samples, containers, artifacts, processes/protocol steps, and projects.
* You can also create User-Defined Types (UDTs), which are organized subsets of related UDFs. As you add and process samples, you can add information to these options and fields.
In the following example, UDFs are added to submitted samples, processes, and sample analytes (derived samples).
* For the submitted sample named Goo, there are UDFs named Type, Color, and Source.
* For the Prepare Goo process/step, there are UDFs named Reagent Lot ID, Temperature, and Cycle Time.
* The output of the Prepare Goo process/step is an analyte named Prepared Goo, which contains UDFs named Quality and Category.
{% hint style="info" %}
Any downstream sample created by running a process is considered an analyte artifact. In the Clarity LIMS interface, analyte artifacts are referred to as derived samples. For more information, see [#samples](#samples "mention"), [#artifacts](#artifacts "mention") and [#processes](#processes "mention").
{% endhint %}
**To record information for these UDFs:**
1. Add Goo to the system and populate the sample-level UDFs.
2. In Clarity LIMS, run the Prepare Goo step and complete the following actions:
* Populate the **Step Details** fields (the process-level UDFs).
* Populate the **Sample Details** table (the analyte-level UDFs).
#### Using the REST Web Service to collect UDF information
You can also use the REST Web Service to collect user-defined information for samples, containers, artifacts, and processes.
After you have configured UDFs, the XML of the appropriate resource expands with data elements for the field values. For example, the Prepared sample of goo artifact would have the following XML:
```
Prepared sample of gooAnalyteAnalyteUNKNOWN1:1trueExcellent1
```
#### Configuring UDFs / Custom Fields
UDFs/custom fields are useful for collecting data at various stages of your workflow. In next-generation sequencing, it is important to record information, such as who submitted a sample, the tested concentration of a library, the reagents that were used during library prep.
As illustrated in the previous Goo example, collect this information by adding UDFs/custom fields for the samples, artifacts, and processes resources:
* A submitted sample UDF / custom field named 'Type'
* An artifact-level UDF / derived sample custom field named 'Validated Concentration'
* A process-level UDF / master step field named 'Reagent Name'
Artifact UDFs/custom fields are flexible.
* You can configure different sets of UDFs / custom fields for the **analyte** artifact type and the **result file** artifact type.
* You can configure different sets of UDFs / custom fields based on the process type.
This flexibility means that:
* Process type / master step A can display fields 'm' and 'n' on a result file, and fields 'q' and 'r' on an analyte
* Process type / master step B can display fields 'm' and 'o' on a result file, and fields 'q' and 's' on its output analyte.
| **Process type / Master step** | **Result file field exposed** | **Analyte field Exposed** |
| ------------------------------ | ----------------------------- | ------------------------- |
| A | m, n | q, r |
| B | m, o | q, s |
Control how users access artifact-level UDFs/custom fields by configuring the type of artifact or process type/master step to which they apply.
Not every detail tracked and recorded needs a UDF. To optimize lab efficiency, it is recommended that you define an essential UDF set.
Increasing the complexity of information collected and managed does not necessarily improve operations or scientific quality. It may be more effective to store files, because the complete details are then available and secure within the attached file.
# The Life Cycle of a Sample: Stages Versus Steps
As an API programmer, it is important to understand the difference between steps and stages. This distinction is especially important because the concept of stages is hidden from the end user. As such, when receiving requirements from end users, steps sometimes means steps. At other times, steps mean stages. This article highlights the differences between these two entities.
### The Life Cycle of a Sample
We tend to think of a protocol as being a linear collection of steps, as shown below.
Figure 1
However, this illustration is not complete as the life cycle of a sample modeled within Clarity LIMS reflects what happens in reality. The workflow is broken into periods of activity and inactivity. If a workflow is comprised of three steps (A, B, and C—as shown in Figure B), Step B does not begin at the exact time that Step A is complete.
### Stages and Steps
To reflect these inactive periods, Clarity LIMS uses the concept of stages in addition to steps. A more complete representation of a workflow is shown below, with the stages occurring between the steps.
Figure 2
The following phrase simplifies this concept:
If the sample isn't active in a step, it's waiting in a stage.
**NOTE:**
The Clarity LIMS concept of the virtual ice bucket is another state that occurs when a sample leaves a stage, but work on the step has not started. This scenario is represented in the Figure 3, with the virtual ice bucket appearing between stages and steps, as the sample moves from left to right. However, virtual ice buckets are largely irrelevant to this discussion. While recognizing their existence, they are discounted from further explanation.
Figure 3
Having simplified our model of a sample passing through a workflow to resemble Figure 2, we can now add the next layer of complexity.
Protocols are components of workflows. As such, it is easy to imagine two or more workflows sharing a protocol. This detail leads to the following summary:
Steps belong to protocols, whereas stages belong to workflows.
This summary means that the stages that exist between steps are part of the workflow (represented in Figure 4 below). For example, samples passing through Workflow O proceed through Step A, Stage X, Step B, Stage Y, and Step C.
Samples passing through Workflow P (which shares the protocol with Workflow O) pass through the same steps. However, samples pass through a different set of stages (Stage X' and Stage Y').
Figure 4
### Why Stages Are Important
Looking at the counts of samples associated with steps in a protocol (for example, in the Lab View dashboard in Clarity LIMS), the number of samples awaiting a particular step is actually the total number of samples across all relevant stages that feed into the step.
For bioinformaticians and programmers who are using the Clarity LIMS API, stages have an additional function. Route samples in ways that vary from the expected, linear route by manipulating which stages the artifacts are in. For example, using the API via a script, do the following actions:
* Implement a forking workflow by assigning artifacts to one (or more) additional stages.
* Create iterative (or looping) workflows by routing artifacts to an earlier stage for additional work.
# Understanding API Terminology (LIMS v5 and later)
The following table shows how API terminology maps to terminology used in the Clarity LIMS v5.x interface.
API Terminology
Clarity LIMS Terminology
Notes
Analyte
Derived sample
Not applicable
Artifact
An item that is input to or generated by a step. Derived samples and measurements are both artifacts.
Not applicable
Lab
Account
Accounts are not fully supported in the Clarity LIMS v5.x web interface. However, lab is supported in the API.
Process
Step
step and process both exist in the API. While related, they are not synonyms and have different uses.
Process type
Master step
Not applicable
Researcher
Client or user
Not applicable
Resultfile
Measurement or file / file placeholder
A file could be a log file that is shared across all samples in the step or a file that belongs to a single sample, such as an Electropherogram.
Sample
Submitted sample
The original sample submitted to the system.
UDF
Custom field
User-defined types (UDTs) are not supported in the Clarity LIMS v5.x web interface. However, udt is supported in the API.
See also the *Terms and Definitions* section.
# Automation
## Overview
To trigger scripts and third-party programs from the BaseSpace Clarity LIMS user interface, use command-line calls configured in step automations.
There are many ways to use automation in Clarity LIMS. Consider the following examples:
* Automate sample tracking and enhance the information recorded.
* Generate and attach specially-formatted text files.
* Simplify data entry.
* Automate the population or updating of data fields and data files.
Before using automation, become familiar with the topics discussed in this article and understand how automation functionality interacts with users, Clarity LIMS, and REST.
As of BaseSpace Clarity LIMS v5.0, several terms have been deprecated:
* **External Program Integration Plug-in (EPP)** has been replaced with **automation**
* **Automated Informatics (AI) node** has been replaced with **Automation Worker (AW) node**
* **Parameter** has been replaced with **token**
### Common applications of automation
Automation scripts are often used to automatically create and attach specially-formatted text files, such as the following:
* Files containing sample lists (sometimes called instrument driver files). Users can import these driver files into control software, saving time and ensuring accurate sample processing.
* Barcode or label files. These are specially-formatted files that can be supplied to barcode software systems to allow users to print out container labels.
* Summary analysis results - for example, from alignment or molecular identification and quantification algorithms.
The two common applications of automation are:
* To create files and attach them to process output placeholders.
* To update data fields with information created during data analysis.
Scripts triggered by automation also use REST to update information directly within the REST resources.
For details, see [REST Web Services](/clarity-lims/api-and-database/api-docs/rest/rest-web-services) and the version-specific documentation in the following sections:
* [Automation Tokens](/clarity-lims/api-and-database/api-docs/automation/automation-tokens)
### How Users Trigger Scripts
Record lab work in Clarity LIMS by running steps on samples. These steps may be configured in Clarity LIMS by an administrator.
Most steps can be configured with an automation trigger that invokes an external script. The script may include fixed and variable information parameters/tokens on the command line.
**NOTE:** As of Clarity LIMS v5.0, the term command-line **parameter** has been replaced with **token**.
### Configuring Processes / Steps to Trigger Scripts
After an AI/AW node is installed, processes (in Clarity LIMS v4.2 and earlier) or steps (Clarity LIMS v5 and later) must be configured to call out to it.
This configuration is executed by the Clarity LIMS administrator:
* In Clarity LIMS v4.2 and earlier, execute configuration in the Operations Interface process configuration dialog on the External Programs tab.
* In Clarity LIMS v5 and later, execute configuration on the Automation configuration screen.
When configuring an automation, the following must be defined:
* **Name**
* **Channel**
* **Command line call**
* **Trigger style and location** (see also [Automation Triggers and Command Line Calls](/clarity-lims/api-and-database/api-docs/automation/automation-triggers-and-command-line-calls))
**NOTE**: Only a brief summary of automation configuration is provided here. This material should be familiar from the Clarity LIMS administration training.
### Configuring Scripts that are Called by Automation
Scripts or third-party programs are called using the operating system command line. They must meet the following requirements:
* Be callable on the command line and, preferably, be able to read and respond to command-line parameters.
* Be accessed by the user account running the automation, with appropriate permissions and disk locations.
* Exit with appropriate exit codes, otherwise the automation may record the script completed with an error.
### How Information Flows Between a User and a Script
* [#howeppinteractswithusersclaritylimsandrest-step1-auserrunsaprocess](#howeppinteractswithusersclaritylimsandrest-step1-auserrunsaprocess "mention")
* [#howeppinteractswithusersclaritylimsandrest-step2-servercreatesthenewprocess](#howeppinteractswithusersclaritylimsandrest-step2-servercreatesthenewprocess "mention")
* [#h\_093e28e0-b22b-4fd4-b013-c35de96340cd](#h_093e28e0-b22b-4fd4-b013-c35de96340cd "mention")
* [#howeppinteractswithusersclaritylimsandrest-step4to7-theexternalprogramexecutesoptionallycallingrestr](#howeppinteractswithusersclaritylimsandrest-step4to7-theexternalprogramexecutesoptionallycallingrestr "mention")
* [#howeppinteractswithusersclaritylimsandrest-step8-theeppreturnsoptionallyattachingcreatedfiles](#howeppinteractswithusersclaritylimsandrest-step8-theeppreturnsoptionallyattachingcreatedfiles "mention")
* [#howeppinteractswithusersclaritylimsandrest-step9-theusercanaccessupdatedresults](#howeppinteractswithusersclaritylimsandrest-step9-theusercanaccessupdatedresults "mention")
The following diagram illustrates what happens when a user runs a step in the LIMS.
#### Step 1 - A User Runs a Step
The lab scientist tracks activities by running a step in Clarity LIMS. The step is configured to display a button that invokes the configured automation script.
#### Step 2 - Server Creates the New Process / Step
**NOTE**: As of Clarity LIMS v5.0, the term **parameter** has been replaced with **token**.
#### Common applications of automation
The application server creates a new step, which is much like POSTing to the processes resource of the REST API. The server resolves any parameters/tokens found in the string and sends the resolved command-line string to the automation.
In this example, two of the most common parameters/tokens used when working with automation are discussed:
* **{processURI:version:scheme}**—This parameter/token passes the REST API URI of the step that issued the command-line string.
* **{ouputFileN}**—This parameter/token passes the LIMS ID of the specified expected output file of the step that issued the command-line string. You can use 0 (zero) for the first file, 1 (one) for the second file, etc.
For more information about the parameters/tokens available for use, refer to the articles in the following API documentation sections:
* [Automation Tokens](/clarity-lims/api-and-database/api-docs/automation/automation-tokens)
**NOTE**: As of API v1 r12, the version and scheme values for {processURI:version:scheme} are automatically populated, based on the REST version and protocol of the deployed server.
#### Step 3 - The Automation Invokes the Operating System Shell Command
The automation program receives the command-line string from the application server. It may also receive other process(step)-related information, such as temporary files. The command-line string is executed by the operating system of the host computer.
#### Steps 4 to 7 - The External Program Executes (Optionally Calling REST Resources)
The automation can work with any third-party program that supports command-line parameters/tokens. The program may simply create files or it may manipulate information directly via the REST API (steps 5 and 6).
Simple automation operation does not require anything of the REST API. If a third-party program creates files that users would like brought back into Clarity LIMS, scripts should use the outputFileN parameter/token to specify that the program create file names that are expected by the client. The files are placed in a temporary local working directory and automatically imported into the client. With this method, the automation automatically handles many of the things that would need manually scripts using the REST API processes, artifacts, files, and glsstorage resources.
For more complicated scenarios, you may want to use automation with the REST API. This situation is where the processURI parameter/token is used. A GET request on the URI of the step that issues the command-line string provides all the information recorded by the user. This information includes links to the analytes (samples) used as inputs. The script can then use other REST API resources to create or update information.
On completion, the third-party program exits (step 7). Standard shell exit codes apply: zero (0) equals successful completion.
#### Step 8 - The Automation Returns (Optionally Attaching Created Files)
On exit of the third-party program, the automation software updates the application server. If the system finds files with names that match the file placeholders produced by a process/step, the files are uploaded to the file server and attached to the appropriate placeholders.
A nonzero exit code sets a flag on the step, indicating that there is an error.
#### Step 9 - The User Accesses Updated Results
With updates complete, the application server sends refresh events to the Clarity LIMS. The user will see that files have been uploaded.
### Verifying Automation Scripts
Verifying and testing scripts is an important part of working with automation. Remember that there are three software components:
* The server
* The automation instance (calling scripts)
* The script
The best way to debug scripts is to unit test each component separately. For example a logical order to work on a script is as follows:
1. Define and test the REST calls required in a web browser.
2. Define the command-line parameters / tokens sent to the automation at step completion.
3. Test the script running just from the command line.
4. Test automation calls to the script at step completion by running the step from the LIMS interface.
### Installing an Automation Worker / AI Node
Before the system can use the automation, a system administrator installs one or more automation workers / AI nodes within the lab network. The installation typically occurs on the server that contains the script program, or third-party application, to be integrated.
The installer program is contained in the **Automated Informatics** / **Automation Worker** software package.
# Automation Channels
The automation and integration of the day-to-day work in the lab requires different Automated Informatics (AI) nodes/automation workers to perform different tasks.
For BaseSpace Clarity LIMS v5.0, several terms are deprecated:
* Automation replaced External Program Integration Plug-in (EPP).
* Automation Worker (AW) node replaced EPP/AI node.
### Specifying Channels
Channels are manually named, and ideally clearly represent the task performed (eg. Type\_2\_Analysis). To make sure that dispatched automation work is routed to the correct destination, specify a channel in the following places:
* On the AI node / automation worker
* Clarity LIMS v5 and later: When configuring step and derived sample automations on the Automation tab
### How Channels Work
1. When the automation trigger conditions are met in the LIMS, the automation job first enters a channel-specific 'first in, first out' (FIFO) queue of work for completion.
2. Jobs queue in this channel until one of the AI nodes/automation workers operating on the channel completes its previous work, and indicates it is free to accept more.
3. The next job is then dispatched from the channel queue to the node. This strategy allows a single channel queue to receive service by one, or many, AI nodes/automation workers servicing the specified channel.
It is possible to have multiple AI nodes/automation workers performing the same type of work all configured on the same channel, allowing a simple but effective way to increase throughput of a particular analysis bottleneck, or to ensure redundancy during a single node failure.
# Automation Execution Environment
As of BaseSpace Clarity LIMS v5.0, several terms have been deprecated:
* **External Program Integration Plug-in (EPP)** has been replaced with **automation**
* **EPP/AI node** has been replaced with **automation worker / AW node**
* **Parameter** has been replaced with **token**
* **User defined field (UDF)** has been replaced with **custom field**
When a job is dispatched to the AI node/automation worker, the following steps occur:
1. A temporary working directory is created on the AI node / automation worker:
* In **AIInstallDirectory/temp/**
* With a unique name including the client process LIMS ID.
2. The command configured and selected as part of the step run in the LIMS is then sent to the AI node / automation worker, with any specified parameters / tokens replaced with actual values.
3. The command is executed on the AI node / automation worker, spawning step execution using the temporary working directory as the working directory context.
* Script processing can use stdout, stderr, and return codes following standard shell programming packages.
4. When the script exits, the AI node/automation worker automatically retrieves any files with matching LIMS IDs from the temporary working directory. The files are attached to the appropriate output file placeholders.
### How the API Infrastructure is Used
The automation API infrastructure can be used alone or with the REST API infrastructure.
For example:
* Simple scripts can use automation parameters/tokens and data files directly from the current working directory. They can write results back to the current working directory, associating them back to the relevant placeholders in Clarity LIMS.
* More advanced scripts can also use the REST API infrastructure to retrieve additional required information and place relevant data back into UDFs/custom fields. Advanced scripts can also attach and associate data files to placeholders, which may be in different locations, while the script is still running.
# Automation Testing
Use the `setExitStatus.py` Python script, attached to this page, to test and simulate the use of the automation triggers within Clarity LIMS.
{% hint style="info" %}
The `setExitStatus.py` script is designed to illustrate concepts for API training purposes. Do not use in a production environment.
The `setExitStatus.py` script relies on the presence of the `glsapiutilv2.py` script. Typically, both scripts are located in the same directory.
{% endhint %}
The `setExitStatus.py` script uses the following command-line parameters:
-u {user}
LIMS username
-{password}
LIMS password
-l {stepURI}
LIMS stepURI—the URI of the transient step API resource that invokes the script.
-s {status}
The status the script is reporting (OK, WARNING, or ERROR).
-m {message}
The descriptive message displayed to the user.
An example of a parameter string that invokes this script from Clarity LIMS is provided in the following. Note the use of the stepURI token in the -l parameter.
`python /opt/gls/clarity/customextensions/setExitStatus.py -l {stepURI:v2:http} \`
`-u {username} -p {password} -s "OK" -m "successful"`
#### Attachments
glsapiutilv2.py:
{% file src="/files/ieBAoV4B9w8sp2twKUjC" %}
setExitStatus.py.txt:
{% file src="/files/MCR65ldlLf1B4Ge1CkzF" %}
The latest glsapiutil (and glsapiutil3) Python libraries can be found on the [GitHub](https://github.com/Illumina/BaseSpace_Clarity_LIMS) page.
# Automation Tokens
This section provides information to help you work with Clarity LIMS automation tokens in Clarity LIMS v5 and later.
* [Derived Sample Automation Tokens](/clarity-lims/api-and-database/api-docs/automation/automation-tokens/derived-sample-automation-tokens)
* [Step Automation Tokens](/clarity-lims/api-and-database/api-docs/automation/automation-tokens/step-automation-tokens)
* [Project Automation Tokens](/clarity-lims/api-and-database/api-docs/automation/automation-tokens/project-automation-tokens)
---
[Next Page](/llms-full.txt/1)
Important!