The Ulysses URL Scheme and Siri Shortcuts

The Shortcuts app is full of hundreds of native actions with customizable parameters and advanced functionality — these are unique capabilities beyond what’s possible with the Siri Shortcuts developed by third-party apps.

But what preceded Siri Shortcuts entirely was a framework called URL schemes, which were what originally enabled the pre-Shortcuts app Workflow to do advanced iOS automation.

Ulysses’ URL Scheme

When apps define a URL scheme that other apps can use, you can pass information along into that app using a link formatted in a special way.

Just like web links have extra information tagged on the end like ?campaign=social, apps can tell iOS that any time a user clicks on something like Ulysses://add-sheet?text=Hello%20World, it should open Ulysses, which takes the add-sheet and following text, then uses its own functionality to add a new sheet with that text included in the sheet.

On iOS, this methodology physically switches your device from app to app and sends raw text into the app. This can feel both advanced and cumbersome for interacting with your apps. It is inherently clunky as it moves about and insecure since any text can be sent.

But, it still opened the doors to advanced automation since developers could adopt URL schemes for their own apps, and the only thing other apps or their users had to do was find or create that link and open it to share data in a structured and scriptable way.

No app took advantage of that better than Workflow.

Workflows actions as URL schemes

Before Workflow was acquired, turned into Shortcuts, and the team developed more secure Siri Shortcuts APIs, they custom-built a series of actions that took advantage of some well-documented URL schemes.

These Workflow actions gave URL schemes a visual front-end so that users could tap into the URL schemes without the complexity of building their own deep links.

One of these apps was Ulysses. The Workflow team built actions from what was available in the URL scheme at the time, and from there the community could utilize it with other actions in Workflow to automate their libraries as much as possible.

With the transition from Workflow to Shortcuts and the introduction of Siri Shortcuts, Ulysses’ native actions survived and still have the advanced functionality of the Workflow actions — even if they still open the app and don’t run in the background like other Siri Shortcuts.

You can view the complete URL scheme on the Ulysses website, but the benefit of Shortcuts is that this scheme is abstracted away for you. Not all of the features are completely covered as the actions haven’t been updated since Workflow was acquired, but for now many features are covered.

Instead of getting into that, let’s instead explore how the Shortcuts actions tap into the URL scheme so you can easily use Ulysses for more powerful automation.

The Ulysses actions in Shortcuts

For Ulysses, Shortcuts provides six native actions (we’ll get to the Ulysses Siri Shortcuts in a bit):

1. New Ulysses Sheet
2. New Ulysses Group
3. Add to Ulysses Sheet
4. Attach to Ulysses Sheet
5. Get Ulysses Sheet
6. Get Details of Ulysses Sheet
7. Open Ulysses

With these you can (1) create new documents in Ulysses; (2) create new groups for those documents to live in; (3) add text notes; (4) apply keywords, or store images alongside an existing note, add text to the beginning or end of an existing sheet; (5) pull sheets into Shortcuts in a rich format that can be pulled apart with a shortcut; and (6) open into any Ulysses sheet or group that you specify.

New Ulysses Sheet and New Ulysses Group generate new assets for you, and after that step is completed within a shortcut, can also open back into Shortcuts and provide the new unique ID for that sheet or group. After doing that, you can then use that newly-created ID to attach more information to that sheet, append to it later, or use within the Open Ulysses action to get back to that sheet later.

You can also use that ID in the Get Ulysses Sheet action, which will have Shortcuts open into Ulysses, grab the sheet, and come back into Ulysses. Then, you can use Get Detail of Ulysses Sheet and select the Title, Identifier, Contents, Keywords, or Notes to extract from that sheet (unfortunately, you can’t get attached images).

Further, with the Open Ulysses action, you can set your shortcut to open into multiple categories: the All section, your Favorites marked with a star, the Last 7 Days category for recently-used sheets, or any Group identified by name. You can even open into sub-groups by using a structure like /The Sweet Setup/Ideas/.

All together, these actions present a powerful host of capabilities for users of Ulysses and Shortcuts. Most of the functionality within the app is covered, and these are also all scriptable alongside what’s possible in Shortcuts.

Working with your Ulysses sheet in Shortcuts

One powerful tip is in regards to the Get Ulysses Sheet and Get Details of Ulysses Sheet actions. Thanks to the feature of Shortcuts called Magic Variables, any time you’ve retrieved a sheet using Get Ulysses Sheet, you can extract any of the same details directly from the resulting sheet.

Once you use Get Ulysses Sheet, the output of the action is automatically saved as a rich piece of data storing all of the information you can choose from in the Get Details of Ulysses Sheet. When you want to use that sheet later in your shortcut, you can use Get Variable or use the Magic Variable icon inside a text field to pick from the output of previous actions and choose that Ulysses sheet.

With the resulting variable that’s now in your shortcut, you can tap it again to directly extract more information, right from that single action. You’ll get a keyboard popover with new options to choose from, just like as if you were using Get Details of Ulysses Sheet.

