Batch Actions API Reference¶

The Heritage Data Processor Batch Actions API provides endpoints for executing multiple operations on files, records, and Zenodo drafts simultaneously within an HDPC project.

Base URL¶

All endpoints are prefixed with /project.

Batch Operations¶

Execute Batch Action¶

Performs batch operations on multiple items within the currently loaded HDPC project, supporting metadata preparation, draft creation, file removal, draft discarding, and file uploads.

Endpoint: POST /project/batch_action

Request Body:

{
  "action_type": "prepare_metadata",
  "item_ids": [1, 2, 3, 4],
  "target_is_sandbox": true
}

Request Parameters:

action_type (string, required): The type of batch action to execute. Must be one of: prepare_metadata, create_api_draft, remove_files, discard_drafts, upload_main_files
item_ids (array, required): List of item identifiers to process. The meaning depends on the action type
target_is_sandbox (boolean, optional): Whether to target the Zenodo sandbox environment. Defaults to true. Only applies to actions that interact with Zenodo

Response:

{
  "success": true,
  "results": [
    {
      "id": 1,
      "success": true,
      "message": "Action completed successfully"
    },
    {
      "id": 2,
      "success": false,
      "message": "Action failed",
      "error": "Validation error details"
    }
  ]
}

Response Fields:

success (boolean): Overall success status. true only if all items succeeded
results (array): Array of individual item results with the following structure:
id (integer): The item identifier that was processed
success (boolean): Whether the action succeeded for this item
message (string): Descriptive message about the operation result
error (string, optional): Error description if the action failed

Status Codes:

200 OK: Batch action completed (check individual results for item-level success)
400 Bad Request: No HDPC project loaded, or missing required parameters

Action Types¶

Prepare Metadata¶

Prepares and validates metadata for source files before creating Zenodo records.

Action Type: prepare_metadata

Item IDs: Source file database IDs (source_file_db_id)

Required Parameters:

target_is_sandbox: Specifies whether to prepare metadata for sandbox or production Zenodo

Success Response Fields:

The response includes fields returned by the metadata preparation process.

Error Cases:

Metadata validation failed: Occurs when metadata does not meet Zenodo requirements
Missing source file: The specified file ID does not exist in the database

Create API Draft¶

Creates Zenodo draft depositions via API for records with prepared metadata.

Action Type: create_api_draft

Item IDs: Local record database IDs (local_record_db_id)

Success Response Fields:

The response includes fields returned by the Zenodo draft creation process, such as the draft ID and deposition URL.

Error Cases:

Record not found: The specified record ID does not exist
Metadata not prepared: Metadata must be prepared before creating drafts
Zenodo API error: Communication or authentication failure with Zenodo

Remove Files¶

Permanently deletes source files from the HDPC project database.

Destructive Operation

This action permanently removes files from the database. Foreign key constraints are enforced during deletion.

Action Type: remove_files

Item IDs: Source file IDs (file_id)

Success Response:

{
  "id": 5,
  "success": true,
  "message": "File with ID 5 was successfully removed."
}

Error Cases:

Database error: Foreign key constraint violations or database connection issues
File not found: The specified file ID does not exist

Discard Drafts¶

Discards Zenodo draft depositions, removing them from both Zenodo and the local database.

Action Type: discard_drafts

Item IDs: Local record database IDs (local_record_db_id)

Implementation:

This action makes an internal API call to /api/project/discard_zenodo_draft with a 60-second timeout.

Error Cases:

Draft not found: The specified draft does not exist in Zenodo or locally
Zenodo API error: Failed to communicate with Zenodo API
Timeout: Operation exceeded 60-second limit

Upload Main Files¶

Uploads the primary source file associated with each record to its corresponding Zenodo deposition.

Action Type: upload_main_files

Item IDs: Zenodo record IDs (record_id)

Implementation:

This action retrieves the associated source file ID from the zenodo_records table and uploads it to the deposition via internal API call with a 300-second timeout.

Success Response:

The response includes upload status, file metadata, and deposition information.

Error Cases:

No associated source file: The record does not have a linked source file
Upload failed: File upload to Zenodo failed due to size limits, network issues, or API errors
Timeout: Upload exceeded 300-second limit

Error Responses¶

All error responses follow a consistent format:

{
  "success": false,
  "error": "Descriptive error message"
}

Common Error Codes¶

400 Bad Request: No HDPC project loaded, or missing action_type or item_ids parameters
500 Internal Server Error: Unexpected server error during batch processing

Item-Level Errors¶

Individual items in the batch may fail while others succeed. Check the results array for per-item status:

{
  "success": false,
  "results": [
    {
      "id": 1,
      "success": true,
      "message": "File uploaded successfully"
    },
    {
      "id": 2,
      "success": false,
      "error": "Database error removing file ID 2: constraint violation"
    }
  ]
}

Usage Examples¶

Example 1: Prepare Metadata for Multiple Files¶

POST /project/batch_action
Content-Type: application/json

{
  "action_type": "prepare_metadata",
  "item_ids": [101, 102, 103],
  "target_is_sandbox": false
}

Response:

{
  "success": true,
  "results": [
    {
      "id": 101,
      "success": true,
      "message": "Metadata prepared successfully"
    },
    {
      "id": 102,
      "success": true,
      "message": "Metadata prepared successfully"
    },
    {
      "id": 103,
      "success": false,
      "error": "Metadata validation failed."
    }
  ]
}

Example 2: Create Multiple Zenodo Drafts¶

POST /project/batch_action
Content-Type: application/json

{
  "action_type": "create_api_draft",
  "item_ids": [201, 202, 203]
}

Example 3: Remove Multiple Files¶

POST /project/batch_action
Content-Type: application/json

{
  "action_type": "remove_files",
  "item_ids": [301, 302, 303, 304]
}

Foreign Key Constraints

Files with foreign key relationships (e.g., associated with existing records) cannot be deleted and will fail with a constraint violation error.

Example 4: Upload Files to Depositions¶

POST /project/batch_action
Content-Type: application/json

{
  "action_type": "upload_main_files",
  "item_ids": [401, 402, 403]
}

Timeout Configuration

File uploads have a 300-second timeout to accommodate large files. Ensure your network connection is stable for large uploads.

Data Types & Formats¶

Action Types¶

prepare_metadata: Validates and prepares metadata for Zenodo submission
create_api_draft: Creates Zenodo draft depositions via API
remove_files: Permanently deletes source files from database
discard_drafts: Removes Zenodo drafts from both remote and local storage
upload_main_files: Uploads primary files to their Zenodo depositions

Item ID Context¶

The meaning of item_ids depends on the action_type:

Action Type	Item ID Refers To	Database Column
`prepare_metadata`	Source file identifier	`source_file_db_id`
`create_api_draft`	Local record identifier	`local_record_db_id`
`remove_files`	Source file identifier	`file_id`
`discard_drafts`	Local record identifier	`local_record_db_id`
`upload_main_files`	Zenodo record identifier	`record_id`

HDPC Project Context¶

All batch actions require an active HDPC (Heritage Data Processor Container) project to be loaded. Operations are performed within the context of the currently loaded project database.