Import from Apple Notes - $2,500

[obsidianmd]

Import from Apple Notes - $2,500

[kepano]

A $2,500 bounty has been added to this project.

[Star-Lord-XIII]

I have been developing & maintaining Exporter for the past 7 years. Just started using Obsidian & loving it. If there are any special requirements needed for Obsidian that aren't being met with the current version of Exporter, please do let me know.

[mirnovov]

I would like to apply for this if possible - this seems like a fun thing to complete.

I have developed the Obsidian Homepage plugin, which is the 30th most popular in the community plugin repository. Additionally, I used to use Apple Notes as my primary note-taking solution and still use it for a few small things (though I use Obsidian for anything substantial), so I'm well-acquainted with what users expect and to test the correctness of any solution that would be developed.

I have examined the Importer code and have already developed a basic proof-of concept AppleNotesImporter that takes the Apple Notes database and decodes the note files, and intend to complete it and create a full-featured solution if this is accepted.

• It detects any NoteStore SQLite database, which is stored in a designated location on the user's computer. This requires Obsidian to have the Full Disk Access permission on macOS, so it would prompt the user to ensure it is enabled if they don't have it (if their vault isn't in a location that requires it). Unfortunately AFAIK there is no way around this.
• Since macOS natively comes with an up-to-date version of SQLite it leverages that (with a small binding library), since using traditional SQLite node modules isn't possible given the Obsidian plugin format. WASM could also be considered instead, but that would be a worse solution IMO (though it could be implemented as a fallback).
• Most note data is stored in a column that is a gzipped protobuf. This contains the raw text, and then any formatting that is applied to said text. I use pako and protobuf.js to decode the note data itself.
• Attachments and internal links aren't currently implemented but would be if I am assigned. The former shouldn't be too difficult as they are already stored in the filesystem, and there is prior work in this area (as you noted above). The latter would be a bit more of a challenge but should be doable.
• It currently only works on macOS, and is disabled on iOS. Unfortunately, I believe there's a good chance that obtaining notes on iOS isn't possible at all given the strict permissions enforced on that platform.

[ReblochonMasque]

Your app worked wonderfully for me @Star-Lord-XIII - Many thanks!

[geekforbrains]

I have been developing & maintaining Exporter for the past 7 years. Just started using Obsidian & loving it. If there are any special requirements needed for Obsidian that aren't being met with the current version of Exporter, please do let me know.

Huge fan of Exporter! 🙇‍♂️ Thanks for your work on that.

[Star-Lord-XIII]

Acknowledged.

[neo773]

Hi there, I'd like to apply for this.

My approach doesn't ask users to grant full disk access, which I think is a bit invasive. The main point of a built-in importer is to make things easier for non-tech people, so this might put them off a bit.

It's based on Apple JXA (JavaScript for Automation) and written in TypeScript. This PR shows how my approach works.

If this gets picked, I can work on it more to fix and iron out the bugs.

Thank you.

[mirnovov]

I have upgraded to macOS Sonoma and confirm that the internal links can be retrieved (quite easily in fact, since it builds on existing aspects of the data format). Haven't really done too much yet as I have been quite busy lately, but I am confident I can meet the deadline barring exceptional mitigating circumstances.

[huyz]

Make sure to check out https://github.com/threeplanetssoftware/apple_cloud_notes_parser

[kepano]

@Star-Lord-XIII have you investigated the new iOS17 format for internal links? It would be great to make sure those links are maintained via [[Link]] syntax once that feature becomes widely available.

Also can you confirm that Exporter's current Markdown export supports all attachment types (images, PDFs, etc), as well as advanced Markdown features like tables?

[Star-Lord-XIII]

I haven't investigated the new link format, will look into it.

Exporter's current Markdown supports almost all these formats for attachments & renders tables correctly in markdown. Images shared from iOS in HEIC & HEIF formats are converted to jpegs while exporting in markdown; they are present in the HTML exports as well but in original (HEIC/F formats). These image formats are not currently imported/supported correctly by most note taking apps, including Obsidian. One exception with attachments is scans made from iOS devices. A workaround for that is to convert them manually into PDFs and reattach them to the note, which should work since PDF attachments are supported. I haven't found a better solution for this one yet as Apple Notes APIs don't expose scans from existing endpoints.

[Star-Lord-XIII]

MacOS 13.5 doesn't expose iOS 17 internal links via attachments or body content. So there is no way to access those yet as far as I have tested. Same goes for todo lists. All other requirements mentioned in bug -- images, attachments, tables and Obsidian-compatible markdown are already supported by Exporter.

[kepano]

@Star-Lord-XIII this issue is for adding support within the Importer plugin, without the need for a separate tool

[holtwick]

I have been developing & maintaining Exporter for the past 7 years. Just started using Obsidian & loving it. If there are any special requirements needed for Obsidian that aren't being met with the current version of Exporter, please do let me know.

@Star-Lord-XIII Your tool is almost perfect and the best I found for exporting Apple Notes. There is one little thing, although an important one, that does not seem to work: export of links (see attached Screenshot of an export to Markdown). Other exporters experience the same issue, therefore I wonder if this is due to limitation of the source data.

[winged-voices]

@holtwick

@Star-Lord-XIII Your tool is almost perfect and the best I found for exporting Apple Notes. There is one little thing, although an important one, that does not seem to work: export of links (see attached Screenshot of an export to Markdown). Other exporters experience the same issue, therefore I wonder if this is due to limitation of the source data.

I can't get Apple Notes to send coherent links as any easy share (I'm sure there is a way, but it's above my coding experience; I came over here to see if someone had snagged this bounty) to ANY other format, even directly from the native "Share to..." on my iPhone or iPad, especially if they are or have ever shown up as rich links. That may be part of the issue. I can see that they're not rich links here, but if it's ever converted into the preview format and you had to hit backspace or x out, it may still need kid gloves.

(A HUGE pain when using Notes as a quick bookmarking system and then trying to send it to yourself on a product where you can't pull up iCloud. Most things print them as text only like the first highlighted one. Again, I'm sure there is a workaround but Notes is frankly terrible for link lists.)

[FilipLaz]

It would be nice to see requirement for tags for importer.

[Star-Lord-XIII]

I have been developing & maintaining Exporter for the past 7 years. Just started using Obsidian & loving it. If there are any special requirements needed for Obsidian that aren't being met with the current version of Exporter, please do let me know.

@Star-Lord-XIII Your tool is almost perfect and the best I found for exporting Apple Notes. There is one little thing, although an important one, that does not seem to work: export of links (see attached Screenshot of an export to Markdown). Other exporters experience the same issue, therefore I wonder if this is due to limitation of the source data.

Yeah, source is the cause of missing links and todo-list status. Unless the data is either present in the HTML body of the note or in the attachment list it cannot be exported by a sandboxed app which needs to follow the entitlement constraints to publish the app on AppStore. With links and todo lists I hope the Obsidian Importer will have an easier time since it will be outside AppStore and can have direct access to the Note's SQLite instance.

[pyeguy]

would be great to support export as pdf for handwritten notes!

[mirnovov]

@neo773 The way I see it, your solution has a different set of trade-offs but I wouldn't explicitly call it better.

• I have previously developed a plugin that interfaces with JXA for another app. It can be a bit fiddly and unreliable at times from my experience. For instance, when testing your plugin, it tells me "Notes account not found" despite my account being extant and having plenty of notes.
• However, if it does work, using JXA to export notes could be more reliable than manually parsing the note format, as it's the intended method made by Apple of doing so, while accessing the SQLite database is not really intended (though it's what both of the tools that kepano linked to do).
• It would require granting the automation permission, which isn't much less invasive. Both permissions grant a pretty wide amount of access to the computer. It is a lot less scary though for a non-tech user to be prompted for "access to control Notes.app" as opposed to being asked to allow "full disk access", which isn't insignificant. Another advantage is AFAIK macOS allows apps to expressly prompt for automation while it can only open the Full Disk Access settings pane, which is less intuitive for users.
• Not sure about having to prompt to export then select which notes to import, seems a bit unintuitive and burdensome to me, especially with large amounts of notes. If that can be avoided and it all done behind the scenes in a temp directory I would do so.
• Not sure if internal links would be compatible with this, given that you've exporting them all as HTML files that are independent of each other. It wouldn't surprise me if the HTML export in Sonoma just strips them; you'd probably want to find that out ASAP.
• Your solution massively increases the Importer JS output size to 21.3 MB, as opposed to the current size of 230 KB (mine is around 400 KB so far, but I don't see it increasing hugely beyond that). Not sure if this is desirable given that the vast majority of this is for one format that doesn't even work on the majority of platforms (only macOS, but not Windows, Linux, iOS or Android). And ofc there's the security risks with large amounts of JS dependencies.

Again, I see trade-offs inherent to both approaches, and I trust Obsidian's developers to make the right judgement. While the bounty is nice I think they should go with whatever is the most technically sound solution, not the one that happens to benefit me the most. Given that Apple pretty strictly sandboxes its apps I don't think there's going to be a solution without some sacrifices but if someone comes up with one I'd be impressed.

[neo773]

@mirnovov

Thanks for insights appreciate it!

it tells me "Notes account not found" despite my account being extant and having plenty of notes.

My PR was WIP so the account not showing up bug can be fixed, the current implementation is hardcoded that's why you can't see your folder.

Not sure about having to prompt to export then select which notes to import,

It's also doable, see 1st point.

It wouldn't surprise me if the HTML export in Sonoma just strips them;

I haven't upgraded my mac yet will test it soon.

Your solution massively increases the Importer JS output size to 21.3 MB

Seeing 3.4 MB on my end when building for production, it's the 2md library that's caused it to balloon
This was quickly put together so the lib can be swapped with the builtin parser.

Also it was not my intention to go around Obsidian bounty rules (with the PR), I've been doing open source bounties listed on Algora.io which works a bit differently. So, I'm sorry about that.

[BrandanTD]

AppleScripts x Osascript

Pros

1. Reliably parse basic Apple Note files as a single file or in bulk using the Note Suite Library.
2. Supports HTML content retrieval.
3. Supports plain text retrieval and attachment retrieval.
4. Can retrieve full links.
5. I would love to work with neo773 on this as neo seems to have quite a decent solution already prepared. I am currently just running AppleScript code in Node via a string and the osascript command. Most data imports correctly.

Cons

1. Cannot retrieve internal embedded links with custom text.
2. Cannot retrieve IOS17 internal links at all.

Requirements

• Must work on macOS
•  Properly converts files to Obsidian-flavored Markdown, including tables, to-do lists, etc
•  Support for images and attachments. Embed links converted to Markdown format !()[image.png] and placed in the user's defined attachment location (Settings → File & links)
• iOS is nice to have but not required for initial version
• Supports internal links added in iOS17

Obsidian x Apple Shortcuts

Pros

1. Does not need to use Obsidian Importer.
2. End users will have free range to manipulate the shortcut according to their needs.
3. Can import/export single Apple Notes or multiple Apple Notes.
4. Obsidian users can create custom shortcut links and custom params to fire their shortcut using this format: shortcuts://run-shortcut?name=[name]&input=[input]&text=[text] .
5. Is a true mobile and macOS solution! - A solution I am invested in.

Cons

1. AFAIK you can't grab videos/markup in bulk on mobile unless the user individually selects the video/markup and shares it. It does however, leave the file name which can then be parsed and found when the user logs into a macOS system.
2. Mobile users will have to install the shortcuts app.
3. Is an external tool outside of Obsidian.

Requirements

• Must work on macOS
•  Properly converts files to Obsidian-flavored Markdown, including tables, to-do lists, etc
•  Support for images and attachments. Embed links converted to Markdown format !()[image.png] and placed in the user's defined attachment location (Settings → File & links)
• iOS is nice to have but not required for initial version
• Supports internal links added in iOS17 (Same Name Internal Links Not Supported)

Internal IOS17 links with the same name as the link are currently not supported in macOS 13 or even when copying text to the clipboard. The potential solution here would be to match the exact text with existing note names and parse accordingly. Even then, the user would need to manually approve these changes as some title names may appear as regular text in subsequent documents.

NoteStore x SQLite

Pros

1. Easy way to access all Apple Note data all at once.
2. Great for if an Obsidian user keeps NoteStore.sqlite files in a external hard drive and needs to import them.
3. Great for if an Obsidian user needs to recover NoteStore.sqlite data.

Cons

1. You will need to have an intermediate to advanced level of SQL knowledge to understand, navigate and integrate this logic.
2. Apple can at any time choose to change their note storage structure as they have many times in the past.
3. This is my least researched and experimented solution. I have reliably retrieved basic Apple Note data using this method. However, I would happily work with or pass off this integration to mirnovov as mirnovov seems to know more about this.

Requirements

• Must work on macOS
•  Properly converts files to Obsidian-flavored Markdown, including tables, to-do lists, etc
•  Support for images and attachments. Embed links converted to Markdown format !()[image.png] and placed in the user's defined attachment location (Settings → File & links)
• Supports internal links added in iOS17 ( Needs Research )
• iOS is nice to have but not required for initial version

Useful Mentions

1. You can create a clipboard listener to synchronously generate obsidian notes.
2. You can use a UI parser to automatically navigate the UI and gather note data.
3. You can use Automator Record Workflow to automatically navigate the UI and gather note data.
4. You can create a PDF parser for users to upload exported Apple Note PDFs.
5. You can get crazy and parse iCloud blobs received from the server. Probably against the rules.

Conclusion

Ideally, all of the solutions should be integrated for an inclusive solution. In my professional opinion, I would integrate in this order:

1. Apple Shortcuts - Obsidian Apple Shortcut Tool - User friendly, non-invasive, faster to set up, easily accessible, requires 0 new npm packages & 0 new installer updates for Obsidian users.
2. AppleScript x Osascript - Great way to pull legacy note & attachment data with a minimal footprint. Users who wish to have embedded internal links transferred will need to use the Obsidian Apple Shortcut Tool.
3. NoteStore x SQLite - Great solution for users who store their note data on external drives, users who may have lost data or advanced users who want to just have more overall control of their notes DB.

Why Hire Me?

• I have thoroughly researched this project and the various potential solutions to the problem at hand.
• Not only am I capable of bringing the project to completion, but I am ecstatic to provide the best solution to Obsidian's users.
• I am more than willing to work with other developers and have 10+ years of experience working with and or managing developers.
• I plan to further develop for Obsidian users for the foreseeable future as I will be personally integrating Obsidian into my daily routines and habits.

Also, I have a ton of Apple Notes and I need them properly imported lol...

I hope at least some of this information was useful to any current or future developers looking at this.

Let's build something great!

[tgrosinger]

@mirnovov, a couple of questions we'd like to verify about your approach:

1. Can you please elaborate on what you mean by a binding library for sqlite? What library are you using, and will it work on both M-chips and Intel Macs?
2. What does granting the Full Disk Access permission look like to the user? Does this happen automatically the first time they use the plugin? Are there any changes that need to be made outside of this importer to make it so that Obsidian and this plugin can request that permission from the OS? What if the user revokes the permission later, will it prompt again next time they import?

Thank you

[mirnovov]

1. I use sqlite-tag-spawned. Since this just calls the SQLite executable bundled with macOS, it should be compatible across architectures.
2. As I stated above, macOS doesn't have a native permissions prompt for this. However, you can open the settings pane for it with the URL x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles (you can test it yourself by using the open command in the shell). There would be an Obsidian prompt beforehand that would explain to the user what to do.

[kepano]

@mirnovov you have been assigned the bounty! Please submit your initial PR by end of day (GMT) on October 16th, 2023.

Join the #plugin-dev/importer channel if you have any questions: https://discord.gg/obsidianmd

---

Thank you @neo773 and @BrandanTD for your very thoughtful submissions. This is a situation where all of the options have significant tradeoffs. We have decided to pursue the SQLite approach despite its downsides. We may ultimately need to explore the AppleScript approach if we hit a roadblock with SQLite, but we'll cross that bridge when we come to it.

[BrandanTD]

Congrats @mirnovov on the bounty acquisition! Can't wait to see what you come up with!

@kepano Happy to help!

I do however, humbly request that you consider concurrent approaches or future solutions to this project. In my research, I have come to the conclusion that at minimum the SQLite and Apple Shortcut approach must be implemented to complete all of the project requirements.

SQLite Approach

The SQLite approach will be needed for past, current or future datastore retrieval no matter what. I am still unsure if it will be able to retrieve IOS 17 internal links, but I am sure @mirnovov will figure that out. Although, I do know it is not an IOS solution.

Apple Shortcuts Approach

I have successfully built an Apple Shortcut as a standalone to extract, decrypt and export Apple Note files. I have also created a simple export shortcut to export Apple Note Files and attachments to a zip that can then be read by the Obsidian importer (see demo below.)

In my research, I have not been able to find out how to communicate with internal Apple Note functions on IOS without the use of a third party vendor, Apple Shortcuts or exposing native modules to communicate between Obsidian and Apple Notes.

These solutions should meet all of the listed requirements without within the constraints of this Obsidian plugin.

Apple Shortcuts Solution MacOS Demo

Apple Shortcuts Solution IOS Demo

Requirements

•  Must work on macOS
•   Properly converts files to Obsidian-flavored Markdown, including tables, to-do lists, etc
•   Support for images and attachments. Embed links converted to Markdown format !()[image.png] and placed in the user's defined attachment location (Settings → File & links)
•  iOS is nice to have but not required for initial version
•  Supports internal links added in iOS17

Issues

• Custom name internal links still link to the old apple note. This isn't terrible, however I would like to decrypt the UUID and link the document internally in Obsidan. Perhaps @mirnovov will be able to extract that UUID note data and we can apply it to the links.

To Do

• Combine the importer and apple shortcut into one button click.
• Add UI updates for imports.
• (Hopefully) - Auto Decrypt/Parse UUID internal links and replace with internal Obsidian links.

Closing Statement

I do not mean for this to take away from @mirnovov's bounty as mirnovov has earned it. I would like to see the SQLite solution and the Apple Shortcut solution implemented.

I request, given this new found information, that this solution will be separate from this bounty. I would be happy to sit down and discuss further details at your convenience.

I understand if you do not want to follow through with this approach. I will continue to build it regardless as I still personally need the solution and I am close to wrapping this up.

[kepano]

@BrandanTD thanks — please open Apple Notes Shortcut as a separate issue so we can keep this issue focused on the SQLite approach. Shortcuts could be an alternate path for some users, but we don't see this as the primary solution for Importer. We also accept issues/PRs to the Help repo if you want to document this solution.