Build Shortcuts – Take Control of Shortcuts

Build Shortcuts

Building shortcuts is not unlike creating a project with Lego—there is a series of actions (blocks) and we need to put them together in a way that fits (aligning the bumps), as well as creating the end goal we want (the model). This chapter outlines the key concepts you need to understand to be able to do this. Don’t feel that you need to read and understand everything here before you can build a Shortcut; you can jump ahead at any time and come back later to “fill in the gaps” as you see fit!

Before you do any of these steps, go to the My Shortcuts tab in Shortcuts and tap the plus button in the top-right corner or tap Create Shortcut. On an iPad, the action pane (list of actions you can add to your shortcut) appears on the left, and on the right is the shortcuts editor. On an iPhone, the main view is the shortcuts editor and there is a search bar at the bottom which when tapped reveals the action pane.

One-Step Shortcuts

Many of the shortcuts demonstrated in this book are of the longer and more complex variety, to really give you a feel of how to combine the different actions to achieve powerful results. That said, the most powerful automation is one you can create and use. Inside the Gallery, the section Shortcuts from Your Apps has a whole host of one-action shortcuts you can create with just the tap of a button. Explore these and look at combining them. You don’t need to worry about Input & Output for something as simple as “Play playlist” and “Set HomeKit Scene.” Here are a few ideas for one action shortcuts you can create right now:

  • Play Playlist: Use this to play your favorite playlist with just one tap.

  • Toggle Alarm: Make sure your 7 A.M. alarm is on.

  • Show Directions: Just one tap to get directions home? Yes!

  • Set Playback Destination: Send the music playing on your device to a HomePod quickly.

Actions

An action in Shortcuts is a block; it can accept input and provide output (but doesn’t have to), and it should do something. Tap the icon in the top-left corner of the action (Figure 18) and then tap Info, or tap the Info icon in the action list. A popover appears that should tell you what the action does (though the explanations for some are not the best).

Figure 18: The details of the Set Volume action.

To add an action to a shortcut, find it in the action pane (either by using the search field or by navigating through the available categories), and then tap it. When you do so, the action appears at the end of your shortcut. If you want to add it to a specific place, you can drag it to that position—either from the end of the shortcut or from the action list. Any input the action requires is shown as light blue bubbles (see Figure 19). Many actions have optional extra information, which is shown when you tap Show More and then provides fields for further information you can enter.

Figure 19: The Add New Event action with required and optional inputs.

We also need to be able to delete an action! To do this tap the delete icon in the top-right corner. Some actions, like If, have settings that sometimes appear (the If action has settings only if you delete Otherwise). This is the action settings icon, and appears next to the delete icon.

Copy, Paste, and Duplicate Actions

You can also copy, paste, and duplicate an action. Tap the icon in the top-left corner of the action to see options to copy and duplicate. After you copy an action, if you tap another action in the same place, you can paste above or below. You can copy only one action at a time, but you can copy between shortcuts—including when you have two open on your screen in split screen mode.

Native Actions vs. Actions From Apps

When you start to create a shortcut you have a variety of actions available to you. Native Actions are actions that are built into Shortcuts and available for every user. Apps can also offer their own actions—these are Actions from Apps or App Actions.

Native Actions

Native actions—those found on every device—are divided into six categories: Scripting, Media, Location, Documents, Sharing, and Web. These actions are available on almost every device (see the sidebar just below) regardless of other apps installed, and without them we couldn’t make shortcuts! I encourage you to scroll through the lists of actions on your device, and tap the Info icon on any action to find out what exactly what it does.

Some actions appear multiple times under different sections—this is because the sections work more like tags than folders. The search field at the top of the list of actions is extremely useful when you know what action you are looking for, or which app provides it.

Scripting

