While we expect people to find the EPPI-Reviewer / Zotero integration to be useful in ways that go far beyond the recommended usage cases, the integration is complex and can sometimes result in confusing behaviour.
The Zotero functionalities can be neatly subdivided into two very distinct phases: setting up the connection and exchanging data. Thus, this page is divided in two separate sections.
Setting up the connection
The Zotero page in EPPI-Reviewer Web has an "initial opening" check: if it detects that it cannot communicate with a Zotero Group Library, it will show the "Setup" tab, and will refuse to move onto the "sync" phase. This is by design, as the sync functionalities can't exchange any data if the connection to a Zotero library is absent or isn't working.
If you are stuck in the setup page
It's possible you may see a situation where the initial setup was working, some pushing and pulling of data between the two systems worked, and then, from one day to the next, you can only see the "Setup" tab. This can happen if the Access Key has been "edited" and/or deleted on the Zotero website. In such situations, all review members will only have access to the setup page. Moreover, only the person that originally set up the Access Keys will be able to resolves this issue..
Any EPPI-Reviewer user who did not create the Access Key but visits the EPPI-Reviewer Zotero page will see an indication of who owns the key, along with brief instructions.
Similar problems might occur when a review is configured to be paired to a specific Group Library and the Library then gets deleted.
In these situations, please contact the Key Owner to visit the Zotero page in EPPI-Reviewer and follow the online instructions to resolve the situation. In most cases, the easiest option is to use the "reset/delete key" buttons provided to obtain a new Key.
If the Access Key Owner cannot intervene, for whatever reason, please contact EPPI-Support. You will need our help to resolve such a deadlock.
If you can't obtain an Access Key
Sometimes after configuring the Access Key preferences, and clicking "Save Key" on the Zotero pages, people will be sent back to the EPPI-Reviewer "Setup(Zotero)" page, with an note on top, saying:
"Sometimes Zotero fails to provide the API-Key needed to access Zotero data [...] Please Please wait one or two minutes and try again"
This happens for unknown reasons and in our tests, trying again usually works, although it's possible (if you are unlucky) that it will take more than two attempts to succeed. If multiple re-tries fail, please contact EPPI-Support.
If you can't follow the on-page instructions
The "Zotero setup" page in EPPI-Reviewer contains detailed "on screen" instructions. You can use the "Show me (new tab)" buttons to open the instruction on a separate window/tab so they will remain visible while operating on the Zotero website. Should these instructions not work for you, please contact EPPI-Support. Please include a detailed description of what is blocking you so we can understand at what step the instructions seem to deviate from what you're observing. Screenshots usually work very well for this purpose.
Exchanging data (pushing and pulling)
The code that drives data exchanges between Zotero and EPPI-Reviewer is remarkably complex, mostly because of the need to "translate" references' data from one "language" to the other, which is not straightforward because the two "languages" are indeed, very different.
For this reason, it is possible that problems (anticipated or not) will occur, and/or that the EPPI-Reviewer code harbours disruptive bugs. In general, we anticipate two distinct families of issues, when pulling/pushing references/items: errors preventing push or pull operations and "translation" errors, where data goes missing (or deteriorates) when pushing, pulling or cycling through both actions.
Explicit errors when pushing or pulling:
We made considerable efforts to ensure that data exchanges can successfully pull or push many references in one operation. Ideally, a problem occurring with one specific reference in a list should not stop the whole operation. If a pull or push operation encounters an error, EPPI-Reviewer will try to show an error identifying (Item/document ID or Zotero Key) the records involved. The remaining items should complete the data exchange (push/pull) successfully.
If this happens, please take a note of the unique identifiers mentioned in the error, try again with those items, and if all else fails, please contact EPPI-Support.
The error message itself might provide a clue about what is failing and suggest what you could do to try and fix it. For example, if you are pushing items and an error mentions something like "[field name] is not present in [publication type]" you may want to try deleting the contents of the corresponding field in EPPI-Reviewer, and then try again. In all cases, even when you could work around the problem yourself, please contact EPPI-Support (we would want to know about all such errors so we can address the issue for future users. As usual, it's extremely useful to provide detailed information about the error, including the unique identifiers mentioned, the error text and, when possible, the time when the error occurred (it makes it easier for us to locate the corresponding data in our logs).
In some cases, the whole operation mail fail, and an "overall" message (which doesn't mention any unique identifiers) will be shown. Once again, if all "retry" attempts do fail, please contact EPPI-Support for assistance (and include as much details as possible).
A common error while pulling:
Sometimes, after attempting to pull some references into EPPI-Reviewer, an error similar to the one shown below will appear.
The error is designed to tell us (at the EPPI Centre) precisely what happened, so it can be obscure to everyone else. What this specific error indicates is that the attachment with ID VVWWXXZZ (attached to reference AABBCCDD) could not be pulled, because Zotero answered "404 (Not Found)" when EPPI Reviewer asked for it. This indicates that Zotero knows that the attachement VVWWXXZZ is associated to a given reference, but the attachment itself could not be found in the Zotero cloud.
There are a few reasons why this may happen, but the most frequent is that the online Storage Quota is full, which prevents to upload (sync) attachments from a local copy of the group library (what people see and use in their own computers) into the Zotero cloud. Thus, the group library will partially sync, adding to references the notion that they have an attachment, but without uploading the attachment(s), because there is no space for it/them. The same would also happen when a Sync operation from a "desktop" version of Zotero (towards the Zotero cloud) ended before completing.
In EPPI Reviewer, if/when trying to "Pull" Zotero references affected by this problem, the system will attempt to download such "notional" attachments, and fail (producing sometimes a long list of errors, one per failure).
What to do to resolve this depends on the root cause: if the sync didn't complete for lack of time (or similar) clicking on the Sync button in your Zotero client (wherever the desired attachments are indeed present) will solve the problem. Otherwise, you'd need to make space, as described in the following section.
Storage Quota issues:
Data contained in Zotero Group Libraries is stored on the Zotero Cloud. This includes the data describing references as well as the data used to store full-text documents. All Zotero accounts come with 300MB of "free" cloud storage space, which is a fair amount, but it is likely that users will eventually "run out of space". Unfortunately, the Zotero API does not provide a way to check how much space is available, which creates another know/predictable problem.
When running out of storage space, attempts to push data into the Group Library will fail with a specific error. Since EPPI-Reviewer cannot check in advance if the storage quota is about to be reached (only end-users can), such errors cannot be prevented on our end. More importantly, such errors cannot be stopped from occurring without either making space (deleting unneeded data on the Zotero end) or purchasing more Storage Space on the Zotero side. Zotero storage is relatively cheap and can be purchased from Zotero here.
When multiple review-members do use EPPI-Reviewer to push data into a Zotero Group Library, it is important to note that all the pushed data will be seen by Zotero as "belonging" to the key owner, and will thus contribute to the Storage Quota of that person alone. This can be confusing, but does also provide a possible third way of dealing with quota issues. We believe that doing the following would work to spread the load across multiple users:
- Log into EPPI-Reviewer as the "key owner" and on the Zotero/setup page Delete the Access Key.
- Then, log into EPPI-Reviewer on as a different (EPPI-Reviewer) user, re-connect the same Review to the same Group Library.
Any data pushed to Zotero from now on should count as contributing to the storage quota of the "different" user, who will hopefully have some more space available.
The "Rebuild" function: what is it for?
When pushing and pulling items/references, EPPI-Reviewer will need to "keep-track" of the reference status to know if a record needs be created or updated, and whether pulling or pushing a reference is appropriate. For example, if we push some items to Zotero, then edit one of them in EPPI-Reviewer, the system should allow you to push the item again as it is now "newer" on the EPPI-Reviewer end. Naturally, if we do push it once more, the system should update the existing reference in Zotero, instead of creating a new record.
To make this possible, EPPI-Reviewer stores the Unique Identifiers of records as pairs: one "ItemId" (unique identifier of EPPI-Reviewer Items) is stored along its corresponding "ZoteroKey" (unique identifier of Zotero records, including Zotero references).
EPPI-Reviewer uses the "modified dates" of "paired records" to establish which version is newer and thus determine what references can be pulled or pushed. It also detects deletions on the Zotero side, as users can delete references from their Group Library at any time. When a deletion is detected, EPPI-Reviewer will automatically delete the corresponding pair of unique identifiers, as there would be nothing to "keep track of", for the corresponding item.
A side effect of this process (the automatic deletion of unique identifier pairs) is that it is possible to "lose" the item/reference pairing data. For example, if the key owner goes to the "Setup" tab, deletes the Access Key, obtains a new Key that provides access to a different Group Library, then all the "previously known" pairs will become obsolete and will be deleted.
If the Key Owner then changes their mind and reverts the changes, linking the same review to the original Group library, the Items/References pairing data has been already deleted. Thus, all references in the Zotero Group Library will be seen as "new to EPPI-Reviewer" and "pulleable" and all (Included) items in EPPI-Reviewer will be considered as "new" to Zotero and thus "pusheable". This would be wrong and could easily lead to the creation of duplicate references on either side.
The rebuild button allows you to recover from such situations and relies entirely on Data stored in the Zotero references. In addition to storing the pairing data in the EPPI-Reviewer database, whenever a reference (and associated PDFs) is pulled or pushed for the first time, EPPI-Reviewer will add an "EPPI-Reviewer Id: xyz" tag to references and "attachments" (the associated PDFs, if any); moreover, for references, the same data is also added to the "Extra" field.
The "Rebuild" function thus uses the (EPPI-Reviewer) IDs stored on the Zotero side to rebuild the pairing data that went lost, thus "relearning" which reference corresponds to what across the two systems, as and when needed.
Please note: the rebuild function can only work if the "EPPI-Reviewer Id" tags (and lines in the Extra field) are not deleted and/or tampered with. Therefore, it is important not to delete or edit these tags and values on the Zotero side.
Data "translation" errors:
Zotero supports a wide range of reference types while EPPI-Reviewer has a more restricted range. Thus, when a reference is pulled into EPPI-Reviewer, the Zotero reference type might not exist in EPPI-Reviewer and will need to be matched to the most appropriate available type. In translating data from one reference type to another, any mismatch in fields could result in some data not being transferred.
As an example, Zotero types such as "Patent" and "Statute" do not have a corresponding type in EPPI-Reviewer and are imported/pulled as a "Generic" items. In transit, the data specifying the type of reference and the data contained in "special" fields that are present only in the Zotero reference type will be lost (for example, "Filing date" of "Patent" type can't be stored in EPPI-Reviewer, for lack of an adequate field, and doesn't get imported).
More importantly, if a reference makes a round-trip between applications (push-pull or pull-push) the data-loss could be "back propagated" to the "original" reference. We have made every effort to ensure this danger will rarely happen in practice, but it is possible when more obscure reference types are used.
Even when the same reference types exist in both applications, there may be difference in the individual fields. For example, books and books sections do not have a DOI field in Zotero while a DOI field will exist in EPPI-Reviewer.
For a detailed description of the known problems and limitations due to "translation issues" please consult the in-depth page.
In practice, if you should notice that data goes missing (or otherwise degrades) upon pushing or pulling, please contact EPPI-Support, preferably already mentioning exactly what doesn't work in detail. If possible, sending us a RIS file with one or more examples of references that fail to push/pull data would help us recreate the issue.