Before installing the Connected Insights - Local software, review and complete the prerequisites. For instructions, refer to Prerequisites.

Once the prerequisites are met, complete the installation of Connected Insights - Local software in the sequence below:

1. Download the Connected Insights - Local software packages. For instructions refer to Download Connected Insights - Local software Package

2. Install the Connected Insights - Local software. For instructions, refer to Install Connected Insights - Local software

3. Install the Connected Insights - Local software license file. For instructions, refer to Install License File

4. Sign in to Connected Insights - Local software. For instructions, refer to Sign In to Connected Insights - Local software

5. Configure external storage. For instructions, refer to Configure External Storage

6. Install Annotations, Genome Data Reference and Knowledge Bases packages from Software updates page. For instructions, refer to Software Updates section Install or Update software and dependent package.

7. Upload License quota file from Software updates page. For instructions, refer to Software Updates section Update License (ConnectedInsights-QuotaLicense.bin) from Local Computer.

After completing the above instructions to install Connected Insights - Local software, follow the instructions in Configuration to set up Connected Insights - Local software and Data Upload from User Storage (Connected Insights - Cloud and Connected Insights - Local) to ingest cases from secondary analysis data.

Before starting the installation or update of Connected Insights - Local software, make sure that the following prerequisites are met.

1. DRAGEN Server v4 Configuration

Ensure the DRAGEN Server v4 configuration is as below:

• DRAGEN server v4 with Oracle Linux 8. The preferred version of Oracle Linux 8 is preinstalled on the DRAGEN server v4. The DRAGEN server v4 software pipeline is also included.

