Preparation

In order to take advantage of the built-in interactive tools of this tutorial, a small amount of preparation is necessary. It involves setting a specific preference in OmniFocus.

What is Omni Automation?

Omni Automation is an implementation of the JavaScript toolset that ships with WebKit on every Apple device and every Apple platform: iOS, iPadOS, and macOS.

Through this implementation of WebKit JavaScript, Omni has exposed the inner workings of their suite of productivity applications to Core JavaScript, so that scripts written using this very popular and prevalent language can query and control most of the functionality of OmniGraffle, OmniPlan, OmniOutliner, and OmniFocus.

Omni Automation scripts can be encoded as URLs that can be embedded in HTML-based webpages and forms, or executed by 3rd party applications. Script URLS enable user interaction with external content to trigger actions within a targeted Omni application. This website incorporates script URLs in its materials.

For the sake of security, you must enable external script access in the Omni application’s preferences. This simple process is described in the following documentation and on the Script URLs section of this website.

Script URLs

Script URLs provide the mechanism for external websites and 3rd-party application to use Omni Automation to communicate with and control Omni applications. For example, webpages can contain forms and links that when activated send Omni Automation scripts to Omni applications to execute.

3rd-party applications that incorporate URL support can send Omni Automation scripts to Omni applications:

Even online databases may contain Omni Automation script links for transferring data to Omni applications:

This level of “content connectivity” provides an excellent way for Omni applications to work with external data sources and applications:

Configuring the Execution of External Scripts

By default, the execution of external Omni Automation scripts is disabled. (Note: this restriction is for external scripts only and does not apply to Omni Automation plug-ins you’ve installed yourself.)

On iOS and iPadOS the following dialog is displayed if an external script attempts to execute:

On macOS the following dialog is displayed if an external script attempts to execute:

Clicking the “Configure…” button will summon the Automation Settings dialog (shown below).

Automation Configuration Settings on macOS

The panel containing the controls for external scripts can be summoned by either clicking the “Configure…” button displayed in the script security alert dialog (shown above) or by selecting the “Configure…” menu item from the application’s Automation menu.

Here is the Automation Configuration panel on macOS:

1 Selecting this control will allow external applications and webpages to send Omni Automation script URLs to the application for processing.

2 Selecting this control will clear the list of approved scripts, requiring all previously approved scripts to be re-approved.

X The tab control for switching between the Plug-In management view and the Security view.

Automation Configuration Settings on iOS/iPadOS

On iOS and iPadOS the panel containing the controls for external scripts can be summoned from the Settings menu > Configure Plug-Ins > Security:

1 Link back to Configure Plug-Ins panel

2 Selecting this control will allow external applications and webpages to send Omni Automation script URLs to the application for processing.

3 Selecting this link will clear the list of approved scripts, requiring all previously approved scripts to be re-approved.

Individual Script Approval

The design of the Omni Automation security for the execution of external scripts requires you to review each external script at least once. If a script is approved and executed, you won’t be prompted to review it again.

On all platforms (iOS, iPadOS, macOS) the displayed script must be viewed in its entirety prior to the execution control being enabled.

macOS

1 The script approval dialog contains the controls for approving and for disallowing or allowing the execution of the script whose code is presented in the dialog window. This dialog will appear automatically unless the script has been approved during a prior execution.

2 The script and argument code. The script argument only is shown if the script URL incorporates the use of the argument parameter. Script URLs using the argument parameter enabled scripts that process a different data set each time, to be approved for execution without re-approval.

3 Select this control to add the displayed script/sending app pairing to the list of approved scripts not requiring security interaction.

4 The button for allowing the execution of the presented script will not be enabled until either the script has been fully scrolled in the view, or that the view has been resized to reveal the entire script.

5 The Cancel button will halt the approval/execution process without saving any settings.

iOS/iPadOS

3 Select this control to add the displayed script/sending app pairing to the list of approved scripts not requiring security interaction.

4 The Cancel button will halt the approval/execution process without saving any settings.

5 The button for allowing the execution of the presented script will not be enabled until either the script has been fully scrolled in the view, or that the view has been resized to reveal the entire script.

IMPORTANT: once a script/sending application pair has been approved, no security interaction will occur during subsequent executions of the script by its hosting application.

In the next section, you’ll learn how to access and use the automation controls in OmniFocus.