Calling Omni Automation Plug-Ins from Shortcuts

Shortcut workflows can be used to launch installed Omni Automation plug-ins. The following documents how to create a Shortcut workflow to call a plug-in.

NOTE: See the Script URL for Plug-In action as an example of how to generate a script URL for execution in a Shortcuts workflow.

Function and Argument

Here is the Omni Automation function used to call an installed plug-in. It is written as a self-invoking function with an argument parameter. The argument will be a JavaScript object containing the plug-in ID and the name of the plug-in action file (without a file extension).

Call Installed Plug-In Function
Copy

(function callInstalledPlugIn(args){
	var pid = args["pid"]
	var actionName = args["actionName"]
	var aPlugin = PlugIn.find(pid)
	aPlugin.action(actionName).perform()
})(argument)

The corresponding argument for this function is a JavaScript object containing the name of the plug-in action and the plug-in identifier string:

Function Argument
Copy

{"actionName":"name-of-action-file","pid":"plug-in-identifier-string"}

To be executable by a Shortcut workflow, the function is encoded into a script URL with an appended argument, using text placeholders for the argument parameters, which is then placed into the workflow as a text action.

In the provided example script URL below, the encoded argument is shown in green with the text placeholders in red.

Encoded Calling Function with Argument
Copy

omnifocus://localhost/omnijs-run?script=%28function%20callInstalledPlugIn%28args%29%7B%0A%09var%20pid%20%3D%20args%5B%22pid%22%5D%0A%09var%20actionName%20%3D%20args%5B%22actionName%22%5D%0A%09var%20aPlugin%20%3D%20PlugIn%2Efind%28pid%29%0A%09aPlugin%2Eaction%28actionName%29%2Eperform%28%29%0A%7D%29%28argument%29&arg=%7B%22pid%22%3A%22XXXXX%22%2C%22actionName%22%3A%22YYYYY%22%7D

TIP: Detailed information regarding encoding Omni Automation scripts into URLS can be found in the Script URL section.

Editing the Workflow

Workflow: https://www.icloud.com/shortcuts/99e9ed47aa6b493f950b17fda6b5da1d

Actions in the workflow will replace the text placeholders with the plug-in information you provide.

To adapt the workflow to target your installed plug-in:

• Change the name of the target Omni application in the URL. Keep it lowercase. The example shows OmniFocus, but this workflow will work for all Omni apps.
• Change the value of the third action to be the ID string of the target plug-in
• Change the value of the fourth action to be the file name of the plug-in action to match the target plug-in action. No file extension are included.

 1  Function • The plug-in calling function encoded as an Omni Automation script URL with an argument parameter.

 2  Plug-In ID • Replace the text placeholder in the encoded URL with the ID of the target plug-in.

 3  Plug-In File Name • Replace the text placeholder with the file name (no file extension) of the target plug-in action.

 4  URL • Create a URL object with the resulting text.

 5  Execute • Execute (open) the URL.

Getting Plug-In Information

Information about a specific installed plug-in can be viewed in the Configure Plug-Ins window accessed from either the Settings control or the Automation menu:

Adapting a Plug-In for Remote Execution

Actions called by remote scripts will have selection objects that are undefined. If the action you intend to call via a Shortcut workflow uses the current selection object, the plug-in code may need to be adapted to be able to be called remotely.

To adapt actions to be “callable” by remote scripts, check for the type of the selection object and if it is undefined, add a script statement for getting the current document selection. In the following example action for OmniOutliner, a list of selected items (rows) is generated if required:

Remotely Callable Action
Copy

((){
	var action = new PlugIn.Action(function(selection){
		// if called externally (from script) generate selection array
		if (typeof selection === 'undefined'){
			// convert nodes into items
			nodes = document.editors[0].selectedNodes
			selectedItems = nodes.map((node) => {return node.object})
		} else {
			selectedItems = selection.items
		}
		// action code …
	});

	action.validate = function(selection){
		// validation check. For example, are items selected?
		// if called externally (from script) generate selection array
		if (typeof selection === 'undefined'){
			selNodesCount = document.editors[0].selectedNodes.length
			return (selNodesCount > 0)
		} else {
			return (selection.items.length > 0)
		}
	};

	return action;
})();

Documentation regarding calling plug-ins and libraries externally is found in the Plug-In documentation.