Scripting actions form the framework that really hold everything together. These actions are considerably less self-explanatory than the others, so I’ve broken down the groups of actions within the scripting category for you:

  • Apps: This includes the action Open App, which does what it says on the tin.

  • Control Flow: This includes actions like Choose from Menu, Continue in Shortcuts, If, Repeats, and Waits.

  • Device: If you want to get information about your device or change a setting then this section has plenty of actions you can choose from. This includes battery level, screen brightness, and playback destination (for AirPlay).

  • Dictionaries: This contains actions related to dictionaries, by which I’m referring to a programming term, not the books that give you definitions of words. For more information, see Lists, Menus, and Dictionaries.

  • Files: This includes actions to Base64 Encode a file or to generate a hash—these actions can be used on files or text.

  • Items: Much like the info popover in Files or the Finder’s Get Info window on a Mac, these actions help you to get the details of a file or variable.

  • Lists: With these actions you can create a list, present the list as a menu, or get a specific item from a list.

  • Math: All the actions we need to calculate something.

  • Measurements: Like Math, but for measurements!

  • Network: If you need your current IP address or want to control the different radios on your device, the actions in this section serve your needs.

  • No-ops: A fun name for actions that don’t do anything, but still help us, this includes Comment and Nothing.

  • Notification: We have multiple kinds of notifications available, Alerts, banner Notification, vibration, playing sound, and even Ask for Input, which is like an alert with an input field.

  • Numbers: These actions work with both the Math and Measurements actions, or independently.

  • Shell: If you need to Run a Script over SSH, this is the action for you. You can use this to control a Mac or other server via the command line—for example, to make it sleep—or even to control a Raspberry Pi computer. It also supports SSH keys; these are created and stored on your device.

  • Shortcuts: There are two actions here, Get My Shortcuts and Run Shortcut.

  • Variables: This includes the actions for Set and Add to Variable; for more detail see the Variables section below.

  • X-Callback: A URL in the browser starts with http(s)://; this tells your device to open it in Safari (or whichever browser is your default). An X-Callback-URL works the same way, except it tells your device to open an app and do something instead. shortcuts:// tells your iPhone or iPad to open Shortcuts, and shortcuts://x-callback-url/run-shortcut?name=Calculate%20Tip would open Shortcuts and run a shortcut named Calculate Tip, if you happened to have one. URL schemes on iOS are still alive and kicking, though Shortcuts has a new method for its actions. The URL encode action can also be handy if you want to Work with REST APIs.

Location

Where in the world are you? How do you convert a street address into longitude and latitude? These questions and more are answered by the actions in this section.

The first four actions are the core actions related to a location. Use these to filter a list of locations, get our current location, get details of a location, or specify a location. In addition, we have weather and map related actions here.

Sharing

A good number of shortcuts only make sense if we get the data back out of them again, and that’s what this section is dedicated to. You can do everything from setting your clipboard to sending a message or even creating a note.

Media

The media actions are ones we can use to get creative with. Whether you want to get the details of an App Store app, take a photo, record audio, edit images, or play music, there are plenty of actions here to keep you entertained for hours.

Documents

A document is text or a file, and we have a whole host of actions available to let us automate many elements of them. These actions include zipping and unzipping files, saving to iCloud Drive and Dropbox as well as retrieving files from there, and working with Notes.

There are a couple of special actions with reviewing:

  • QR Codes: Whether you want to generate a QR Code of a link to put on a flyer or read a QR code, these shortcut actions are standing at the ready.

  • Translation: If you need to quickly detect which language something is written in, or translate it, then these actions, which use Microsoft’s Bing translator, are here for you.

Web

The web actions cover more than just Safari pages. If you want to get the article from a web page (like the Reader view in Safari), or get the latest entry from an RSS feed, this is the area to look.

Shortcuts from Your Apps

On the Gallery tab is an area called “Shortcuts from Your Apps” (see Figure 20). This is a selection of actions from different apps representing actions you have recently or frequently taken.

Figure 20: The Shortcuts Gallery.

Tapping See All in the top-right corner of this section reveals actions grouped by app (see Figure 21), and depending on your device and its orientation, you can either swipe across the group of actions to reveal them or tap another “See All” to reveal all the actions from an app. Tapping the icon creates a shortcut with just this action and allows you to name it.

Figure 21: Shortcuts from Your Apps.

