Importing text (e.g. CSV) files

If you have existing data in another application or from another source, you can import your existing data into the timeline file using CSV import. CSV importing allows you to import data for events and other entities such as people and locations from within a single CSV file.

This article steps through the process of importing a CSV file and the large number of settings available.

Steps to import a file

  1. Ensure your CSV file is formatted correctly, and matches the expected data formats for each column as listed below:
    • Adding a header row with labels that match the column labels used during importing will allow Aeon Timeline to automatically match the column, reducing configuration steps for you
    • If you have additional data columns you wish to import that do not match any existing fields, you may wish to configure Timeline Settings to add those extra fields before continuing
  2. Open the timeline file you want to import the data into (or create a new file)
  3. Choose Import CSV or TSV... from the File menu
  4. In the Open file dialog, select your CSV file
  5. Adjust the global and column settings that will be used to import the file (see below)
  6. Keep an eye out for any error messages associated with each column
    • These will let you know if there are any issues with your data that you need to fix up
    • If there are errors, you will need to cancel the import, correct your CSV file, and start again from Step 3 to continue
  7. Click Next: Confirm Data, and a confirmation screen will tell you how many items of each type will be created or updated during importing, and how many rows will be ignored.
  8. Click Import to perform the import.
    • Depending on the amount of data you are importing, this may take several minutes to complete.

Correcting any import errors

You may find it takes several iterations to configure the CSV file and import settings to get your data exactly how you want it.

If you perform an import and it is not to your liking, there are two paths to correct it:

  1. If there are issues affecting a lot of items, you can Undo the import (Cmd+Z on Mac, Ctrl+Z on Windows). 
    • This will return your timeline to the state prior to the import
    • You can then correct any issues in your source CSV file and perform the importing steps again
  2. If there are only a few issues, it may be easier to just fix up those few issues in your timeline file and carry on from there

Import Settings

The import modal window provides access to a range of options to configure your import:

The import settings are divided into two sections:

  1. The top section provides global settings that configure how the import will work across all rows in your CSV file.
  2. The column selections configure what the import should do with each column.
    • The CSV import dialog includes all of the columns in your CSV file, but you will need to scroll the column selection table horizontally to access all columns.

Each is described in more detail below.

Global Settings

The table below lists all of the fields within Aeon Timeline that can be matched to your CSV file, and describes the expected data and data formats for each:

Setting Description
Header Row When selected, the first row of the CSV file will be treated as a header row. The data will not be imported, and its values will be used as a heading for the column settings table shown underneath.
Default Row Type Select the item type that will be applied by default when importing rows into your table:
  • This will normally be your main event type (e.g. Event in fiction, Task in project management).
  • If you choose a column to match Item Type, the data in that column will take precedence (the default value would be used if the field is blank or contains a value that does not match a valid item type in your timeline file).
Date format Select the date format used in Start Date and End Date columns.
Two-digit years Choose whether two-digit years should be matched to the current century (e.g. 19 becomes 2019, 89 becomes 2089), or whether they should remain as-is (e.g. 19 represents 0019 AD).

Column Settings

The column settings table shows each column in your CSV file, and allows you to choose how you want to treat the data in each column.

The table below lists all of the fields within Aeon Timeline that can be matched to your CSV columns, and describes the expected data and data formats for each.

Note: Each field value can be matched to a single column only. Once it is selected for one column, it will be disabled for all others.

Field Description Expected Data
Don't Import This column will be ignored during importing
Label The text label that will be displayed for the event throughout the interface Any text value is accepted.
  • Follow CSV formatting guidelines to include newlines, quotes, or commas (generally Excel etc. will take care of this for you)
Type Specifies the item type that will be used when creating an item from this row This value should match the label of an item type that exists in your timeline. For example:
  • Fiction templates may have Event, Scene, Character, Story Arc, etc.

If the value is blank or a match can't be found, the default value will be used.

