“Omni Automation Script” Action Interface

The “Omni Automation Script” action for Shortcuts is designed to enable the execution of Omni Automation scripts within a Shortcuts’ workflow (shortcut).

This action presents a simple interface with options for accepting data input, identified related files, and the code of the Omni Automation script placed within its interface.

The action interface is as shown (except for the app icon), regardless of the hosting Omni application: OmniFocus, OmniGraffle, OmniPlan, and OmniOutliner.

(⬇ see below ) The action interface (collapsed) in the OmniFocus instance of the “Omni Automation Script” action.

1 Action Title • The title of the “Omni Automation Script” action.

2 Data Input Socket • Accepts a string, as well as variables containing the data to be passed-into the script. The socketed variable may contain data stored as a string, integer, array (list), or dictionary. Passed-in data can be retrieved within the script using the argument.input parameter.

3 Expand/Collapse View • A toggle control for expanding or collapsing the action interface.

4 Script Field • The Omni Automation script is pasted or written into this field, that automatically expands or contracts as needed around the script code.

5 Associated Files Control • Files to be made available to the hosted script with sandbox approval, are selected from the file picker dialog summoned by selecting this control. Stored file references can be retrieved within the script using the argument.files parameter.

(⬇ see below ) The action interface (expanded)

Script Template: Asynchronous Wrapper with Error Handler

Use this script template with the “Omni Automation Script” action:

If your script incorporates the display of an action form
If your script may need to display an error message to the user

Asynchronous Wrapper with Error Handler


(async () => {
	try {		
		// SCRIPT STATEMENTS GO HERE
	}
	catch(err){
		if(!err.causedByUserCancelling){
			await new Alert(err.name, err.message).show()
		}
		throw `${err.name}\n${err.message}`
	}
})();

NOTE: this script will stop its parent shortcut workflow after the error message has been displayed in the host Omni application.

Example Script with No Input

Scripts used with the “Omni Automation Script” action for Shortcuts can be simple or complex, comprising a few lines or many lines of code. Scripts may even include Omni Automation Forms in order to present interfaces to the user to collect data or indicate selections.

The following is an example Omni Automation script that, while requiring no input, presents a simple menu form to the user, and returns the value of the chosen option back to the parent Shortcut (workflow). This example script works with any of the Omni applications.

Return Title of Chosen Menu Item


(async () => {
	try {
		weekDays = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
		weekdaysMenu = new Form.Field.Option(
			"weekday", 
			null, 
			weekDays, 
			weekDays, 
			"Sunday"
		)

		inputForm = new Form()
		inputForm.addField(weekdaysMenu)

		formPrompt = "Choose a day:"
		buttonTitle = "Continue"
		formObject = await inputForm.show(formPrompt, buttonTitle)
		weekday = formObject.values["weekday"]
		return weekday
	}
	catch(err){
		if(!err.causedByUserCancelling){
			await new Alert(err.name, err.message).show()
		}
		throw `${err.name}\n${err.message}`
	}
})()

The Shortcuts Workflow (shortcut) [DOWNLOAD]

1 Open App Action • Begins the Shortcut by making OmniFocus the active application.

2 No Input • In this example, the “Omni Automation Script” action has no input passed into it, so the “Input Socket” is empty.

3 Omni Automation Script Code • The script is comprised of Omni Automation JavaScript code wrapped in an asynchronous function that presents a form with a simple menu 4

5 The Form Menu • The value for the chosen menu item is returned from the script, and is passed s a result to the parent workflow 7 NOTE: if the script is not wrapped as a function returning a result, the resulting value of the last line of executing code is returned as the script action result.

(⬇ see below ) The example Shortcuts workflow (shortcut).

(⬇ see below ) The form interface displaying an options menu.

Next…

The next section of this documentation demonstrates how various data types may be passed into the “Omni Automation Script” action via the action’s Input Socket.