UserImportTask

UserImportTask#

Import users to FOLIO with full relationship handling, field protection, and upsert capabilities. This task uses the folio_data_import library’s UserImporter for enhanced features beyond the standard /user-import API.

When to Use This Task#

  • Loading transformed users with request preferences and service point assignments

  • Updating existing users while protecting specific fields

  • When you need fine-grained control over which user fields are updated

  • Handling complex user imports with concurrent processing

Tip

UserImportTask offers advantages over BatchPoster with objectType: Users:

  • Field protection to prevent overwriting specific fields

  • Configurable match key (externalSystemId, username, or barcode)

  • Automatic handling of request preferences and service points users

  • Better error handling and progress reporting

Configuration#

{
    "name": "import_users",
    "migrationTaskType": "UserImportTask",
    "userMatchKey": "externalSystemId",
    "batchSize": 250,
    "files": [
        {
            "file_name": "folio_users_transform_users.json"
        }
    ]
}

Parameters#

Parameter

Type

Required

Default

Description

name

string

Yes

-

The name of this task

migrationTaskType

string

Yes

-

Must be "UserImportTask"

files

array

Yes

-

List of user files from results/ folder

batchSize

integer

No

250

Users per concurrent batch (1-1000)

userMatchKey

string

No

externalSystemId

Match key: externalSystemId, username, or barcode

onlyUpdatePresentFields

boolean

No

false

Only update fields present in input

defaultPreferredContactType

string

No

"002"

Default contact type for users

fieldsToProtect

array

No

[]

Field paths to never overwrite

limitSimultaneousRequests

integer

No

10

Max concurrent HTTP requests (1-100)

noProgress

boolean

No

false

Disable progress reporting

User Match Keys#

Match Key

Description

Use Case

externalSystemId

Match on external system ID

Default; most reliable for ILS migrations

username

Match on username

When usernames are stable identifiers

barcode

Match on barcode

When barcodes are the primary identifier

Preferred Contact Types#

ID

Name

Description

001

mail

Postal mail

002

email

Email (default)

003

text

Text/SMS message

004

phone

Phone call

005

mobile

Mobile phone

Field Protection#

Protect specific fields from being overwritten during updates:

{
    "name": "update_users",
    "migrationTaskType": "UserImportTask",
    "userMatchKey": "externalSystemId",
    "fieldsToProtect": [
        "personal.email",
        "barcode",
        "patronGroup"
    ],
    "files": [{"file_name": "user_updates.json"}]
}

Protected fields will retain their existing values in FOLIO, even if different values are provided in the input.

Partial Updates#

When you only want to update fields that are present in the input:

{
    "name": "partial_user_update",
    "migrationTaskType": "UserImportTask",
    "userMatchKey": "externalSystemId",
    "onlyUpdatePresentFields": true,
    "files": [{"file_name": "user_partial_updates.json"}]
}

When onlyUpdatePresentFields is true:

  • Fields in the input file will be updated

  • Fields missing from the input will be left unchanged

  • This is useful for targeted updates (e.g., only updating addresses)

Source Files#

  • Location: iterations/<iteration>/results/

  • Format: Newline-delimited JSON (one user record per line)

  • Content: Output from UserTransformer with mod-user-import structure

Expected File Structure#

User objects should include the standard mod-user-import format with optional extensions:

{
    "username": "jsmith",
    "externalSystemId": "12345",
    "barcode": "U123456",
    "active": true,
    "patronGroup": "faculty",
    "personal": {
        "lastName": "Smith",
        "firstName": "John",
        "email": "jsmith@example.edu"
    },
    "requestPreference": {
        "holdShelf": true,
        "delivery": false
    }
}

Output Files#

Output

Description

Migration report

Statistics on created/updated/failed users

Console output

Progress bars and summary information

Failed records

Logged in migration report with error details

Examples#

Basic User Import#

{
    "name": "import_users",
    "migrationTaskType": "UserImportTask",
    "files": [
        {"file_name": "folio_users_transform_users.json"}
    ]
}

Update by Barcode with Field Protection#

{
    "name": "update_by_barcode",
    "migrationTaskType": "UserImportTask",
    "userMatchKey": "barcode",
    "fieldsToProtect": ["personal.email", "personal.phone"],
    "files": [
        {"file_name": "user_address_updates.json"}
    ]
}

High-Volume Import with Throttling#

{
    "name": "bulk_user_import",
    "migrationTaskType": "UserImportTask",
    "batchSize": 100,
    "limitSimultaneousRequests": 5,
    "files": [
        {"file_name": "all_users.json"}
    ]
}

Partial Update - Only Present Fields#

{
    "name": "update_expiration_dates",
    "migrationTaskType": "UserImportTask",
    "userMatchKey": "externalSystemId",
    "onlyUpdatePresentFields": true,
    "files": [
        {"file_name": "user_expirations.json"}
    ]
}

Input file might contain only the fields to update:

{"externalSystemId": "12345", "expirationDate": "2025-12-31"}
{"externalSystemId": "67890", "expirationDate": "2025-12-31"}

Non-Interactive/CI Environment#

{
    "name": "ci_user_import",
    "migrationTaskType": "UserImportTask",
    "noProgress": true,
    "files": [
        {"file_name": "test_users.json"}
    ]
}

Running the Task#

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

See Also#

Contents