MARC migrations API (1.0.0)

API for managing MARC record migrations in FOLIO.

This API allows users to:

  • Create new migration operations for MARC records
  • Monitor the progress of migrations
  • Retrieve information about existing migration operations

The API supports migration operations for different entity types (authority, instance) and operation types (remapping).

marc-migrations

MARC migration operations

Get MARC migration operations

Retrieves a collection of MARC migration operations with pagination and filtering options.

Authorizations:
ApiKey
query Parameters
offset
integer [ 0 .. 1000 ]
Default: 0

Skip over a number of migrations by specifying an offset value for the query.

limit
integer [ 0 .. 1000 ]
Default: 100

Limit the number of migration operations returned in the response.

entityType
string (EntityType)
Enum: "authority" "instance"
Example: entityType=authority

Migration Entity Type to filter by.

header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Responses

Response samples

Content type
application/json
{
  • "migrationOperations": [
    ],
  • "totalRecords": 2
}

Register new MARC migration operation

Creates a new MARC migration operation for the specified entity type and operation type.

Authorizations:
ApiKey
header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Request Body schema: application/json
required
entityType
required
string (EntityType)
Enum: "authority" "instance"

Type of MARC entity being migrated.

operationType
required
string (OperationType)
Enum: "remapping" "import"

Type of migration operation to perform.

Responses

Request samples

Content type
application/json
{
  • "entityType": "authority",
  • "operationType": "remapping"
}

Response samples

Content type
application/json
{
  • "id": "474d0af6-028f-4d15-8354-d2fc10c71a68",
  • "userId": "0db8f753-6864-452c-9b49-5362a20188b5",
  • "entityType": "authority",
  • "operationType": "remapping",
  • "status": "new",
  • "totalNumOfRecords": 10000
}

Retry MARC migration operations

Retries MARC migration operations for the specified chunk IDs.

Authorizations:
ApiKey
path Parameters
operationId
required
string <uuid>
Example: 774d0af6-028f-4d15-8354-d2fc10c71a77

The UUID of a MARC migration operation.

header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Request Body schema: application/json
required
Array
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "574d0af6-028f-4d15-8354-d2fc10c71a07",
  • "074d0af6-028f-4d15-8354-d2fc10c71a08"
]

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "entityType": "authority",
  • "operationType": "remapping",
  • "status": "data_mapping",
  • "totalNumOfRecords": 0,
  • "mappedNumOfRecords": 0,
  • "savedNumOfRecords": 0,
  • "startTimeMapping": "2019-08-24T14:15:22Z",
  • "endTimeMapping": "2019-08-24T14:15:22Z",
  • "startTimeSaving": "2019-08-24T14:15:22Z",
  • "endTimeSaving": "2019-08-24T14:15:22Z"
}

Retry saving MARC migration operations

Retry saving MARC migration operations for the specified chunk IDs.

Authorizations:
ApiKey
path Parameters
operationId
required
string <uuid>
Example: 884d0af6-028f-4d15-8354-d2fc10c71a88

The UUID of a MARC migration operation.

header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Request Body schema: application/json
required
Array
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "584d0af6-028f-4d15-8354-d2fc10c71a08",
  • "884d0af6-028f-4d15-8354-d2fc10c71a08"
]

Response samples

Content type
application/json
{
  • "message": "Invalid UUID format",
  • "type": "IllegalArgumentException",
  • "parameters": [
    ]
}

Get MARC migration operation by ID

Retrieves a specific MARC migration operation by its unique identifier.

Authorizations:
ApiKey
path Parameters
operationId
required
string <uuid>
Example: 474d0af6-028f-4d15-8354-d2fc10c71a68

The UUID of a MARC migration operation

header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Responses

Response samples

Content type
application/json
{
  • "id": "474d0af6-028f-4d15-8354-d2fc10c71a68",
  • "userId": "0db8f753-6864-452c-9b49-5362a20188b5",
  • "entityType": "authority",
  • "operationType": "remapping",
  • "status": "data_mapping",
  • "totalNumOfRecords": 10000,
  • "mappedNumOfRecords": 5000,
  • "startTimeMapping": "2023-01-15T10:30:00.000Z"
}

Initialize MARC migration operation save stage

Save results of the MARC migration operation.

Authorizations:
ApiKey
path Parameters
operationId
required
string <uuid>
Example: 474d0af6-028f-4d15-8354-d2fc10c71a68

The UUID of a MARC migration operation.

header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Request Body schema: application/json
required
status
required
string (MigrationOperationStatus)
Enum: "new" "data_mapping" "data_mapping_completed" "data_mapping_failed" "data_saving" "data_saving_completed" "data_saving_failed"

Current status of the migration operation.

publishEvents
boolean
Default: true

A flag that indicates if domain events should be published when the operation is updated.

Responses

Request samples

Content type
application/json
{
  • "status": "data_mapping",
  • "publishEvents": true
}

Response samples

Content type
application/json
{
  • "message": "Invalid UUID format",
  • "type": "IllegalArgumentException",
  • "parameters": [
    ]
}

Create error report for a migration operation

Combines all error records in one report.

Authorizations:
ApiKey
path Parameters
operationId
required
string <uuid>
Example: 474d0af6-028f-4d15-8354-d2fc10c71a68

The UUID of a MARC migration operation

header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid UUID format",
  • "type": "IllegalArgumentException",
  • "code": "validation_error",
  • "parameters": [
    ]
}

Get error reports for a migration operation

Retrieves a list of error reports for a specific migration operation with pagination.

Authorizations:
ApiKey
path Parameters
operationId
required
string <uuid>
Example: 474d0af6-028f-4d15-8354-d2fc10c71a68

The UUID of a MARC migration operation

query Parameters
offset
integer [ 0 .. 1000 ]
Default: 0

Skip over a number of error reports by specifying an offset value for the query.

limit
integer [ 0 .. 1000 ]
Default: 100

Limit the number of error reports returned in the response.

header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Responses

Response samples

Content type
application/json
{
  • "errorReports": [
    ]
}

Get status of error report generation

Provides the current status of error report generation for a specific migration operation.

Authorizations:
ApiKey
path Parameters
operationId
required
string <uuid>
Example: 474d0af6-028f-4d15-8354-d2fc10c71a68

The UUID of a MARC migration operation

header Parameters
X-Okapi-Tenant
required
string
Example: diku

Tenant ID

Responses

Response samples

Content type
application/json
{
  • "operationId": "3051932a-fdd2-48fa-b330-7e7d41535969",
  • "status": "not_started"
}