Managing batch processes

You can use Cloud API endpoints to start and stop batch processes.

Starting a batch process

Use the following endpoint to start a batch process:

  • POST /systemtools/v1/batch-processes/{batchProcessType}/start

The POST does not require a request body. However, if the batch process has arguments and Cloud API supports those arguments, you can add an optional request body to specify arguments. For more information, see Starting a batch process with arguments.

The response to the /start endpoint includes the processId field. This value serves two purposes:

  • It verifies that the batch process was started as a result of the call to the /start endpoint. If the batch process could not be started, such as when the process is already running, then this value does not appear in the response.
  • This value may be required by other tools, such as the Guidewire SOAP-based MaintenanceToolsAPI, which needs the process ID to get batch process status or request batch process termination.

A batch process can be categorized as MaintenanceOnly, which means the batch process is not available if the server's run level is above NODAEMONS mode. The /start endpoint is not available for MaintenanceOnly batch processes when the server's run level is above NODAEMONS mode.

Batch processes can also be categorized as APIRunnable. This setting impacts whether the batch process can be run from the Guidewire SOAP-based MaintenanceToolsAPI. It does not impose any limitation on whether Cloud API can start the batch process.

Example of starting a batch process

The following is an example of the response to starting the Activity Escalation batch process.

POST /systemtools/v1/batch-processes/ActivityEsc/start

RESPONSE:
{
    "data": {
        "attributes": {
            "distributed": true,
            "processId": 4055,
            "status": {
                "dateCreated": "2022-09-19T17:54:19.929Z",
                "failedOps": 0,
                "opsCompleted": 0,
                "serverId": "55d109613ac9",
                "type": "ActivityEsc"
            },
            "type": {
                "code": "ActivityEsc",
                "name": "Activity Escalation"
            },
            "workQueueStatus": {
                "numActiveExecutors": 1,
                "numActiveWorkItems": 0
            }
        },
        ...

Starting a batch process with arguments

In PolicyCenter, some batch processes let you specify arguments when you run the batch process. These arguments perform the function of input parameters, and they can change the way the batch process runs.

For example, the Purge Async API Requests batch process removes stale information about API requests that were executed asynchronously. By default, the batch process removes information for asynchronous requests that are more than 7 days old. However, when running this batch process, you can specify a different number of days.

In Cloud API, for some batch processes, the /start endpoint supports arguments. For these batch processes, you can submit a request with no body, which is equivalent to starting the batch process without arguments. Or, you can submit a request with a body that specifies arguments and their values.

Determining which arguments the /start endpoint supports

The root resource for the /start endpoint is BatchProcessArguments. This resource has one JSON object for each base configuration batch process for which arguments are supported. To determine if you can submit arguments for a given batch process, you must check the schema to see if a JSON object exists for that batch process.

For example, the BatchProcessArguments resource has a PurgeAsyncApiRequests object. This means that, when using the /start endpoint to start the Purge Async API Requests batch process, you can submit arguments.

Syntax for the request body

When specifying arguments, the syntax for the request body is as follows:

{
  "data": {
    "attributes": {
      "<batchProcessFieldName>": {
        "<argument1>": <values>,
        "<argument2>": <values>,
        ...
      }
    }
  }
}

For example, the PurgeAsyncApiRequests object has one integer field, purgeDaysOld. The following request starts the Purge Async API Requests batch process and passes in a purgeDaysOld value of 3.

POST /systemtools/v1/batch-processes/PurgeAsyncApiRequests/start

{
  "data": {
    "attributes": {
      "purgeAsyncApiRequests": {
        "purgeDaysOld": 3
      }
    }
  }
}
Note that the structure of the JSON object varies based on the datatype of the arguments. For example, the following is an example of starting the Database Consistency Check batch process with arguments. Note that one of the arguments, tableNames, is an array, whereas the other, description, is a string.
POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
  "data": {
    "attributes": {
      "dbconsistencycheck": {
        "tableNames": [
          "cc_activity",
          "cc_address"
        ],
        "description": "Start of Q1 maintenance"
      }
    }
  }
}

If the attributes section contains any property with an unexpected name, Cloud API returns a 400 error.

Custom batch processes with arguments

Insurers can also create custom batch processes that have arguments. Starting custom batch processes with arguments requires additional configuration. For more information, see the Cloud API Developer Guide.

Stopping a batch process

Use the following endpoint to stop a batch process:

  • POST /systemtools/v1/batch-processes/{batchProcessType}/stop

The POST does not require a request body.

The response to the /stop endpoint includes the wasStopped field. This field is set to true if the batch process was stopped while the batch process was executing. It is set to false if the batch process was not running when the /stop request was made.

For example, the following request stops the Activity Escalation batch process:
POST /systemtools/v1/-batch-processes/ActivityEsc/stop

RESPONSE:
{
    "data": {
        "attributes": {
            "distributed": true,
            "status": {
                "dateCompleted": "2022-09-19T18:00:51.304Z",
                "dateCreated": "2022-09-19T18:00:51.291Z",
                "failedOps": 0,
                "opsCompleted": 0,
                "serverId": "55d109613ac9",
                "startDate": "2022-09-19T18:00:51.298Z",
                "type": "ActivityEsc"
            },
            "type": {
                "code": "ActivityEsc",
                "name": "Activity Escalation"
            },
            "wasStopped": true,
            "workQueueStatus": {
                "numActiveExecutors": 1,
                "numActiveWorkItems": 0
            }
        },