Scrivener and Ulysses Syncing

What is Scrivener and Ulysses Syncing?

The syncing feature lets you link events in your timeline with documents in your Scrivener project or in Ulysses. Aeon Timeline will keep track of changes made to timeline events or documents. Each time you sync, any changes made to the event will be copied across to the corresponding fields for the document, and vice versa.

You can specify which fields in Aeon Timeline and Scrivener or Ulysses are used when syncing. From Scrivener, we support syncing the project title, label, status, synopsis, keywords, and any custom metadata fields that have been created. Almost all values from Aeon Timeline can be included in a sync.

Terminology

Although Scrivener and Ulysses are similar in many ways, there are some slight differences in terminology and the way each program structures their project.

Scrivener

In Scrivener, there is very little distinction between a folder and a text document. Both can have nested folders and text documents within them, and both can have text of their own (i.e. they are a document in their own right).

Therefore, in Scrivener, the distinction between a folder and text document is somewhat arbitrary and it is up to the user to decide how they want them to be used. For this reason, Aeon Timeline is capable of syncing with both text documents and folders in a Scrivener project.

As the most common use case for Scrivener users is to sync only with text documents and not folders, Aeon Timeline provides an option in Sync Settings to Automatically ignore all non-text items (folders, PDFs, media, etc.). If you choose this option, Aeon Timeline will assume that you do not want to sync with folders and automatically ignore them – but it is still possible to override them on a case-by-case basis.

Ulysses

In Ulysses, there is a clear distinction between folders (called Groups inside Ulysses) and documents (called Sheets). Ulysses Groups are simply a collection of Sheets, and the Groups themselves cannot have any associated text or metadata values.

For this reason, Aeon Timeline is only able to sync with Sheets in Ulysses. Syncing with Groups is not possible.

Terminology Used

Within this documentation and the Aeon Timeline application, we have adopted a uniform set of terminology across both Scrivener and Ulysses. For the most part, this is based on Scrivener’s terminology, because that was the application we integrated first and our existing users are familiar with those terms.

Specific terminology used within Aeon Timeline and this documentation includes:

Document: This broadly refers to anything that Aeon Timeline can sync an event with, namely any item (text document or folder) inside Scrivener, and a Sheet within Ulysses.
Text Document: More specifically, this is a text document inside Scrivener (any item not marked as a folder), and a Sheet within Ulysses.
Folder: A folder inside Scrivener, and a Group inside Ulysses.
Binder: This refers to the tree-based user interface that shows the entire contents of a project inside Scrivener, or the entire contents of the Ulysses library. This terminology is shared with Scrivener.

Syncing with a Scrivener Project

To begin syncing your timeline with a Scrivener project:

Close your project if you have it open in Scrivener (Scrivener does not allow opening or editing a project from two different applications at the same time).
Access Choose Project -> Scrivener … from the Sync menu.
In the Open panel, select your Scrivener project (file extension .scriv on Mac and .scrivx on Windows). If you don’t have a Scrivener project yet, you will need to create one via Scrivener before continuing.

If you are successful, a binder will open within Aeon Timeline showing the contents of your selected Scrivener project. If this is the first time you have synced this timeline with this project, the Sync Settings dialog will appear (see below).

If you try to sync to a project that Scrivener believes is open elsewhere, you will see an error message in the Binder instead of the project contents. In that case, close the Scrivener project and then click Retry.

If Aeon Timeline is giving you that error message and you are sure the file is not open elsewhere, that means the last application to lock that file did not correctly unlock it. In that case, you should open the file with Scrivener, press Continue when it gives you a warning about the project being open elsewhere, and then close the project again to clear the lock.

Note that any changes made to a Scrivener project by Aeon Timeline are saved when the binder inside Aeon Timeline is closed. You should always close the binder inside Aeon Timeline before opening the project in Scrivener. Otherwise, Scrivener will show a warning that the project is open elsewhere.

Syncing with Ulysses

While Scrivener projects must be closed before syncing, Ulysses is the opposite: the Ulysses app must be running when syncing occurs.

Unlike Scrivener syncing, syncing updates to Ulysses are applied live by sending the changes directly to the Ulysses app.

To sync with Ulysses, access Choose Project->Ulysses from the Sync menu. If you don’t already have the Ulysses open, this will automatically open it.

A binder will open within Aeon Timeline showing your documents in Ulysses.

Sync Settings Dialog for Scrivener Syncing

The sync settings dialog allows you to choose which fields to synchronise between your timeline and your Scrivener document by selecting a value from a dropdown box for each field of your timeline. For each field, you can:

Select from one of the relevant existing fields inside your Scrivener project (only relevant fields for a value will be displayed – e.g. keywords can only be synced with tags. In Scrivener, the “Wrap Text” box must be checked for any fields that you want to sync with multiline text properties, or with any roles that allow more than one entity per event)
Select ‘None’ if you do not wish for a timeline field to be synced to the Scrivener document
Select ‘New Custom Field’ if you wish to create a new custom meta-data field inside your Scrivener document to display your timeline value.

