Bug 32313

Summary: Complete database column descriptions for cataloguing module in guided reports
Product: Koha Reporter: Katrin Fischer <katrin.fischer>
Component: I18N/L10NAssignee: David Nind <david>
Status: Needs Signoff --- QA Contact: Testopia <testopia>
Severity: minor    
Priority: P5 - low CC: david, f.demians
Version: MainKeywords: Academy
Hardware: All   
OS: All   
Change sponsored?: --- Patch complexity: ---
Documentation contact: Documentation submission:
Text to go in the release notes:
This fixes some column descriptions used in guided reports. It: - Adds missing descriptions for the items and biblioitems tables (used by the Circulation, Catalog, Acquisitions, and Serials modules) - Updates some column descriptions to make them more consistent or clearer.
Version(s) released in:
Bug Depends on: 29695, 32292    
Bug Blocks:    
Attachments: Bug 32313: Update guided reports column descriptions for items and biblioitems tables

Description Katrin Fischer 2022-11-21 22:27:46 UTC
There are entries missing for the biblioitems table.
Bug 32292 takes care of missing entries in biblio and items.

How to test:
* Add a new guided report
* Select module catalog
* Verify that statistics is missing some descriptions, only showing the database value
Comment 1 David Nind 2022-12-05 01:26:07 UTC
There are a couple of columns I'm not sure about for this.

Columns with no descriptions
============================

biblioitems.ean
biblioitems.collectiontitle
biblioitems.collectionissn
biblioitems.collectionvolume
biblioitems.editionstatement
biblioitems.editionresponsibility 
biblioitems.cn_source
biblioitems.cn_class
biblioitems.cn_item
biblioitems.cn_suffix
biblioitems.cn_sort
biblioitems.totalissues

Column descriptions I have identified
=====================================

I've identified these ones, and a reasonably comfortable with them - notes are in brackets and footnotes (these won't be included as part of the column description).

biblioitems.ean => EAN
biblioitems.collectiontitle => Series statement [1]
biblioitems.collectionissn => Series ISSN [2]
biblioitems.editionstatement => Edition statement (250$a) [3]
biblioitems.cn_source => Source of classification/shelving scheme (942$2) [3][4]
biblioitems.cn_class => Classification part (942$h) [3]
biblioitems.cn_item => Item part (942$i) [3]
biblioitems.cn_suffix => Call number suffix (942$m) [3]
biblioitems.cn_sort => Koha normalized classification for sorting (942$6) [3] [5]
biblioitems.totalissues => Total checkouts (942$0) [3] [6]

[1] Could reword as "Series title"
[2] See BugĀ 29635 - Map biblioitems.collectionissn to 490$x by default (MARC21)
[3] Description from Koha to MARC mappings
[4] Description from 942$2 is "Source of classification or shelving scheme", have used the same as the items table.
[5] The items table uses "Koha normalized classification for sorting", so have kept the same for consistency.
[6] Name used in Koha to MARC mappings is "Koha issues (borrowed), all copies". Have used the same description used for items.

Columns I am not sure about
===========================

I'd welcome some information on these items.

I couldn't figure out where these came from - which just reflects my limited MARC and Koha reporting knowledge!

biblioitems.collection*
~~~~~~~~~~~~~~~~~~~~~~

I've mapped collectiontitle and collectionissn as above, however I noted using a git grep search that for UNIMARC:
- 225$a Series title: is mapped to field biblioitems.collectiontitle
- 225$v Volume Designation: is mapped to biblioitems.collectionvolume
- 225$x ISSN of Series: is mapped to biblioitems.collectionissn

In UNIMARC, 225 is for "Series".

biblioitems.collectionvolume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Possibly "Series volume number"?

The title for 490$v (MARC21), if that is the related field, is "Volume/sequential designation".

However, biblioitems already has "Volume number" for biblioitems.volume, that is mapped in the Koha to MARC mappings to 440$v and 490$v.

When using UNIMARC, 225$v is mapped to the biblioitems.collectionvolume field and called "Volume Designation".

biblioitems.editionresponsibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Possibly "Edition responsibility"?

In UNIMARC, 225$f Statement of Responsibility is mapped to Koha field biblioitems.editionresponsibility. (From installer/data/mysql/en/marcflavour/unimarc/mandatory/unimarc_framework_DEFAULT.yml)

Note that 250 in MARC21 has  $b - Remainder of edition statement: Usually, a statement of personal or corporate responsibility and/or a parallel edition statement. https://www.loc.gov/marc/bibliographic/bd250.html

Koha/Bibliotem.pm has this (line 48):  editionresponsibility => undef, # obsolete, not mapped
Comment 2 David Nind 2024-05-19 03:05:35 UTC
Created attachment 166917 [details] [review]
Bug 32313: Update guided reports column descriptions for items and biblioitems tables

This adds missing column descriptions to the items and biblioitems
tables (used in guided reports for the Circulation, Catalog,
Acquisitions, and Serials modules).

It also updates some existing descriptions for consistency, removes
biblioitems columns that no longer exist, and sorts items and statistics
descriptions in the source file in alphabetical order.

Test plan:
1. Go to Reports > Guided reports > Create guided report.
2. Choose 'Catalog' for the module to report on, and then select
   'Next'.
