Importing from CSV
TimeStory can import data from comma-separated value (CSV) files, allowing
you to quickly bring in events from many project-planning tools, calendars,
spreadsheets, and other sources.
Configuring Your Import
To get started, create a new document (or open a document to which you wish to
add the events) and choose File > Import from CSV. This will let you choose an
existing CSV file. After opening the file, TimeStory will show you up to
100 rows from the file, and let you configure how you want to import it.
- The “Field separator” option will normally be a comma, but you can change it
to a tab. (Such files are, naturally, known as tab-separated value or TSV
- If the first row in the table contains the column titles, check the “First
row contains column titles” checkbox. (This makes it easier to pick columns
for each field, and prevents that row from being treated as an event.)
- Each row in the table will map to at most one event. By default, any rows
which can’t be converted to events will just be skipped, in case you have
extra rows in your table; you can change that by choosing a different policy
next to “In case of error”.
- You must tell TimeStory which column of the table to use for each event’s
date and title. (These may be the same column, if you just want to name
each event after its date.) See below for the format of dates
- For span events, you can also pick a column to contain their end dates.
Any event without an end date will be imported as a point event. See below
for more details.
- If applicable, pick the column containing each event’s section title.
During import, events will be assigned to the section with the corresponding
title; if one cannot be found, a new section will be created.
- By default, each event will be placed in a separate row, at the end of its
assigned section (or at the end of the document, if no sections are
present). Use the “Create new events” drop-down if you wish to switch this
behavior and put all events on the same row.
Validating the Configuration
You can press the Validate button to ask TimeStory to attempt to read the
entire CSV according to your current settings, without importing anything yet.
It will tell you how many valid events it found, and how many rows it had to
skip because it could not extract a valid event.
Performing the Import
When you’re ready, press Import. The events will be imported and added to your
document, and they will all be selected, so that you can easily adjust styling
TimeStory can import quite large CSV files, containing tens of thousands of
events. A large import or validation may take several seconds; as it runs, the
dialog will continue to update the number of events found and the number of
unusable rows it had to skip, and you can choose to stop at any time.
You can Undo and Redo a CSV import, just like any other document editing
About Date Values
Your CSV must contain at least one date column. Dates can be specified in
different ways, described below. (Note that, for most purposes, you can just
ignore this section, and save dates to your CSV files in a natural way, and
the right thing should happen.)
- Using a common localized, system-dependent date format. For example, in the
US, this might be “1/2/19” to represent January 2, 2019; in other regions
and languages, that same string might refer to February 1. Note that each
region tends to support a variety of formats, using spelled-out or
abbreviated month names, omitted years, etc.
- Using a fixed date format of the form YYYY-MM-DD (that is, a four-digit
year, a two-digit month number, and a two-digit day of month, in that order,
separated by dash characters, and nothing else). This format will work no
matter what your computer’s region and language settings are. This is
provided because many external tools and programs will produce dates in this
format, avoiding any ambiguity.
If your CSV contains an End Date column, each row’s value for that column
may be any of the following:
- An empty string (empty cell, in the spreadsheet), to create a Point event
with only one date;
- A date, using either of the above formats, to create a Span event whose last
day is the given date, as if you entered that date into the End Date field
on the Inspector; or
- A date prefixed by the “<” character (the less-than symbol), indicating that the span
event ends before the given date. This is provided because many other
tools and programs consider the “end” of an event to be the day after it
completes, not its last day.