The NovaSeq X Series On-Prem integration v1.0 relies on secret management util version 1.5.0.12 or later to store the access token to Illumina Run Manager and its related secrets.

ℹ If using Vault, ensure that the [appropriate ACL policies](TODO: addlink) are added.

Illumina Run Manager Integration Service v1.0 or later is required for this integration.

Illumina Preset Protocols (IPP) v2.10 package contains the workflow configuration and template files required to enable the NovaSeq X Series On-Prem workflow to run properly.

Install the workflow configurations below on the same server on which you intend to install the NovaSeq X Series On-Prem integration.

• NovaSeq X Series On-Prem Sequencing v1.0 workflow

• Library Prep Validation v2.3.5 workflow (optional, but recommended)

NGS Commons Package v5.25.0 or later is required for Step Automation to work properly.

Purpose:

• Included for validation purposes only, this protocol models the library preparation steps required to advance samples to the NovaSeq X Series On-Prem Sequencing v1.0 workflow.

• The protocol contains a single step - Library Prep Validation v2.3.5. After this step, a routing script sends the samples to the first step of the NovaSeq X Series On-Prem Sequencing v1.0 workflow (Assign Analysis Configuration Template (NovaSeq X Series On-Prem Sequencing v1.0)).

Steps:

1. Library Prep Validation v2.3.5

Purpose:

• This protocol models the lab processes of run setup for starting a NovaSeq X Series sequencing and secondary analysis run on premise.

Steps:

1. Assign Analysis Configuration Template (NovaSeq X Series On-Prem Sequencing v1.0)

   • The secondary analysis of samples is configured using the ACT.

   • The labels applied to the samples are validated against the selected ACT to ensure that samples use valid labels.

2. Make Bulk Pool (NovaSeq X Series On-Prem Sequencing v1.0)

   • Samples are pooled and resuspension buffers and reagents are added with the help of the 'Calculate Volumes' automation.

   • ACT of pooled samples are validated with Validate Analysis Configurations automation to ensure that the secondary analysis configurations remain valid after pooling.

3. Dilute and Denature (NovaSeq X Series On-Prem Sequencing v1.0)

   • Samples from step 2 are denatured and diluted to the final loading concentration with the help of the 'Calculate Volumes' automation.

4. Load To Library Tube Strip (NovaSeq X Series On-Prem Sequencing v1.0)

   • The library pools from step 3 are now ready to be loaded to the NovaSeq X Series library tube strip.

   • Run and analysis information is validated.

   • Samplesheet is generated and planned run is created on NovaSeq X Illumina Run Manager.

5. AUTOMATED - Sequencing Run (NovaSeq X Series On-Prem Sequencing v1.0)

   • This is a fully-automated step that is started and completed automatically once the sequencing run is started and completed on the instrument side.

   • All the sequencing run metadata e.g. run configuration, primary run metrics etc. are recorded automatically.

   ⚠ Samples should be queued at the step. The user must not add samples to the Ice Bucket or start or complete the step. The integration will do this automatically.

6. AUTOMATED - Analysis Run (NovaSeq X Series On-Prem Sequencing v1.0)

   • This is a fully-automated step that is started and completed automatically once the analysis run is started and completed on DRAGEN on-board the instrument.

   • All the analysis run metadata e.g. status and high level analysis summary and demultiplexing result files are recorded automatically.

   ⚠ Samples should be queued at the step. The user must not add samples to the Ice Bucket or start or complete the step. The integration will do this automatically.

Automatically triggered on entry of the step, this automation validates that the sample names contain only alphanumeric, dash and underscore characters.

/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} script:evaluateDynamicExpression -exp 'submittedSamples.each { sample -> if ( !sample.name.matches( ::[A-Za-z0-9_-]+:: ) ) { fail ( ::Submitted sample :: + sample.name + :: should only have alphanumeric, dash, and underscore characters. Please rename and try again.:: ) } }' -log {compoundOutputFileLuid1}

Triggered when you select '1. Retrieve ACT List' button on the Record Details screen, this automation retrieves the list of ACTS that has been created using Illumina Run Manager UI.

/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/novaseqxseries-onprem/automation/novaseqxseries-onprem-automation.jar script:retrieve_act_list -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} -n 'INSTRUMENT_USED' -t true

Triggered when you select '2. Retrieve ACT Information' button on the Record Details screen, this automation:

• Retrieves the details of the selected ACT and populates the step UDFs (e.g., Analysis Version, Library Prep Kit, Index Adapter Kit, Reference Genome)

• Saves the details into a file stored in the Analysis Configuration Metadata file placeholder, which is available for user to download.

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/novaseqxseries-onprem/automation/novaseqxseries-onprem-automation.jar script:retrieve_act_info -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} -a '{udf:Analysis Configuration Template}' -n 'INSTRUMENT_USED'

