(tutorials:reporter-register-sample)=
# Register a patient and sample

This page explains how to register a new clinical case in Reporter. Registering creates the patient, order, biosample, and supporting records that the downstream analysis and reporting stages use.

## Before you start

- Confirm that you have the **ReporterDataEntryOperator** role. If the **Add Sample** area is not available, ask your administrator to check your assigned role.
- Gather the required identifiers and clinical information for the case.
- Verify that the assay or test type is configured for your organization.

## Required information

Reporter's Add Sample page collects the following sections. All mandatory fields must be complete before you can submit.

| Section | What to enter | Why it matters |
| --- | --- | --- |
| **Lab test / Order** | Order or test identifiers, assay selection, ordered date. | Links the biosample to the requested test. |
| **Biosample** | Sample ID, sample type, collection date, handling information. | Identifies the physical specimen being analyzed. |
| **Personal (Individual)** | National ID, Medical record number, Name, Alias Name (optional), Date of birth, Ethnicity, Gender. | Identifies the patient and supports report generation. |
| **Phenotypic Features** | Observed phenotypes, searched by term. | Provides clinical context for interpretation and reporting. |
| **Ordering physician** | Physician name, institution, contact information. | Required for report attribution and communication. |

### Field formats

- **National ID** and **Medical record number** are free-text identifiers; there is no fixed pattern, but they should follow your organization's identifier scheme so duplicate-detection is reliable.
- **Sample ID** (in the Biosample section) is also free text, but must be unique within your organization. Reporter rejects a submission if the Sample ID already exists.
- **Gender** is a single-select of Female, Male, or Unknown.
- **Ethnicity** is a fixed dropdown (for example North American, East Asian, European, African, and similar categories) rather than free text.
- **Phenotypic Features** uses a type-ahead search over HPO terms: type at least 3 characters of a clinical description (for example "seizure") and select one or more matching HPO terms as chips. It is not free text and not a static dropdown.

### Linking to an existing patient

Use the **Import** button at the top of the **Personal** section to search for and select an existing Individual record instead of creating a duplicate patient. Selecting an existing individual auto-fills and locks the Personal fields (National ID, Medical record number, Name, Alias Name, Date of birth, Ethnicity, Gender) from that record; leave the section blank and fill it in manually to create a new Individual.

## How to register a single sample

1. In Reporter, open **Add Sample**.
2. Fill in each section on the form. The timeline on the right shows which sections are still invalid.
3. When all sections are valid, click **Submit**.
4. Reporter creates the records and places the sample in the **PENDING** state.

## How to register samples in batch

The **Batch** button opens the Batch Sample Registrator, a 3-step wizard:

1. **Accession / Copy-Paste Data.** Copy 16 columns from Excel or a CSV file and paste them into the text box, or click **Download Excel Template (.xlsx)** to start from a blank template. The columns, in order, are:

   | # | Column | Mandatory |
   | --- | --- | --- |
   | 1 | Assay Name | Yes |
   | 2 | Sample ID | Yes |
   | 3 | Sample Type | Yes |
   | 4 | Time of Collection | Yes |
   | 5 | Primary Cancer Type | No |
   | 6 | Sampled Tissue | No |
   | 7 | Person Name | Yes |
   | 8 | National ID | Yes |
   | 9 | Medical Record Number | Yes |
   | 10 | Date of Birth | Yes |
   | 11 | Ethnicity | Yes |
   | 12 | Gender | Yes |
   | 13 | Phenotypes (comma-separated HPO IDs, for example `HP:0100013,HP:0000769`) | No |
   | 14 | Order Date | Yes |
   | 15 | Hospital Name | Yes |
   | 16 | Physician Name | Yes |

2. **Review & Edit Spreadsheet.** Reporter parses the pasted data into an editable grid and runs a real-time audit: missing mandatory fields, duplicate Sample IDs within the batch, and invalid dates are flagged per cell. You can add rows manually, use **Autofill Order Details** to copy shared order-level values (order date, assay, sample type, diagnosis) across rows, or remove failed rows.
3. **Verify & Submit to System.** Submission is blocked until the error count is zero. Each valid row creates a Biosample and Phenopacket independently, so a single row's failure (for example a duplicate Sample ID) does not block the rest of the batch.

## Validation and duplicate prevention

- Mandatory fields are enforced before submission, both for single-sample registration and for batch rows.
- Sample IDs are checked for uniqueness within the organization; a duplicate Sample ID is rejected with an error naming the conflicting ID. If a duplicate is detected, verify whether the sample is a rerun, re-collection, or data-entry error before proceeding.
- Batch rows are also checked for duplicate Sample IDs against each other within the same paste.
- Phenotype terms are restricted to HPO terms returned by the built-in search; there is no free-text phenotype entry.

## What happens after submission

- The sample appears in the **PENDING** lane of the **Management** view.
- The sample is listed in **Sample List**.
- No analysis has started yet; the next step is to upload sequencing data and launch the pipeline. See {ref}`tutorials:reporter-upload-and-analysis`.

## Troubleshooting

| Problem | Possible cause | Action |
| --- | --- | --- |
| Submit button is disabled | A required field is missing or invalid. | Review the timeline indicators and complete each section. |
| Duplicate identifier warning | The patient or sample ID already exists. | Verify the identifier or mark the case appropriately. |
| Assay not available | The assay is not configured for your organization. | Contact your SeqsLab administrator. |

## Related material

- {ref}`tutorials:reporter-overview` for the big picture.
- {ref}`tutorials:reporter-sample-lifecycle` for state transitions and role ownership.
- {ref}`tutorials:reporter-operations` for finding the sample after registration.