3. Choose 'Tabular' for the type of report and select 'Next'.
4. Note that there are no descriptions for these column names
   (proposed column names shown in brackets):
   - items.itemnumber (Koha item number (autogenerated))
   - items.biblionumber (Biblio number (internal))
   - items.bookable (Bookable)
   - items.localuse (Total local uses)
   - biblioitems.ean (EAN)
   - biblioitems.collectiontitle (Series statement)
   - biblioitems.collectionissn (Series ISSN)
   - biblioitems.collectionvolume (Series volume)
   - biblioitems.editionstatement (Edition statement)
   - biblioitems.editionresponsibility (Edition responsibility)
   - biblioitems.cn_source (Source of classification or shelving scheme)
   - biblioitems.cn_class (Classification part)
   - biblioitems.cn_item (Item part)
   - biblioitems.cn_suffix (Call number suffix)
   - biblioitems.cn_sort (Koha normalized classification for sorting)
   - biblioitems.totalissues (Koha issues (borrowed), all copies)
5. Apply the patch.
6. Restart all the things (restart_all).
7. Reload the page.
8. Note that there are now descriptions for the columns in step 4.
9. Note that the descriptions for these columns are changed (for
   consistency with other tables, or clarification):
   - items.itype => Koha item type (previously Koha itemtype)
   - items.timestamp => Modification date (previously Timestamp)
   - biblioitems.timestamp => Modification date (previously Timestamp)
   - biblioitems.illus => Other physical details (previously
     Illustrations)
   - biblioitems.biblioitemnumber => Biblio item number (internal)
     (previously Biblioitem number)
   - biblioitems.biblionumber (and also acqorders.biblionumber and
     biblio.biblionumber) => Biblio number (internal)
     (previously Biblio number)
10. Sign off :D

Signed-off-by: David Nind <david@davidnind.com>
Comment 3 David Nind 2024-05-19 03:12:38 UTC
Feel free to suggest alternative column names, or correct comes that I have gotten wrong.

Notes on column description changes
===================================

Naming approach: 
- Generally, use the subfield name used in the MARC framework or Koha to MARC mapping.
- Otherwise use a name that:
  . makes sense, or
  . is consistent with other names, or
  . makes it clearer what the column contains.

Columns with no descriptions - items
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

. items.itemnumber => Koha item number (autogenerated) (952$9) [1]
. items.biblionumber => Biblio number (internal) (consistency with other tables)
. items.bookable => Bookable
. items.localuse => Total local uses (Bug 16122 - Item record needs to keep local use count)

Columns with no descriptions - biblioitems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- biblioitems.ean => EAN
- biblioitems.collectiontitle => Series statement (490$a) [2]
- biblioitems.collectionissn => Series ISSN (490$x) [3]
- biblioitems.collectionvolume => Series volume (490$v) [4]
- biblioitems.editionstatement => Edition statement (250$a)
- biblioitems.editionresponsibility => Edition responsibility (250$b) [5]
- biblioitems.cn_source => Source of classification or shelving scheme (942$2) [1][6]
- biblioitems.cn_class => Classification part (942$h) [1]
- biblioitems.cn_item => Item part (942$i) [1]
- biblioitems.cn_suffix => Call number suffix (942$m) [1]
- biblioitems.cn_sort => Koha normalized classification for sorting (942$6) [1][7]
- biblioitems.totalissues => Koha issues (borrowed), all copies (952$0) [1][8]

Column descriptions changed
~~~~~~~~~~~~~~~~~~~~~~~~~~~

These column descriptions were changed for consistency or clarification:
- biblioitems.timestamp => Modification date (same title used for biblio.timestamp)
- biblioitems.illus => Other physical details (maps to 300$b, have used same title used for that subfield and MARC21 definition)
- biblioitems.biblioitemnumber, items.biblioitemnumber => Biblio item number (internal) (consistency) 
- acqorders.biblionumber, biblio.biblionumber, bibliotems.biblionumber => Biblio number (internal) (consistency with other tables)
- items.cn_source => Source of classification or shelving scheme (consistency with biblioitems.cn_source)
- items.itype => Koha item type (consistency with statistics and suggestions)
- items.timestamp => Modification date (same title used for biblio.timestamp and biblioitems.timestamp)
- suggestions.itemtype => Koha item type (consistency with items and statistics)

Order of columns in source file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Most tables are sorted by the column name in the source file. I updated items and statistics tables to sort in this order.

I think these were originally in the order that the columns appear in the database table.

Happy to change to database table order if this is required.


Notes
~~~~~

[1] Description from Koha to MARC mappings.
[2] Could reword as "Series title", but have used the 490$a description.
[3] See Bug 29635 - Map biblioitems.collectionissn to 490$x by default (MARC21) (bug status = NEW).
[4] Full name in 490$v is 'Series volume/sequential designation', but 'Series volume' is probably sufficient (MARC21 definition label is 'Volume/sequential designation').
[5] Full name in 250$b is 'Remainder of edition statement', but 'Edition responsibility' is probably sufficient (MARC21 definition is "Usually, a statement of personal or corporate responsibility and/or a parallel edition statement.".)
[6] Description from 942$2 is "Source of classification or shelving scheme", have updated items > cn_source to match.
[7] items > cn_sort uses "Koha normalized classification for sorting", so have kept the same for consistency.
[8] Name used in Koha to MARC mappings is "Koha issues (borrowed), all copies". Have used the same description used for items.