Automatically triggered on exit of the Record Details screen, this automation:

• Checks that the molarity of all samples are specified

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} script:evaluateDynamicExpression -t false -h false -exp 'if (!input.hasValue(::Molarity (nM)::)) { fail(::The Molarity cannot be empty.::); } else if (input.::Molarity (nM):: <= 0) { fail(::The Molarity cannot be negative or zero.::); }' -log {compoundOutputFileLuid1}

• Checks that all samples are indexed, indexes are the same as the selected ACT.

• Assign the ACT ID, ACT Name, Run Mode and Instrument ID to all the samples in the step.

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/novaseqxseries-onprem/automation/novaseqxseries-onprem-automation.jar -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} -a '{udf:Analysis Configuration Template}' -n 'INSTRUMENT_USED' --derivedSampleInstrumentIdUdf 'Instrument ID' script:validate_indexes script:assign_act

• Sets the next step for samples to ADVANCE, advancing them to the next step in the protocol - Make Bulk Pool (NovaSeq X Series On-Prem Sequencing v1.0).

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} script:evaluateDynamicExpression -t false -h false -exp 'nextStep = ::ADVANCE::' -log {compoundOutputFileLuid1}

Automatically triggered on exit of the Pooling screen, this automation performs analysis configuration validity and checks each pool for the following characteristics:

• Pooled samples assigned with the same secondary analysis application must have the same analysis version (e.g. v3.8.4) and settings (e.g. Map/Align Output Format = CRAM).

/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} script:validate_same_udf_value_for_analytes -f 'Instrument ID' -f 'Run Mode' -v 'perPool' && \
/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} script:evaluateDynamicExpression -t false -h false -exp 'output.::Instrument ID:: = input.::Instrument ID::' -log {compoundOutputFileLuid1} && \
/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/novaseqxseries-onprem/automation/novaseqxseries-onprem-automation.jar -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} -m PerPool -n 'INPUT.Instrument ID' script:validate_analysis_config script:validate_physical_logical_configurations

Triggered when you select 'Calculate Volumes' on the Record Details screen, this automation completes the following actions:

• Checks to ensure all samples have molarity values assigned.

  Copy

  if (!input.hasValue(::Molarity (nM)::)) { return; };

• Uses Number of Samples in Pool to calculate the volumes needed for the 2 nM intermediate library pools.

  Copy

  if (output.hasValue(::Number of Samples in Pool::)) { output.::Number of Samples in Pool:: = output.::Number of Samples in Pool:: + 1; } else { output.::Number of Samples in Pool:: = 1; }' -t true

• Uses the Bulk Pool Volume (ul) field and Number of Lanes to Sequence to calculate volumes needed for the 2 nM intermediate library pools.

• Copies the Final Loading Concentration (pM) and Flowcell Type from the step inputs to the step outputs.

  Copy

  output.::Bulk Pool Volume (ul):: = 100 * step.::Number of Lanes to Sequence::; output.::NovaSeq X Flowcell Type:: = step.::Flowcell Type::; output.::Final Loading Concentration (pM):: = step.::Final Loading Concentration (pM)::;

• Calculates the per sample volume required for each library to make a 2 nM intermediate library pool and sets the total sample volume to zero.

  Copy

  input.::Per Sample Volume (ul):: = 2 * output.::Bulk Pool Volume (ul):: / input.::Molarity (nM):: / output.::Number of Samples in Pool::;output.::Total Sample Volume (ul):: = 0;' -t true

• Calculates the adjusted per sample volume for the pools if any of the calculated volume is lesser than the value specified in Minimum Per Sample Volume (ul) step UDF.

  Copy

  script:calculate_multipool_adjusted_per_sample_volume -t

• Uses the Total Sample Volume (ul) to calculate the RSB volume (ul) required to top up the pools that are needed to create the 2 nM intermediate library pools. The RSB volume is saved to the file in the Calculation File placeholder in the Files section.

  Copy

  script:evaluateDynamicExpression \
    -exp 'if (output.hasValue(::Total Sample Volume (ul)::)) { output.::Total Sample Volume (ul):: = output.::Total Sample Volume (ul):: + input.::Adjusted Per Sample Volume (ul)::; } else { output.::Total Sample Volume (ul):: = input.::Adjusted Per Sample Volume (ul)::; }' -t true \
    script:evaluateDynamicExpression \
    -exp 'if (output.::Total Sample Volume (ul):: > output.::Bulk Pool Volume (ul)::) { output.::RSB Volume (ul):: = 0 } else { output.::RSB Volume (ul):: = output.::Bulk Pool Volume (ul):: - output.::Total Sample Volume (ul):: }' -t true

