Querying for batch process information

There are several endpoints that provide information about batch processes. They are summarized in the table below.

Endpoint Description
GET /systemtools/v1/batch-processes Return a list of batch process types. In other words, this identifies all of the batch processes that could be run.
GET /systemtools/v1/batch-processes/{batchProcessType} For a given batch process type, return information about the most recent execution of that batch process, if any.
GET /systemtools/v1/batch-processes/{batchProcessType}/histories For a given batch process type, return information about all previous runs of that batch process.
GET /systemtools/v1/batch-processes/{batchProcessType}/histories/{processHistoryId} For a given batch process type, return information about the run of that batch process with the given processHistoryId, which may or may not be the most recent run.

Getting information about the most recent run of a batch process

You can retrieve information about the most recent run of a given batch process. When you do so, 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 about the most recent run, 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 Deprecated. Do not use.
processHistoryId 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 most recent run of 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 most recent run of 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 most recent run of the Activity Escalation batch process, but doing so 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"
            }
        },
        ...