Launching Shortcuts from Timepage and Actions

Launch your Shortcuts from Actions & Timepage

iOS 12 introduced the concept of Siri Shortcuts to iOS, and they’re a great way of easily triggering commonly used tasks within your apps. There is another, even more customizable and powerful side to this coin, and this involves the Shortcuts app.

In this post, I’ll go in-depth into using Timepage and Actions to launch custom Shortcuts via the Shortcuts app. This allows powerful workflows to be triggered right from your actions, events and their notifications.

What is the Shortcuts app?

Shortcuts is Apple’s powerful new scripting app. The app is the evolution of Workflow that was purchased by Apple a year and a half ago. The deeper integration with iOS that’s been enabled by being a part of Apple has allowed the talented Shortcuts team to greatly improve the power of the app and make it more accessible than ever to all iOS users.

The first step in our process today is therefore creating a shortcut in the Shortcuts app.

Here are some example Shortcuts that you can install and by tapping the links below on your iOS device:

  1. Play that song! — searches Apple Music for a particular song and plays it. I add this to the notes of the actions in my “Favourite Tunes” list.
  2. Log Water — asks for a glass size, and then records water consumption in the Health app.
  3. Word of the day — retrieves and presents Merriam-Webster’s “Word of the day”.

Inserting a link into Notes

Once we have our Shortcut, we can now trigger it from Actions and Timepage. We’ll continue this post talking about Actions, but the process is the same in Timepage.

Create an Action Card, tap the newly created action, and then tap “Notes”.

In the notes editor, long press on the cursor — you’ll now see a button called “Insert Shortcut”.

Easily insert your Shortcuts link into the notes field.

Enter the name of the shortcut that you want to launch from your action — you’ll need to enter it exactly, so here’s another shortcut that makes that easy:

Copy Shortcut Title to Clipboard

You’ve entered the title of your shortcut into the pop-up, but you’re now facing a rather unfriendly looking URL — not to worry, you’ll not need to see this URL around the apps too often. Let’s break down what’s going on here.

Firstly, the URL that you’ll be faced with will have all sorts of percent encoded characters — this is to make sure that particular characters can be included in the URL; for example, the space character is encoded to “%20”.

I’ve unencoded the URL below so we can properly deconstruct it and explain the various parts:

[My Shortcut](shortcuts://x-callback-url/run-shortcut?name=My Shortcut&x-source=Timepage&x-success=timepage://&x-cancel=timepage://&x-error=timepage://&input=text&text={“itemTitle”:”{itemTitle}”,”containerTitle”:”{containerTitle}”,”linkTitle”:”{linkTitle}”})

The overall format of the link is wrapped in “markdown”, so that we can display the title without having to show the link itself elsewhere in the app. This particular format of markdown link is as follows: [Link Title](url)

In our example we therefore have a title of “My Shortcut”, followed by the long URL.

The first part of the URL itself opens the Shortcuts app via its “custom URL scheme”, and runs our shortcut:

shortcuts://x-callback-url/run-shortcut?name=My Shortcut

The next part of the URL tells Shortcuts which app the link is coming from, and also how it should return to that app after it has finished doing its thing:

Actions

x-source=Actions&x-success=mskactions://&x-cancel=mskactions://&x-error=mskactions://

Timepage

&x-source=Timepage&x-success=timepage://&x-cancel=timepage://&x-error=timepage://

The final part of the URL is where this gets really powerful. This tells Shortcuts to receive some text from our app, and gives Shortcuts three parameters:

&input=text&text={“itemTitle”:”{itemTitle}”,”containerTitle”:”{containerTitle}”,”linkTitle”:”{linkTitle}”})

You can add your own params here if you want, but the three defaults are in the form of a template, and will automatically be filled with the relevant details by Actions (& Timepage) when you actually launch the link.

  1. itemTitle: This is the title of the action (or event in Timepage).
  2. containerTitle: This is the title of the list that contains the action (or the calendar in Timepage).
  3. linkTitle: This is the title of the link itself. This allows you to provide multiple links to the same shortcut from the same action, and have them behave in different ways e.g. starting & stopping a timer. This is used by the “Play that song!” shortcut to search Apple Music.

By default, if you use the “Insert Shortcut” button in the notes fields of the apps, the “linkTitle” parameter will be the name of the shortcut. To change it, just edit the text between the square brackets at the beginning of the link. You could, for example, have two identical links to the same shortcut, with one titled “Start” and one titled “Stop” — your shortcut can then start & stop a timer based on the “linkTitle” parameter that it receives.

Using the link

Once you’ve got your link in the ‘Notes’ field of your action, you can launch it in a number of ways:

Trigger the link from notifications or via 3D touch.
  1. By tapping it in the Notes field. You can tap the links directly from the Notes field in Actions and Timepage to run the shortcut.
  2. By pressing on the Action Card. Hard press on the action in Actions and you’ll see a menu of all the links available — but these are not just links to Shortcuts. Other links like email addresses and phone numbers will also be exposed here.
  3. From the dynamic buttons in Actions’ rich notifications. Similarly to the 3D Touch method above, your Shortcuts (and other) links will be presented as buttons in your rich notifications. Just expand the notification to see all of the buttons

You can now start tracking time on that job directly from the notification, start your running playlist directly from your run reminder, or log your water consumption directly from your water reminder.

Conclusion

There’s more to come, and we’ll expand on this post in future, but I hope that this demonstrates this powerful new feature in both Timepage and Actions.

We’d love to hear about the ways you’re using Shortcuts with Actions and Timepage, so please let us know in the comments or via Twitter at @moleskinestudio. As usual, please also let us know any issues via our support channels, and/or Feature Requests boards.