Passing Data into the Action
The “Omni Automation Script” action for Shortcuts can receive input data by placing a variable containing the data into the action’s Data Input Socket, located within the action title.
The data to be passed-into the action through the Data Input Socket can be stored as a variety of data types:
- String
- Number
- Array (list)
- Dictionary
The passed-in data is retrieved through the use of the argument parameter placed in the script code.
The documentation in this section will provide examples of passing data into the action.
Passing in String Data
The following example Shortcuts workflow (shortcut) shows passing a multiple-line block of text into the action.
1 Passing Action • The Shortcuts “Text” action containing multiple lines of text.
2 Data Input Socket • A Shortcuts variable containing the output of the “Text” action is placed in the Data Input Socket of the “Omni Automation Script” action.
3 Argument Parameter • The argument parameter represents data passed into or stored in the action. The argument.input parameter represents the data passed in via the Data Input Socket, and argument.files parameter represents the file references passed into the action using the Associated Files control.
4 Action Result • Since the last line of the script in the “Omni Automation Script” action is the argument.input parameter, its contents are returned as the result of the action. 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 ) A Shortcuts workflow (shortcut) passing String data into the “Omni Automation Script” action.
Direct String Input
NOTE: The Data Input Socket can accept text as well as variables. In the following example Shortcuts workflow (shortcut), the string to use by the script is entered directly into the socket.
1 “Open App” Shortcuts action • Make OmniOutliner the active application.
2 Data Input Socket • The Data Input Socket can hold text as well as data variables. In this workflow, the string “DRAFT” is passed into the script via the socket to be retrieved using the argument.input parameter.
3 The selection Parameter • An array of references to the currently selected outline rows is generated by appending the term “items” to the parameter: selection.items
4 Validation Check • If there are no selected items, throw an error to the in-script error handler.
5 Error Handler • Display the error information to the user, and then return an Error object to stop the workflow (shortcut).
6 Action Result • The JavaScript map() function is used to process the rows and return an array of identifiers to the selected rows. The passed identifiers can be used by other actions to target the rows, like with this URL: omnioutliner:///open?row=aIAgE10lKLS
TIP: Here is the link to documentation regarding use of The selection Parameter
Passing-in a String in a Variable
In the following example shortcut, the string provided from a user prompt is used to replace the default text in a created object in OmniGraffle.
(⬇ see below ) Selected objects in OmniGraffle 1 are converted into the JavaScript code used to create them by using the “Copy as JavaScript” command 2—3 from the Edit or Contextual menu. When the menu is executed, the self-replicating Omni Automation code is placed on the clipboard.
(⬇ see below ) A shortcut for creating a new text-on-a-circle object using provided text: (DOWNLOAD)
1 The “Open App” action • Makes OmniGraffle the frontmost application.
2 The “Ask for Input” action • Prompts the user 3 to enter the text to use to create a new text-on-a-circle object on the current canvas.
4 The Data Input Socket • of the “Omni Automation Script” action, accepts a variable containing the text passed by the “Ask for Input” action.
5 The Copied JavaScript Code • generated using the “Copy as JavaScript” command is placed within the “Omni Automation Script” action in the shortcut
6 The argument.input Parameter • is used as a replacement for the circle-path text and when the new object is created by the script, the passed-in text will be used for the text-on-a-path.
(⬇ see below ) The prompt dialog displayed to the user, in which they enter the short string to be used for the text-on-a-circle object to be created.
(⬇ see below ) The result of the shortcut is a newly created text-on-path circle using the provided text (string).
Passing in an Array
An Array is a series of items, such as a list of names or numbers. The “Omni Automation Script” action accepts an array as input.
1 Passing Action • The Shortcuts “List” action containing a list of strings.
2 Data Input Socket • A Shortcuts variable containing the output of the “List” action is placed in the Data Input Socket of the “Omni Automation Script” action.
3 Argument Parameter • The argument parameter represents data passed into or stored in the action. The argument.input parameter represents the data passed in via the Data Input Socket, and argument.files parameter represents the file references passed into the action using the Associated Files control.
4 Action Result • Since the last line of the script in the “Omni Automation Script” action is the argument.input parameter, its contents are returned as the result of the action. 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 ) A Shortcuts workflow (shortcut) passing an array (list) into the “Omni Automation Script” action.
Passing in a Dictionary
A Dictionary (also called a “Record”) is an object containing one or more key:value pairs with the data expressed in a variety of classes: Boolean, Number, String, Array, and Dictionary. The “Omni Automation Script” action accepts a dictionary as input.
TIP: if your script requires data from multiple sources in the workflow, creating a an input dictionary is an excellent way to provide script access to the required sources.
1 Passing Action • The Shortcuts “Dictionary” action containing a record 2 of keys with corresponding values.
3 Data Input Socket • A Shortcuts variable containing the output of the “Dictionary” action is placed in the Data Input Socket of the “Omni Automation Script” action.
4 Argument Parameter • The argument.input parameter represents data passed into the action through the Data Input Socket. Since the passed-in data is a Dictionary (record), the individual data items can be retrieved by appending the various dictionary keys to the input parameter, like: argument.input.name The retrieved data is then used to create and format a new Task in OmniFocus.
5 Action Result • Since the last line of the script in the “Omni Automation Script” action is the a statement setting the Boolean value of the flagged property, that boolean value is passed as the result of the action.
(⬇ see below ) A Shortcuts workflow (shortcut) passing a Dictionary (record) into the “Omni Automation Script” action.
Passing in a Date
In Shortcuts, Date objects are converted to String representations when passed between actions or via variables. It is important to set their string style to a format compatible with the JavaScript new Date() constructor to convert them into object instances of the Date class.
An example showing how to set the date format for converting to Date objects in the script:
1 Date Action • The Shortcuts “Date” action is used to generate a date chosen by the user.
2 Passed Date • A variable containing the text representation of the chosen date is placed in the Data Input Socket.
3 Date Parameters Dialog • Clicking on the variable will reveal a dialog for setting the formatting parameters of the date data.
4 ISO 8601 Date Format • Select the standard ISO 8601 format for date representation.
5 ISO 8601 Time Format • Select the standard ISO 8601 format for time representation.
1 Input Parameter • Since the passed data is a date string, the argument.input parameter will retrieve the value.
2 Date String • The resulting date/time string in ISO 8601 format.
1 Date Object • Use the argument.input parameter as the value for the new Date() constructor to convert the date string into an instance of the Date class.
2 Date String • The resulting Date object converted to a string representation by Shortcuts.
Checking for Input Type
In some situations Shortcuts may pass multiple types into the action. For example, shortcuts may pass in an Array for multiple items, or a String for a single item. In such cases, your scripts will need to check for the type of input and handle it accordingly, as in this example where a single string will be converted into an array by the script before processing:
Processing Tasks by ID
// Set input type to "Primary Key"(async () => {try {itemIDs = argument.inputif (JSON.stringify(itemIDs) === "[]"){throw {name: "Selection Issue",message: "No item IDs were received as input."}}// If a single item is passed in, convert to arrayif(!Array.isArray(itemIDs)){itemIDs = new Array(itemIDs)}itemIDs.forEach(id => {task = Task.byIdentifier(id)// TASK PROCESSING STATEMENTS GO HERE})}catch(err){if(!err.message.includes("cancelled")){await new Alert(err.name, err.message).show()}throw `${err.name}\n${err.message}`}})();
For example, here is a shortcut that marks the remaining tasks as complete:
Next…
The next section of this documentation demonstrates how data may be passed from the “Omni Automation Script” action.