Skip to content

feat(packages): add subjects major headings facet to packages search - #724

Merged
viacheslavkol merged 7 commits into
masterfrom
MODKBEKBJ-850
Oct 20, 2026
Merged

viacheslavkol merged 7 commits into
masterfrom
MODKBEKBJ-850

Conversation

@viacheslavkol

@viacheslavkol viacheslavkol commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Purpose

Packages search needs to display a "Subjects - Major headings" facet so users can narrow packages by subject. This change adds the facet to the packages search response and a filter to apply selected subjects.

Approach

  • GET /eholdings/packages gets an optional repeatable filter[subject] query parameter. It is declared as string[] and each value must be an integer subject id. RMB passes list query parameters as raw strings whatever element type the RAML declares, so the values are validated in PackageFilterValidator (a new entry in its VALIDATORS table, non-numeric values return 400) and converted to integers in PackageRecordFilter.toClientFilter.
  • GET /eholdings/packages gets an optional subjectFacetCount query parameter. When it is not provided, null is passed to the HoldingsIQ client, which then uses its own default (1000).
  • The subject facet is always requested from HoldingsIQ (facetstoinclude=subject) for GET /eholdings/packages, so facets are returned whenever HoldingsIQ has them. The provider packages endpoint does not request facets.
  • The response gets an optional facets.subjects field. A new packageFacets.json holds it (the shared facets.json is untouched, because titles have no subjects). PackageFacetsConverter keeps only major headings (no parentId) that have a positive count, skips null entries, passes counts through unchanged and orders them by count descending.
  • filter[subject] is treated like the other HoldingsIQ filters (e.g. filter[custom]): it is part of PackageRecordFilter.searchCriteriaValues(), so a request with filter[tags] or filter[access-type] plus filter[subject] goes to HoldingsIQ instead of the database path, and the tags/access type are ignored in that case, as they already are for q, filter[custom] and filter[selected].
  • FilterValidatorLogic is now generic over the validated parameter type so that list parameters can use the same validation table. PackageFilterValidator skips validation only for requests that actually take the database (tags / access type) path.
  • Adds AGENTS.md with guidance for AI coding agents.

Changes Checklist

  • API Changes: GET /eholdings/packages gets the optional filter[subject] and subjectFacetCount query parameters and an optional facets.subjects response field (ramls/packages.raml, ramls/types/packages/packageCollection.json, ramls/types/packages/packageFacets.json, ramls/types/packages/subjectFacet.json).
  • Database Schema Changes: Not applicable.
  • Interface Version Changes: None. eholdings stays at 5.0: the major bump from 4.0 (last release v7.0.2) is already part of the unreleased 8.0.0, and the new parameters and field are additive.
  • Interface Dependencies: No changes.
  • Permissions: No changes.
  • Logging: No changes.
  • Unit Testing: New PackageFacetsConverterTest and PackageRecordFilterTest; extended PackageCollectionResultConverterTest and EholdingsPackagesImplTest.
  • Integration Testing: EholdingsPackagesIntegrationTest covers the facet response and the subjectfilter / subjectfacetcount sent to HoldingsIQ, the always-requested facet, filter[subject] combined with filter[tags], and 400 responses for invalid filter[subject] (parameterized together with the filter[custom] validation cases).
  • Manual Testing: Tested against HoldingsIQ; this is where the AND behaviour of repeated filter[subject] values was found (see below).
  • NEWS: Updated with the new feature.

Notes for reviewers

  • Repeated filter[subject] values combine with AND, not OR. The ticket (AC5) describes OR. HoldingsIQ returns only packages that have all the selected subjects, so the RAML description states AND semantics. This needs a decision on the ticket / with the UI (UIEH-1549) if OR is required.
  • AC3 (facet data only with a search term or filter) is not enforced in this module: the facet is requested on every GET /eholdings/packages call and the result depends on what HoldingsIQ returns. When HoldingsIQ returns no facets, facets is omitted from the response.
  • AC4 (cap of 1000): the cap is the client's default subjectfacetcount, which can be overridden by the new subjectFacetCount parameter. There is no additional cap in this module.
  • AC6: the facet comes from the same HoldingsIQ call as the package list, so a HoldingsIQ failure or timeout fails the whole packages search through the existing error handling, not just the facet.
  • The subjectfilter values are sent to HoldingsIQ comma-separated by folio-holdingsiq-client (subjectfilter=1,2), while the ticket examples repeat the parameter.

Related Issues

🤖 Generated with Claude Code

Add filter[subject] query parameter to GET /eholdings/packages and return a facets.subjects list (major headings only, ordered by count descending) in the packages collection response. The facet is requested from HoldingsIQ only when a query or filter is present. Non-numeric filter[subject] values are rejected with 400. Bump eholdings interface to 5.1.

Refs: MODKBEKBJ-850
@viacheslavkol viacheslavkol self-assigned this Oct 20, 2026
@viacheslavkol
viacheslavkol marked this pull request as ready for review October 20, 2026 10:04
@viacheslavkol
viacheslavkol requested a review from a team as a code owner October 20, 2026 10:04
Comment thread AGENTS.md Resolved
Comment thread AGENTS.md Resolved
@viacheslavkol
viacheslavkol requested a review from psmagin October 20, 2026 11:11
@sonarqubecloud

Copy link
Copy Markdown

@viacheslavkol
viacheslavkol merged commit ddaaff1 into master Oct 20, 2026
18 checks passed
@viacheslavkol
viacheslavkol deleted the MODKBEKBJ-850 branch October 20, 2026 12:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants