Add support for callback URLs to allow external joplin:// URLs

[laurent22]

Should implement the x-callback-url spec: http://x-callback-url.com/specifications/

This spec is for iOS but is used by desktop apps too such as Bear.

Forum post: https://discourse.joplinapp.org/t/are-url-links-on-the-roadmap/599

Example URLs

• Opening a note: joplin://x-callback-url/openNote?id=NOTE_ID
• Getting a note: joplin://x-callback-url/getNote?id=NOTE_ID&x-success=targetApp://x-callback-url/receiveNote
• Creating a note: joplin://x-callback-url/createNote?title=NOTE_TITLE&body=NOTE_BODY
• Opening a notebook: joplin://x-callback-url/openFolder?id=FOLDER_ID

Implementation

To keep things simple all the actions should be performed by the data API. The goal then is to create a translation layer that maps the x-callback-url call to a data API call, and then handle the response.

For example, joplin://x-callback-url/createNote?title=NOTE_TITLE&body=NOTE_BODY would be translated to POST /notes with the title/body as post data.

Security

Security should be considered for destructive actions, for example when creating or deleting a note. In that case, perhaps the API token should be required (and passed to the data API, which will check it).

Non-destructive actions such as opening a note perhaps don't need a token.

Platforms

Ideally both mobile and desktop should be supported eventually, so the implementation should be made in such a way that both platforms can re-use most of the code.

Update 2021-10-16

This was implemented in desktop, so only mobile is needed now.

[arnoldoree]

I've had a look over the development environment specification, and that should be fine.

As far as coding goes, even though I have not used Node.js or TypeScrypt before I am sure I will be able to pick those up promptly.

Are there any design level artefacts available, principally a system architecture document (e.g. UML diagram)?

Withe regard to the x-callback-url functionality. My principal target platform is actually Linux, as all my machines run or Debian. I believe that the equivalent to x-callback in Linux is custom URL protocol handlers [x-scheme-handler]. I would of course look to implement the functionality on all platform Joplin applications, however working on my native platform first will be most straight forward.

I'm not sure what the convention is i.e. whether I should have moved over to the GitHub issue already, so I will copy this message both here and there.

I've outlined a basic programme as follows:

CODE

• A method will need to be coded for constructing the externally accessible (Data API) URL for the target note and copying it to the clipboard
  • This method should be accessible via:
    • UI button press
    • Context menu option
• An openNoteExt() method will need to be coded to finally execute the changing of the active note in the Joplin application to the target note.

EXECUTION FLOW

• The Data API sub-system will need to call the openNoteExt() method upon receiving a request at the endpoint URL
• The openNoteExt() method will need to change the active note in the Joplin application to the target note identified in the request URL, and to bring the Joplin application into focus if it is already open and in the background.

[laurent22]

There's no UML diagram but if something's unclear I can explain. For a start it would indeed make sense to only focus on a way to open a note, which I guess will be the common use case. In that case you can ignore what I wrote about the data API - instead you'll only need to call the openNote command (await CommandService.instance().execute('openNote', 'NOTE_ID'))

A method will need to be coded for constructing the externally accessible (Data API) URL for the target note and copying it to the clipboard

• This method should be accessible via:

  • UI button press
  • Context menu option

I don't understand this part - since it's a callback URL there should be no UI, or am I missing something?

openNoteExt

Small thing, but it should be called "openNote", not "openNoteExt".

[arnoldoree]

There's no UML diagram but if something's unclear I can explain

Sure thanks, will let you know once I get into the code if I need any clarification.

A method will need to be coded for constructing the externally accessible (Data API) URL for the target note and copying it to the clipboard

• This method should be accessible via:

  • UI button press
  • Context menu option

I don't understand this part - since it's a callback URL there should be no UI, or am I missing something?

Sorry I don't think I explained very clearly. What I am referring to here is how the user will be able to generate a URI to open a target note. So for instance if the user wanted to access a specific note from within a LibreOffice Writer document they would:

1. EITHER: Right click the note and click generate external link, OR select the note and click a button to generate an external link
2. The link would then be generated in accordance to the scheme specified, and copied to the user's clipboard
3. The user could then paste this link into a LibreOffice Writer document and effectively have direct access to the note from most all places within the operating system environment.

