I. Tutorial x-Callback: The secrete of productivity

We all want to work more productive in order to get more time for the really important things in life.

Personally, I think that time management and efficiency improvements have their limits and if not that the human has as he needs to sleep at some point.

Having said that, today I will show a secrete of productivity and how to improve your workflow.by automating tasks.

My secrete calls x-callback function and can be used for most apps using your MAC or IOS. You will be able to get rid of recurring tasks and do them automatically. Do not jump any more from one to the other app or go back and forth to the main screen.

As my readers told me they like to see more tutorials and step-by-step guidance and therefore this will be a series now of three articles.

What is x-Callback

This function is not new or a state-of-the-art newly devised program. It is used in programming in Java, Python, C, C++ quite a long time. It will give arguments to another function and this function can return some result.

A bit new is the possibility to use it externally without having it surrounded by code.

Developers of apps and software have opened a little „door“ to their apps and programs so that they can receive and send some information.

X-Callback can be used bi-directional and therefore it is pretty mighty and saves you thousands of clicks and therefore time. With this function your workflow can be enhanced - especially under IOS - and brings you more choice how to use your apps and increase your productivity.

The really cool thing is that you do not need a special program or apps to devise your x-Callback but a simple text editor will be sufficient. The code can be executed in any browser - that’s they there is the suffix „URL“ in this name.

Your browser will ask once you are executing the x-Callback if the app or program should be opened:

Further to this you can use x-Callback in any other link emails or wherever you like.

Unfortunately, I could not find the meaning of the „X“ in x-callback. Probably it will stand for „execute“.

Do you know more - then please let us know!

For what can use it now?

It depends on two things:

  • how far open the „door“ in the app is

  • your own needs.

More and more apps get this function now and it is helpful especially under IOS. Because it saves you clicks, time and it is easy to use.

This nerve-racking jumping around between the apps is something from the past. Now you can use x-Callback to work without disruptions or having to go to the home screen over and over.

Here come some example what you can do with x-callback:


  1. Show your calendar and let the next appointments show

  2. Create emails automatically and let them send

  3. Search for data in a database and return the result

  4. Create screenshots, PDF, Pages and much more.

Nice! But the function can also be used to retrieve something and send it back to the original app which called for that action. This is the point it gets interesting….


A small scenario for IOS or MAC:

I write in Ulysses an article and surf in the Internet for additional data and references to be used. I can do that really easily with the split-screen under IOS.

Usually, I would take the reference URL and paste into Ulysses.

But what happens I want to include a document from DTTG into Ulysses and link it as a reference point?

Well, the first option is to get DTTG on the right side of your screen and leave your browser; the second option would be to go to your home screen in order to open DTTG.

Would not it be much nicer to start from Ulysses and a search box will appear asking what to find - show results - after selection use this document reference into my text immediately? Without opening and scrolling to DTTG or going back to the main screen.

That would be cool would not it?

If DTTG is used as my document management system then everything should be there ready for referencing in any app or document. I prefer to have everything on one place - do you?

Later I want to take some screen shoots for a tutorial without leaving Ulysses at all.

After a couple of hours I am working in Numbers and crunching some numbers in the correct order. Then, I remember I wanted to include this into my tutorial. - Could I just send to the correct sheet in Ulysses? Yes, I can!

Multiple - Way - Function:

Another scenario could be:

I take scan some documents using my Ipad which I would need for a later appointment.

With x-Callback I can do that in one go:

  1. Take photo of document

  2. Render it and rename it

  3. Send it to DTTG or directly to my calendar as PDF

  4. IF send to DTTG:

  5. Take the link from DTTG which are sync’ed across my devices

  6. Send it to my calendar for my specific appointment xyz.

All three examples are possible with x-Callback and much more, without having to open each single app separately.

Use your time for something nicer and automate tasks with x-Callback. You can use it as bookmarks in your browser and execute them directly from there or use Workflow.is as hub of all your code. The nice thing of Workflow.is is that you can use the functions as Widget or in a share menu.

