Clarity LIMS Product Analytics Service Integration v1.1 Installation

Clarity LIMS Product Analytics Integration v1.1 provides data from Illumina products, including instruments, cloud software, informatics software, and assays. The integration also integrates Clarity LIMS data into the Illumina Connected Analytics product analytics service. The data uploaded from Clarity LIMS includes information about the following actions:

• Sample accessioning
• Library pooling
• Step execution
• Sequencing runs
• Run analysis

Clarity LIMS Product Analytics Integration v1.1 supports the workflows and application versions listed in the following table.

All workflows are provided as a configuration slice outside of the Illumina Preset Protocols (IPP) installation.

Supported Workflows and Applications

Sofware/Workflow

Version

ClarityLIMS-App

v6.0 and later

NovaSeq X Series

v1.0

NovaSeq 6000 v3 workflow

v3.4¹, v3.6¹, and v3.8¹

NextSeq 1000/2000 workflow

v2.2¹, v2.3, and later

Library Prep Validation

v2.0.5¹, v2.2.0, and later

¹ The Clarity LIMS Product Analytics enabled workflows are provided as separate configuration slices outside of the IPP installation.

Clarity LIMS Product Analytics Integration v1.1 includes the following required components:

• BaseSpaceLIMS-unified-products-analytics—The core service of the integration. This service installs the daemon service that publishes messages to the product analytics service through the LINK service.
• BaseSpaceLIMS-unified-products-analytics-scripts—The automation scripts of the integration. If new workflows or scripts are introduced, this component can be upgraded.

For more information on the scripts for the product analytics service, refer to Automation Scripts.

The following prerequisites must be completed before using Clarity LIMS Product Analytics Integration v1.1:

Clarity LIMS Product Analytics Integration v1.1 connects to the service through the Illumina Connected Analytics LINK service. You need an ICA user account before you can use the integration.

You must also obtain an API key so that the Clarity LIMS Product Analytics service can gain access to ICA.

Because ICA is used in several different regions, you must provide the applicable region for the connection. ICA is required to be used in the same region as the BaseSpace Sequence Hub.

Set Up ICA Account

You can acquire a user account through ICA before you set up the integration. The account can be under a subscription (Enterprise or Professional). You can register for a free account as a public user. For more information on how to get access to ICA, contact the Illumina Support team.

Generate API Key

The API key is used by the integration to gain access to ICA. Generate an API key as follows.

3. Log in to Illumina Platform. If you do not have an account with Illumina Platform, log in to IlluminaBaseSpace Sequence Hub.
4. Go to the API list view.
5. Select Generate to open the Generate An API Key dialog box.
6. Enter a name and select Generate.

If your account is linked to multiple working groups, select one with ICA permissions. The selected workgroup must be the same one that is used with the instrument and the BaseSpace Sequence Hub. This makes sure that the data created by Clarity LIMS is visible.

7. A pop-up dialog shows the API key that is needed during SIS configuration. Download or write down the API key.

The API key can only be viewed or downloaded at generation. If the key is lost, you must generate a new one.

8. Close the API Key Generated dialog. The key now appears in the key list.

To prevent unauthorized users from accessing data, keep the API key in a secure location and do not share it. If the key is compromised, generate a new one and update the Clarity LIMS configuration.

You must be registered with ICA IMS to use this integration. You must be in the Clarity Admin workgroup to register with IMS.

After registration is complete, a signed application key file will be available to use with the installation of Clarity LIMS Product Analytics Integration v1.1.

You must install Clarity LIMS (v6.0 or later) and its associated workflows. To install the workflows, contact Illumina Support. To customize other workflows, refer to Clarity LIMS Product Analytics Integration v1.1 Configuration and User Interaction.

Clarity LIMS Product Analytics Integration v1.1 uses the Secret Management Utility tool (Secret Utility) to store the ICA API key.

For Illumina cloud hosted deployments of Clarity LIMS, the Clarity LIMS installation tool automatically performs the Secret Utility configuration. No additional configuration is needed.

If you have an on premise deployment of Clarity LIMS v6 or later and have not installed or configured the Secret Utility, you must do so. You need the following information to complete the installation and configuration.

• Tenant database password
• Clarity LIMS database password
• FTP password
• If LDAP is enabled, the LDAP manager password
• If using Clarity LIMS LabLink, the LabLink database password
• Reporting database password
• RabbitMQ password

For installation instructions, refer to Clarity LIMS Install/Upgrade Secret Management for Integration Modules in the Clarity LIMS v6.0 Core Functionality documentation.

For information on the Secret Utility configuration modes, refer to Guide to Secret Management in the Clarity LIMS Core Functionality documentation.

Install Clarity LIMS Product Analytics Integration v1.1 as follows.

