User Interaction, Validation and Troubleshooting
This section explains how to validate the installation of the Illumina NovaSeqDx Integration Package v1.3.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 NovaSeqDx v1.2 workflow validates the following items:
Successful routing of samples from the Run Format (NovaSeqDx v1.2) step to the NovaSeqDx Standard (NovaSeqDx v1.2) or NovaSeqDx Xp (NovaSeqDx v1.2) step.
Automated generation of 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 6000Dx Operating Software (NVOS) via the Sequencer API and is used to create the run recipe and initiate the run.
Automated tracking of the NovaSeq 6000Dx sequencing run and parsing of run statistics into Clarity LIMS, via the Sequencer API.
The validation steps assume that the NovaSeqDx Integration Package v1.3.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 v2.3.4 and NovaSeqDx v1.2 workflows.
On the Configuration tab, under Workflows, activate both the Library Prep Validation v2.3.4 and NovaSeqDx v1.2 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 NovaSeqDx v1.2 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 = NovaSeqDx
On exit from the step, the Routing Script automation is triggered. This automation assigns samples to the first step of the NovaSeqDx v1.2 workflow, Define Run Format (NovaSeqDx v1.2). This is the only step in Protocol 1: Run Format (NovaSeqDx v1.2).
Protocol 1: Run Format (NovaSeqDx v1.2)
This protocol includes a single step, Define Run Format (NovaSeqDx v1.2). The step allows for the assignment of per sample values for the following fields:
NovaSeqDx Run Mode
Loading Workflow Type
Normalized Molarity
Flowcell Type
Final Loading Concentration (pM)
At the end of the step, samples are routed to the NovaSeqDx Standard or NovaSeqDx Xp protocol. This routing is done according to the selected Loading Workflow Type. The selected NovaSeqDx Run Mode must be compatible with the Loading Workflow Type and Flowcell Type. The following table shows the compatibility for the combinations of each Flowcell Type based on the NovaSeqDx Standard protocol.
NovaSeqDx Standard Protocol Compatibility
The following table shows the compatibility for the combinations of each Flowcell Type based on the NovaSeqDx Xp protocol.
NovaSeqDx Xp Protocol Compatibility
Step 1: Define Run Format (NovaSeqDx v1.2)
In Lab View, locate the Run Format (NovaSeqDx v1.2) protocol. The samples are queued for the Define Run Format (NovaSeqDx v1.2) 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):
NovaSeqDx Run Mode — Select DX or RUO.
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.
Checks that the NovaSeqDx Run Mode value is compatible with the Loading Workflow Type and Flowcell Type. This automation also generates an error message if the Loading Workflow Type or the Flowcell Type are incompatible.
Calculates the Minimum Molarity.
Checks Normalized Molarity value. For samples with no Normalized Molarity value (eg, 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. A message is recorded in the Warning field for the sample.
To proceed, choose one of the following 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 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 NovaSeqDx Standard (NovaSeqDx v1.2) step. This step is the first step in the NovaSeqDx Standard protocol.
Samples whose Loading Workflow Type is set to NovaSeq Xp are routed to the Make Bulk Pool for NovaSeqDx Xp (NovaSeqDx v1.2) step. This step is the first step in the NovaSeqDx Xp protocol.
Protocol 2: NovaSeqDx Standard (NovaSeqDx v1.2)
In this protocol, samples are pooled and added to the library tube in preparation for the NovaSeq 6000Dx run. The protocol contains two steps:
Make Bulk Pool for NovaSeqDx Standard (NovaSeqDx v1.2)
Dilute and Denature (NovaSeqDx v1.2)
Step 1: Make Bulk Pool for NovaSeqDx Standard (NovaSeqDx v1.2)
In Lab View, locate the NovaSeqDx Standard (NovaSeqDx v1.2) protocol.
Samples for the Make Bulk Pool for NovaSeqDx Standard (NovaSeqDx v1.2) 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.
When the step begins, the Validate Single NovaSeqDx Run Mode automation is triggered. This automation checks that the samples have the same NovaSeqDx Run Mode (RUO or DX).
On the Pooling screen, perform the following actions:
Create a pool by dragging samples into the Pool Creator.
Enter a name for the pool or accept the default name (eg, Pool #1).
Select Record Details.
After exiting the Pooling screen, the Validate Inputs Flowcell Type and Single Pool 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 Step automation. This automation sets the next step for samples to ADVANCE and advances them to the next step in the protocol, Dilute, and Denature (NovaSeqDx v1.2). The automation also copies the NovaSeqDx Run Mode value from the input pool to the output pool.
On the Assign Next Steps screen, the next step for samples is set to the next step in the workflow: Dilute and Denature (NovaSeqDx v1.2).
Select Finish Step.
At the end of this step, the pool of samples automatically advances to the Dilute and Denature (NovaSeqDx v1.2) step.
Step 2: Dilute and Denature (NovaSeqDx v1.2)
In Lab View, locate the NovaSeqDx Standard (NovaSeqDx v1.2) protocol. The pool of samples queued for the Dilute and Denature (NovaSeqDx v1.2) 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 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 that corresponds with the NovaSeqDx Run Mode in the following table. If the barcode does not match, 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. To add and activate reagent lots, 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 (NovaSeqDx v1.2)
On the Record Details screen, select Validate Run Setup and Generate Sample Sheet. This triggers the automation script, which performs the following actions:
Validates the parameters entered on the Record Details screen.
Generates the v2 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 automation is triggered and samples are routed to AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2).
In Lab View, the pool of samples is queued for the AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2) step.
At this point in the workflow, the user interaction ends. Proceed to AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2).
Protocol 3: NovaSeqDx Xp (NovaSeqDx v1.2)
In this protocol, samples are pooled and added to lanes on the NovaSeq 6000Dx flow cell. The option selected in the Define Run Format (NovaSeqDx v1.2) step determines the flow cell type.
The protocol contains three steps:
Make Bulk Pool for NovaSeqDx Xp (NovaSeqDx v1.2)
Dilute, Denature & ExAmp (NovaSeqDx v1.2)
Load to Flowcell (NovaSeqDx v1.2)
Step 1: Make Bulk Pool for NovaSeqDx Xp (NovaSeqDx v1.2)
In Lab View, locate the NovaSeqDx Xp (NovaSeqDx v1.2) protocol. The samples are queued for the Make Bulk Pool for NovaSeqDx Xp (NovaSeqDx v1.2) 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, do as follows.
Create a pool by dragging samples into the Pool Creator.
Enter a name for the pool or accept the default name (e.g., 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, based on the ratio used to increase the lowest value to 5.
[Optional] 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 Step 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 next step in the protocol—Dilute, Denature & ExAmp (NovaSeqDx v1.2).
On the Assign Next Steps screen, the next step for samples is set to Dilute, Denature & ExAmp (NovaSeqDx v1.2).
Select Finish Step.
At the end of this step, the pool of samples automatically advances to the Dilute, Denature & ExAmp (NovaSeqDx v1.2) step.
Step 2: Dilute, Denature & ExAmp (NovaSeqDx v1.2)
In Lab View, locate the NovaSeqDx Xp (NovaSeqDx v1.2) protocol. The pool of samples queued for the Dilute, Denature & ExAmp (NovaSeqDx v1.2) 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 (refer to 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, perform the following actions:
In the Reagent Lot Tracking section, select from the active lots displayed in each drop-down list.
In the Step Details section, verify that the DPX1, DPX2, and DPX3 reagent volume values are populated. The script sets these values and they cannot be edited.
[Optional] In the Sample Details table, select the pool icon to view details of the working pool composition.
Make sure that the following values and columns are populated:
BP Aliquot
Mastermix per lane
NaOH
Tris-HCl
Flowcell Type
Loading Workflow Type
A script sets these values and columns and they cannot be edited. The working pool number is appended to the bulk pool name, so that you can 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 (NovaSeqDx v1.2).
Select Finish Step.
Step 3: Load to Flowcell (NovaSeqDx v1.2)
On the Ice Bucket screen, perform the following actions:
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 automation checks the following information:
The Flowcell Type field is set to a valid value (SP, S1, S2, or S4) and 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, do as follows.
Drag 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. This automation also copies the Flowcell Type and Loading Workflow Type field values from step inputs to outputs. The following table shows the barcode mask information.
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. Refer to the following table for details.
Fields Displayed on Record Details Screen of Load to Flowcell (NovaSeqDx v1.2) Step
Select Validate Run Setup and Generate Sample Sheet to trigger the automation script. The script 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 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 - NovaSeqDx Run (NovaSeqDx v1.2) step.
Proceed to AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2).
Protocol 4: AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2)
This protocol contains a single fully automated step: AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2).
The integration starts the step automatically and data from the run is parsed back into Clarity LIMS. User interaction is not required, but you can review the stages of the step in Clarity LIMS (refer to Review Run Data).
Automations
The NovaSeqDx Run (NovaSeqDx v1.2) 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.
The Illumina Preset Protocols (IPP) Package include a Set Next Steps automation configured on the AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2) step. You can use this automation to override the default next step behavior. For more information, refer to NovaSeq 6000Dx Integration v1.3.0 Configuration.
Update Lane Number — This automation is triggered automatically upon entry to the Record Details screen. To make sure that the Lane Number displays correctly, do not disable or modify this automation.
Review Run Data
Read summary metrics are recorded for the library pool. After the run is complete, open the step and review these metrics displayed on the Next Steps screen in the Step Data section and the Sample Details table.
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 6000Dx Integration v1.3.0 Configuration.
When setting up a run on the NovaSeq 6000Dx instrument, NVOS sends a request for the run recipe.
The Sequencer API validates that samples and containers are correctly queued for the AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2) step.
Clarity LIMS sends a JSON response to NVOS. 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, NVOS 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 the kit and enables 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, NVOS 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, NVOS sends a request containing the parsed run metrics. NVOS sends a request only when the run completes successfully. However, the API does not make this assumption and accepts the request regardless of status. The Sequencer API then does the following:
Records the metrics into the fields on file placeholder outputs in Clarity LIMS.
Completes the step in Clarity LIMS if the status is RunCompletedSuccessfully. For all other status options, the step remains in progress. This action is the default autocomplete step behavior. For more information, refer to NovaSeq 6000Dx Integration v1.3.0 Configuration.
Sample sheet generation and contents
NovaSeq 6000Dx 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, (e.g., the error is related to the AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2) step) review the log file information. For more details, refer to Logging.
If the automated run step starts, but does not complete, do 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. You can use the Library Tube or Flowcell barcode as the search term. The steps depend on whether the search is a NovaSeqDx Standard or NovaSeqDx Xp run.
On the Record Details screen, the Sequencing Log multiline text field contains logging information.
If 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 the Clarity LIMS support team. Provide the relevant information from the troubleshooting steps already performed.
Logging
In addition to updating the Sequencing Log multiline text field on the AUTOMATED - NovaSeqDx Run (NovaSeqDx v1.2) step, the Sequencer API writes a detailed log file to
Log messages include the Library Tube ID and Flow Cell ID whenever the messages are related to a sequencing run-related request. In the Clarity 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 of the log messages for this request. However, the LIMS ID of the file must be known in order to retrieve all messages related to the file download. The LIMS ID is found in the Clarity LIMS API and, for sample sheets used in a run, in the recipe response (which can also be found in the log file).
Example lines from the log file:
Last updated
