Zotero is a free open-source reference manger, which is widely used because of it richness of functionalities, and its availability to all potential users.
It also has an API that allows third parties to exchange data with it making it an ideal match for integration with EPPI-Reviewer. By connecting Zotero with EPPI-Reviewer you can use Zotero to locate and upload full text documents to your review as well make use of the Zotero "Cite While You Write" functionality.
In these pages you will find resources and guidance on how to use it, including a quick-start guide (below), "general warnings", some hints re the "recommended use-cases" (also below), troubleshooting (page 2), and an in-depth page (page 3).
You can find a short video on using Zotero with EPPI Reviewer here.
Quick Start Guide
Zotero is, at its core, a desktop application, meaning that by default, its data is stored inside the computer where it is installed. To accommodate groups of users with multiple devices, Zotero has created a "cloud component" called Group Libraries, which are accessible to multiple people using multiple devices. Since most work in EPPI-Reviewer happens within shared reviews, Zotero Group Libraries are a natural "destination" of data-exchanges as they permit "multi-user" access for both applications.
In order to use the EPPI-Reviewer/Zotero integration, you will need to have a Zotero account (can be created here) and then create one Zotero Group Library. Having a Zotero account and a group library, you will be able to obtain an "Access Key" which EPPI-Reviewer will use on your behalf to exchange data between one EPPI-Reviewer Review and one Zotero Group Library. Should you want to connect more reviews you will need to create additional group libraries, as EPPI-Reviewer enforces the one-to-one correspondence between reviews and libraries. You will also be able to control which Zotero users have access to what group library. Once the connection is set up, all regular EPPI-Reviewer review members will be able to exchange data with the chosen Group Library.
Setting up Zotero:
- If you have not done so already, Create a Zotero Account, then download and install Zotero on your preferred devices.
- Create one Group Library.
- We recommend giving the library a unique name that clearly identifies the review it will be used for.
- We also recommend to create private group libraries so your data is not publicly visible.
- In terms of permissions, since you will be controlling who can access it (on the Zotero end), the "Any group member can edit" setting appears to be a good starting point.
- Login into EPPI-Reviewer Web, open the review and click on the Zotero button. This opens the Zotero page, which will show detailed instructions on how to link the current review to an existing Zotero Group Library.
- Following the on-screen instructions, you will be redirected to the Zotero pages, where you'll pick the options to produce an Access Key.
- It's important to pick the minimum necessary security settings for the Key: you want to authorise Read and Write access to the chosen Group Library and only the chosen library.
- In EPPI-Reviewer, the setup page includes "Show me (new tab)" buttons with instructions on how to do so, which open in a new tab so they can be are viewable while you are operating on the Zotero pages.
- Once the Access Key settings are chosen, clicking "Save key" will re-direct you back to EPPI-Reviewer. If the settings meet the minimum requirements (i.e. the key does provide read and write access to at least one Group Library) you will automatically see the "(Zotero) Sync" page. This means the setup is finished and validated.
At this point, your review will be linked to your Group Library and you can start exchanging data between the two systems.
Moving data: push and pull.
EPPI-Reviewer reviews can (and often do) contain tens of thousands references or more (millions, in some cases). Zotero has never been written to handle such big datasets and is likely to start malfunctioning (or be very slow) if people started using its cloud component to store too many references. As well, the Zotero free access is limited to 300 MB so there are physical limits to stop you from sharing too many references. To stay responsive, EPPI-Reviewer does not provide a single "sync" function, which would move and keep-in-sync all references within a review. Instead it allows you to push and pull references between the two systems, while keeping track of the reference status in each application.
Pushing References: this refers to the action that moves data from EPPI-Reviewer to the Zotero Group Library.
To push references, you need to select a code from the on-screen drop-down menu to list the (included) items with the chosen code. You can then decide to select the individual references to push, or push all of the selectable references listed.
Pulling References: this refers to the opposite action, where data moves from Zotero into EPPI-Reviewer.
The system automatically displays all references present in the Zotero library and allows you to pull selected references or to pull all of the selectable references listed. A reference will be selectable if it is not already in EPPI-Reviewer or has been edited more recently than the reference in EPPI-Reviewer.
When pulling references, EPPI-Reviewer will create new references in the review, when appropriate, and group them in individual sources (one source per "pull" action); otherwise, references that are already "known" on both ends will be updated in EPPI-Reviewer (when pulled).
Both lists ("items with this code" on the left and references in the Zotero library on the right) will include a visual indication of the state of each reference, distinguishing whether a reference can be pushed, pulled, or is up-to-date on both ends. This "reference state" is computed on the basis of the "last modified" date of references on both sides. Pushing and pulling references which have one or more full text documents uploaded/attached will also transfer the full text documents, if they are not already present in the destination.
The lists are "paged" (users can change the page size) and can be sorted in multiple ways, to help identify individual references. It's also possible to show/hide a limited number of fields, for the same purpose.
It is possible that a Group Library may contain "extra references" that might not belong to the review so it is very important to pay attention to what references are being pull from Zotero. If unwanted references are pulled into EPPI-Reviewer it is possible to permanently delete the new source in EPPI-Reviewer but this might not always be practical as the source could contain both wanted and unwanted references. A similar warning may apply to "pushing" but since we can't really predict in what ways you'll be using the Zotero library data, it might not be of the same concern.
Zotero supports a wide range of reference types while EPPI-Reviewer has a more restricted range. This means that 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 be transferred. 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.
Finally, the Zotero API is officially subject to change which could break, without warning, the way Zotero and EPPI-Reviewer exchange data. Although we will try to fix any issues as quickly as possible, depending on the complexity of the fix, there may be times when the Zotero / EPPI-Reviewer functions are unavailable.
For more details, see the in-depth discussion. For hints on how to resolve problems, see the troubleshooting page.
At the present time there are two main use cases, which are fully supported and should be ready to use.
Using Zotero to find the "full text" documents.
In this use-case, after screening on title and abstract, you can push data to the Zotero Group Library, use the "Find available PDF" function in Zotero, and then pull the results back in EPPI-Reviewer. Here is how:
- Start by making sure your Group Library contains no references. This is useful to ensure you won't risk importing unneeded references later on.
- In the EPPI-Reviewer Zotero page, list "Items with this code", picking the code(s) that contain the included items after screening on title and abstract.
- Push all these items into the Group Library.
- In Zotero, use the built-in "Find available PDF" function for all references in the library.
- (Optional) Use other strategies to locate the full-text documents, and attach them to your references in Zotero.
- (Optional) You may also edit your references in Zotero, at this point. If you do so, your changes will be "re-imported" into EPPI-Reviewer at the next step.
- Pull all references back into EPPI-Reviewer. This will update the references you pushed in step 3, adding all of the PDFs you attached in steps 4 and 5, and updating the item records with any edits that you made.
Using Zotero to "Cite While You Write" (CWYW)
In this use-case, after "finishing" the work inside EPPI-Reviewer, you may want to use Zotero "Cite While You Write" features with access to the included references, for the purpose of writing the review report(s). You can do this as follows:
- Start by making sure your Group Library contains only the references you know are relevant to your report. This can be done by making sure your group library is empty and then following steps 2 and 3.
- In the EPPI-Reviewer "Zotero" page, list "Items with this code", picking the code(s) that contain the items you want to work with.
- Push all of the relevant items into the Group Library.
- (Optional) If the report will be written collaboratively, ensure your collaborators have access to the Group Library.
- (Optional) You can otherwise use the group library as a "stepping stone" and move/copy the references into whichever Zotero library (shared or personal) would suit your needs.
- You can now use the Zotero CWYW functions while having access to all Included/Relevant studies in your review.