Data Importer
Overview
The Data Importer is a powerful tool that allows you to import project-specific data into your Zymmr instance. This functionality streamlines the process of migrating from other project management tools or importing bulk data from CSV files.
Available Now
The Data Importer functionality is now available for all Zymmr users. This self-service tool enables you to import data without requiring assistance from our support team.
Accessing the Data Importer
To access the Data Importer functionality:
- You must have Global Admin privileges
- Click on the Settings gear icon (⚙️) in the top-right navigation bar next to your profile avatar
- In the sidebar that appears, select Data Importer
The Import Dashboard: Your Import History
The main Data Importer screen serves as a dashboard, providing a complete history of all past import operations. It helps you track, review, and troubleshoot your import history.
- + New Import Button: The primary button, located in the top right, to start a fresh data import.
The dashboard table includes the following information:
| Column | Description |
|---|---|
| DATE | The timestamp indicating when the import was performed. Click this to view the Import Details page. |
| IMPORTED PROJECT | The Zymmr project into which the data was imported. |
| TYPE | Specifies whether the import contained Work Items, Time Log, Comments, Test Suite or Test Case data. |
| FILE | The name of the original CSV file that was uploaded. |
| IMPORTED WORK ITEM COUNT | The number of records from the file that were successfully imported into Zymmr. |
| TOTAL WORK ITEM COUNT | The total number of records found in the uploaded CSV file, helping you spot any import discrepancies. |
The Import Details:
You can access the details of any past import by navigating to the Import Dashboard and clicking the DATE for the desired entry.
Import Context Header: The header at the top of the page provides the context for the import, showing the Project, the data Type (e.g., Work Item), and the name of the File that was used. On the right side of this header is the Column Mappings Button, which allows you to re-open the mapping modal to review or adjust the settings for this specific import.
Import Summary: A box below the header provides vital statistics, such as Found X records and Y columns and confirms if any warnings were found during the validation process.
Data Preview Table: This table displays the actual data from your CSV file as it was read by Zymmr. It allows you to visually verify that the correct data was processed and troubleshoot any issues by reviewing the source data.
Supported Import Types
The Data Importer currently supports importing:
| Import Type | Description | Template |
|---|---|---|
| Work Items | Tasks, bugs, epics, and other work item types | Work Item Import Template |
| Time Logs | Time tracking entries associated with work items | Time Log Import Template |
| Comments | Discussion threads and feedback on work items | Comment Import Template |
| Test Suites | Hierarchical suites (up to 5 levels) for organizing test cases | Test Suite Import Template |
| Test Cases | Test case definitions with steps, linked to suites, priorities and modules | Test Case Import Template |
Import Templates Available
We've created comprehensive import templates with detailed field documentation, validation rules, and sample data. These templates include step-by-step guides to help you prepare your data correctly and avoid common import errors.
Import Process
Step 1: Start New Import
Start the import process by clicking on the New Import button present on top right section of data importer page.
Step 2: Select Project
Begin by selecting the project you want to import the data into. This ensures that all imported data is associated with the correct project in your Zymmr instance.
Step 3: Choose Import Type
Select what type of data you want to import:
- Work Items
- Time Logs
- Comments
- Test Suite
- Test Case
Test Management import order
Import Test Suites before Test Cases in the same project. The Test Case importer only links to suites that already exist. See Importing Test Management Data.
Step 4: Upload CSV File
Click on the "Attach" button under the "Import File" label and select the CSV file you want to import.
Once your file is selected:
- The importer will upload the data into your instance under the "files" section for future reference
- You'll see details about your uploaded file, including the total number of records found and the number of columns in the file
Step 5: Map Columns
Note
The following steps assume you've selected Work Items as your import type in step 2. The mapping interface will show different fields based on your selected import type.
Click on the "Map Columns" button to open the column mapping interface:
- On the left side, you'll see the columns from your uploaded file (view only)
- On the right side, you'll see the available work item fields in Zymmr
- Map each column from your file to the appropriate work item field
- Required fields must be mapped to proceed with the import
Important Mapping Considerations
| Field | Behavior if Not Mapped |
|---|---|
| Creation Date | Current date will be used |
| Owner (Created By) | Current global user will be set as owner |
| Status | Must be mapped to "Workflow State" field |
Step 6: Validate Data
Click the "Validate" button to check your data for any issues:
Validation Process
The validation process helps identify potential issues before importing your data. Addressing these issues will ensure a smooth import experience.
The importer will validate the data and display any validation warnings in a table with the following information:
| Column | Description |
|---|---|
| Type | The type of validation warning (e.g., Required Check Failed, FieldType Validation Failed, Email Not Found in Linked User Table) |
| File Column | The column in your file causing the warning |
| Mapped Column | The corresponding work item field |
| File Row | The specific row in your file with the issue |
| Warning | A detailed message explaining the issue with suggestions to fix it |
| Default | The default value that will be used if the validation issue is ignored |
You can choose to:
- Resolve the warnings by correcting your column mappings
- Update the data format in your file
- Ignore the warnings and proceed with the import
Step 7: Start Import
Click the "Start Import" button to begin the import process:
Import Progress
The import process will show real-time progress and estimated completion time.
- A progress indicator will show the number of records imported so far
- An estimated time remaining will be displayed
- Do not close or refresh the page until the import process is complete
- Once complete, you can close the modal by clicking the "Close" button
Step 8: Verify Imported Data
After the import is complete, verify that your data has been imported correctly by checking the work items in your project.
Preparing Your Import File
Using Import Templates
We strongly recommend using our pre-built import templates to ensure successful data imports:
Work Item Import Template
- Link: Work Item Import Template
- Contains: Complete field documentation, validation rules, sample data, and troubleshooting guide
Time Log Import Template
- Link: Time Log Import Template
- Contains: Duration formats, user validation, work item linking, and realistic sample entries
Comment Import Template
- Link: Comment Import Template
- Contains: Date format, user validation, work item linking, and realistic sample entries
Test Suite Import Template
- Link: Test Suite Import Template
- Contains: Suite hierarchy with Parent Path, status values, validation rules, and a sample suite tree
Test Case Import Template
- Link: Test Case Import Template
- Contains: Single-row and multi-row step formats, suite/priority/module linking, validation rules, and sample cases that match the Test Suite template
How to Use Templates
- Make a copy of the template to your Google Drive
- Review the "Import Guide & Format" tab for complete documentation
- Use the "Sample Data" tab as reference for your data structure. The Test Case template has two: Sample Data (Single Row) and Sample Data (Multi Row)
- Fill your data in the designated sheet following the format guidelines
- Export as CSV when ready to import (File > Download > Comma-separated values). Only the active sheet is exported
Manual File Preparation Guidelines
If creating your own CSV file, ensure it follows these guidelines:
User Fields
Fields such as Owner, Primary Assignee, Secondary Assignee, and Reporter must contain the email address of the user in the corresponding column.
Important
Email addresses must match existing users in your Zymmr instance.
Date Formats
| Field Type | Format | Example |
|---|---|---|
| Date fields | YYYY-MM-DD | 2023-12-31 |
| Datetime fields | YYYY-MM-DD HH:MM:SS | 2023-12-31 14:30:00 |
Custom Fields
You can map custom fields from your file to custom fields in Zymmr.
Importing Test Management Data
Use these two imports to bring existing test suites and test cases into Test Management. Run them as two separate imports in the same project, in this order:
- Test Suite: builds the suite tree.
- Test Case: creates cases and links them to the suites from step 1.
Order matters
The Test Case importer does not create suites. If a case references a suite that doesn't exist in the selected project, that suite link is dropped and the case is imported without it.
The sample data in both templates is designed to be imported together. Importing the Test Suite sample first and then the Test Case sample gives you a working tree with every case linked.
Test Suite Import
Fields
| Field | Required | Type | Accepted values / format |
|---|---|---|---|
| Title | ✓ Yes* | Text | Unique suite title within the project, e.g. Regression, Auth, Work Items |
| Description | Optional | Text | Free text. Saved on create only |
| Status | Optional | Select | Active or Archived. Blank or invalid values default to Active |
| Parent Path | Optional | Path | Segments separated by / or >, e.g. Regression, Regression>Auth. Max 5 levels |
| Parent Test Suite | Optional | Link to Test Suite | Exact title of a suite that already exists in the project, e.g. API |
* Title can be left blank only when Parent Path already names the suite itself (see below).
How Parent Path works
Parent Path both resolves and creates suites. Any missing ancestors are created under the selected project.
| Title | Parent Path | Result |
|---|---|---|
Regression | (blank) | Root suite Regression |
Auth | Regression | Auth created under Regression |
Password | Regression>Auth | Password created under Regression › Auth (ancestors created if missing) |
Auth | Regression/Auth | Title equals the last segment, so the path is the suite: Regression › Auth |
| (blank) | Regression/Auth | Same as above; the last segment is used as the suite |
- Use Parent Path to build a new tree.
- Use Parent Test Suite only when the parent already exists. Only titles are accepted here, not paths.
- If both are set, Parent Path wins and Parent Test Suite is ignored.
Re-importing existing titles
Suite titles are unique per project. If a row's title matches an existing suite, the importer reuses that suite and does not update its parent, description, status or order. To move or edit an existing suite, do it from the Test Management UI.
Sample
| Title | Description | Status | Parent Path | Parent Test Suite |
|---|---|---|---|---|
| Regression | Root suite for product regression coverage. | Active | ||
| Auth | Authentication flows under Regression. | Active | Regression | |
| Checkout | Checkout and payment flows under Regression. | Active | Regression | |
| Password | Password reset coverage under Regression/Auth. | Active | Regression>Auth | |
| Smoke | Root suite for smoke coverage. | Active | ||
| API | Root suite for API coverage. | Active | ||
| Work Items | Work item API coverage under API. | Active | API | |
| Archive | Archived suite for deprecated coverage. | Archived |
In the import wizard, select Test Suite as the import type.
Test Case Import
Fields
| Field | Required | Type | Accepted values / format |
|---|---|---|---|
| Title | ✓ Yes | Text | Max 140 characters. Required on every single-row case and on the first row of each multi-row group |
| Description | Optional | Text Editor | Plain text or HTML |
| Priority | Optional | Link to Priority | Existing Priority title, case-sensitive, e.g. Low, Medium, High |
| Status | Optional | Select | Draft, In Review, Active, Deprecated. Blank defaults to Draft |
| Test Suite | Optional | Link to Test Suite | Suite title or path (A/B/C or A>B>C). Comma-separate for multiple, e.g. Smoke, Regression |
| Modules | Optional | Comma-separated titles | Existing Module titles in the project, e.g. Payments, Orders |
| Precondition | Optional | Text | Saved on the Test Case Version |
| Expected Result | Optional | Text | Case-level expected result, saved on the Test Case Version. Not a step result |
| Step Action | Optional | Text | The action for each step |
| Step Data | Optional | Text | Test data for each step |
| Step Expected Result | Optional | Text | The expected outcome of each step |
| Step Number | Optional | Integer | Whole numbers (1, 2, 3). If omitted, steps are numbered 1..N |
| Case ID | Optional | Text | Grouping key for multi-row steps only, e.g. TC-1. Not saved in Zymmr |
Suites, priorities and modules must already exist
Test Suite, Priority and Module values are looked up in the selected project and never created. Missing suite and module references are omitted from the case.
Choosing a step format
The template ships with two sample sheets. Pick one format per import file.
Single row: one row per test case. Put every step in the same cell and separate them with real line breaks (Alt+Enter on Windows, Option+Enter on Mac). Line N of Step Action lines up with line N of Step Data and Step Expected Result. If a step has no data, leave that line empty so the lines stay aligned.
| Case ID | Title | Status | Test Suite | Step Action | Step Data | Step Expected Result |
|---|---|---|---|---|---|---|
| TC-1 | Login with valid credentials | Active | Regression/Auth | Open the login page Enter valid email and password Submit the login form | user1@zymmr.in / Pass@123 | Login form is displayed Credentials are accepted Dashboard loads with the user session |
Multi row: one row per step. The first row of a case holds Case ID, Title and the other case fields. Following rows leave Case ID and Title blank and fill only the step columns. Rows are grouped by Case ID, then Title.
| Case ID | Title | Status | Test Suite | Step Number | Step Action | Step Data | Step Expected Result |
|---|---|---|---|---|---|---|---|
| TC-1 | Login with valid credentials | Active | Regression/Auth | 1 | Open the login page | Login form is displayed | |
| 2 | Enter valid email and password | user1@zymmr.in / Pass@123 | Credentials are accepted | ||||
| 3 | Submit the login form | Dashboard loads with the user session |
Enable "Multiple rows per test case" for multi-row files
In the import wizard, select Test Case as the import type. If your file uses the multi-row format, check Multiple rows per test case. Leave it unchecked for single-row files.
Common step-format mistakes
- Making the row taller instead of pressing Enter inside the cell. Only real line breaks create separate steps.
- Separating steps with commas instead of line breaks.
- Adding a step-only row before any row that has Case ID or Title.
- Putting a step's expected result in the case-level Expected Result column.
Test Management Troubleshooting
| Warning | Import | Cause | Fix |
|---|---|---|---|
| Required Check Failed | Test Suite | Title is blank and Parent Path doesn't name the suite | Fill Title, or make the last Parent Path segment the suite name |
| Depth Limit Exceeded | Test Suite | Parent Path is deeper than 5 levels | Keep paths to 5 segments or fewer |
| Parent Test Suite Not Found | Test Suite | Parent title doesn't exist in the project | Import the parent first and use its exact title, not a path |
| Invalid Status | Test Suite | Value isn't Active or Archived | Use Active / Archived, or leave it blank |
| Duplicate Title | Test Suite | A suite with that title already exists | Expected behavior: the existing suite is kept unchanged. Use a new title to create another suite |
| Required Check Failed | Test Case | Title missing on a case, or on the first row of a multi-row group | Fill Title on every case or group's first row |
| Test Suite Not Found | Test Case | Suite title/path doesn't exist in the project | Import Test Suites first, then use the exact title or path |
| Module Not Found | Test Case | Module title doesn't exist in the project | Create the module first or fix the title |
| Multi-row continuation has no preceding identity | Test Case | A step row appears before any row with Case ID or Title | Put Case ID and Title on the first row of each group |
| Invalid Status | Test Case | Value isn't one of the allowed options | Use Draft, In Review, Active or Deprecated |
Best Practices
For Successful Imports
- Use our import templates - Start with our pre-built templates to avoid common formatting issues
- Review template documentation - Each template includes comprehensive guides and validation rules
- Test with sample data first - Use the provided sample data to understand the correct format
- Prepare your CSV file with clean, consistent data
- Ensure all required fields are included
- Verify user email addresses exist in the system
- Use correct date formats
- Back up your data before importing
Troubleshooting
If you encounter any issues during the import process, check for validation warnings and ensure your data follows the format requirements. Common issues include:
| Issue | Solution |
|---|---|
| Email addresses not found | Verify users exist in your Zymmr instance |
| Incorrect date formats | Format dates as YYYY-MM-DD or YYYY-MM-DD HH:MM:SS |
| Missing required fields | Ensure all required fields are mapped |
| Invalid field values | Check validation warnings and correct data |
Need Help with Format Issues?
If you're experiencing data format or validation errors, consult our import templates:
- Work Items: Work Item Import Template
- Time Logs: Time Log Import Template
- Comments: Comment Import Template
- Test Suites: Test Suite Import Template
- Test Cases: Test Case Import Template
These templates include detailed troubleshooting guides with specific solutions for validation errors.