Add a new field for citation count (#13531)

SalvadorRomo · koppor · Salvador Romo · web-flow · commit d6858cb6c5c4 · 2025-07-21T12:48:35.000Z
* first changes

* partial change

* add fields to GUI

* finish change

* fix citation count identifier

* adding tests

* add more testing

* remove unwanted logic

* add entry to change log

* resolve comments

* resolve comments

* resolve conflicts

* enhance citation count change log

* enhance citation count change log

* change assertion style

* resolve conflicts

* resolve conflicts

* resolve conflicts

* resolve test errors

* resolve conflicts

* fix branch

* fix test

* remove unused class

* resolve comment

* Update CHANGELOG.md

Co-authored-by: Oliver Kopp &lt;kopp.dev@gmail.com&gt;

* resolve comments

* fix comments

* fix comments

* fix comments

* fix issues

* fix comments

* remove unused import

* fix comments

* fix test cases

* fix comments

* fix tests

* Fix space in fieldname

* Use "error" from server for notification of error

* Fix requires for xmlunit

* Ensure that streams are closed during test

* Fix test file

* Fix OpenRewrite

---------

Co-authored-by: Oliver Kopp &lt;kopp.dev@gmail.com&gt;
Co-authored-by: Salvador Romo &lt;salvadorromo@MacBook-Air-de-Salvador.local&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv
 
 ### Added
 
+- We added a field for the citation count field on the General tab. [#13477](https://github.com/JabRef/jabref/issues/13477)
 - We added automatic lookup of DOI at citation relations [#13234](https://github.com/JabRef/jabref/issues/13234)
 - We added focus on the field Link in the "Add file link" dialog. [#13486](https://github.com/JabRef/jabref/issues/13486)
 - We introduced a settings parameter to manage citations' relations local storage time-to-live with a default value set to 30 days. [#11189](https://github.com/JabRef/jabref/issues/11189)
diff --git a/build-logic/src/main/kotlin/org.jabref.gradle.base.dependency-rules.gradle.kts b/build-logic/src/main/kotlin/org.jabref.gradle.base.dependency-rules.gradle.kts
@@ -274,8 +274,9 @@ extraJavaModuleInfo {
     module("org.xmlunit:xmlunit-matchers", "org.xmlunit.matchers") {
         exportAllPackages()
         requires("java.logging")
-        requires("org.xmlunit")
+        requires("java.xml")
         requires("org.hamcrest")
+        requires("org.xmlunit")
     }
     module("org.xmlunit:xmlunit-placeholders", "org.xmlunit.placeholder")
 
diff --git a/jabgui/src/main/java/org/jabref/gui/fieldeditors/CitationCountEditor.java b/jabgui/src/main/java/org/jabref/gui/fieldeditors/CitationCountEditor.java
@@ -0,0 +1,84 @@
+package org.jabref.gui.fieldeditors;
+
+import javax.swing.undo.UndoManager;
+
+import javafx.fxml.FXML;
+import javafx.scene.Parent;
+import javafx.scene.control.Button;
+import javafx.scene.control.Tooltip;
+import javafx.scene.layout.HBox;
+
+import org.jabref.gui.DialogService;
+import org.jabref.gui.StateManager;
+import org.jabref.gui.autocompleter.SuggestionProvider;
+import org.jabref.gui.fieldeditors.contextmenu.DefaultMenu;
+import org.jabref.gui.preferences.GuiPreferences;
+import org.jabref.logic.citation.SearchCitationsRelationsService;
+import org.jabref.logic.integrity.FieldCheckers;
+import org.jabref.logic.l10n.Localization;
+import org.jabref.logic.util.TaskExecutor;
+import org.jabref.model.entry.BibEntry;
+import org.jabref.model.entry.field.Field;
+
+import com.airhacks.afterburner.injection.Injector;
+import com.airhacks.afterburner.views.ViewLoader;
+import jakarta.inject.Inject;
+
+public class CitationCountEditor extends HBox implements FieldEditorFX {
+    @FXML private CitationCountEditorViewModel viewModel;
+    @FXML private EditorTextField textField;
+    @FXML private Button fetchCitationCountButton;
+
+    @Inject private DialogService dialogService;
+    @Inject private GuiPreferences preferences;
+    @Inject private UndoManager undoManager;
+    @Inject private TaskExecutor taskExecutor;
+    @Inject private StateManager stateManager;
+    @Inject private SearchCitationsRelationsService searchCitationsRelationsService;
+
+    public CitationCountEditor(Field field,
+                             SuggestionProvider<?> suggestionProvider,
+                             FieldCheckers fieldCheckers) {
+        Injector.registerExistingAndInject(this);
+        this.viewModel = new CitationCountEditorViewModel(
+                field,
+                suggestionProvider,
+                fieldCheckers,
+                taskExecutor,
+                dialogService,
+                undoManager,
+                stateManager,
+                preferences,
+                searchCitationsRelationsService);
+
+        ViewLoader.view(this)
+                  .root(this)
+                  .load();
+
+        textField.textProperty().bindBidirectional(viewModel.textProperty());
+
+        fetchCitationCountButton.setTooltip(
+                new Tooltip(Localization.lang("Look up %0", field.getDisplayName())));
+        textField.initContextMenu(new DefaultMenu(textField), preferences.getKeyBindingRepository());
+        new EditorValidator(preferences).configureValidation(viewModel.getFieldValidator().getValidationStatus(), textField);
+    }
+
+    @FXML
+    private void fetchCitationCount() {
+        viewModel.getCitationCount();
+    }
+
+    public CitationCountEditorViewModel getViewModel() {
+        return viewModel;
+    }
+
+    @Override
+    public void bindToEntry(BibEntry entry) {
+        viewModel.bindToEntry(entry);
+    }
+
+    @Override
+    public Parent getNode() {
+        return this;
+    }
+}
diff --git a/jabgui/src/main/java/org/jabref/gui/fieldeditors/CitationCountEditorViewModel.java b/jabgui/src/main/java/org/jabref/gui/fieldeditors/CitationCountEditorViewModel.java
@@ -0,0 +1,74 @@
+package org.jabref.gui.fieldeditors;
+
+import java.util.Optional;
+
+import javax.swing.undo.UndoManager;
+
+import javafx.beans.property.BooleanProperty;
+import javafx.beans.property.SimpleBooleanProperty;
+
+import org.jabref.gui.DialogService;
+import org.jabref.gui.StateManager;
+import org.jabref.gui.autocompleter.SuggestionProvider;
+import org.jabref.gui.preferences.GuiPreferences;
+import org.jabref.logic.citation.SearchCitationsRelationsService;
+import org.jabref.logic.integrity.FieldCheckers;
+import org.jabref.logic.l10n.Localization;
+import org.jabref.logic.util.BackgroundTask;
+import org.jabref.logic.util.TaskExecutor;
+import org.jabref.model.entry.field.Field;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class CitationCountEditorViewModel extends AbstractEditorViewModel {
+    private static final Logger LOGGER = LoggerFactory.getLogger(CitationCountEditorViewModel.class);
+
+    protected final BooleanProperty fetchCitationCountInProgress = new SimpleBooleanProperty(false);
+    private final TaskExecutor taskExecutor;
+    private final DialogService dialogService;
+    private final UndoManager undoManager;
+    private final StateManager stateManager;
+    private final GuiPreferences preferences;
+    private final SearchCitationsRelationsService searchCitationsRelationsService;
+    public CitationCountEditorViewModel(
+            Field field,
+            SuggestionProvider<?> suggestionProvider,
+            FieldCheckers fieldCheckers,
+            TaskExecutor taskExecutor,
+            DialogService dialogService,
+            UndoManager undoManager,
+            StateManager stateManager,
+            GuiPreferences preferences,
+            SearchCitationsRelationsService searchCitationsRelationsService) {
+        super(field, suggestionProvider, fieldCheckers, undoManager);
+        this.taskExecutor = taskExecutor;
+        this.dialogService = dialogService;
+        this.undoManager = undoManager;
+        this.stateManager = stateManager;
+        this.preferences = preferences;
+        this.searchCitationsRelationsService = searchCitationsRelationsService;
+    }
+
+    public BooleanProperty fetchCitationCountInProgressProperty() {
+        return fetchCitationCountInProgress;
+    }
+
+    public boolean getFetchCitationCountInProgress() {
+        return fetchCitationCountInProgress.get();
+    }
+
+    public void getCitationCount() {
+        Optional<String> fieldContent = entry.getField(field);
+        BackgroundTask.wrap(() -> searchCitationsRelationsService.getCitationCount(this.entry, fieldContent))
+                      .onRunning(() -> fetchCitationCountInProgress.setValue(true))
+                      .onFinished(() -> fetchCitationCountInProgress.setValue(false))
+                      .onFailure(e -> {
+                          dialogService.notify(Localization.lang("Error occurred when getting citation count, please try again or check the identifier.\n\n%0", e.getLocalizedMessage()));
+                          LOGGER.error("Error while fetching citation count", e);
+                      })
+                      .onSuccess(identifier -> {
+                          entry.setField(field, String.valueOf(identifier));
+                      }).executeWith(taskExecutor);
+    }
+}
diff --git a/jabgui/src/main/java/org/jabref/gui/fieldeditors/FieldEditors.java b/jabgui/src/main/java/org/jabref/gui/fieldeditors/FieldEditors.java
@@ -75,6 +75,8 @@ public static FieldEditorFX getForField(final Field field,
         } else if (fieldProperties.contains(FieldProperty.IDENTIFIER) && field != StandardField.PMID || field == StandardField.ISBN) {
             // Identifier editor does not support PMID, therefore excluded at the condition above
             return new IdentifierEditor(field, suggestionProvider, fieldCheckers);
+        } else if (field == StandardField.CITATIONCOUNT) {
+            return new CitationCountEditor(field, suggestionProvider, fieldCheckers);
         } else if (field == StandardField.ISSN) {
             return new ISSNEditor(field, suggestionProvider, fieldCheckers, undoAction, redoAction);
         } else if (field == StandardField.OWNER) {
diff --git a/jabgui/src/main/java/org/jabref/gui/fieldeditors/identifier/IdentifierEditor.java b/jabgui/src/main/java/org/jabref/gui/fieldeditors/identifier/IdentifierEditor.java
@@ -45,7 +45,6 @@ public class IdentifierEditor extends HBox implements FieldEditorFX {
     @Inject private GuiPreferences preferences;
     @Inject private UndoManager undoManager;
     @Inject private StateManager stateManager;
-
     private Optional<BibEntry> entry = Optional.empty();
 
     public IdentifierEditor(Field field,
@@ -63,6 +62,7 @@ public IdentifierEditor(Field field,
                     this.viewModel = new ISBNIdentifierEditorViewModel(suggestionProvider, fieldCheckers, dialogService, taskExecutor, preferences, undoManager, stateManager);
             case EPRINT ->
                     this.viewModel = new EprintIdentifierEditorViewModel(suggestionProvider, fieldCheckers, dialogService, taskExecutor, preferences, undoManager);
+
             // TODO: Add support for PMID
             case null, default -> {
                 assert field != null;
diff --git a/jabgui/src/main/resources/org/jabref/gui/fieldeditors/CitationCountEditor.fxml b/jabgui/src/main/resources/org/jabref/gui/fieldeditors/CitationCountEditor.fxml
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<?import javafx.scene.control.Button?>
+<?import javafx.scene.control.ProgressIndicator?>
+<?import javafx.scene.control.Tooltip?>
+<?import javafx.scene.layout.HBox?>
+<?import javafx.scene.layout.StackPane?>
+<?import org.jabref.gui.fieldeditors.EditorTextField?>
+<?import org.jabref.gui.icon.JabRefIconView?>
+<fx:root xmlns:fx="http://javafx.com/fxml/1" type="HBox" xmlns="http://javafx.com/javafx/8.0.112"
+         fx:controller="org.jabref.gui.fieldeditors.CitationCountEditor">
+    <EditorTextField fx:id="textField" prefHeight="0.0" HBox.hgrow="ALWAYS"/>
+    <Button fx:id="fetchCitationCountButton" onAction="#fetchCitationCount" styleClass="icon-button">
+        <graphic>
+            <StackPane>
+                <JabRefIconView glyph="LOOKUP_IDENTIFIER"
+                                visible="${!controller.viewModel.fetchCitationCountInProgress}"/>
+                <ProgressIndicator maxHeight="12.0" maxWidth="12.0"
+                                   visible="${controller.viewModel.fetchCitationCountInProgress}"/>
+            </StackPane>
+        </graphic>
+    </Button>
+</fx:root>
diff --git a/jablib/src/main/java/org/jabref/logic/citation/SearchCitationsRelationsService.java b/jablib/src/main/java/org/jabref/logic/citation/SearchCitationsRelationsService.java
@@ -1,6 +1,7 @@
 package org.jabref.logic.citation;
 
 import java.util.List;
+import java.util.Optional;
 
 import org.jabref.logic.bibtex.FieldPreferences;
 import org.jabref.logic.citation.repository.BibEntryCitationsAndReferencesRepository;
@@ -83,6 +84,17 @@ public List<BibEntry> searchCitations(BibEntry cited) {
         return relationsRepository.readCitations(cited);
     }
 
+    public int getCitationCount(BibEntry citationCounted, Optional<String> actualFieldValue) throws FetcherException {
+        boolean isFetchingAllowed = actualFieldValue.isEmpty() ||
+                relationsRepository.isCitationsUpdatable(citationCounted);
+        if (isFetchingAllowed) {
+            Optional<Integer> citationCountResult = citationFetcher.searchCitationCount(citationCounted);
+            return citationCountResult.orElse(0);
+        }
+        assert actualFieldValue.isPresent();
+        return Integer.parseInt(actualFieldValue.get());
+    }
+
     public void close() {
         relationsRepository.close();
     }
diff --git a/jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/CitationFetcher.java b/jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/CitationFetcher.java
@@ -1,6 +1,7 @@
 package org.jabref.logic.importer.fetcher.citation;
 
 import java.util.List;
+import java.util.Optional;
 
 import org.jabref.logic.importer.FetcherException;
 import org.jabref.model.entry.BibEntry;
@@ -40,6 +41,14 @@ enum SearchType {
      */
     List<BibEntry> searchCiting(BibEntry entry) throws FetcherException;
 
+    /**
+     * Get the paper details that includes citation count field for a given {@link BibEntry}.
+     *
+     * @param entry entry to search citation count field
+     * @return returns a {@link Integer} for citation count field (may be empty)
+     */
+    Optional<Integer> searchCitationCount(BibEntry entry) throws FetcherException;
+
     /**
      * Returns the localized name of this fetcher.
      * The title can be used to display the fetcher in the menu and in the side pane.
diff --git a/jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/semanticscholar/SemanticScholarCitationFetcher.java b/jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/semanticscholar/SemanticScholarCitationFetcher.java
@@ -3,6 +3,7 @@
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.List;
+import java.util.Optional;
 
 import org.jabref.logic.importer.FetcherException;
 import org.jabref.logic.importer.ImporterPreferences;
@@ -13,6 +14,8 @@
 import org.jabref.model.entry.BibEntry;
 
 import com.google.gson.Gson;
+import kong.unirest.core.json.JSONObject;
+import org.jooq.lambda.Unchecked;
 import org.jspecify.annotations.NonNull;
 
 public class SemanticScholarCitationFetcher implements CitationFetcher, CustomizableKeyFetcher {
@@ -33,6 +36,12 @@ public String getAPIUrl(String entry_point, BibEntry entry) {
                 + "&limit=1000";
     }
 
+    public String getUrlForCitationCount(BibEntry entry) {
+        return SEMANTIC_SCHOLAR_API + "paper/" + "DOI:" + entry.getDOI().orElseThrow().asString()
+                + "?fields=" + "citationCount"
+                + "&limit=1";
+    }
+
     @Override
     public List<BibEntry> searchCitedBy(BibEntry entry) throws FetcherException {
         if (entry.getDOI().isEmpty()) {
@@ -84,6 +93,41 @@ public List<BibEntry> searchCitedBy(BibEntry entry) throws FetcherException {
                                  .map(referenceDataItem -> referenceDataItem.getCitedPaper().toBibEntry()).toList();
     }
 
+    @Override
+    public Optional<Integer> searchCitationCount(BibEntry entry) throws FetcherException {
+        if (entry.getDOI().isEmpty()) {
+            return Optional.empty();
+        }
+        URL referencesUrl;
+        try {
+            referencesUrl = URLUtil.create(getUrlForCitationCount(entry));
+        } catch (MalformedURLException e) {
+            throw new FetcherException("Malformed URL", e);
+        }
+        URLDownload urlDownload = new URLDownload(referencesUrl);
+        importerPreferences.getApiKey(getName()).ifPresent(apiKey -> urlDownload.addHeader("x-api-key", apiKey));
+        String result;
+        try {
+            result = urlDownload.asString();
+        } catch (FetcherException e) {
+            e.getHttpResponse().ifPresent(Unchecked.consumer(response -> {
+                Optional.ofNullable(response.responseBody())
+                        .map(JSONObject::new)
+                        .flatMap(json -> Optional.ofNullable(json.getString("error"))
+                                                 .map(Unchecked.function(error -> {
+                                                     throw new FetcherException(referencesUrl, error, e);
+                                                 })));
+            }));
+            throw e;
+        }
+        PaperDetails paperDetails = GSON.fromJson(result, PaperDetails.class);
+
+        if (paperDetails == null) {
+            return Optional.empty();
+        }
+        return Optional.of(paperDetails.getCitationCount());
+    }
+
     @Override
     public String getName() {
         return FETCHER_NAME;
diff --git a/jablib/src/main/java/org/jabref/model/entry/field/FieldFactory.java b/jablib/src/main/java/org/jabref/model/entry/field/FieldFactory.java
@@ -231,7 +231,7 @@ private static Set<Field> getAllFields() {
      * separate preferences object
      */
     public static List<Field> getDefaultGeneralFields() {
-        List<Field> defaultGeneralFields = new ArrayList<>(Arrays.asList(StandardField.DOI, StandardField.CROSSREF, StandardField.KEYWORDS, StandardField.EPRINT, StandardField.URL, StandardField.FILE, StandardField.GROUPS, StandardField.OWNER, StandardField.TIMESTAMP));
+        List<Field> defaultGeneralFields = new ArrayList<>(Arrays.asList(StandardField.DOI, StandardField.CITATIONCOUNT, StandardField.CROSSREF, StandardField.KEYWORDS, StandardField.EPRINT, StandardField.URL, StandardField.FILE, StandardField.GROUPS, StandardField.OWNER, StandardField.TIMESTAMP));
         defaultGeneralFields.addAll(EnumSet.allOf(SpecialField.class));
         return defaultGeneralFields;
     }
diff --git a/jablib/src/main/java/org/jabref/model/entry/field/StandardField.java b/jablib/src/main/java/org/jabref/model/entry/field/StandardField.java
@@ -136,6 +136,7 @@ public enum StandardField implements Field {
     // JabRef-specific fields
     GROUPS("groups"),
     OWNER("owner"),
+    CITATIONCOUNT("citationcount"),
     TIMESTAMP("timestamp", FieldProperty.DATE),
     CREATIONDATE("creationdate", FieldProperty.DATE),
     MODIFICATIONDATE("modificationdate", FieldProperty.DATE);
diff --git a/jablib/src/main/resources/l10n/JabRef_en.properties b/jablib/src/main/resources/l10n/JabRef_en.properties
@@ -311,6 +311,7 @@ Entry\ table\ columns=Entry table columns
 Entry\ Title\ (Required\ to\ deliver\ recommendations.)=Entry Title (Required to deliver recommendations.)
 Error=Error
 Error\ occurred\ when\ parsing\ entry=Error occurred when parsing entry
+Error\ occurred\ when\ getting\ citation\ count,\ please\ try\ again\ or\ check\ the\ identifier.\n\n%0=Error occurred when getting citation count, please try again or check the identifier.\n\n%0
 Error\ during\ persistence\ of\ crawling\ results.=Error during persistence of crawling results.
 '%0'\ exists.\ Overwrite\ file?='%0' exists. Overwrite file?
 Export=Export
diff --git a/jablib/src/test/java/org/jabref/logic/citation/SearchCitationsRelationsServiceTest.java b/jablib/src/test/java/org/jabref/logic/citation/SearchCitationsRelationsServiceTest.java
diff --git a/jablib/src/test/java/org/jabref/logic/citation/repository/BibEntryRelationsRepositoryTestHelpers.java b/jablib/src/test/java/org/jabref/logic/citation/repository/BibEntryRelationsRepositoryTestHelpers.java
diff --git a/jablib/src/test/java/org/jabref/logic/exporter/OpenOfficeDocumentCreatorTest.java b/jablib/src/test/java/org/jabref/logic/exporter/OpenOfficeDocumentCreatorTest.java
diff --git a/jablib/src/test/java/org/jabref/logic/importer/fetcher/citation/CitationFetcherHelpersForTest.java b/jablib/src/test/java/org/jabref/logic/importer/fetcher/citation/CitationFetcherHelpersForTest.java
diff --git a/jablib/src/test/java/org/jabref/logic/importer/fetcher/citation/semanticscholar/SemanticScholarCitationFetcherTest.java b/jablib/src/test/java/org/jabref/logic/importer/fetcher/citation/semanticscholar/SemanticScholarCitationFetcherTest.java
diff --git a/jablib/src/test/resources/org/jabref/logic/exporter/OldOpenOfficeCalcExportFormatContentSingleEntry.xml b/jablib/src/test/resources/org/jabref/logic/exporter/OldOpenOfficeCalcExportFormatContentSingleEntry.xml
