Workflow Customization

Last Updated: December 2024

Release Date: July 2024

Document Version: 2

Clarity LIMS Product Analytics (CLPA) Integration is provided to integrate and make available Clarity data to Illumina Connected Analytics (ICA). CLPA allows user to aggregate and analyze lab data from end-to-end workflow in a single location.

These data are uploaded through ICA. Note that ICA subscription is only required to view data on ICA UI.

CLPA integration supports the workflows:

• MiSeq i100 Series

• NextSeq 1000/2000

• NovaSeq 6000 v3

• NovaSeq X Series

• Library Prep Validation

Other workflows (e.g. User's own custom workflow and other Illumina library preparation workflow) can be customized to add CLPA integration capabilities. This guide provides instructions to configure workflow with CLPA integration.

Contact Illumina Support for help to enable UPA on these older workflows:

• NovaSeq Workflow v3.3, v3.5 and v3.7

• NextSeq 1000/2000 Sequencing v2.1 Workflow

Prerequisites

1. BaseSpaceLIMS-unified-product-analytics and BaseSpaceLIMS-unified-product-analytics-scripts are installed and configured

2. IPP v2.3 and above is installed and at least 1 supported workflow installed.

3. Submitted Sample UDF "Illumina Universal Sample Identifier" is required by all UPA automation scripts.

Universal Sample Identifier

The Universal Sample Identifier is a Submitted Sample custom field used by the Register Sample automation. The field assigns a unique identifier to a sample across Illumina workflows. This identifier is used by CLPA to associate the sample with the workflows and analysis that result from a sequencing run and analysis (eg, sample lineage and traceability). Enter the Universal Sample Identifier value during sample accessioning. If the identifier is not provided during sample accessioning, the Register Sample automation does not have access to this value at run time. The CLPA association between the samples and other analytics data is also restricted.

When you install any of the CLPA enabled workflows, the Illumina Universal Sample Identifier custom field is automatically created. If the CLPA enabled workflows are not installed, the custom field must be created manually. When using the Illumina Universal Sample Identifier, the recommended data format is

usi.<clarity_hostname>.<sampleId>

For more information on installing CLPA enabled workflows, contact Illumina Support.

Add the Illumina Universal Sample Identifier Submitted Sample custom field:

1. On the main menu, select Configuration, and then select the Custom Fields tab.

2. On the Global Fields tab, in the Submitted Sample list, select the plus icon to create a custom field.

3. Enter Illumina Universal Sample Identifier as the field name.

4. Set the following properties:

   • For Field Type, select Text.

   • For Required Field, select No.

   • For Read Only, select No.

5. Select Save.

   

Use Common CLPA Automation

Common CLPA automation scripts are used for workflow customization. Each of these automation scripts logs a message into a log file that is defined with the parameter -l. Because steps can have different log placeholder positions, you must update the -l parameter to reference the correct log file placeholder (E.g., {compoundOutputFileLuid1}).

The following automations can be used on any step.

• Step Started:

  bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/unified-product-analytics/automation/unified-product-analytics-automation.jar script:executeUPAAutomationScript -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} -s 'com/illumina/upa/scripts/common/step_started.groovy'"

• Step Completed:

  bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/unified-product-analytics/automation/unified-product-analytics-automation.jar script:executeUPAAutomationScript -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} -s 'com/illumina/upa/scripts/common/step_completed.groovy'"

The Register Sample automation can be used on the Library Prep step. If there are multiple steps in the Library Prep workflow, only add the Register Sample automation to the first step of the protocol. The script is as follows.

bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/unified-product-analytics/automation/unified-product-analytics-automation.jar script:executeUPAAutomationScript -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid0} -s 'com/illumina/upa/scripts/common/register_sample.groovy'

The Register Pool automation is available for the Pooling workflow. The script is as follows.

bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/unified-product-analytics/automation/unified-product-analytics-automation.jar script:executeUPAAutomationScript -i {stepURI:v2} -u {username} -p {password} -l {compoundOutputFileLuid1} -s 'com/illumina/upa/scripts/common/pooling.groovy'

Workflow Customization

Customize the workflow with CLPA automation as follows.

1. Identify the type of CLPA automation to be added along with the trigger location and style. For more information on CLPA automation types and trigger location and styles, refer to Automation Scripts in Configuration for the UPA version of interest.

2. Identify the protocol step to be customized.

3. Check for any existing automations on the triggers (eg, Step/Automatic upon entry or Step/Automatic upon exit). If there is an existing automation, modify the script as follows.

   1. Append the automation after the existing script with &&. Refer to the following examples.

      ℹ When modifying an existing script, make sure to append the automation using the correct quotation marks ("). If you are appending an existing script on the next line, make sure that a backslash (\) is added on the last line of the script.

      • Before append:

        bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/"

      • After append:

        bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ \
        && /opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/unified-product-analytics/automation/unified-product-analytics-automation.jar \
        script:executeUPAAutomationScript -i {stepURI:v2} -u {username} -p {password} \
        -l {compoundOutputFileLuid0} -s 'com/illumina/upa/scripts/common/step_completed.groovy'"

   2. Update the -l parameter to identify the correct Log File placeholder location.

      {compoundOutputFileLuid0} in the example refers to the first file placeholder.

   3. If necessary, update the automation name to describe the new behavior.

   4. In the Automation Use section, enable the step.

      
   5. Save the automation.

4. If there is not an existing automation on the protocol step, check for an existing automation that has been configured as follows.

   1. Identify the automation that is being used (e.g., Register Step Started).

      

   2. Make sure that the log file setting for the existing script has the -I parameter. This parameter identifies the same Log File placeholder that is used with the step.

      • If the Log File location is the same, enable the step in the Automation Use section.

      • If the Log File location is not the same, create a separate automation and enable the step in the Automation Use section of the new automation.

   3. Save the automation.

5. Go to Configuration and select Lab Work.

6. Select the step and configure the Trigger Location/Style. Refer to Automation Scripts in Configuration for the UPA version of interest.

   After the automation is enabled, the automation configuration option becomes available on the Step configuration page.

   

7. Save the step.

Revision History

Version	Changes
2	Added MiSeq i100 Series to list of supported workflows.
1	Initial release.