How to import a CSV file

Import Csv 2

To import events from a CSV file into your current timeline, perform the following steps:

  1. Ensure your CSV file meets the rules listed for valid CSV files below. In particular, ensure the file uses UTF8 encoding.
  2. Select Import -> CSV… from the File menu.
  3. Choose the CSV file you wish to import.
  4. In the Import CSV dialog (shown left)
    • Select whether your file is using Comma or Tab as the delimiter for columns within a row.
    • Specify whether the first row in the CSV file contains column headers, or whether the data to import begins in the very first row.

Note, it is generally recommended to use a CSV file with a row of column names at the top, as it will make the next step much easier.

Specify how to handle each column

import csv 3

The next import screen lets you specify what you want to do with each column of data in the CSV file.

A separate dropdown will be shown for each column of data, allowing you to choose the timeline field that the column should be matched with. When importing, you are able to specify columns to use for the event title, dates and duration, color, tags, links, and any properties and roles specified in your chosen template.

If your CSV file contains a header row (as per previous import screen), each dropdown will be labeled with the column name, making it easier to match up each column with the intended result. Otherwise, the columns will be labelled as “Column A”, “Column B”, etc.

No two columns can be paired with the same field in the timeline (i.e. selections in the dropdowns must be unique). Title and Start Date are the only mandatory fields that you must select somewhere.

Note that Aeon Timeline 2 will always create new event IDs for imported events.If you CSV file contains a column for event IDs, you should generally set this field to Ignore.

Once you are happy with your selections, click Import to add the events into your timeline file. Depending on the size of your CSV file, this may take several seconds to complete.

Rules for CSV files

In order to import data from a CSV file, the file must conform to the following rules:

  1. Your file must use a csv or txt extension.
  2. Files should be in ASCII or UTF-8 file format. Other Unicode formats and UTF-16 may not import correctly and should be converted to UTF-8.
  3. One record is entered per line. There must be no newline characters within a record.
  4. The fields within each record must be delimited with either commas (,) or tabs.
  5. Each record should contain the same number of fields/delimiters. It is acceptable to leave some fields empty, but their delimiters must remain intact.
  6. Any field values that include the value delimiters (i.e. comma or tab, depending which is used to delimit each value) must be included in straight double quotes ("). Optionally, all fields can be enclosed in these quotes.
  7. Curly quotes must not be used when surrounding values.
  8. Any double quotes within field values must be escaped by placing a second double quote next to the first. For example, the text She said "It's me!" would need to be written as "She said ""It's me!"""

Unfortunately, there is no single standard that defines how a CSV file should be created. We have tried to adopt the most universal standard available, but you may need to massage data from some applications in a text editor before importing.

Converting to UTF-8 format

If your timeline file is not already in UTF-8 format, you will need to convert it to UTF-8 format before you can import it.

Mac OS X

On Mac, you should be able to open your csv file with TextEdit and convert it as follows:

  1. Hold down the Alt key and click on the File menu.
  2. Choose Save As…
  3. In the save dialog, change the Plain Text Encoding dropdown, choose Unicode (UTF-8).

Windows

On Windows, many tools are available to convert to UTF-8 format. You can download a text editor such as Notepad++ and open the file.

Using Notepad++, you can do the following:

  1. Open the file in Notepad++.
  2. Click on the Encoding menu, and choose your current file encoding by choosing Encode in XXX.
  3. Open the Encoding menu again, and choose Convert to UTF-8.
  4. Save the file (you can use Save As and change the file name if you wish).

Multi-value columns

Some columns, such as columns representing a “Role”, may allow multiple values for a single record… e.g. an event may have more than one Person in the role of Witness.

In such instances, each value inside your CSV file should be delimited using a pipe character (|).

Exporting CSV files

Aeon Timeline can export timeline data to a CSV file as well as read it. This can be a useful way to share timeline data with other applications.

To export to a CSV file, choosing Export To -> CSV from the File menu, and choose where to save the exported file.

The exported file will follow the CSV rules defined above, and use UTF8 encoding.

Importing Aeon Timeline Files

Due to the flat nature of the CSV file format, some data is lost when exporting a timeline to a CSV file and then importing it again elsewhere.

If you are looking to open a version 1 timeline file in version 2, it is better to open that file directly rather than export its contents and import it into a new timeline.

Merging Timelines

We will look to include a specific “merge timelines” function in a future release to make it easier to combine multiple timelines into one, but for the moment, the inexact science of CSV export/import, or direct copy and paste are the best available options.

Discuss

Bug reports? Suggestions? Feeling lost? Leave your questions or comments below…