Skip to main content
English (United States) Nederlands

Assets Server REST API - Processes

Updated

The Process API lets clients track and cancel long-running server processes.

Note: A process can be viewed or canceled only by a superuser or by the user who started it. Finished processes remain queryable only for a limited time (see section Process history & retention later in this article.)

Get process status API

GET POST /services/process/info

Returns the current status of a single process by its ID.

Parameters

Name Type Description Example
processId string ID of the process to query, as returned when the process was started. Required. ID of the process to query, as returned when the process was started. Required.

Result

The response is a ProcessInfo object.

Field Type Description
id string Unique process ID.
name string Process name.
load string Load category: NORMAL, HEAVY, or HEAVY_EXCLUSIVE.
user string Name of the user who started the process.
cancelable boolean Whether the process supports cancellation.
state string Current state (see Process states).
progress number Number of items processed so far. -1 means indeterminable.
total number Total number of items to process. -1 or 0 means indeterminable.
errorCount number Number of errors encountered. -1 means indeterminable.
details string Message describing the current step.
failureMessage string Exception message when the process failed; otherwise absent.
displayState string Progress state.
estimateTimeRemaining string Estimated time remaining, or 'done' when finished.
done boolean 'true' once the process has finished.

Example

Running process:

{
  "id": "k3Jd9aQ2",
  "name": "Stats history cleanup",
  "load": "NORMAL",
  "user": "admin",
  "cancelable": true,
  "state": "RUNNING",
  "progress": 1200,
  "total": 5000,
  "errorCount": 0,
  "details": "Processing index stats-202104-r1",
  "displayState": "24.0%, 1,200 per minute, ETR: 3m 10s",
  "estimateTimeRemaining": "3m 10s",
  "done": false
}

Completed process:

{
  "id": "k3Jd9aQ2",
  "name": "Stats history cleanup",
  "load": "NORMAL",
  "user": "admin",
  "cancelable": true,
  "state": "COMPLETED",
  "progress": 5000,
  "total": 5000,
  "errorCount": 0,
  "details": "Done",
  "displayState": "COMPLETED, processed 5000 in 4m at 1,250 per minute",
  "estimateTimeRemaining": "done",
  "done": true
}

Cancel process API

POST /services/process/cancel

Cancels a running process.

Note: Cancellation only works if the process can be canceled (cancelable: true).

Parameters

Name Type Description Example
processId string ID of the process to cancel. Required. k3Jd9aQ2

Result

{ "status": "OK" }

Process states

State Description
RUNNING The process is currently executing.
COMPLETED The process finished successfully with no errors.
COMPLETED_WITH_ERRORS The process finished, but one or more items failed.
FAILED The process aborted because of an error.
CANCELLED The process was canceled by a user.

Process history & retention

When a process finishes it is moved from the active list into an in-memory history, where it stays queryable through the Get process status API.

The twelve most recently finished processes are kept in history

Process authorization (role required to start)

Superuser tools (ROLE_SUPERUSER)

Assets processing tool

  • Bulk Import
  • Index rescue filestore scan
  • Missing original index scan
  • Restore backup
  • Stats activity cleanup
  • Stats history cleanup
  • Stats index cleanup
  • Stats search cleanup
  • Stats usage cleanup

Data-admin tools (ROLE_DATA_ADMIN)

  • Asset duplicate cleanup

Standard user operations (ROLE_USER + permission)

  • AddAssetToCollection
  • Move folder contents
  • RemoveFolder
  • RemoveRelations
  • UpdateMetadataBulk
  • and others

Related articles

Comments

0 comments