Federico
Files actions in iPadOS 15.
Hello everyone, and welcome to the first monthly lesson of the Automation Academy. As the release of iOS and iPadOS 15 draws near, this month we’re taking a look at a revamped suite of actions in the updated Shortcuts app that will radically change how you can get work done on iPhone and iPad: the new Files actions.
In this lesson, I’ll explain how Shortcuts’ new integration with Files works and how it differs from iOS 14; I will take a closer look at new and updated actions and cover a variety of tips and tricks on how to configure them; and finally, I’ll be sharing a selection of shortcuts I’ve put together to demonstrate these actions, along with the first assignment for Club MacStories members.
Let’s get started.
For the past several years, I always complained about one particular aspect of Shortcuts in my iOS and iPadOS reviews: its lackluster integration with the Files app. It took replacing Automator for Apple to figure this one out, but proper integration with any file or folder from the Files app is here, and Shortcuts can, at long last, go beyond the limitations of its iCloud Drive sandbox.
Here’s a first high-level concept to understand: starting with iOS and iPadOS 15, you’ll no longer be limited to the iCloud Drive/Shortcuts sub-folder when it comes to programmatically (i.e. without user interaction) saving or retrieving files. Instead, Shortcuts can now be granted access to any external location that supports the modern Files framework. And it’s not just files: for the first time, Shortcuts is now also aware of folders, which will allow you to have even greater control on your documents.
Before I dig into the specifics of the updated Files actions in Shortcuts, let’s take a look at what these actions are. Files actions live under the ‘Documents’ category in the Shortcuts action library, and here’s the full list of Files-based actions you will find in iOS and iPadOS 15:
All of these actions (both existing and new ones) are fully compatible with Shortcuts’ extended support for the Files framework. But how does that integration actually work?
It’s quite simple: Shortcuts now comes with a native Files picker that lets you configure actions before running a shortcut so that you can fetch a specific file or access a specific folder no matter where they are located on the filesystem. With this approach you are, effectively, poking a hole in the Shortcuts application sandbox and giving the app access to a different location or document stored elsewhere. This process needs to be performed manually by the user: you’re always in control of configuring Files actions and the location they’re using; apps or shortcuts can never go and read files scattered across the filesystem without your explicit permission.
This new technology is best demonstrated by the Get File from Folder action, which, as the name implies, lets you retrieve a file from a specific folder and pass it as input for the next action in a shortcut. By default, this action is set up to read files from the usual ‘Shortcuts’ sub-folder in iCloud Drive. However, you’ll notice that the ‘Shortcuts’ folder name is now a blue, tappable parameter. Tap it, and you’ll see that you can now replace the Shortcuts folder with something else. Tap the ‘Replace’ button, and you’ll be able to pick folders from any installed file provider that supports the Files API; this includes any other folder from iCloud Drive, your local storage, apps like Working Copy, and even servers you’re connected to over SMB.
Going outside the sandbox with iOS 15.
So this is how Shortcuts in iOS 15 can go beyond the limitations of its former iCloud Drive sandbox: you give it permission to access external folders, and that needs to be done only once. When a shortcut is configured to read files from an external location, that access will stick across device reboots and system updates; if the same service or app is installed on other devices (e.g. iCloud Drive or Working Copy), an action you configured on iPad will work on iPhone and Mac too, and vice versa. Of course, whenever you give Shortcuts permission to access files and folders on your filesystem, that authorization will be reflected in the shortcut’s Privacy screen, which has been redesigned in iOS 15:
Privacy details for Files access.
To finish the example above with the Get File from Folder action: after choosing a folder, you can get a specific file from it by entering its file path. Pay attention to this aspect since this is a key concept you can reuse for all other Files actions: file paths in iOS 15 support both individual file names (e.g. ‘Dashboard.md’) and sub-folder paths.
If you have a file called ‘Scratchpad.md’ stored in a sub-folder named ‘Personal’ that is contained in a parent folder named ‘Documents’, here’s how you can get it using the Get File from Folder action:
Different ways to access the same file.If you’ve followed how Apple’s new system for files and folders in Shortcuts works so far, you may be wondering: how is it any different from the security-scoped “bookmarks” you covered on MacStories before with Toolbox Pro and Scriptable? The technology is, I believe, the same, but there’s an important implementation detail worth mentioning. Apple’s approach is more straightforward: to give Shortcuts access to any file or folder you want, you just pick a location with a native Files picker. Unlike Scriptable and Toolbox Pro, you don’t create global “bookmarks” in the app’s settings and give them a unique name; you just configure Files access on a per-shortcut basis by picking different files and folders in the actions you want to use. As we’ll see later, the only downside of Apple’s approach is that it doesn’t quite work for shortcuts that have to deal with local storage.
Alright, let’s get into the finer details of some of the new actions now.
With these two actions, you can select specific files or folders beforehand, so that when a shortcut runs, the actions are already set to specific locations on the filesystem. For example: if you want to compress a specific folder as a .zip archive every day and back it up to Dropbox, you can use the Folder action, point it to that specific folder, and it’ll always be used in that automation.
The File and Folder actions.
Essentially, the goal of these actions is to provide you with a way to statically embed individual files or folders in a shortcut and use them as variables. You can configure both actions with the same approach I described above (via a Files picker) and, interestingly, you can assign multiple files or folders to the same action. Just click the ‘+’ button next to each action to continue picking more files or folders you want to use in a shortcut, and that’s it.
As you can imagine, the actions return two distinct ‘File’ and ‘Folder’ magic variables you can inspect to extract specific properties out of each file or folder. The ‘File’ variable isn’t new to Shortcuts and it contains the usual name, size, extension, and date properties. The ‘Folder’ variable is new though, and it comes with some fascinating details we can use:
Properties for a folder variable.I’ve emphasized the properties I think deserve your attention when it comes to scripting folders in Shortcuts. When you’re working with a folder variable in Shortcuts for iOS 15, you can use variable properties to, say, count how many files are contained in a folder or just fetch the entire contents of a folder. With the Last Modified Date property, you could put together a shortcut that sorts multiple folders in a list based on when you last added something to them.
Oddly enough, the ‘Filter Files’ action can be inserted after a ‘folder’ variable, but it won’t offer the same filters you can otherwise get as variable properties. I assume this is a leftover implementation from iOS 14 that will be updated for folders eventually.
“Filter files”, but it’s a folder.
One more thing on these actions: both File and Folder can be configured to run dynamically at runtime without a pre-selected file or folder inside them – meaning they’ll ask you to pick a file or folder each time a shortcut runs. As you can imagine, you can do this by adding an ‘Ask Each Time’ value to the File or Folder parameter in the action. Doing this is kind of hidden though: you have to long-press the empty parameter until a menu comes up, and from there you’ll be able to pick the ‘Ask Each Time’ value. When a File or Folder action with an ‘Ask Each Time’ value runs, you’ll see a new dialog in iOS 15 to pick a file or folder manually.
Choosing a file at runtime.
Given that the File and Folder actions can be configured to run dynamically at runtime, I find the inclusion of a separate ‘Select File’ action somewhat curious.
Think of this action as a dynamic-only equivalent of File and Folder: this action lets you select a file or folder only when a shortcut runs with a native Files picker. You can configure the action in either file or folder mode, and if you expand it, you’ll also find a toggle to select multiple files or folders at runtime.
Selecting files.
What’s odd about this action is that it’s redundant. You can configure the File or Folder actions with the Ask Each Time method I described above, and the end result will be the same. Even the ‘Select Multiple’ flag doesn’t seem necessary: if you make the File action dynamic, you can still select multiple files at once by tapping the More button in the Files picker (the three dots) and hitting ‘Select’ from the menu to enter a multi-file selection mode, achieving the same results as the ‘Select File’ action configured with Select Multiple.
You can still select multiple files at once with a dynamic File action.
Furthermore, as of the latest iOS 15 developer beta, the Select Multiple option for the Select File action just doesn’t work for selecting multiple folders. When the Files picker comes up in folder selection mode, you can only select one folder at a time. For this reason, I don’t really understand why the standalone Select File action exists, or why is it labeled in such a way that may confuse people seeking to select folders. The only reasonable explanation I came up with is that the Select File action doesn’t display an additional Choose File/Folder alert when a shortcut runs. Perhaps this action can become more useful once multiple folder selection gets fixed; for now, I’d recommend sticking with the more versatile File and Folder actions.
The Get Contents of Folder action is, arguably, one of the best additions for power users this year. This action lets you fetch all files contained in a folder with a single step; it even comes with a ‘Recursive’ toggle that returns all files from a folder including its sub-folders, which opens up some fantastic possibilities for file automation.
Getting the contents of a folder and all its sub-folders.
Get Contents of Folder is the action you want to use for those times when you need to build a shortcut that gets all files from a folder and outputs them as a list of items. There are several potential use cases for this action, which I’m going to detail later in the Examples section, but allow me to point out a few essential takeaways upfront.
Because the result of the Get Contents of Folder action is a list (in Shortcuts parlance, a “list” is a variable that contains multiple items in it), you can put a Choose from List action after it and you’ll end up with a very simple, yet effective menu that shows you all the files stored inside the folder you selected; you can pick one or multiple files from the list and generate a File variable for the chosen file. In this case, something like Get Contents of Folder ⇾ Choose from List ⇾ Share would be an effective shortcut to select a file from a specific folder and instantly share it with extensions.
Getting the contents of a folder and sharing with extensions.
By the same token, because the Get Contents of Folder action returns a list of files, you can connect a Filter Files action to it if you want to filter files by specific criteria or sort them in a particular order. Want to get the five most recently modified files from a specific folder somewhere on your iPad? Easy to do with just two actions in iPadOS 15:
The ‘Recursive’ toggle is also worth your attention: if you enable it, the action will get all files inside a folder, including those stored in sub-folders. This can be useful for shortcuts that deal with creating backup copies of large projects spanning multiple sub-folders; you’ll lose the folder structure if you do this, but at least you’ll end up with a collection of all files stored in the parent folder you can save somewhere else with other actions.
Here’s another concept to understand about how the Files actions work: Shortcuts is always aware of the original location of a file, so even if you pass a variable representing the original file to the Move and Rename actions, those will continue to work.
It’s important to keep this in mind because, by looking at the Move and Rename actions and how they’re designed, you may think you always have to manually pick a file in the empty ‘File’ parameter in order to move or rename it. But that’s not the case. If you fetch a specific file at the beginning of a shortcut and save it to a variable, add 10 unrelated actions in the middle, then use the Move action at the end of the shortcut to move that variable to a different folder, that will stil work. When a file is saved to a variable (or magic variable – it doesn’t matter) the variable contains all the necessary information for other actions to deal with that file.
You can now rename and move files in any folder.
Keep this in mind since you’ll want to interact with manual Files pickers as little as possible now that Shortcuts has full support for the entire iOS and iPadOS filesystem.
Here’s a more advanced detail I stumbled upon as I was preparing this lesson: Shortcuts in iOS 15 features partial support for accessing files stored in hidden folders.
If you’re a Mac user, you should be familiar with hidden folders in the Finder: by default they are, well, hidden, but if you decide to show them, they’ll be displayed with a ‘.’ character in front of their name and they’ll be dimmed in the UI. That’s why these items are also often called “dot files”.
iOS and iPadOS have never supported hidden files and folders in the Files app, and to this day there’s still no way in Files for iOS or iPadOS 15 to display them. While I was looking into a solution to inspect the contents of the hidden ‘.obsidian’ folder in my Obsidian vault on iPad, however, I discovered that the Get File from Folder action supports retrieving files stored in a hidden folder if you provide an absolute file path to the action.
How to get hidden files in iPadOS 15.
As you can see in the screenshot above, you can do this by selecting a parent folder in the main folder parameter of the action, then navigating to the hidden location in the file path field. I’ve been using this technique to fetch JavaScript and CSS files stored in the hidden .obsidian folder on my iPhone and iPad, and it works like a charm.
Unfortunately, it appears that, at the moment, Shortcuts only offers partial support for hidden files and folders: you can retrieve files in hidden folders, but you cannot save them. If you provide a hidden folder path to the ‘Subpath’ field of the Save File action, Shortcuts will throw an error. Hopefully, this will be fixed soon; I have a feeling that every Obsidian user with an iPhone or iPad would love to be able to save plugins and CSS snippets manually using native Shortcuts actions.
This concept is more specific to Obsidian, but I think other members may benefit from learning about it as well. Suppose you have an application that stores its files in the On My iPad and On My iPhone local storage providers of iPadOS and iOS and you want to build shortcuts that process specific folders or files in that database. Let’s say you want to access a file named ‘Test.md’ that’s stored at the root directory of this database. You build a shortcut on your iPad that uses the Get File from Folder action to read this file by selecting the app’s root folder and typing ‘Test.md’ in the file path. The shortcut runs and works perfectly on iPad; you then run it on iPhone, where the same app has the same database with the same files, and the shortcut says the file doesn’t exist. Why?
The crux of the problem here lies in how, technically, On My iPad and On My iPhone are different locations that Shortcuts cannot reconcile across multiple platforms. A provider named “On My iPad” doesn’t exist on iPhone, and vice versa. There isn’t an ideal solution for this niche use case at the moment, but we can work around it.
My recommendation is the following: if you find yourself in this scenario (again, most likely because you’re an Obsidian user), you have to pick the same folder twice on each platform and configure your shortcut so that it knows on which device it’s currently being executed. You can take a look at my recommended solution in the image below:
My routine to assign separate iPhone and iPad folders in the same shortcut.
The idea here is simple enough: we can combine the ‘Get Device Details’ action with a conditional block to check the device model that’s currently running a shortcut. The conditional block has two possible outcomes: the shortcut is either running on an iPad or an iPhone. Inside each block, you have to pick the root folder and save it to a variable of the same name. Later, depending on whether you want to get the contents of a folder, access a file from it, or save a file into it, you can just use the named variable as a root directory.
This way, every time the shortcut runs, it’ll check if you’re using an iPhone or iPad, and it’ll know which folder it needs to access in the On My iPad or On My iPhone local storage providers. This approach requires more configuration upfront, but it’s foolproof system once it’s properly set up. I’ve been taking advantage of this technique for all my shortcuts that deal with my local Obsidian vault, and it works beautifully every time.
Here are some shortcuts I put together to demonstrate the power and flexibility of the new Files actions in iOS and iPadOS 15.
The first shortcut is a simple one that demonstrates how you can now save files anywhere in the Files app since there are no longer any sandboxing limitations in Shortcuts. With this five-action shortcut, you can quickly jot down some text in a ‘Text’ action, and it will be saved as a time-stamped Markdown file in a folder of your choosing.
Saving text files outside of Shortcuts’ document sandbox.
This shortcut doesn’t do anything particularly revolutionary, but you can see how even such a simple idea can greatly benefit from the freedom to save files anywhere now. If you’re using a text editor or note-taking app that is compatible with Files, you can use this shortcut to create quick “scratchpad” notes and save them into the app’s database in Files directly a widget on the Home Screen. Or you could use this to save clippings into ‘shelf apps’ such as Yoink or Anybuffer. As long as an app comes with a file provider that supports the modern Files framework, this shortcut will let you pick a folder from that provider and use it. I’ve added an import question to select a folder upon installing the shortcut, so once it’s set, you can forget about it completely.
You can get the shortcut here.
During the week of WWDC back in June, I started watching session videos to learn about the new APIs and frameworks in this year’s OS updates. As I watched videos, I saved screenshots for relevant slides in an ‘Assets’ sub-folder of my Obsidian vault, which I store locally on my iPhone and iPad. Later, I realized I wanted a quick way to see those screenshots again, so I built a shortcut to speed up the process.
You can now preview files from any folder.
This shortcut takes advantage of the Get Contents of Folder action to fetch all files from a folder and present them with a Choose from List action. Screenshots from the folder are sorted by creation date with the latest images displayed at the top thanks to a Filter Files action that sits in between Get Contents of Folder and Choose from List. At the end of the shortcut, the image I pick from the list is copied to the system clipboard so I can paste it in other apps.
As I described above, because I store my Obsidian vault locally and let it sync across devices with the Obsidian Sync service, I had to work around the limitations of the Shortcuts app with a conditional block that accesses the same folder twice. Regardless of whether I’m running the shortcut on iPhone or iPad, the contents of the folder are saved into a named ‘Files’ variable, which is then connected to Filter Files. If you don’t need to work with local storage, you can remove the conditional block entirely and simply run Get Contents of Folder once for the folder you want to access.
You can get the shortcut here.
This shortcut is also based on the Get Contents of Folder action, but it uses it for something different that should be familiar to Mac users: cleaning up the Downloads folder by removing old downloaded files.
As we’ve seen above, each file fetched via Shortcuts contains properties such as name, size, and date. By leveraging Shortcuts’ support for date calculations and the Creation Date property of files, I was able to assemble a shortcut that checks your Downloads folder for files older than four weeks and deletes each one, leaving only more recent downloads in the folder.
You can run this shortcut manually, but I think it’s best used as an automation that runs on a schedule. Here’s how it works: at the beginning of the shortcut, we can define a start date that acts as a threshold to determine what constitutes an “old” file. By default, I set it to four weeks, but you can change it to any value you prefer. The time threshold is calculated using the Adjust Date action, which subtracts four weeks from the Current Date magic variable. If you run this today, the start date will be four weeks ago – i.e. August 9, 2021.
Deleting old files with Shortcuts.
Then, the shortcut uses the Get Contents of Folder action to read all the files contained in the Downloads folder of iCloud Drive. Again, you can change this to any other folder you want to clean up on your device.
Here’s where the magic happens: using a Repeat with Each block, we can start iterating over every file contained in the folder and compare its Creation Date property against the Adjusted Date we set at the beginning of the shortcut. This can be done with an If block set to ‘Date is before Date’. If the condition is met (meaning, the file’s creation date is older than four weeks ago), the shortcut uses the Delete Files action to immediately delete the file; otherwise, it leaves the file alone and continues the loop with the next file.
Comparing dates for files.
The first time you run this shortcut, you’ll be asked to give Shortcuts permission to delete files; do it once, and you won’t be asked to confirm file deletion again, so the shortcut will always delete files immediately the next time it runs.
There’s another nice touch in the shortcut worth noting: the final count of deleted files that is displayed with an alert at the end. To create this numeric value, I added a ‘Number’ action at the beginning of the shortcut, set its value to 0, and saved it as a named ‘Count’ variable. Then, after each repetition of the Delete Files action, the shortcut uses a Calculate action to add ‘1’ to the variable, which is re-saved with the same ‘Count’ name and an updated value. I talked about this technique I call Variable Reset here before (thanks Calliope for letting me find this so easily!), and it’s a useful one to keep handy whenever you want to count successful repetitions of something in a shortcut. In this case, the variable is used to tell you how many files were deleted so you can get a nice confirmation at the end of the shortcut.
I’ve run similar Hazel scripts on my Mac for years, and it’s nice that I can now clean up my Downloads folder on iPhone and iPad using Shortcuts.
You can get the shortcut here.
I also use this shortcut with my Obsidian vault, but its underlying structure can be applied to work with any app that stores documents in Files and supports opening them by name via a URL scheme.
With this shortcut, which I use several times a day, I can search a folder for files matching a specific filename, choose from a list of results, and quickly open the file in Obsidian. Effectively, this shortcut brings Files search to the Home Screen, allowing me to look for any document in a specific folder of the Files app directly from a widget pinned to the first page of my iPhone and iPad.
Searching a folder from the Home Screen.
At this point, you should be pretty familiar with all the techniques and concepts I implemented in this shortcut: the entire contents of a specific folder are fetched by Shortcuts via the Get Contents of Folder action, which is then set to a variable; the folder is accessed independently on iPhone and iPad so it can work for people who rely on local storage; results from the folder are sorted using a Filter Files action. There are still some details I want to point out though.
In the Filter Files action, besides sorting by last modified date, we’re also filtering folder contents based on keywords typed in an Ask for Input action at the beginning of the shortcut. This is the filename you’re looking for, and you can filter files matching that query using the ‘Name contains’ option in the Filter Files action.
Filtering the contents of a folder to sort found files.
Unfortunately, this filter is case-sensitive and there’s no way to turn it off; this means that if a file is called ‘Random Thoughts’, you’ll have to type ‘Random’ and not ‘random’ in order for the shortcut to find the file. I’d like Apple to improve this aspect of Files search and filtering.
I also added a count-checking routine to this shortcut to ensure users have a nice experience when it comes to the number of search results they get. If Shortcuts finds multiple documents matching your search query, it makes sense to let users pick them with a Choose from List action; however, if only one document is found, users shouldn’t have to manually select one item from a list – it should be auto-selected. This is something I do for all my shortcuts, which I suggest you learn and add to your shortcut-building repertoire:
Do you see where the fallacy is in the routine above though?
If the result isn’t 1, it doesn’t necessarily mean that it’s always greater than 1: it could also be 0, meaning no files were found, which also means the Choose from List action would return an error. To avoid this common pitfall, enclose all of this into an outer If block that says “If Files has any value”; if you do this, you can then rest assured that the output of the Count action will always be either 1 or greater than 1, and you can put a nice error message at the end of the shortcut in the final Otherwise block to throw an error and tell the user that no matches were found.
The flow I just explained, visualed in Shortcuts.
The final portion of the shortcut has been optimized for Obsidian users, but you can replace the actions I used with any other app that supports reopening specific documents by name. Specifically, the shortcut uses the obsidian://open? URL command to open the file returned by search and chosen by the user as a new pane in the app. If you don’t use Obsidian, just replace the actions I marked up in the shortcut with other actions or a different URL scheme to reopen the found file in another app. Alternatively, you could even use a Quick Look action to preview the found file on the Home Screen (and share it too using the Share button) without opening it in any app at all.
I’ve prepared two versions of this shortcut you can download: the first version is optimized for local storage and lets you configure separate folders for iPhone and iPad; the other works with a single folder you can pick in iCloud Drive or any other file provider on your devices. You can download either version below.
That concludes our first lesson of the Automation Academy for Club MacStories members, but this is also where you come in.
If you’ve been playing around with the new Files actions for iOS and iPadOS 15, and if you’ve studied this lesson, I would love to see the shortcuts and automations you’ve put together to simplify and speed up file management on your devices.
Here’s my assignment for those interested in participating: build a shortcut that takes advantage of Shortcuts’ new Files actions, share it in the #automation-academy channel on our Discord server, and explain the techniques you’ve used and why.
Shortcuts don’t have to be complex to be useful, but I’d like to see interesting explanations of the problems you’ve tried to solve for file management. Not only will be this a useful exercise to familiarize yourself with Shortcuts and Files, but we may also feature the best shortcuts in future issues of MacStories Weekly (with your permission) for other members to enjoy and learn from you.
Thank you all for following along to this first lesson of the Automation Academy. I hope you’ve been able to learn something useful here, and I look forward to playing around with all the shortcuts you’ll be putting together in the Discord. I’ll see you next month for a brand new lesson of the Automation Academy.
Buona automazione!
-"Automation Academy: Diving Deeper into Shortcuts' Files Actions for iOS and iPadOS 15"