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
CSV Import adds events, and possibly sections, to an existing document. Start by either creating a new, empty document, or by opening a document to which you want to add the new content. Then, either drag your CSV file from Finder into the timeline window, or use to choose your CSV file. Once a file has been loaded, you’ll see the CSV Import dialog.
At the top of this dialog, you’ll see a preview of up to 100 rows of data from the file; below that are the settings to use to do the import. The preview will automatically update as you change those settings.
TimeStory will attempt to automatically detect the correct configuration from the contents of the file. If the file came from a TimeStory export, then this detection should normally be perfect, and you just have to click the Import button. For other sources, TimeStory will automatically detect the basics, but you’ll often need to make some changes.
- The field separator is the character used to delimit fields in the input file. TimeStory allows both comma and tab characters, which are both commonly used.
- First row contains column titles tells TimeStory that the first row of the CSV contains column titles, not a valid event.
- Stop after the first error causes TimeStory to fail to import if there are any rows of data it can’t import. Use this if you want all or nothing; normally, it tries to import everything it can, and tell you about what it couldn’t.
- Put all events in a single row does what it says. Normally, each event goes into its own row. Note that if your import includes section titles, this really means all events in a single row per section.
- Update existing events with the same title treats this CSV file as an update to your document. When it finds an event whose title is already found in the document, it edits that event rather than creating a new one.
- Date Format lets you request a specific language and regional date format for reading dates. By default, it uses your Mac’s current system settings; the screenshot above was taken on my Mac, hence US. Note that TimeStory also always recognizes dates of the form YYYY-MM-DD, regardless of your settings, as those are commonly produced by other programs and are fairly universal.
Finally, for each column in the CSV, you can choose where it goes: the event title, description, tag list, color, shape, and so on. Some fields have variations; for example, the end date can be inclusive (the last day of the event) or exclusive (the day after the last day of the event), and the section title can be just the immediate containing section or the sequence of section/subsection titles in a more complex document.
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 let you view any errors or unrecognized fields.
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 or position.
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 action.
Exporting to CSV
To export a document, choose . This brings up the CSV Export dialog, which shares many options with the Import dialog.
The main difference here is that you can add or remove columns. The set of available column types exactly matches those on the import dialog, with the same meaning.
Click Export to choose a file to save the output to, or click Copy to Clipboard to copy the data to the clipboard if you want to paste it into another editor, app, or spreadsheet.
If you make any changes to the configuration before exporting, those changes will be remembered the next time you open the Export dialog for the same document.