User Interaction, Validation and Troubleshooting
This section explains how to validate the installation of the Illumina NovaSeq 6000 Integration Package v3.7.0.
The validation process involves the following items:
Running samples through the Library Prep Validation workflow.
The workflow contains a single-step protocol that models the library prep required to produce normalized libraries. At the end of the step, the normalized libraries advance to the workflow selected.
Running normalized libraries through the NovaSeq 6000 v3.8 workflow validates the following items:
Successful routing of samples from the Run Format (NovaSeq 6000 v3.8) step to the NovaSeq Standard (NovaSeq 6000 v3.8) or NovaSeq Xp (NovaSeq 6000 v3.8) step.
Automated generation of v1 sample sheet for use with bcl2fastq2 v2.20 analysis software or v2 sample sheet. This file automatically uploads to the sequencing system via the Sequencer API.
Automatic validation of run setup information. Information is uploaded to the NovaSeq Control Software (NVCS) via the Sequencer API and is used to create the run recipe and initiate the run.
Automated tracking of the NovaSeq sequencing run and parsing of run statistics into Clarity LIMS, via the Sequencer API.
The validation steps assume that the Illumina NovaSeq 6000 Integration Package v3.7.0 is installed and you have imported the default Clarity LIMS configuration.
Activate Workflow, Create Project, Add and Assign Samples
The following steps set up Clarity LIMS in preparation for running samples through the Library Prep Validation and NovaSeq 6000 v3.8 workflows.
On the Configuration tab, under Workflows, activate both the Library Prep Validation and NovaSeq 6000 v3.8 workflows.
On the Projects and Samples screen, create a project and add samples to it.
Assign the samples to the Library Prep Validation workflow.
Library Prep Protocol: Library Prep Validation v2.3.4
This single-step protocol models the library prep required to produce normalized libraries that are ready for the NovaSeq 6000 v3.8 workflow.
Follow the steps in Library Prep Validation Protocol to run the Library Prep Validation workflow with the following:
Label Group = TruSeq HT Adapters v2 (D7-D5)
Sequencing Instrument = NovaSeq 3.0
On exit from the step, the Routing Script automation is triggered. This automation assigns samples to the first step of the NovaSeq 6000 v3.8 workflow, Define Run Format (NovaSeq 6000 v3.8). This step is the only one in Protocol 1: Run Format (NovaSeq 6000 v3.8).
Protocol 1: Run Format (NovaSeq 6000 v3.8)
This protocol includes a single step, Define Run Format (NovaSeq 6000 v3.8). The step allows for the assignment of per sample values for Loading Workflow Type, Normalized Molarity, Flowcell Type, and Final Loading Concentration (pM). At the end of the step, samples are routed to the NovaSeq Standard or NovaSeq Xp protocol, according to the selected Loading Workflow Type.
Step 1: Define Run Format (NovaSeq 6000 v3.8)
In Lab View, locate the Run Format (NovaSeq 6000 v3.8) protocol. The samples are queued for the Define Run Format (NovaSeq 6000 v3.8) step.
Add the samples to the Ice Bucket and select View Ice Bucket.
On the Ice Bucket screen, select Begin Work.
On the Record Details screen in the Sample Details table, populate the following fields (values can vary across samples):
Loading Workflow Type — Select NovaSeq Standard or NovaSeq Xp from the drop-down list.
Flowcell Type — Select SP, S1, S2, or S4.
Final Loading Concentration (pM) — Select from the two preset options: 225 (for PCR-free workflows), 400 (for Nano workflows), or enter a different value.
Normalized Molarity (nM) — These values are copied over from the previous step. If this column is not populated during library prep, enter the values here.
Select Next Steps, which triggers the Set Next Steps automation and the following actions:
Sets the value of the next step (for all samples) to Remove from workflow. The Routing Script automation expects this value and requires it to advance samples to the next step.
Calculates the Minimum Molarity.
Checks Normalized Molarity value. For samples with no Normalized Molarity value (an empty value not including 0), generates an error message notifying that the field cannot be empty.
Compares each sample Normalized Molarity value with the Minimum Molarity value.
On the Assign Next Steps screen:
In the Sample Details table, the Next Step for all samples is prepopulated with Remove from workflow, regardless of the Loading Workflow Type.
For samples whose Normalized Molarity value is lower than the Minimum Molarity value, the Loading Workflow Type is set to Remove from workflow. Also, a message is recorded in the Warning field for the sample.
At this point, there are two options:
Return to the Record Details screen and adjust the Normalized Molarity value so that it equals or exceeds the Minimum Molarity value. The Loading Workflow Type must be set to NovaSeq Standard or NovaSeq Xp, as applicable.
Complete the protocol without correcting the Normalized Molarity value. In this case, the samples in question are removed from the Clarity LIMS workflow.
Select Finish Step. The Routing Script & Register Step Completed automation is triggered:
Samples whose Loading Workflow Type is set to Remove from workflow are removed from the Clarity LIMS workflow. (Occurs when the Normalized Molarity value is lower than the Minimum Molarity.)
Samples whose Loading Workflow Type is set to NovaSeq Standard are routed to the Make Bulk Pool for NovaSeq Standard (NovaSeq 6000 v3.8) step. This step is the first one in the NovaSeq Standard protocol.
Samples whose Loading Workflow Type is set to NovaSeq Xp are routed to the Make Bulk Pool for NovaSeq Xp (NovaSeq 6000 v3.8) step. This step is the first one in the NovaSeq Xp protocol.
Protocol 2: NovaSeq Standard (NovaSeq 6000 v3.8)
In this protocol, samples are pooled and added to the library tube in preparation for the NovaSeq run.
Step 1: Make Bulk Pool for NovaSeq Standard (NovaSeq 6000 v3.8)
In Lab View, locate the NovaSeq Standard (NovaSeq 6000 v3.8) protocol. Samples for the Make Bulk Pool for NovaSeq Standard (NovaSeq 6000 v3.8) step are queued.
On the Queue screen, add samples of the same Flowcell Type to the Ice Bucket and select View Ice Bucket.
On the Ice Bucket screen, select Begin Work.
On the Pooling screen:
Create a pool by dragging samples into the Pool Creator.
Enter a name for the pool or accept the default name (Pool #1).
Select Record Details.
After exiting from the Pooling screen, the Validate Inputs Flowcell Type and Single Pool automation is triggered. The automation verifies the following items:
All samples in the pool have been assigned the same Flowcell Type.
Only one pool has been created.
On the Record Details screen in the Step Details area, complete the two required fields and one optional field, as needed:
Number of Flowcells to Sequence — Used in volume calculations, to make sure that the volumes are sufficient for the number of times the pool is sequenced.
Minimum Per Sample Volume (ul) — Used to calculate how much of each sample is included in the pool. The field is prepopulated with the configured default value 5 µl, but can be edited.
% PhiX (2.5 nM) Spike-In — Used to calculate the volume of PhiX v3 control included in the pool for the given percentage of spike-in. The field is optional and can be edited.
If the smallest Per Sample Volume (ul) value is < 5, Clarity LIMS automatically assigns a value of 5 to the Adjusted Per Sample Volume (ul) field.
Clarity LIMS changes the Adjusted Per Sample Volume (ul) field value for all other samples in the batch, based on the ratio used to increase the lowest value to 5.
In the Sample Details table, select the pool icon to view details on the pool composition.
Select Calculate Volumes to trigger the Calculate Volumes automation. This automation performs calculations based on the selected Flowcell Type, then generates and attaches the Calculation File (CSV) to the step. This file contains volume information about the pool and the individual samples that it contains.
Select Next Steps to trigger the Set Next Steps automation. This automation sets the next step for samples to ADVANCE and advances them to the next step in the protocol, Dilute, and Denature (NovaSeq 6000 v3.8).
On the Assign Next Steps screen, the next step for samples is set to the next step in the workflow: Dilute and Denature (NovaSeq 6000 v3.8).
Select Finish Step.
At the end of this step, the pool of samples automatically advances to the Dilute and Denature (NovaSeq 6000 v3.8) step.
Step 2: Dilute and Denature (NovaSeq 6000 v3.8)
In Lab View, locate the NovaSeq Standard (NovaSeq 6000 v3.8) protocol. The pool of samples queued for the Dilute and Denature (NovaSeq 6000 v3.8) step are listed.
Add the samples to the Ice Bucket and select View Ice Bucket.
On the Ice Bucket screen, select Begin Work. The Validate Single Input & Register Step Started automation is triggered. This automation verifies that only one container is input for the step.
On the Placement screen:
Drag the pool into the library tube in the Placed Samples area.
Scan or type the barcode of the library tube into the Library Tube field.
Select Record Details.
After exiting the Placement screen, the Validate Library Tube Barcode automation makes sure that the library tube barcode conforms to the barcode mask [A-Z]{2}[0-9]{7}-[A-Z]{3}. If it does not, an error message displays. The automation also copies the Flowcell Type and Loading Workflow Type values from step inputs to outputs.
On the Record Details screen, the Reagent Lot Tracking section lets you tracks the NaOH, Resuspension Buffer, and Tris-HCl reagents used in the step. Add and activate lots for these reagents. For more information on creating a new lot, refer to Add and Configure Reagent Kits and Lots in the Clarity LIMS (Clarity & LabLink Reference Guide) documentation.
In the Reagent Lot Tracking section, select from the active lots displayed in each drop-down list.
The fields displayed on the Record Details screen are used to set up the run and generate the sample sheet. Some of these fields are autopopulated and some must be completed manually.
Fields Displayed on Record Details Screen of Dilute and Denature (NovaSeq 6000 v3.8)
On the Record Details screen, select Validate Run Setup and Generate Sample Sheet. This selection triggers the automation script, which performs the following actions:
Validates the parameters entered on the Record Details screen.
Generates the sample sheet and attaches it to the placeholder in the Files area of the Record Details screen.
Select Next Steps.
On the Assign Next Steps screen, the Next Step for samples is prepopulated with Remove from workflow. The Routing Script automation expects this value, and requires the value to advance samples to the next step.
Select Finish Step.
After exiting the step, the following actions occur:
The Routing Script & Register Step Completed automation is triggered and samples are routed to AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8).
In Lab View, the pool of samples is queued for the AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8) step.
At this point in the workflow, the user interaction ends. Proceed to AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8).
Protocol 3: NovaSeq Xp (NovaSeq 6000 v3.8)
In this protocol, samples are pooled and added to lanes on the NovaSeq flow cell. The option selected in the Define Run Format (NovaSeq 6000 v3.8) step determines the flow cell type.
Step 1: Make Bulk Pool for NovaSeq Xp (NovaSeq 6000 v3.8)
In Lab View, locate the NovaSeq Xp (NovaSeq 6000 v3.8) protocol. The samples are queued for the Make Bulk Pool for NovaSeq Xp (NovaSeq 6000 v3.8) step.
On the Queue screen, add samples of the same Flowcell Type to the Ice Bucket and select View Ice Bucket.
On the Ice Bucket screen, select Begin Work.
On the Pooling screen, create and name a pool as follows.
Create a pool by dragging samples into the Pool Creator.
Enter a name for the pool or accept the default name (Pool #1).
Select Record Details.
On exiting the Pooling screen, the Validate Inputs Flowcell Type and Single Pool automation is triggered. The automation verifies the following items:
All samples in the pool are assigned the same Flowcell Type.
Only one pool was created.
On the Record Details screen in the Step Details area, complete the two required fields and one optional field, as needed:
Number of Lanes to Sequence — Used in volume calculations to make sure that volumes are sufficient for the number of times the pool is sequenced.
Minimum Per Sample Volume (ul) — Used to calculate how much of each sample is included in the pool. The field is prepopulated with the configured default value 5 µl, but can be edited.
% PhiX (0.25nM) Spike-In — Used to calculate the volume of PhiX v3 control to be included in the pool for the given percentage of spike-in. The field is optional and can be edited.
If the smallest Per Sample Volume (ul) value is < 5, Clarity LIMS automatically assigns a value of 5 to the samples Adjusted Per Sample Volume (ul) field.
Clarity LIMS then adjusts the Adjusted Per Sample Volume (ul) field value for all other samples in the batch. This adjustment is based on the ratio used to increase the lowest value to 5.
In the Sample Details table, select the pool icon to view details on the pool composition.
Select Calculate Volumes. This selection triggers the Calculate Volumes automation. This automation performs calculations based on the selected Flowcell Type, then generates and attaches the Calculation File (CSV) to the step. This file contains volume information about the pool and the individual samples that it contains.
Select Next Steps to trigger the Set Next Steps automation. This automation performs the following actions:
Copies the Flowcell Type values from the step inputs to the step outputs.
Sets the next step for samples to ADVANCE, advancing them to the Dilute, Denature & ExAmp (NovaSeq 6000 v3.8) step in the protocol.
On the Assign Next Steps screen, the next step for samples is set to the Dilute, Denature & ExAmp (NovaSeq 6000 v3.8) step in the workflow.
Select Finish Step.
At the end of this step, the pool of samples automatically advances to the Dilute, Denature & ExAmp (NovaSeq 6000 v3.8) step.
Step 2: Dilute, Denature & ExAmp (NovaSeq 6000 v3.8)
In Lab View, locate the NovaSeq Xp (NovaSeq 6000 v3.8) protocol. The pool of samples queued for the Dilute, Denature & ExAmp (NovaSeq 6000 v3.8) step displays.
Add the pool to the Ice Bucket and select View Ice Bucket.
[Optional] On the Ice Bucket screen, set the number of derivatives to create (placed into the flow cell lanes) and select Begin Work.
On entry to the Record Details screen, the Calculate Volumes automation is triggered. This automation sets the following values based on the selected Flowcell Type:
BP Aliquot Volume (ul)
NaOH Volume (ul)
Tris-HCl Volume (ul)
DPX1 Volume (ul)
DPX2 Volume (ul)
DPX3 Volume (ul)
Mastermix per Lane (ul)
The automation also populates the Flowcell Type and Loading Workflow Type columns of the Sample Details table.
The automation also generates the Calculation File (CSV) and attaches it to the step. This file contains information about the DPX Mastermix volume and the volume of Mastermix, NaOH, and Tris-HCl to add per working pool (see the next step).
On the Record Details screen, the Reagent Lot Tracking section tracks the DPX1, DPX2, DPX3, NaOH, Resuspension Buffer, and Tris-HCl reagents used in the step. These reagents must be added. To add and activate reagent lots, refer to Add and Configure Reagent Kits and Lots in the Clarity LIMS (Clarity & LabLink Reference Guide) documentation.
On the Record Details screen:
In the Reagent Lot Tracking section, select from the active lots displayed in each drop-down list.
In the Step Details area, the DPX1, DPX2, and DPX3 reagent volume values are prepopulated. The script sets the values and they are not editable.
In the Sample Details table, select the pool icon to view details on the working pool composition.
The BP Aliquot, Mastermix per lane, NaOH, and Tris-HCl volume values for each working pool are populated. The script sets the values and they are not editable.
The Flowcell Type and Loading Workflow Type columns are populated.
The working pool number is appended to the bulk pool name, to identify which working pools are derived from the same bulk pool.
In the Files area, select the Calculation File (CSV) to open it and view details on the DPX Mastermix volume and the volume of Mastermix, NaOH, and Tris-HCl to add per working pool.
Select Next Steps. On the Assign Next Steps screen, the next step is already set to Load to Flowcell (NovaSeq 6000 v3.8).
Select Finish Step.
Step 3: Load to Flowcell (NovaSeq 6000 v3.8)
On the Ice Bucket screen:
In the Container Options panel, select the appropriate flow cell type from the Destination Container drop-down list.
Select Begin Work.
The Validate Inputs and Selected Container & Register Step Started automation checks the following:
The Flowcell Type field is set to a valid value (SP, S1, S2, or S4) and that each input has the same value for the field.
The container type selected matches the value in the Flowcell Type field.
The number of outputs matches the number of lanes on the selected flow cell type. If validation fails, an error message reports the number of working pools does not match the number of lanes available on the flow cell.
On the Placement screen:
Drag one or more pools from the left of the screen over into the Placed Samples area on the right.
Scan or type the barcode of the flow cell into the Flowcell field.
Select Record Details.
After exiting the Placement screen, the Validate Flowcell Barcode automation makes sure that the container barcode conforms to the barcode mask for the selected Flowcell Type (as listed in the following table). This automation also copies the Flowcell Type and Loading Workflow Type field values from step inputs to outputs.
The fields displayed on the Record Details screen are used to set up the run and generate the sample sheet. Some of these fields are autopopulated and some must be entered manually. For details, refer to the following table:
Fields Displayed on Record Details Screen of Load to Flowcell (NovaSeq 6000 v3.8) Step
Select Validate Run Setup and Generate Sample Sheet to trigger the automation script, which does the following:
Validates the parameters entered on the Record Details screen.
Generates the sample sheet and attaches it to the placeholder in the Files area on the Record Details screen.
Select Next Steps.
On the Assign Next Steps screen, the Next Step field for samples is prepopulated with Mark protocol as complete.
Select Finish Step.
At this point in the workflow, the user interaction ends. The flow cell is queued for the AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8) step.
Protocol 4: AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8)
This protocol contains a single fully automated step - AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8).
The integration starts the step automatically and data from the run is parsed back into Clarity LIMS. User interaction is not required, but the various stages can be reviewed in Clarity LIMS under Review Run Data.
Automations
The NovaSeq Run (NovaSeq 6000 v3.8) step contains two automations:
Set Next Steps — This automation is disabled (Set to Not Used). By default, the Sequencer API is used to set the next step for output samples.
Update Lane Number — This automation is triggered automatically upon entry to the Record Details screen.
Review Run Data
Read summary metrics are recorded for the library pool. After the run is complete, open the step and review these metrics on the Next Steps screen in the Step Data section and the Sample Details table.
Step Data Section
The following values populate in the master step fields:
Run ID
Run Status
Output Folder
Current Cycle
Current Read
Loading Workflow Type
Flow Cell ID
Flow Cell Side
Flow Cell Mode
Flow Cell Part Number
Flow Cell Lot Number
Flow Cell Expiration Date
Instrument ID
Instrument Type
Instrument Control Software Version
Firmware Version
RTA Version
Sequencing Log
Sample Details Table
Summary metrics populate the global fields listed. Values are aggregated across all lanes. Some values (for example Yield PF (Gb) R1) are summed, while others are averaged.
Yield PF (Gb) R1
Yield PF (Gb) R2
Reads PF (M) R1
Reads PF (M) R2
Cluster Density (K/mm^2) R1
Cluster Density (K/mm^2) R2
%PF R1
%PF R2
% Bases >=Q30 R1
% Bases >=Q30 R2
Intensity Cycle 1 R1
Intensity Cycle 1 R2
% Phasing R1
% Phasing R2
% Prephasing R1
% Prephasing R2
% Aligned R1
% Aligned R2
% Error Rate R1
% Error Rate R2
How the Integration Works
The following steps summarize how the Sequencer API integration works. For details on sample sheet generation and the sequence of events involved in the NovaSeq run, refer to NovaSeq 6000 Integration v3.7.0 Configuration.
When setting up a run on the NovaSeq 6000 instrument, NVCS sends a request for the run recipe.
The Sequencer API validates that samples and containers are correctly queued for the AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8) step.
Clarity LIMS sends a JSON response to NVCS. The response includes the run recipe information and a link to download the sample sheet (used with analysis software such as bcl2fastq2).
When the run starts, NVCS sends a RunStarted run status request. The Sequencer API then does the following:
Validates reagent kit information in the RunStarted request:
Verifies that the reagent kit exists. If the reagent kit does not exist, the Sequencer API creates and enables it on the master step.
Verifies that the reagent kit is activated. If the reagent kit is not active, the Sequencer API activates it.
Initiates the step for the queued samples. The step produces one output file placeholder per lane of the flow cell in use, based on the flow cell type.
Records all relevant information from the RunStarted request on the step (such as reagent lots and step fields).
At the end of the run, NVCS sends one of the following run status requests:
RunCompletedSuccessfully
RunEndedByUSer
RunErroredOut
The Sequencer API updates the step with any new information, which includes only the status and cycle/read information.
After primary analysis completes, NVCS sends a request containing the parsed run metrics. NVCS sends a request only when the run completed successfully, but the API does not make this assumption and accepts the request regardless of status. The Sequencer API then does the following actions:
Records the metrics into the fields on file placeholder outputs in the LIMS.
Completes the step in Clarity LIMS when the status is RunCompletedSuccessfully. For all other status options, the step remains in progress. This action is the default autocomplete step behavior. For details, refer to NovaSeq 6000 Integration v3.7.0 Configuration.
Sample sheet generation and contents
NovaSeq 6000 run
User authentication and login
Run recipe contents
Troubleshooting
If an automation trigger does not appear to run its corresponding scripts, refer to the following sections in the Clarity LIMS API documentation:
Troubleshooting Automated Worker in the Clarity LIMS (Clarity & LabLink Reference Guide) documentation.
Troubleshooting Automation in the Clarity LIMS (API & Database) documentation.
If an error occurs that does not provide direction on how to proceed, complete the following steps:
Confirm the version of the installed Illumina NovaSeq 6000 Integration Package by running the following command on the Clarity LIMS server command line:
If the error is related to the AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8) step, review the log file information. For details, refer to Logging.
If the automated run step starts but does not complete, proceed as follows.
Use one of the following methods to open the in progress step in Clarity LIMS:
Log in to the default user account.
In Lab View, find the step in the Recent Activities pane.
Search for the step in Clarity LIMS, using either the Library Tube, or Flowcell barcode as the search term. The steps depend on whether the search is a NovaSeq Standard or NovaSeq Xp run.
On the Record Details screen, the Sequencing Log multiline text field contains logging information. If you are unable to reach the Record Details screen, or if the Sequencing Log field does not contain enough information to resolve the issue, review the sequencer-api.log file. For details, refer to Logging.
Contact Illumina Support. Provide the relevant information from the troubleshooting steps already performed.
Logging
In addition to updating the Sequencing Log multiline text field on the AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8) step, the Sequencer API writes a detailed log file to the following location:
Log messages include the Library Tube ID and Flowcell ID whenever the messages are related to a sequencing run-related request. In the LIMS workflows, these IDs are recorded as container names.
Some log messages are not directly related to a sequencing run request, such as downloading the sample sheet. In this case, the file LIMS ID and file name are included in log messages. The sample sheet downloaded by the sequencing system has a name that includes the sequencing container ID (Library Tube for Standard or Flowcell for Xp). The relevant container name search finds most the log messages for this request. However, if all messages for downloading a file are found, the LIMS ID of the file must be known. The LIMS ID is found in the Clarity LIMS API and, for sample sheets used in a run, in the recipe response (also included in the log file).
Example lines from the log file:
Last updated