Before Shortcuts was Shortcuts, the team built in support for lots of popular apps, such as Drafts and OmniFocus. Since September 2019, developers can now build these actions into their own apps, and have them show in Shortcuts! This is much better for you and me, the users, but also for the developer who doesn’t have to wait for Apple to fix things. Except for those poor popular apps who were added by the Workflow team. These actions are still in Shortcuts, so you might see some actions twice, or two very similar actions. There is no easy way to tell which action is which, so if this happens to you then I recommend looking in the app (e.g., Drafts) for the help or support documentation to see which action the developer wants you to use.

Favorite Actions

There are some actions you will use more frequently than others, and you can add these to your favorites. Tap the icon in the top-left corner of an action in the shortcuts editor, or tap the Info icon in the action list, and then tap Favorite. Favorites are another top-level category available at the top of your action list.

Name

Although the name of your shortcut is usually one of the last things you set, it has several implications you should know about. You may see several shortcuts in the app already, and the names of these shortcuts are how you can call them using Siri. Just as with any document or file, you should also name it so you can recognize it and find it later.

Variables

A variable is a temporary place to store one or more values. They allow you to get data in one part of your shortcut and use it in another part. For example, anything you share to a shortcut is in the variable Shortcut Input, so you can retrieve this anywhere you want or need to in your shortcut to use.

Shortcuts has both explicit and implicit, or magic, variables, and both are useful in their own ways. Let’s look at these!

Setting vs. Adding to a Variable

An explicit variable is one you deliberately create. Shortcuts has two actions for explicit variables, Set Variable and Add to Variable. Both these actions create explicit variables, with a name you choose, but the two actions work in different ways. Set Variable overwrites whatever value your variable has, while Add to Variable adds another value.

If you start with a variable Animals and set it to Dog, then later set it to Cat, when you go to use it, Animals gives you the value Cat. However, if you Add to Variable every time, when you use Animals later, you have two values, Dog and Cat. (We don’t get DogCat—Shortcuts doesn’t glue anything together for us!)

If you use the Set Variable or Add to Variable actions, these variables are shown above your keyboard, making it easy to access them.

Magic Variables

Most actions in Shortcuts give us output, and the outputs of these actions are automatically made available as magic variables. When you tap a variable field in an action, the option to choose a Magic Variable is represented as a magic wand icon above the keyboard on the left; recent actions are also listed here (see Figure 22).

Figure 22: The extra keyboard row in Shortcuts.

So if you have an Ask for Input action, you can choose Provided Input as a magic variable, while Add to Calendar gives us a New Event variable.

When you tap the magic wand to select a magic variable, your keyboard disappears, your actions fade, and variables appear between them with small icons representing their type (Figure 23).

Figure 23: Selecting a magic variable.

You can also rename a magic variable. To do this, select it in an action and then tap Rename on the menu that appears. This pops up a dialog (Figure 24) where you can type the name—then, wherever you use the variable and whenever you open the selector for magic variables, this name will be shown. I recommend renaming magic variables you work with to avoid confusion; otherwise, you may end up with six Provided Input variables and it will be bothersome to keep them straight.

Figure 24: Renaming a magic variable.

Persistent Variables

There are some variables that always appear in the keyboard row; we call these persistent variables:

  • Ask Each Time: Every time you run your shortcut, this field is shown for you to fill out. Some fields let you add your own text or another variable as well.

  • Clipboard: This contains whatever is currently on your clipboard.

  • Current Date: This is the current date and time when the shortcut gets to it. If you have a long shortcut with a Current Date at the beginning and another at the end, they will have slightly different values.

  • Shortcut Input: For any shortcuts that accept input, this allows you to get it and manipulate it.

Getting Variables

Every action that accepts input has a spot where you can select which variable it should work with (see Input & Output). By default this is filled with the last output provided—usually from the action above it.

Variables as Programming Data Types

Just as in a programming language, variables have types, by which I mean a variable could be a number, text, a file, a song, or even an app. A variable’s type dictates what you can do with it. Just as we wouldn’t try to multiply two words together, Shortcuts can’t either—so we need to understand types to know how some of these actions work best.

Most items are objects, which means they are collections of parts, each of which can have a different type. Examples are calendar events, apps, music, and photos. A calendar event is an object, but the start time is a Date, what we think of as date and time. Lots of object types have actions, such as Get Details of Calendar Event, to let us extract different properties of this object. A dictionary is also an object that we can define ourselves; it pairs keys, what we use to look something up, and values—what we get when we look up the key. There are dictionary actions to get and set properties.

