CSV Import
Ketryx allows bulk creation and updates of items through CSV file imports. This feature is useful for migration intro Ketryx. This feature also enables teams to manage data in spreadsheet tools like Excel and synchronize it with Ketryx continuously, integrating spreadsheet-based workflows into the broader product lifecycle.
How to access
CSV import is accessed from the All Items page via the Import items button.
Use cases
CSV import supports several workflows:
Bulk item creation - Create multiple items of any type from spreadsheet data
Bulk item updates - Update existing items based on a stable identifier
Excel roundtripping - Export data via document templating, enhance in Excel, then re-import
Preparing your CSV file
Required columns
Your CSV file must include at minimum:
Type - The item type for each row (must match item type names in yoru environment)
Title - The title/name for each item
Unique item import ID - A stable identifier used to match rows to existing items. Reccomended format: [PROJECT]-[TYPE]-[INTEGER], such as "KP-RQ-1".
The unique item import ID is stored at the item level and remains stable across revisions once the item is imported. This identifier is used to determine whether a row will create a new item or update an existing one. You can also use the automatically generated Ketryx item ID (KXITM...) for this purpose, especially when updating existing items that were not created via CSV import originally. The Ketryx item ID can be retrieved in bulk (along with any other info) from existing items by using document templating, see this simple example template that retrieves the data required for import:
Supported file format
UTF-8 CSV files only
Single file limit - Only one CSV can be uploaded at a time
Column naming requirements
Column names in your CSV must exactly match the field names in Ketryx:
Use the field names as they appear in the Ketryx interface
Supports fields renamed via Advanced Settings > Field names
Supports custom fields
Supports updating fields on custom item types
Column name matching is case-sensitive and must be exact
Important: The system does not provide column mapping for any fields other than Type and Unique import ID - your CSV column headers must match Ketryx field names exactly.
Field value formatting
Text fields - Enter text directly in cells
Date fields - Use ISO 8601 date format (ex. 1997-02-21)
Datetime fields - Use ISO 8601 datetime format (ex. 1997-02-21T12:00Z)
User fields (ex. Owner) - Not currently supported
Select fields - Use the underlying system option name for any built-in Ketryx fields (you will find these names in the linked documentation). Use the exact option name as it appears in Ketryx for custom fields.
Multi-select fields - Use the underlying system option name for any built-in Ketryx fields (you will find these names in the linked documentation). Use the exact option name as it appears in Ketryx for custom fields. Provide a comma-separated list of values in a single cell:
Relation fields - Reference other items using either:
The unique item import ID of the target item (if the other item was created via import)
The Ketryx item ID (e.g., KXITM...)
For multiple relations, use comma-separated values:
CVSS vectors - If a column contains a CVSS vector string, it will be imported into the CVSS Calculator field as the base vector (special case - contact Ketryx support)
⚠️ Blank cells - Blank cells will clear the corresponding field value for that item
Creating relations
Relations can be created during import in two ways:
To existing items - Reference items already in Ketryx using their item ID (KXITM...) or unique item import ID (if created via import)
Between items in the CSV - Reference other rows in the same CSV using the value that appears in the column that will be used as the unique import ID
When creating relations between items in the same CSV, Ketryx creates all items first, then establishes the relationships. This allows you to define interdependencies within a single import.
Note: Only forward relations can be imported. This will come naturally with the restriction that you must import to fields. Relation fields in Ketryx only appear on the source item and reference the target item (although the relation is represented bidirectionally across the platform and in your documents). Just ensure the name of the column aligns with the data you have in the CSV. For example, when you have a column "Tested items", then you should give the unique import ID or Ketryx item ID for the tested item (ex. a Requirement) on the row of the Test Case. This will create a forward relation from the Test Case to the Requirement. There is no field like "Is tested by" in Ketryx, so you are unable to create a valid CSV that attempts to make a reverse relation.
Note: Cross-project relations are not supported.
Example CSV structure
Import workflow
Step 1: Upload CSV
Navigate to the All Items page
Click Import items
Upload your CSV file
The system validates that:
Column headers are unique
Empty columns are filtered out
Columns with values but no column name are filtered out
Step 2: Map columns
Select which columns contain:
Unique item import ID column - The identifier for matching to existing items
Item type column - The type of item for each row
The system automatically detects other columns that match Ketryx field names.
The system validates that:
The column selected for unique import ID is not duplicated
The column selected for item type is not duplicated
Step 3: Preview
After mapping columns, Ketryx provides a preview showing:
Count of items to be created - New items that will be added
Count of items to be updated - Existing items that will be modified
Count of items where no change is detected - These items will be skipped
Item types - Types of items that will be created/updated
Detected fields - Which CSV columns matched to Ketryx fields
Preview of first several rows - Sample of items to be imported
Errors and warnings - Any validation issues detected
Common warnings include:
Rows missing a unique item import ID (these rows will be skipped)
Duplicate unique item import IDs across rows (these rows will be skipped)
Invalid item types (these rows will be skipped)
Invalid field values
Invalid relations
Review the preview carefully before proceeding.
Step 4: Authorize and execute
To complete the import:
Provide a rationale for the import (optional)
Enter your password for electronic signature
Click Continue to authorize
The import executes and creates/updates items according to the preview.
Step 5: Review results
After import completion:
A log is provided detailing items created, items updated, and any warnings or errors
The log can be downloaded for record-keeping
Import activity is recorded in History > Audit change logs with:
Date and time of import
User who performed the import
Change type: PROJECT_ACTIVITY
Item IDs affected by the import
Rationale provided during authorization
Item update behavior
When an imported row's unique item import ID matches an existing item:
Matched fields are updated - Fields with values in the CSV overwrite existing values
Blank cells clear fields - Empty cells in the CSV will clear the corresponding field
Unmatched fields unchanged - Fields not included in the CSV remain unchanged
Important: Currently, blank cells clear field values. To preserve existing values, ensure all fields in your CSV contain the current data when performing updates. Use document templating to export current values before making changes.
Supported item types
CSV import works with:
System item types - Requirements, Test Cases, Risks, etc.
Custom item types - Any custom item types created in your organization
Renamed item types - Item types renamed via Advanced Settings > Item type names
The system validates that all item types in the CSV are valid. Rows with invalid item types are skipped and logged as warnings.
Best practices
Use document templating for roundtripping - Export items via templating to get properly formatted CSVs with current field values
Test with small datasets first - Validate your CSV structure with a few rows before bulk imports
Review the preview carefully - Check counts, detected fields, and warnings before authorizing
Include all field values for updates - Because blank cells clear fields, include complete data for each field that is included in the CSV when updating. If a column is not included, then nothing will happen (i.e. it will not be cleared)
Provide meaningful rationales - Document the purpose of each import for audit trails
Download import logs - Save logs for troubleshooting and compliance records
Limitations and considerations
CSV only - Excel (.xlsx) files are not supported; save as CSV before import
One file at a time - Each import handles a single CSV file
No column mapping - Column names must exactly match Ketryx field names
Blank cells clear values - Empty cells will clear existing field values
No validation for select field values - Invalid select field values will still populate the field
Project scope - Imports are performed within a single project context
Troubleshooting
Items not being created/updated:
Verify unique item import ID is populated for all rows
Check that item types match exactly (including case)
Ensure no duplicate unique item import IDs in the CSV
Review the import log for specific error messages
Relations not being created:
Confirm target items exist or are defined in the same CSV
Verify unique item import IDs or Ketryx item IDs are correct
Check that relation field names match exactly
Fields not populating:
Verify column names match Ketryx field names exactly
Check for renamed fields in Advanced Settings
Ensure field values are valid for the field type
Duplicate column errors:
Check that the unique import ID column appears only once
Check that the item type column appears only once
Remove any duplicate column headers
Last updated
Was this helpful?