Call Installed Omni Automation Plug-In

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.

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).

(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:

{"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 orange with the text placeholders in red.

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 here.

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:

call-plug-in-workflow

 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:

Screenshot

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:

((){ 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; })();

DISCLAIMER