RoamResearch is a knowledge management tool. It’s not a file management tool. Any document I load into Roam is locked in — not in a way that prevents me getting it out — but in a way that locks me out of all the other things I may want to do with that document. Edit it easily, make a copy, send it to a friend. Yet, storing a document close by any notes I take on it is important as well.

This article describes how to get the best of both by embedding OneDrive files within RoamResearch.

The criteria for success

Having used many tools in the past, there is a set of criteria I have which builds a system that works best of me.

1. Document must be easily accessible for reading, markup, modification, and copying.
2. Documents must be able to be renamed or moved without breaking links.
3. Documents must be shared and quickly accessible across multiple devices and operating systems without breaking links.
4. Documents must be secure.
5. Documents must be backed up and quickly restored as part of my normal backup processes.

OneDrive for file storage

Let’s look at file management first. I use Microsoft’s OneDrive as part of the Office 365 subscriptions I have at home and work. In a past life I used Dropbox and you should be able to create a similar solution to this if Dropbox is your cloud sharing solution.

OneDrive integrates with Windows, MacOS and iOS. It gives me access to files anywhere and keeps any changes synced wherever I am logged in. Check items #3 (shared) and #4 (secure) above. I can make a change to a document on Windows and pretty much pick it up immediately on a Mac. Documents are stored behind a username, password and two-factor authentication. And I even get a fair dose of #5 (backup) for online backup just by virtue of having multiple copies on multiple devices and version of each whenever a change is made.

Obviously #1 (file access) comes as a the default.

The magic of the share link

Any file or folder on OneDrive can be shared with another person. There are multiple points in the interface where you can "Share" a link to a file.

Each file shared in this way is:

• Provided by a unique URL that gives read/edit access to the file
• Useable by anyone on the planet that has access to a web browser and the link.

Now, it is possible to add some security options to a link but if I have tens or hundreds of files to load into RoamResearch it becomes cumbersome.

What this does mean however — and this is critical — is that every file in OneDrive receives a unique number when shared that doesn’t change.

Here’s the link to the file above, a diagram mapping the various states of awareness in the Pathfinder 2 role-playing game.

https://1drv.ms/b/s!Ag8laod4ZSw5rEwoPMBBU7X10VQB?e=PnbJVT

In Roam I might write:

[States of Awareness.pdf](https://1drv.ms/b/s!Ag8laod4ZSw5rEwoPMBBU7X10VQB?e=PnbJVT)

There are two ways to stop that link from working. Either I remove the share, or I delete the file. Renaming or moving the file to another folder does not break the access.

So we’re part way there. It looks like OneDrive can potentially do what we need. It gives links to files that can be pasted in to RoamResearch, though the file is not visible inline i.e., embedded. But the share sits against the file and when doing that for personal use, a little too much.

Let’s embed

The syntax we need to embed something into Roam is {{iframe: URL}}. It makes sense to think {{iframe: https://1drv.ms/b/s!Ag8laod4ZSw5rEwoPMBBU7X10VQB?e=PnbJVT}} would work but it doesn’t. It’s not the link OneDrive is expecting when you want to embed a file.

Is there such a thing? Sure is.

Firstly, make yourself familiar with the Embed files directly into your website or blog instructions provided by Microsoft. This gives you the HTML for inserting into a blog such as this.

The code for our previously shared file is:

Note: At this point I have two shares attached to my file. The earlier share and the new embed share. Normally there would only be one, but this shows how crazy it can get. If I had shared a parent folder, then I’d have three.

If you copy and paste this text as is into Roam it won’t work. Too much information for Roam to parse in a form it’s not expecting. Instead, copy everything from https://onedrive.live.com to, and incuding, &em=2.

Sorry, did I forget to mention you can’t actually copy that little bit directly out of the OneDrive window where it gives you the code. You have to copy it all, paste somewhere, then copy the URL out. Not my bad interface design.

Once you’ve done that, you’ll have a link that will show an embedded version of your document in Roam.

{{iframe: https://onedrive.live.com/embed?cid=392C6578876A250F&resid=392C6578876A250F%215708&authkey=APbx5r3cvxeEIvo&em=2}}

You’re done.

Yet, with a couple of different steps we can make some improvements.

Improve your embeds

Let’s look at that URL again.

https://onedrive.live.com/embed?cid=392C6578876A250F&resid=392C6578876A250F%215708&authkey=APbx5r3cvxeEIvo&em=2

The key parts which differ from the simple share link of earlier are:

• The word embed after the domain name
• The cid value, a unique identifier for the document
• The resid value, the same identifier as cid but with some extra values
• The authkey value, which provides an authentication key for access by everyone
• em=2 which tells the Roam to display the document as embedded, rather than just linked.

Ideally we want a link which:

• Is faster to create and edit than the embed process given by Microsoft.
• Works only on a device if you are also logged into OneDrive (security)
• Can be automatically formatted for Roam using a text expander tool such as Keyboard Maestro, FastKeys, TextExpander or Phrase Express.

This is what we do.

1. Open OneDrive in a browser
2. Navigate to the file you want to share
3. Click on that file
4. Copy the URL, from the start, up to right before &parid
5. Create your {{iframe: }} item in RoamResearch
6. Paste the URL
7. Replace &id with &resid
8. Add &em=2 at the end.

Ignore any line wrapping you see below.

I hope you can manage steps 1-3 without guidance. My full url is

https://onedrive.live.com/?cid=392C6578876A250F&id=392C6578876A250F%215708&parId=392C6578876A250F%212958&o=OneUp

and I want to copy just (step 4)

https://onedrive.live.com/?cid=392C6578876A250F&id=392C6578876A250F%215708

An understanding of Web Query String formatting may help you identify the right point.

Steps 5 and 6 give me:

{{iframe: https://onedrive.live.com/?cid=392C6578876A250F&id=392C6578876A250F%215708 }}

Step 7 gives

{{iframe: https://onedrive.live.com/?cid=392C6578876A250F&resid=392C6578876A250F%215708 }}

Here I’ve modified the &id=392… in the middle to &resid=392… (c’mon, Microsoft is famous for being consistent)

And finally, step 8, add the &em=2 instruction to embed the file.

{{iframe: https://onedrive.live.com/?cid=392C6578876A250F&resid=392C6578876A250F%215708&em=2 }}

This is what it looks like in Roam once done. There are some good controls for resize and zoom at the bottom of the window.

Important to note. If not signed into OneDrive, this shows up as a grey box indicating the file cannot be accessed. Log into OneDrive in your browser and it will show.

Wrapping up

Let’s go back to my original criteria.

1. Document must be easily accessible for reading, markup, modification, and copying.
2. Documents must be able to be renamed or moved without breaking links.
3. Documents must be shared and quickly accessible across multiple devices and operating systems without breaking links.
4. Documents must be secure.
5. Documents must be backed up and quickly restored as part of my normal backup processes.

How did we do?

• OneDrive meets critiera 1, 3, 4 and 5 out of the box
• Sharing links gives us 2
• Using the final steps shown above, we get security in Roam as well

For me an ideal solution.

Now to create those text expansions to make it even faster.