Enhanced Package Metadata and Search Capabilities for eHoldings App (UXPROD-5543)

Link: UXPROD-5543: eholdings app > Enhanced Package metadata and search capabilitiesIn RefinementPreview
Status: Analysis Complete | Priority: P3 | Reporter: Khalilah Gambrell
Labels: EFPM273, EFPM3, SI1, erm, resourcemanagement

Overview

EBSCO KB has been enhanced with more package metadata and search capabilities.
To take advantage of these, the team needs to upgrade applicable Package API endpoints in mod-kb-ebsco-java,
then expose these capabilities in the eHoldings UI.

Full Requirements (from UXPROD-5543)

1. Metadata Enhancements

• Granular visibility — Replace "Show titles in package to patrons" with three separate checkboxes:

  • Hide/Exclude in Publication Finder (PF)

  • Hide/Exclude in Full Text Finder (FTF)

  • Exclude from MARC export

• Managed description — Read-only field surfacing KB-managed description (markdown supported)

• Custom description — Editable WYSIWYG field (HTML supported, 2000 char limit, no script tags)

• Managed Alternate names — Read-only list of KB-managed alternate package names

• Custom Alternate names — Up to 10 user-defined alternate names (300 char limit each, plain text)

• Custom display name (Package Display Name) — Custom label for a package (300 char limit, plain text)

• Package Free Access — Read-only field: Public = True / Controlled = False

2. Search Enhancements

• Advanced search — Support new HoldingsIQ v2 advanced search capabilities

• Filter: Publication Finder — Show in / Hide in Publication Finder

• Filter: Full Text Finder — Show in / Hide in Full Text Finder

• Filter: MARC export — Include in / Exclude from MARC export

• Filter: Package Access — Public / Controlled

• Search by alternate & display names — Package search/sort should consider Custom Display Name and Custom/Managed Alternate Names (behavior driven by HoldingsIQ API)

3. Additional Updates

• Package Search Results list — Show Package Display Name in italics in parentheses next to package name; indicate hidden status

• Export — Add new fields (Display Name, Managed/Custom Alt Names, Managed/Custom Description, Package Access, Hide flags); remove "Show to patrons" field

• Create Custom Package — Support new fields (custom description, custom alt names) on the create form

• Multi-KB access (Non-ECS) — Allow users to access and switch between multiple KBs without changing Settings assignment

Tickets by Scope

✅ Done / Spike

🏗️ Foundation / Infrastructure BE Stories

These must be completed first — all other BE and UI work is blocked on them.

Dependency chain:

🔵 Backend (BE) Stories

🟢 Frontend (UI) Stories

🎨 UX / Design Stories

Work Split Summary

Stories requiring both BE and UI teams

Stories BE-only

(No UI changes required beyond what's driven by data availability)

• AE-8 — New fields on POST /eholdings/packages endpoint (the UI create-form stories AE-14, AE-15 consume this)

Stories UI-only / Testing-only

• AE-16 — Testing-only story: validates HoldingsIQ search behavior by display name/alt names. No code change required, just test coverage.

BE Requirements Detail

FHIQC-49 — HoldingsIQ Client Library: v2 Migration (folio-holdingsiq-client)

Blocking dependency for all downstream BE work.

• Migrate endpoint URLs to /v2/ prefix; replace packages path segment with lists

• Update individual package operations: retrievePackage(), retrievePackages(), updatePackage(), deletePackage() in PackagesHoldingsIQServiceImpl

• Handle new listId parameter (was {vendorid}/{packageid}, now {packageid} = listId); maintain backward-compat mapping in PackageData

• Refactor visibility model:

  • Remove: VisibilityInfo visibilityData

  • Add: List<VisibilityItem> visibility where VisibilityItem has:

    • VisibilityCategory category — enum: PF, FTF, MARC

    • Boolean hidden

    • String reason

• Update PackagesFilterableUrlBuilder to support v2 patterns

• Bump major version of the library (breaking changes)

• Update unit tests; add tests for new visibility structure

MODKBEKBJ-804 — mod-kb-ebsco-java: Integrate Updated HoldingsIQ Client

Blocked by FHIQC-49. Blocking dependency for AE-8 and all field-level BE stories.

• Update PackagesHoldingsIQService usage for v2 endpoints

• Implement data transformation between v2 models and existing FOLIO package representations

• Handle packageId ↔ listId mapping transparently throughout the module

• Handle new List<VisibilityItem> visibility array structure in package processing

• Preserve FOLIO-specific filtering (tags, access types), existing validation and error handling

• Bump major version of the module interface; keep changes in a feature branch to avoid breaking consumers

AE-8 — POST /eholdings/packages new fields

• customDescription — string, max 2000 chars, HTML/markdown supported (no script tags)

• customDisplayName — string, max 300 chars, plain text only

• customAltNames — array of strings, max 10 items, each max 300 chars, plain text only

• packageFreeAccess — boolean (true = Public, false = Controlled)

AE-17 — Export additions

Remove from export:

• Show to patrons field

Add to export:

AE-7 — Multi-KB (Non-ECS)

• Allow multiple EBSCO KBs to be assigned to a user

• No Settings reassignment required to switch KB

• KB selection must be sticky (persisted)

• App must display which KB is currently active

• Define permission model for secondary KBs

UI Requirements Detail

AE-9 + AE-14 — Custom Alternate Package Names (View/Edit/Create)

• Section: Package Settings accordion

• Field type: Repeatable text box

• Max entries: 10; disable add button + show tooltip when limit reached

• Character limit: 300 per entry; inline error if exceeded

• Validation: No HTML/markdown; inline error if detected

• View mode: Semi-colon separated list; dash if empty

AE-10 — Granular Visibility (View/Edit)

• Replace "Show titles in package to patrons" with header "Hide/exclude all titles in the package"

• Checkboxes:

  • In Publication Finder

  • In Full Text Finder

  • In MARC export

• Action applies to all titles in the package

• Applies to: Managed Package edit/view, Custom Package edit/view

AE-11 — Managed Fields (View/Edit Managed Package only)

• Package Information accordion:

  • Package access — read-only; always has a value (Public/Controlled); shown last; dash if empty

• Package Settings accordion:

  • Managed alternate names — read-only; semicolon-separated; dash if empty

  • Managed description — read-only; markdown rendered; dash if empty

• These fields must not appear on Custom Package records

AE-12 — Package Display Name (View/Edit)