×

Script: New Run Omni Automation Plug-In Voice Control Command

Omni Automation incorporates the use of either single-file or bundle plug-ins as a means of extending application functionality. Omni Automation plug-ins can integrate advanced elements such as Interactive Forms, and powerful classes like the Fetch.API, Credentials, Bookmarks, Preferences, Pasteboard, XML Read/Write, and Speech Synthesis (TTS) classes.

Inclusion of advanced classes may be impractical in many “light-weight” Omni Automation scripts used in Voice Control “Open URL” commands, so an excellent alternative for delivering plug-in functionality with voice commands is the use of an “Open URL” voice command that calls and executes installed plug-ins for you. Obviously such commands require that called plug-ins be already installed by the user!

The following documentation details how the targeted plug-ins are called, and shows how to use the provided script tools to auto-generate the XML text of the Voice Control command for executing the indictated Omni Automation plug-in.

But first, here’s a gift for you:

Example Plug-Ins

To aid in your study of creating voice commands sets, we provide the following set of Omni Automation plug-ins that that work with any Omni application:

  • Open App Documents Folder • Open the sandboxed Documents folder for the host Omni application.
  • Open App iCloud Folder • Open the iCloud Documents folder for the host Omni application.
  • Clipboard Text to App Documents Folder • Save the clipboard text as a file to the sandboxed Documents folder of the host Omni application.
  • Clipboard Text to App iCloud Folder • Save the clipboard text as a file to the iCloud Documents folder of the host Omni application.

You can install these plug-ins and target them in creating voice commands sets.

DOWNLOAD COLLECTION • To install, place the folder containing the plug-ins in the host Omni application’s Plug-Ins folder, which is accessed from the Automation Configuration dialog summoned from the app Automation menu.

Get Properties of Installed Plug-Ins

When creating a voice command for calling installed Omni Automation plug-in, the script tool provided on this page will automatically extract two bits of information about the targeted plug-in for you:

When the script is run it will prompt you to choose the identifier of the plug-in you wish to run, from a list of the identifiers of the currently installed plug-ins. Once you’ve selected a plug-in ID, the script will automatically extract and implement the required plug-in data for you.

However, should you wish to view metadata regarding your installed plug-ins, we’ve provided the following Omni Automation plug-in for you. Download and install it, and optionally add its icon to the Console toolbar of the host Omni application (see below)

console-plug-ins-info

 1  Console Window • Every Omni application provides a console window or sheet for entering and executing your Omni Automation scripts.

 2  Plug-In Button • The installed plug-in’s icon has been added to the Console toolbar to provide easy access to run the plug-in.

 3  Plug-In Info • The dotted-lines separate the sections of metadata for each of the installed plug-ins.

 4  Plug-In ID • Every plug-in has a unique identifier that is used by the application and scripts to “identify” or reference a specific plug-in. Furthermore, plug-ins contain one ore more “actions” that perform the functionality provided the plug-in code. And each action has an ID used by the plug-in to identify it.

 5  Action Count • The number of actions contained by the parent plug-in.

 6  Action Name • The filename of the plug-in action is the action identifier.

When the plug-in is executed it will display the metadata information for all of the Omni Automation plug-ins currently installed in the host Omni application. The value of the ID property will be the identifier of the plug-in, and the value of the ACTIONNAME property will be the file name of the plug-in action you wish to execute.

NOTE: in single-file plug-ins, the NAME of the plug-in will also be the ACTIONNAME.

For your reference, here’s the Omni Automation code of the plug-in, and a button for downloading the plug-in file:

Log Data for All Plug-Ins
 

/*{ "type": "action", "targets": ["omnifocus","omnigraffle","omniplan","omnioutliner"], "author": "Otto Automator", "identifier": "com.omni-automation.all.plug-ins-info", "version": "1.0", "description": "Logs information regarding each plug-in to the console.", "label": "Plug-Ins Info", "shortLabel": "Plug-Ins Info", "paletteLabel": "Plug-Ins Info", "image": "powerplug.fill" }*/ (() => { var action = new PlugIn.Action(function(selection, sender){ console.clear() PlugIn.all.forEach(plugin => { console.log("- - - - - - - - - - - - - - - - - - - - - - - -") console.log("NAME-->", plugin.displayName) console.log("ID-->", plugin.identifier) console.log("AUTHOR-->", plugin.author) console.log("VERSION-->", plugin.version.versionString) console.log("DESRIPTION-->", plugin.description) actionsCount = plugin.actions.length console.log("ACTIONS-->", actionsCount) plugin.actions.forEach((action, index) => { increment = " " + index + " -->" console.log("▸ ACTIONMENU" + increment, action.label) console.log("▸ ACTIONNAME" + increment , action.name) console.log("▸ ACTIONDESC" + increment, action.description) }) console.log("") }) }); action.validate = function(selection, sender){ return true }; return action; })();

