/
Scripting Bulk Edit Jobs Through APIs

Scripting Bulk Edit Jobs Through APIs

  • In progress

    • Retrieve records

    Retrieving records can be done using Identifiers or Query approach.

    Upload step

    To retrieve records using Identifiers, upload CSV file with record identifiers of specific entityType. It can be done using Postman with the following required headers:
    folioAccessToken in the Cookie
    X-Okapi-Tenant

    Screenshot 2026-03-20 113105.png

    CSV file to upload can be selected via Body → form-data → file → New file from local machine:

    Screenshot 2026-03-20 113423.png


    Parameter entityType can be either INSTANCE (in the example), HOLDINGS_RECORD, ITEM, or USER. Parameter identifierType depends on entityType and for INSTANCE it can be ID or HRID, for HOLDINGS_RECORD it can be ID, HRID, INSTANCE_HRID (to get holdings by instance), ITEM_BARCODE (to get holdings by item), for ITEM it can be BARCODE, ID, HRID, FORMER_IDS, ACCESSION_NUMBER, HOLDINGS_RECORD_ID (to get item by holdings record), and for USER it can be ID, BARCODE, EXTERNAL_SYSTEM_ID, USER_NAME. Parameter manual is false here, true can be used in the next step (Edit) and only for USER entity type. The following example demonstrates the upload for INSTANCE as entityType and ID as identifierType:

    POST /bulk-operations/upload?entityType=INSTANCE&identifierType=ID&manual=false

    upload.png

    Save "id" from response as operation_id and then start the job by operation_id:
    POST /bulk-operations/{{operation_id}}/start

    {     "step": "UPLOAD" }
    start_upload.png

    Response above shows status: RETRIEVING_RECORDS. However, to proceed further, it requires a polling job operation by operation_id until status is DATA_MODIFICATION:
    GET /bulk-operations/{{operation_id}}

    datamodif.png

    To retrieve records using Query, first of all get entity types and save id (for example, for Instances) as entity_type_id:
    GET /entity-types

    Screenshot 2026-03-20 122200.png

    Then, Post query using the previously stored entity_type_id and specific fql query (here all instances that have uuid are selected):
    POST /query

    {     "entityTypeId": "{{entity_type_id}}",     "fqlQuery": "{\"instance.id\":{\"$empty\":false},\"_version\":\"24\"}" }
    Screenshot 2026-03-20 123651.png

    Save queryId as query_id and then Post bulk operation query by query_id and entity_type_id:

    Screenshot 2026-03-20 124142.png

    Save id as operation_id. Response above shows status: EXECUTING_QUERY. However, to proceed further, it requires a polling job operation by operation_id until status is DATA_MODIFICATION:
    GET /bulk-operations/{{operation_id}}

    Screenshot 2026-03-20 124515.png

    After upload, it is possible to preview uploaded records and possible errors.

    To preview records:
    /bulk-operations/{{operation_id}}/preview?limit=100&offset=0&step=UPLOAD

    previewrecords.png

    To preview errors and warnings:

    /bulk-operations/{{operation_id}}/errors?limit=100&offset=0&errorType=

    previewerrorsafterupload.png

    Edit step

    Next, edit the records by adding, for example, Administrative note.
    Also payload (rule_details) for content-update can be copied from predefined bulk edit profile:

    GET /bulk-operations/profiles?query=(entityType=="INSTANCE") sortBy name/sort.ascending&offset=0&limit=1000

    Screenshot 2026-03-20 135749.png

    Post content update:

    POST /bulk-operations/{{operation_id}}/content-update

    {   "bulkOperationRules": [     {       "bulkOperationId": "{{operation_id}}",       "rule_details": {         "option": "ADMINISTRATIVE_NOTE",         "tenants": [],         "actions": [           {             "type": "ADD_TO_EXISTING",             "initial": null,             "updated": "new note",             "tenants": [],             "updated_tenants": [],             "parameters": []           }         ]       }     }   ],   "totalRecords": 59 }
    edit.png

    Then, start the job by operation_id:

    POST /bulk-operations/{{operation_id}}/start
    {
    "step": "EDIT",
    "approach": "IN_APP"
    }

    edit_start.png

    Response above shows status DATA_MODIFICATION_IN_PROGRESS. However, to proceed further, it requires polling job operation by operation_id until status is REVIEW_CHANGES:
    /bulk-operations/{{operation_id}}

    review_changes.png

    After editing and before commit step, it is possible to preview records with desired changes:

    /bulk-operations/{{operation_id}}/preview?limit=100&offset=0&step=EDIT

    previewareusure.png

    Apply changes

    Commit step

    Start the job by operation_id to commit changes:

    /bulk-operations/{{operation_id}}/start
    {
    "step": "COMMIT",
    "approach": "IN_APP"
    }

    commit.png

    Monitor and report job status

    After commit, wait until job status is COMPLETED or FAILED. Monitoring can be done using polling the job by operation_id.

    Get the job by operation_id:

    GET /bulk-operations/{{operation_id}}

    getbyid.png

    Report completion of the job and possible errors

    Preview records after commit:

    GET /bulk-operations/{{operation_id}}/preview?limit=100&offset=0&step=COMMIT

    previewaftercommit.png

    Preview errors after commit:

    GET /bulk-operations/{{operation_id}}/errors?limit=100&offset=0&errorType=

    previewerrors.png