Where this were combined with an application such as XMind it will give a very simple yet extremely powerful functionality.

openNoteExt

Small thing, but it should be called "openNote", not "openNoteExt".

I see. The reason for the ...Ext was to disambiguate, openNote() could be a method to open a note from within the application, from for instance another note. I have not looked at the internals of the system yet, so I do not know if any transformations would have already been handled by the openNote method.

I would say however also that having two separate methods one for open from within Joplin and one from the OS environment or a remote host will generate greater flexibility going forward, giving options to preform action such as extra security checks. At this stage openNoteExt could simply call openNote and do nothing more.

[arnoldoree]

@laurent22. Can you please expand at a high level on the deeper integrations that you are driving towards with the use of the callback method & Data API? I.e. What is an example of an application & use case that may require retrieving a note from Joplin or directly creating a note within Joplin?

[laurent22]

What I am referring to here is how the user will be able to generate a URI to open a target note. So for instance if the user wanted to access a specific note from within a LibreOffice Writer document they would:

1. EITHER: Right click the note and click generate external link, OR select the note and click a button to generate an external link
2. The link would then be generated in accordance to the scheme specified, and copied to the user's clipboard
3. The user could then paste this link into a LibreOffice Writer document and effectively have direct access to the note from most all places within the operating system environment.

Yes indeed we need this, and I should probably add it to the spec.

Can you please expand at a high level on the deeper integrations that you are driving towards with the use of the callback method & Data API? I.e. What is an example of an application & use case that may require retrieving a note from Joplin or directly creating a note within Joplin?

I just copied the callback example from the x-callback-url. We don't need this for now, I guess as a start just a way to open a note would be enough.

[atdnorth]

Sorry I don't think I explained very clearly. What I am referring to here is how the user will be able to generate a URI to open a target note. So for instance if the user wanted to access a specific note from within a LibreOffice Writer document they would

@arnoldoree If I understand your question correctly - My use case is copying an x-callback-url from a Joplin note into OmniFocus or DevonThink. In this way, I can access the Joplin note easily in my task manager (OmniFocus) or my information repository (DevonThink).

The ideal way (as occurs in most applications) would be to right-click on the note in Joplin, choose "Copy Link" as a selection, and then go into my target application and paste this link into a document. So, for instance, I would paste the Joplin link (with the Joplin note name as the visible text and the x-callback-url as the link) into OmniFocus or DevonThink.

[arnoldoree]

@atdnorth Yes. That's very well put. To my view this is somewhat standard functionality. Moreover I do not necessarily see the need for a call-back URL in implementing the functionality set out in this issue at the basic level.

If we want to take things further, for instance by providing the capability to return an edited version of a given note to the calling application, then we could create a loop in Joplin, allow the user to carry through the edits, and where the user gives say-so the loop could be broken and the editd note passed back in the required format to the calling application, by way way of the callback.

However for the basic implementation of accessing the note via a generated URL, the calling application really does not need to receive any call-back after Joplin has been called with all necessary parameters to identify and load the target resource, and to take focus in the OS.

[atdnorth]

@arnoldoree Yes, this is standard functionality in many office/productivity-styled OSX apps. I think that is why so many people have requested it to be added to Joplin. As such, Joplin allows Markdown links but those only provide functionality within Joplin itself (e.g. intra application links). If you consider an OSX app like "Hook" which allows one to group a series of heterogenous calllback links together (from different applications and even files), it is easy to understand how callblack links can improve productivity.

And just to clarify once again, when clicking the callback link in let's say DevonThink or OmniFocus, the link should simply open the document in Joplin, just as clicking a standard URL link will open the href in the web browser. I personally have never had a use case where there was a need for the calling application to receive a calllback from Joplin. i would be curious if other peoplle had examples of such, but my guess is that most people simply want the basic functionality. Thanks so much for working on this. It will be a valuable feature.

[msbentley]

From the linux perspective, yes, just a way to pass a parameter to Joplin (running or not) to open at a specific note given a URI would be great. Then I can set up a x-scheme-handler so that all joplin:// links, system-wide, open a specific note.

[sirius-fan]

This is an awesome feature. But, I did not find it in the latest release, is it already available ? When will it be released ？

[roman-r-m]

Should be open, was closed by mistake.

[roman-r-m]

