How to import entities from a CSV file

Edit online

The Import feature allows you to upload a CSV file and import entities (e.g., User Stories, Tasks) into the system.

You can import CSV files for Portfolio Epics, Epics, Features, User Stories, Tasks, Bugs, Requests, Requesters, Users, Test Cases, and Impediments in Targetprocess.

Files in CSV (Comma-separated values) format are commonly used to transfer data between spreadsheet editors (such as Microsoft Excel, OpenOffice, LibreOffice, Google Sheets) and other software systems and tools. Targetprocess supports CSV files both for Import and Export purposes.

Import from CSV files is just one method of batch data update in Targetprocess. To learn about other supported methods, see How to migrate or import data to Targetprocess from other project management system.

How to prepare the CSV data file

You can create a source CSV file manually. Use any available spreadsheet editor such as Microsoft Excel, OpenOffice, LibreOffice, Google Sheets. All of them support saving data to a CSV file format.

How to perform the Import

Let’s say, you want to quickly create a project backlog for a new project. Instead of adding each user story manually, you decide to import them in bulk.

Create a simple list with several user stories in Excel and save the file as user-stories.csv.

To upload a CSV file:
  1. Navigate to Settings < Import.
  2. To upload your file, you can either drag and drop the file or click upload box to select a file from your computer.
  3. Choose what type of entities you want to import from the Select Type of Entities dropdown menu.
  4. In the Specify Entity Type Column field, enter the column name in your CSV that defines entity types (e.g., Entity Type).
    Note:

    This is required if your file contains multiple entity types.

  5. (Optional) Choose one or more projects from the Select Related Projects dropdown menu.
    This helps:
    • Automatically map columns
    • Make project-specific custom fields available

    If no project is selected, all custom fields will be available for mapping.

  6. Choose how values in the CSV are separated from the Select Column Delimiter dropdown menu.
    Note:

    Default delimiter is Comma (,).

  7. Click the Next.

    importing csv files into targetprocess

  8. In the Select Type to Import section, choose UserStory if you want to import User Stories, or e.g. TestCase for Test Cases. Click Next.

    selecting the entity type

  9. In the Map CSV columns section, map CSV columns to the system fields and click Next.

    mapping columns

  10. Import completed. Click Next.
  11. View the import log.

Delimiters

Targetprocess accepts four delimiters:

  • , (comma)
  • ; (semicolon)
  • the Tab character
  • | (the vertical bar character)

Targetprocess cannot detect the delimiter used in your file automatically. If something goes wrong and columns are not recognized please verify what delimiter is actually used in the file within plain text viewer such as Notepad tool.

Step 2: Select Type to Import

To define which entities will be imported, use the Select Type to Import step.
  • Each entity type is imported separately.
  • After completing the import for one entity type, the wizard will return to this step so you can select another type to import.
  • If an entity type was already selected in Step 1, the wizard will skip this step and proceed directly to Step 3.

Step 3: Map CSV Columns

Your CSV file must include a Project column (either Project ID or Project Name) mapped to the Project field. The import will fail if this mapping is not provided.

ID mapping behavior:
  • If the ID field is not mapped, all records will be created as new entities.
  • If the ID field is mapped but contains empty values, the records will also be created as new entities.
  • If the ID field is mapped and contains values, the system will attempt to update existing entities with matching IDs.
Required vs optional mappings:
  • Required: Project (and ID, depending on whether you want to update existing entities)
  • Optional: All other fields can be mapped as needed

Step 4: Perform Import

Start the import process.

Step 5: View Log

Review import results and errors.

Import entities in a single project

The project column is not required when all the entities you import belong to the same project. You can exclude the Project column from your CSV file. Instead, select this single Project in the list of projects displayed in Step 1 of the Import wizard.

Otherwise, you have to specify the Project for your entities. The project column is required in your CSV file and should be mapped properly. You can use either numeric Project ID or text Project Name as values in the column. In this case, you may select none or two and more Projects on Step 1 of the Import wizard.

Permissions

The Team and Role access permissions remain intact for Import. Administrators can import entities to any project and team, even to the ones they are not members of.

Entities and fields mapping

For a complete list of entities and fields that can be imported and used during column mapping, see Entities and fields supported for import from CSV files.

  • Map each CSV column to the appropriate Targetprocess field, or select Skip to exclude it.
  • For example, map Estimated Effort (CSV column) to the Effort field of a User Story.
  • You can also map custom fields.

Guidelines:

  • The system attempts to automatically map columns, but you should review and adjust mappings as needed.
  • You cannot map multiple CSV columns to a single Targetprocess field.
  • You can skip the first row if it contains column headers instead of data.

Procedure:

  1. Complete column mapping.
  2. Click Next.

The system will either start the import (Perform Import), or display warnings if mapping issues are detected.

After the import completes, select View Log to review the results.

Import of hierarchical backlog

You can import features, user stories and tasks into your backlog within a single CSV file. For more information, see Import Hierarchical Backlogs from CSV Files.

Productivity Tips

  • Ensure your CSV file:
    • Uses correct column headers
    • Matches the selected delimiter
  • Include an Entity Type column if importing multiple entity types
  • Select related projects to simplify mapping
Iteratively test Import with small data snippet
Testing with a small dataset helps identify and resolve issues early, reducing the risk of errors in large imports. When performing a data import for the first time, start with a small sample of your data.
  • Prepare a test file with 2–5 rows only.
  • Run a test import to verify that:
    • Data formatting is correct
    • Column mappings are accurate
    • Values are recognized as expected
If issues occur:
  • Delete the test entities
  • Fix any data or mapping problems
  • Repeat the test import

Once the sample import works correctly, proceed with importing the full dataset.

Validate data after Import on a List view
After the import is complete, verify the results in the system:
  1. Create a new List view: Apply filters to display only the imported entities.
  2. Adjust columns: Customize the view to show the same columns as in your CSV file.
  3. Compare data:
    • Review the records in the system alongside your CSV file.
    • Ensure that all values have been imported correctly and mapped as expected.

Troubleshooting

Entity Type Names Are Incorrect

If your CSV file includes an Entity Type column and the import proceeds past column mapping but no entities are created, verify the values in this column.

  • Entity type names must not contain spaces and must match the expected format.
  • Example:
    • Earlier versions: UserStoryTestCase
    • Later versions: User StoryTest Case

Ensure the format matches your application version.

Missing Mandatory Fields

If the import fails or does not create entities:

  • Verify that all required fields are mapped in the mapping step.
  • Ensure that these fields are populated with valid values in the CSV file.
Line Breaks Not Preserved in Descriptions

CSV files do not preserve line breaks by default.

  • To retain line breaks in text fields such as Description, use the HTML tag: HTML<br />

    Show more lines

Fields Not Available for Mapping

If expected entity types or custom fields are missing in the mapping dialog:

  • Check that the correct projects are selected in the import context.
  • Confirm that your user account has access and membership in those projects.
Setting Creation Date During Import
  • The Creation Date is important for history tracking and affects related fields such as Start Date and End Date.
  • For existing entities, the Creation Date cannot be modified.
  • For new entities, you can specify a custom Creation Date during import.
  • Start Date and End Date cannot be earlier than the Creation Date.
Non-English Characters Not Imported Correctly

If your CSV file contains non-English text, save the file using UTF-8 with BOM format to ensure proper character handling.

Large Files and Performance Issues

Importing very large CSV files can be slow or unstable.

  • Imports with thousands of rows may take several hours.
  • In some cases, the process may stop before completion.

Recommendation:

  • Split large files into smaller batches of 500–1000 records each to improve reliability and performance.