# Introduction

This extension started out of a basic use case : **importing data from Zotero to Roam based on a citekey**. 

A number of users in the Roam community, myself included, have adopted a reference system where citekeys are used as page names like so : `[[@citekey]]`. This allows for a few convenient things like : 

* having a unique, simple handle to reference a literature item within Roam ;
* being able to cite really easily with `[[` and filtering suggestions with **@** ;
* being able to write in Roam, and then to export to a formatting tool (Zettlr, Pandoc, etc.) without having to manually go in and replace references.

Beginning in \~May 2020, [melat0nin's Zotero export plugin](https://github.com/melat0nin/zotero-roam-export) enabled Zotero -> Roam data import, using the Zotero desktop client and a JSON file. It's the best solution I know if you're looking to import a lot of library items at once into Roam ; it handles single items, multi-item selection, and collections. 

It's been a major inspiration for the development of this extension, in particular with user settings. Though while it's very efficient for bulk data import, it's cumbersome to generate a JSON file when adding just one item. Especially if you repeat the process a few times. It also requires starting from the Zotero app, tracking down which item(s) you haven't imported yet, and a fair amount of context-switching.

What this extension provides is a **data import functionality directly from within Roam**, by making calls to the Zotero Web API. It assumes the workflow described above, where the `[[@citekey]]` nomenclature is used, and works best with the [Better BibTeX plugin](https://retorque.re/zotero-better-bibtex/) as citekey manager.