Function for Calling Installed Plug-Ins

The script tool uses the following Omni Automation function to call the targeted plug-in. This function, along with the user-indictated parameters, is encoded by the script into a URL placed within command XML. The function offers two optional parameters:

For your reference and study, here is the code of the calling function:

Call Plug-In Function


function performPlugInAction(pluginID, actionName, announceRun, announceText, showError){ speakerVoice = Speech.Voice.allVoices.find(voice => voice.name.startsWith("Alex")) synthesizer = new Speech.Synthesizer() try { plugin = PlugIn.find(pluginID) if (plugin === null){ throw { name: "Missing Plug-In", message:"The specified plug-in is not installed." } } actionNames = plugin.actions.map(action => action.name) if(actionNames.indexOf(actionName) === -1){ throw { name: "Missing Action", message: `Action “${actionName}” is not in the plug-in.` } } else { if(plugin.action(actionName).validate()){ plugin.action(actionName).perform() if(announceRun){ Timer.once(1, () => { utterance = new Speech.Utterance(announceText) utterance.voice = speakerVoice synthesizer.speakUtterance(utterance) }) } } else { throw { name: "Validation Error", message: `The action “${actionName}” is not validated to execute.` } } } } catch(err){ utterance = new Speech.Utterance(`${err.name}. ${err.message}`) utterance.voice = speakerVoice synthesizer.speakUtterance(utterance) if(showError){new Alert(err.name, err.message).show()} } }
Using the Function


pluginID = "com.omni-automation.all.open-app-iCloud-folder" actionID = "all-open-app-icloud-fldr" performPlugInAction(pluginID, actionID, true, "Ready!", false)

Property List Editor and Tools

To edit Voice Control commands files, you’ll need an XML editor application that accepts the creation of XML elements via the pasting of XML text from the clipboard. The examples and downloads provided on this website were created using PlistEdit Pro from Fat Cat Software.

DOWNLOAD SCRIPT TOOL (macOS)

  1. To install the script file, DOWNLOAD and run the “Setup Script Menu” applet. This script applet will turn on the system-wide “Script Menu,” and open the macOS “Scripts” folder on the desktop. This process may require your approval of security dialogs, granting this script applet access to the “AppleScript Utility” and “Finder” applications.
  2. Unpack the downloaded ZIP archive containing the script tool, and place the script file into the “Scripts” folder now open on the Desktop. Once added, the script will be available from the system-wide “Script Menu” located at the top right of the menu bar.

When the script tool is executed, it presents the following opening dialog in which you can indictate the target Omni application:

Opening Dialog

After clicking the “Continue” button, the script will present dialogs for selecting the target plug-in and for providing the text of the voice command.

The resulting XML (similar to that shown below) will be placed on the clipboard for you to paste into a commands file:

XML Open URL Element


