OmniFocus 3 Reference Manual for macOS

Appendix E

Automating with Shortcuts

Shortcuts—multiple steps that occur within and between apps on your device—are a great way to get even more out of OmniFocus by automating many OmniFocus-related tasks.

OmniFocus works with the Shortcuts app on your Mac to provide several built-in shortcut actions for tasks related to OmniFocus. This appendix lists those actions and describes what they do.

Creating Shortcuts with OmniFocus Actions

OmniFocus adds a default list of shortcut actions to the Shortcuts app when it is installed on your device (search for OmniFocus to find them).

OmniFocus actions in the Shortcuts app.

Each action has a description with additional detail about the action's function, possible inputs and results, and relationship to other actions. Click the Info button to the right of the action title to show its details.

To add an OmniFocus action to the current shortcut, double-click it in the list.

OmniFocus Shortcut Action List

The following actions are available in the Shortcuts app when OmniFocus is installed:

Add Item

Adds a new item to OmniFocus with the specified details.

  • Input—Text
  • Result—Item

Add TaskPaper

Adds the TaskPaper passed as input into OmniFocus.

Find Items

Searches for the items in your OmniFocus database that match the given criteria.

  • Input—Text

This shortcut action returns inbox items and actions (inside OmniFocus projects) specifically. To find projects or tags instead, use those respective shortcut actions.

The “Project” and “Tags” fields provide a picker for narrowing results from the "Find Items" action based on project and tags. You can also dynamically provide the value for these fields using Find Projects or Find Tags.

Find Projects

Searches for the projects in your OmniFocus database that match the given criteria.

  • Input—Text
  • Result—Project

This shortcut action returns projects specifically. To find action items or tags instead, use those respective shortcut actions.

Find Tags

Searches for the tags in your OmniFocus database that match the given criteria.

  • Input—Text
  • Result—Tag

This shortcut action returns tags specifically. To find action items or projects instead, use those respective shortcut actions.

Get Database Object Result from Input

Returns a "Database Object Result" containing one of "Item", "Project", "Folder", "Tag", or "Perspective", depending on the input. These objects can be used in the pickers found in other OmniFocus shortcut actions.

Accepts JSON-formatted text passed in as input. The JSON attributes are "type" (with values "task", "project", "folder", "tag", or "perspective") and "primaryKey". You may recognize these attributes from their use in omnifocus:// URLs.

  • Input—Text
  • Result—Database Object Result

What are Database Objects?

In the contexts of shortcut actions, Database Objects are representations of entities in OmniFocus that aren't natively supported by the Shortcuts app. They make it possible to manipulate elements of OmniFocus that otherwise would be inaccessible. (For example, to pass an OmniFocus folder from one action to another.)

What are Primary Keys?

The Get Database Object Result from Input action does not allow you to look up an item by its name. Instead you can use its Primary Key, which is the unique id for that item.

To look up an item's Primary Key, copy and paste it from OmniFocus into a text field to find the unique segment at the end of the URL. Alternatively you can set up a shortcut to display it; for example:

A sample shortcut for looking up an item's Primary Key.

Omni Automation Plug-In

Runs an action from among the Omni Automation Plug-In actions you have installed in OmniFocus. Adding this to your shortcut provides a drop-down menu where you can select the desired Omni Automation action to run.

Omni Automation Script

Runs an Omni Automation script, using optional input from another Shortcuts action.

Show in OmniFocus

Shows a project, folder, tag, or perspective chosen from a list, or an item passed from the previous action. The latter is useful in combination with the Find Items action.

Today's Forecast

Get items for today from your OmniFocus Forecast, including tagged and deferred items if those options are selected in Forecast View Options.

  • Result—Item