A list is an array, which is an ordered collection of items. The array’s index, or what we use to find something in it (like the key in the dictionary above), starts at 1 (whereas in some programming languages it starts at 0). So if we have a list with three items; Cat, Dog, Parrot, then Cat is at index 1, Dog at 2, and Parrot at 3. If you want to process every item in a list or a collection (a list of objects, such as multiple calendar events from Find Calendar Events) we can use two actions. Repeat With Each gives us every action in our list or collection in turn, so we can process them in the same way. Get Item from List lets you specify an index, and get the item at that index—so if we Get Item from List at Index 1, we get Cat. If you use Add to Variable you build a collection, and the Split Text action gives us a list. You can work with them the way I detailed here.

Formatting Variables

Usually when I say “format” I am talking about text in a document (like this one!) where I can apply font formatting. Formatting a variable does more than change what it looks like; it changes how it acts and reacts—specifically it changes the type (typecasting in programmer-speak). To see what type a variable is, tap it where you have used it. An editor pops up (Figure 26), and you can see the name of the variable with as [Type], this tells you which type your variable is.

Figure 26: View the format of a variable.

For example, the Ask for Input action usually provides the output as text, but if you set it to accept a number or date, you will want to work with it in the same format. Tap the variable to see what format something is, and tap the as ___ > text to choose from a range of formats.

Formatting Dates

Dates are a whole other ballgame when it comes to formatting. Shortcuts has a specific action to format a date, or you can format it when you use it the same way I detailed above. Shortcuts has an action, Format Date (Figure 27) which, I’m sure you’ll be surprised to know, can format dates!

Figure 27: The format date action in Shortcuts.

The app has several built-in formats for both date and time, and you can set these independently. What these formats deliver changes based on the region your device uses. This is what the different formats produce:

  • Short: 12/9/19, 9:18 AM

  • Medium: Dec 9, 2019 at 9:18:00 AM

  • Long: December 9, 2019 at 9:18:00 AM GMT+1

  • Relative: in 3 weeks

  • RFC 2822: Mon, 09 Dec 2019 09:18:00 +0100

  • ISO 8601: 2019-12-09T09:18:00+01:00

These formats are always available to us whenever we want format the date. You can also set the date or time to none if you just want one of the parts.

You can build nearly any date or time format using letters that represent part of the date/time, sometimes with different meanings assigned when you repeat the letter:

  • Year y: Repeat this twice for a two digit year, and four times for a four digit year.

  • Month M: Repeat this once or twice for a one or two digit month, and three or four times for a short or long word format.

  • Day of the week e: Like the month output, repeat this three or four times to get the short or long format of the day as a word.

  • Hour h or H: Use the lowercase to get a 12-hour date format, or uppercase for 24-hour. One instance produces a single-digit format, and two produces a two-digit format!

  • Minute m: A single m becomes a single-digit minute, and two is the double-digit version.

  • Second s: This works the same way as minutes.

  • AM or PM a: a single a outputs either am or pm, based on the date in question.

So, if you put EEEE, MMM d, yy. h:mma in the custom format, you get Wednesday, December 4, 2019. 9:18AM (assuming this correlates with the date you provide).

For the full breakdown on the magic code to format dates, you can review the ICU User Guide—the standard Shortcuts uses.

Input & Output

Two crucial concepts in Shortcuts are input and output. Input is what you provide to an action and how you provide it, and output is what you get out. For example, the Make PDF action accepts anything as input (seriously, it says anything), and the output is a PDF. (Five points if you guessed the output!)

To see what input an action accepts, check the action information by tapping the icon in the top-left corner of any action (the same way we check what our Actions do). Input is integrated into the action—highlighted in blue (Figure 28). If you add an action below another one, the second action will automatically have its input set to the output of the previous action. This is the same way Automator on the Mac works. You can tap the variable there and remove it to select another variable, or type in your own text instead (if the action accepts text as input).

Figure 28: An action with a variable spot.

