UPDATE: I finished writing this tutorial literally the same day that the wonderful app Workflow was released. Whilst Workflow doesn’t entirely obsolete the techniques describe below, it does make it exceedingly easy to achieve large swaths of the things that previously required x-callback-url, and more besides, all wrapped up in a package that is far easier for the novice automator to get to grips with.
After a sulky tweet or two, I’ve decided to publish it anyway, partly because — as of right now — x-callback-url still has a few tricks up its sleeve Workflow can’t replicate[1], (and indeed, Workflow itself supports x-callback-url for just this reason), but mostly just because HUBRIS won’t allow me to throw it away. However, if you’re just dipping your toe into the EFFERVESCENT water of iOS Automation, then I’d urge you to try out Workflow first, and to come back here AFTER you’ve discovered you need x-callback-url for something and want to learn how it works.
Launch Center Pro — “Like speed dial for everyday tasks” — and Drafts — “a different kind of note taking app”— are two of my favourite iPhone apps. Each incredibly powerful, they team up like VOLTRON to create a giant anime robot when used together,[2] making short work of complex tasks, and adding new levels of POWER to the previously svelte, simple experience offered by iOS. Without them my iPhone would be a sadder creature indeed.
It’s easy to see the appeal of Drafts: it lets you write short notes fast, and then do things with them. I think Launch Center Pro is a slightly harder sell. When you read what other people do with it, it looks cool, but because the things you can do with it are so specific and personal, it’s tricky to figure out what you might want to use it for. Luckily for me, my job is not to SELL Launch Center Pro to you. It’s merely to TEACH you how to get the most from it.
In today’s Super Simple Guide I am going to:
I like to watch movies. Sometimes I think of a movie I want to see at some point in the future. Sometimes I forget about these movies and thus never get around to watching them. Then I look like a RUBE when I am talking to my friends and they’re all like, “You haven’t seen Pulp Fiction?! How is that even possible in 2007? Am I really going to have to hire out a cinema and put on a screening just for you?”[3]
I kept a list of movies in the excellent note-taking app SimpleNote.
Admittedly, yes, this totally worked. But it was a bit of a pain finding the note that contained the list by scrolling down the list or typing in a search term.[4] And once I found it I still had to open the note, scroll to the bottom, and make sure the text-entry caret was in the correct place using iOS’s PAINFUL caret-placing mechanism, before I could actually start typing in the name of the film I want to watch. Excruciating.
I now have a much ZIPPIER set of steps: Tap, tap, type!
That is, first I tap on the Launch Center Pro app, then I tap on the “Film to Watch” icon, then I type in the name of the movie. Fast! Easy!
But how does it work?
I am possibly the only geek that was slightly disappointed when Apple announced they would be improving inter-app communication in iOS with “Extensions”. Most users and tech commentators were excited about how Extensions would allow app developers to create lots of great new features, but I was sad because by introducing them, Apple effectively hamstrung the existing methods that could be used to use apps in combination.
In particular, something called x-callback-url allowed savvy users to create complex chains of actions by simply typing stuff into an app. Which was great, because it didn’t require any input from developers. Instead, the users of iOS could extend its functionality.
In short, the new Extensions are more powerful, but, with Launch Center Pro and Drafts, the old method is more user-customizable.
But now that Extensions exist, app developers are far less likely to continue to add support for x-callback-url to their apps, and this is sad, because as we shall see, x-callback-url is SUPER NIFTY.
So in ye olde iOS 7, one incredibly LIMITED way that an app could talk to another app was via a URL Scheme. These allow an iOS app to declare, “Hey! Here’s a new type of URL! Please refer all requests about URLs like this to me!” So, for example, if you’re an iPhone app for donkey enthusiasts called Donkey Fancier, you might declare a new URL scheme donkeyfancier. Then other apps could tell you to open by visiting the URL: donkeyfancier:. HEE-HAW!
In and of themselves, URL Schemes weren’t particularly powerful. As a method of inter-app communication they could be described not-inaccurately as WEAKSAUCE. All they really allowed you do to was open one app from another app, and maybe pass along a bit of information, so, for example, a reading app could open up a dictionary app and automatically display the definition for a particular word.
However, the developer of the app Drafts, Greg Pierce, realised that if everyone agreed to set up their URL Schemes to work in similar ways, then apps could instruct their app PALS to perform more complex actions. For example Instapaper could tell Terminology to not only display the definition for a word, but ALSO to display a button allowing the user to quickly ZOOM back to Instapaper once they were done with their LEXICOLOGY.
He called this system x-callback-url. url: because it uses URLs. callback: because it allows apps to “call back” to other apps after they complete an action. x: because using it feels EXACTLY like executing a Double McTwist 1260 (Tomahawk).
Pierce also realised that, with these URL schemes in place, you could allow users of iOS to type in URLs directly, thus allowing them to create their own sequences of actions, without requiring the developers to think of and implement them in advance.
This was a game-changer.
We’re going to replace the note in SimpleNote with a plain text file in Dropbox, and we’re going to add a button in Launch Center Pro that can be tapped to INSTANTANEOUSLY add a new film to the bottom of this list.
Launch Center Pro actually already includes an action for appending a line to the end of a Dropbox file, so you’d think that we could just use that and goodness gracious that was a lot of build up for an incredibly anticlimactic finish.
However, PITFALL! Launch Center Pro’s Dropbox action doesn’t work offline. So when I meet up with one of my fixie-riding friends in a dingy underground gin bar and they recommend I watch The Station Agent, then goddammit I’m going to wish I never deleted SimpleNote off my phone!
This is where Drafts comes to the rescue! It has its own Dropbox action! But, uh, the Drafts Dropbox action also doesn’t work offline. Oh no the lifeboat has capsized and its crew can’t even swim!
But all is not lost. We’re going to hack around the thorny problem of ropy reception by using Launch Center Pro to tell Drafts to add a film to the list IF we’re online, and otherwise to add an item to our todo list app, the indispensable Things, reminding us to add it next time we have a ROBUST internet connection. Drafts will remember the film for us so we can easily retry the Dropbox action the next time WEBSURF’S UP!
Let’s get cracking:
We’re going to create three actions in Drafts. One to save the film to Dropbox, one to save the film to Things when we’re offline, and a THIRD to chain the first two together.
First we’re going to create a Dropbox action to add the name of the film into a file in Dropbox. Fire up Drafts, and pull open the actions drawer on the right, tap on the + button, and select Create Action to create a new action.
Give it the name Film To Dropbox and tap on the 0 steps row followed by the + button to add a new step. Find the Dropbox service in the list, and then fill in the options thusly:
filmstxt/- [[draft]] (added [[created]])Tap here to import the Film to Dropbox action into Drafts
Tap Save to finish adding the Dropbox step, and then tap < Action to return to the Action itself. Scroll to the Advanced section at the bottom, and change the value of After Success to Archive.[7] Tap Done to finish adding the action.
When the action is initiated on a draft, Drafts will replace the [[drafts]] tag in the Content with the contents of the draft (i.e. the name of the film) and the [[created]] tag with the date that the draft was created.[8] The action will then add this Content line to the bottom of the file films.txt in the top-level of your Dropbox folder. It will then archive the draft, removing it from the Drafts Inbox.
Pretty simple, huh?
Next we’re going to create an action to save the film in Things in the event that the Dropbox action fails (e.g. if we have no internet access). Tap the + button again, and just like before, select Create Action.
Give this one the name FilmToThings. See how there are no spaces in the name? That’s important, and we’ll see why later. Next, instead of adding a “Dropbox” step, add a “URL” step.
Fill in the URL Template with the following URL:
things:add?title={{Film to Watch}}¬es=[[draft]]Tap here to import the FilmToThings action into Drafts
This is fairly simple, too. Let’s break it down like James Brown. We know that there are three sections to a URL:
things: – Remember this? Yes! It’s a URL Scheme. This scheme tells your iPhone to invoke the Things app,add – This tell Things that we want to add a new todo item,?title={{Film to Watch}}¬es=[[draft]] – The third section of this URL contains two parameters, separated by an ampersand:
title={{Film to Watch}} – The first parameter, title, is set to {{Film to Watch}} — the {{double curly brackets}} around the action name tell Drafts to URL encode the title of the todo item so that it is safe to use in a URL,
notes=[[draft]] – The second parameter, notes, is set to [[draft]] — Drafts will replace [[draft]] with the content of the draft: this is just to give us a reminder of what film we need to add. This part isn’t STRICTLY necessary, because Drafts will already remember the name of the film, but it’s nice to have.
Once you’re done adding the URL step, make sure that After Success for the action is set to Do Nothing. We want the draft to stick around so we can try adding it to Dropbox again later.
Now we need to glue the two together with an action that will first attempt to fire off the Dropbox action, and then save the film to Things if the Dropbox action fails. Create a new action named Film to Watch, and add a URL step with the URL,
x-drafts4://x-callback-url/open?uuid=[[uuid]]&key=MYKEY&action={{Film to Dropbox}}&x-success={{launch://}}&x-error={{x-drafts4://x-callback-url/open?uuid=[[uuid]]&key=MYKEY&action=FilmToThings}}
N.B. Type it all on one line; Don’t tap the return key while entering it.
Tap here to import the Film to Watch action into Drafts
Now we are finally starting to HARNESS the POWER of x-callback-url. Let’s see how this works by breaking it down like before:
x-drafts4:// – It’s another URL Scheme! This one is the URL Scheme for Drafts itself. Drafts is going to tell itself to do something. Yes, it is like a cut-price geeky version of Inception up in here. Like the web addresses we looked at earlier, and UNLIKE the things: URL Scheme above, the x-drafts4:// URL scheme follows the colon with two forward slashes,
x-callback-url/open – We want to use Drafts’s x-callback-url support to open an existing draft.
?uuid=[[uuid]]&key=MYKEY&action={{Film to Dropbox}}&x-success={{launch://}}&x-error={{x-drafts4://x-callback-url/open?uuid=[[uuid]]&key=MYKEY&action=FilmToThings}} – This time there are 5 parameters, again, separated by ampersands:
uuid=[[uuid]] – UUID stands for Universally Unique IDentifier, and it just tells Drafts which draft to open. In this case, we get Drafts to open the same draft that we’re running this action with, by getting Drafts to fill in the UUID itself with the [[uuid]] tag.
key=MYKEY – Allowing any app to fire off actions in Drafts is a bit of a security hole. In order to prevent a malicious app posting all of your drafts to Twitter or other such NEFARIOUS activities, Drafts allows you to set a key, and will only carry out actions if the calling app uses the correct key. I have set my key to MYKEY. You will want to set yours to something different. In fact, by default, Drafts does not allow you to fire off actions via URL Schemes at all. In order to allow this, you will also have to turn on Allow URLs to trigger actions in the URL Security section of Drafts’s settings.
action={{Film to Dropbox}} – We want to perform the Film to Dropbox action we created earlier,
x-success={{launch://}} – This is where x-callback-url gets clever (and a bit more complicated). We can tell Drafts that after it performs the action, we want it to do different things depending on whether the action was carried out successfully or not. How do we tell Drafts what to do? With another URL! We’re burrowing down the levels like Leonardo DiCaprio. The x-success parameter tells Drafts what to do if the Film to Dropbox action succeeds in adding the film to Dropbox. And what do we want it to do? {{launch://}} – It’s an URL within an URL! Shakespeare would be proud.
The launch:// URL scheme is for Launch Center Pro, and we’re not giving it any further information: we just want Launch Center Pro to open again after the action completes, in case we want to quickly add a number of films to the list. We’re wrapping the entire URL in {{double curly brackets}} in order to URL encode the colon and slashes.
x-error={{x-drafts4://x-callback-url/open?uuid=[[uuid]]&key=MYKEY&action=FilmToThings}} – But what if there is no internet connection and Drafts can’t save the file to Dropbox? NO WORRIES! We can also tell Drafts what to do if an action fails with the x-error parameter, which we have set to: {{x-drafts4://x-callback-url/open?uuid=[[uuid]]&key=MYKEY&action=FilmToThings}} Yes! It’s another URL! (Again wrapped in {{double curly brackets}}.) Let’s break this one down, too:
x-drafts4:// – We want to ask Drafts…
x-callback-url/open – to open…
?uuid=[[uuid]]&key=MYKEY&action=FilmToThings – the same draft again, using the same key, but this time carrying out the FilmToThings action. And now we finally see why we had to omit the spaces from the name of the FilmToThings action. The entire URL is already wrapped in {{double curly brackets}}, and because this is not RUSSIA, and because curly brackets are not DOLLS, we can’t use another set to automatically URL encode the FilmToThings name.[9] It’s easier, therefore, to use a name that doesn’t need to be URL encoded, and a name that contains no spaces is an easy way to achieve this.
Phew. That was a bit more complicated, but the good news is, we’re done creating Drafts actions! Just make sure your new Film to Watch action has After Success set to Do Nothing, and finally tap on Done to save it.
Finally, we’re going to create a Launch Center action to kick off the whole thing. Open Launch Center Pro, tap on the pencil icon and then on an empty action slot to create a new action. Give it any name you like, and fill in the URL like so:
x-drafts4://x-callback-url/create?text=[prompt:Film Title]&action={{Film to Watch}}&key=MYKEY
N.B. Again, the whole URL is on one line; fingers off that return key!
Tap here to import this action into Launch Center Pro
You should be able to figure the structure of this URL out for yourself. There’s only one new part here, and that’s the value of the text parameter, which contains the [prompt:Film Title] tag. This tells Launch Center Pro that when the user initiates the action, it should prompt them to type in the Film Title.
Tap on your new Launch Center Pro action and type in the name of a film, and then watch the SPARKS fly. With a bit of luck, you set everything up correctly, and the film will be added to a file in your Dropbox folder. If not, double-check that all the actions are configured as described above. Everything has to be 100% correct in order for it to work. If it’s still not working, then it might help to activate the actions manually from within Drafts — this can help you track down the culprit.
Once you’re happy that it’s working online, try turning on Airplane Mode and adding another film. See how a todo list item is added to Things? Then you can turn Airplane Mode off again, and go back into Drafts to fire off the Film to Dropbox action manually. WUNDERBAR!
It is possible to add a URL to the Things todo item that kicks off the Drafts action automatically. This is left as an exercise for the reader.[10]
So now you are an expert in iOS automation using x-callback-url! Doesn’t it make you feel SASSY? If you want to learn a bit more about what SPICY ingredients Launch Center Pro brings to the automation BROTH, then READ ON to try out creating a new action. Alternatively, if you’re all like, “Yeah, I get it.”, then skip forwards to the wrap-up and debrief, below
I used to keep my life organised by storing appointments and important dates in a Google Calendar. Google Calendar plays well with iOS, allowing you to view and add appointments in any calendar app you have installed, but for VARIOUS REASONS[11] I decided I was going to stop using it, and instead use the Unix tool Remind to ensure I never forget my Mum’s birthday.
Remind is a “sophisticated calendar and alarm program.” Being a Unix tool, it’s a bit more… esoteric… than your average calendar app, but it’s also incredibly FLEXIBLE and POWERFUL — it is like the body-building yoga instructor of calendar apps, except it is a yoga instructor who will only speak in riddles. Lovely!
You populate your calendar by filling up a text file with lines like:
REM Oct 25 2014 +14 MSG - %"Finish writing tutorial%" [daysaway()]%This defines a reminder for the date October 25th with the name Finish writing tutorial, that I will be warned about 14 days in advance. My Remind set-up then reads this file, squirts my appointments and birthday reminders into my iPhone calendar,[12] and sends me a daily agenda every morning using the snazzy Pushover app.
Don’t worry about the non-emphasised parts. They’re just how my Remind configuration expects reminders to look, and they’ll be identical in all our reminders. We’ll just need to create an action that fills in the emphasised parts, which change from reminder to reminder.
Okay, so let’s create a set of actions to append new reminders to the end of my Remind file:
We’re going to create three actions in Drafts, much like before.
This is very similar to the Dropbox action we created earlier.
Like before, pull open the actions drawer on the right, tap on the + button, and select Create Action to create a new action.
This time, give it the name Append to Dropbox and fill in the Dropbox service’s options thiswise:
[[line|2]][[line|3]][[line|4]][[line|1]]Like before, set After Success to Archive.
Tap here to import Append to Dropbox action into Drafts
This is slightly different to the Dropbox action we created before. Instead of specifying the name, extension, path, and content of the action explicitly, we’re using Drafts’s [[line|#]] tags to pull single lines out from the draft for these. This allows us to pick the name and location of the target file in Dropbox within the contents of the Draft itself, by creating a draft with four lines, like this one:
Applying the action to a draft with the content above would add the line Flaming drongos! to a file named alf.txt in a folder named home_and_away_quotes in Dropbox’s root folder.
This means that we can re-use this action in multiple places. We’ll see why that’s useful a bit later on.
The other notable difference is that we’re appending the line as-is to the Dropbox file, instead of formatting it here. This is because we’re going to build the reminder with a number of prompts in Launch Center Pro.
We also need to create another Things action. Do so like before, but this time use the name RemindToThings. The URL is very similar to before. In this case, we’re just going to save the first line of the draft in the todo.
things:add?title={{Add Remind Entry}}¬es=[[line|1]]Tap here to import the RemindToThings action into Drafts
You know the drill! Call this action Remind Entry and give it the URL:
x-drafts4://x-callback-url/open?uuid=[[uuid]]&key=MYKEY&action={{Append to Dropbox}}&x-success={{launch://}}&x-error={{x-drafts4://x-callback-url/open?uuid=[[uuid]]&key=MYKEY&action=RemindToThings}}
Tap here to import the Remind Entry action into Drafts
This is almost exactly the same as before, merely swapping in our new remindy actions for the filmy ones from before.
Now, we need something a smidge more complicated here, as we need to build the Remind entry from several prompts, and we need to create a draft with several bits of information on different line.
First, let’s take another look at the format of the Remind entry we want to create.
REM Oct 25 2014 +14 MSG - %"Finish writing tutorial%" [daysaway()]%First we replace the bits that don’t always stay the same with Launch Center prompts. (The [prompt-numberpad] tag works in the same way as the other prompt tags, but displays a keyboard that only contains numbers.):
REM [prompt:Date] +[prompt-numberpad:Advance Notice] MSG - %"[prompt:Title]%" [daysaway()]%
Then we add the filename, extension, and location of the Remind file in Dropbox on the lines below:
Finally, we wrap the whole lot in {{double curly brackets}} to URL encode, and then plug that into the text parameter of our Drafts URL:
N.B. Note that this time you do need to tap on the return key: at the positions marked with a ⏎ symbol i.e. after [daysaway()]%, calendar, and rem (but no-where else!), so that the draft that is created is made up of four separate lines.
Tap here to import this action into Launch Center Pro
Job’s a good’un.
For comparison, this is the same URL, but manually URL encoding instead of using the automated {{ }} encoding:
x-drafts4://x-callback-url/create?text=REM%20%5B%5Bprompt%3ADate%5D%5D%20%2B%5B%5Bprompt-numberpad%3AAdvance%20Notice%5D%5D%20MSG%20-%20%25%22%5B%5Bprompt%3ATitle%5D%5D%25%22%20%5Bdaysaway()%5D%25%0Acalendar%0Arem%0A%2Fremind%2F&action=Remind%20Entry&key=MYKEY
Maybe you'll disagree, but I know which one I’d rather write/debug.
Save your new Launch Center Pro action and try it out!
Okay, we’re going to automate one more task!
I also have all my favourite people’s birthdays stored in my a separate Remind file. Adding a new birthday is done with a Remind line like:
REM Dec 25 +3 MSG %"Humphrey's Birthday%" [daysaway()]%Poor Humphrey — I bet he gets HALF as many presents as he DESERVES!
Let’s see how we can add another set of actions to easily add new birthdays to my diary when I make new FRIENDS!
Remember how we set up Append to Dropbox so that you could use it to append lines to different files in Dropbox? Well now our chickens are really coming home to roost! We can re-use that action! No changes required!
Oh-ho! Same here! This game is easy!
And… what’s this… we can use the same master action too? Truly, we are REAPING what we hath sowed! You can go ahead and tap on your Home button to leave Drafts because we are DONE here.
Okay we will need to create a new Launch Center action. But by now you’re a DAB HAND at this, so you will knock this one up in NO TIME:
Tap here to import this action into Launch Center Pro
We just had to make a couple of tweaks to the content of the REM line, and we’re storing the birthdays in a different file, but this was basically the same as before. EASY-PEASY.
So now we can add BIRTHDAYS to our diary, too.
We’ve created some useful gizmos, but we’ve really just SCRATCHED the surface of the TIP of the iceberg. I’m sure by now your mind is BRIMMING with the ENDLESS possibilities that are literally at your fingertips. (Some of which don’t even involve appending things to files in Dropbox!) Check out the Drafts Action Directory or the x-callback-url site for more ideas, or read the comprehensive guides to Drafts and Launch Center Pro on MacStories for a more EXHAUSTIVE review of what’s possible.
My personal toolkit also includes actions for creating a few more types of Remind entry, an action that saves the weight of my DIETING CAT in a file in Dropbox, which is scooped up by launchctl and PLOTTED onto a graph using Python, and a couple of other things besides. These are all tasks for which there exist countless iPhone apps, many of which will admittedly provide a more ROUNDED experience. But mine work exactly how I want them to, are LIGHTNING quick to initiate, and furthermore, because I ROLLED them myself, give me the FRISSON of excitement that comes from telling a computer what to do and then having it do it.[13] If you’re not a computer programmer, maybe you don’t know what I’m referring to. It’s hard to describe, but it looks like this.
x-callback-url and the apps that use it are either a SHINING TESTAMENT to the creativity of iOS’s third-party developers that have concocted such remarkably versatile tools which can be clicked together like LEGO by idiots such as myself to create something MAGICAL. Or they are a DAMNING indictment of the SHABBY support for inter-app communication offered by iOS itself that required such workarounds in order to get anything done. (In versions prior to 8, at least.)
Either way, it’s a great system that lets you skirt around the outside of iOS’s restrictive nature, and I’m glad I got to use it for a while. Give it a try, and maybe you will be too!
Comments? Profuse gratitude? Money? New incredibly useful actions you’ve concocted that you think I need to start using? Send them to me at: …@whileyouweregone.co.uk or @whenyougotback.
In particular, Workflow can't solve any of the examples in this tutorial without resorting to x-callback-url. ↩
A giant, metaphorical, anime robot. ↩
Thanks, Chippy! Turns out Pulp Fiction is a good movie. ↩
SimpleNote makes this slightly easier with its “Pin to Top” feature, as does using Merlin Mann’s nifty ‘q’ trick for jumping quickly to the relevant note, but there’s still FRICTION. Fundamentally, SimpleNote is not optimised for frequent fast additions to specific notes. ↩
The scheme of the URL defines what you will find in the rest of the URL. Most of the schemes that we will deal with will use the double slashes after the colon, but one doesn’t. ↩
Really, this is two sections, but for our purposes we can treat it as one. ↩
It’s also possible to set After Success on the fly when you kick off the action, but we’re doing it here to keep our URLs a bit cleaner. ↩
If you don’t like the way the date is formatted, Drafts gives you a lot more control over this. In my version of this action I actually use the following: [[created|%-d/%-m/%Y %H:%M]]. ↩
Launch Center Pro also uses the {{double curly bracket}} method for automatic URL encoding, and in recent versions of Launch Center Pro the curly brackets CAN be nested. ↩
Oh, all right then, here. It’s actually even possible to bypass Drafts entirely (if you’re willing to forgo the timestamps that are added by Drafts). This results in URLs that are somewhat more complex than appropriate for a Super Simple Guide, and so it really is left as an exercise to the reader. If you plan on having a crack at it, note that the first thing the action will need to do is to store the name of the film in the clipboard with Launch Center Pro’s clipboard action. ↩
The reasons are threefold: 1. Google has a habit of killing off its tools, and after getting caught out I wanted to minimise my risk of getting hit again, 2. You are not the customer, 3. I just got bored and wanted to try out a new toy. What? I didn’t say the reasons were GOOD, just that there were three of them. ↩
Via an iCalendar file which I push up to a web server and subscribe to. ↩
I grew up using a computer where the word processor couldn’t even display bold or italics. Yes, the iPhone is a computer. ↩