RequestsMigrator

RequestsMigrator#

Migrate open requests from legacy systems into FOLIO using the circulation APIs.

When to Use This Task#

  • Migrating active hold/recall requests from legacy ILS

  • Preserving request queue positions

  • Creating requests via FOLIO’s circulation APIs

Attention

This task creates real circulation transactions. Ensure items and users have been posted to FOLIO before running.

Configuration#

{
    "name": "migrate_requests",
    "migrationTaskType": "RequestsMigrator",
    "openRequestsFile": {
        "file_name": "requests.tsv"
    },
    "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 "RequestsMigrator"

openRequestsFile

object

Yes

File definition with file_name for request data

startingRow

integer

No

Row number to start processing. 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/requests/

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

Required Columns#

Column

Description

item_barcode

Barcode of the requested item

patron_barcode

Barcode of the requesting patron

request_type

Type of request (Hold, Recall, Page)

request_date

Date the request was placed

Optional Columns#

Column

Description

pickup_service_point_id

UUID of the pickup location

expiration_date

Request expiration date

request_level

Item or Title level request

fulfillment_preference

Hold Shelf or Delivery

Example Data#

item_barcode	patron_barcode	request_type	request_date	pickup_service_point_id
1234567890	P001234	Hold	2024-11-01	a77b55e7-f9f3-40a1-83e0-241bc606a826
0987654321	P005678	Recall	2024-11-15	a77b55e7-f9f3-40a1-83e0-241bc606a826

Pre-validation#

If itemFiles and/or patronFiles are specified, the task validates requests 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

Failed records are saved for review.

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 Request Migration#

{
    "name": "migrate_requests",
    "migrationTaskType": "RequestsMigrator",
    "openRequestsFile": {
        "file_name": "requests.tsv"
    }
}

With Pre-validation#

{
    "name": "migrate_requests",
    "migrationTaskType": "RequestsMigrator",
    "openRequestsFile": {
        "file_name": "requests.tsv"
    },
    "itemFiles": [
        {
            "file_name": "folio_items_transform_items.json"
        }
    ],
    "patronFiles": [
        {
            "file_name": "folio_users_transform_users.json"
        }
    ]
}

Running the Task#

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

See Also#

Contents