Beyond the Import Wizard: Section 1 - Summary and Guide Overview

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 the engineer who just wants the answer and to move on.

If you're looking for a step-by-step guide to importing Excel files into Jama Connect®, stop. This isn't that article.

Don't Panic.

Most Excel imports don't fail because of Excel. They fail because of a handful of project configuration and import decisions that aren't obvious until you've been bitten by them. Understanding how Jama Connect interprets your data is just as important as preparing the spreadsheet itself.

This guide is intended to answer the questions that usually come before you've started trying to import complex Excel spreadsheets or after an import didn't behave the way you expected. Common edge cases, consultant tips, and links to the existing documentation are provided so you can better understand how Excel imports, Round Trip imports, and project structure behave in real-world scenarios.

Whether you're importing for a new project, updating existing items, or troubleshooting a complex Round Trip, this guide will help you understand the "why" behind the behavior.

Resolution

1.1 The One Golden Rule

Your Excel template is your contract with the Jama Connect import wizard. Treat it like a schema definition, not a spreadsheet. Your column headers don't need to match Jama Connect field names (the import wizard allows the user to map those), but every cell value must match your Jama Connect project field configurations.

Preparing a spreadsheet is only half the job. How Jama Connect interprets that data depends on your project configuration, field definitions, workflows, permissions, and the import options you choose.

1.2 What This Guide Covers

Rather than replacing existing documentation, this article connects it together and fills in the gaps that users commonly encounter, including:

When Round Trip updates existing items (and when it doesn't).
Why workflow fields and locked items don't always behave as expected.
When to use highlighting, indentation, or both to create hierarchy.
Common import behaviors that aren't obvious from the import wizard.
Practical validation and troubleshooting strategies for imports that don't behave as expected.

Throughout the guide you'll find links to existing documentation for step-by-step procedures, along with consultant tips that explain the nuances and edge cases frequently encountered during real-world migrations and bulk updates.

1.3 Top 3 Mistakes to Avoid

Importing without doing a dry run: Never. Do. This. Skipping the validation step (or importing straight to Production) means you discover structural errors after 847 items are half-imported. See Section 4.3: Verify with a Small Test Import.
Assuming Jama Connect determines the Item Type from your spreadsheet: It doesn't. The destination you choose during import determines the Item Type being created. Importing into the wrong location creates the wrong Item Type, even if the spreadsheet itself is perfectly correct. See Section 2.1: Understanding Jama Connect's Data Model (Item Types vs. Fields).
Assuming relationships can be imported directly in your Excel template: They can't. Importing relationships is a two-pass effort: first you import item data, then you establish relationships separately using the relationship plugin or REST API script. Plan for this upfront. See Section 3.6: Handling Relationships During Import.

1.4 Pre-Import Checklist

One item type per Excel tab/workbook. Jama Connect imports one item type at a time. Don't mix Requirements and Test Cases in the same sheet (see Section 2.2 if you're starting with a mixed-item spreadsheet). Round Trip caveat: A Round Trip export can contain multiple Item Types, but field mapping still applies to one Item Type at a time.
Column headers can be any name; you'll map them to Jama Connect fields during import.
All required fields are populated (or assigned a default value where supported). Rich text fields cannot use default values. See Section 2.5.
Picklist and multi-select values copied directly from Jama Connect (or retype carefully because they are case-sensitive).
Use highlighting and/or indentation to let Jama Connect build your hierarchy during import. See Section 3.5: Building Hierarchy During New Imports.
Two-pass strategy planned for relationships (import items first, relationships second).
Dry-run import completed against a test project.
Use .xlsx unless you have a specific reason to use CSV. See Section 2.4 The CSV Question.

Additional Resources

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

Related to