@laurent22 there's still mobile to be implemented, shall we keep this open for now?
And also CLI but not sure if it's possible at all to support callback URLs for the CLI app.

[laurent22]

That's true, it could be supported on mobile so let's re-open.

[dpickett]

would it be possible / welcomed to link to a specific resource?

Effectively what I want to do is manage my attachments in joplin and link to them via obsidian. I'd like to have the ability to directly embed an image using a joplin:// url so that it can interop among my devices.

[roman-r-m]

would it be possible / welcomed to link to a specific resource?

Effectively what I want to do is manage my attachments in joplin and link to them via obsidian. I'd like to have the ability to directly embed an image using a joplin:// url so that it can interop among my devices.

I'm not sure how you expect this to work. These URL, when called, trigger actions within Joplin, like opening a note or a notebook, but I don't think there's a way to return data (e.g. image) back to the caller

[benlau]

This was implemented in desktop, so only mobile is needed now.

How about the callback to create a new note? Is it implemented? I have tried Joplin 2.6.10 with the following link:

joplin://x-callback-url/createNote?title=NOTE_TITLE&body=NOTE_BODY

But it just launch Joplin without creating any new note in Mac.

[roman-r-m]

How about the callback to create a new note? Is it implemented?

No, currently there's only openNote/openFolder/openTag

[drewmoseley]

Hi all. Thanks for this feature. I look forward to using it heavily. I'm not sure how to access the URLs though. I generally run both Ubuntu and MacOS. I get the "external link" from the right-click menu and add it to calendar entries and todo list items. But then when I click them I don't get the app launched and the right note selected.

They work properly from the command line in Ubuntu using "xdg-open "

When I click in a google calendar invite it simply opens up a blank tab to the URL "about:blank#blocked". Is there a setting I need to change?

When I click a link in my ToDo manager (https://www.rememberthemilk.com/) the app window simply goes blank white and I have to exit and reenter. The web version of the ToDo manager does the same thing as Google calendar.

Finally when I click on the link on my iPhone, the Joplin app is launched but the note is not selected.

Thanks for any advice in resolving these issues.

[roman-r-m]

When I click in a google calendar invite it simply opens up a blank tab to the URL "about:blank#blocked". Is there a setting I need to change?

This looks like some kind of permission issue, possibly in Chrome. How did you install Joplin btw? It works for me in Firefox with Joplin installed via AppImage.
I copy the link, paste in into Firefox, press enter and get a prompt to select the app with Joplin being the default.

Finally when I click on the link on my iPhone, the Joplin app is launched but the note is not selected.

I'm actually surprised this works at all, I was sure we only have link handling on desktop atm

[drewmoseley]

I used the "recommended" approach for installing in my Ubuntu system. ie

wget -O - https://raw.githubusercontent.com/laurent22/joplin/dev/Joplin_install_and_update.sh | bash

And if I copy/paste the full URI into the address bar of either chrome or firefox (on Ubuntu any way) I see now that does work. It just seems to be using "clickable links" that does not want to work.

Regarding mobile, I thought it was reported above as not working but I tried anyway and that's the behavior I saw. Just consider it a report of an issue and nothing urgent.

[drewmoseley]

And when I manage to get a clickable link in Firefox with Google Calendar, I right click and do "Open in New Tab" and it opens with an "Invalid URL" error to the URL "about:invalid#zSoyz"

[roman-r-m]

I am not sure why this is happening for you.

I got it working in google calendar:

• created a new task
• pasted the link into the description
• used the link button to convert text into a link
• right-click - open in new tab
• I got popup message "Allow calendar.google.com to open joplin link", I press Select Application and there's Joplin there.
• Select Joplin and it becomes active and switches to the note.

[drewmoseley]

Very odd. That's exactly what I did. But for some reason the "joplin://" URIs are not clickable but "http://". I get the same behavior in Chrome and Firefox(even in safe mode). Not sure if there is some google calendar setting I need to change. I'll keep banging on it.

[laurent22]

Let's close this one as it was implemented in #5416. If it gets implemented on mobile we could create a new issue.

[GonzRon]

is there a ticket for android yet?

[roman-r-m]

is there a ticket for android yet?

Not that I know of. It was included in another pr but it never got merged.

[GonzRon]

Created #8639