• Uses the NovaSeqXSeries_Bulk_Pool1.csv and NovaSeqXSeries_Bulk_Pool2.csv template files to generate a single CSV file. This file contains information about the pools and the samples that they contain. The generated file is stored in the Calculation File placeholder in the Files section.

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/DriverFileGenerator.jar -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} script:driver_file_generator \
          -t /opt/gls/clarity/extensions/conf/driverfiletemplates/NovaSeqXSeries_Bulk_Pool1.csv -o 1.csv \
          script:driver_file_generator \
          -t /opt/gls/clarity/extensions/conf/driverfiletemplates/NovaSeqXSeries_Bulk_Pool2.csv -o 2.csv \
          && cat 1.csv 2.csv > {compoundOutputFileLuid0}.cs

• Resets the Number of Samples in Pool, Total Sample Volume (ul), and Bulk Pool Volume (ul) to null before exiting the step.

  Copy

  -exp 'output.::Number of Samples in Pool:: = ::::; output.::Total Sample Volume (ul):: = ::::; output.::Bulk Pool Volume (ul):: = ::::;' -t true

Automatically triggered on exit of the Record Details screen, this automation completes the following actions:

• Proceeds only if the sample has a molarity value.

• Copies the Run Mode from input to output.

• Sets the next step for samples to ADVANCE, which advances them to the Dilute and Denature (NovaSeq X Series On-Prem Sequencing v1.0) step.

/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} -log {compoundOutputFileLuid1} \
script:evaluateDynamicExpression -exp 'if (!input.hasValue(::Molarity (nM)::)){ return; }; output.::Run Mode:: = input.::Run Mode::; nextStep = ::ADVANCE::;'"

Automatically triggered on entry of the step, this automation checks the a NovaSeq X Flowcell Type has been assigned to each input.

/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} script:evaluateDynamicExpression -h false -exp 'if (!input.hasValue(::NovaSeq X Flowcell Type::)){fail(::Invalid Flowcell Type custom field value. Please make sure all input samples have a value assigned for Flowcell Type custom field.::)}' -log {compoundOutputFileLuid1}

Triggered when you select 'Calculate Volumes' on the Record Details screen, this automation completes the following actions based on the NovaSeq X Flowcell Type selected:

• Sets the NaOH Volume (µl) and TT2 Volume (µl) field values.

• Computes the BP Aliquot Volume (µl) and RSB Volume (µl) required for the dilution of pools to the required final loading concentration.

• Sets the PhiX Volume (µl) and PhiX Concentration (µl) if there is a PhiX spike-in.

  Copy

  bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} -log {compoundOutputFileLuid1} \
    script:evaluateDynamicExpression \
    -exp '
    if (input.::NovaSeq X Flowcell Type:: == ::10B:: || input.::NovaSeq X Flowcell Type:: == ::1.5B::) {
        output.::NaOH Volume (ul):: = 8.5;
        output.::TT2 Volume (ul):: = 127.5;
        output.::BP Aliquot Volume (ul):: = input.::Final Loading Concentration (pM):: * 170 / (2 * 1000);
        output.::RSB Volume (ul):: = 34 - output.::BP Aliquot Volume (ul)::;
        if (step.::1-2% PhiX Spike-In::) { 
            output.::PhiX Volume (ul):: = 1; output.::PhiX Concentration (pM):: = 300; 
        }else { 
            output.::PhiX Volume (ul):: = ::::; output.::PhiX Concentration (pM):: = ::::; 
        };
    } else {
        output.::NaOH Volume (ul):: = 14;
        output.::TT2 Volume (ul):: = 210;
        output.::BP Aliquot Volume (ul):: = input.::Final Loading Concentration (pM):: * 280 / (2 * 1000);
        output.::RSB Volume (ul):: = 56 - output.::BP Aliquot Volume (ul)::;
        if (step.::1-2% PhiX Spike-In::) { 
            output.::PhiX Volume (ul):: = 1.6; output.::PhiX Concentration (pM):: = 300; 
        }
        else { 
            output.::PhiX Volume (ul):: = ::::; output.::PhiX Concentration (pM):: = ::::; 
        };
    }'

• Generates a single CSV file containing information about the reagents volume required to dilute the working pools. The generated file is stored in the Calculation File placeholder, in the Files section, for user to download.

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/DriverFileGenerator.jar -i {stepURI:v2} -u {username} -p {password} \
    script:driver_file_generator \
    -t /opt/gls/clarity/extensions/conf/driverfiletemplates/NovaSeqXSeries_Dilute_Denature_Calculate_Volumes.csv -o {compoundOutputFileLuid0}.csv -q true -destLIMSID {compoundOutputFileLuid0} -l {compoundOutputFileLuid1} \
    && echo; echo 'Calculate Volumes completed successfully.'"