Actions (usually) deliver output. This is our result and is then available to all subsequent actions as one of our Magic Variables. So the Make PDF action gives us a PDF we can use as the input to (for example) a Share action.

Some actions, like Choose from Menu, say “This action passes input through as output,” which means they does not accept input or provide output and instead execute an action independently of everything else.

If and Otherwise

It’s nice to be able to use logic within a shortcut (or every day life) to decide what to do in different situations. We humans are pretty good at figuring out “if it’s raining, take an umbrella, but otherwise, leave the umbrella at home.” In order for a Shortcut to do this we can add an If action. If doesn’t come alone; it brings Otherwise along with it, as well as End If to indicate where the conditional statement ends.

The first block in If is If [input] [condition], which alone sounds rather…fuzzy. First we have to give it input. Shortcuts does this automatically if we have another action before the If; otherwise, we must add an action. If gives us a lot of choices, and these depend on what we give it! For example, let’s start with a Select Photos action before our If. Now when we tap Condition we have two choices: has any value and does not have any value (Figure 29).

Figure 29: The options for the Condition of an If action with a photo as input.

But, if we tap Photos and select Width, the Condition gives us a lot more choices. Width is a number, so we can compare it to another number—either exactly, or relatively (Figure 30).

Figure 30: The options for the Condition of an If action with the Photo Width as input.

Please note: I am not responsible if you program your shortcut incorrectly and get rained on! 😉

Repeat Loops

A Repeat Loop is a way to do the same actions time and time again. Shortcuts has two kinds of repeat loops—Repeat and Repeat With Each.

Repeat lets you input a number to set how many times the action happens. If you touch and hold on the repeat count, you can set it to the value of a magic variable rather than to a fixed number.

Repeat With Each takes input, such as every line from Split Text, and goes through each item. If you want to send someone a copy of your calendar events for today, you would use Repeat with Each after you have the calendar events to produce a list of the name of the event with the start and end times. Or, if you want to add a task to read each chapter of a book, you can use a plain Repeat action, with the count set to the number of chapters for the book. For both of these examples you need to use the Repeat variables: Repeat Index and Repeat Item.

In Figure 31 you can see an example of how these two variables work.

Figure 31: The repeat variables.

Repeat Index is a magic variable created by both repeat loops; it starts at 1 and increases every time the repeat loop runs—so with the example of the chapters, you can use the Repeat Index to specify the chapter number.

Repeat Item is available only in the Repeat With Each loop. It gives you the content you are working with—so if you have calendar events, your repeat item is one calendar event.

Lists, Menus, and Dictionaries

Adding choices to your shortcuts is something you will find extremely useful. There are three ways to do this, depending on what result you want:

  • List: A list gives you what you choose, so if I have a list with “Haircut,” “Cinema,” and “Dinner” as the options, followed by a Choose from List action, I will get whichever option I have chosen (see Figure 33). If multiple options are enabled I will be given all of the options I choose (and can work through them with a repeat loop).

    Figure 33: A list in Shortcuts.
  • Menu: A menu is more like branching. If I have a menu with the same three options, “Haircut,” “Cinema,” and “Dinner,” then choosing one of those allows me to nest actions within it. The simplest example of a menu would be “Yes” as the only the option. Choose from Menu and Choose from List automatically add a Cancel option for us so when we run our shortcut, we see Yes and Cancel (Figure 34).

    Figure 34: Choose from Menu.
  • Dictionary: A dictionary is a halfway between a list and a menu. A dictionary allows me to choose Haircut and get different data out—just like a dictionary in the traditional sense gives you a meaning when you look up a word. This is extremely useful if we want to choose “Haircut” but instead get the text “Haircut 9 AM Monday” back. In your dictionary Haircut is the key, “Haircut 9 AM Monday” is the value, and the dictionary returns the value (Figure 35).

Figure 35: A dictionary and a Choose from List action.

Dictionaries allow you to store text, numbers, arrays (lists), dictionaries, and booleans (true or false). There’s unlimited nesting, which can become complex, but there are examples later in the book which include them.

Debug Shortcuts

For better or for worse, creating shortcuts is programming. This means that things go wrong, so we creators need to find out what went wrong, how it went wrong, and how to fix it. Here are some key tools that should be kept in your virtual toolbox at all times to help you whenever you get stuck or want to break something down.