<key>Custom.671255184.38784435</key> <dict> <key>CustomAppName</key> <string>OmniFocus</string> <key>CustomCommands</key> <dict> <key>en_US</key> <array> <string>Open App iCloud Folder</string> <string>Open [the] iCloud Folder for [this] App</string> </array> </dict> <key>CustomModifyDate</key> <date>2022-04-09T20:46:24Z</date> <key>CustomScope</key> <string>com.omnigroup.OmniFocus4</string> <key>CustomType</key> <string>URL</string> <key>CustomURLStringList</key> <array> <string>omnifocus://localhost/omnijs-run?script=function%20performPlugInAction%28pluginID%2C%20actionName%2C%20announceRun%2C%20announceText%2C%20showError%29%7B%0A%09speakerVoice%20%3D%20Speech%2EVoice%2EallVoices%2Efind%28voice%20%3D%3E%20voice%2Ename%2EstartsWith%28%22Alex%22%29%29%0A%09synthesizer%20%3D%20new%20Speech%2ESynthesizer%28%29%0A%09try%20%7B%0A%09%09plugin%20%3D%20PlugIn%2Efind%28pluginID%29%0A%09%09if%20%28plugin%20%3D%3D%3D%20null%29%7B%0A%09%09%09throw%20%7B%0A%09%09%09%09name%3A%20%22Missing%20Plug%2DIn%22%2C%0A%09%09%09%09message%3A%22The%20specified%20plug%2Din%20is%20not%20installed%2E%22%0A%09%09%09%7D%0A%09%09%7D%0A%09%09actionNames%20%3D%20plugin%2Eactions%2Emap%28action%20%3D%3E%20action%2Ename%29%0A%09%09if%28actionNames%2EindexOf%28actionName%29%20%3D%3D%3D%20%2D1%29%7B%0A%09%09%09throw%20%7B%0A%09%09%09%09name%3A%20%22Missing%20Action%22%2C%0A%09%09%09%09message%3A%20%60Action%20%E2%80%9C%24%7BactionName%7D%E2%80%9D%20is%20not%20in%20the%20plug%2Din%2E%60%0A%09%09%09%7D%0A%09%09%7D%20else%20%7B%0A%09%09%09if%28plugin%2Eaction%28actionName%29%2Evalidate%28%29%29%7B%0A%09%09%09%09plugin%2Eaction%28actionName%29%2Eperform%28%29%0A%09%09%09%09if%28announceRun%29%7B%0A%09%09%09%09%09Timer%2Eonce%281%2C%20%28%29%20%3D%3E%20%7B%0A%09%09%09%09%09%09utterance%20%3D%20new%20Speech%2EUtterance%28announceText%29%0A%09%09%09%09%09%09utterance%2Evoice%20%3D%20speakerVoice%0A%09%09%09%09%09%09synthesizer%2EspeakUtterance%28utterance%29%0A%09%09%09%09%09%7D%29%0A%09%09%09%09%7D%0A%09%09%09%7D%20else%20%7B%0A%09%09%09%09throw%20%7B%0A%09%09%09%09%09name%3A%20%22Validation%20Error%22%2C%0A%09%09%09%09%09message%3A%20%60The%20action%20%E2%80%9C%24%7BactionName%7D%E2%80%9D%20is%20not%20validated%20to%20execute%2E%60%0A%09%09%09%09%7D%0A%09%09%09%7D%0A%09%09%7D%0A%09%7D%0A%09catch%28err%29%7B%0A%09%09utterance%20%3D%20new%20Speech%2EUtterance%28%60%24%7Berr%2Ename%7D%2E%20%24%7Berr%2Emessage%7D%60%29%0A%09%09utterance%2Evoice%20%3D%20speakerVoice%0A%09%09synthesizer%2EspeakUtterance%28utterance%29%0A%09%09if%28showError%29%7Bnew%20Alert%28err%2Ename%2C%20err%2Emessage%29%2Eshow%28%29%7D%0A%09%7D%0A%7D%0ApluginID%20%3D%20%22com%2Eomni%2Dautomation%2Eall%2Eopen%2Dapp%2DiCloud%2Dfolder%22%0AactionID%20%3D%20%22all%2Dopen%2Dapp%2Dicloud%2Dfldr%22%0AperformPlugInAction%28pluginID%2C%20actionID%2C%20true%2C%20%22Ready%21%22%2C%20false%29</string> </array> <key>Enabled</key> <true/> </dict>

1st-Run of the Script

For security purposes, external Omni Automation script URLs must be approved by the user. In the forthcoming security dialog, there is an option to indictate that further approval is not necessary (see below). Full documentation regarding Omni Automation script security is available here.

Script Security Dialog

AppleScript Script Code

The code of the script tool, written in AppleScript-ObjC in the Script Debugger editor, is shown below:

AppleScript Script: New Run Omni Automation Plug-In Command