1. Install the following RPM:
• BaseSpaceLIMS-unified-product-analytics
• BaseSpaceLIMS-unified-product-analytics-scripts
2. As the glsjboss user, run the following command:

/opt/gls/clarity/config/configure_upa.sh

3. Answer the prompts described in the following table.

After you clear the prompts, the script validates the key and workgroup.

Prompts

Prompt

Answer

Description

Do you want to enable Unified Product Analytics integration?

Y or N

Y enables the product analytics service.

ICA base domain URI:

Enter the default URI.

Enter the URI for the ICA base domain (eg, https://use1.platform.illumina.com for US-east).

ICA API Key

Enter the API key.

This key gives access to ICA. The API key must be associated with the same workgroup.

Filepath to Signed Application Key XML

Enter the file path: /opt/gls/clarity/extensions/unified-product-analytics/conf/signedApplicationKey.xml

This path is the default location from IMS for the key. Enter the full path to the file.

Are you or your organization or your collaborative organization an Enterprise/Professional user of ICA?

Y or N

Enterprise/Professional users of ICA select Y.

Workgroup ID

Enter the workgroup ID associated with the API key.

If the previous prompt is answered with Y, this prompt displays.
4. To start the service, run the following command:

service clarity_upa start

5. To make sure that the service is running successfully, run the following command:

service clarity_upa status

The following application settings are set in /opt/gls/clarity/extensions/unified-product-analytics/conf/upa.properties. Most of these values are set during configuration, but can be changed if necessary. If you adjust any values in the configuration file, you must restart the clarity_upa service.

Application Settings

Property Key

Value

Description

upa.enabled

Assigned during configuration.

If this setting is enabled, the message publishes to ICA.

icaBaseApiUri

Assigned during configuration.

This value is the base URI for ICA.

workgroupId

Assigned during configuration.

This value is the workgroup ID for the workgroup that owns the service data.

threadCount

4

This value is used to process service messages for each polling interval. The default value is 4 and is only increased if it is necessary.

The recommendation is to set this value to one that is not much higher than 50 percent of the number of vCPUs. For example, if there are 8 vCPUs, threadCount would be 4.

pollingIntervalsInSeconds

60

This value is used for the polling frequency of available service messages. The default value is 60 seconds and is only increased if it is necessary.

For a higher throughput, make sure that the polling time is less than 90 seconds.

numberOfRetriesToPublish

3

This value is used for the number of internal retries if there is an HTTP error. The default value is 3.

signedApplicationKeyFilepath

Assigned during configuration.

This location is where you can find the signed Application Key File.

Troubleshooting issues starts with the log and message files. There are additional errors that can be fixed through troubleshooting in Clarity LIMS Product Analytics Integration v1.1.

Two filesThe following files can help determine if the service is running correctly.

•  UpaService.log
• UpaService.error.log.

Check both of these files to make sure that there are no errors. The log files are at /opt/gls/clarity/extensions/unified-product-analytics.

Message files are created when the Clarity LIMS workflow runs any steps that have automation scripts for the product analytics service. The message files contain information about the step ID and the script that is being run. The files are at /opt/gls/clarity/extensions/unified-product-analytics/message.

The product analytics service processes the message files for each pollingIntervalsInSeconds time.

• If the files are processed successfully, they are deleted. UpaService.log indicates that the processing was successful.
• If the files fail to process, they are moved to /opt/gls/clarity/extensions/unified-product-analytics/message/failed. UpaService.error.log indicates whether the files processed successfully.

Troubleshoot the connection/configuration as follows.

1. Download the validate_upa_connectivity.sh script.

This script attempts to establish a connection to LINK from the given credentials and configuration. The script also attempts to publish an empty test message to LINK.

2. Copy the script over to Clarity LIMS and execute it as the glsjboss user.

If the troubleshooting is successful, the script displays a success message: Message file successfully processed! Connectivity to Clarity LIMS Product Analytics is verified to be working.

The following table shows possible errors and recommended actions for troubleshooting them.

Errors

Error

Possible Reason

Recommended Actions

Timeout or unable to communicate with LINK

Connection issues or incorrect URI.

Make sure that the http connection is available and that the ICA base URI is set up correctly.

Refer to the Connection/Configuration troubleshooting section.

Permission denied

Invalid credentials or the ICA EULA is not signed.

Make sure that the workgroup and API key are configured correctly.

Make sure that the Signed Application File is configured correctly and that glsjboss:claritylims has file read access.

Make sure that the ICA end user license agreement (EULA) has been signed. If the EULA notification displays, sign in to ICA and sign the EULA.

Refer to the Connection/Configuration troubleshooting section.

Message files are not processed

Clarity LIMS product analytics service is not running.

Make sure that the service is running using the service clarity_upa status command. If the service is not running, start it manually using the service clarity_upa start command.

If the service does not run, look for error messages in the log file.