Quick Look

Quick Look shows you exactly what you’re working with, in the format you choose. This can let you see if your variable is being set in the way you want, or check that an action is returning output as you want. Quick Look launches you into Shortcuts if you run the shortcut from Siri or the Widget. The format of your variable dictates what you see, so a Location defaults to the Address (Figure 36).

Figure 36: The Quick Look action with a Location.

Alert

Quick Look is great, especially as it can show you a lot more than the Alert dialog, but what if, after seeing something, you want to be able to stop? By default, an alert shows you an OK and a Cancel button (Figure 37). The latter stops your shortcut right then and there—consider it a handy emergency escape hatch you can drop in wherever you want—before you start your shortcut, of course.

Figure 37: The Alert action with default settings.

Cheat with Repeat

If you are debugging a shortcut and don’t want to run a section of the actions, but don’t want to delete them either, you can instead put a number action in your shortcut and set it to zero. Then put a Repeat action in, set the count to your number (Repeat can’t be set to zero by itself), and drag the bottom of the repeat down to the end of the actions you don’t want to run.

You can also use Repeat to help you move a whole series of actions at once without losing their order. Drag the repeat into the shortcut and the end of it below the last action you want to move, then drag your whole repeat loop. When you’re done, delete the repeat block—and keep the actions inside it.

Graphical Representation (the Icon)

Most humans identify things by what they look like, instead of the text below or next to something. For this reason we can, and want to, give our shortcuts a good visual representation.

The name of the shortcut is important, but the icon is too. There are three elements to an icon:

  • Color: In Shortcuts we can choose from 15 different colors (Figure 38) to represent our shortcut. You could use these to represent different kinds of shortcuts (such as all Music is pink), or to help you identify how shortcuts are usually run (green is share sheet).

    Figure 38: Icon colors in Shortcuts.
  • Glyph: If your shortcut has actions from only one app, it automatically shows the icon of that app in Shortcuts. If you have actions from lots of apps, including Shortcuts actions, it will show the glyph you choose (Figure 39).

    Figure 39: Some of the many glyphs available for a shortcut.
  • Home screen icon: When you add a shortcut to your Home screen, you can tap the icon and select any image from your photos or files, but this does not change what we see in Shortcuts.

Run a Shortcut Inside Another Shortcut

As with everything in life, at some point or another you will realize you are repeating yourself in Shortcuts. An example that comes to mind is my preferred method for formatting calendar events for display or to be spoken through Siri. Instead of creating these steps manually in multiple shortcuts, and then when you want or need to make a change looking for every shortcut where you did this and fixing it, you can create another shortcut and run it in a shortcut with the action Run Shortcut. You can pass input to it and get output from it—so you are making your own actions as shortcuts!

There’s a neat little trick to prevent all of these function shortcuts from showing up in a share sheet—let them accept input, but turn off all the input types. To do this, open the Details view of your shortcut, and tap Share Sheet Types. Tap Deselect All in the top-right corner to uncheck all the options (Figure 40).

Figure 40: Set the Share Sheet Types for a shortcut.

This lets you use it in another shortcut but means it will never get in your way elsewhere!

Organize Shortcuts in Folders

The graphical representation and the name are not the only way to find shortcuts. In iOS 14 and iPadOS 14, Apple added folders to the app. Folders, just like you are used to with Finder and Files, allow you to sort your shortcuts—a shortcut can live in just one folder. In addition to this there are several smart folders—All Shortcuts, Share Sheet, and Apple Watch.

To add a folder, tap Shortcuts in the top-left corner, and then add a folder with the folder icon in the top-right corner. Next you should name your folder, and change the icon if you want to. The folder then appears in the list—displayed on the left on the iPad, and on the current screen on the iPhone. When you tap into the folder you can add a shortcut directly to it, and change the name and icon with the edit button. From All Shortcuts, you can use the Select button to choose shortcuts and move them to a folder of your choice.

There are several smart folders, Share Sheet, Apple Watch, and Sleep Mode. The Apple Watch and Sleep Mode shortcuts only show on iOS devices.