← Contents

Adding by Identifier and Retrieving Metadata

With an identifier such as a DOI or ISBN you can get a complete reference quickly; and an existing PDF can be recognized the other way round. These functions follow Zotero's approach and use Zotero's lookup translators.

Adding by identifier

Add Reference(s) by Identifier in the library toolbar opens a window. You can enter DOIs, ISBNs, arXiv IDs, ADS bibcodes and PubMed IDs, separated by spaces or one per line, several at a time. The application works out which kind each one is, asks the matching data source, and adds the result to the collection you are looking at.

  • Keywords and subject headings that come back are added as automatic tags (which can be hidden in the tag selector); the setting "Automatically tag references with keywords and subject headings" under Miscellaneous controls this.
  • A DOI that is already in the library is not added twice; the message points to the reference that already has it.
  • The data sources are reached over the network; if the network is not available see Troubleshooting.

The Look up buttons beside the DOI and ISBN fields of the reference form take the same route.

ISBN coverage

When you add a book by ISBN, the application asks these catalogs: the Library of Congress, the Bibliothèque nationale de France, K10plus in Germany, LIBRIS in Sweden (only numbers starting with 91), the National Library of Poland (only numbers starting with 83), the Brazilian Book Chamber, and WorldCat and the World Health Organization (only numbers starting with 978924).

Chinese and Korean books are often not found; this is not a mistake in what you entered. When a book is not found, create the reference by hand, save it from a library catalog or another site with the browser window, or import a file exported from such a site.

Retrieve Metadata

Right-click a PDF or ebook attachment and choose Retrieve Metadata, and the application tries to work out which reference the file is, creates a reference as its parent and moves the attachment under it. Turning on "Automatically retrieve metadata for PDFs and ebooks" on the General page of the settings does this whenever you add a file. Undo Retrieve Metadata reverses it.

Retrieving metadata is done on your own computer. It works like this:

  1. it takes the text of the first five pages of the PDF and looks for a DOI or arXiv ID printed there;
  2. it runs the identifier it found through Adding by identifier above;
  3. the title that comes back must really appear in the text of those pages, otherwise the match is treated as wrong (a DOI of someone else's work cited in the text is not attached to this PDF by mistake).

So papers that print a DOI or arXiv ID in their first pages can usually be recognized; older papers without a printed DOI, scans, books, theses and most Chinese manuscripts usually cannot, and you get the message "No matching references found". In that case create a reference by hand and drag the PDF onto it, or use Create Parent Item(s)… in the context menu to create a parent for the PDF. A row that could not be recognized also has a Create Parent Item… button in the progress window, so you can carry on from there.

For ebooks (EPUB) the application first reads the metadata in the book, then looks for a DOI and ISBN on the copyright page and the first sections and runs a lookup; if nothing is found it creates the reference from the metadata in the book.

Find Full Text

Select a reference and choose Find Full Text from the context menu, and the application looks for an open-access PDF or ebook for it. It requires that the reference has a DOI, a URL or a PubMed Central ID and that it has no PDF or ebook attachment yet. The search tries these routes in turn: the page the DOI resolves to, the reference's own URL, open-access sources, and resolvers that you define yourself.

Several open-access sources can be used, each switched on or off in the "Find Full Text" group on the General page of the settings: OpenAlex, Europe PMC and Semantic Scholar are on by default and receive only the DOI of the reference; Unpaywall is off by default and is asked only after you turn it on and enter your own e-mail address, in which case it receives the DOI and that address. The enabled sources are asked at the same time, and the download addresses they return are merged into one list (OpenAlex first, then Unpaywall, Europe PMC and Semantic Scholar, with each address kept once) that is tried in order; the first PDF or ebook that downloads is used. If one source finds nothing, is rate-limited or fails, only that source has no result and the others are unaffected. The settings say next to each option who receives what, and the choice is yours.

Custom resolvers are added, edited and removed with "Manage Custom Resolvers…" in the same group. Each one has a name, a request method, an address containing {doi} (replaced with the reference's DOI, which is sent to the server at that address), how the response is read (web page or JSON) and how the download address is taken from it; the Auto column decides whether it is also used when references are added. Every field is checked when you save, and the one that is wrong is named on the spot. The list is stored in the findPDFs.resolvers setting, in the same format as Zotero.

Requests to the same site are spaced out, the application waits when a server asks it to try again later, and it stops after repeated failures; you can watch all of this in the progress window. A file that is found is named by the File Renaming template and added under the reference as an attachment.