folio-data-import 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

folio_data_import/UserImport.py

@@ -5,6 +5,7 @@ import getpass
 import json
 import os
 import time
+import uuid
 from datetime import datetime as dt
 from pathlib import Path
 from typing import Tuple
@@ -41,12 +42,12 @@ class UserImporter:  # noqa: R0902
         self,
         folio_client: folioclient.FolioClient,
         library_name: str,
-        user_file_path: Path,
         batch_size: int,
         limit_simultaneous_requests: asyncio.Semaphore,
         logfile: AsyncTextIOWrapper,
         errorfile: AsyncTextIOWrapper,
         http_client: httpx.AsyncClient,
+        user_file_path: Path = None,
         user_match_key: str = "externalSystemId",
         only_update_present_fields: bool = False,
         default_preferred_contact_type: str = "002",
@@ -94,14 +95,34 @@ class UserImporter:  # noqa: R0902
         """
         return {x[name]: x["id"] for x in folio_client.folio_get_all(endpoint, key)}
 
+    @staticmethod
+    def validate_uuid(uuid_string: str) -> bool:
+        """
+        Validate a UUID string.
+
+        Args:
+            uuid_string (str): The UUID string to validate.
+
+        Returns:
+            bool: True if the UUID is valid, otherwise False.
+        """
+        try:
+            uuid.UUID(uuid_string)
+            return True
+        except ValueError:
+            return False
+
     async def do_import(self) -> None:
         """
         Main method to import users.
 
         This method triggers the process of importing users by calling the `process_file` method.
         """
-        with open(self.user_file_path, "r", encoding="utf-8") as openfile:
-            await self.process_file(openfile)
+        if self.user_file_path:
+            with open(self.user_file_path, "r", encoding="utf-8") as openfile:
+                await self.process_file(openfile)
+        else:
+            raise FileNotFoundError("No user objects file provided")
 
     async def get_existing_user(self, user_obj) -> dict:
         """
@@ -116,7 +137,7 @@ class UserImporter:  # noqa: R0902
         match_key = "id" if ("id" in user_obj) else self.match_key
         try:
             existing_user = await self.http_client.get(
-                self.folio_client.okapi_url + "/users",
+                self.folio_client.gateway_url + "/users",
                 headers=self.folio_client.okapi_headers,
                 params={"query": f"{match_key}=={user_obj[match_key]}"},
             )
