Refactor of GetDigitalSpecimenComplete service and setup of data mapper to UI

.github/workflows/.trivyignore

@@ -21,4 +21,7 @@ CVE-2026-33671
 
 # Vulnerability in image dependency libpng that is included in the image and we cannot fix Apr-1-2026
 CVE-2026-33416
-CVE-2026-33636
+CVE-2026-33636
+
+# lodash-es is pinned as a dependency on a vulnerable version in formik and cannot be upgraded by us Apr-3-2026
+CVE-2026-4800

package.json

@@ -36,15 +36,15 @@
     "cytoscape": "3.30.4",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0",
-    "formik": "^2.4.6",
+    "formik": "^2.4.9",
     "i18next": "^24.0.5",
     "intro.js": "^7.2.0",
     "intro.js-react": "^1.0.0",
     "json-schema-to-typescript": "^15.0.3",
     "jsonpath": "^1.1.1",
     "keycloak-js": "^26.0.7",
     "leaflet": "^1.9.4",
-    "lodash": "^4.17.21",
+    "lodash": "^4.18.1",
     "moment": "^2.30.1",
     "msw": "^2.6.7",
     "openseadragon": "^5.0.0",

src/hooks/useDigitalSpecimen.ts

@@ -0,0 +1,24 @@
+import { useQuery } from '@tanstack/react-query';
+import { getDigitalSpecimenComplete } from 'services/digitalSpecimenService/getDigitalSpecimenComplete';
+import { mapDigitalSpecimen } from 'utils/DataMappers/digitalSpecimenDataMapper';
+
+/* Base constants */
+const staleTime = 1000 * 60 * 5; // How long until the time is stale
+const gcTime = 1000 * 60 * 10; // Cache time: How long to store it in the cache
+
+/* useQuery hook to retrieve the complete Digital Specimen data object by calling the getDigitalSpecimenComplete service */
+export const useDigitalSpecimenComplete = ({ handle, version }:
+    { handle: string, version?: number }) => {
+    return useQuery({
+        queryKey: ['digitalSpecimen', handle, version],
+        queryFn: () => getDigitalSpecimenComplete({ handle, version }),
+        select: (data) => {
+            return {
+                ...data,
+                ...mapDigitalSpecimen(data),
+            }
+        },
+        staleTime,
+        gcTime
+    });
+};

src/services/digitalSpecimenService/getDigitalSpecimenComplete.ts

@@ -0,0 +1,40 @@
+import apiClient from '../apiClient';
+
+/**
+ * Service that retrieves the complete digital specimen details through the apiClient
+ * Takes handle and version as a parameter object
+ * @returns An array with complete digital specimen data on specimen, media and annotations
+ */
+export const getDigitalSpecimenComplete = async ({ handle, version }:
+    { handle: string, version?: number }) => {
+    let endPoint: string;
+
+    if (version) {
+        endPoint = `digital-specimen/v1/${handle}/${version}/full`;
+    } else {
+        endPoint = `digital-specimen/v1/${handle}/full`;
+    }
+    try {
+        /* Call service and wait for response */
+        const response = await apiClient.get(endPoint, {
+            params: {
+                handle,
+                version
+            }
+        });
+
+        /* Throw error if response is not as expected */
+        if(!response.data?.data) {
+            throw new Error('Incorrect response format');
+        }
+
+        /* Return response data */
+        return response.data;
+    } catch (error) {
+        /* If error, throw error with generic error message */
+        console.error('Error fetching the digital specimen:', error);
+
+        /* Rethrow error for useQuery */
+        throw error;
+    }
+}

src/utils/DataMappers/digitalSpecimenDataMapper.ts

