NovaSeq Run

The following steps outline the sequence of events that occurs when a flow cell is loaded onto the NovaSeq instrument.

User authentication and login to the NovaSeq instrument is achieved via the getSequencerLoginURL endpoint (found at /Illumina/Sequencer/v2/sequencing-run/login). This endpoint returns the URL that the instrument uses to get an access token.

1. The Sequencer API service provides the NovaSeq Control Software (NVCS) with a URL for the Clarity LIMS login screen and the NVCS displays this screen to the user. Log in to automatically authorize the NVCS to use your account to access the Clarity LIMS.
2. Enter credentials:
• Username and password are passed to the Clarity LIMS server to make sure that the access is valid.
• By default, the Sequencer API service tries to contact the Clarity LIMS at http://localhost:9080/clarity/. This URL is set by the installation script, but it can be configured with the clarity.url property in the application.yml file (see application.yml Properties
3. The user is redirected to the Sequencer login page at /Illumina/Sequencer/v2/sequencer_login.
• If authentication is successful, the screen displays a success message. The Clarity LIMS server provides the OAuth token and username by returning them in redirect to /Illumina/Sequencer/v2/sequencer_login/Success. This redirect does not reload the page, but allows the NovaSeq to continue with run setup.
• If authentication fails, the user is left on the login screen and a warning message informs them of the failure. A background redirect to /Illumina/Sequencer/v2/sequencer_login/Error informs the NovaSeq of the failure.
1. The sequencing-run/recipe/novaseq endpoint consumes a POST request with a LibraryContainerI, FlowCellId, and reagents information.
• LibraryContainerId, FlowCellId, and reagent information is provided by the NovaSeq.
• LibraryContainerId and FlowCellId should match either the library tube ID or flow cell ID of the corresponding containers in Clarity LIMS.
• If there are no containers or multiple containers, an error is generated.
2. All populated containers whose name matches either the LibraryContainerId or FlowCellId are validated as follows.
• All samples in the container must be queued for a sequencing run step.
• All samples must be queued for only one sequencing run step.
• All samples must be queued for the same sequencing run step.

Configure the steps that are considered sequencing run steps in the novaseq.sequenceStepNames property in the application.yml file. The property is a list and each list entry must be the exact name of a sequencing step, not the name of the underlying master step/process type. See application.yml Properties for more details.

3. After a single container has passed validation, the run setup information (run recipe request) is returned to the NVCS via the API and the run recipe is generated.

Note the following details:

• The run recipe information is read from fields configured on the parent process/master step of the samples in the container. The workflow must include recipe definition in that step.
• By default, the parent process/master step is the Dilute and Denature (NovaSeq 6000 v3.3) or Load to Flowcell (NovaSeq 6000 v3.3) step, depending on workflow.
• The default field values match the names of the fields in the NovaSeq v3.4.0 configuration included in IPP. The field names are configurable through the recipe.udfNames.* properties. Each of these properties corresponds to an entry in the recipe and the value of a property defines the name of the field that is used to populate that entry in the recipe.
• It is assumed that this parent process/master step removes any illegal characters from the Experiment Name field.
• The Clarity LIMS download link to the sample sheet created on the run setup step is used for the SampleSheet value in the recipe. The name of the output of the sample sheet on the setup step can be configured through the recipe.sampleSheet.outputName property (Sample Sheet by default) in the application.yml (see application.yml Properties for more details). If no matching output is found, or no file was attached to the output, then the value of the recipe.sampleSheet.notAvailableValue property (Not Available by default) is used in the recipe.
4. After the recipe is generated, it is returned as a *.json file in the response, in the form defined by the Swagger definition for the API.

The contents of the run recipe are controlled by the sample sheet contents and the fields configured on the Dilute and Denature (NovaSeq 6000 v3.3) and Load to Flowcell (NovaSeq 6000 v3.3) steps:

Example of run recipe content is as follows:

{

  "run_name": "NVCS16027_SPrime_2x250",

  "run_mode": "S4",

  "workflow_type": "DualIndex",

  "librarytube_id": "NV0025867-LIB",

  "flowcell_id": "",

  "sample_loading_type": "NovaSeqStandard",

  "rehyb": false,

  "paired_end": true,

  "read1": 151,

  "read2": 151,

  "index_read1": 8,

  "index_read2": 8,

  "output_folder": "\\\\network_path\\run_data",

  "samplesheet": "<path to sample sheet on LIMS server>",

  "require_samplesheet_authentication": true,

  "usecustomrecipe": false,

  "customRecipe": null,

  "use_basespace": false,

  "basespace_mode": null,

  "use_custom_read1_primer": false,

  "use_custom_read2_primer": false,

  "use_custom_index_read1_primer": false

}

