Skip to content

Annotation Import

SyRF allows you to import annotations from external systematic review tools into your project. If your team has been using another tool (such as Rayyan, Covidence, or a custom spreadsheet) and wants to bring that work into SyRF, the import wizard guides you through the process step by step.

Overview

The annotation import feature is designed for teams migrating to SyRF mid-review. Rather than re-doing annotation work that has already been completed in another tool, you can import your existing annotations directly into a SyRF project stage.

The import process uses a 5-step wizard:

flowchart LR
    A["1. Upload<br/>File"] --> B["2. Map<br/>Fields"]
    B --> C["3. Validate"]
    C --> D["4. Resolve<br/>Conflicts"]
    D --> E["5. Commit<br/>Import"]

Who This Guide Is For

  • Project Administrators -- You run the import wizard and make decisions about field mapping and conflict resolution
  • Reviewers/Annotators -- After the import, you see the imported annotations alongside any manually created ones. The import is transparent to your annotation workflow.

Before You Start

Before running an import, make sure:

  1. Your project has a stage with questions configured -- The import maps external data to your SyRF annotation questions. The target stage must have its questions set up and the stage must be activated.
  2. Your studies are uploaded -- The studies that the annotations belong to must already exist in your SyRF project. The import maps annotations to existing studies by identifier.
  3. Your data file is ready -- Export your annotations from the external tool in one of the supported formats (see below).

Supported Formats

Format Best for Notes
CSV Spreadsheet exports, tabular data The most common format. Each row represents one annotation for one study.
JSON Structured hierarchical data Supports nested parent-child question relationships natively.
YAML Structured hierarchical data Same as JSON but in YAML syntax. Useful for hand-edited files.

Step 1: Upload Your File

  1. Navigate to the stage where you want to import annotations
  2. Open the stage administration area
  3. Click Import Annotations
  4. Select your file and choose the source format (CSV, JSON, or YAML)
  5. Click Upload

The system parses your file immediately and shows you: - The detected column names (for CSV) or field names (for JSON/YAML) - Sample data from the first few rows - The total number of records detected

If the file cannot be parsed (wrong format, corrupted data), the system tells you what went wrong so you can fix the file and try again.

Step 2: Map Fields

In this step, you tell SyRF how the columns in your file correspond to SyRF concepts.

Required Mappings

  • Study identifier -- Which column identifies the study? This can be:
  • A SyRF study ID (if your external tool tracks SyRF IDs)
  • A custom identifier that matches a field on your studies (e.g., a PubMed ID, DOI, or internal study code)
  • Annotator identifier -- Which column identifies who made the annotation? This can be:
  • An email address that matches a SyRF user
  • A SyRF user ID

Question Mappings

For each annotation question in your target stage, map it to a column in your file:

  1. The wizard lists all questions in the target stage
  2. For each question, select the corresponding column from your file
  3. The wizard suggests automatic mappings based on column names -- review and adjust these suggestions

If your file contains columns that do not map to any SyRF question, you can leave them unmapped (they are skipped during import).

If a SyRF question has no corresponding column in your file, those annotations are left blank after import.

Step 3: Validate

After you confirm your field mappings, the system validates the entire file in the background. This step runs automatically -- you do not need to do anything except wait for it to complete.

The validation checks:

  • Study resolution -- Can each study identifier in your file be matched to a study in your project? Unmatched studies are flagged.
  • Annotator resolution -- Can each annotator identifier be matched to a SyRF user? Unresolved annotators are flagged.
  • Data integrity -- Are all required fields present? Are values valid for their question types (e.g., a number for a numeric question, a valid option for a dropdown)?
  • Conflict detection -- Does the imported data conflict with existing annotations? For example, if a study has already been annotated by the same person in SyRF, the system detects this.
  • Orphaned child annotations -- If your file has answers to conditional (child) questions but no answer to the parent question, the system flags these.

For large files (thousands of rows), validation runs as a background process. You receive a notification when it completes, and you can navigate away and come back.

Validation Results

The results screen shows:

  • Clean records -- Records that passed all checks and are ready to import
  • Warnings -- Records with minor issues (e.g., an optional field is empty)
  • Errors -- Records that cannot be imported without resolution (e.g., unmatched study, invalid value)
  • Conflicts -- Records where imported data conflicts with existing data

Step 4: Resolve Conflicts

If the validation found conflicts or errors, this step lets you decide how to handle them.

Conflict Types

Duplicate annotations: The same annotator already has answers for the same study in SyRF. - Overwrite -- Replace the existing SyRF annotations with the imported ones - Skip -- Keep the existing SyRF annotations and do not import for this study

Unmatched studies: A study in your file could not be matched to a study in SyRF. - Review the unmatched identifiers - Check that the studies have been uploaded to your project - Unmatched records are skipped during import

Unresolved annotators: An annotator in your file could not be matched to a SyRF user. - Check that the email addresses or user IDs are correct - Unresolved records are skipped during import

Orphaned child annotations: Answers to conditional questions where no parent answer exists. - Promote -- Import the child annotation as a standalone answer (parent is left blank) - Skip -- Do not import the orphaned answers

The conflict resolution screen shows clear counts: how many records are clean, how many have conflicts, and how many are unmatched. You can resolve conflicts in bulk (e.g., "Overwrite all duplicates") or individually.

Step 5: Commit the Import

After resolving all conflicts, review the import summary:

  • Total records to import -- How many annotations will be created
  • Studies affected -- How many studies will receive imported annotations
  • Records skipped -- How many records were excluded (unmatched, unresolved, or skipped by your choices)

Click Commit to start the import. The import runs in the background -- for large files, this may take a few minutes. You receive a notification when it completes.

After the Import

Once the import is complete:

  • Imported annotations appear alongside manually created ones -- Annotators see all annotations for a study, regardless of whether they were entered manually or imported
  • Each imported annotation is tagged with its import source -- You can identify which annotations came from an import
  • Import history is available in the stage settings -- You can view a log of all imports for a stage, including when they were run, who ran them, and how many records were imported

Tips

  1. Test with a small file first -- Before importing your full dataset, try importing a file with 5-10 records to verify that your field mappings are correct.
  2. Check your study identifiers carefully -- The most common import issue is unmatched studies due to identifier mismatches. Make sure your file uses the same identifiers as your SyRF project.
  3. Export from the source tool in CSV if possible -- CSV is the most widely supported format and easiest to inspect and fix if issues arise.
  4. Review the validation results thoroughly -- Take time to understand any warnings or errors before proceeding to the commit step.