Querying for batch process information

Use the following endpoints to retrieve information about batch processes:

  • GET /systemtools/v1/batch-processes
  • GET /systemtools/v1/batch-processes/{batchProcessType}
When querying for information on a specific batch process, you must include the batch process type as defined in the BatchProcessType typelist. This value is case-sensitive. For example, to query for information on the Activity Escalation batch process, use the following:
GET /systemtools/v1/batch-processes/ActivityEsc

The BatchProcess resource

Cloud API manages batch process information using the BatchProcess resource. This resource contains the following fields:

Field Description Returned By Default?
type The batch process's BatchProcessType. Yes
status An inline object with status information, such as startDate, dateCompleted, opsCompleted, and failedOps. Yes
distributed A Boolean indicating whether the batch process is distributed. Yes
workQueueStatus If the batch process is distributed, this is an inline object containing information on the worker status for the batch process. Only if the batch process is distributed
processId The ID for a newly created process. Only in the response to the /start endpoint, and only if the call to the /start endpoint started the batch process
wasStopped A Boolean indicating whether the batch process was stopped. Only in the response to the /stop endpoint

The information in the response varies based on whether the batch process has completed, is running, or has never been run.

Response for a completed batch process

The following is an example of querying for the Activity Escalation batch process after the batch process has been run. Note that the status object includes the dateCompleted field, and there is no opsExpected field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
    "data": {
        "attributes": {
            "distributed": false,
            "status": {
                "dateCompleted": "2022-09-19T17:30:00.021Z",
                "dateCreated": "2022-09-19T17:30:00.003Z",
                "failedOps": 0,
                "opsCompleted": 0,
                "serverId": "55d109613ac9",
                "startDate": "2022-09-19T17:30:00.011Z",
                "type": "ActivityEsc"
            },
            "type": {
                "code": "ActivityEsc",
                "name": "Activity Escalation"
            }
        },
        ...

Response for a running batch process

The following is an example of querying for the Activity Escalation batch process while the batch process is running. Note that the status object includes the opsExpected field, and there is no dateCompleted field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
    "data": {
        "attributes": {
            "distributed": false,
            "status": {
                "dateCreated": "2022-09-19T17:30:00.003Z",
                "failedOps": 0,
                "opsCompleted": 0,
                "opsExpected": 0,
                "progress": "1 out of 3",
                "serverId": "55d109613ac9",
                "startDate": "2022-09-19T17:30:00.011Z",
                "type": "ActivityEsc"
            },
            "type": {
                "code": "ActivityEsc",
                "name": "Activity Escalation"
            }
        },
        ...

Response for a batch process that has never been run

The following is an example of querying for the Activity Escalation batch process before the first iteration of the batch process. Note that the status object includes only the failureReason field and the type field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
    "data": {
        "attributes": {
            "distributed": false,
            "status": {
                "failureReason": "This batch process type has never run",
                "type": "ActivityEsc"
            },
            "type": {
                "code": "ActivityEsc",
                "name": "Activity Escalation"
            }
        },
        ...