Connecting OmniOutliner

OmniOutliner documents can be used on your Mac, iPad, iPhone, or Apple Vision Pro. For extra planning power and focused flexibility, documents can easily sync between devices, and be edited anywhere. You can sync OmniOutliner documents using iCloud Drive, OmniPresence, and other cloud services that are supported by the operating system.

You can also expand the reach of OmniOutliner by using Connected Folders and Omni Links to pull together a range of resources.

iCloud Drive

iCloud Drive supports syncing OmniOutliner documents between your Mac, iPad, iPhone, and Apple Vision Pro devices.

If you need to set up iCloud Drive, start with this Apple Support article:

Set up iCloud Drive

Once you have iCloud Drive set up, open System Settings, and navigate to Apple Account > iCloud > Drive > Apps syncing to iCloud Drive, and turn on OmniOutliner.

OmniPresence

If you would rather not use iCloud Drive, you may be interested in a sync solution we created.

The first part of our sync solution is OmniPresence.

OmniPresence runs in the background, watching a folder that you select, and makes sure that the files inside are in sync with files in the cloud, as well as with your other devices which are configured to use OmniPresence.

On Mac:

Download OmniPresence for Mac from our Downloads page.
Open the Disk Image, and drag OmniPresence to your Applications folder.
Double-click the OmniPresence icon to launch the app.
Click on Set Up Syncing, and follow the instructions to configure your own sync folder.
If you need additional help, select OmniPresence Help from the menu.

On iPad, iPhone, and Apple Vision Pro:

Select Configure OmniPresence from the OmniOutliner Menu in the toolbar.
Select Add OmniPresence Account.
Choose from Add Omni Sync Server Account or Add WebDAV Server.
Enter your cloud service credentials.

As part of configuring OmniPresence, you will need to select a cloud services provider. You can use our Omni Sync Server, or your own WebDAV server.

Omni Sync Server

Omni maintains the Omni Sync Server, which is designed to work well with OmniPresence. We recommend this as the best sync solution for most users using OmniPresence, since it’s the one for which we can provide Support, and it also happens to be free!

If you choose to entrust your data with the Omni Sync Server, we’ll treat it with utmost care and responsibility. Please see our Terms of Service and Privacy Policy, to learn more.

If you have an Omni Account, you can use our sync service. If you don’t yet have an account, and want to use the Omni Sync Server, get started by creating a new Omni Account.

WebDAV Server

Omni Sync Server is a great solution for most OmniPresence users, but if your sync needs require that your data be kept completely within a system you control, you can configure OmniPresence to sync using another WebDAV server.

We are not able to provide support for third party servers, so this option is not recommended unless you have a specific need, and you have the technical knowledge for server configuration and administration.

OmniPresence sync is compatible with any WebDAV standards-compliant server, whether remote (there are many fine providers available) or hosted on your own Mac.

If you choose to use your own WebDAV server, please read our support article about Configuring a WebDAV server for OmniPresence sync.

Other Cloud Services

You can also use OmniOutliner with cloud services other than iCloud Drive or OmniPresence.

There are two different ways of using cloud services with OmniOutliner:

Some cloud services support both ways of working, while others support syncing documents, but do not support using Connected Folders.

If you need help configuring cloud services on iPhone, iPad, or Apple Vision Pro, start with this Apple Support article:

Use third-party cloud apps in the Files app

Syncing Documents

By default, OmniOutliner stores documents as flat files, which are compatible with common cloud storage services such as Box, Dropbox, Google Drive, and OneDrive.

If you are using iCloud Drive or OmniPresence to sync, you may want to store documents as file packages instead. You can read about Document Format options to learn more.

Connecting Folders

Folders synced using other cloud services can be used as Connected Folders, as long as the cloud service is fully supported by the operating system. This requires a higher level of integration than simply syncing documents, so may limit which cloud service you decide to use.

macOS supports using Connected Folders with most cloud services, so if you are using Connected Folders only with Macs, you will have many options. Please email Support if you encounter any issues, or have questions.

iPadOS, iOS, and visionOS currently support using Connected Folders with iCloud Drive, OmniPresence, and Dropbox. They do not currently support Box, Google Drive, OneDrive, or Proton Drive, amongst others.

This support may change over time. You can check others cloud services, or see if updates from Apple or the cloud services have added support for your device by either:

Connecting a Synced Folder or Reconnecting a Synced Folder on iPad, iPhone, or Apple Vision Pro. If the Open button can’t be selected, the service cannot be used for Connected Folders.
Open Apple’s Shortcuts app, and create a new shortcut with the operating system Select File action. Switch from Select File to Select Folder, and run the shortcut. If a service can’t be selected for this shortcut, the service also cannot be used for Connected Folders.