• DRAGEN server v4 setup shall be completed following the Illumina DRAGEN Server v4 Installation Guide (document #200015717). For more information, refer to Illumina DRAGEN Server v4 Installation Guide on the Illumina support site.

• DRAGEN server v4 is idle during installation or update of Illumina Connected Insights - Local software.

If you are setting the hostname for a DRAGEN server v4, ensure the server has FQDN (Fully Qualified Domain Name) (Example: If the server's hostname is onpremtest and domain is abcd.com, then the server shall be registered as onpremtest.abcd.com in your organization's DNS(Domain Name Server)). If your organization does not have a DNS server, then ensure to setup the server with a static IP and the /etc/resolv.conf file shall be an empty file with no contents in it. Once set up, this configuration will be required for installation and cannot be changed throughout the software's usage. If it changes in the between, then application may not behave as intended and could possibly throw errors. Thus, ensure to finalize the configuration i.e. with FQDN (Or) with Static IP before starting the installation process mentioned in this document.

2. Root or sudoer privileges to access DRAGEN Server v4

You must have root or sudo privileges to run installation commands. To access the DRAGEN server v4 and run commands from the command-line interface, you should be familiar with the Linux commands used to install the software and config file (in case of upgrade from current installed version to the new version).

3. Mounted External Storage Drive with read/write access. It is highly recommended you create a user on the mounted storage which has read and write permission and not use a root user.

An external storage drive must be connected to the DRAGEN server v4 directly or through the network. If an external storage drive meeting the requirements below is not mounted already, refer to the How to section for details on how to mount an external storage drive.

Below are the minimum requirements of the external storage which shall be mounted on the DRAGEN server v4.

• Configured with CIFS/SMB or NFS protocols only. Recommended to use NFS v3.5 and above or CIFS/SMB v3.1 and above protocol for data security. Illumina also recommends an encrypted data storage drive to safeguard your data.

• 100 gigabytes (GB) of available storage space.

• Recommended: 10 Gb (Gigabits) per second of network speed.

The external storage drive is used by Connected Insights - Local software to read inputs and write outputs.

• For inputs, Connected Insights - Local software reads secondary analysis data (for example, VCF and BAM files).

• For outputs, Connected Insights - Local software writes analysis output data and backup files (for example, annotated VCF files, visualization files, and PDF report files).

4. Illumina provided package URLs are accessible in your network

In Illumina's welcome email or customer notification email, all the links to download the packages shall be accessible. If you are unable to reach to any of the sites, please check with your IT to whitelist the URLs. The example URLs are https://support.illumina.com/downloads/* and https://illumina-use1-ici-local-release-data.s3.amazonaws.com/releases/knowledgebases/*

5. A Personal Computer

A personal computer which has a remote access client tool to connect to the DRAGEN server v4 to run the commands and a browser to access Connected Insights - Local software application after software is installed.

Overview of Packages and Download Methods

Overview of Packages

Below are the mandatory packages needed to install Illumina Connected Insights - Local software.

1. Connected Insights Packages — The files are downloaded from the Illumina Connected Insights Software Downloads support page using Downloader Utility.

   • Illumina Connected Insights - Local software: This is the base software package. File size: ~14 GB; file extension: .run

   • Illumina Connected Annotations: This is the Annotations sources package. File size: ~90 GB; file extension: .run

   • Illumina Connected Genome Data Reference: This is Genome references and visualization package. File size: ~11 GB; file extension: .run

2. Connected Insights - Local software license files — These are 2 files provided to the customers by Illumina via email. Both need to be downloaded to your personal computer. One License file (ConnectedInsights-Local-SetupLicense.bin) is required to access the Connected Insights - Local software application before signing into the application and the other License File (ConnectedInsights-Local-QuotaLicense.bin) is required to add Genomic Equivalent (GE) sample credits required to perform tertiary analysis (Process Cases). Both files are mandatory to be installed.

3. Knowledge Base files — These files are downloadable from the links provided by Illumina. Please contact connectedinsightslocal@illumina.com to receive the links.

   • JAX-CKB (File extension: .run)

   • CIViC (File extension: .run)

   • OncoKB (File extension: .run)

❗ To avoid errors during installation, make sure to not alter the names or the extensions of the downloaded files and all the files shall have execute permissions.

For downloading the packages listed in point 1, use the software Downloader Utility compatible to your download environment (Mac, Windows or Linux) from the Illumina Connected Insights Software Downloads support page. The utility shows the progress of the current package being downloaded and exits out of the terminal once downloading all the packages completes.

If the download was interrupted, the Downloader Utility can be re-executed by providing the same file path which will resume the download from where it paused previously.

Overview of Download Methods

There are 3 different ways to make the Connected Insights - Local software packages accessible on the DRAGEN v4 server. You can use any one of the below options to download and make the files accessible.

1. Download directly to DRAGEN v4 server connected to internet

2. Download to external storage drive mounted on the DRAGEN v4 Server using your personal computer

3. Download and Copy Files to USB Drive

❗ Downloading all the packages on an average network speed of 300 Mbps takes between 8 to 10 hours. Downloading all the packages on the recommended network speed of 10 Gbps takes 1 to 2 hours.

Download directly to the DRAGEN Server v4 connected to internet

❗ For Linux, we currently support only Oracle Linux 8 (glibc version≥2.28 and x64), which is the base operating system installed on the DRAGEN server v4. This utility is tested only on the DRAGEN server v4 with Oracle 8 and not other flavors of Linux.

1. Login to the DRAGEN server v4 via root or a user with sudo permissions and navigate to the /staging folder: cd /staging

2. Download the Downloader Utility

   1. On the Chrome Browser launch Illumina Connected Insights Software Downloads support page, select View Options and then Download Utility - Unix (compatible with DRAGEN server v4).

   2. Once you click on the utility, you will be redirected to Illumina account page. Enter your valid Illumina account details. Upon successful login, when prompted, enter either your Customer Number associated with your MyIllumina Account (Or) the valid DRAGEN server v4 serial number. To get the DRAGEN server v4 serial number, login to the DRAGEN server v4 using the root or sudoer user and enter one of the following commands on the DRAGEN server v4: dragen_lic | grep Board or dragen_info -b | grep Serial. Copy the string after SN and enter it in the box prompted on the browser. This begins to download the utility which is ~8 to 10 MB in size.

3. Once it validates, it will generate a presigned URL which is valid only for sometime. Copy this pre-signed URL if you want to directly download the files to the DRAGEN server v4 and on the command prompt enter wget "<CopiedPresignedURL>" -O ici_downloader_unix (Or) you can also download this utility on your laptop/computer and then secure copy (scp command) the utility to the DRAGEN server v4.

4. Once downloaded, make sure the Downloader Utility has execute permission: chmod +x ici_downloader_unix

5. Run the Downloader Utility: ./ici_downloader_unix

6. When prompted to Please enter the path, enter: /staging. This will create the folder /icipackages under /staging and download all the Connected Insights Packages files from the support site to there.

7. Once the Downloader Utility completes downloading, copy the Knowledge Base files (JAX-CKB, CIViC and OncoKB) received from the email link into the /icipackages folder.

8. Make sure all the files have execute permissions. Execute these 2 commands: cd /staging/icipackages chmod +x "illumina_connected_insights_<JAX-CKB file name suffix>.run" "illumina_connected_insights_<CIViC file name suffix>.run" "illumina_connected_insights_<OncoKB file name suffix>.run"

9. This completes the downloading step. Proceed to installing the software by following the instructions in Install Connected Insights Software.

❗ For Linux, we currently support only Oracle Linux 8 (glibc version≥2.28 and x64), which is the base operating system installed on the DRAGEN server v4. Refer to the above section.

(Or)

Download to external storage drive mounted on the DRAGEN server v4 using your personal computer

1. Make sure the personal computer is mounted to the external storage drive directory. Also make sure that external storage drive directory is mounted to the DRAGEN server v4 as well. For details on how to mount the external storage to your laptop, refer to How to.

2. Download the Downloader Utility from Illumina Connected Insights Software Downloads support page, select View Options and choose either Download Utility - Windows or Download Utility - Mac based on what is compatible with your download environment operating system (Mac or Windows)

3. You will be redirected to Illumina login page. Enter your valid Illumina account details. Upon successful login, when prompted enter with your Customer Number associated with your MyIllumina Account (Or) the valid DRAGEN server v4 serial number. To get the DRAGEN server v4 serial number, login to the DRAGEN server v4 via root user and on the command prompt enter one of these commands: dragen_lic | grep Board or dragen_info -b | grep Serial. Copy the string after SN and enter it in the box prompted on the browser. Upon success, choose a location to download the utility which is about ~11 to 12MB in size.

4. Once downloaded, make sure the Downloader Utility has execute permissions.

   • For MacOS (11.0 arm64 or higher), execute this command within the folder containing the Downloader Utility file: chmod +x ici_downloader_mac

   • For WindowsOS (Win11(x64) or higher), in File Browser, right click the Downloader Utility file, click Properties, then go to Security. Confirm the groups and users have all permissions in the Allow column ("Special permissions" not required). To add permissions, click Edit....

5. Run the Downloader Utility.

   • For Macos (11.0 arm64 or higher), execute this command from the folder containing the Downloader Utility file: ./ici_downloader_mac

   • For WindowsOS (Win11(x64) or higher), double click on the executable (or) open Windows Command Prompt and execute the below command from the folder containing the Downloader Utility file: .\ici_downloader_windows.exe

6. When prompted, enter the absolute file path to the mounted external storage drive directory where you want to download all the software packages.

   • Examples:

     • For MacOS (11.0 arm64 or higher): /Volumes/<Root directory of mounted external storage drive>

     • For WindowsOS (Win11(x64) or higher): \\<Root directory of mounted external storage drive>

   • This will create a folder called icipackages under the directory <Root directory of mounted external storage drive> and downloads all the software files from the support site to there. Once the download completes successfully, the Downloader Utility will exit out of the terminal.

7. Once the Downloader Utility completes downloading, copy the Knowledge Base files (JAX-CKB, CIViC and OncoKB) received from the email link into the icipackages folder.

8. Make sure all the files have execute permissions.

   • For MacOS (11.0 arm64 or higher), execute this command in the icipackages directory: chmod +x "illumina_connected_insights_<JAX-CKB file name suffix>.run" "illumina_connected_insights_<CIViC file name suffix>.run" "illumina_connected_insights_<OncoKB file name suffix>.run"

   • For WindowsOS (Win11(x64) or higher), the files may have execute permissions by default. To confirm or edit, see step 4 above.

9. This completes the downloading step. Proceed to installing the software by following the instructions in Install Connected Insights Software.

(Or)

Download and Copy Files to USB Drive

Use this download method when the DRAGEN server v4 is not connected to the internet, incapable of having a personal laptop mount to it, or if the software files cannot be made available on the DRAGEN server v4 via the two methods above for other reasons.

The USB drive must meet the following requirements:

• USB 3.0

• At least 150 GB of storage space to accomodate all the files

• xfs or ext4 format file system

Download the files via the USB method as follows:

1. From your laptop which has access to the links to download all the mandatory packages, format the USB with the partition/label name as usbinstall. For instruction on how to format a USB, refer to How to section "Prepare USB compatible with DRAGEN v4 server (type xfs or ext4 only)".

2. Download and execute the Downloader Utility on your laptop by following steps 2-5 in the section above ("Download to external storage drive mounted on the DRAGEN server v4 using your personal computer").

3. When prompted, enter the absolute file path to either the usbinstall folder to download directly to the USB (Or) the file path to a folder on your laptop and then copy the files to the usbinstall folder once downloading completes. Once the Connected Insights Packages files are completely downloaded on/copied to usbinstall, copy the Knowledge Base files (JAX-CKB, CIViC and OncoKB) received from the email link into the usbinstall folder. For instructions on how to copy files to the USB, refer to How to under the same section "Prepare USB compatible with DRAGEN v4 server (type xfs or ext4 only)".

4. Unplug the USB from your laptop. Take the USB and insert it into the DRAGEN v4 Server.

5. Login to the DRAGEN v4 server as root or sudo user and create a folder named /usbinstall under the /media folder with the following command: mkdir -p /media/usbinstall

6. Run the following command to mount the connected USB drive partition that contains the downloaded Connected Insights Packages files and Knowledge Base files to the DRAGEN server v4: mount /<path to USB partition with downloaded files> /media/usbinstall

7. Run the following commands to make sure that the downloaded files have executable permissions: cd /media/usbinstall chmod +x *

8. This completes the downloading step. Proceed to installing the software by following the instructions in Install Connected Insights Software.

Connected Insights enables user actions that are common for interpreting oncology assays data. The sequence of steps can differ between laboratories, but typically includes the following actions:

Software Setup Actions

Perform the following actions during the initial setup of the software:

1. Configure secondary analysis data upload and sample data upload.

2. Configure settings (for example, QC metrics, variant interpretation, and transcripts).

3. Configure variant filters.

4. Configure the report template.

5. Configure the test definitions that store and automate the settings used for processing individual cases.

Case Review Actions

To review a case, perform the following actions:

1. Find the new case created by the data uploaded to the software.

• Case flags are used at this step to assign users and categories, perform searches, and filter as needed.

1. On the Overview tab, review findings in key genes, genome-wide biomarkers, and key QC metrics (if configured).

2. On the Visualize tab, review chromosomal and other events on the Genome View plot.

3. On the Variants tab, review variants as follows.

• Edit or create filters to customize the specific case information that displays.

• Use the Integrative Genomics Viewer (IGV) to review variant quality.

• Use tags to flag variants to support communication between variant reviewers.

1. Perform variant interpretation and include selected variants into the report as needed.

2. Use information from internal and external sources (for example, My Knowledge Base, JAX-CKB, and the COSMIC database) to facilitate the interpretation process. Reuse information stored for a variant that has been interpreted previously. When you remove and add variants, the draft report is automatically edited to reflect any changes.

3. On the Lab QC tab, review sample and variant quality information.

4. On the Report tab, review the draft report (if defined and enabled from the Configuration page).

5. Preview the final report and add the interpretation summary.

6. Approve the report (available only for the laboratory director role).

7. [Optional] Open the report and update or correct information.

1. After the license installation, once you are redirected to this Login page, using the following default login information to create the first-time administrator account:

   • Username —icidefault

   • Password — P@ssw0rd@123

2. After you sign in, you must add an administrator user. Populate the following fields:

   • Username

   • First Name

   • Last Name

   • Email Address

   • Create Temporary Password

   • Confirm Password

3. Select Save.

4. A page displays indicating that the default account has been suspended and that you can sign in under your administrator username. Select Continue. This will take you to the login page.

5. Using your administrator username and temporary password, sign in to Connected Insights - Local software.

6. After reading the Master Service Subscription Agreement (MSSA), select I Accept.

7. Enter a new password in the New Password and Confirm Password fields and select Reset.

8. Select your security questions and select Save. After you save, you will be logged off.

9. Now sign in to the application with your administrator username and password.

10. Upon successful sign in, you will see 3 notifications. These notifications will continue to display until Installation steps 5 and 6 from Introduction - Software Installation (New Customers), Step 5 (Configure external storage. For instructions, refer to Configure External Storage ) and Step 6 (Install Annotations, Genome Data Reference and Knowledge Bases packages from Software updates page. For instructions, refer to Software Updates ) are completed.

• Your Genome Equivalent Sample balance has reached 0. Case ingestion has been stopped. Please contact administrator or Illumina Sales team.

• External storage drive has not been setup. Go to Administration Console -> Storage drives to configure.

• One or more required packages are not installed. Go to Administration Console -> Software Update to install.

1. Click on the Administration Console -> Storage Drives to complete the Step 5 of Installation steps from Introduction - Software Installation (New Customers). You will be redirected to configure Storage Drives page

❗Note: Illumina recommends having at least two users with Administrator privileges to prevent any potential lockout from the Administrator user login when managing actions on the Administration Console.

Connected Insights - Local software provides status messages during the installation process. These messages indicate that the installation has passed, failed, or has errors that prevent it from continuing. The detailed installer log is at /var/log/ici_installer.log.

Connected Insights - Local software Messages

The following messages are related to the installation of the Connected Insights - Local software:

• If the installation is successful, the following message displays: – Success: Illumina Connected Insights software installation is successful.

• If the installation fails, the following message displays with information on how to troubleshoot the installation issues: – Failed: Illumina Connected Insights software installation has failed, unable to start one or more services. Please visit troubleshooting section of the product documentation or contact service and support team.

• If errors occur before or during installation, the following messages display with information on how to resolve the errors: – Error: DRAGEN server v4 check failed. Please run this script on DRAGEN v4 server only. Installation is aborted. – Error: Unsupported Operating system. Oracle Linux 8 Operating System is required to install this Software. Installation is aborted. – Error: Memory space check failed. /staging on DRAGEN server v4 needs 200GB or more free space to install the Software. Installation is aborted.

License File Messages

The following messages are related to the installation of the Connected Insights - Local software license file:

• If the installation is successful, the following message displays: The license was installed successfully

• If the License installation fails, application displays appropriate error message with the reason for the failure: – If the License is corrupted or a unsupported .bin file is selected: The License file is Invalid – If the License has expired: The License file is expired – If License file is not intended for the current DRAGEN server v4: The license file in not intended for this DRAGEN server v4. – If the selected license file is a Quota License file instead of Setup: The License provided is a renewal License file. We could not find an existing License to renew. Please reach out to Illumina Customer Care to get a new license. – If the DRAGEN server v4 is not reachable via DNS or if the Illumina License Manager service is down: Unable to reach License Manager. Please make sure the License Manager Service is up and running.

• Download both of the license files (.bin) from the Illumina welcome email to your laptop.

• Launch the application in browser based on the Info message provided during the time of successful installation in the nohup.out file, either with the Fully Qualified domain name (Example: hostname.domainname.com) or with the Static IP address. Once application is launched, you will see a message in the browser "Your connection is not private". This message is shown because the application is configured with a self signed certificate which auto renews periodically. To bypass this message from the browser, refer to How to section under the section "Add Certificate to the Trusted sites". Or alternatively if you do not want to "Add this certificate to the Trusted sites", you can click on Advanced button in the browser and then select proceed to the url. Application will then get launched where it would ask you to upload the License File.

• Upload the license file which has the name 'ConnectedInsightsSetupLicense.bin' in it from the browse button. This provides access to Connected Insights - Local software. The installation of license shall be very quick. After installation is complete, you will see a pop-up message which says "License Installation is successful" and you will be redirected to the login screen. You can dismiss the message. Proceed to next step which is Step 4 of Software Installation (New customers)

Note: If the license file installation fails, a failure message displays, and you will not be able to use the application. If a failure occurs you will see any one of these messages, refer to Installation Status Messages. To recover, contact Illumina support team.

Before uploading samples, the lab director must create a test definition, which defines the parameters applied to samples for data processing and display.Test definitions are used to do the following:

• Specify a workflow when uploading a secondary analysis result to Connected Insights.

• Use the uploaded secondary analysis results to create a case.

• Define parameters in the test definition associated with the workflow to apply them to the case.

The test definition defines the following information:

• Supported genome builds

• External knowledge bases

• Applied default variant filters

• Applied default variant flags

• Reports available templates

Custom actionability classifications can be set up in Configuration. Later, when you create therapeutic, prognostic, and diagnostic assertions, you can specify these classifications.

Create custom actionability classifications as follows.

1. On the top toolbar, select Configuration.

2. In the General tab, select Actionability Classification. The default actionability classifications are based on AMP/ASCO/CAP Li et al, 2017. If you want to specify your own, select I want to classify using my own classifications.

3. Provide a name for the actionability classifications (for example, ESMO ESCAT).

4. Select Add.

5. Add a classification name (eg, Level 1).

6. [Optional] Add a description.

7. Choose a color.

8. Select Save.

9. Repeat steps 4–8 until you have your classification created.

   • Classifications can be deleted by selecting x on the created classification.

   • Classifications can be edited by selecting the pencil icon on the created classification.

10. Use the drag handles to map your classifications to the AMP/ASCO/CAP Li et al., 2017 guideline on the right side of the window. Place your classifications in order of their significance. After you create assertions, this order is used to prioritize variants and evidence.

    ❗ Whenever you edit these classifications, it does not modify existing assertions in your knowledge base or reports. When you encounter assertions using older classifications, they can be edited to use the latest classification.

The Connected Insights - Local software installation process can take approximately 45–60 minutes based on network speed.

Install Connected Insights - Local software as follows:

1. Login to DRAGEN server v4 via root or sudoer user and navigate to the directory where you made the installation files accessible to the DRAGEN server v4. This directory depends on how you downloaded and made the files accessible to the DRAGEN server v4 (as instructed by the section Download Connected Insights - Local software packages).

   • If you downloaded directly to DRAGEN server v4 connected to internet, use the command: cd /staging/icipackages

   • If you downloaded to the external storage drive mounted on the DRAGEN server v4 using your personal computer, use the command: cd /mnt/<Path to the directory that the storage drive is mounted to>/icipackages

   • If you downloaded and copied the files to a USB drive, use the command: cd /media/usbinstall

   • Note: you are in the correct directory if the command ls returns all of the installation files you downloaded.

2. Start installation: nohup ./illumina_connected_insights_local_<version>.run &

   • Note: Replace <version> with the version number in the file name (e.g., 5.0.0). If desired, you may replace ./ with the absolute file path (e.g., nohup /mnt/ici_mount/icipackages/illumina_connected_insights_local_5.0.0.run &).

3. After running the command, press Enter.

4. Run the following command to monitor the progress: tail -f nohup.out

5. Wait for a success or failure/error message to display in the command prompt and in the log file (nohup.out). This may take 45-60 minutes. Examples of the success and failure messages and next steps are below.

If installation is successful

1. If the installation is successful, the following 2 messages will display in the command prompt and the log file (nohup.out):

   • Success message: Success: Illumina Connected Insights software installation is successful.

   • URL message: The software generates the URL you can use to access the application via a web browser. There are two forms of this message based on the DNS configuration of the DRAGEN server v4:

     • If the DRAGEN server v4 is configured with a fully qualified Domain Name: Info: Illumina Connected Insights software application can be accessed at https://<FullyQualifiedDomainName>/login

     • If the DRAGEN server v4 is configured with a Static IP address: Info: Illumina Connected Insights software application can be accessed at https://<IP address>/login

❗ Ensure you access the application using the URL printed in nohup.out otherwise it might throw blank errors after the page loads.

1. On your laptop, open a browser and enter the URL to access the Connected Insights - Local software application to perform the remaining steps by proceeding to Install License File.

   • If you receive a browser message indicating that your connection is not private, disregard and proceed to the URL. This is normal and does not impact anything.

Note: After the installation is successful, Connected Insights - Local software creates the following on the DRAGEN server v4:

• /staging/ici_analysis_dir

  • This directory will be deleted after the External Storage drive is configured and the data stored here is moved to external storage drive.

• /staging/ici

• /staging/ici_temp

• /var/log/

❗ Do not delete or alter content in these folders or files. If the files are deleted, new cases cannot be processed, or case results may not be available. If the contents of /var/log are deleted, then we will lose the files needed for troubleshooting in case of any failures.

If installation fails

If the installation fails or an error occurs, a message displays that provides information on how to resolve the error. For more information, refer to Installation Status Messages. If you must reinstall, refer to Software Errors and Corrective Actions.

Illumina Connected Insights is a software solution that enables tertiary analysis of next-generation sequencing (NGS) data. There are two versions of Illumina Connected Insights:

• Connected Insights - Cloud—This version is hosted by Illumina.

• Connected Insights - Local—This version is installed on the local DRAGEN server v4. Both versions of Illumina Connected Insights have the same functionality, but Connected Insights - Local has differences in installation, administration, and license management due to the method of deployment.

In the current version, Connected Insights enables tertiary analysis of variant data generated using somatic oncology assays. The software accepts data generated from DNA and RNA sequencing workflows and can be configured to accept input data from oncology assays and variant callers. Connected Insights integrates several genomic databases that are used to annotate uploaded data to help understand its biological significance.

The software supports variants frequently identified in tumor samples (for example, SNVs, insertions, deletions, fusions, and structural variants). The software also accepts and enables user interpretation for genome-wide biomarkers (for example, tumor mutational burden (TMB), microsatellite instability (MSI), and genomic instability score (GIS) used to assess homologous recombination deficiency (HRD)).

The software has the following features:

• Automated upload of secondary analysis files and case creation

• Case management

• Annotation of genes and variants using connected databases

• Storage of variant interpretation records (assertions) produced by the user

• Configurable test definitions

• Customizable gene and variant filters

• Visualization of variant information

• Generation and editing of summary reports

The following illustration shows typical data flow in Connected Insights - Local

Below is illustration of network interaction of Connected Insights - Local

User-defined automation can add assertions from your knowledge base and/or other knowledge bases automatically to a draft report.

Automation only applies to cases using a test definitions with automation turned on during case ingestion. Cases that were ingested before automation was turned on will not have assertions automatically added to their reports.

Automated assertions can be added for all types of variants with assertions in the supported knowledge bases, including the genome-wide biomarkers TMB, MSI, and GIS. Automation configuration settings determine which biomarkers are included in automation and which assertions for those biomarkers are added to the report.

You can also edit or remove assertions that were automatically added before approving a report. For more information, refer to .

Prerequisites

Before enabling automation, make sure that the following information is set up:

• Key genes and TMB, MSI, and GIS thresholds to limit reporting to certain biomarker scores. For more information, refer to .

• Preferred transcripts to limit reporting to preferred transcripts. For more information, refer to .

• Default filters to limit the variants being reported. For more information on creating variant filters and adding them as default filters in a test definition, refer to and .

Variant Selection

Select either of the following sets of variants to be reported:

• Variants that appear in a default filter and key genes (i.e., Key Findings of the Overview page).

• Variants that appear in a default filter.

The following are not reported:

• Any variant with a likely benign, benign, or likely neutral biological classification in a knowledge base (including My Knowledge Base and ClinVar).

• Any variant with no biological classification in any knowledge base (including My Knowledge Base and ClinVar), and biological classification predicted by the tool is VUS, likely benign, or benign.

• TMB, MSI, and GIS with an unknown status.

Max number of variants eligible for reporting:

• If variant selection is Variants that appear in default filter and key genes, only the first 70 variants with assertions in your default filters that are in key genes are eligible for reporting.

• If variant selection is Variants that appear in default filter, only the first 70 variants with assertions in your default filters are eligible for reporting.

Knowledge Base Selection

You can select KBs you want to report assertions from. The following KBs are selectable:

• My Knowledge Base

• JAX-CKB

• CIViC

• OncoKB

You can also reorder KBs to prioritize assertions. Select and hold the icon to the left of the KB and move it up or down to reorder the KB list. Connected Insights uses the following information to prioritize which KB is used to report findings:

• Order in the KB list (for example, if you move My Knowledge Base above JAX-CKB in the KB list, then My Knowledge Base is prioritized)

• Case disease and assertion disease match (for example, if JAX-CKB is below My Knowledge Base in the KB list, but the case disease matches the JAX-CKB assertion disease, then JAX-CKB is prioritized)

Automatic Reporting Setup

1. On the Configuration page, select the General tab.

2. Select Report Automation, and then select Edit.

3. Select one of the following Report a biomarker when options:

   • Appears in a default filter and Key Genes (Key Findings)

   • Appears in a default filter

4. Select applicable knowledge sources from the following Report findings from options:

   • My Knowledge Base

   • JAX-CKB

   • CIViC
5. Select Yes or No for the following questions:

   • Report assertions previously reported only?

   • Report therapeutic assertions with highest classification only, skipping anything in a lower classification?

   • Report therapeutic assertions that indicate response or resistance only?

6. Select Save.

Custom Annotations allows you to attribute annotations (labels, scores, and population frequency) to variants or variants within a genomic region. The supported data categories for custom annotation in Connected Insights are as follows:

• Filter: String labels

• Score: Numeric values

• AlleleFrequency: Allele frequency for population frequency data

When matching annotations for large variants (structural variants and copy number variants), by default Annotation Overlap (measured as the total overlap divided by the length of the annotation) of >= 0.75 is used, but can be changed to Reciprocal Overlap (measured as the total overlap divided by either the length of the annotation or the length of the variant, whichever is larger) by specifying Reciprocal Overlap in the Description column for the annotation. For more information, refer to .

Upload a new Custom Annotation File

1. On the top toolbar, select Configuration, and then select the Test Components tab.

2. Navigate to Custom Annotations and select New.

3. Download the attached template.

4. Edit the file with the desired annotations (refer to linked documentation above).

5. Upload the file.

Download an existing Custom Annotation Files

1. On the top toolbar, select Configuration, and then select the Test Components tab.

2. Select the Custom Annotations section.

3. Select the desired custom annotation.

4. Select Download.

Test Definitions allow you to specify default parameters that apply to cases when they are ingested. Make sure you have test components created, then create a test definition as follows.

1. On the top toolbar, select Configuration.

2. Select the Test Definitions tab.

3. Select New.

4. In the right-hand pane, enter a test name in the Test Name field.

5. Choose a human reference genome.

6. [Optional] Select one or more custom annotations (must be compatible for the selected human reference genome).

7. Choose one or more variant filters. These filters display in the Case screen as locked filters.

8. Choose a variant flag group.

9. Choose a report template from the Report Template drop-down list.

10. [Optional] Enter version comments as applicable.

11. [Optional] Select the Turn on Automation toggle to enable or disable the automated addition of assertions to reports using this test definition. For more information, refer to .

12. Select Save. The new test definition appears on the left-hand accordion menu. Select a test definition to preview and access the following actions:

    • Select Edit to edit a test definition.

    • Select Copy as New Test to copy the definition as a template for a new test definition.

    • Select Archive to hide the test definition from the PDF report.

Configure the pipeline metrics that appear on the report and edit the default values for each metric as follows.

1. On the top toolbar, select Configuration, and then select the General tab.

2. In the left-side pane, select Pipeline & QC Configuration.

3. Select the applicable pipeline. QC metric configurations display to the right of the selection.

4. Select Edit.

5. To add or remove metrics from the report, select the Add to Overview & Report toggle for each metric.

6. To edit specification limits for applicable metrics, select the Lower Spec Limit or Upper Spec Limit fields and enter the new value. If you cannot edit a value, NA replaces the field.

7. [Optional] To undo all of your changes, select Reset to Default Values.

8. Select Save. The updated metrics appear in the Lab QC tab of the case along with the Pass/Fail designations.

Variant flag groups allow you to organize variants later in the case interpretation. You can add flags for common tasks such as follow-up or to track review statuses.

1. On the top toolbar, select Configuration.

2. Select the Test Components tab.

3. In the left-hand pane, next to the Variant Flag Groups accordion, select New.

4. In the right-hand pane, enter a Variant Flag Group Name.

5. Enter a Flag Name.

6. Choose a flag color.

7. Select Add.

8. Create additional flags as needed.

9. Use the drag handles to change the order that data are displayed in Connected Insights and the final report.

10. Select Save. The variant flag group appears on the left-hand accordion menu. Select through the flag groups to display previews.

    • Select Duplicate to duplicate a flag group.

    • Select Archive to make the flag group unavailable when you create a test definition.

The Custom Case Data page allows you to configure fields for case, subject, and sample information that accompanies cases in Connected Insights. The configuration covers field names, data type, restriction status, and the field category. When you upload the custom case data file, the fields in the file must be formatted to match the definition provided on this page. The information appears in the user interface on the Case Details screen and in the JSON and PDF reports in the corresponding sections.

To configure custom case data:

1. On the top toolbar, navigate to Configuration represented by the cog wheel icon.

2. Navigate to Case Data Definition.

3. In the right-side pane, select the Data Type from the drop-down list. This data type can be text, number, or a date. The type impacts the accepted inputs during data ingestion.

4. Enter a Custom Name. This name is the label that appears in the user interface and the PDF report.

5. Choose if you want this data to be Restricted from the drop-down list.

   • Select Yes if the custom case data are sensitive. When you view the Case Details, the data are hidden with asterisks as indicators, and only displays if you select Show/Hide.

   • If the data are non-sensitive, then select No.

6. Select Case, Subject, or Sample as the Associated Entity from the drop-down list. The corresponding data appears in the Case Details and on the PDF report.

7. Use the drag handles to change the order that data are displayed in Connected Insights and the final report.

8. Select Add to add the new custom case data definitions to the PDF report.

9. [Optional] Select the archive icon next to the custom case data definition to archive it so that it no longer appears on the final report.

10. [Optional] Select the X next to custom case data to remove an entry.

The Variant Filters section describes how to add, configure, duplicate, or archive variant filters.

Add and Configure a Variant Filter

1. On the top toolbar, select Configuration.

2. Select the Test Components tab.

3. Navigate to Variant Filters and select New.

4. Navigate to the Condition Group section and enter the applicable genes in the Genes field.

5. [Optional] Select the Include genes from diseases check box.

6. Select Apply.

7. Select Include or Exclude from the drop-down list for each gene.

8. For Variant Category, select the field to open up a drop-down list of variants that can be included or excluded.

9. Select the check boxes next to the applicable variant types.

10. Select Add Criteria and select the applicable criteria from the drop-down list (for example, Cancer Hotspot Samples).

11. Select Include or Exclude from the drop-down list for the criteria.

12. To include or exclude additional criteria, repeat steps 10 and 11.

13. For AND or OR, select Add Condition Group to add any other applicable condition groups.

14. [Optional] Select Reset to undo the changes to the condition groups.

15. Select Save.

Edit a Variant Filter

1. On the top toolbar, select Configuration.

2. Select the Test Components tab.

3. For Variant Filters, select a filter.

4. Select Edit.

5. Update the applicable settings. For more information, refer to Add and Configure a Variant Filter.

6. Select Save.

Duplicate a Variant Filter

1. On the top toolbar, select Configuration.

2. Select the Test Components tab.

3. For Variant Filters, select the applicable filter.

4. In the right-hand pane, select Duplicate.

5. [Optional] Adjust the condition group settings. For more information, refer to Add and Configure a Variant Filter.

6. Select Save.

Archive a Variant Filter

1. On the top toolbar, select Configuration.

2. Select the Test Components tab.

3. For Variant Filters, select the applicable filter.

4. In the right-hand pane, select Archive.

5. To confirm, select Yes, change.

This section provides information on how to create and customize reports using a template.

Connected Insights requires you to provide a report template for each test definition to ensure consistency of reports produced across cases. This section summarizes the actions that can be performed with report templates to customize the look and content of PDF reports to your specifications.

• Create several report templates and use them in more than one test definition.

• Use a default report template provided by Connected Insights or customize the report as needed. These customizations include: – Changing the logo of the laboratory. – Changing the report name. – Reformatting the page and date. – Removing parts of the report related to the Nothing Reported section. This modification might be needed if the laboratory prefers not to report pertinent negatives. – Adding sample information alongside case and subject information. – Changing text in the Supplemental Information section.

For more information on the customization options, refer to .

Create a Report Template

1. On the top toolbar, select Configuration, and then select the Test Components tab.

2. Navigate to Report Templates and select New.

3. Select Download the template.

4. Save the base ODT template.

5. Edit the file with an applicable document editor. The document editor must be able to load v1.3 ODT files. For information on making custom edits to the report, refer to .

6. Select Upload template to re-upload the template with the recently made changes. Uploaded files must in the ODT format.

7. Select Confirm Report Creation when the report preview displays. Download the original report in the ODT format at any time. You can also archive and unarchive report templates. Archiving a report template makes it unavailable for use when creating a test definition.

Download Report Template

1. On the top toolbar, select Configuration, and then select the Test Components tab.

2. Select Report Templates, and then select Pre-configured Demo Report Template or Pre-configured Demo Report Template (Version 2).

3. After the report loads, select Download as ODT.

Test Changes After Report Template Customization

1. On the top toolbar, select Configuration, and then select the Test Components tab.

2. Navigate to Report Templates and select New.

3. For Create your new report, select Upload template.

4. Using file explorer, navigate to the template with the changes and select Open.

5. Review the PDF preview to make sure that the modified report displays as intended.

Audit Log APIs

Use this API to get the Audit Log information in Connected Insights. Search audit logs for cases, subjects, samples, analysis, etc.

1. On the API page, navigate to the AuditLog section.

2. Select GET /als/api/v1/auditlogs/search.

3. In the Parameters table, update the description for the following applicable parameters:

   • caseId — The displayed case ID (for example, ILM-ABC-234) or the ID for the case (for example, https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/overview).

   • userDisplayId — The email of a user's Connected Insights account (for example, esong@company.com).

   • entityId — The ID of a specific Case, Sample, Subject, or Analysis.

   • entityType — A type of entity. An entity is something within Connected Insights (e.g., user or subject). Refer to the the complete list of Entity Types below.

   • eventName — A type of event that occurred in Connected Insights (e.g., case.added or molecular-data.deleted). Refer to the the complete list of Event Names below.

   • toDate — Include audit log entries created on and before this date. This date is in the yyyy-MM-dd'T'HH:mm:ss'Z' format (for example, 2021-01-30T08:30:00Z).

   • fromDate — Include audit log entries created on and after this date. This date is in the yyyy-MM-dd'T'HH:mm:ss'Z' format (for example, 2021-01-30T08:30:00Z).

   • pageNumber — The specific page number of the API response.

   • pageSize — The size of each page in the API response.

4. Select Execute.

List of searchable Entity Types:

• actionability-classifications

• assertion

• biomarker

• case

• cli-log

• custom-annotation

• custom-case-data

• data-upload

• disease-configuration

• domain

• filter

• flag-groups

• ici-uploader

• molecular-data

• pipeline-configuration

• preferred-transcript

• qc-configuration

• report

• report-automation

• report-category

• report-footer

• report-summary

• report-template

• sample

• subject

List of searchable Event Names:

• case.added

• case.analysis.linked

• case.assertion.updated

• case.biomarker.status.updated

• case.deleted

• case.disease.added

• case.disease.updated

• case.metadata.added

• case.metadata.updated

• case.molecular-data.added

• case.report.added

• case.report.deleted

• case.report.json.viewed

• case.report.pdf.viewed

• case.report.status.reset

• case.sample.added

• case.status.updated

• case.subject.added

• case.subject.updated

• case.tags.updated

• case.updated

• case.viewed

• domain.project.added

• file.metadata.added

• file.metadata.error

• file.metadata.processed

• file.metadata.processing

• ici.uploader.downloaded

• molecular-data.added

• molecular-data.cloud.ingestion.added

• molecular-data.deleted

• molecular-data.updated

• sample.metadata.added

• sample.metadata.updated

• subject.deleted

• subject.metadata.added

• subject.metadata.updated

• subject.renamed

• subject.transferred

The Preferred Transcripts section allows you to upload a preferred transcript file that defines which transcripts for a gene are preferred. These transcripts are prioritized over other transcripts of the gene when the default transcript for a variant is determined. For more information, refer to Transcripts.

Upload the preferred transcript file as follows.

1. On the top toolbar, select Configuration, and then select the General tab.

2. Select Preferred Transcripts.

3. If there are no preferred transcripts, select Create One.

4. For Template File, select Upload and select your transcript file. You can also download a template to customize and upload as your preferred transcript file.

5. Select Open.

6. After the file displays, Select Save.

7. Select Download & View to download the transcript file.

8. [Optional] To upload an updated version of the file, select Upload New Version.

Use APIs to perform the following tasks in Connected Insights:

• Retrieve, edit, and delete case information including disease and case metadata. For more information, refer to Case APIs.

• For Connected Insights - Cloud, ingest cloud analysis data. For more information, refer to Ingest Cloud Analysis Data API (ConnectedInsights - Cloud Only).

• Pull report information, including PDF report drafts and case data. For more information, refer to Report APIs.

Prerequisites

Before using the APIs, make sure that the following prerequisites are met:

• Access to the Swagger site. Access this site by appending /api-docs to the Connected Insights host URL using one of following URL formats:

  • For Connected Insights - Cloud, use the URL format https://<domain>.connectedinsights.illumina.com/api-docs

  • For Connected Insights - Local, use one of the following URL formats depending on whether a fully-qualified domain name is configured:

    • If fully-qualified domain name is configured, use the URL format https://<DRAGEN server hostname>.<domain name>/api-docs

    • If fully-qualified domain name is not configured, use the URL format https://<DRAGEN server IP address>/api-docs

    For Connected Insights - Local, the URL will follow the same format as the URL used to login to Connected Insights (for example, if the login URL includes an IP address, the API URL will also include an IP address).

• Know the following authorization values. Instructions for finding all 3 of these values are below:

  • Authorization (apiKey or psToken/iasPsToken)

  • X-ILMN-Domain

  • X-ILMN-Workgroup

Authorization (apiKey or psToken/iasPsToken)

An API key or psToken/iasPsToken may be used. Consider the following before proceeding:

❗ Note the limitations below for API keys for Connected Insights - Cloud only:

• Regenerating an API key will break Data Uploaders using it until API key in the uploader config file is updated.

• If using the maximum number of API keys, consider using the psToken instead of regenerating an API key or deleting then creating a new API key.

• If using a global API key, API actions will be limited to the workgroup used for the X-ILMN-Workgroup authorization.

If using an API key, it is retrieved from the Manage API Keys section of Connected Insights. Retrieve the API key as follows.

1. From anywhere in Connected Insights, click your username in the top-right, then select Manage API Keys.

2. Click Generate, enter an API key name, then select workgroups and application roles.

   Selecting All current and future workgroups and roles (Global API Key) will still cause API actions to only occur in the workgroup for the X-ILMN-Workgroup authorization you provide later in Swagger. Selecting this option does not mean all API actions will occur in all workgroups.

   You may use an existing API Key if you recorded it and it pertains to the desired workgroup(s) and application role(s). For Connected Insights - Cloud users, consider the limitations above before regenerating an existing API Key.

3. Click Generate and copy the API key.

   This is the one time this value can be viewed. If you will use it again in the future, record and store the API key securely and do not share it with others. You cannot recover it later.

4. In another tab or window, go to the Swagger site. Select Authorize, then in the Available authorizations window, type ApiKey (including one space after) as a prefix followed by the API key value (for example, ApiKey <API key value>)

5. Select Authorize.

If using a psToken, it is retrieved from browser metadata where Connected Insights is being accessed:

1. In Connected Insights browser window, right-click and select Inspect.

2. From the Inspect pane, navigate to the top toolbar and select Application.

3. In the Storage section, select Cookies, then select the menu option with the same name as the Connected Insights URL.

4. In the Name column, copy one of the following values depending on whether you are using Connected Insights - Cloud or Local:

   • For Connected Insights - Cloud, select psToken and copy the psToken value that displays at the bottom of the pane.

   • For Connected Insights - Local, select iasPsToken and copy the iasPsToken value that displays at the bottom of the pane.

5. In another tab or window, go to the Swagger site. Select Authorize, then in the Available authorizations window, paste the psToken or iasPsToken value in the Authorization (apiKey) section Value field. No prefix is required before the psToken or iasPsToken value.

6. Select Authorize.

X-ILMN-Domain

The domain name is retrieved from the URL.

For Connected Insights - Cloud, retrieve the domain name as follows:

1. Copy the domain name from the URL for Connected Insights. For example, <domain> from https://<domain>.connectedinsights.illumina.com. Note that only the domain name is needed, not the entire URL.

2. In the Swagger Available authorizations window, enter the domain name into the X-ILMN-Domain (apiKey) section Value field.

3. Select Authorize.

For Connected Insights - Local, retrieve the domain name as follows:

1. From the Connected Insights URL, the following information from one of the Connected Insights URLs depending on whether a fully-qualified domain name is cofigured or not:

   • Copy the DRAGEN server v4 hostname if fully qualified Domain Name is configured. For example, <DRAGEN server v4 hostanme> from https://<DRAGEN server v4 hostname>.<domain name>/. Note that only the hostname is needed, not the entire URL

   • Copy the IP address of the DRAGEN server v4 if the fully-qualified Domain name is not configured. For example, <DRAGEN server v4 IP address> from https://<DRAGEN server v4 IP address>/.

2. In the Swagger Available authorizations window, paste the copied hostname or IP into the X-ILMN-Domain (apiKey) section Value field.

3. Select Authorize.

X-ILMN-Workgroup

The workgroup ID is found in the metadata of the Connected Insights browser. Retrieve the workgroup ID as follows.

1. In Connected Insights, right-click and select Inspect

2. On the Inspect pane at the right of the screen, navigate to the top ribbon and select Application. A pane opens to the left of the Inspect pane.

3. Navigate to the Storage section and select Cookies.

4. From the Name column, select olympia-current-workgroup and copy the Cookie Value that displays at the bottom of the pane (for example, a1bc2efg-h3i4-567j-8901-k23l45mno6p7).

5. In the Swagger Available authorizations window, paste the copied workgroup ID into the X-ILMN-Workgroup (apiKey) section Value field.

6. Select Authorize.

Use an API to ingest cloud analysis data in Illumina Connected Analytics (ICA) into Connected Insights as follows.

1. From the API page, navigate to the Cloud Analysis section.

2. Select POST /crs/api/v1/analysis-molecular-data/ica/ingest-ica-analysis.

3. In the Parameters table, update the description for the following required parameters:

   • analysisProjectId — The ICA project ID that contains the analysis. To retrieve this ID, open the ICA project containing the analysis and copy the ID from the URL (for example, https://{ICA-host-name}.illumina.com//ica/projects/{analysisProjectId}/projectDetails).

   • analysisId — The ICA analysis ID. To retrieve this ID, open the ICA project containing the analysis, open the desired analysis, and copy the ID value from the ID field.

4. [Optional]Update the description for one of the following optional parameters:

   • workflowId — The workflow ID for the Connected Insights pipeline that will be used to ingest the analysis data. Note, the associated test definition will be applied. To retrieve this ID, go to the Connected Insights Configuration page, General tab, Data Upload section, and select From Illumina Connected Analytics to view the ICA Pipeline workflows. Select the menu icon within the desired workflow and select Copy Workflow Id.

   • pipelineId — The ICA pipeline ID used in the desired analysis. To retrieve this ID, open the ICA project containing the analysis, open the desired analysis, find the pipeline listed here and open it, open the pipeline, and copy the ID value from the ID field.

   ❗ Enter either the specific workflow or pipeline ID.

   • autoGenerateCaseId — Select either true or false for the system-generated case ID (the default value is false).

   • tags — Tag names associated with the case that can be used for a full or partial search.

   • analysisStatus — Enter either SUCCEEDED or FAILED for the analysis status from ICA for the run (the default is SUCCEEDED).

   • Accept-Language — The applicable language for the data.

5. Select Execute.

Use APIs to pull reports (signed-off and draft) and case data, including the subject, sample, and report details. The reports are in a PDF output, and case data is in a JSON output.

Pull Signed-off and Draft Report PDFs

Use this API to pull a PDF of the report for a case. If the report is a draft (e.g., case status is not "Report(s) Signed-Off"), the PDF will include a watermark stating "DRAFT".

1. From the API page, navigate to the DrsPullController section.

2. Select GET /drs/{apiVersion}/draftreport/case/{caseId}/reports/{reportId}/pdf

3. In the Parameters table, update the description for the following required parameters:

   • apiVersion — This value should be v1.

   • caseId — The case ID for the case. To get this information, open the case in Connected Insights and copy the case ID from the URL (for example, https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/draft-report).

   • reportId — The ID associated with the report. To get this information, open the case in Connected Insights, go to the Report page, and copy the report ID from the URL (for example, https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/draft-report).

4. [Optional]Update the description for the following optional parameters:

   • Accept-Language — The applicable language for the data.

   • reportLanguage — The applicable language for the generated report.

5. Select Execute.

Pull Case Data

Use this API to pull case data in JSON format. Case data includes subject, sample, and report details. If the report is a draft (e.g., case status is not "Report(s) Signed-Off"), the JSON will include the information in the draft report.

1. From the API page, navigate to the DrsPullController section.

2. Select GET /drs/{apiVersion}/draftreport/case/{caseId}/reportjson.

3. In the Parameters table, update the description for the following required parameters:

   • apiVersion — This value should be v1.

   • caseId — The case ID for the case. To get this information, open the case in Connected Insights and copy the case ID from the URL (for example, https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/draft-report).

4. [Optional] Update the description for Accept-Language with the applicable language for the data.

   • Accept-Language — The applicable language for the data.

5. Select Execute.

Use APIs to perform the following tasks in Connected Insights:

• Get the case ID

• Add or update the disease for a case

• Search cases

• Delete cases

• Upload Case Metadata files

❗Do not use the Update Case Information or Patch Case APIs. These APIs can significantly alter case data and are only used by Illumina TechnicalSupport.

Get Case ID

1. On the API page, navigate to the Cases section.

2. Select GET /crs/api/v2/cases/{caseId}.

3. In the Parameters table, update the description for the following required parameters:

   • caseId — The ID for the case. To retrieve this ID, select the applicable case in Connected Insights and copy the ID from the URL (for example, https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/overview).

   • directIdentifiers — This parameter includes or ignores direct identifiers. Select true or false from the drop-down list. The default value is false.

   • includeQcOverviewMetrics — This parameter includes or ignores the QC metrics for the case. Select true or false from the drop-down list. The default value is false.

   • Accept-Language — The applicable language for the data.

4. Select Execute.

Add or Update the Disease for a Case

1. On the API page, navigate to the Cases section.

2. Select PUT /crs/api/v1/cases/{caseId}/diseases.

   ❗ This API puts the case in a processing state. Then, it moves to the Ready for Interpretation state. Navigate to the Case List page to check the status of the case.

3. In the Parameters table, update the description for the following parameters:

   • caseId — The ID for the case. To retrieve this ID, select the applicable case in Connected Insights and copy the ID from the URL (for example, https://{domain}.connectedinsights.illumina.com/interpretation/{caseId}/reports/{reportId}/overview).

4. For the Request body, enter the disease name you want to add or update. Refer to the following example: { "externalid": "255032005", "ontologytype": "SNOMEDCT", "name": "Medullary thyroid carcinoma" }

5. Select Execute.

Delete Cases

Use an API to delete cases as follows.

1. On the API page, navigate to the Cases section.

2. Select DELETE /crs/api/v1/cases/{id}

3. In the Parameters table, enter the applicable case ID.

4. [Optional] Enter the applicable language in the Description field.

5. Select Execute.

Search Case

Use an API to search for cases based on one or multiple parameters. If you are using multiple parameters, the search is completed with the AND condition for each parameter.

1. On the API page, navigate to the Cases section.

2. Select GET /crs/api/v1/cases/search.

3. In the Parameters table, update the description for the following applicable parameters:

   • status — The case status. Enter the applicable status in the field. The available statuses are listed in the Description column.

   • isExactMatch — This parameter is used with displayId and determines if the result is an exact match. Select true or false from the drop-down list. The default value is false.

   • displayId — The displayed case ID ( for example, ILM-ABC-234 ). This parameter is an exact search when isExactMatch is set to true.

   • id — The caseId ( for example, dc25cd92-78e0-11e8-adc0-fa7ae01bbebc ). This parameter is also used to search for a partial ID.For example, if you search for 11e8, then dc25cd92-78e0-11e8-adc0-fa7ae01bbebc displays in the results.

   • externalSampleId — The external sample ID for a case ( for example, ILM-ABC-234 ). This parameter is also used to search for a partial ID. For example, if you search ABC or 234, then ILM-ABC-234 displays in the results.

   • analysisId — The specific or custom analysisId.

   • tags — The tags associated with the case. Select Add string item to add a tag. This parameter is also used to search for partial tags. For example, if you search for onc, then both oncogenic and oncology display in the results.

   • diseaseName — The disease name associated with the case.

   • creationDateBefore — The date before the data is created. This date is in the yyyy-MM-dd'T'HH:mm:ss'Z' format ( for example,2021-01-30T08:30:00Z ).

   • creationDateAfter — The date after the data is created. This date is in the yyyy-MM-dd'T'HH:mm:ss'Z' format ( for example, 2021-01-30T08:30:00Z ).

   • pageNumber — The specific page number of the API response.

   • pageSize — The size of each page in the API response.

   • orderBy — This parameter is used by id, displayId, and status to sort results. Results are sorted in ascending or descending order.Enter ASC to sort in ascending order, and enter DESC for descending order.

   • Accept-Language — The applicable language for the data.

4. Select Execute.

Upload Metadata files via an API

Use an API to upload a Case Metadata file as follows.

1. On the API page, navigate to the Cases section.

2. Select POST /crs/api/v2/custom-case-data/files

3. In the Parameters table, select Add string item, then Choose File to select the Case Metadata file from local storage.

4. [Optional] To upload multiple files, select Add strong item and Choose File again. Upload up to 5 files. Accepted file types: CSV. Each file should not exceed 10MB in size, with a combined files limit of 50MB.

5. [Optional] Enter the applicable language in the Description field.

6. Select Execute.

Connected Insights - Cloud Data Uploader tool supports uploading of VCF files and analysis output for user-provided machines and storage devices and can be downloaded from Configuration -> Data Upload section of the application.

Connected Insights - Local Connected Insights - Local includes the Data Uploader tool that is installed on the DRAGEN server v4 as part of the Connected Insights - Local installation and reads secondary analysis results from the external storage drive that is configured. The Data Uploader tool is detected and identified as Default-CLI-Installation in the Data Upload section of the Configuration page. If Default-CLI-Installation does not show as Online, refer to .

The Data Uploader logs can be found at /staging/ici/logs/tss-cli/. With Connected Insights - Local, these logs can also be downloaded from the Activity tab in the Case Details pane on the Cases page. For more information, refer to .

The secondary analysis input logs can be found /ExternalStorageDriveMountPath>/d53e4b2d-0428-4b3e-92bf-955f7153c360/d53e4b2d-0428-4b3e-92bf-955f7153c360/upload-logs/<DataUploadConfiguredMonitoringLocation>/<SecondaryAnalysisRunFolder>/run_<Timestamp>.json

Setup (Connected Insights - Cloud Only)

This section identifies the requirements for uploading data from user storage, enabling ingestion from the network drive, and adding an existing pipeline. For Connected Insights - Cloud, this section also covers how to download and install the Data Uploader tool and has instructions for generating an API key.

Requirements

To upload data from user storage, the following requirements must be met:

• Make sure you have Java 8 or a newer version installed on your computer. You can check by opening a terminal or command prompt and typing java -version. If you don't have it installed, you can download and install it from the official Java website.

• Data Uploader with Java Virtual Machine (JVM) 8+ that is compatible with Mac, Windows, or Linux CentOS.

• An API key and access to the workgroup to which the data is uploaded. The API key comes with the installer. To generate a newAPI key, refer to .

• Administrator access on the computer where Data Uploader is installed.

Before you begin, perform the following actions:

1. Create custom case data.

2. Create test components.

3. Create test definitions.

Download and Install Data Uploader

Download and install the Data Uploader tool as follows.

1. In Connected Insights, select the gear at the top right of the page.

2. In the General tab, under Data Upload, select the From Local Storage tab.

3. Under Download and Launch the Data Uploader, select the storage device operating system from the drop-down list.

4. Select Download Data Uploader. A progress bar displays during the download.

5. Copy the installation directory of the storage device. Make sure that Data Uploader is in a location that has access to your secondary analysis output folder.

6. Use the following tar command to extract the files: Replace {ici uploader script} with the applicable file name. tar xvzf {ici uploader script}.tar.gz

   ❗ Extracting files can vary depending on the operating system. Most terminals support the tar command. For Windows, you can use a zip file extraction application (eg, 7-Zip) to extract the content of the tar folder.

7. Make sure that the files in the following table are in the unzipped Data Uploader file.
8. Install Data Uploader as follows:

   a. [Windows] Start the command prompt as an administrator and run ici-uploader.exe install.

   ❗ For windows environment, user must be in the installation directory to install/uninstall the application. ici-uploader.exe start-daemon

   b. [Mac and Linux] Run the following command on the terminal ./ici-uploader install

   ❗ If the installation fails, start the Connected Insights installation manually using ici-uploader start-daemon

   c. Follow any prompts in Data Uploader. d. Enter your API key and press Enter.

   e. Under Define and Monitor Data Uploads, make sure that your machine displays.

Data Uploader is now set up for auto and manual ingestion. You can also change the name of the installed Data Uploader by selecting ... and Edit Server Name . If you must download any logs associated with the Data Uploader from the last 24 hours, select ... and Download Logs.

❗ If the user is not a system administrator, the daemon can be started with the ici-uploader start-daemon command for Mac/Linux or with the ici-uploader.exe start-daemon command for Windows. This command does not run the process as a system service and requires you to start and stop the service manually. To stop the daemon, run the command ici-uploader stop-daemon

After Data Uploader has been downloaded and installed on the user storage, you can set up configurations for the tool to upload data into Connected Insights automatically. Each configured pipeline monitors user storage for new molecular data.

f. User can stop the ici-uploader (running as system service) using the following command ici-uploader stop-service command for Mac/Linux or with the ici-uploader.exe stop-service command for Windows. User can start the uploader via ici-uploader start-service.

❗If data-uploader is already running as system-service, and user also runs the uploader manually via ici-uploader start-daemon, it may cause issues. User must stop already running data-uploader with ici-uploader stop-service before starting uploader manually.

Enable Upload from Network Drive (Connected Insights - Cloud)

If you are using Linux, automatic case upload is already enabled and this section is not applicable. For Mac, contact Illumina Technical Support. For Windows, run the "illumina ICI Auto Launch Service" to make the network drive available for Data Uploader as follows:

1. When the Data Uploader is running, open the Services application from the Start menu and locate the "illumina ICI Auto Launch Service".

2. Right-click "illumina ICI Auto Launch Service" and select Properties from the drop-down menu.

3. In Properties, select the Log On tab and enter your account ID and password. Confirm the password.

4. Select the General tab.

5. Select Stop, then select Start to start the service. The network drive is available for ingestion for Data Uploader.

After completing these steps, the Data Uploader details are visible in Connected Insights.

Enable Ingestion from Proxy Server Setting

If the computer where the Data uploader is installed is behind a proxy server, then Uploader proxy setting must be enabled. Before you install the Data Uploader, run the following command on the terminal (Linux).

❗ export JDK_JAVA_OPTIONS='-Dhttps.proxyHost=<IP address of the proxy server e.g. 1.2.3.4> -Dhttps.proxyPort=<Port of the proxy server e.g. 8080>'

For Windows, it can be set via following command.

❗ setx JDK_JAVA_OPTIONS "-Dhttps.proxyHost=<IP Address of the proxy server e.g. 1.2.3.4> -Dhttps.proxyPort=<Port of the proxy server e.g. 8080>"

Remember to replace and with the actual values you need.

Select Compatible Pipeline

2. Select a pipeline from the drop-down list (for example, DRAGEN TruSight Oncology 500 Analysis Software v2.5.2).

   ❗ When running the DRAGEN Somatic Whole Genome pipeline in the Tumor-Only mode, you must set --output-file-prefix to match sample-id (the RGSM of the sample in the FASTQ list) of the run.

3. For Test Definition, select the applicable definition.

4. For Choose a folder to monitor for case metadata (optional), enter the path for the folder in the secondary analysis folder created by Data Uploader.

5. Select Save.

Generate an Api Key

If you are using Data Uploader for the first time, then you must generate a new API key. All Data Uploader operations require an API key for authentication. The Data Uploader bundle can be downloaded with an autogenerated API key. If the bundle includes an API key, skip this section.

❗ If you are installing Data Uploader on multiple machines, manually create and track your API key by running the following auto-updating and manual run command:

ici-uploader configure --api-key={apiKey} Make sure that the API key is within single quotation marks (for example,'{SYSTEM_API-KEY}')

1. In Connected Insights, select Manage API Keys from the Account drop-down menu.

2. Select Generate.

3. Enter a name for the API key.

4. To generate a global API key, select All workgroups and roles.

5. Select Generate.

6. In the API Key Generated window, select one of the following options:

   • Show — Reveals the API key.

   • Download API Key — Downloads the API key in .TXT file format.

7. Select Close after you have stored the API key.

   ❗ The API key cannot be viewed again after closing this window. Download the API key or save it in a secure location.

   The API key is added to the Manage API keys list.

8. Perform any of the following actions in the Manage API Keys list:

   • Select Regenerate to generate a new API with the existing API key name.

   • Select Edit to edit the API key name or change the workgroups and roles selection.

   • Select Delete to delete the API key.

Automation of Data Upload from User Storage ( Connected Insights - Cloud and Connected Insights - Local )

The following information is applicable to both Connected Insights - Local and Connected Insights - Cloud. Create each configuration as follows.

1. Input the {monitoring location} for secondary analysis output.

   • The monitoring location is the full path to the location where secondary analysis output data is deposited in user's storage.

     • For example: /rest/of/storage path/{monitoring location}/{runFolder}/{sample folders, sample sheet, inputs, tumor_fastq_list.csv}

     • For DRAGEN server v4 standalone results: /rest/of/storage path/{monitoring location}/{sample name folders}/{sample sheet, inputs, VCFs, .bams}

5. Select Save to complete the configuration. If Data Uploader is running, it monitors this configuration for data upload.

Perform any of the following actions below:

Edit You can modify the pipeline configuration by clicking "Edit" against a configuration.

Note: The change in configuration does not impact the Case that are already ingested.

Delete You can delete the pipeline configuration by clicking "Delete" against a configuration.

Requeue (Connected Insights - Local) You can resume or reupload a secondary analysis output folder by clicking "Requeque" against a configuration. Upon clicking "Requeue", application will re-attempt to create the case from the run folders which previoulsy failed due to one of the below errors:

• SampleSheet validation error

• Case ingestion has stopped due to zero GEs balance

• Case ingestion has stopped due to low space on external mounted storage or /staging

On-Demand Data Upload from User Storage (Connected Insights - Cloud Only)

1. Upload an analysis output by running the following command: ici-uploader analysis upload --folder={path-to-analysis} --pipeline-name={pipelineName}

   • --folder {path-to-analysis} — The absolute path to the analysis output to upload into Connected Insights. This folder contains the sample sheet.

   • --pipeline-name={pipelinename} — The name of the pipeline created in Connected Insights to apply to cases uploaded from this analysis. Pipeline names must include only letters, numbers, underscores, and dashes. The name cannot include spaces or special characters.

   • [Optional] --runId={path-to-config} — The id of the run to be created in place of the run ID determined by the run folder name.

   • [Optional] --pair-id={pair-id} — The pair-id of the analysis to upload from the Sample Sheet when limiting upload to a single analysis.

   • [Optional] --case-display-id={case-display-id} — The id of the case to be created in place of the pair-id when uploading a single analysis with --pair-id={pair-id}.

   • [Optional] ici-uploader logs show — Run to display the logs in ICI_Data_Upload_log.json.

   • [Optional] Downloads > ici-uploader logs download — Download Data Uploader logs in a zipped folder by running the command prompt.

2. Upload the custom case data file associated to one or more cases by running the following command: ici-uploader case-data --filePath={absolute-path-of-csv-file}

Case Processing Performance (Connected Insights - Local Only)

The following table shows the approximate time it takes for example datasets to upload and receive the Ready for Interpretation status. The duration is evaluated by analyzing a batch of samples ingested through the Connected Insights tertiary analysis in conjunction with the DRAGEN secondary analysis performed on similar datasets on the DRAGEN server v4.

This section describes how to upload data with Connected Insights and includes setup instructions. Connected Insights requires the following data types:

• Secondary analysis output data — Connected Insights is compatible with a broad range of analysis pipeline outputs. To configure the input file format, select a compatible pipeline (for example, DRAGEN TruSight Oncology 500 v2.5.2) or configure a custom pipeline.

• Case, subject, and sample data — For more information on custom case data, refer to

Connected Insights - Cloud allows data upload from the following sources:

• User storage — Data ingestion is managed by the Data Uploader tool that supports uploading variant call format (VCF) files and other analysis output files. For more information, refer to .

• Cloud storage on ICA — Data ingestion can be configured through the Data Upload page or API. For more information on using the Data Upload tab or API, refer to .

Before uploading, create the following items:

• Custom case data (if applicable)

• Test components

• Test definitions For more information on creating test components and definitions, refer to .

Connected Insights - Cloud includes an Illumina Connected Analytics pipeline that supports data uploads from ICA to defined workflows.

Requirements

You must be a member of the workgroup to which the data is uploaded. A project not linked to the workgroup must be given permissions at the level of Contributor in the Team tab of ICA to be accessible from Connected Insights. User must have "Lab Director" role for Connected Insights to run the ici-uploader. For more information on adding users to a workgroup and adding permissions, refer to .

Configure Auto-pickup for a Supported Illumina Connected Analytics Pipeline

This section provides instructions for adding a supported ICA pipeline.

1. In Connected Insights, select the gear in the top-right corner to open the Configuration page.

2. Select the General tab.

3. Select Data Upload.

4. Select the From Illumina Connected Analytics tab.

5. For Cloud Pipelines, select Add.

6. For Choose compatible pipeline from the catalog, select the applicable pipeline from the drop-down list, refer to .

7. For Test Definition, select the applicable definition.

8. Select Save.

ℹ️ For the configured Illumina Connected Analytics Pipeline, Connected Insights will automatically upload new analyses in ICA for the specified workflow. When data is uploaded, the status to the right of the workflow name will show the last analysis upload date. If a new project is created or linked after the configuration is made, it will need to be refreshed by editing and saving the configuration before it will begin to pick-up data from that project.

Disable Auto-pickup for a Configured Illumina Connected Analytics Pipeline

1. Locate the pipeline, and then select ...

2. Select Delete.

3. When prompted, select Yes, Remove.

Manual Upload for a Supported Illumina Connected Analytics Pipeline

This section provides instructions for manually uploading a completed analysis for a supported ICA pipeline.

1. From the Case List, select + New Case.

2. Select the Import from Connected Analytics option and click the button for Import from Connected Analytics.

3. Ensure the correct project is selected under Select Project.

4. Select the desired analysis to upload and click the button to Continue.

6. Click Review.

7. Review the information and click Submit to begin processing the selected analysis.

❗ The user must first configure the pipeline in Data Upload Configuration, see above, before manually uploading analyses from ICA.

Upload Data from Illumina Connected Analytics with API

In Connected Insights, use the default report template or introduce customizations to configure the reports according to your specifications. For more information on using the default report template, refer to .

The following applications can be used to customize the report:

• LibreOffice v7.5 or later

• Carbone Studio Illumina recommends using LibreOffice to customize the report. For more information on the customizations that can be done with LibreOffice, refer to the writer guide on the LibreOffice website. Carbone studio and its documentation are updated regularly. Please ensure any command used in an ODT is compatible with Carbone version 4.22.4 or earlier.

Use LibreOffice or an equivalent ODT editor to do common report customizations, including:

• Changing the logo in the header.

• Changing the report name.

• Updating the date and time format.

• Adjusting the font size and color.

• Reordering and removing sections.

• Inserting or removing information, such as single or aggregate data and the Genomic biomarkers table asterisk.

• Changing the paper size.

• Update Methodology Description and Gene List.

• Show Findings by Tier

Change the Logo

1. Prepare the image file that is going to be inserted into the template.

   • Make sure that the image is between 200 and 600 pixels so that it can fit within the header.

   • Make sure that the image file size is less than 50 KB to avoid a delay in report generation.

2. Open the template in the ODT editor.

3. Replace the Laboratory image in the header as follows. a. Select the Laboratory image within the header of the first page. b. Replace the image with the formatted image from step 1. If you are using LibreOffice, right-click and select Replace. For more information on LibreOffice functions, refer to the writer guide on the LibreOffice website. The location and size are adjustable after the image is placed in the header.

   ❗ The default template includes a different header style for the first page and subsequent pages.

   c. Select the image in the header of the second page. d. Replace the image with the formatted image from step1. If you are using LibreOffice, right-click and select Replace.

   For more information on LibreOffice functions, refer to the writer guide on the LibreOffice website. This replacement causes the header image to change in subsequent pages.

Change the Report Name

1. Open the template in the ODT editor.

2. At the top of the template of the first page, replace the following text with the new report name: {d.reportData.reportLabels.report:ifEM():show('Report'):upperCase()}

   ❗ The default template includes different report name text for the first page and subsequent pages.

3. Repeat step 2 for the second page. This replacement causes the report name to change in subsequent pages.

Change Date and Time Format

1. Open the template in the ODT editor.

2. At the top of the template, find the following code that generates the report updated time text: {d.subjects[0].reports[0].reportDetails.updateDate:formatD('YYYY-MM-DD HH:mm')}

3. Replace YYYY-MM-DD HH:mm with the desired format (for example,YYYY-MM-DD).

Localize Time and Date

1. Open the template in the ODT editor.

2. Find and replace every instance of (UTC) with {d.reportData.localDates.timezone.shortName}. This will replace "UTC" with the local time zone abbreviated name (for example, "PT" for Pacific Time).

3. Find the following code that generates the updated date and time text: d.subjects[0].reports[0].reportDetails.updateDate

4. Replace every instance with d.reportData.localDates.reportUpdateDate

5. Find the following code that generates the report approval date and time text: d.reportData.reportHistory[i].approvedDate

6. Replace every instance with d.reportData.reportHistory[i].approvedDateLocal

Change Font Color and Size

1. Open the template in the ODT editor.

2. Change the font color and style using the font characteristics function for an individual text section.

   ❗ Color and size are changeable, but the font style and type cannot be altered.

3. [Optional] If you must update the font color and size for the whole document, adjust the paragraph style.

Reorder Sections

1. Open template in the ODT editor.

2. Identify the sections that must be rearranged.

3. Select and copy all relevant text or tables in that section.

   ❗ The sections of the template primarily consist of tables. Make sure that the entire table is selected when reordering a section. If you do not,then formatting issues can occur.

4. Enter a paragraph break between the sections where the copied section is being placed.

5. Paste the copied section to the new location.

6. Make sure that all of the information is present and formatted correctly.

7. Delete the original section.

8. Repeat steps 1–7 for any other sections that must be reordered.

Remove a Section

1. Open the template in the ODT editor.

2. Select the section of the report that you want to remove.

   ❗ The sections of the template primarily consist of tables. To remove the section, make sure that the entire table is selected. If you do not, then formatting issues can occur.

3. Delete the section.

Insert Information

Insert single data (for example, Methodology) or aggregate data as follows.

1. Open the template in the ODT editor.

2. Place the cursor where you want the new information to appear.

3. Add the applicable code or text used to generate new content or enter free text that you want to appear in all of the generated reports. For example, enter {d.createdDate:formatD('YYYY-MM-DD')} for the date the report was created or {d.reportData.therapies[]:aggCount} to add a count for the number of therapy assertions included in the report.

Remove the Genomic Biomarkers Table Asterisk (Remove Pertinent Negative)

1. Open the template (version 1) in the ODT editor.

2. Search for and delete the following line (use Ctrl+F to search): {$lbl.gbTableFooter:ifEM():show('*Contains disease related genes only')}

3. Search for the following and delete only the asterisk (*): ('Nothing reported')}*

Remove the Nothing Reported genes list

1. Open the template (version 2) in the ODT editor.

2. Search for the following line (use Ctrl+F to search): {$lbl.nothingReportedV2:ifEM():show('Nothing Reported')}

3. Use the ODT editor delete the table row containing the searched for text above.

Change Supplemental Information Description

1. Open the template in the ODT editor.

2. Search for supplemental information in the search field at the bottom of the template. You can also select Ctrl+F to search.

3. Make the desired edits. For more information on complex edits, refer to the ODT editor help documentation. The following edits are common:

   • Change an existing term heading or its definition by updating the text within the single quotation marks for a given term or definition. For example, {$lbl.geneList:ifEM():show('Gene List')} can be changed to the following: {$lbl.geneList:ifEM():show('Genes Included In This Test')}

   • Add static text (for example, laboratory contact information) by placing the cursor outside of the braces ({ }) where the status text begins. Then, type the text. If needed, press Enter to start a new line. Refer to the following example:

   • Before editing:

     {d.dataSourceVersions}{d.dataSourceVersions:ifEM():showBegin()}{$lbl.notProvided:ifEM():show('Not provided')}{d.dataSourceVersions :showEnd()}

   • After editing:

     {d.dataSourceVersions}{d.dataSourceVersions:ifEM():showBegin()}{$lbl.notProvided:ifEM():show('Not provided')}{d.dataSourceVersions :showEnd()} Contact Information Name of Laboratory +1 (123) 555-1234 Email@Email.com

Change Paper Size

1. Open the template in the ODT editor.

2. Select each paragraph style and adjust the page size to the required size needed for printing.

Change Methodology Description and Gene List

1. Open the template in the ODT editor.

2. Search for and delete the following line (use Ctrl+F to search):{d.reportData.methodology.assayDescription:convCRLF()}

3. Replace line with desired methodology text used for the specified workflow. Example text can be found in the default PDF generated from a case in ICI.

4. Search for and delete the following line (use Ctrl+F to search):{d.reportData.methodology.assayGeneListText:convCRLF()}

5. Replace line with desired gene list.

Show Findings by Tier

1. The version 2 template can conditionally display findings at the beginning of the report based on the Tier/Actionability level. The default shows all levels in this section. To only display Tier I and Tier II (or equivalent).

2. Open the template in the ODT editor.

3. Search for the following line (use Ctrl+F to search):classification.actionabilityOrder:ifGTE(7.0)

4. Change 7.0 to 5.0 in the instances of the line.

5. Search for the following line (use Ctrl+F to search):classification.actionabilityOrder>6.9999

6. Change 6.9999 to 4.9999 in all instances of the line.

Connected Insights accepts metadata information about case, subject, and the sample in CSV format to use it for the case creation, display, and reporting.

Overview of uploading custom case data. Each step is further detailed below:

1. Download the Case Metadata template file from the Connected Insights Cases page.

2. Edit the Case Metadata template file to include the desired data.

3. Upload the Case Metadata file via the Connected Insights user-interface, Data Uploader, or API.

Download the Case Metadata template file

Download the Case Metadata template file from Connected Insights:

1. Navigate to the Connected Insights Cases page.

2. Select Upload Case Metadata (top-right corner of the page).

3. Select Upload CSV.

4. Click attached template to download the Case Metadata template CSV file.

❗ Starting from the template can help guide formatting, however, any CSV file that follows the content formatting requirements detailed below can be used to upload case metadata. Files containing non-English characters must be encoded as UTF-8.

Edit the Case Metadata file

Edit the case metadata file to add and correctly format the desired information. See the example at the bottom of this subsection:

1. Open the CSV file with software capable of editing CSV files (for example, a text editor; if using Excel, be cautious of potential unexpected formatting and character additions).

2. Ensure the following formatting requirements are met:

   • The first row must contain the headers of the fields to be updated. Each subsequent row contains data.

   • Each row must contain information in the Sample_ID and Case_ID columns. Sample_ID values are case-sensitive.

   • Fields that require a date must be in yyyy-mm-dd format.

   • Tumor_Type values must be the SNOMEDCT ID for the disease.

     • The SNOMEDCT ID can be found by navigating to an existing case and searching for the disease in the Case Details or assertion form. It can also be found by navigating to the Configuration page, Disease Configuration section, clicking New +, then searching in Associated Disease Term(s). Lastly, the ID can also be found by using the International Edition browser at the SNOMED International SNOMED CT Browser website.

     • When the tumor type is unknown, SNOMETCT ID 363346000 ("Malignant neoplastic disease") or 255052006 ("Malignant tumor of unknown origin") can be used. However, the accuracy of actionability will be higher the more specific the tumor type provided is.

   • All other columns must follow formatting requirements specified in the Case Metadata template file.

   • Data in columns for fields defined in the Custom Case Data Definition section of the Configuration page must match the formatting requirements based on whether the data type is text, a number, or a date (for details, refer to Custom Case Data Definition).

3. Once all rows are added, save.

Refer to the following formatting example:

Sample_ID,Case_ID,Sample_Type,Tumor_Type,Date of Birth,Example Case Meta,Example Subject Meta,Example Sample Meta
SampleId1,Case001,DNA,707405009,2011-01-21,Case Data 01,Subject Data 01,Sample Data 01
SampleId2,Case001,RNA,707405009,2011-01-21,Case Data 01,Subject Data 01,Sample Data 02
SampleId3,Case002,DNA,707405009,2012-02-22,Case Data 02,Subject Data 02,Sample Data 03

Upload Case Metadata files

Case metadata can be uploaded in three ways. See below for instructions on each method:

• Upload from local storage via Connected Insights user-interface.

• Upload from local storage via the Data Uploader.

• Upload from local storage via an API.

Upload Case Metadata files via the Connected Insights user-interface

1. Navigate to the Connected Insights Cases page.

2. Select Upload Case Metadata (top-right corner of the page).

3. Select Upload CSV.

4. Upload the file.

Upload Case Metadata files via the Data Uploader

1. Install the Data Uploader in a location with access to the Case Metadata file (refer to Data Upload from User Storage). Proceed to the next step if it is already installed.

2. Ensure the Case Metadata file is in a location accessible by the Data Uploader.

3. Create a new pipeline or edit an existing pipeline and set the Choose a folder to monitor for case metadata (optional) field to the file path of the directory containing the Case Metadata file (refer to Data Upload from User Storage).

4. Next time the Data Uploader daemon runs, the file will be ingested (may be ~10-15 minutes).

Upload Case Metadata files via an API

• Refer to Case APIs, subsection "Upload Metadata files via an API".

Update existing cases or create new cases by uploading Case Metadata

Update case metadata of an existing case

To update an existing case, use the Sample_ID and Case_ID of the existing case and add updated information in additional fields. It may be useful to use an API in the Case Metadata section of the API page to retrieve the existing case metadata for a case (for details on using APIs, see APIs). The overwriting and preservation logic is as follows:

• Overwriting Logic: If data conflicts, new data will overwrite existing data. For the Tags field, new data will be added as an additional tag and will not overwrite any existing tag(s).

• Preservation Logic: Existing data will not be overwritten if the data for the field is the same as existing or no data is entered. Additionally, fields not included in the Case Metadata file will not be affected (for example, if the Case Metadata file does not include the Date of Birth field, existing data in that field will not be updated).

Create a new case by uploading a Case Metadata file

To create a new case, use a new Sample_ID and a new Case_ID and upload the Case Metadata file before ingestion of molecular data (for example, VCF files or other secondary analysis output files).

• In order for the molecular data to associate with the correct case metadata, the Sample_ID and Case_ID must match (for example, the Sample_ID value used in the Case Metadata file should match the Sample_ID value in the sample sheet).

• Cases created this way will have a Status column value of Awaiting Molecular Data and a Workflow Name column value of N/A in the Case List on the Cases page. The Status and Workflow Name will update after completely uploading molecular data.

View Case Metadata upload tracking and error messages

The Case Metadata Uploads page displays Case Metadata file upload history and error messages:

1. Navigate to the Connected Insights Cases page.

2. Select Upload Case Metadata (top-right corner of the page).

3. Select View Past Uploads.

4. The table displays Case Metadata file upload history, status, and details.

5. If errors occur, the Details column will state this and provide a link to download a copy of the Case Metadata file annotated with error messages for each row.

Custom Pipeline Configuration

The custom pipeline option is designed to make Connected Insights understand the structure of the secondary analysis output files produced by a pipeline that is not yet compatible with the software. This option also requires the creation of a workflow schema file that describes the content and location of the secondary analysis output files. For an example of a how to configure a custom pipeline for TSO 500 Analysis Module v2.2, refer to Custom Pipeline Configuration Example.

Select Custom Pipeline

1. In Configuration Settings, select the radio button next to Configure custom pipeline.

2. If necessary, create a workflow schema file by selecting Download the template file. For more information on setting up the template file, refer to Create a Workflow Schema File

3. Select Choose File to upload your template file.

4. For Custom Pipeline Name, enter a name for the pipeline.

5. For Test Definition, select the applicable definition.

6. For the Choose a folder to monitor for case metadata (optional) field, enter the path for the folder in the secondary analysis folder created by Data Uploader.

7. Select Save.

Create a Workflow Schema File

To set up data upload for secondary analysis output data that is not yet compatible with Connected Insights, create a workflow schema file (.yaml format). This file specifies the files in the secondary analysis output data that Connected Insights analyzes. This file is only used when configuring a custom pipeline.

Download a workflow schema file template from Connected Insights as follows.

1. On the top toolbar, select Configuration.

2. Select the General tab.

3. Select Data Upload.

4. Select From Local Storage.

5. For Define and Monitor Data Uploads, select Add Path.

6. For Configuration Settings, select the radio button next to Configure custom pipeline.

7. Select Download a template file to download the workflow schema template file. If you do not want to create a pipeline, select Cancel. When prompted, select Yes, clear.

8. Edit the file as needed to reflect the files for upload. Refer to the following topics that pertain to the workflow schema template file sections:

   • Pipeline

   • Sample Sheet

   • Joint Files

   • Sample Files

   ❗ If, Optional is after the file name, then Connected Insights uploads the file if it is available or moves on to the next available file.

9. After the workflow schema file is edited, create a pipeline. Then, select Configure manually under Configuration Settings.

10. Select Choose File and upload the edited workflow schema file.

11. Complete the remaining fields and save the pipeline.

    ❗ If this pipeline is used for manual uploading, make sure that the pipeline name only consists of numbers, letters, underscores, and dashes. The name cannot include spaces or special characters. This name is used in the --pipeline-name= command listed in On-Demand Data Upload from User Storage (Connected Insights - Cloud Only)

Pipeline

This section of the file can be partially or completely deleted if uploading does not entail any (or all) of the following aspects:

Required

• successMarkerFile and failureMarkerFile: Specify a success marker file or failure marker file. When this file is present in the specified location, upload begins or stops, respectively.

Optional

• sampleType — If the given analysis output belongs to only DNA or RNA, you can override the samples with the sampleType. If the sample Type is not specified, the system determines it from the analysis output.

Sample Sheet

This section specifies the sample sheet file path found in the analysis folder, the data header row marker, and column aliases. The following information is used to create cases in Connected Insights:

Required

• filePath — Adding a file path to the sample sheet for the cases.

Optional

• columnAliases — Specify the column aliases. These aliases must match the sample information column headers. Some aliases are required and others are optional.

  • sampleId — Appears in the Case ID column of the Cases page.

  • caseId — Appears in the Case ID column of the Cases page. For DNA-RNA paired samples, both the DNA and RNA sample rows have the same value in the column whose header is aliased to caseId. If the caseId is aliased to column header Pair_ID, a DNA-RNA sample must contain the same value in the Pair_ID column in both the DNA and RNA sample rows in Sample Sheet.

  • Sample_Type — No alias can be made for Sample_Type. The sample sheet must include a column header titled Sample_Type with all sample rows containing DNA or RNA in this column.

  • sex — Aliased to the header title of the column containing the sex of each sample.

  • Disease aliases — Determine the list of Key Genes used for this sample. For more information, refer to Overview Tab. If the disease name or ID is not provided, then the Status column on the Cases page displays Missing Required Data. This message displays until the disease name or ID is added. You can add a disease by uploading disease information as custom case data.You can also open the case in Connected Insights and enter the disease for an individual case.

  • id — Can be optionally aliased to the header title of the column containing sample disease ID number according to SNOMEDCT. The SNOMEDCT ID can be found by navigating to an existing case and searching for the disease in the CaseDetails or assertion form. The ID can also be found by using the International Edition browser at the SNOMED International SNOMED CT Browser.

  • name — Can be optionally aliased to the header title of the column containing sample disease name according to SNOMEDCT.If a disease ID is specified, a name is required. If you would not like to specify a name while using a disease ID, enter a null, or any non-exist column for the name field.

• dataHeaderRowMarker - Specify the sample sheet data header row marker. The default value is [Data]. This specifies that the next row (one row below) contains the sample information headers and that the rows below that (two rows below and beyond) contain the sample information values for each sample. This should be the sample sheet cell text in the first column (furthest left) one row above the row containing the column headers describing the types of sample information listed for each sample (two rows above the first row containing sample information).

Joint Files

Specifies the file paths for biomarkers and metrics to be included for interpretation. File names can include symbolic references to the files that depend on the Sample ID or Pair ID:

• {pairId}

• {sampleId.DNA}

• {sampleId.RNA}

When using the workflow scheme file template downloaded from the Configuration page, lines for files that are not uploaded can be deleted. The , Optional designation can be removed unless the file is an optional file for the pipeline.

Sample Files

The following table shows specific sample visualization files used for IGV. File formats include .bam and .bam.bai. For more information, refer to IGV Visualizations. Under alignment Files, the , Optional designation can be removed unless the file is an optional file for the pipeline.

Custom Pipeline Configuration Example

The following example shows the custom pipeline configuration process using Local Run Manager TruSight Oncology 500 Analysis Module v2.2. For details on this process, refer to Custom Pipeline Configuration.

Uploaded Data

Uploaded data is organized as cases that provide details about the sample. A case is a secondary analysis result that has been imported and annotated.These files include VCF files for genetic variants (or CSV files for TruSight Oncology 500 RNA Fusion variants). The cases page lists all cases for your account or workgroup. The following files can be uploaded, but are not required:

• BAM files

• JSON, TSV, and CSV files for TMB, MSI, and GIS biomarkers or for QC metrics

Example Sample Sheet

Make sure that the sample sheet is included in the secondary analysis results folder. The following example shows the structure of the [Data] section of the sample sheet:

[Data]
Sample_ID, Sample_Type, Pair_ID, Tumor_Type
DNA_Control, DNA, Control-Case, 255052006
RNA_Control, RNA, Control-Case, 255052006
Lung_DNA_001, DNA, Lung_001, 254637007
Lung_RNA_001, RNA, Lung_001, 254637007
Breast_DNA_002, DNA, Breast_002, 254837009

Using this example, Connected Insights creates the following cases:

Example Analysis Results

Open the secondary analysis results folder and find the files that must be identified in the workflow schema file. The following example shows the secondary analysis results folder structure:

Example Workflow Schema File

For more information, refer to Create a Workflow Schema File in Custom Pipeline Configuration.

The following example shows the workflow schema file structure:

pipeline:
  successMarkerFile: Logs_Intermediates/MetricsOutput/MetricsOutput.tsv
  failureMarkerFile: "./failure.txt"
sampleSheet:
  filePath: SampleSheet.csv
jointFiles:
  msiFile: Logs_Intermediates/Msi/{sampleId.DNA}/{sampleId.DNA}.msi.json, Optional
  tmbFile: Logs_Intermediates/Tmb/{sampleId.DNA}/{sampleId.DNA}.tmb.json, Optional
  snvFiles: Logs_Intermediates/VariantMatching/{sampleId.DNA}/{sampleId.DNA}_MergedSmallVariants.genome.vcf, Optional
  cnvFiles:
    - Logs_Intermediates/CnvCaller/{sampleId.DNA}/{sampleId.DNA}_CopyNumberVariants.vcf, Optional
  rnaSpliceFiles: Logs_Intermediates/RnaSpliceVariantCalling/{sampleId.RNA}/{sampleId.RNA}_SpliceVariants.vcf, Optional
  rnaFusionFiles:
    - Logs_Intermediates/FusionCalling/{sampleId.RNA}/{sampleId.RNA}.vcf.gz, Optional
    - Logs_Intermediates/RnaFusionMerge/{sampleId.RNA}/{sampleId.RNA}_AllFusions.csv, Optional
  metricsQCFile: Logs_Intermediates/MetricsOutput/MetricsOutput.tsv, Optional
sampleFiles:
  tumorPairId:
    alignmentFiles:
      dnaBamFile: Logs_Intermediates/DnaAlignment/{sampleId.DNA}/{sampleId.DNA}.bam, Optional
      dnaBaiFile: Logs_Intermediates/DnaAlignment/{sampleId.DNA}/{sampleId.DNA}.bam.bai, Optional
      rnaBamFile: Logs_Intermediates/RnaAlignment/{sampleId.RNA}/{sampleId.RNA}.bam, Optional
      rnaBaiFile: Logs_Intermediates/RnaAlignment/{sampleId.RNA}/{sampleId.RNA}.bam.bai, Optional

❗ If , Optional is after the file name, then Connected Insights uploads the file if it is available or moves on to the next available file.

Connected Insights directly supports the following pipelines:

Connected Insights imports variant calls for the following variant types in the Variant Call File (VCF) file format (v4.1 and later):

• Small variants (SNVs, MNVs, and small indels)

• Structural variants (SVs)

• Copy number variants (CNVs)

• RNA fusion variants

• RNA splice variants

❗ Imported VCF files must contain at least one sample and be sorted correctly to ensure valid display of results in Connected Insights.

The following sample fields are supported for each variant type:

Small variants

¹ The following GT values are interpreted as an absence of the reported variant and are not imported:

• .

• ./.

• 0

• 0/0

Copy number variants

¹ The following GT values are expected given the CN of the variant:

• 0: The copy number is normal in a region expected to be haploid.

• 1: The copy number differs from normal in a region expected to be haploid.

• 0/0: The copy number is normal in a region expected to be diploid.

• 0/1: The copy number differs from normal and is not a complete loss in a region expected to be diploid.

• 1/1: The copy number is a complete loss in a region expected to be diploid.

Structural variants and RNA fusion variants

¹ The following GT values are interpreted as an absence of the reported variant and are not imported:

• .

• ./.

• 0

• 0/0

Previous interpretations can be uploaded to My Knowledge Base at any time (for example, during onboarding) so you can immediately start prioritizing variants and reporting based on information from your lab.

1. Navigate to the app selector (grid icon) at the top-right of the screen and select My Knowledge Base.

2. In My Knowledge Base, under Add New Knowledge, select Add Assertions.

3. Select attached template to download the upload template.

4. Edit the template by adding values to the columns. For more information on the applicable columns and values, refer to CSV Template and Uploading Gene Descriptions . To view existing assertions as examples, refer to Existing Assertion Entries.

5. After editing, save the file in the CSV format. The maximum permitted file size is 10 MB.

6. Upload the template file. For more information, refer to Uploading the Template.

CSV Template

The template is in CSV format and contains the following columns:

Uploading the Template

If using Excel, make sure that no auto-formatting has occurred.

After the content has been added to the template, it can be uploaded for processing.

1. In the Add Assertions dialog, drag and drop or select the file to upload. The maximum permitted file size is 10 MB. Any initial validation errors are displayed (for example, missing required headers, incorrect file type).

2. After the file has been uploaded, view the processing status for each file by selecting View Uploads.

3. When completed, view the number of rows processed, including rows that have issues. If a file has issues, download the file and view the issues in a new error column provided in the download. Issues can be resolved in the file and re-uploaded.

Uploading Gene Descriptions

Upload gene descriptions through the CSV template used to upload assertions. To upload gene descriptions, the following fields are required:

• type (for the gene description, the value must be Gene Information)

• geneRoles

• summary

• biomarkerType

• level (for the gene description, the value must be Gene)

• genomeBuild

• geneSymbol

• nbciGeneId

Existing Assertion Entries

Assertions in the knowledge base, created either by upload or within a case, can be downloaded at any time.

1. In the My Knowledge Base screen, select Download to View.