How-To: Add an Omni Automation Plug-In To OmniFocus (and Assign a Keyboard Shortcut)

UPDATE 2021-01-04: The below instructions were originally written in July 2019, while Omni Automation for OmniFocus was still in development and before it was officially shipped. These instructions are now out of date and I suggest instead referring to https://omni-automation.com/plugins/installation.html for updated instructions on how to install plug-ins.

Note that the below refers mainly to iPadOS but the processes for macOS and iOS are both very similar.

Step 1: ‘Turn on’ automation

Support for Omni Automation is currently off by default in OmniFocus, so the first thing you need to do is turn it on.

To do this, open omnifocus:///change-preference?OJSEnabled=1.

This will open OmniFocus on your device and ask you to confirm that you would like to change the preference:

Tap on Invoke to confirm that this is what you want, then close OmniFocus completely and re-open it.

After you re-open OmniFocus, you should see a new Automation menu or button.

On iPadOS and iOS, this is located on the left sidebar (shown below). On macOS, it gets its own menu bar item between Format and Window.

The new Automation menu gives you three options:

• Automation Console, which lets you run scripts directly without installing a plug-in;
• Automation API Reference, which contains (currently incomplete) documentation about OmniJS; and
• Configure Plug-Ins, which we’re about to do!

Step 2: Save the plug-in file

If you want OmniFocus to recognise the script as a plug-in, you need to make sure that the script actually creates a plug-in (and is not just designed to run in the console).

A script that contains a plug-in will most likely look something like this:

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Action Author",
	"identifier": "com.youOrCompany.actionName",
	"version": "1.0",
	"description": "Action Description",
	"label": "Menu Item Title",
	"shortLabel": "Toolbar Item Title"
}*/
var _ = function(){
	var action = new PlugIn.Action(function(selection, sender){
		// action code
		// selection options: tasks, projects, folders, tags
		<# PUT YOUR PROCESSING CODE HERE #>
	});

	action.validate = function(selection, sender){
		// validation code
		// selection options: tasks, projects, folders, tags
		return true
	};
	
	return action;
}();
_; 

(Side note: if you want to write your own Omni Automation plug-ins then the generator at Omni-Automation.com—where the above code is taken from—is your best friend. You just need to write your code in the part that says <# PUT YOUR PROCESSING CODE HERE #>)

If you are saving a plug-in you will need to make sure it is saved as an .omnijs file. (If you’re copying and pasting code rather than using a ready-made file, you can do this by pasting it into a text folder and saving it.)

You’ll need to save it somewhere OmniFocus can access it. (I’ve chosen to store these in an iCloud folder so that any plug-ins can be synced across my various devices, but of course, this is completely up to you.)

Step 3: Link a plug-in folder

Go ahead and open OmniFocus and click on the Configure Plug-ins item in the newly-available Automation menu.

Tap on Add Linked Folder..., navigate to the folder where you saved your .omnijs file in the last step, and tap OK.

All going well, you should now see the plug-in you added listed under the folder, something like the below. If not, check that you have linked the correct folder, and go back and double-check that your .omnijs file actually creates a plug-in.

Step 4: Run the script

Now, when you click on the Automation menu, you should see a new option: your plug-in under a new ACTIONS section.

You might notice in the screenshot above that one of my actions is greyed out. This means that the validation criteria are not met: in this case, it means that that plug-in is written to be run when an item is selected and nothing currently is.

All you need to do to run the action is to tap on it here. And you’re done!

Bonus Step: Assign a keyboard shortcut

For an extra bit of automation goodness, you can assign a keyboard shortcut to an action in a plug-in!

To do so, head back to the Configure Plug-ins screen and tap on the plug-in you would like to set up a keyboard shortcut for.

Then tap on the action (it will be under the heading Actions) and choose which keyboard shortcut you would like to use.

Finally, delight in the Omni team’s amazing work in putting all this together, and enjoy configuring OmniFocus to do exactly what you want at any given moment!