Shortcuts Action Reference
General Notes
Documents
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:
- Using a CSS color name. These include many common and less-common English
color names, such as Red, Azure, and Dark Slate Grey. For a list, see
here. (CSS is a standard used by Web browsers.)
- Using one of the names of the colored pencils (or crayons) from macOS’s
built-in color picker, such as Steel, Clover, or Bubblegum. These are
defined by Apple; see them by opening the color picker from an app (like
TextEdit or TimeStory), choosing the pencils tab, and hovering your mouse.
- As a Web-style sRGB color code. These look like “#d4e32f”, and consist of six
hexadecimal digits following a hash mark. Many drawing tools, color apps,
and Websites let you construct these.
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.