Color The color that will be applied to the imported item This can be one of two values:
  • A label that matches a pre-existing color label defined in timeline settings
  • A hexadecimal code for a color to be imported (e.g. #FF0000). Note that hexadecimal values will be matched to the closest color in our pre-configured color palette. Not all colors can be directly matched.
Start Date The start date for an imported even, or the birth or creation date for an imported entity.
  • For uncertain dates, you should also specify Latest Start Date in another column. 
  • In that case, this date is treated as the Earliest Start Date.
A recognisable date (or date and time) matching any of the following formats:
  • Short format (e.g. 03/05/2014), matching the date format order set in the Global import section, with or without time
  • Medium format specifying a day (e.g. 17 Mar 2014), month (e.g. Sep 2017) or year (e.g. 2021)
  • Long format specifying a day, month, or year (e.g. 17 March 2014)

Time can also be added onto any of the date formats (e.g. 17 Mar 2014 15:30:00).

If this field is omitted from your settings, the value is blank, or the value is not a recognisable date:

  • A start date may instead be determined from the End Date and Duration (i.e. Start Date = End Date - Duration, or Start Date = End Date if no duration is set)
  • If no start date can be determined, the item will be created without a start date
End Date The start date for an imported even, or the death or destruction date for an imported entity.
  • For uncertain dates, you should also specify Earliest End Date in another column. 
  • In that case, this date is treated as the Latest Start Date.
Date formatting options as per Start Date.

If this field is omitted from your settings, the value is blank, or the value is not a recognisable date:
  • An end date may instead be determined from the Start Date and Duration (i.e. End Date = Start Date + Duration, or End Date = Start Date if no duration is set)
  • If no start or end date can be determined, the item will be created without a start date
Duration The duration of the event, or the lifespan of an entity A single number, or a text string specifying units and durations.
  • Valid text values include single values (e.g. 3 months) or combinations of values (e.g. 4 years 3 weeks).
  • If a single number is specified, you must choose the default unit (e.g. years, months) that will be applied to that value.
Summary A longer text summary of the event, which can optionally be displayed on your timeline (and other places) Any text value is accepted.
  • Follow CSV formatting guidelines to include newlines, quotes, or commas (generally Excel etc. will take care of this for you)
Tags Any text keywords or "tags" that you want associated with the event A comma-separated list of values. Example: "doubtful, red herring, love story".
  • Follow CSV formatting guidelines to include the comma delimiters within the field (generally Excel etc. will take care of this for you).
  • Commas are not able to be imported within a tag itself.
Internal ID An internal identifier used to refer to this item in other columns: 
  • This value is not used or displayed anywhere within your timeline file.
  • Fields (including Parent, Blocks, and various Relationship fields) in other rows can use this value to uniquely refer to this imported item
  • Do not use Internal IDs that will overlap with automatically generated display IDs in your file, as this may lead to collisions and conflicts when importing (e.g. if your timeline file will auto-generate IDs such as "EV1", "EV2", "EV3", etc. do not use this same system for your internal IDs) 
  • If this value matches a value used in a previous import, existing data will be updated rather than new rows created (see Updating existing data)
Any number or text string, but every row must have a unique value. 
Parent

Indicates another item that this imported item should be nested under.
The Internal ID or label of another imported row, or the label of an existing item in your timeline
Blocks Indicates items that cannot start until this item has ended A comma-separated list of internal IDs or labels of other rows or existing items
  • Follow CSV formatting guidelines to include the comma delimiters within the field (generally Excel etc. will take care of this for you).
  • Commas are not able to be imported within a tag itself.
Latest Start Date Used to represent uncertainty in dates: this is the latest possible start date for an event (i.e. it may start earlier, but it definitely didn't start after this time).
  • If this value is specified, the Start Date column is treated as the Earliest Start Date.  
Date formatting options as per  Start Date.
  • If this field is omitted or blank, the item will be assumed to have fixed, known dates with no uncertainty.
Earliest End Date Used to represent uncertainty in dates: this is the earliest possible end date for an event (i.e. it may have ended later, but it definitely didn't end before this time).
  • If this value is specified, the End Date column is treated as the Latest End Date.
Date formatting options as per  Start Date
  • If this field is omitted or blank, the item will be assumed to have fixed, known dates with no uncertainty.
Links Indicates any external links (e.g. web links) that should be associated with the imported item A comma-separated list of URLs 
  • Follow CSV formatting guidelines to include the comma delimiters within the field (generally Excel etc. will take care of this for you).
  • Commas within links should be URL-escaped
Properties (various) Each option in the sub-menu represents a separate property value within the timeline file.
  • Available properties depend on your chosen timeline template, and are configurable in Timeline Settings.
Varies depending on the property type:
  • Strings, numbers, or boolean (true/false) values may all be acceptable, depending on the property
  • In the case of list properties, values are expected to match an existing value in the list.
Types (various) Creates a relationship between this row and an item of the specified type.
  • The created relationship will be the default relationship allowed between items of these types (typically the highest relationship type in Timeline Settings that this selected type can be a value for).
  • Available types depend on your chosen timeline template, and are configurable in Timeline Settings.
A comma-separated list of values, which can:
  • Match another row's internal ID or label
    • In which case the relationship will be made with that item
  • Match the label, short label, initials or previous internal ID (from an earlier import) of an existing item in your timeline file
    • In which case the relationship will be made with the existing item
  • Contain a string that does not match any imported row or existing item
    • You can choose whether to create new items for unmatched strings
    • For the first appearance of that label, a new item will be created. All subsequent relationships will be with the same item.
Relationships (various) Creates a relationship between this row and another item.
  • The created relationship will be of the selected relationship type.
  • If a new item is created, it will be the default item type allowed for this relationship type (typically the highest item type in timeline settings that is allowed to be a value for this relationship type)
  • Available types depend on your chosen timeline template, and are configurable in Timeline Settings.
A comma-separated list, as per Types above.