Therefore the usage of x-Callback has only two limits:

  • The app itself and the „open doors“ and

  • What you like to do and your ideas!


The function starts mostly with:

x-AppName://Command:?What to do

For DTTG for instance it is: x-devonthink:// .

There is one distinct disadvantage and which is that there is no unique way for all the functions and commands. It depends on the developer how he wants to call it and how it should be executed.

A lot the following structure is used:

  • x-source
    Where should the command be executed

  • x-success
    Which result should be shown and used if the command is successful?

  • x- error
    What happens on an err?

  • x-Cancel
    How will the procedure be stopped?

But this is not always the case, that this structure is used.

Also the structure of data is different from app to app depending for what the app is actually used for. For instance is a „new file“ in:

  • DTTG:
    New file - which? Text, images, audio, video?

  • Ulysses:
    New group or new sheet?

  • ByWord
    Creates a new file

  • 1Writer:
    Used „create“ not „new“

  • 2Do:
    Uses „addNewTask“.

  • Working Copy
    Is it write or read?

It really depends on the app and program for what it is used, hence the commands will depend on this too as well as the full structure.

Most developers have a cheat sheet for their x-Callback function like a „building plan“ available. It will show the structure (syntax) and how the function is used.


It is important to know:

  • What you like to do

  • Which apps should interact with each other

  • What is your standard workflow?

For the latter I mean: Can you standardise something or do you use an additional user interaction? It is possible to create user interactions with x-Callback too and use them as variables for the later function.

As you can see there are endless possibilities under IOS and MAC but where can you store all that code later?

I use Workflow.is which you can download from the App Store for free. Actually, I use it quite a long time and had to pay for the app :-(

This app will give you a great choice of possible scenarios and it can store and execute x-Callback.

A further advantage of Workflow.is is, that you can use the ready-to-go code in widgets or with the share menu. This is really useful under IOS as you can just tab on your x-callback and it will execute it from everywhere.

For all the other needs I use x-callback in Workflow.is and generate my data from there. There is also LaunchPad and others but I do really like Workflow.is as it is the only one which I am satisfied with.

„Knitting“ you code

It is the same: To knit something goes usually by a pattern or some instruction and the same is true for code. The code instructions depending on the developer and which functions (commands) are available.

Steffi's Cloud

First thing first -> Start knitting the first expression:

x-devonthink:// for DTTG or DevonThinkProOffice.

Next up the line the command:


The question mark acts like a kind of divider.

The file should have a title too - the third knit: „My first test“

x-devonthink://createtext?title=My first test.

Lastly, there should be something in the text - here „My first text with DTTG and x-Callback“:

x-devonthink://createtext?title=My first test&text=My first test with DTTG and x-Callback

If you use this string in a browser (copy and paste), you will be asked if you really like to execute it and open the specific app or program. If you agree, you will see the DTPO or DTTG file structure and asked where to save it. Once done, you have a new file called „My first test“ with the content of „My first text with DTTG and x-Callback“

This code string will work under IOS and MAC and does need to adjusted for the separate operating system.

If you imagine now that both title and body will be used as variable which you have to enter first and they get executed with the code.

What can you do else with it?

You will be able to create text or html with different title and content in DTTG or DTPO. - It’s not magic!

But how boring would it be if there would not be more to do with x-Callback:


  • Clips

  • Bookmarks

  • Documents

  • Groups

  • Images

  • Markdown documents

  • Web archives

  • Import clipboard AND

Some commands for:

  • Which database to be saved

  • which location within the database to be saved or searched

  • Add some comments and much more.

Call back results from:

  • Searches in specific databases and/or locations or

  • Search in the full or use NEAR

  • Copy links to documents and send them to other Apps and much more.

It is really worth to use the x-Callback function especially under IOS.

An advanced function, sent by Els, on of my readers, is to add an email from AirMail to DTPO using HTML. Thank you Els for this reference!

Here is the code:


Important: Before you execute anything

It is important to note, you are handling with CODE and it is executable!

A wrong configured URL can possibly:

  • Delete what you do not want

  • Change data which are not considered to be changed

  • Crash of app in worst cases.

It makes sense to:

  • Knit the app step-by-step
    for instance you should just try to call up the app.
    After this you can try to create a text file and so on

  • Test environment
    A good idea is to have a test environment for programming code.One possible variant is for DevonThinkProOffice for instance to create a new database „test“ with some structure and in 2Do use a new list or a new account for testing.

  • Once you are satisfied within your test environment
    You can release your code to the productive stage and work with it in you workflow.

One Code - Several users

Code will not work everywhere except you make some assumptions or changes within.

If there are two user A and B and both have their own copy of DTPO and DTTG with a database and a folder therein called „Test“ the issue will already come up:

If you like to save a PDF file now from a website to the test folder it will not work with the same code.

Why not?

DevonThinkProOffice uses not the name of databases, folders or documents but an unique ID - aka UUID. This UUID is essential to identify the correct folder in the correct database and it might be different between user A and B.

Therefore, you would need to change this UUID in the code of x-callback in order to get a result.

This is not true, if both users synchronise DTPO and DTTG with the same Sync-Store. Only then the UUIDs are equal between user A and B as well as IOS and MAC.

Attention when sharing your code with others

This is true for all programming languages and codes and you need to do assumption for the usage of your code. The hardest thing to „overcome“ calls „Human behaviour or non-behaviour“ :-)