@@ -0,0 +1,47 @@
+/* Import schemas */
+import DIGITAL_SPECIMEN_SCHEMA_MAP from "./schemas/DigitalSpecimenSchema";
+
+/* Import types */
+import { DigitalSpecimenUIModel, SchemaMap, UIProperty } from "./types/dataMapperTypes";
+
+/**
+ * Function to get the accepted identification or the first one it can find
+ * @param ds The digital specimen object
+ * @returns Either the accepted identification or, if there is none, the first identification it can find
+ */
+const getAcceptedIdentification = (ds: any) => {
+    const identifications = ds["ods:hasIdentifications"];
+    if (identifications) {
+        const availableIdentification = identifications.find((item: any) => item["ods:isVerifiedIdentification"]) || identifications[0];
+        return availableIdentification?.["ods:hasTaxonIdentifications"]?.[0];
+    }
+}
+
+/**
+ * Transforms raw Digital Specimen data into a UI-ready model 
+ * based on the DIGITAL_SPECIMEN_SCHEMA_MAP definitions.
+ * It is executed in the useDigitalSpecimen hook immediately when the call is being done.
+ */
+export const mapDigitalSpecimen = (rawData: any): DigitalSpecimenUIModel | null => {
+    const ds = rawData?.data?.attributes?.digitalSpecimen;
+    if (!ds) return null;
+
+    /* Find acceptedIdentification or second best option */
+    const acceptedIdentification = getAcceptedIdentification(ds);
+
+    return Object.entries(DIGITAL_SPECIMEN_SCHEMA_MAP as SchemaMap).reduce((accumulator, [groupKey, fields]) => {
+        const mappedFields: Record<string, UIProperty> = {};
+
+        Object.entries(fields).forEach(([fieldKey, config]) => {
+            mappedFields[fieldKey] = {
+                label: config.label,
+                value: config.resolve(ds, acceptedIdentification),
+                isHtml: !!config.isHtml,
+                type: config.type || 'base',
+            };
+        });
+
+        accumulator[groupKey as keyof DigitalSpecimenUIModel] = mappedFields;
+        return accumulator;
+    }, {} as DigitalSpecimenUIModel);
+};

src/utils/DataMappers/schemas/DigitalSpecimenSchema.ts

