Update field mapping documentation for holdings and and item note types

Author: bltravis

docs/source/mapping_file_based_mapping.md

@@ -296,3 +296,50 @@ This rule allows you to map codes to strings. Given the following mapping:
 
 If the STATUS field contains *0*, then the resulting value in the note title will be *Graduate*.
 If no match is made, the original string will be returned. So if STATUS is *1*, then the note title will be *1*.
+
+## Validation of Hardcoded Note Type Values
+
+When mapping item or holdings note types (`itemNoteTypeId` or `holdingsNoteTypeId` fields), any hardcoded values specified in the `value` or `fallback_value` properties are validated at mapper initialization. This ensures that mapping files are correct before data transformation begins.
+
+### Validation Rules
+
+Each hardcoded note type value is validated against the FOLIO tenant's available note types:
+- **Empty values** are allowed and skipped
+- **UUID values** must exist in FOLIO's note type repository
+- **Name values** must match a valid FOLIO note type name (case-insensitive)
+
+### Error Handling
+
+If any hardcoded note type value is invalid, a comprehensive error is raised listing all invalid values with their locations in the mapping file:
+
+```
+Invalid note type values found in field mapping:
+  - 'invalid-type-1' (in field: notes[0].itemNoteTypeId, value) - name not found in FOLIO
+  - '99999999-9999-9999-9999-999999999999' (in field: notes[1].itemNoteTypeId, value) - UUID not found in FOLIO
+  - 'unknown-note' (in field: notes[2].holdingsNoteTypeId, fallback_value) - name not found in FOLIO
+
+Available note types: action-note, public-note, staff-note, ...
+
+Please update your mapping file with valid note type names or UUIDs.
+```
+
+### Example: Valid Configuration
+
+```json
+{
+    "folio_field": "notes[0].itemNoteTypeId",
+    "legacy_field": "",
+    "value": "staff-note",
+    "description": "Always use staff note type",
+    "fallback_value": ""
+},
+{
+    "folio_field": "notes[1].itemNoteTypeId",
+    "legacy_field": "NOTE_TYPE",
+    "value": "",
+    "description": "Map from legacy data, fallback to public-note",
+    "fallback_value": "public-note"
+}
+```
+
+This validation ensures that mapping configuration errors are caught immediately, rather than during data processing when iteration is more costly.

docs/source/mapping_files_inventory.md

@@ -16,6 +16,8 @@ temp_loan_types.tsv  | no | no | no | optional |  no   |   no
 call_number_type_mapping.tsv  | no | no | optional | optional |  no   |   no
 statcodes.tsv  | optional | optional | optional | optional |  no   |   no
 item_statuses.tsv | no | no | no | optional    |  no   |   no
+item_note_types.tsv | no | no | no | optional    |  no   |   no
+holdings_note_types.tsv | no | optional | optional | no    |  no   |   no
 post_loan_migration_statuses.tsv | no | no | no | no    |  optional  |   no
 patron_types.tsv | no | no | no | no    |  no  |   yes
 user_mapping.json | no | no | no | no    |  no  |   yes
@@ -156,3 +158,30 @@ lost | Aged to lost
 ```{attention}
 If the item status you are mapping is the result of a circulation transaction (i.e. "Checked out", "Paged", "Aged to lost", "Declared lost", "Claimed returned"), we recommend using an item status mapping of Available for these items, instead. You can set the `next_item_status` in your loans data migration to ensure that loan-related statuses are appropriately set after the migrated loan is created.
 ```
+
+### 📄 item_note_types.tsv
+Optional mapping file for translating legacy item note type codes to FOLIO item note types. This file allows you to map custom or legacy note type codes to FOLIO note type names before they are resolved to their corresponding UUIDs.
+
+The file should be structured with `legacy_note_type` and `folio_name` columns:
+
+legacy_note_type | folio_name 
+------------ | -------------
+LOCAL_NOTE | Local note
+INTERNAL_NOTE | Staff note
+PUBLIC_NOTE | Public note
+*  | Public note
+
+When this file is not provided, note type values are resolved directly as FOLIO note type names or UUIDs. If a value cannot be resolved, an error is recorded.
+
+### 📄 holdings_note_types.tsv
+Optional mapping file for translating legacy holdings note type codes to FOLIO holdings note types. This file allows you to map custom or legacy note type codes to FOLIO note type names before they are resolved to their corresponding UUIDs.
+
+The file should be structured with `legacy_note_type` and `folio_name` columns:
+
+legacy_note_type | folio_name 
+------------ | -------------
+SUPPLEMENTAL_HOLDINGS | Binding information
+PRESERVATION_NOTE | Action note
+*  | Action note
+
+When this file is not provided, note type values are resolved directly as FOLIO note type names or UUIDs. If a value cannot be resolved, an error is recorded.

docs/source/reference_data_mapping.md

@@ -68,6 +68,8 @@ The FOLIO column name depends on the type of reference data being mapped:
 | Material Types | `folio_name` | Material type **name** |
 | Loan Types | `folio_name` | Loan type **name** |
 | Call Number Types | `folio_name` | Call number type **name** |
+| Item Note Types | `folio_name` | Item note type **name** |
+| Holdings Note Types | `folio_name` | Holdings note type **name** |
 | Patron Groups | `folio_name` | Patron group **name** (the `group` field) |
 | Departments | `folio_name` | Department **name** |
 | Statistical Codes | `folio_code` | Statistical code **code** |