Beyond the Import Wizard: Section 3 - Choosing (and preparing for) the Right Import Options

Published Date: November 2, 2026
Audience: Everyone
Products and Versions Covered:

• Jama Connect® All Versions
  • Cloud/CVC
  • Self-hosted
    • Replicated - KOTS
    • Kubernetes - Native
      • Database
      • OS

IMPORTANT: Access to the REST API and the Jama Connect Cloud MCP Server is restricted to users with a Named Creator Jama Connect license, which includes access to v1, Labs, and SCIM endpoints. Users without a Named Creator license—including those with a Creator Float license—do not have access.

Summary

For intermediate users performing routine imports.

The mechanics of performing an Excel import are covered in the official documentation. This section focuses on the decisions that determine how your import behaves.

Resolution

3.1 Understanding Import Behavior Modes

Jama Connect offers three Excel import modes. Choose based on your goal:

The screenshot below shows exactly where these options are selected in Step 1 of the Jama Connect Data Import Wizard:

• “Update Items” NOT selected skips matching logic entirely. Every row becomes a new item. Use this only when you’re sure no duplicates exist.
• “Update Items” selected requires you to export first (to automatically populate Jama Connect’s API IDs). Without those IDs, Jama Connect can’t match rows to existing items.
• Critical nuance: Even in “Excel Wins” mode, workflow transitions (e.g., moving from “Draft” to “Approved”) won’t get updated. See Section 2.3: Import Before Enabling Workflow.

3.2 New Imports

Importing a new set of items into Jama Connect is generally straightforward. If you're looking for the step-by-step import procedure, refer to the official documentation: Import Items or Test Cases from Excel.

Most first-time import issues aren't caused by the import wizard itself; instead, they're caused by a handful of setup decisions made before clicking Import.

Keep these points in mind:

• Your Excel column headers don't need to match your Jama Connect field names. During the import, you'll map each Excel column to the appropriate Jama Connect field.
• Default values can save time. Many field types allow you to specify a default value during import, reducing the amount of data you need to populate in Excel. Rich text fields are a notable exception.
• Verify the worksheet you're importing. If your workbook contains multiple sheets, confirm you've selected the correct one.
• Verify the header row. Jama Connect allows you to specify which row contains your column headers, so don't assume it's always the first row.
• Verify the destination in the Explorer Tree. Items are imported into the location you select, and that location determines the Item Type being created. Selecting the wrong destination is one of the quickest ways to end up with incorrectly typed items.

Consultant Tip: Don't Bypass a Test Run

Before importing hundreds of rows, perform a small test import using five to ten representative items. It's much easier to verify field mappings, hierarchy, and default values on a handful of items than after a large import.

Keep an Eye Out: Always Confirm Your Import Location

The destination determines the Item Type being created. Importing into the wrong location won't just put your items in the wrong place; it creates the wrong type of item.

3.3. Round Trip Imports

Round Trip imports are where Excel imports become much more than a migration tool. They synchronize changes back into existing Jama Connect items while preserving their identity and history.

The mechanics of performing a Round Trip export are covered in the official documentation: Export/Import via Jama Connect to Excel (Round Trip). This section focuses on the decisions that determine whether your Round Trip behaves the way you expect.

A Round Trip Import always begins with a Round Trip export. The export isn't just a snapshot of your project; it's the context Jama Connect uses to identify existing items during import. Before exporting, configure the list view in Jama Connect to include the fields you'll need for your update.

Consultant Tip: Round Trip Exports Aren't Frozen

Many users treat a Round Trip export as a read-only snapshot of their data. It isn't.

After exporting, you can:

• Add new columns for additional Jama Connect fields.
• Populate newly created custom fields.
• Import only the fields you actually want to update by mapping only those columns during import (see Section 2.1 Understanding Jama Connect’s Data Model).

This flexibility makes Round Trip useful for much more than simple data updates.

Keep an Eye Out: Don't Copy API IDs to New Rows

When adding new items or Test Steps to a Round Trip spreadsheet, leave Jama's API ID fields blank for the new rows. API IDs identify existing Jama records; copying an existing ID into a new row can cause the import to fail or produce unexpected results. This is especially important when adding new Test Steps to an existing Test Case, since copying an existing step row also copies its API ID. Preserve the exported IDs only for existing items you intend to update.

One clue that you may have a conflict as described above is this error from the Import Wizard:

Excel Wins vs. Jama Connect Wins

The import mode you choose determines how Jama Connect resolves conflicts between your spreadsheet and existing data. See Section 3.1 Understanding Import Behavior Modes.

On Conflict, Excel Wins

Use when the spreadsheet should become the source of truth.

If the same field has been modified in both Excel and Jama Connect, the value in Excel overwrites the value in Jama Connect.

This is typically the right choice for planned bulk updates where you've intentionally prepared the spreadsheet with the values you want.

On Conflict, Do Not Update (Jama Connect Wins)

Choose this option when you want to preserve existing Jama Connect data while adding new information. This mode is particularly useful when:

• importing newly added fields into an existing project;
• populating fields that were previously blank; or
• importing data into projects where other users may have made changes since the export.

It allows you to extend your data without accidentally overwriting work that has already been completed in Jama Connect.

Consultant Tip

Jama Connect Wins is often overlooked, but it's one of the safest ways to introduce new custom fields into an established project without risking unintended updates to existing content.