@@ -0,0 +1,143 @@
+import { FieldConfig } from "../types/dataMapperTypes";
+
+/* Data schema to map Digital Specimen data that we use in the UI, managed from one central data mapper */
+const DIGITAL_SPECIMEN_SCHEMA_MAP: Record<string, Record<string, FieldConfig>> = {
+    SPECIMEN_RECORD: {
+        doi: {
+            label: 'DOI',
+            resolve: (ds) => ds["@id"],
+            type: 'copy'
+        },
+        catalogNumber: {
+            label: 'Catalog Number',
+            resolve: (ds) => {
+                const catalog = ds["ods:hasIdentifiers"]?.find((id: any) => id["dcterms:title"] === "dwc:catalogNumber");
+                const fallBack = ds["ods:hasIdentifiers"]?.find((id: any) => id["dcterms:title"] === "dwca:ID");
+                return catalog?.["dwc:catalogNumber"] || fallBack?.["dwca:id"];
+            }
+        },
+        specimenProvider: {
+            label: 'Specimen Provider',
+            resolve: (ds) => ds["ods:organisationName"]
+        },
+        sourceSystem: {
+            label: 'Source System',
+            resolve: (ds) => ds["ods:sourceSystemName"]
+        },
+        basisOfRecord: {
+            label: 'Basis of Record',
+            resolve: (ds) => ds["dwc:basisOfRecord"]
+        },
+        discipline: {
+            label: 'Discipline',
+            resolve: (ds) => ds["dwc:topicDiscipline"]
+        }
+    },
+
+    IDENTIFICATION: {
+        scientificName: {
+            label: 'Scientific Name',
+            isHtml: true,
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["ods:scientificNameHTMLLabel"] || acceptedIdentification?.["dwc:scientificName"]
+        },
+        taxonomicStatus: {
+            label: 'Taxonomic Status',
+            type: 'url',
+            resolve: (_, { acceptedIdentification: acc }) => acc?.["@id"]
+        },
+        verbatimName: {
+            label: 'Identification Verbatim',
+            type: 'verbatim',
+            resolve: (ds) => ds["ods:hasIdentifications"]?.[0]?.["dwc:verbatimIdentification"]
+        },
+        kingdom: {
+            label: 'Kingdom',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:kingdom"]
+        },
+        phylum: {
+            label: 'Phylum',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:phylum"]
+        },
+        class: {
+            label: 'Class',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:class"]
+        },
+        order: {
+            label: 'Order',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:order"]
+        },
+        family: {
+            label: 'Family',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:family"]
+        },
+        subFamily: {
+            label: 'Sub-family',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:subfamily"]
+        },
+        genus: {
+            label: 'Genus',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:genus"]
+        },
+        species: {
+            label: 'Species',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:species"]
+        },
+        specificEpithet: {
+            label: 'Specific Epithet',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:specificEpithet"]
+        },
+        nomenClaturalCode: {
+            label: 'Nomen/Clatural Code',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:nomenclaturalCode"]
+        },
+        scientificNameAuthorship: {
+            label: 'Scientific Name Authorship',
+            resolve: (_, { acceptedIdentification }) => acceptedIdentification?.["dwc:scientificNameAuthorship"]
+        },
+    },
+
+    LOCATION: {
+        country: {
+            label: 'Country',
+            resolve: (_, { primaryEvent: ev }) => ev?.["ods:hasLocation"]?.["dwc:country"]
+        },
+        locality: {
+            label: 'Locality',
+            resolve: (_, { primaryEvent: ev }) => ev?.["ods:hasLocation"]?.["dwc:locality"]
+        },
+        verbatimLocality: { 
+            label: 'Locality Verbatim', 
+            type: 'verbatim',
+            resolve: (_, { primaryEvent: ev }) => ev?.["ods:hasLocation"]?.["dwc:verbatimLocality"],
+        },
+        geodeticDatum: {
+            label: 'Geodetic Datum',
+            resolve: (_, { primaryEvent: ev }) => ev?.["ods:hasLocation"]?.["dwc:geodeticDatum"]
+        }
+    },
+
+    COLLECTING_EVENT: {
+        collector: {
+            label: 'Collector',
+            resolve: (_, { primaryEvent: ev }) => ev?.["ods:hasAgents"]?.[0]?.["schema:name"]
+        },
+        date: {
+            label: 'Date',
+            resolve: (_, { primaryEvent: ev }) => ev?.["dwc:eventDate"]
+        },
+        verbatimDate: {
+            label: 'Date verbatim',
+            resolve: (_, { primaryEvent: ev }) => ev?.["dwc:verbatimEventDate"],
+            type: 'verbatim'
+        }
+    },
+
+    CITATION_LICENSE: {
+        license: {
+            label: 'License Agreement',
+            resolve: (ds) => ds["dcterms:license"]
+        }
+    }
+};
+
+export default DIGITAL_SPECIMEN_SCHEMA_MAP;

src/utils/DataMappers/types/dataMapperTypes.ts

@@ -0,0 +1,38 @@
+/* MapperContext to set the context of the data, e.g. acceptedIdentification */
+interface MapperContext {
+    acceptedIdentification?: any;
+    primaryEvent?: any;
+}
+
+/* UI Property interface to map data to */
+interface UIProperty {
+    label: string;
+    value: any;
+    isHtml: boolean;
+    type: string;
+}
+
+/* Corresponding field config interface for DigitalSpecimen schema */
+interface FieldConfig {
+    label: string;
+    resolve: (ds: any, context: MapperContext) => any;
+    isHtml?: boolean;
+    type?: string;
+}
+
+/* Result of the Digital Specimen data mapper */
+interface DigitalSpecimenUIModel {
+    SPECIMEN_RECORD: Record<string, UIProperty>;
+    IDENTIFICATION: Record<string, UIProperty>;
+    LOCATION: Record<string, UIProperty>;
+    COLLECTING_EVENT: Record<string, UIProperty>;
+    CITATION_LICENSE: Record<string, UIProperty>;
+}
+
+/* Generic map to handle schemas for the digitalSpecimenUIModel */
+type SchemaMap = {
+    [Key in keyof DigitalSpecimenUIModel]: Record<string, FieldConfig>;
+};
+
+export type { UIProperty, FieldConfig, DigitalSpecimenUIModel, SchemaMap };
+