From there, you can directly retrieve the Title, Contents, Keywords, Notes, and even the Identifier again. This saves you from using Get Details of Ulysses Sheet repeatedly and manually storing all of that information with a Set Variable action. Instead, Shortcuts can intelligently store and extract that data for you along the way, reducing the need for extra-complicated programming.

Instead, you can use Magic Variables to extract that whole sheet and all the available attached features right from the original Get Ulysses Sheet action or some combination of both the variable and Get Details Of Ulysses Sheet, depending on the specific way some of your actions may accept content as input or using the on-action parameters, like in the Post to WordPress example above.

Limitations of URL scheme actions

Overall, these actions do enable a lot of functionality within Ulysses and the Shortcuts app, but there is a small degree of organization required. If you want to use sheets to extract information, you might need to keep track of the unique IDs somewhere like a Reminders list or text file in iCloud Drive; otherwise, there’s no immediately easy way to find an existing sheet and act on it again later.

For this reason, extensive use of splitting and glueing sheets might not enable a fully-automated system. In those cases, I recommend keeping track of Group IDs where applicable instead of the individual sheet ID, which might be merged with another sheet and no longer available.

This functionality for grabbing sheets using their direct IDs is just limited enough that I don’t often take advantage of it. Some of the effort is too high for the return in the short term.

There are ways to use Shortcuts to script this functionality, but I’ve personally found it too complicated for the level of writing I’m currently engaged in, especially since I hope this gets better with more power in the Siri Shortcuts capabilities in the future.

Ulysses and Siri Shortcuts

Beyond the native actions in the Shortcuts app, Ulysses also takes advantage of some of the Siri Shortcuts API and provided functions that can be triggered with Siri using custom phrases you’ve chosen.

Once you’ve interacted with your Ulysses library and utilized some of your groups, Ulysses can “donate” those recently-used actions you’ve performed to Siri to be used elsewhere. If you go to the Siri & Search section of the iOS Settings app, you can find suggested Siri Shortcuts for your Ulysses groups. Tap one and you can save it with your own phrase, and when you use that phrase, Siri will open that group for you right away.

This works for any sheet or group you’ve added to Ulysses — just make sure to access it first in Ulysses, then open the Siri & Search section of iOS Settings. You might see Ulysses shortcuts in there if you’ve recently used the app, otherwise tap All Shortcuts and find Ulysses for a full list of Siri Shortcuts you can add.

In addition, Ulysses also provides Siri Shortcuts for individual sheets. Add a trigger phrase to these and you can jump right back into that long piece or place you’re referring to regularly.

Ulysses also has a New sheet in [Group] shortcut that shows up once you’ve created a new sheet from within a group in your library. Try navigating to that group, adding a new blank sheet, and checking the Settings app if you want to save that as a shortcut.

Running these can create a blank sheet for you right in the group of your choice, which is great to set up straight from Siri.

Right now these can be a bit redundant with what’s available through the Shortcuts actions and the URL scheme, but those are not controlled by the makers of Ulysses. Since they came from Workflow days, they were custom built.

For now, this is all the Ulysses developers are able to provide. Hopefully, Apple improves the Siri Shortcuts APIs in the future so we can replicate actions like Get Ulysses Sheet without needing sheet IDs or allowing actions to happen entirely in the background without needing to open Ulysses physically on the device.

Siri Shortcuts in your custom shortcuts

For now, your Siri Shortcuts can still be used as standalone actions or alongside the native Ulysses actions in course of your custom shortcuts.

For example, you could have a Morning Routine shortcut that turns on your office lights, plays music, and opens your Ideas list with a new sheet so you can start off the day with a focused writing session.

To set this shortcut up, I did the following:

1. Open the Home app and trigger the Good Morning scene, go into the Ulysses group for Ideas and create a new sheet, and then play My Favorites Mix from the Music app.
2. Next, open Shortcuts, create a new shortcut, and open the Siri Suggestions category. In there, find the actions for each of the apps have “donated” their Siri Shortcut to the system. Find the exact ones you want to use and add them to the shortcut.
3. Once you add those, turn off the Show When Run option in an effort to keep the process as quick as possible. (I don’t want Siri to say much of anything; just do it.)
4. Finally, go into the individual shortcut settings/options menu (the icon that looks like two toggles just under the Done button), and tap Add to Siri to give the shortcut a custom phrase. I chose Morning Routine as suggested from the title of my shortcut.

Now, whenever you want to run this shortcut, you can trigger Siri — using \”Hey Siri\” or the side button on your devices — and speak the phrase, and Siri will run the shortcut, which will trigger the lights, open a new sheet in Ulysses, and play the playlist in the background.

Lots to work with

These Siri Shortcuts and Ulysses custom native actions in Shortcuts present you with tons of options, but overall that’s a good problem if you’re using this app.

The advanced actions available in Ulysses are a huge leap ahead of what else is currently possible with the Shortcuts app compared to many other writing applications, so there’s a lot to experiment with.

It can take some time to mix and match these types of Siri Shortcuts and custom shortcuts together, especially if you’re still building an overall writing workflow.

But defining some of those processes so you can utilize automation as well helps solidify those plans. Some things will settle into place, and you’ll begin to see how Ulysses can extend your writing capabilities even further.