You can import data from a CSV file. This import method useful if you're still using spreadsheets or maintain your assets in CSV files. More about importing

Skip to:

• Before you begin
• Formatting CSV data
• Step by step tutorial for importing a CSV file
• Pre-defined structure and configuration
• Import configuration created
• Before you go
  • Object type mapping settings
• Known limitations

Before you begin

Here are some requirements for your CSV file:

• Make sure you have an object structure already defined. If not, check out our Assets tutorial.

• The CSV file needs to have headers, as they're used to create the data locators for the imports.

• To divide multiple values, for the Assets Attributes with multiple cardinality, use || (two pipe characters).

Formatting CSV data

If there's a syntax error in your CSV data file, your import might produce unexpected results or not run. Make sure to follow the formatting rules:

• You can use any of the following formats: UTF-8 (default), UTF-16, ISO-8859-1, ISO-8859-15, Windows-1250, or Windows 1252.

• The CSV file must include a single-character delimiter. The default delimiter is the comma ,. You can select a custom delimiter in the Delimiter field when you create an import configuration. To include a delimiter character, use a single character input. You can also enter \t to use a tab-delimiter.

• If you're importing Jira users, you must identify them by their Names, Emails, or User keys.

• If you're importing Jira groups, you must identify them by their Names only.

• If you're importing URLs, they must begin with a protocol, such as http, https, ftp, or file followed by :// to be converted into the URL attribute type. If you don’t include the protocol, the value won’t be imported. Explore attribute types

• If you're importing CSV data from a Google Sheets link, edit the URL so it works properly. Remove /edit#gid=0 from the ending of the URL and replace it with /export?format=csv.

Step by step tutorial for importing a CSV file

For testing purposes, you can use the following CSV file sample. This file includes the information about employees: name, employment start and end date, role, name that Jira uses to display them, and the assigned office location.

Name,Employment start date,Employment End date,Role,Jira User,Office
John Doe,2019-06-15,2023-04-30,Project Manager,John Doe,New York
Jane Smith,2021-03-01,,Developer,Jane Smith,London
Emily Johnson,2018-09-10,2022-12-31,Designer,Emily Johnson,Sydney
Michael Brown,2020-01-20,,QA Tester,Michael Brown,San Francisco
Emma Wilson,2017-11-05,,HR Specialist,Emma Wilson,Berlin
James Davis,2022-01-01,,Data Analyst,James Davis,Tokyo
Olivia Martinez,2016-07-25,2021-08-15,Marketing Coordinator,Olivia Martinez,Toronto
Liam Garcia,2019-11-18,,Sales Executive,Liam Garcia,Singapore
Sophia Lee,2023-05-01,,Customer Success Manager,Sophia Lee,Dublin

After importing and configuring the file, you should see the imported objects (employees, in this case) and objects' values (employee data). This will result in a configuration like this for a single object:

To create an Import structure:

1. From your service project, go to Assets, then Object Schemas.

2. From the Object Schemas list, next to the Object Schema you want to use, select Configure.
   
   

3. In the Schema configuration view, open the Import tab.

4. Under the Import tab:

   • If there’s no import structure, you’ll see the message “You don't have any import connections yet”. Select Create Import configuration to create a new import structure.

   • If an import structure has already been created, select Create Configuration.

5. Select CSV import, then select Next.

6. Fill in the General, Module, and Scheduling import fields.
   

   General fields

   Here are general fields, common for every import type:

   Name	Description
   Name	The name of the import.
   Description	The description for your convenience.
   Concatenator	You can specify a default concatenator. When joining multiple data locators into one Assets attribute, this will be the default concatenator. One example could be to join two columns like "First name" and "Last name" into one attribute. So "Mathias" (first name) and "Edblom" (last name) will be concatenated as "Mathias Edblom" if using \s as concatenator. Enter \s for space-concatenated. To include a concatenate character, place the value between double quotes (i.e "\s").
   Empty Values	Defines what should happen when a Data Locator is empty: Ignore - the existing value in the object will be retained and not overridden by an empty value. Remove - the existing value for the object will be removed, and replaced with an empty field value.
   Unknown Values	Defines what should happen if a Data Locator is unknown. This could happen with attribute types like "Status" and "Select".  Ignore - the value from CSV will be ignored and the object attribute will be left empty. Add - the value passed in the CSV file will be added to the list and the object attribute will be updated with the new value.
   Date Format	Format for date fields in import source to convert dates into Insight. If left empty, Insight will automatically try to find correct format.  The format should be specified according to the Java SimpleDateFormat guidelines.
   Date/Time Format	Format for date/time fields in import source to convert dates into Insight. If left empty, Insight will automatically try to find correct format.  The format should be specified according to the Java SimpleDateFormat guidelines.

   
   
   Module fields

   These fields are specific to an import type (module).

   Setting	Description
   Import from	Choose a file or URL.
   URL	Protocol, Hostname, and Port of where to find the external CSV file. Examples: http(s)://example.com/file.csv file:///opt/csv/example.csv https://docs.google.com/spreadsheets/d/your-spreadsheet-id If you’re importing a Google Sheet file, you might also see URLs with additional parameters, such as https://docs.google.com/spreadsheets/d/your-spreadsheet-id/edit?usp=sharing. In such situation, remove edit?usp=sharing from the ending of the URL and replace it with /export?format=csv.
   	Choose a file to upload.
   Username	Optional username for basic authentication.
   Password	Optional password for basic authentication.
   Delimiter	The delimiter used in the file. The default delimiter is the comma ,. Enter \t for tab-delimited. You can select a custom delimiter in the Delimiter field when you create an import configuration. To include a delimiter character, use a single character input. You can also enter \t to use a tab-delimiter.

   Scheduling fields

   Scheduling fields are responsible for keeping your data in sync:

   Name	Description
   Synchronizing Account	The Jira user to use when synchronize data into Assets. For LDAP and database imports, the account used for synchronization must have Jira admin permissions.
   Cron Expression	The interval for the automatic synchronization.
   Automatically Synchronize	If the import should be scheduled for automatic synchronization.

7. Select Create.

The Imports tab should now be populated with your new import structure. Next, you’ll need to create a predefined structure and configuration for your CSV file.

Pre-defined structure and configuration

After you've filled in the required fields, Assets will ask you whether you want to create a predefined structure (object type mappings) and configuration (attribute mappings). Details of this will differ depending on the import type. For the CSV import:

• Each column from the CSV file will be created as an Assets attribute of type Default Text, and configuration will be mapped accordingly. 

• The object type created will always be the same.

• Some object type mappings are disabled by default. Make sure to select the relevant ones.

If you want to have different attribute types created by the import of the data from the CSV file, create the predefined structure and then change the attribute types.

After you select Create predefined configuration, Assets will create configurations and mapping from the fields in the CSV file to the attributes in the object type. As these are created based on the default rules, you might need to review the mappings and make necessary changes.

Import configuration created

You can now view your import configuration, but it's not ready yet. You still need to create or review the object type and attribute mapping, and make sure there are no problems with your import configuration.

When you're ready, go to 2. Create object type and attribute mapping.

Before you go

Object type mapping settings

In the next step, you'll create the object mapping settings. Here are some settings specific to the CSV import type.

Known limitations

• The textArea attribute has a hyperlink option. However, this can't be used in the CSV import.

• For the textArea attribute, the value should be enclosed in the wrapper element, such as <div class="created-with-ak-editor content-wrapper"><p></p>. If the wrapper element isn’t present in the source, every sync will rewrite it, adding the wrapper each time and creating a new history event.