Beyond the Import Wizard: Section 2 - Foundations or Before You Click "Import"

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 new users and first-timers, with depth for anyone who’s ever had an import fail silently or corrupt data.

Resolution

2.1 Understanding Jama Connect's Data Model (Item Types vs. Fields)

Core Concept:
Jama Connect doesn’t just store “rows”, it stores structured items, each tied to an Item Type (e.g., Requirement, Test Case, Risk). Each Item Type defines:

Which fields are available (e.g., “Description”, “Priority”, “Status”)
Which fields are mandatory (Name)
What data types those fields accept (text, number, date, single-select picklist, etc.)

Why It Matters for Excel:

Jama Connect doesn't determine an item's type from the contents of your spreadsheet. The destination you choose during the import determines what item type is created.

If you accidentally import into the wrong item type, you'll still create items, but the available fields may not match your spreadsheet. Any columns that aren't mapped simply aren't imported.

Consultant Tip: Unmapped Fields as an Import Strategy

Unmapped columns aren't always a mistake. If you're performing a Round Trip update and only want to modify a single field, intentionally map only that field.

Jama Connect ignores unmapped columns, allowing you to update just the data you care about.

Consultant Tip: You Don't Have to Start with an Export

A common misconception is that every Excel import begins with exporting data (or the item type structures) from Jama Connect. For new imports, you can build your spreadsheet from scratch as long as it contains the required data and you map the fields correctly during import.

Exporting first is only necessary for update scenarios such as Round Trip imports.

2.2 The Anatomy of a Valid Excel File

A valid import file isn’t just “data in rows.” It needs structural integrity:

Element	Requirement	Why It Matters
Header Row	One row in the worksheet must contain column headers	Jama Connect matches headers to fields, but you can select which row is your header row during import.
One Item Type per Sheet	Each worksheet should contain only one Item Type	Not required, but mixed types will ALL be imported as a single item type, determined by the import location selection.
No Merged Cells	All cells must be unmerged	Jama Connect can’t parse merged cells reliably. This becomes relevant when importing multiple test steps into test cases.
No Hidden Rows/Columns	All data must be visible	Hidden rows are still imported. Hiding rows in Excel does not exclude it from the import, which may result in importing data you didn’t want.

Table 2.1: Essential Components of an Excel Import File

Consultant Tip: The “Copy-Paste-Separate” Work-Around

Many users start with one big sheet containing mixed Item Types. Here’s how to fix it cleanly:

Copy the entire sheet to a new workbook.
Filter or sort by Item Type.
Create a new sheet for each type.
Paste only the relevant rows into each sheet.
Name each sheet clearly (e.g., “Requirements”, “Test Cases”).

This avoids the common mistake of expecting Jama Connect to infer item types from mixed data.

Real-World Example

When importing Test Cases with multiple test steps, don't merge the Test Case name across rows. Instead, repeat the Test Case Name on every row. Jama Connect interprets repeated rows as multiple test steps, while merged cells cannot be interpreted the same way.

This behavior is specific to Test Case item types. For complete examples of formatting Test Cases and Test Steps, see:

2.3 Common Pitfalls: Formatting, Hidden Characters, and Stealth Cell Fill

Even perfect-looking data can fail due to invisible issues.

Formatting Traps:

Numbers stored as text: Leading zeros, apostrophes ('123), or comma separators can break numeric fields.
Whitespace & Hidden Characters: Non-breaking spaces ( ), tabs, or carriage returns can invalidate picklist values and change the formatting of rich text fields.
Cell fill colors: Excel cell fill colors can affect how Jama Connect interprets hierarchy. If items unexpectedly import as folders or subsets, check your cell formatting.
Rich text hyperlinks: Excel hyperlinks are not imported as hyperlinks. Rich text fields must contain HTML markup if you want hyperlinks preserved.

What You Cannot Import or Update via Excel:

Categories (these must be created in Jama Connect UI or via API)
Workflow Status transitions (you cannot change a workflow status via excel import)
System-locked Items (system locks prevent updates via Excel; user locks do not)

Consultant Tip: Excel Hyperlinks vs. HTML Hyperlinks

If you want hyperlinks (or similar formatting) preserved during import, include the HTML syntax in your excel spreadsheet before importing. Excel's Insert Hyperlink feature stores hyperlink metadata, not HTML, so only the visible text is imported.

Consultant Tip: Import Before Enabling Workflow

Workflow fields can't be updated through Excel import. Period. If possible, import the bulk of your data before applying a workflow to the item type. Once a workflow is enabled, status changes must follow the workflow itself rather than being imported.

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

One of the most difficult import issues to diagnose happens when a spreadsheet uses a white fill instead of No Fill. They look identical in Excel, but Jama Connect uses cell fill colors to infer hierarchy during import. If items unexpectedly import as folders or subsets, verify that the rows use No Fill rather than a white fill color in your Excel sheet.

Section 2.3.png — Figure 2.1: Excel View to Select "No Fill"

2.4 The CSV Question: When to Use It (and When to Avoid It)

CSV has its place, but for most Excel imports, .xlsx remains the better choice.

Recommended Approach

Use .xlsx for development, testing, and most interactive imports because it preserves formatting, worksheets, and data types.

Consider CSV only when:

automating import pipelines,
working with exceptionally large datasets,
or troubleshooting workbook-related issues.

Why CSV Can Be Better

Simpler structure (no formatting, formulas, or hidden metadata)
Fewer parsing issues for large datasets
Better suited for version control (plain-text diff friendly)

When CSV Breaks Things

Loss of multi-sheet support
Encoding issues (UTF-8 vs ANSI vs system default)
Date and number formatting ambiguity

Consultant Tip: Use UTF-8 When Importing CSV

If you use CSV, always save it as UTF-8 to preserve special characters. Windows' default CSV encoding often uses ANSI, which can corrupt non-Latin characters.

2.5 Quick Checklist: Pre-Import Validation

Before clicking “Import,” run this sanity check:

One Item Type per worksheet.
No merged cells or formulas. Verify that any hidden rows aren't being imported unintentionally.
Picklists (single and multi-select) values must match Jama Connect pick list values exactly.
No leading/trailing whitespace in text fields. Import preserves leading and trailing whitespace exactly as it appears in Excel.
Mandatory fields are populated in spreadsheet (you can set a default value in some cases, but NOT rich text fields).
Workflow values cannot be changed via excel import (even round trip). Use Batch Edit in Jama Connect to update workflow values after import (or see Workflow tip above).

Additional Resources

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

Related to