Basic Setup

After installing the extension through Roam Depot, you'll need to complete one last step to use the extension.

If the extension was installed correctly, a warning icon should appear in the navigation bar of your Roam graph. Hovering over it will show some information about the extension's status, and include a button to finish the setup:

Click on the button - it will open the extension's settings panel.

Adding data requests

At the top of the panel, you will see a section titled "Requests". This is where you can let the extension know which Zotero libraries you'd like to use. Click on "Add request".

A popup will appear, where you can add one or multiple libraries. For each library, make sure to indicate:

• the library's type (user library or group library)

• the library's ID : this is a 6- or 7-digit ID, and is different from the library's name. Here is how you can find it:

  • User library: see Pre-requisites

  • Group library: log into your Zotero account in a browser, and open the library. Check the URL of the page ; it should have a 6- or 7-digit ID.

• an API key that can access the library's items (see Pre-requisites). If you'd like to use a single API key for all your libraries, you don't need to enter it every time -- it's enough to enter it only once.

• a nickname (optional) : this isn't used anywhere in the extension, but can help you keep track of what the different requests are.

Make sure to click "Add", then when you're done entering requests, click "OK". If there are any issues, the extension will show a warning - otherwise, you will be able to see your list of requests.

Close the dialog, and you should see that a book icon replaced the warning icon in the top navigation bar of the graph:

The book (right-most) is the extension's icon

About the extension's icon

The icon acts as a toggle for turning the extension on/off, and signals the state of the extension in real time :

• Inactive - the extension is off.
• Busy - the extension is loading data. Depending on the number of requests and items, it may take ~20s for all data to be loaded.
• Active - all data has been loaded and is available to use.
• Error - something went wrong while attempting to retrieve the data. Hover on the icon or check the browser console for details.

You can hover over the icon at any time, to check on the loading state and get additional information (link to docs, current version of the extension...) :

Here, the extension has finished loading all data, and didn't encounter any errors. Hovering over the icon reveals a tooltip, which shows when data was last synced.