Custom Case Data Upload

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.