Automatically triggered on exit of the Record Details screen, this automation completes the following actions:

• Copies the Run Mode, NovaSeq X Flowcell Type and Instrument ID from input to output.

• Sets the next step for samples to ADVANCE, advancing them to the Load to Library Tube Strip (NovaSeq X Series On-Prem Sequencing v1.0) step.

/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} script:evaluateDynamicExpression -t false -h false -exp 'output.::Run Mode:: = input.::Run Mode::; output.::NovaSeq X Flowcell Type:: = input.::NovaSeq X Flowcell Type::; output.::Instrument ID:: = input.::Instrument ID::; nextStep = ::ADVANCE::' -log {compoundOutputFileLuid1}

Automatically triggered on entry to the step, this automation completes the following actions:

• Checks that the selected destination container type at Load to Library Tube Strip step matches the selected flowcell type of the samples. 1.5B flowcell is compatible with Library 2-tube Strip while 10B and 25B flowcells are compatible with Library 8-tube Strip.

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} \
    script:validate_same_udf_value_for_analytes -f 'Run Mode' -f 'NovaSeq X Flowcell Type' \
    script:validate_selected_container \
    -fn 'NovaSeq X Flowcell Type' -fv '1.5B' -ct 'Library 2-tube Strip' \
    -fn 'NovaSeq X Flowcell Type' -fv '10B' -ct 'Library 8-tube Strip' \
    -fn 'NovaSeq X Flowcell Type' -fv '25B' -ct 'Library 8-tube Strip'

• Performs basic checks on the secondary analysis configuration of the samples in the same planned run. The following checks are included in this script:

  • Samples in the same pools that have the same secondary analysis application must have the same analysis version (e.g. v3.8.4) and settings (e.g. Map/Align Output Format = CRAM).

  ⚠ This script is required for the NovaSeq X Series On-Prem Sequencing v1.0 workflow to function properly.

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/novaseqxseries-onprem/automation/novaseqxseries-onprem-automation.jar  -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} -m PerRun -n 'INPUT.Instrument ID' script:validate_analysis_config script:validate_physical_logical_configurations

Automatically triggered on exit of the Placement screen, this automation validates the library tube strip barcode to ensure it conforms to the barcode mask LC[0-9]{7}-L[A-Z]1 for Library 8-tube Strip and LC[0-9]{7}-L[A-Z]2 for Library 2-tube Strip.

/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} script:validate_output_containers -l {compoundOutputFileLuid1} -r 'Library 8-tube Strip:LC[0-9]{7}-L[A-Z]1' -r 'Library 2-tube Strip:LC[0-9]{7}-L[A-Z]2' -max 1

Triggered when you select 'Validate Run Setup and Create Planned Run' button on the Record Details screen, this automation completes the following actions:

• Validates the parameters entered on the Record Details screen. These parameters are used to set up the run, generate the sample sheet file, and create the planned run on Illumina Run Manager.

  • Run Name may only contain alphanumeric, dash, underscore or period characters. Spaces are not permitted.

    Copy

    if (!step.::Run Name::.matches(::[a-zA-Z0-9-_]+[a-zA-Z0-9-_. ]*::)) { fail(::Run Name contains prohibited characters. Please check to make sure Run Name only contains alphanumeric characters, spaces, dashes and underscores. Run Name must start with alphanumeric, a dash or an underscore::); }

  • Run Name shall not exceed 255 characters.

    Copy

    if (step.::Run Name::.length() > 255) { fail(::Run Name shall not exceed 255 characters.::); };

• Checks the Index 1 Cycles and Index 2 Cycles field values. If Index 2 Cycles is greater than 0, the Index 1 Cycles value must be greater than 0 or an error can occur.

  Copy

  if (step.::Index 2 Cycles:: > 0 && step.::Index 1 Cycles:: == 0) { fail(::Index 1 Cycles cannot be zero if Index 2 Cycles is non-zero::); };

• Generates the sample sheet and creates the planned run on Illumina Run Manager. The sample sheet is attached to the step.

  Copy

  /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/novaseqxseries-onprem/automation/novaseqxseries-onprem-automation.jar  script:generate_sample_sheet -i {stepURI:v2} -u {username} -p {password} -c {compoundOutputFileLuid0} -l {compoundOutputFileLuid1} -n 'INPUT.Instrument ID'

Automatically triggered on exit of the Record Details screen, this automation completes the following actions:

• Sets the next step for samples to ADVANCE, advancing them to the AUTOMATED - Sequencing Run (NovaSeq X Series On-Prem Sequencing v1.0) step.

/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -i {stepURI:v2} -u {username} -p {password} script:evaluateDynamicExpression -t false -h false -exp 'nextStep = ::ADVANCE::' -log {compoundOutputFileLuid1}