Fields You Can't Change

Some fields exist only so Jama Connect can identify and manage items internally. Leave these fields exactly as exported.

Examples include:

• Global ID
• Project ID
• Other Jama Connect managed system identifiers (API-ID)

Keep an Eye Out

Changing or deleting Jama Connect managed identifier fields prevents Jama Connect from matching your spreadsheet back to existing items correctly. Those fields aren't there for you; instead, they're there for Jama Connect.

3.4 Mapping Fields Correctly

Once your file is uploaded, the field-mapping step determines how Jama interprets your spreadsheet. The mechanics are covered in the official documentation; the guidance below focuses on the decisions that matter most.

Watch for missing required fields. The Data Import Wizard doesn't indicate which fields are required. You'll only discover missing mappings when you click "Next." The screenshot below shows the type of error you'll receive:

Save your mapping configuration after a clean run. Name it descriptively (“Req_Import_v2_2026”) so you can reuse it without re-mapping every time.

Consultant Tip: Saved Mappings Don’t Disappear

Saved mappings are scoped to the user, project, and item type. If a mapping "disappears," verify that:

• You're logged in as the same user.
• You're importing into the same project.
• You're importing the same item type.

If any of those change, the saved mapping won't appear.

3.5 Building Hierarchy During New Imports

One of the biggest advantages of Excel import is that you can build entire sections of your Explorer tree during import instead of creating folders and moving items afterward. Jama Connect uses two mechanisms for importing hierarchy: highlighted fields and indentation.

Jama Connect documentation explains how to use highlighted rows and indentation independently; the example below demonstrates how they can work together:

1. First, highlight the fields/rows in your spreadsheet that you want to designate as a folder:

2. Next, use indentations, and be sure to look closely at the levels. Notice Requirement 1 must be indented at the same level as folder 3.1.1 in the spreadsheet. Both should become children of folder 3.1. Otherwise it will end up being interpreted like this:

3. Once you are ready for import, select the following options:

4. These settings allow Jama Connect to interpret both your indentation and highlighted rows together, producing the hierarchy shown in the spreadsheet example at the top of this section.

Keep an Eye Out: White Fill Isn't "No Fill"

If your hierarchy doesn't import as expected, double-check both your cell fill and indentation levels. See Section 2 for details on how Jama Connect interprets cell fill.

Keep an Eye Out: Use Distinct Names for Test Case Folders and Test Cases

When using indentation or highlighting to create folder structure for Test Cases, use a different name for the folder and the Test Case. If the folder and Test Case have the same name, the Test Case and its test steps may not be imported.

3.6 Handling Relationships During Import

Relationships are imported differently than item data. Jama Connect doesn't automatically create relationships simply because another item's identifier appears in your spreadsheet. Instead, relationship creation is handled separately using the Relationship Import Plugin, which is why a two-pass approach is recommended.

Two-Pass Strategy:

1. Pass 1 – Import or create all parent and child items in Jama Connect. Record a unique identifier for every item (for example, Global ID, Document Key, or a custom external ID field) that can be used to match items during the relationship import.
2. Pass 2 – Create a CSV containing the upstream and downstream unique identifiers, then import it using the Relationship Import Plugin.

For organizations with more advanced automation requirements, relationships can also be managed through the REST API. See Section 5.3: Knowing When to Move Beyond Excel.

Consultant Tip: Relationship Import for European Customers

If you're using the Relationship Import Plugin in a European locale and it doesn't behave as expected, see: Relationship Import Plugin Not Working for European Jama Connect Users.

Consultant Tip: One CSV For Each Relationship Type

The relationship import plugin will not automatically map all relationship “Display names” based on your project Traceability Information Model Configuration; instead, it will map all relationships in the CSV as one relationship name/type. Create a separate CSV for each relationship type.

Consultant Tip: Generate Relationship Sheets with Excel Functions

Use Excel's VLOOKUP, XLOOKUP, or Power Query to generate relationship sheets automatically from exported Jama Connect data. This reduces manual effort and significantly lowers the risk of incorrect identifiers.

Keep an Eye Out: Relationships Aren't Resolved During the Same Import

It may seem intuitive that Jama Connect could create relationships if the referenced item appears elsewhere in the spreadsheet. In practice, relationship creation should be treated as a separate operation after all items have been imported.

Keep an Eye Out: Format Relationship CSV File Carefully

The CSV used for relationships may only contain data in two columns (A and B), and every row must have an upstream/downstream pair. Check your import file carefully, as Jama Connect may fail silently on orphaned references.

See Preparing Your CSV File

Additional Resources

• Beyond the Import Wizard: A Field Guide to Excel Imports in Jama Connect
• Section 1 - Summary and Guide Overview
• Previous: Section 2 - Foundations or Before You Click "Import"
• Next: Section 4 - Validation and Verification After Import
• Section 5 - Advanced Strategies and Nuances
• Section 6 - Lessons from the Field
• Importing Items via Excel
• Import Items or Test Cases from Excel
• Export/Import via Jama Connect to Excel (Round Trip)
• Best Practices for Data Structuring in Jama Connect®: Item–Subitem vs Folder–Item Approaches
• Relationship Import Plugin
• Relationship Import Plugin Not Working for European Jama Connect Users
• Preparing Your CSV File

Feedback:
We welcome your input! Please sign in to leave any comments, suggestions, or ideas for improvement below.