Connected Folders

New in OmniOutliner 6, Connected Folders support jumping directly to OmniOutliner documents or rows using Omni Links, as well as syncing Custom Templates and Omni Automation Plug-Ins between devices.

OmniOutliner creates a default Connected Folder in iCloud Drive:

Configuring the iCloud Drive Folder

You can also add Connected Folders from OmniPresence or other cloud services:

iCloud Drive Connected Folder

By default, OmniOutliner uses the OmniOutliner folder inside iCloud Drive as the default Connected Folder, as long as you have already configured iCloud Drive to support OmniOutliner. Please see the iCloud Drive section, if you need help.

Configuring the iCloud Drive Folder

The default Connected Folder has support for Omni Links turned on by default. To turn on support for additional item types, select the Connected Folders command:

From the OmniOutliner Menu on Mac and iPad.
From the OmniOutliner Toolbar Menu on iPad, iPhone, and Apple Vision Pro.

Once the Connected Folder window opens:

Select OmniOutliner in the Sidebar.
Select Omni Links to turn support for Omni Links on or off for documents stored anywhere in the OmniOutliner folder.
Select Templates to turn support for Templates on or off for templates stored in the OmniOutliner > Templates folder.
Select Plug-Ins to turn support for Plug-Ins on or off for plug-ins stored in the OmniOutliner > Plug-Ins folder.

Once you have updated the settings you can either close the window, or connect additional folders by selecting the add button.

Please note that the default Connected Folder will only display templates and plug-ins which are stored in specific folders. This allows you to store additional templates or plug-ins in the OmniOutliner folder, without having them show in-app. To create those folders, you can either select the magnifying glass button next to the Location field, or:

On Mac, open Finder and choose Go > iCloud Drive from the menu bar, then open the OmniOutliner folder.
On iPad, iPhone, or Apple Vision Pro, open Files, tap on iCloud Drive in the left sidebar, then open the OmniOutliner folder.

You can now create the required folders, if they do not exist:

iCloud Drive > OmniOutliner > Templates
iCloud Drive > OmniOutliner > Plug-Ins

Connecting a Synced Folder

If you are connecting a folder which has previously been configured on any device (either by you or somebody else) please jump directly to Reconnecting a Synced Folder.

In addition to the default Connected Folder in iCloud Drive, you can connect as many synced folders as needed, using either OmniPresence or other cloud services which are supported by the operating system.

To connect a new folder, select the Connected Folders command:

From the OmniOutliner Menu on Mac and iPad.
From the OmniOutliner Toolbar Menu on iPad, iPhone, and Apple Vision Pro.

Once the Connected Folder window opens:

Select the button.
On Mac, navigate inside of the folder you would like to configure, and click the Connect Folder button.
On iPad, iPhone, or Apple Vision Pro, navigate inside of the folder you would like to configure, and tap the Choose or Open button.

The Connected Folder is automatically selected for editing, with the following attributes set to their default values:

The window also contains a Settings menu, which contains commands to:

Reconnecting a Synced Folder

To use existing Omni Links on different devices, or when reinstalling OmniOutliner on the same device, you must ensure that OmniOutliner is using the same Omni Links Folder ID everywhere you want to use the Omni Links.

The easiest way to reconnect is:

Sync the folder you would like to use to your current device.
Click or tap the Omni Link to a document in that folder.
OmniOutliner will prompt you to select the synced folder which matches the Folder ID in the existing Omni Link.
Navigate to the requested folder, and select the Connect Folder button.
The link should successfully resolve, and show you the document you were trying to access.

If you have already connected a synced folder, and are still being prompted to connect it after selecting an Omni Link, you can either:

Remove the existing synced folder, and add it again using the steps described above.
Edit the existing Folder ID to match the requested ID; read the Omni Link Folder ID section to learn more.

Connected Folder Attributes

Once you have finished Connecting or Reconnecting a synced folder, you can edit the following attributes:

You can also:

Display Name

When you connect or reconnect a synced folder, the Display Name is based on the name of the folder.

To change the Display Name:

Select the folder in the sidebar.
Tap or click into the Display Name field.
Edit the name.
Press Return or exit the field to save changes.

This updates the name displayed in this window, but does not change the name of the synced folder.

Location

The Location field shows where the synced folder is located on your device.

To view the local copy of your synced folder, you can either:

Select the button next to the Location field.
Select Show in Files or Show in Finder from the Settings menu.

Use For

When you connect or reconnect a synced folder, support for Omni Links is turned on, with the rest of the supported types turned off.

To update the Use For section:

Select the folder in the sidebar.
Select Omni Links to turn support for Omni Links on or off.
Select Templates to turn support for Templates on or off.
Select Plug-Ins to turn support for Plug-Ins on or off.