@@ -140,7 +161,7 @@ class UserImporter:  # noqa: R0902
         """
         try:
             existing_rp = await self.http_client.get(
-                self.folio_client.okapi_url
+                self.folio_client.gateway_url
                 + "/request-preference-storage/request-preference",
                 headers=self.folio_client.okapi_headers,
                 params={
@@ -167,7 +188,7 @@ class UserImporter:  # noqa: R0902
         """
         try:
             existing_pu = await self.http_client.get(
-                self.folio_client.okapi_url + "/perms/users",
+                self.folio_client.gateway_url + "/perms/users",
                 headers=self.folio_client.okapi_headers,
                 params={
                     "query": f"userId=={existing_user.get('id', user_obj.get('id', ''))}"
@@ -200,10 +221,20 @@ class UserImporter:  # noqa: R0902
             mapped_addresses = []
             for address in addresses:
                 try:
-                    address["addressTypeId"] = self.address_type_map[
-                        address["addressTypeId"]
-                    ]
-                    mapped_addresses.append(address)
+                    if (
+                        self.validate_uuid(address["addressTypeId"])
+                        and address["addressTypeId"] in self.address_type_map.values()
+                    ):
+                        await self.logfile.write(
+                            f"Row {line_number}: Address type {address['addressTypeId']} is a UUID, "
+                            f"skipping mapping\n"
+                        )
+                        mapped_addresses.append(address)
+                    else:
+                        address["addressTypeId"] = self.address_type_map[
+                            address["addressTypeId"]
+                        ]
+                        mapped_addresses.append(address)
                 except KeyError:
                     if address["addressTypeId"] not in self.address_type_map.values():
                         print(
@@ -229,7 +260,16 @@ class UserImporter:  # noqa: R0902
             None
         """
         try:
-            user_obj["patronGroup"] = self.patron_group_map[user_obj["patronGroup"]]
+            if (
+                self.validate_uuid(user_obj["patronGroup"])
+                and user_obj["patronGroup"] in self.patron_group_map.values()
+            ):
+                await self.logfile.write(
+                    f"Row {line_number}: Patron group {user_obj['patronGroup']} is a UUID, "
+                    f"skipping mapping\n"
+                )
+            else:
+                user_obj["patronGroup"] = self.patron_group_map[user_obj["patronGroup"]]
         except KeyError:
             if user_obj["patronGroup"] not in self.patron_group_map.values():
                 print(
@@ -256,7 +296,16 @@ class UserImporter:  # noqa: R0902
         mapped_departments = []
         for department in user_obj.pop("departments", []):
             try:
-                mapped_departments.append(self.department_map[department])
+                if (
+                    self.validate_uuid(department)
+                    and department in self.department_map.values()
+                ):
+                    await self.logfile.write(
+                        f"Row {line_number}: Department {department} is a UUID, skipping mapping\n"
+                    )
+                    mapped_departments.append(department)
+                else:
+                    mapped_departments.append(self.department_map[department])
             except KeyError:
                 print(
                     f'Row {line_number}: Department "{department}" not found, '  # noqa: B907
@@ -320,7 +369,7 @@ class UserImporter:  # noqa: R0902
             else:
                 existing_user[key] = value
         create_update_user = await self.http_client.put(
-            self.folio_client.okapi_url + f"/users/{existing_user['id']}",
+            self.folio_client.gateway_url + f"/users/{existing_user['id']}",
             headers=self.folio_client.okapi_headers,
             json=existing_user,
         )
@@ -340,7 +389,7 @@ class UserImporter:  # noqa: R0902
             HTTPError: If the HTTP request to create the user fails.
         """
         response = await self.http_client.post(
-            self.folio_client.okapi_url + "/users",
+            self.folio_client.gateway_url + "/users",
             headers=self.folio_client.okapi_headers,
             json=user_obj,
         )
@@ -490,7 +539,7 @@ class UserImporter:  # noqa: R0902
                    and the existing PU object (existing_pu).
         """
         rp_obj = user_obj.pop("requestPreference", {})
-        spu_obj = user_obj.pop("servicePointsUser")
+        spu_obj = user_obj.pop("servicePointsUser", {})
         existing_user = await self.get_existing_user(user_obj)
         if existing_user:
             existing_rp = await self.get_existing_rp(user_obj, existing_user)
@@ -540,7 +589,7 @@ class UserImporter:  # noqa: R0902
         rp_obj["userId"] = new_user_obj["id"]
         # print(rp_obj)
         response = await self.http_client.post(
-            self.folio_client.okapi_url
+            self.folio_client.gateway_url
             + "/request-preference-storage/request-preference",
             headers=self.folio_client.okapi_headers,
             json=rp_obj,
@@ -564,7 +613,7 @@ class UserImporter:  # noqa: R0902
         existing_rp.update(rp_obj)
         # print(existing_rp)
         response = await self.http_client.put(
-            self.folio_client.okapi_url
+            self.folio_client.gateway_url
             + f"/request-preference-storage/request-preference/{existing_rp['id']}",
             headers=self.folio_client.okapi_headers,
             json=existing_rp,
@@ -586,7 +635,7 @@ class UserImporter:  # noqa: R0902
         """
         perms_user_obj = {"userId": new_user_obj["id"], "permissions": []}
         response = await self.http_client.post(
-            self.folio_client.okapi_url + "/perms/users",
+            self.folio_client.gateway_url + "/perms/users",
             headers=self.folio_client.okapi_headers,
             json=perms_user_obj,
         )
@@ -674,7 +723,13 @@ class UserImporter:  # noqa: R0902
             mapped_service_points = []
             for sp in spu_obj.pop("servicePointsIds", []):
                 try:
-                    mapped_service_points.append(self.service_point_map[sp])
+                    if self.validate_uuid(sp) and sp in self.service_point_map.values():
+                        await self.logfile.write(
+                            f"Service point {sp} is a UUID, skipping mapping\n"
+                        )
+                        mapped_service_points.append(sp)
+                    else:
+                        mapped_service_points.append(self.service_point_map[sp])
                 except KeyError:
                     print(
                         f'Service point "{sp}" not found, excluding service point from user: '
@@ -685,7 +740,13 @@ class UserImporter:  # noqa: R0902
         if "defaultServicePointId" in spu_obj:
             sp_code = spu_obj.pop('defaultServicePointId', '')
             try:
-                mapped_sp_id = self.service_point_map[sp_code]
+                if self.validate_uuid(sp_code) and sp_code in self.service_point_map.values():
+                    await self.logfile.write(
+                        f"Default service point {sp_code} is a UUID, skipping mapping\n"
+                    )
+                    mapped_sp_id = sp_code
+                else:
+                    mapped_sp_id = self.service_point_map[sp_code]
                 if mapped_sp_id not in spu_obj.get('servicePointsIds', []):
                     print(
                         f'Default service point "{sp_code}" not found in assigned service points, '
@@ -708,7 +769,7 @@ class UserImporter:  # noqa: R0902
             existing_spu (dict): The existing service-points-user object, if it exists.
             existing_user (dict): The existing user object associated with the spu_obj.
         """
-        if spu_obj is not None:
+        if spu_obj:
             await self.map_service_points(spu_obj, existing_user)
             if existing_spu:
                 await self.update_existing_spu(spu_obj, existing_spu)
@@ -727,7 +788,7 @@ class UserImporter:  # noqa: R0902
         """
         try:
             existing_spu = await self.http_client.get(
-                self.folio_client.okapi_url + "/service-points-users",
+                self.folio_client.gateway_url + "/service-points-users",
                 headers=self.folio_client.okapi_headers,
                 params={"query": f"userId=={existing_user['id']}"},
             )
@@ -751,7 +812,7 @@ class UserImporter:  # noqa: R0902
         """
         spu_obj["userId"] = existing_user["id"]
         response = await self.http_client.post(
-            self.folio_client.okapi_url + "/service-points-users",
+            self.folio_client.gateway_url + "/service-points-users",
             headers=self.folio_client.okapi_headers,
             json=spu_obj,
         )
@@ -770,7 +831,7 @@ class UserImporter:  # noqa: R0902
         """
         existing_spu.update(spu_obj)
         response = await self.http_client.put(
-            self.folio_client.okapi_url + f"/service-points-users/{existing_spu['id']}",
+            self.folio_client.gateway_url + f"/service-points-users/{existing_spu['id']}",
             headers=self.folio_client.okapi_headers,
             json=existing_spu,
         )
@@ -781,7 +842,7 @@ class UserImporter:  # noqa: R0902
         Process the user object file.
 
         Args:
-            openfile: The file object to process.
+            openfile: The file or file-like object to process.
         """
         tasks = []
         for line_number, user in enumerate(openfile):
@@ -935,12 +996,12 @@ async def main() -> None:
             importer = UserImporter(
                 folio_client,
                 library_name,
-                user_file_path,
                 batch_size,
                 limit_async_requests,
                 logfile,
                 errorfile,
                 http_client,
+                user_file_path,
                 args.user_match_key,
                 args.update_only_present_fields,
                 args.default_preferred_contact_type,

folio_data_import/marc_preprocessors/__init__.py

@@ -1 +1 @@
-from ._preprocessors import prepend_ppn_prefix_001, strip_999_ff_fields
+from ._preprocessors import *

folio_data_import/marc_preprocessors/_preprocessors.py

@@ -1,4 +1,23 @@
 import pymarc
+import logging
+
+logger = logging.getLogger("folio_data_import.MARCDataImport")
+
+
+def prepend_prefix_001(record: pymarc.Record, prefix: str) -> pymarc.Record:
+    """
+    Prepend a prefix to the record's 001 field.
+
+    Args:
+        record (pymarc.Record): The MARC record to preprocess.
+        prefix (str): The prefix to prepend to the 001 field.
+
+    Returns:
+        pymarc.Record: The preprocessed MARC record.
+    """
+    record["001"].data = f"({prefix})" + record["001"].data
+    return record
+
 
 def prepend_ppn_prefix_001(record: pymarc.Record) -> pymarc.Record:
     """
@@ -11,8 +30,22 @@ def prepend_ppn_prefix_001(record: pymarc.Record) -> pymarc.Record:
     Returns:
         pymarc.Record: The preprocessed MARC record.
     """
-    record['001'].data = '(PPN)' + record['001'].data
-    return record
+    return prepend_prefix_001(record, "PPN")
+
+
+def prepend_abes_prefix_001(record: pymarc.Record) -> pymarc.Record:
+    """
+    Prepend the ABES prefix to the record's 001 field. Useful when
+    importing records from the ABES SUDOC catalog
+
+    Args:
+        record (pymarc.Record): The MARC record to preprocess.
+
+    Returns:
+        pymarc.Record: The preprocessed MARC record.
+    """
+    return prepend_prefix_001(record, "ABES")
+
 
 def strip_999_ff_fields(record: pymarc.Record) -> pymarc.Record:
     """
@@ -25,7 +58,276 @@ def strip_999_ff_fields(record: pymarc.Record) -> pymarc.Record:
     Returns:
         pymarc.Record: The preprocessed MARC record.
     """
-    for field in record.get_fields('999'):
-        if field.indicators == pymarc.Indicators(*['f', 'f']):
+    for field in record.get_fields("999"):
+        if field.indicators == pymarc.Indicators(*["f", "f"]):
             record.remove_field(field)
     return record
+
+def clean_999_fields(record: pymarc.Record) -> pymarc.Record:
+    """
+    The presence of 999 fields, with or without ff indicators, can cause
+    issues with data import mapping in FOLIO. This function calls strip_999_ff_fields
+    to remove 999 fields with ff indicators and then copies the remaining 999 fields
+    to 945 fields.
+
+    Args:
+        record (pymarc.Record): The MARC record to preprocess.
+
+    Returns:
+        pymarc.Record: The preprocessed MARC record.
+    """
+    record = strip_999_ff_fields(record)
+    for field in record.get_fields("999"):
+        _945 = pymarc.Field(
+            tag="945",
+            indicators=field.indicators,
+            subfields=field.subfields,
+        )
+        record.add_ordered_field(_945)
+        record.remove_field(field)
+    return record
+
+def sudoc_supercede_prep(record: pymarc.Record) -> pymarc.Record:
+    """
+    Preprocesses a record from the ABES SUDOC catalog to copy 035 fields
+    with a $9 subfield value of 'sudoc' to 935 fields with a $a subfield
+    prefixed with "(ABES)". This is useful when importing newly-merged records
+    from the SUDOC catalog when you want the new record to replace the old one
+    in FOLIO. This also applyes the prepend_ppn_prefix_001 function to the record.
+
+    Args:
+        record (pymarc.Record): The MARC record to preprocess.
+
+    Returns:
+        pymarc.Record: The preprocessed MARC record.
+    """
+    record = prepend_abes_prefix_001(record)
+    for field in record.get_fields("035"):
+        if "a" in field and "9" in field and field["9"] == "sudoc":
+            _935 = pymarc.Field(
+                tag="935",
+                indicators=["f", "f"],
+                subfields=[pymarc.field.Subfield("a", "(ABES)" + field["a"])],
+            )
+            record.add_ordered_field(_935)
+    return record
+
+
+def clean_empty_fields(record: pymarc.Record) -> pymarc.Record:
+    """
+    Remove empty fields and subfields from the record. These can cause
+    data import mapping issues in FOLIO. Removals are logged at custom
+    log level 26, which is used by folio_migration_tools to populate the
+    data issues report.
+
+    Args:
+        record (pymarc.Record): The MARC record to preprocess.
+
+    Returns:
+        pymarc.Record: The preprocessed MARC record.
+    """
+    MAPPED_FIELDS = {
+        "010": ["a", "z"],
+        "020": ["a", "y", "z"],
+        "035": ["a", "z"],
+        "040": ["a", "b", "c", "d", "e", "f", "g", "h", "k", "m", "n", "p", "r", "s"],
+        "050": ["a", "b"],
+        "082": ["a", "b"],
+        "100": ["a", "b", "c", "d", "q"],
+        "110": ["a", "b", "c"],
+        "111": ["a", "c", "d"],
+        "130": [
+            "a",
+            "d",
+            "f",
+            "k",
+            "l",
+            "m",
+            "n",
+            "o",
+            "p",
+            "r",
+            "s",
+            "t",
+            "x",
+            "y",
+            "z",
+        ],
+        "180": ["x", "y", "z"],
+        "210": ["a", "c"],
+        "240": ["a", "f", "k", "l", "m", "n", "o", "p", "r", "s", "t", "x", "y", "z"],
+        "245": ["a", "b", "c", "f", "g", "h", "k", "n", "p", "s"],
+        "246": ["a", "f", "g", "n", "p", "s"],
+        "250": ["a", "b"],
+        "260": ["a", "b", "c", "e", "f", "g"],
+        "300": ["a", "b", "c", "e", "f", "g"],
+        "440": ["a", "n", "p", "v", "x", "y", "z"],
+        "490": ["a", "v", "x", "y", "z"],
+        "500": ["a", "c", "d", "n", "p", "v", "x", "y", "z"],
+        "505": ["a", "g", "r", "t", "u"],
+        "520": ["a", "b", "c", "u"],
+        "600": ["a", "b", "c", "d", "q", "t", "v", "x", "y", "z"],
+        "610": ["a", "b", "c", "d", "t", "v", "x", "y", "z"],
+        "611": ["a", "c", "d", "t", "v", "x", "y", "z"],
+        "630": [
+            "a",
+            "d",
+            "f",
+            "k",
+            "l",
+            "m",
+            "n",
+            "o",
+            "p",
+            "r",
+            "s",
+            "t",
+            "x",
+            "y",
+            "z",
+        ],
+        "650": ["a", "d", "v", "x", "y", "z"],
+        "651": ["a", "v", "x", "y", "z"],
+        "655": ["a", "v", "x", "y", "z"],
+        "700": ["a", "b", "c", "d", "q", "t", "v", "x", "y", "z"],
+        "710": ["a", "b", "c", "d", "t", "v", "x", "y", "z"],
+        "711": ["a", "c", "d", "t", "v", "x", "y", "z"],
+        "730": [
+            "a",
+            "d",
+            "f",
+            "k",
+            "l",
+            "m",
+            "n",
+            "o",
+            "p",
+            "r",
+            "s",
+            "t",
+            "x",
+            "y",
+            "z",
+        ],
+        "740": ["a", "n", "p", "v", "x", "y", "z"],
+        "800": ["a", "b", "c", "d", "q", "t", "v", "x", "y", "z"],
+        "810": ["a", "b", "c", "d", "t", "v", "x", "y", "z"],
+        "811": ["a", "c", "d", "t", "v", "x", "y", "z"],
+        "830": [
+            "a",
+            "d",
+            "f",
+            "k",
+            "l",
+            "m",
+            "n",
+            "o",
+            "p",
+            "r",
+            "s",
+            "t",
+            "x",
+            "y",
+            "z",
+        ],
+        "856": ["u", "y", "z"],
+    }
+
+    for field in list(record.get_fields()):
+        len_subs = len(field.subfields)
+        subfield_value = bool(field.subfields[0].value) if len_subs > 0 else False
+        if not int(field.tag) >= 900 and field.tag in MAPPED_FIELDS:
+            if int(field.tag) > 9 and len_subs == 0:
+                logger.log(
+                    26,
+                    "DATA ISSUE\t%s\t%s\t%s",
+                    record["001"].value(),
+                    f"{field.tag} is empty, removing field",
+                    field,
+                )
+                record.remove_field(field)
+            elif len_subs == 1 and not subfield_value:
+                logger.log(
+                    26,
+                    "DATA ISSUE\t%s\t%s\t%s",
+                    record["001"].value(),
+                    f"{field.tag}${field.subfields[0].code} is empty, no other subfields present, removing field",
+                    field,
+                )
+                record.remove_field(field)
+            else:
+                if len_subs > 1 and "a" in field and not field["a"].strip():
+                    logger.log(
+                        26,
+                        "DATA ISSUE\t%s\t%s\t%s",
+                        record["001"].value(),
+                        f"{field.tag}$a is empty, removing subfield",
+                        field,
+                    )
+                    field.delete_subfield("a")
+                for idx, subfield in enumerate(list(field.subfields), start=1):
+                    if (
+                        subfield.code in MAPPED_FIELDS.get(field.tag, [])
+                        and not subfield.value
+                    ):
+                        logger.log(
+                            26,
+                            "DATA ISSUE\t%s\t%s\t%s",
+                            record["001"].value(),
+                            f"{field.tag}${subfield.code} ({ordinal(idx)} subfield) is empty, but other subfields have values, removing subfield",
+                            field,
+                        )
+                        field.delete_subfield(subfield.code)
+                if len(field.subfields) == 0:
+                    logger.log(
+                        26,
+                        "DATA ISSUE\t%s\t%s\t%s",
+                        record["001"].value(),
+                        f"{field.tag} has no non-empty subfields after cleaning, removing field",
+                        field,
+                    )
+                    record.remove_field(field)
+    return record
+
+
+def fix_leader(record: pymarc.Record) -> pymarc.Record:
+    """
+    Fixes the leader of the record by setting the record status to 'c' (modified
+    record) and the type of record to 'a' (language material).
+
+    Args:
+        record (pymarc.Record): The MARC record to preprocess.
+
+    Returns:
+        pymarc.Record: The preprocessed MARC record.
+    """
+    VALID_STATUSES = ["a", "c", "d", "n", "p"]
+    VALID_TYPES = ["a", "c", "d", "e", "f", "g", "i", "j", "k", "m", "o", "p", "r", "t"]
+    if record.leader[5] not in VALID_STATUSES:
+        logger.log(
+            26,
+            "DATA ISSUE\t%s\t%s\t%s",
+            record["001"].value(),
+            f"Invalid record status: {record.leader[5]}, setting to 'c'",
+            record,
+        )
+        record.leader = pymarc.Leader(record.leader[:5] + "c" + record.leader[6:])
+    if record.leader[6] not in VALID_TYPES:
+        logger.log(
+            26,
+            "DATA ISSUE\t%s\t%s\t%s",
+            record["001"].value(),
+            f"Invalid record type: {record.leader[6]}, setting to 'a'",
+            record,
+        )
+        record.leader = pymarc.Leader(record.leader[:6] + "a" + record.leader[7:])
+    return record
+
+
+def ordinal(n):
+    s = ("th", "st", "nd", "rd") + ("th",) * 10
+    v = n % 100
+    if v > 13:
+        return f"{n}{s[v % 10]}"
+    else:
+        return f"{n}{s[v]}"

{folio_data_import-0.2.6.dist-info → folio_data_import-0.2.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: folio_data_import
-Version: 0.2.6
+Version: 0.2.8
 Summary: A python module to interact with the data importing capabilities of the open-source FOLIO ILS
 License: MIT
 Author: Brooks Travis
@@ -19,8 +19,7 @@ Requires-Dist: flake8-black (>=0.3.6,<0.4.0)
 Requires-Dist: flake8-bugbear (>=24.8.19,<25.0.0)
 Requires-Dist: flake8-docstrings (>=1.7.0,<2.0.0)
 Requires-Dist: flake8-isort (>=6.1.1,<7.0.0)
-Requires-Dist: folioclient (>=0.61.0,<0.62.0)
-Requires-Dist: httpx (>=0.27.2,<0.28.0)
+Requires-Dist: folioclient (==0.70.1)
 Requires-Dist: inquirer (>=3.4.0,<4.0.0)
 Requires-Dist: pyhumps (>=3.8.0,<4.0.0)
 Requires-Dist: pymarc (>=5.2.2,<6.0.0)
@@ -102,11 +101,30 @@ When this package is installed via PyPI or using `poetry install` from this repo
     }
 }
 ```
-One thing to note here is that this importer does not require `externalSystemId` as the match point for your objects. While it is the default, if the user objects have `id` present, that will be used, falling back to `externalSystemId`. However, you can also specify `username` or `barcode` as the match point if desired, using the `--default_preferred_contact_type` argument.
+#### Matching Existing Users
 
-Another point of departure from the behavior of `mod-user-import` is the handling of `preferredContactTypeId`. This importer will accept either the `"001", "002", "003"...` values stored by the FOLIO, or the human-friendly strings used by `mod-user-import` (`"mail", "email", "text", "phone", "mobile"`). It will also __*set a customizable default for all users that do not otherwise have a valid value specified*__, unless a value is already present in the user record being updated.
+Unlike mod-user-import, this importer does not require `externalSystemId` as the match point for your objects. If the user objects have `id` values, that will be used, falling back to `externalSystemId`. However, you can also specify `username` or `barcode` as the match point if desired, using the `--user_match_key` argument.
 
-How to use:
+#### Preferred Contact Type Mapping
+
+Another point of departure from the behavior of `mod-user-import` is the handling of `preferredContactTypeId`. This importer will accept either the `"001", "002", "003"...` values stored by FOLIO, or the human-friendly strings used by `mod-user-import` (`"mail", "email", "text", "phone", "mobile"`). It will also __*set a customizable default for all users that do not otherwise have a valid value specified*__ (using `--default_preferred_contact_type`), unless a (valid) value is already present in the user record being updated.
+
+#### Field Protection (*experimental*)
+
+This script offers a rudimentary field protection implementation using custom fields. To enable this functionality, create a text custom field that has the field name `protectedFields`. In this field, you can specify a comma-separated list of User schema field names, using dot-notation for nested fields. This protection should support all standard fields except addresses within `personal.addresses`. If you include `personal.addresses` in a user record, any existing addresses will be replaced by the new values.
+
+##### Example
+
+```
+{
+    "protectedFields": "customFields.protectedFields,personal.preferredFirstName,barcode,personal.telephone,personal.addresses"
+}
+```
+
+Would result in `preferredFirstName`, `barcode`, and `telephone` remaining unchanged, regardless of the contents of the incoming records.
+
+
+#### How to use:
 1. Generate a JSON lines (one JSON object per line) file of FOLIO user objects in the style of [mod-user-import](https://github.com/folio-org/mod-user-import)
 2. Run the script and specify the required arguments (and any desired optional arguments), including the path to your file of user objects