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 or Comments 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 |
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
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
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
- Fill your data in the designated sheet following the format guidelines
- Export as CSV when ready to import
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.
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
These templates include detailed troubleshooting guides with specific solutions for validation errors.