Shortcuts Action Reference

General Notes


Many actions, such as Find Events, take a timeline file as an input parameter called Document. You can specify the document file directly when you build the shortcut, or take it from some other source such as a Finder action or a shortcut input.

If the referenced file is already open in the app, the shortcut operates on that opened file; otherwise, it opens the file in the background (with no visible window) to do its work.

(Use the “Show Timeline in Window” action to ensure that a timeline is visible on screen, even if it was opened by Shortcuts.)

You can also create a new timeline, using the “New Document” action; this document must be given a name and folder, and after that, you can operate on it like any other document.

Any changes made to a document are automatically saved; there is no save action.

Event Parameters

Actions which operate on events, to edit them, fetch details from them, etc., take an input parameter called Events. This parameter accepts the output of actions like Find Events or Add Event; these event entries remember what file they came from, so you don’t need to specify the file again.

Color Parameters

Color parameters appear as text inputs. You can enter a color in any of these ways:

Note that TimeStory ignores letter case, spaces, and hyphens in color names, so while CSS defines “AliceBlue”, you may type “aliceblue”, “Alice Blue”, or “Alice-Blue”.

Point-Event Icon Parameters

Point-event icon names are the names shown in the Point Event Icons dialog window, and must be a case-insensitive exact match.

List of Available Actions

Add New Event
Adds a new event to an existing timeline. Provide a date (for a "point event") or a date range (for a "span event"). Optionally assign the event to a section and/or a vertical position (row) in the timeline. The event is returned as the action's output, so you can use subsequent actions to style it, tag it, etc.
Add Tag To Events
Adds a single tag to the given events. (Has no effect on an event which already has that tag.)
Copy Event Style
Copies the styling (colors, shapes, font, etc.) from a source event (or "template" event) and applies it to one or more target events.
Delete Events
Deletes the input events from their document.
Export Events as CSV
Formats the given events as CSV. The CSV format is fixed, and includes event titles, section titles, and date ranges. Use this to extract event data in bulk, for exporting or for further processing.
Export Timeline as PDF
Generates a PDF from the specified document, optionally including only the specified date range.
Find Events
Finds all events in a document, filtered by a set of optional criteria like date ranges and text. Returns events which you can then pass to other actions to style them, modify them, delete them, etc.
Find Events using Filter Syntax
Finds all events in a document which match the given filter syntax, which uses the same format as the Filter Events feature in the main app.
Get Currently-Open Timeline
If a document is already open in TimeStory, returns it. If multiple documents are open, returns the one in the frontmost window.
Get Date from Events
For a single input event, extracts its start or end date. For a collection of multiple input events, finds the earliest start date or latest end date from the entire group. (So this always returns just one date.)
Get Details from Events
Retrieves the given textual property (description, title, tags) from the given input events.
Import Events From CSV
Reads events from a CSV file and adds them to the given document. Specify the column layout or, if your input only contains simple titles and date ranges, request automatic detection.
New Document
Creates a new timeline document, saving it in a specified folder. Optionally uses a named template (like New from Template in the main menu.)
Remove Tag From Events
Removes a single tag from the given events. (Has no effect on any events which don't already have the given tag.)
Set Event Property
Changes a property on the input event or events, such as event title, event description, date range, or style settings.
Show Timeline in Window
Shows and configures a timeline document on screen, opening it first if it's not already open. Window configuration includes the visible time range, current time unit, and vertical scroll position.