use AppleScript version "2.4" -- Yosemite (10.10) or later use framework "Foundation" use scripting additions -- classes, constants, and enums used property NSUserDefaults : a reference to current application's NSUserDefaults property NSNumberFormatter : a reference to current application's NSNumberFormatter property NSNumberFormatterNoStyle : a reference to 0 property NSCharacterSet : a reference to current application's NSCharacterSet property NSString : a reference to current application's NSString property scriptID : "com.nyhthawk-productions.script.vc-run-omni-automation-plug-in" property defaultTargetAppName : "OmniFocus" property defaultTargetAppID : "com.omnigroup.OmniFocus4" global targetAppName, targetAppID, plugInID, actionID, actionLabel ## USER DEFAULTS set theDefaults to NSUserDefaults's alloc()'s initWithSuiteName:scriptID theDefaults's registerDefaults:{targetAppName:defaultTargetAppName, targetAppID:defaultTargetAppID} set targetAppName to (theDefaults's stringForKey:"targetAppName") as string set targetAppID to (theDefaults's stringForKey:"targetAppID") as string ## USER PROMPT repeat set dialogMessage to "This script will generate the XML text for a new Open URL Voice Command element that launches a specified Omni Automation plug-in installed in the host Omni application." & return set dialogMessage to dialogMessage & return & "Target Application: " & targetAppName set dialogMessage to dialogMessage & return & "Application ID: " & targetAppID display dialog dialogMessage with title "Voice Control Command: Open URL" buttons {"Cancel", "Set App", "Continue"} default button 3 set actionChoice to the button returned of the result if actionChoice is "Continue" then exit repeat else if actionChoice is "Set App" then set targetApp to choose application with prompt "Select the application to use:" tell targetApp set targetAppID to the id of it set targetAppName to the name of it end tell theDefaults's setObject:targetAppID forKey:"targetAppID" theDefaults's setObject:targetAppName forKey:"targetAppName" end if end repeat ## QUERY USER set dialogMessage to "Should this Voice Control command be available only in " & targetAppName & " or System-Wide?" display dialog dialogMessage with title "Availability of Voice Control Command" buttons {"Cancel", "System-Wide", targetAppName} default button 3 set chosenScope to the button returned of the result ## PROMPT FOR PLUG-IN AND GET INFO using terms from application "OmniFocus" tell application id targetAppID set plugInIDs to evaluate javascript "PlugIn.all.map(plugin => plugin.identifier)" end tell set plugInID to choose from list plugInIDs with prompt "Select the ID of the plug-in to run:" if plugInID is false then error number -128 tell application id targetAppID set actionCount to (evaluate javascript "plugin = PlugIn.find(\"" & plugInID & "\");plugin.actions.length") as integer end tell if actionCount is 1 then tell application id targetAppID set actionID to evaluate javascript "plugin = PlugIn.find(\"" & plugInID & "\");plugin.actions[0].name" end tell else tell application id targetAppID set actionIDs to evaluate javascript "plugin = PlugIn.find(\"" & plugInID & "\");plugin.actions.map(action => action.name)" end tell set actionID to choose from list actionIDs with prompt "Select the ID of the plug-in’s action to run:" if actionID is false then error number -128 end if set jscript to "plugin = PlugIn.find(\"" & plugInID & "\"); actionID = \"" & actionID & "\"; plugIn = PlugIn.find(\"" & plugInID & "\"); plugIn.actions.find(action => {return action.name === actionID}).label;" tell application id targetAppID set actionLabel to evaluate javascript jscript end tell end using terms from ## QUERY USER display dialog "Should the script display an error dialog (in addition to the spoken alert) if there is a problem executing the specified plug-in?" with title "Script Parameters: Optional Error Dialog" buttons {"Cancel", "Show Dialog", "No Dialog"} default button 3 if the button returned of the result is "Show Dialog" then set showErrorAlert to true else set showErrorAlert to false end if ## QUERY USER repeat try display dialog "Should script announce the execution of the plug-in? If yes, provide the announcement string:" default answer "" with title "Script Parameters: Announcement" buttons {"Cancel", "Announce", "No Announcement"} default button 3 set dialogResult to the result set shouldAnnounce to the button returned of the dialogResult set confirmationString to the text returned of the dialogResult if shouldAnnounce is "Announce" then set shouldAnnounce to true if confirmationString is not "" then exit repeat else set shouldAnnounce to false exit repeat end if beep on error error number -128 end try end repeat ## PROMPT FOR COMMAND STRING repeat display dialog "Enter the command text or phrase:" default answer actionLabel with title "Voice Control Command: Open URL" set commandString to the text returned of the result if commandString is not "" then exit repeat end repeat ## THE OMNI AUTOMATION SCRIPT FOR CALLING PLUG-IN set functionAndCall to "function performPlugInAction(pluginID, actionName, announceRun, announceText, showError){ speakerVoice = Speech.Voice.allVoices.find(voice => voice.name.startsWith(\"Alex\")) synthesizer = new Speech.Synthesizer() try { plugin = PlugIn.find(pluginID) if (plugin === null){ throw { name: \"Missing Plug-In\", message:\"The specified plug-in is not installed.\" } } actionNames = plugin.actions.map(action => action.name) if(actionNames.indexOf(actionName) === -1){ throw { name: \"Missing Action\", message: `Action “${actionName}” is not in the plug-in.` } } else { if(plugin.action(actionName).validate()){ plugin.action(actionName).perform() if(announceRun){ Timer.once(1, () => { utterance = new Speech.Utterance(announceText) utterance.voice = speakerVoice synthesizer.speakUtterance(utterance) }) } } else { throw { name: \"Validation Error\", message: `The action “${actionName}” is not validated to execute.` } } } } catch(err){ utterance = new Speech.Utterance(`${err.name}. ${err.message}`) utterance.voice = speakerVoice synthesizer.speakUtterance(utterance) if(showError){new Alert(err.name, err.message).show()} } } pluginID = \"" & plugInID & "\" actionID = \"" & actionID & "\" performPlugInAction(pluginID, actionID, " & shouldAnnounce & ", \"" & confirmationString & "\", " & showErrorAlert & ")" ## ENCODE THE OMNI AUTOMATION SCRIPT set encodedString to my encodeUsingPercentEncoding(functionAndCall) set lowercaseAppName to my changeCaseOfText((targetAppName as string), 1) set the scriptURL to lowercaseAppName & "://localhost/omnijs-run?script=" & encodedString ## GENERATE COMMAND IDENTIFIER set IDstring to ("Custom." & generateAbsoluteTimeID()) as string ## GENERATE DATE STRING set dateString to do shell script "date +'%Y-%m-%dT%H:%M:%SZ'" ## GET THE CURRENT LOCALE set localeString to user locale of (system info) ## CREATE THE XML ELEMENT if chosenScope is "System-Wide" then set commandXML to " <key>" & IDstring & "</key> <dict> <key>CustomCommands</key> <dict> <key>" & localeString & "</key> <array> <string>" & commandString & "</string> </array> </dict> <key>CustomModifyDate</key> <date>" & dateString & "</date> <key>CustomScope</key> <string>com.apple.speech.SystemWideScope</string> <key>CustomType</key> <string>URL</string> <key>CustomURLStringList</key> <array> <string>" & scriptURL & "</string> </array> <key>Enabled</key> <true/> </dict> " else set commandXML to " <key>" & IDstring & "</key> <dict> <key>CustomAppName</key> <string>" & targetAppName & "</string> <key>CustomCommands</key> <dict> <key>" & localeString & "</key> <array> <string>" & commandString & "</string> </array> </dict> <key>CustomModifyDate</key> <date>" & dateString & "</date> <key>CustomScope</key> <string>" & targetAppID & "</string> <key>CustomType</key> <string>URL</string> <key>CustomURLStringList</key> <array> <string>" & scriptURL & "</string> </array> <key>Enabled</key> <true/> </dict> " end if ## ANNOUNCE TO USER set the clipboard to commandXML display dialog "The new Open URL Voice Command XML is on the clipboard." buttons {"OK"} default button 1 with title "Voice Control Command: URL" on encodeUsingPercentEncoding(sourceText) try -- create a Cocoa string from the passed AppleScript string, by calling the NSString class method stringWithString: set the sourceString to NSString's stringWithString:sourceText -- indictate the allowed characters that do not get encoded set allowedCharacterSet to NSCharacterSet's alphanumericCharacterSet -- apply the indictated transformation to the Cooca string set the adjustedString to the sourceString's stringByAddingPercentEncodingWithAllowedCharacters:(allowedCharacterSet) -- convert from Cocoa string to AppleScript string return (adjustedString as string) on error msg display dialog msg end try end encodeUsingPercentEncoding on changeCaseOfText(sourceText, caseIndicator) -- create a Cocoa string from the passed text, by calling the NSString class method stringWithString: set the sourceString to NSString's stringWithString:sourceText -- apply the indictated transformation to the Cocoa string if the caseIndicator is 0 then set the adjustedString to sourceString's uppercaseString() else if the caseIndicator is 1 then set the adjustedString to sourceString's lowercaseString() else set the adjustedString to sourceString's capitalizedString() end if -- convert from Cocoa string to AppleScript string return (adjustedString as string) end changeCaseOfText on generateAbsoluteTimeID() ## 669490008.038141 set currentAbsoluteTime to current application's CFAbsoluteTimeGetCurrent() set fmtr to NSNumberFormatter's new() fmtr's setFormat:"#.#########" set exportDateString to NSString's stringWithFormat_("%@", fmtr's stringFromNumber:currentAbsoluteTime) as string if length of exportDateString is not 23 then repeat until length of exportDateString is 18 set exportDateString to exportDateString & (random number from 1 to 9) as string end repeat end if return exportDateString end generateAbsoluteTimeID

 

 

 

LEGAL

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Mention of third-party websites and products is for informational purposes only and constitutes neither an endorsement nor a recommendation. OMNI-AUTOMATION.COM assumes no responsibility with regard to the selection, performance or use of information or products found at third-party websites. OMNI-AUTOMATION.COM provides this only as a convenience to our users. OMNI-AUTOMATION.COM has not tested the information found on these sites and makes no representations regarding its accuracy or reliability. There are risks inherent in the use of any information or products found on the Internet, and OMNI-AUTOMATION.COM assumes no responsibility in this regard. Please understand that a third-party site is independent from OMNI-AUTOMATION.COM and that OMNI-AUTOMATION.COM has no control over the content on that website. Please contact the vendor for additional information.