1. Matching container for the run (library tube or flow cell) is found, and contents are validated to be queued for the correct step.

If no matching container is found or if the samples in the container are incorrectly queued, an error is thrown and the step is not started. This validation is also done during the run recipe request immediately prior, so this error case should not be encountered.

2. Reagent kits that are configured for the Sequencer API are checked against the configuration for the step to be run:
• If a kit is configured for the API but does not exist in Clarity LIMS, it is created.
• If a kit exists, but is not enabled on the step to be run, the step configuration is updated to enable it.
• If a kit that is to be enabled is Archived, it is set to Active.
• If a kit that is to be enabled is in Pending status, it is set to Active.
• If any kits enabled on the step are not configured for the Sequencer API, a warning is logged and the step cannot be completed by the API without user intervention.
• If any kits provided in the recipe request are not configured for the Sequencer API, they are ignored and a warning is logged during lot tracking.
3. The number of replicates for the step is determined by the type of flow cell being used in the run.
• For Standard mode, this information is based on the number of lanes in the flow cell. This information is stored as part of the Sequencer API configuration.
• For XP mode, there is always one replicate, because there is already one input tracked for each lane.
4. The automated sequencing step is started.
5. Reagent lots are attached to the step. The Flow Cell and Library Tube reagents in the request are ignored. Information from these reagents is tracked in Clarity LIMS as containers and custom fields.

Any other reagents in the request are handled as follows.

• If the reagent is not configured to be tracked, a warning is logged and the reagent is ignored.
• Existing reagent lots are looked up by kit name (determined by Sequencer API configuration), name (the serial number in the request), and lot number (the lot number in the request).
• If one or more matching reagent lots exist in Clarity LIMS, the newest one is used.
• If the expiry date does not match the expiry in the request, or if the status is not set to Active, the lot is updated to have the correct expiry date and an Active status.

Otherwise a new lot is created with the following configuration:

• Reagent Kit—Matching kit as determined from Sequencer API configuration and step 2.
• Name—Serial number in request.
• Lot Number—Lot number in request.
• Expiry—Expiry date in request.
• Status—Active.

If any reagents are expected to be in the request but are not, these reagents are logged. This action prevents the step from being completed without user intervention.

6. Master step custom fields are updated with the run information parsed from the request. See Respond to Record InterOps Metrics Call from Instrument.
7. Any important events during this request are logged into the Sequencer API log file and in the Sequencing Log multiline global custom field on the step (assuming the step was started successfully). See Respond to Record InterOps Metrics Call from Instrument.

When the metrics endpoint receives a POST, it completes the following actions:

• Looks for a matching library tube or flow cell in Clarity LIMS.
• Find the in-progress sequencing step for that container.

When the step is found, the run metrics in the request are written to container global custom fields in Clarity LIMS.

If the sequencing run is successful, after the metrics are recorded, the API call for Sequencing Completed is received. Information is matched by Sequencing Container and the following occurs in Clarity LIMS:

1. The Current Cycle, Current Read, and Status master step custom fields are updated.
2. The multiline Sequencing Log master step field is updated.
3. A success message is recorded in the log file at the info level:

Sequencing run with Run ID {runId} of Step '{step.name}' ({step.limsid}) completed successfully.

4. The Clarity LIMS waits for any automations that are triggered automatically as it advances the step.
5. By default, the Clarity LIMS assigns the next steps on the outputs to move them on to the first configured next step. If there are no next steps, the protocol is completed.

If the sequencing run is unsuccessful, the API call for Sequencing Error is received. Information is matched by Sequencing Container and the following occurs in Clarity LIMS:

1. The Current Cycle, Current Read, and Status master step custom fields are updated.
2. The multiline Sequencing Log master step field is updated.
3. A failure message is recorded in the log file at the error level:

Step '${Step.name}' (${Step.limsid}) failed with Run ID ${runId}.

4. The step is left at the Record Details screen.

If the sequencing run is ended by the user, the API call for Sequencing RunEndedByUser is received. Information is matched by Sequencing Container and the following occurs in Clarity LIMS:

1. The Current Cycle, Current Read, and Status master fields are updated.
2. The multiline Sequencing Log master step field is updated.
3. The following message is recorded in the log file, at the warning level:

"Sequencing run with Run ID ${status.runInfo.runId} of Step '${step.configuration.name}' (${step.limsid}) aborted by user ${status.runInfo.userName}."

4. The step is left at the Record Details screen.