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:

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:

• The target plug-in’s identifier
• The target plug-in action’s filename (identifier)

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)

 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
Copy Download Plug-In

/*{
	"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:

• By default, the text of error messages are “spoken” by the function using the Omni Speech Synthesis (TTS) class. Optionally, you can also have an error alert dialog displayed in conjunction with the spoken alert.
• In addition, you can choose to incorporate a “spoken” custom announcement when the plug-in is executed. This is useful for plug-ins that perform an action like opening a folder on the desktop: “Done!”

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

Call Plug-In Function
Copy

function performPlugInAction(pluginID, actionName, announceRun, announceText, showError){
	speakerVoice = Speech.Voice.allVoices.find(voice => voice.identifier.endsWith(".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
Copy

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

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

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
Copy

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

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
Copy

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