LoansMigrator

LoansMigrator#

Migrate open loans from legacy systems into FOLIO using the circulation APIs. Unlike other tasks, this task creates transactions in real-time rather than transforming data for later posting.

When to Use This Task#

  • Migrating active/open loans from legacy ILS

  • Preserving loan due dates and renewal counts

  • Creating loans via FOLIO’s circulation APIs (with policy validation)

Attention

This task creates real circulation transactions and can generate thousands of patron notices. We strongly recommend disabling SMTP before running this task.

Configuration#

{
    "name": "migrate_loans",
    "migrationTaskType": "LoansMigrator",
    "fallbackServicePointId": "a77b55e7-f9f3-40a1-83e0-241bc606a826",
    "openLoansFiles": [
        {
            "file_name": "loans.tsv",
            "service_point_id": "a77b55e7-f9f3-40a1-83e0-241bc606a826"
        }
    ],
    "startingRow": 1,
    "itemFiles": [
        {
            "file_name": "folio_items_transform_items.json"
        }
    ],
    "patronFiles": [
        {
            "file_name": "folio_users_transform_users.json"
        }
    ]
}

Parameters#

Parameter

Type

Required

Description

name

string

Yes

The name of this task.

migrationTaskType

string

Yes

Must be "LoansMigrator"

fallbackServicePointId

string

Yes

UUID of service point for check-out transactions

openLoansFiles

array

Yes

List of loan data files with optional per-file service point

startingRow

integer

No

Row number to start processing (for resuming). Default: 1

itemFiles

array

No

Transformed item files for pre-validation

patronFiles

array

No

Transformed user files for pre-validation

Source Data Requirements#

  • Location: Place CSV/TSV files in iterations/<iteration>/source_data/loans/

  • Format: Tab-separated (TSV) or comma-separated (CSV) with specific required columns

Required Columns#

Column

Description

item_barcode

Barcode of the item being loaned

patron_barcode

Barcode of the patron with the loan

due_date

Due date of the loan

out_date

Check-out date of the loan

Optional Columns#

Column

Description

proxy_patron_barcode

Barcode of proxy borrower (if applicable)

renewal_count

Number of times the loan has been renewed

next_item_status

Item status to set after loan is created

service_point_id

Override service point for this specific loan

Example Data#

item_barcode	patron_barcode	due_date	out_date	renewal_count
1234567890	P001234	2024-12-15	2024-11-01	2
0987654321	P005678	2024-12-20	2024-11-15	0

Date Formats#

Dates should be in ISO 8601 format:

  • 2024-12-15 (date only)

  • 2024-12-15T10:30:00 (with time)

  • 2024-12-15T10:30:00-05:00 (with timezone)

Pre-validation#

If itemFiles and/or patronFiles are specified, the task validates loans before attempting to create them:

  • Missing items: Rows with item barcodes not found in item files are set aside

  • Missing patrons: Rows with patron barcodes not found in user files are set aside

  • Invalid dates: Rows where due_date precedes out_date are set aside

Failed records are saved to failed_records_<task_name>_<timestamp>.txt.

How It Works#

  1. Check-out via API: Creates loans via /circulation/check-out-by-barcode with all overrides enabled

  2. Update dates: Updates loanDate and dueDate to match original values

  3. Handle special statuses: If item status prevents checkout (Aged to lost, Declared lost, Claimed returned), temporarily changes status to Available

  4. Handle inactive patrons: If patron is inactive, temporarily activates for checkout then deactivates

Tip

Migrate items with loanable statuses (like “Available” or “Checked out”) rather than non-loanable statuses to improve performance. The task can handle non-loanable statuses but it’s significantly slower.

Output Files#

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

File

Description

failed_records_<task_name>_<timestamp>.txt

Records that failed validation or posting

Report files

Migration statistics and error logs

Examples#

Basic Loan Migration#

{
    "name": "migrate_loans",
    "migrationTaskType": "LoansMigrator",
    "fallbackServicePointId": "a77b55e7-f9f3-40a1-83e0-241bc606a826",
    "openLoansFiles": [
        {
            "file_name": "loans.tsv"
        }
    ]
}

With Pre-validation#

{
    "name": "migrate_loans",
    "migrationTaskType": "LoansMigrator",
    "fallbackServicePointId": "a77b55e7-f9f3-40a1-83e0-241bc606a826",
    "openLoansFiles": [
        {
            "file_name": "loans.tsv"
        }
    ],
    "itemFiles": [
        {
            "file_name": "folio_items_transform_items.json"
        }
    ],
    "patronFiles": [
        {
            "file_name": "folio_users_transform_users.json"
        }
    ]
}

Multiple Files with Different Service Points#

{
    "name": "migrate_loans",
    "migrationTaskType": "LoansMigrator",
    "fallbackServicePointId": "a77b55e7-f9f3-40a1-83e0-241bc606a826",
    "openLoansFiles": [
        {
            "file_name": "main_library_loans.tsv",
            "service_point_id": "a77b55e7-f9f3-40a1-83e0-241bc606a826"
        },
        {
            "file_name": "branch_loans.tsv",
            "service_point_id": "b88c66f8-g4h5-51b2-94f1-352de707b937"
        }
    ]
}

Resuming from a Specific Row#

{
    "name": "migrate_loans",
    "migrationTaskType": "LoansMigrator",
    "fallbackServicePointId": "a77b55e7-f9f3-40a1-83e0-241bc606a826",
    "startingRow": 5001,
    "openLoansFiles": [
        {
            "file_name": "loans.tsv"
        }
    ]
}

Running the Task#

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

Troubleshooting#

SMTP Warning#

The task checks if SMTP is disabled before starting. If not, you’ll get a 10-second warning before proceeding.

Item Status Issues#

Items in non-loanable statuses will be temporarily changed to “Available”, have the loan created, then have their status reset. This is logged but significantly slows processing.

Inactive Patrons#

Inactive patrons will be temporarily activated for the checkout, then deactivated. This is handled automatically.

See Also#

Contents