The default iCloud Connected Folder looks for templates and plug-ins stored in specific folders inside of the iCloud OmniOutliner folder:

Omni Links are available for documents stored anywhere in iCloud Drive > OmniOutliner.
Templates are available if they are stored in iCloud Drive > OmniOutliner > Templates.
Plug-Ins are available if they are stored in iCloud Drive > OmniOutliner > Plug-Ins.

Connected Folders that have been added by Connecting a Synced Folder or Reconnecting a Synced Folder display templates and plug-ins from anywhere inside that folder.

Omni Links Folder ID

When you connect a new folder, a unique Omni Links Folder ID is generated, by combining the name of the synced folder with a random number. This Folder ID is used as part of any Omni Links you create. Using a random number ensures that different synced folders with the same name will have unique Omni Links, so you can consistently access the documents you intend.

Once generated, the Folder ID is stable, unless you intentionally change it; it will not change if you update the name of the synced folder or the Display Name.

A different Folder ID will be generated if you connect the same synced folder on different devices, or connect a synced folder multiple times on the same device.

To update the Omni Links Folder ID:

Select the folder in the sidebar.
Select the button.
Enter your preferred ID.
Select Update to save your changes, or Cancel to discard your changes.

Updating the Omni Links Folder ID will break any existing Omni Links, so please carefully consider the warning before making any changes. You may need to manually update existing links, or create new links.

Disconnecting a Folder

To disconnect a folder:

Select the folder in the sidebar.
Select Disconnect Folder from the Settings menu.

Omni Links

You may be familiar with the Copy as Link command from earlier versions of OmniOutliner, which allowed linking to specific rows in an open document. This command is still available in OmniOutliner 6, though it has been renamed to Copy Legacy Link.

OmniOutliner 6 introduces a more powerful version of this command: Copy Omni Link, which allows you to link to specific rows in any OmniOutliner document that is stored in a Connected Folder. These links can be used on any device where you are using OmniOutliner, as long as your devices are configured to use the same Connected Folder.

To use Omni Links:

Select one or more rows.
Select the Copy Omni Link command from the Edit Menu or Row Shortcut Menu.
Navigate to another location, and Paste the link.
Select the pasted link to jump back to your original location.

In OmniOutliner for Mac, you can either select the link and replace the text, or Option + click on the link and edit the Display title.

You also have the option to Show URL, or Remove Link.

When you have finished editing the link, click Done.

Configuring Omni Links

Omni Links are easy to use, but need to be carefully configured. Please select one of these options:

If you are using the default iCloud Drive Connected Folder, see Configuring the iCloud Drive Folder.
If you are adding a non–iCloud Drive Connected Folder which has never been used (on any device), see Connecting a Synced Folder.
If you are adding a non–iCloud Drive Connected Folder which has been used (on any device), see Reconnecting a Synced Folder.

Structure of Omni Links

There are several required components of an Omni Link.

In order of appearance, they are:

Omni App Name — Name of the Omni application, in lowercase, followed by a colon (:) and three forward slashes (///).
Link Type — The link type, in lowercase. Currently, only document (doc) links are supported.
Path — Folder path to the location of your document, with Percent-encoding used for spaces and other special characters.
Document Name — Name and file extension for your document, with Percent-encoding used for spaces and other special characters.
Omni Links Folder ID — Unique Folder ID generated when Connecting a Synced Folder, preceded with ?folder=.

What do these components look like, when combined in an Omni Link? Let’s start with a simple example, from the default iCloud Drive Connected Folder:

omnioutliner:///doc/My%20Outline.ooutline?folder=iCloud%20Drive

We can see that this Omni Link has the following components:

Omni App Name of OmniOutliner (omnioutliner:///)
Link Type of Document (doc)
Path is empty (/)
Document Name of My Outline (My%20Outline.ooutline)
Omni Links Folder ID of iCloud Drive (iCloud%20Drive)

Reading this Omni Link, you can see that it will use OmniOutliner to open a Document named My Outline (with a file extension of .ooutline, indicating that it is an OmniOutliner Document, rather than an OmniOutliner Template), located directly inside the iCloud Drive Connected Folder.

Adding a little more complexity, an Omni Link may also contain one or more optional Elements, each preceded with an &. OmniOutliner currently supports:

Focus — Element type and ID for the focused row, such as focus=mDFTZpAeCb8,
Row Selection — Element type and ID for the selected row, such as row=fh4Q0jgg5iB.

Looking at another example, from a non–iCloud Drive Connected Folder:

omnioutliner:///doc/foo/bar/My%20Outline.ooutline?folder=Work%20Server%209070&focus=mDFTZpAeCb8&row=fh4Q0jgg5iB

We can see that this Omni Link has the following components:

Omni App Name of OmniOutliner (omnioutliner:///)
Link Type of Document (doc)
Path of foo > bar (/foo/bar/)
Document Name of My Outline (My%20Outline.ooutline)
Omni Links Folder ID of Work Server 9070 (Work%20Server%209070)
Element of Focus (focus=mDFTZpAeCb8)
Element of Row Selection (row=fh4Q0jgg5iB)

Reading this Omni Link, you can see that it will use OmniOutliner to open a Document named My Outline (with a file extension of .ooutline), located inside of foo > bar, in the Work Server 9070 Connected Folder. Once the document has been opened, it will Focus on a row with an id of mDFTZpAeCb8, and add a Row Selection on a row with an id of fh4Q0jgg5iB.

Troubleshooting Omni Links

Now that you understand how Omni Links are structured, and can read a link to learn more about it, let’s complicate things a touch.

Here are a few ways that a link can stop working, and how you can resolve the issue:

Changing the name of a document — To resolve this you can change the document name back to the original name, use Copy Omni Link to create an updated Omni Link, or manually edit your existing Omni Link to use the new name.
Changing the location of a document — To resolve this you can move the document back to the original location, use Copy Omni Link to create an updated Omni Link, or manually edit your existing Omni Link to use the new location.
Removing a document from the Connected Folder — To resolve this, you need to return the document to its original location in the Connected Folder.

Here are a few items that can reduce the effectiveness of an Omni Link, and how you can resolve the issue:

Moving a row with Row Selection outside of a row with Focus applied — The row with Focus will still display, but the Row Selection will not, as it is not currently in the Outline. If you want to have both Focus and Row Selection, they must be part of the same group.

We will continue to add examples to this section; please Email Support to let us know what you would like to see.

Templates

Templates which are stored in a Connected Folder are available to OmniOutliner on all devices.

To make sure templates are available, you may need to configure the Use For attribute for a given folder.

If you need to configure a Connected Folder, please select one of these options:

Plug-Ins

Requires OmniOutliner Pro

Omni Automation Plug-Ins which are stored in a Connected Folder are available to OmniOutliner on all devices.

To make sure plug-ins are available, you may need to configure the Use For attribute for a given folder.

If you need to configure a Connected Folder, please select one of these options:

Legacy Links

Legacy Links are the same type of link found in OmniOutliner 5 and earlier, which allowed you to jump quickly between rows in the same document, with a new name.

Omni Links support more powerful workflows, but they can only be used with documents stored in a Connected Folder. In contrast, Legacy Links work as long as the document is open, which makes them ideal for linking within the same document, or building folder-independent Templates.

To use Legacy Links:

Select one or more rows.
Select the Copy Legacy Link command from the Edit Menu or Row Shortcut Menu.
Navigate to another location in the outline, and Paste the link.
Select the pasted link to jump back to your original location.

In OmniOutliner for Mac, you can either select the link and replace the text, or Option + click on the link and edit the Display title.

You also have the option to Show URL, or Remove Link.

When you have finished editing the link, click Done.

Structure of Legacy Links

There are two required components of a Legacy Link.

In order of appearance, they are:

Omni App Name — Name of the Omni application, in lowercase, followed by a colon (:) and three forward slashes (///).
Link Type — The link type, in lowercase. Legacy Links only support open (open) links.

The simplest possible Legacy Link is:

omnioutliner:///open

Reading this Legacy Link, you can see that it will open OmniOutliner. That isn’t often useful by itself, so we need to add some complexity. A Legacy Link may also contain one or more optional Elements. OmniOutliner currently supports:

Focus — Element type and ID for the focused row, such as focus=nBZUyLQl3b6,
Row Selection — Element type and ID for the selected row, such as row=j3NzslZpCi8.

Looking at another example:

omnioutliner:///open?focus=nBZUyLQl3b6&row=j3NzslZpCi8

We can see that this Legacy Link has the following components:

Omni App Name of OmniOutliner (omnioutliner:///)
Link Type of Open (open)
Element of Focus (focus=nBZUyLQl3b6)
Element of Row Selection (row=j3NzslZpCi8)

Reading this Legacy Link, you can see that it will open OmniOutliner, as above. If the document containing the destination for these links is also open, it will Focus on a row with an id of nBZUyLQl3b6, and add a Row Selection on a row with an id of j3NzslZpCi8.

Troubleshooting Legacy Links

Troubling Legacy Links tends to be easier than Troubleshooting Omni Links, as there is one primary reason a link stops working: the document containing the link is no longer open. This can be difficult to resolve, as the link doesn’t contain any information about the original document. Situations like this are part of the reason that we built Omni Links!