ManualFeeFinesTransformer#

Transform delimited (CSV/TSV) data into FOLIO Manual Fees/Fines (accounts and fee/fine actions).

When to Use This Task#

Migrating static, non-incrementing fees/fines from legacy systems
Creating manual charges not tied to open loans (e.g., replacement costs for returned items)
Preserving fee/fine history with partial payment records

Important

This task creates manual (static) fees/fines. For automatic fees/fines that increment over time (like overdue fines), FOLIO generates these from open loans. To avoid duplication, only migrate manual fees/fines for charges not related to open loans.

Configuration#

{
    "name": "transform_feefines",
    "migrationTaskType": "ManualFeeFinesTransformer",
    "feefinesMap": "feefines_mapping.json",
    "feefinesOwnerMap": "feefine_owners.tsv",
    "feefinesTypeMap": "feefine_types.tsv",
    "servicePointMap": "service_points.tsv",
    "files": [
        {
            "file_name": "feefines.tsv"
        }
    ]
}

Parameters#

Parameter	Type	Required	Description
`name`	string	Yes	The name of this task.
`migrationTaskType`	string	Yes	Must be `"ManualFeeFinesTransformer"`
`feefinesMap`	string	Yes	JSON mapping file for fee/fine fields
`feefinesOwnerMap`	string	No	TSV file mapping fee/fine owners
`feefinesTypeMap`	string	No	TSV file mapping fee/fine types
`servicePointMap`	string	No	TSV file mapping service points
`files`	array	Yes	List of source data files to process

Source Data Requirements#

Location: Place CSV/TSV files in iterations/<iteration>/source_data/feefines/
Format: Tab-separated (TSV) or comma-separated (CSV) with header row
Prerequisites: Run UserTransformer and post users first

Fee/Fine Mapping File#

Behind the scenes, a manual fee/fine in FOLIO consists of one “account” and one or more “feeFineActions”. The mapping file creates both:

{
    "data": [
        {
            "folio_field": "legacyIdentifier",
            "legacy_field": "FEE_ID"
        },
        {
            "folio_field": "account.userId",
            "legacy_field": "PATRON_BARCODE",
            "description": "Matched to user UUID"
        },
        {
            "folio_field": "account.amount",
            "legacy_field": "ORIGINAL_AMOUNT"
        },
        {
            "folio_field": "account.remaining",
            "legacy_field": "BALANCE"
        },
        {
            "folio_field": "account.feeFineType",
            "legacy_field": "FEE_TYPE",
            "description": "Mapped via feefinesTypeMap"
        },
        {
            "folio_field": "account.ownerId",
            "legacy_field": "LOCATION",
            "description": "Mapped via feefinesOwnerMap"
        },
        {
            "folio_field": "account.feeFineOwner",
            "legacy_field": "LOCATION",
            "description": "Mapped via feefinesOwnerMap"
        },
        {
            "folio_field": "feefineaction.dateAction",
            "legacy_field": "CHARGE_DATE"
        },
        {
            "folio_field": "feefineaction.comments",
            "legacy_field": "NOTES"
        },
        {
            "folio_field": "feefineaction.createdAt",
            "legacy_field": "SERVICE_POINT",
            "description": "Mapped via servicePointMap"
        }
    ]
}

Reference Data Mapping Files#

Reference data mapping files connect values from your legacy data to FOLIO reference data. See Reference Data Mapping for detailed documentation on how these files work. All files are optional—you can alternatively specify UUIDs directly in the mapping file.

Mapping File	FOLIO Column	Maps To
`ownerMapFileName`	`folio_owner`	Fee/fine owner name (the `owner` field)
`feefineTypeMapFileName`	`folio_name`	Fee/fine type name (the `feeFineType` field)
`servicePointMapFileName`	`folio_name`	Service point name

Attention

The fee/fine type must be associated with the fee/fine owner in FOLIO.
FOLIO allows duplicate fee/fine type names, but the reference data mapping requires unique names.

Fee/Fine Status#

The overall Fee/Fine status is automatically determined:

Open: If remaining amount > 0
Closed: If remaining amount = 0

You can map any valid payment status, but the overall status is calculated from the remaining balance.

Output Files#

Files are created in iterations/<iteration>/results/:

File	Description
`extradata_<task_name>.extradata`	Fee/fine records for posting
`feefines_id_map_<task_name>.json`	Legacy ID to FOLIO UUID mapping

Examples#

Basic Fee/Fine Transformation#

{
    "name": "transform_feefines",
    "migrationTaskType": "ManualFeeFinesTransformer",
    "feefinesMap": "feefines_mapping.json",
    "files": [
        {
            "file_name": "feefines.tsv"
        }
    ]
}

With All Reference Data Mappings#

{
    "name": "transform_feefines",
    "migrationTaskType": "ManualFeeFinesTransformer",
    "feefinesMap": "feefines_mapping.json",
    "feefinesOwnerMap": "feefine_owners.tsv",
    "feefinesTypeMap": "feefine_types.tsv",
    "servicePointMap": "service_points.tsv",
    "files": [
        {
            "file_name": "feefines.tsv"
        }
    ]
}

Running the Task#

folio-migration-tools mapping_files/config.json transform_feefines --base_folder ./

Posting Fee/Fines#

Fee/fine data is stored in an extradata file. Post using BatchPoster:

{
    "name": "post_feefines",
    "migrationTaskType": "BatchPoster",
    "objectType": "Extradata",
    "batchSize": 1,
    "files": [
        {
            "file_name": "extradata_transform_feefines.extradata"
        }
    ]
}

ManualFeeFinesTransformer

Contents