How to import entities from a CSV file

You can import CSV (comma-separated values) files for Epics, Features, User Stories, Tasks, Bugs, Requests, Requesters, Test Cases, Impediments in Targetprocess.

CSV files are commonly used to mass-update Targetprocess data using spreadsheet editors (e.g. Microsoft Excel) or to transfer data between Targetprocess and third-party tools such as bug trackers etc.

Import from CSV files is just one method of batch data update in Targetprocess. Find other available methods in dedicated article: How to migrate or import data to Targetprocess from other project management system

Let’s say, we’re looking to create a simple project backlog. Stories can be added one by one, but it’d be faster to import them. For that, create a simple list with several user stories in Excel and save the file as a .csv. You can download and use this template.

Now go to Settings → Import

Import

As a first step, you should Upload CSV file to Targetprocess. Then specify which entities you’re going to import, the entity type column (for the dynamic entity type definition), the location of your CSV file and select the column delimiter.

Delimiters

Targetprocess currently accepts 4 delimiters:

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

Entity Type selection

In the Entity Type column, choose “UserStory” if you want to import User Stories, or e.g. “TestCase” for Test Cases.

To define the imported entities dynamically, do the Select Type to Import step. Various entity types are imported separately. After importing the entities of one type, the wizard will return you to this step again. If some entity type has been selected at Step 1, the wizard will forward you on to Step 3.

Import1

At Step 3, you should Map CSV columns.

Import2

It’s a must to map the Project and ID columns for CSV files and Targetprocess entities, mapping the other columns is optional.

If the ID property is not mapped, all the entities will be inserted as New. If the ID column is mapped but empty, the entities will also be inserted as New. If the ID column is mapped and not empty, Targetprocess will try to update IDs for the entities with values specified in the CSV file.

When only one Project is selected in the project context menu, you can leave off the ‘Project’ field from the CSV file. In this case, only entities from the currently selected project will be imported/updated.

When two or more Projects are selected, or if entities from multiple Projects need to be updated, the ‘Project’ column should appear in your CSV file. With the Project ID columns mapped, you can update entities from any Project you have access to, even if these Projects are not currently selected. You can use either Project ID or Project Name in the Project Column.

You can not change Project for an Entity within the Import feature.

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

List of entities and fields that can be imported from CSV files and used in columns mapping is available in the dedicated article: Entities and fields supported for import from CSV files

You can map a Targetprocess entity field with a certain CSV column, or choose the ‘Skip’ option. For example, User Story may have the “Effort” property while in the CSV file you may have the “Estimated Effort” column, and you can map them. Custom fields can be imported as well.

Usually Targetprocess tries to define the mapping by itself, but in some cases it may fail with the resolution.

It is not possible to map two or more columns from a CSV file to one Targetprocess entity field.

First line of the CSV file can be skipped because usually it contains the header and the column names, not the data itself.

When you’re done mapping columns, click Next and Targetprocess will either do the import (that’s the Perform Import step) or will display a warning for possible mapping issues so they can be fixed manually.

As a last step, you can View Log of the completed import.

Import of hierarchical backlog

CSV file

It is possible to import Features, User Stories and Tasks into your backlog altogether within single CSV file. Find detailed step-by-step guide in dedicated article.

Troubleshooting

Entity type must be spelled without spaces

When you are able to pass through columns mapping step but no entities are still imported, please check that entity type names are spelled correctly without spaces in between (e.g. UserStory, TestCase) and all mandatory fields are mapped and filled in.

Line breaks in Descriptions

To preserve line breaks when Importing from a CSV file, please use the <br /> HTML tag.

Fields not available for mapping

When some Entity Types or Custom Fields are missing in the mapping dialogs, check the context of currently selected Projects and that your user is a member of those Projects.

Set Creation Date during import

Creation Date field in Targetprocess entities is important for history tracking. Other dates such as Start Date and End Date depend on it. These fields are used when data is displayed on Timelines and in charts. It is not possible to modify creation date for existing entities. It also not possible to set start or end date to the moment before creation date for existing entities. However you can set custom creation dates for your new entities at the moment when you import them. More information: How to set Creation Date during import

Local symbols in names

When CSV file contains data other than in English, it should be encoded in UTF-8 with BOM format. Find more details here.

Huge files and performance

Importing of massive files with thousands of lines is slow. It may take several hours until the import finishes. Moreover, sometimes with large files it can stuck in the middle. Therefore, in order to increase stability and provide additional control over importing, we recommend you to split your input files into multiple batches having 500-1000 entities in each one.

  • mb963

    How can I import ‘Comments’ associated with an Entity Type?

  • Alex

    So far it is not possible to import comments one by one from a CSV file.
    However, it is possible to import whole comments thread, HTML-formatted, into ‘Description’ formatted text of any entity that is available for Import.

    We gather votes and feedback regarding this change request here: https://tp3.uservoice.com/foru

  • mb963

    Thanks for your response Alex.

  • Julie Peppers

    I’m trying to update a lot of data at once, but I’m not seeing all of the fields available in mapping, and I don’t want to overwrite data I already have in TargetProcess with blanks if the fields aren’t being mapped – why aren’t all of the fields available in the export also available for mapping in import? Specifically, I need to map planned start, planned end, team sprint – if I can’t map them, what happens to those fields for the user stories I import?

  • Alex

    Hi @juliepeppers:disqus! Yes I can confirm that the list of fields supported for mapping and, therefore, for update within CSV file is limited. Start/End planned dates and Team Iteration fields are not supported so far. I’ve added both requirements to our public backlog – where everyone can support them with votes and comments:
    http://tp3.uservoice.com/forum
    http://tp3.uservoice.com/forum

    General principle is the following: if during mapping some field is left unmapped, it remains unchaged in the database after the import is performed. If it is blank, it remains blank. If some entity in the database has a value in such field filled-in, then import doesn’t reset it to blank and preserves existing value.
    Planned dates and Team Iteration fields should be set manually within graphical UI for imported items so far.

  • Julie Peppers

    Thanks for the follow up – I’ll vote for this in the user forum

  • Luca

    How can I enable the “import functionality” to a specific user?

  • Sergey Gnedin

    @disqus_nthHqqBroz:disqus there are no individual permissions for import – if a user is allowed to create bugs or tasks, he will be able to import them as well. Please note that if the import link is grayed out at settings, it may be because no projects are currently set at top left project/team selector

  • Luca

    thanks!

  • Mike B

    Hi,

    I think it might be beneficial to update the template.

    It would be helpful to have examples with ‘First Name’, ‘Last Name’ (Developer) in there, to show some more complex possibilities.

    Same with ‘Effort’ where you can have multiple roles.

    I think many people like myself briefly read the docs, grab the example CSV and then go. Then when there’s an error, it takes a while to dig around and find the answer.

    The error messages on import are mostly clear, but I think it and the template can be improved.

    Or perhaps a simple & advanced version might even be better!

    Thanks!

Still have a question?

We're here to help! Just contact our friendly support team

Find out more about our APIs, Plugins, Mashups and custom extensions. Join our community of passionate users and even discuss directly with our developers.

Try for free

Account url: *.tpondemand.com
How many people would be using Targetprocess?
  • Myself
  • 2–20
  • 21–100
  • 101–1000
  • 1000+
By clicking Continue you agree to our Terms of service and Privacy policy