It will be quite common to select ‘New Custom Field’ for timeline properties such as Start and End Dates or Duration, as most Scrivener projects will not have fields setup for these values in advance.

If you change your mind and want to include or exclude fields at a later time, you can change your current sync settings by clicking on the Settings icon

in the top left corner of the binder when you have your Scrivener project open inside Aeon Timeline.

The Sync Settings dialog also contains an option to Auto-ignore non text items. Scrivener allows you to add many different file types (folders, PDFs, videos, web-links etc). If you choose this option in Sync Settings, anything that is not a text document will be automatically ignored by default. You can still choose to sync to individual items if you wish to, but if you follow a conventional structure, this will keep all of the folders and other organisational elements out of your Warnings tab.

Sync Settings Dialog for Ulysses Syncing

The sync settings dialog allows you to choose which fields to synchronise between your timeline and your Ulysses document by selecting a value from a dropdown box for each field of your timeline. For each field, you can:

Select ‘None’ if you do not wish for a timeline field to be synced to the Ulysses document
Select ‘Scoped Note’ if you wish to create a new custom note inside your Ulysses document to display your timeline value.

In the metadata for Ulysses the event field title will appear as Note in the format Name: Data. Therefore when you are trying to sync data that has been added to a Ulysses document, it needs to be in this format and have the same name as the Aeon Timeline event field to be able to sync it with Aeon Timeline.

Syncing can only occur with “Sheets” (i.e Documents), not “Groups”( i.e. folders). Aeon Timeline will also ignore external folders and smart filters inside Ulysses, as these are not compatible with syncing.

If you change your mind and want to include or exclude fields at a later time, you can change your current sync settings by clicking on the Settings icon

in the top left corner of the binder.

Starting with an Existing Project

If you already have an existing project you have been working on for some time, and you now wish to create a timeline that matches your project, simply perform the following:

Open the project inside Aeon Timeline as described above.
Expand folders and documents within the binder tree to find the documents from which you wish to create new timeline events.
Select a document from the binder and drag it into your timeline to create a new event. Any existing metadata in the document will be copied across to the new event immediately. If there is no metadata for the date or duration already specified in the document, the new event will be placed at the date you dragged it to in the timeline.
Repeat this process for all events you wish to create. You can drag multiple documents at a time from the binder.
Alternatively, if you right-click on a document in the binder and choose Create event, a new event will be created at the centre of the current timeline window (unless existing metadata overrides the dates).

Starting with an Existing Timeline

Conversely, if you already have an existing timeline you have been working on for some time, and you now wish to push those events into a new document, simply perform the following:

Open the project inside Aeon Timeline as described above.
Expand folders and documents within the binder tree to find the documents from which you wish to create new timeline events.
Select events that you wish to add into your project, and drag them into the binder. A new document will be created inside Scrivener or Ulysses with all relevant fields copied across from the timeline event.
Repeat this process for all events you wish to create. You can drag multiple events at a time into the binder.

You can safely move documents around inside the binder if you want to change their position. These changes will be reflected when you next open the project inside Scrivener, or in Ulysses.

If necessary, you can also create new folders or documents inside the binder, rename documents, or move them to trash using the right-click context menu inside the binder.

Starting with both Timeline and Project

If you are starting with an existing timeline and an existing project, this process is a little slower, as you will need to specifically link existing documents with existing timeline events.

To do so, you will need to do the following:

Open the project inside Aeon Timeline as described above.
Expand folders and documents within the binder tree to find the documents you wish to link to existing events.
Right-click on the document, and choose Link to event… from the context menu.
From the ensuing dropdown, select the timeline event you want to link it to. You can type keywords or an event ID into the search field to narrow down the list of options and find the event you want faster.
Repeat this process for each document/event pair that you wish to link.

Keeping Things in Sync

As you continue your work, you will make changes to both the timeline and document so that the fields are no longer matched.

Each time you open your project inside Aeon Timeline, an icon next to the binder documents will show you the sync status of each document:

Document is not yet linked:
Document and event are up to date:
Document or event has changed:
Conflicting changes to document and event:
Document is marked to be ignored: [no icon]

You can hover your mouse over a document to see a tooltip with additional information about the status, such as which values are conflicted or changed.

Syncing Changes

If one or more documents are marked as changed, click on the Sync All button at the top of the binder to sync changes for all event/document combinations. Upon clicking this button, any changes you made to documents will be copied across to the timeline, and any changes to the timeline will be copied to the documents.

Any changes that are copied to documents in Scrivener will appear the next time you open the Scrivener project. However, syncing between Ulysses and Aeon Timeline happens simultaneously. When you sync something in Aeon Timeline you will see the change in Ulysses almost immediately, and when you change something in Ulysses you will see the change in the sync binder of Aeon Timeline.

Alternatively, if you wish to sync items individually, click on the document’s status item inside the Binder or Warnings tab, or by choosing Show Item Status from the context or Sync menus.

This will open the Item Status Popover. This provides a snapshot of the currently selected Scrivener document or sync link.

The Item Status popover shows:

The document’s metadata values for all selected fields in Sync Settings.
The linked event’s information for the same fields (if the document is linked).
If the document and event values are the same, the value is shown in a single field stretching the width of the popover.
If either the document or event value has been edited, the document and event values are shown in separate columns. Any changes since the document’s last sync are shown in green (additions) or orange (deletions).
Any conflicts are highlighted with a red boundary.

Wherever the timeline and document values differ, you can choose which value you wish to keep when applying a sync:

The currently chosen option will be highlighted with a bold outline.
Click on the Choose button in the other column to switch to the other value.
In the case of a conflict, neither option will be chosen by default. Click Choose in one column or the other to choose that value. You cannot sync a document until all conflicts have been resolved.
If the values differ but can be merged (e.g. a keywords list), then you won’t get the option to choose one value or the other.

Once the selections are configured the way you want them, click Sync Now to apply those changes immediately.

Warnings Tab

The warnings tab lists three distinct types of warnings:

Conflicts: Lists any conflicted links – that is, links where the same value has been edited inside both Aeon Timeline and Scrivener/Ulysses, which requires manual intervention to determine which version to keep when syncing.
Linked to deleted events: Lists any items that are linked to events that no longer exist in the timeline.
Unlinked documents: Lists all documents that are neither ignored, nor linked to a Timeline Event. This allows you to see any new documents in the project.

Clicking on any items in the Warnings tab gives you access to the same options as you would have when accessing them inside the binder itself.

You can also hold down Shift to select multiple documents within the one category, allowing you to quickly apply the same decision (e.g. Ignore, Create New Event) to all of the selected items at once.

The number shown at the top of the Warnings tab tells you the total number of documents across the three categories. The number badge will be coloured red if there are any conflicts, and orange otherwise.

The Events Tab

Where the new Warnings tab draws attention to documents that require specific attention, the new Events tab does the same thing for timeline events.

The events tab lists events in two categories:

Linked to deleted items: Lists any events that are linked to documents that no longer exist in the project.
Unlinked events: Lists all Timeline events that are neither ignored, nor linked to a document. This allows you to see any new events in the timeline that you may want to import into the project.

Clicking on the status icon next to an event will select the event in the timeline and scroll it into view.

The context menu provides access to options to resolve the issues, including:

Remove Link: Removes the existing link and moves the event into the Unlinked events category.
Ignore: Mark the event as ignored to remove it from the list.
Create new document in Inbox: Creates a top-level folder in your project called Inbox (if it doesn’t already exist), and then adds a new document linked to this event to that folder.

The Create in Inbox option provides a fast way to sync a number of new events at once, rather than seeking them out in the Timeline and dragging them into the Binder.

As with the warnings tab, you can hold down Shift to select multiple events within the one category to apply the same action to all selected events.

Ignoring Documents

If there are documents that you know you will never want to sync, you can choose to permanently ignore those documents by right-clicking on the document and choosing Ignore.

Ignored documents will no longer show a status icon, and you can choose to hide ignored events entirely from your binder.

You can also ignore entire subtrees of documents. This option is found in the context and sync menu for a selected item. This ignores not only the selected item, but all children of that item now and in the future. This allows you to automatically ignore top-level folder such as Research and Trash, and never be bothered with items in those folders appearing in your Warnings tab.

Binder Display Options

At the bottom of the binder there are two display options that you might find useful.

Show Unchanged Items

When this is unchecked, all unchanged items will be removed from the binder (i.e. all items showing

). The only items showing will be those with changes

or those that are not yet synced

, plus any parents of those items (to maintain the integrity of the tree structure).

This can significantly reduce the number of documents visible in the binder, making it easier to find items that have changed.

Show Ignored Items

By default, ignored items will be removed from the binder (unless their child documents must be displayed.

When this is checked, those items will be displayed. Allowing you to review the ignored items and potentially drag them onto the timeline or link them with another event.

Project Filter

If you want to quickly find an item inside the Project Binder and know the document’s title, you can use the filter textfield at the bottom of the binder to search for that document.

As you type, the binder list will be filtered to show only documents that match the entered text.

Syncing Links in Inspector

Aeon Timeline automatically creates an external link whenever an event is synced with a document. These automatic links are shown in the Links tab in the Inspector, under a separate category from the other links.

This provides a way for you to see which document an event is linked with (this information was not easily accessible in earlier versions).

This link will be visible, even if the project is not open at the time.

The links tab allows you to perform the following actions for Scrivener documents only:

(Mac-only) Click the Quicklook icon to view the actual document contents in a Quicklook window.
(Mac-only) Click the Open icon to open that selected document inside Scrivener. This will launch Scrivener and try to open the project, so you should close the project inside Aeon Timeline first.
If the Scrivener project is currently open for syncing, click on the red minus button next to the document to unlink the event from the document.

Note that since timelines can sync with multiple projects, there may be more that one document listed in the Syncing area of the links tab.

Manage Projects

Found in the Sync menu, this shows a list of all projects the timeline is currently synced with. Within this window, you can erase all sync data related to a project. This is useful if you want to erase an existing sync to start again, or to remove projects you no longer care about so they don’t show up in the Inspector).