Of course will be possible to have user inputs for :

  • Name and Notes

  • Text within the file

  • Date and Time

  • Setting or priorities an so on.

After this input, variables can be created from this and used in x-Callback-URL.

That works fine as long as the user knows what and how to enter information and data. One example is the date for today: Tuesday, 09 May 2017:

  • 20170509

  • 2017-05-09

  • Tue, 09. May 2017

  • Tue, 09.05.17 and so on.

A query needs a specific format and different users would enter in different ways the information. That can incur errors or breaking either the apps and or x-Callback-URL as the source app does not know what to do with wrong information.

Mitigate and eliminate faulty codes

To mitigate or eliminate such error you could:

  • Input only Text or select given text
    Tomorrow, Today, in four days etcetera would make sense for selection from a list.The input can be calculated in days from now and put in the correct format.

  • Input using other apps within
    Of course it would be possible to show a calendar and let the user select date and time.

  • Fix data
    You could also fix the time altogether. For instance 11 am in the correct format of 11:00).

  • Documentation and Display errors
    Another possibility is to tell the user upfront with a documentation or display how to enter the data correctly.Will he do it then right?You can only test it with an function in the function if the input is correct or not and display a message how to enter the correct format and try again if the first input was wrong.

There are loads of things around which depending on the actual user and therefore you should be careful before sharing your code.

Do you want x-Callback URL only for you - then you do not need to do a documentation or display as you know how to use it.

But what is in one month or one year? Can you still recall?

I always recommend to do a little documentation for any code - which can be placed directly into the code as comment or so. If you cannot recall you can use the comments to refresh your memory.

Your workflow - your choices

You will have loads of more choices and possibilities to create or amend you workflow as you can see from my tiny examples.

if I tell you now that:

  • AirMail

  • 2Do

  • Ulysses

  • BusyCal

  • Workflow.is and many more apps and software

can use x-Callback then you could just imagine how powerful it will be and how you could improve your productivity to a new higher level. Also, your workflow will not be the same any more, once you know how to use it.

For all above mentioned apps I have a download available for you in RTF-Format. There are only simple example of x-callback but take a look into this:

[sdm-download id="5197" fancy="0" button_text="Examples for x-callback-URL"]
Do you like more and do not want to wait until the next tutorial? Then there are two nice websites which I can recommend as a starting point:

MacStories and Tutorial and Example.

The website of the last links was written by Agil Tortoise. You do not know them? Sure, you do: There are the developers of Drafts, Terminology, Interact, Interact Scratchpad, Tally, Diced for IOS!

My next tutorial will be about certain apps and programs and how to „knit“ the code for them.

Do you have a favourite which you like to see first? Then just let me know using the comment below.




    Comments 1