CSV Import and Export
TimeStory can import events from, and write events to, comma-separated value
(CSV) files. These plain-text files can be created, viewed, and edited by
spreadsheets, text editors, and other apps, and can also be imported and
exported by many project-management and calendar tools.
Importing from CSV
You always import events into an existing document; this can be a
newly-created document, or it can be a document which already has events and
Start an import by choosing File > Import from CSV, then selecting 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 more about 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 Import 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
Importing 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.
Exporting to CSV
To export a document, choose File > Export Events to CSV from the menu. This
brings up the CSV Export dialog, which offers a couple of options:
- Whether to export all events in the document, or whether to export only
the currently selected events. (If no events are selected, this latter
option is disabled.)
- Whether to include a row of column headers at the top of the file. These
headers name the columns, and are useful for manually-edited CSVs, but may
not be as useful if you are passing the CSV to another app.
The resulting CSV file has a fixed column format. Fields are separated by
commas, rows are separated by carriage-return/linefeed pairs, and double
quotes are used as needed to allow fields to contain those special characters.
There is one header row, followed by one row per event.
The tabular format is as follows:
- Date contains the start date of a span event, or the date of a point
event. It is never empty.
- End Date contains the end date of a span event; it is empty for a point
- Title contains the plain-text contents of the event title. No formatting
information is included.
- Section contains the plain-text title of the section to which the event
belongs; it is empty if the document does not use sections.
- Description contains the plain-text description of the event, from the
Note that the resulting CSV file does not contain any formatting information,
such as font choices, graphic shapes, or color selections.